docs(01): create verified fidelity baseline plans

This commit is contained in:
UnixNight committed 2026-11-12 17:38:34 -05:00
1 parent 36f24e4474
commit cf64b8ce18
21 files changed
+1473 -32

No files matched your search

@@ -0,0 +1,113 @@
---
phase: 01-reproducible-fidelity-baseline
plan: "05"
type: execute
wave: 3
depends_on: ["01-02", "01-03", "01-04"]
files_modified:
- tools/recon/fidelity_checkpoint.py
- scripts/prepare-fidelity-checkpoint.sh
- scripts/collect-fidelity-windows.ps1
- scripts/collect-fidelity-windows.cmd
- tests/test_fidelity_checkpoint.py
- tests/fidelity-windows.Tests.ps1
- docs/evidence/windows-session.md
autonomous: true
requirements: [EVID-01, EVID-02, EVID-04]
estimate:
tokens: 34000
raw_tokens: 34000
tasks: 2
confidence: low
must_haves:
truths:
- "One complete local checkpoint bundle contains identified port packages, a verified generated original copy, scenarios, viewer and result collection per D-14."
- "The available Windows PC is treated as a pending execution environment per D-13; actual OS/GPU/driver/tool identities are collected during the session."
- "The original launches only from a generated copy through the user's identified DxWnd binary/exported profile, separately from native port receipts, per D-15."
- "All original-reference and port materials are prepared before one combined session per D-16; preparation does not close EVID-02 or EVID-04."
- "Launcher preflight or recording failure produces an actionable local failure receipt without inventing successful capture or downloading dependencies."
artifacts:
- path: tools/recon/fidelity_checkpoint.py
provides: "Offline checkpoint manifest/preflight and bundle assembly"
- path: scripts/collect-fidelity-windows.ps1
provides: "Native Windows local preflight/launch/collection"
- path: docs/evidence/windows-session.md
provides: "Single combined-session instructions and local result transfer"
key_links:
- from: scripts/prepare-fidelity-checkpoint.sh
to: tools/recon/fidelity_checkpoint.py
via: "Consumes completed package bytes and validated scenario/ledger/viewer artifacts"
- from: scripts/collect-fidelity-windows.ps1
to: tools/recon/fidelity_receipts.py
via: "Same schema-versioned per-run receipt contract and byte identities"
---
<objective>
Prepare the complete local Windows original-DxWnd/native-port checkpoint per D-13–D-16, without asking the user to execute partial materials.
Artifacts this phase produces: fidelity_checkpoint.py prepare/preflight CLI; scripts/prepare-fidelity-checkpoint.sh; scripts/collect-fidelity-windows.ps1 and .cmd; tests/test_fidelity_checkpoint.py; tests/fidelity-windows.Tests.ps1; windows-session.md. The generated dist/fidelity/phase01 checkpoint contains manifest.json, READY.json, original-pristine/, original-runs/, port/win-x64/, port/linux-x64/, review/, protocol/, results/ and local launchers. READY means materials prepared, never acceptance passed. No media/packages are committed or uploaded.
</objective>
<execution_context>
@/home/cristian/.codex/gsd-core/workflows/execute-plan.md
@/home/cristian/.codex/gsd-core/templates/summary.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/phases/01-reproducible-fidelity-baseline/01-CONTEXT.md
@.planning/phases/01-reproducible-fidelity-baseline/01-RESEARCH.md
@.planning/phases/01-reproducible-fidelity-baseline/SKELETON.md
@.planning/phases/01-reproducible-fidelity-baseline/01-01-SUMMARY.md
@.planning/phases/01-reproducible-fidelity-baseline/01-02-SUMMARY.md
@.planning/phases/01-reproducible-fidelity-baseline/01-03-SUMMARY.md
@.planning/phases/01-reproducible-fidelity-baseline/01-04-SUMMARY.md
</context>
<tasks>
<task type="tracer" tdd="true" id="01-05-01">
<name>Prepare one runnable checkpoint case through package identity, launch plan and collected result</name>
<files>tools/recon/fidelity_checkpoint.py, scripts/prepare-fidelity-checkpoint.sh, scripts/collect-fidelity-windows.ps1, scripts/collect-fidelity-windows.cmd, tests/test_fidelity_checkpoint.py</files>
<read_first>scripts/package.sh; scripts/build-linux.sh; scripts/build-windows.sh; tools/recon/fidelity_receipts.py; tools/recon/fidelity_review.py; docs/evidence/scenarios.json; 01-RESEARCH.md Minimum Viable Windows Recording and Bundle.</read_first>
<behavior>At least 12 Python tests prepare→preflight→fixture-result-import one checkpoint case, compare actual package/resource and original hashes, reject output overlap/reuse, stale/missing binary/resources, tampered launcher/media, interrupted/concurrent assembly and missing dependencies. Fixture collection cannot qualify as native Windows.</behavior>
<action>Create failing tests first. Assemble a complete offline tree consuming actual finished package bytes and their BUILD-INFO rather than stamping the current docs revision onto old DLLs. Use scripts/package.sh locally if new observer packages are needed; retain its original identity fields and add a separate canonical manifest excluding its own output to avoid self-hashing. Record actual runtime source/dirty/diff identity, executable/resource/package tree hashes, original manifest hash and launcher/viewer hashes. Verify originals before copying; retain a pristine generated original seed and make a fresh writable original-runs copy per fresh case, preserving retained case state explicitly. Launchers are script-relative and quoted; no shell/eval or commands supplied by receipts. Implement one complete case path: preflight byte identities and dependencies, select actual tool/profile, start original-DxWnd or native port as separate explicit modes, collect invocation/exit/log/artifact metadata and publish a truthful receipt/failure. Do not assume DxWnd command switches/profile correctness: inspect the selected local distribution's help/config inside the final session, retain original exported profile plus any relocation-only edits, and provide transparent manual launch if automation is unsupported. Windows requires neither Python nor SDK for the self-contained port/PowerShell collector. Retain launcher/profile hashes, Windows/GPU/driver/SDL/Vulkan evidence as actually available. Hash incrementally and bound file counts, sizes and process waits. Bundle test round trips use deliberately synthetic executables/media and are labeled tooling-only. Original/native launch remains an actual final-session check.</action>
<acceptance_criteria>One checkpoint fixture travels through preparation, preflight and schema-valid import; an actual offline package tree can be assembled without original writes or external services; failures identify exact missing/tampered dependencies; Windows runtime remains pending.</acceptance_criteria>
<verify>
<automated>python3 -c 'import sys,unittest; s=unittest.defaultTestLoader.discover("tests",pattern="test_fidelity_checkpoint.py"); assert s.countTestCases() >= 12,"fewer than 12 checkpoint tests"; sys.exit(not unittest.TextTestRunner(verbosity=2).run(s).wasSuccessful())'</automated>
<fails_when>Nonzero exit, fewer than 12 tests, missing end-to-end bundle import, or tampered/partial/tooling-only evidence incorrectly passes.</fails_when>
<automated>bash -n scripts/prepare-fidelity-checkpoint.sh</automated>
<fails_when>Nonzero exit or shell syntax diagnostic.</fails_when>
</verify>
<done>One production checkpoint path exists from completed local package to identity-bound result, with Windows execution explicitly pending.</done>
</task>
<task type="auto" tdd="true" id="01-05-02">
<name>Complete all session materials and collect audiovisual results without fragmented requests</name>
<files>scripts/collect-fidelity-windows.ps1, scripts/collect-fidelity-windows.cmd, tests/fidelity-windows.Tests.ps1, docs/evidence/windows-session.md, tests/test_fidelity_checkpoint.py</files>
<read_first>01-CONTEXT.md D-01–D-04 and D-13–D-16; docs/evidence/scenarios.json; receipt schema; 01-RESEARCH.md assumptions A1/A2 and Windows sequence.</read_first>
<behavior>Extend checkpoint tests to at least 16 checks for all matrix/materials, explicit original/native categories, abort/skip receipts and bundle readiness distinct from acceptance. Create package-free PowerShell tests with at least eight checks for identity/path/argument/exit/result functions; Windows execution is deferred to the same final session.</behavior>
<action>Finish launcher/checklist for all eight matrix cells, continuous/focused obligations, native port and original-DxWnd modes. Put one ordered combined agenda in windows-session.md: local dependency selection; versions/hashes/config capture; short original and port visual/audio preflights; all required runs; paired browser/audio review; result collection/postflight; one local return transfer. Initial OBS recommendation is offline Display Capture, with actual selected tool/version/source/settings recorded. Retain raw MKV plus any verified browser preview, exact derivation command/tool/version/timestamp/crop/aspect metadata; never discard the raw recording. A preview codec is accepted only after real browser playback. Require visible moving game content, intelligible game audio and correct crop in human preflight, not merely ffprobe streams. Original markers describe actual visible input/event intervals and uncertainty; port traces use observer data. Collect missed/skipped/aborted cases and wrapper rendering/timing limitations, distinguish diagnostic runs, and preserve generated original post-run changes. Keep DxWnd provenance distinct from native Windows port receipts per D-15. No guessed profile, forced timer/render setting, tool download or redistributed third-party installer. PowerShell tests run without Pester/package installs using temporary fixtures and explicit positive check count. Include their exact command in the session agenda; absence of pwsh here remains pending rather than pretending syntax tests ran. Local transfer instructions use USB/local filesystem or existing local shares, with hashes rechecked on return. Do not request capture yet.</action>
<acceptance_criteria>Every required case/tool/material appears in the one agenda; synthetic tests prove completeness/classification; package-free Windows selftests are ready; no capture request occurs before final readiness.</acceptance_criteria>
<verify>
<automated>python3 -c 'import sys,unittest; s=unittest.defaultTestLoader.discover("tests",pattern="test_fidelity_checkpoint.py"); assert s.countTestCases() >= 16,"fewer than 16 checkpoint tests"; sys.exit(not unittest.TextTestRunner(verbosity=2).run(s).wasSuccessful())'</automated>
<fails_when>Nonzero exit, fewer than 16 tests, or missing agenda/required-cell/abort/classification checks.</fails_when>
<human-check>At the final combined session run powershell.exe -NoProfile -File .\tests\fidelity-windows.Tests.ps1 from the prepared checkpoint, requiring eight or more passing checks and zero failures; then perform the actual original/native recording agenda. Missing tools/settings remain explicit failure receipts.</human-check>
</verify>
<done>A complete local checkpoint and one combined session agenda cover original-reference and native Windows capture, including honest failure/abort results.</done>
</task>
</tasks>
<threat_model>
ASVS level 1; unresolved high/critical threats block acceptance. No new package installs.
| Boundary | Description |
|---|---|
| Selected tools/profile → process launch | Only explicitly selected local executables run with transparent arguments |
| Checkpoint package → user results | Byte identity and classification must survive local transfer |
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|---|---|---|---|---|---|
| T-01-13 | Elevation of privilege | PowerShell launcher | high | mitigate | No elevation/download/eval; allow explicit local selection, argument-safe invocation and no receipt-supplied commands |
| T-01-14 | Tampering | Bundle/transfer | high | mitigate | Canonical hashes, preflight/postflight, atomic fresh assembly and tampered artifact rejection |
| T-01-15 | Spoofing | Original/native receipts | high | mitigate | Separate methods/profile provenance, explicit abort/limitations and no acceptance from launch or metadata alone |
| T-01-SC | Tampering | Package installation | high | mitigate | No ecosystem additions or third-party redistribution; actual external executable provenance recorded locally |
</threat_model>
<verification>Run counted bundle tests and shell syntax check. Checkpoint READY describes materials only. Actual Windows PowerShell/original/DxWnd/native port and browser checks occur once in plan 01-07.</verification>
<success_criteria>Everything needed for the single Windows hands-on session is complete and locally transferable before the user is asked to run it.</success_criteria>
<output>Create .planning/phases/01-reproducible-fidelity-baseline/01-05-SUMMARY.md with checkpoint membership, actual package identities and pending Windows checks.</output>