Files
Neutron/.planning/phases/01-reproducible-fidelity-baseline/01-03-PLAN.md
T

115 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
phase: 01-reproducible-fidelity-baseline
plan: "03"
type: execute
wave: 2
depends_on: ["01-01"]
files_modified:
- tools/recon/fidelity_ledger.py
- tests/test_fidelity_ledger.py
- docs/evidence/capabilities.json
- docs/evidence/README.md
autonomous: true
requirements: [EVID-03]
estimate:
tokens: 28000
raw_tokens: 28000
tasks: 2
confidence: low
must_haves:
truths:
- "Reviewers browse movement, contacts, gadgets, progression, visuals and audio with requirement/source/scenario/platform links per D-09."
- "Each capability leads with working behavior, verified scope/platform, known differences and remaining acceptance per D-10."
- "Current applicable evidence precedes expandable explicitly superseded revision history per D-11; applicability uses content/scope/platform rather than newest date."
- "Discrepancies order blocking/disruptive failures before subtler differences and missing verification per D-12; all missing evidence keeps acceptance open."
- "All 33 full-game requirements have capability coverage even when unimplemented; an empty ledger fails and one capability remains renderable."
- "Equal receipt/content identities merge only when the record bytes match; conflicts remain explicit, and duplicate history rows never silently overwrite evidence."
- "Equal-priority entries have deterministic stable ID ordering; explicit supersession cycles and unresolved contradictory current claims fail validation."
artifacts:
- path: docs/evidence/capabilities.json
provides: "Authoritative full-game capability ledger"
- path: tools/recon/fidelity_ledger.py
provides: "Scope-aware validator and deterministic render/export"
- path: docs/evidence/README.md
provides: "Generated capability-first navigation and evidence instructions"
key_links:
- from: docs/evidence/capabilities.json
to: .planning/REQUIREMENTS.md
via: "Complete 33-ID coverage with implementation/evidence/acceptance separation"
- from: tools/recon/fidelity_ledger.py
to: "Generated ledger.json consumed by paired review"
via: "SKELETON.md shared capability contract; no parallel viewer file writes"
prohibitions:
- statement: "MUST NOT erase contradictory history, hide unimplemented required content or turn missing evidence into a fidelity-completion claim."
status: unresolved
reason: "Spec-less recall; project-specific transparency value, descriptor-less and flagged-unverified."
---
<objective>
Make the full reconstruction auditable through one authoritative capability ledger per D-09–D-12, retaining all evidence boundaries and exact current applicability.
Artifacts this phase produces in this plan: capabilities.json schema-versioned records; fidelity_ledger.py validate/render/export CLI and select_current_evidence function; generated docs/evidence/README.md navigation; tests/test_fidelity_ledger.py. Exported ledger.json stays below artifacts/fidelity/review. No parallel edits to viewer or root status files.
</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/REQUIREMENTS.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
</context>
<tasks>
<task type="tracer" tdd="true" id="01-03-01">
<name>Trace one real capability from source report to current receipt and review navigation</name>
<reversibility rating="costly">The ledger is a shared evidence interface; version it and generate all presentation from its retained records.</reversibility>
<files>tools/recon/fidelity_ledger.py, tests/test_fidelity_ledger.py, docs/evidence/capabilities.json, docs/evidence/README.md</files>
<read_first>docs/checkpoint/coverage.md; docs/compatibility.md; docs/gameplay/main-menu-player-lifetime.md; docs/gameplay/jimmy-movement-stabilization.md; .planning/REQUIREMENTS.md; SKELETON.md capability contract; 01-RESEARCH.md Pattern 4.</read_first>
<behavior>At least 12 tests cover one real capability render/export round trip, empty/single ledger, duplicate/conflicting IDs/history, equal-priority ordering, supersession cycles, nonexistent/unsafe links, docs-only revisions, changed package/resources, mismatched platform/scope and missing evidence remaining open.</behavior>
<action>Create tests first. Implement one fully populated capability for the already corrected TSK-backed first-story input order using current authoritative reports, preserving direct-fresh distinction and legitimate landing bank. Link source evidence, implementation revision and exact bounded runtime receipt/report, with missing local artifacts explicitly recorded. Lead with what works, where verified, differences and acceptance per D-10. Define records with stable capability ID, group, requirement IDs, behavior/scenes, source links/addresses when present, implementation source revision, evidence records with method/platform/content/scope and artifact identities, current applicability, discrepancies and acceptance. Current receipt selection must use exact content identity and scope; a newer docs commit does not supersede unchanged runtime bytes, while changed runtime/resources require explicit applicability review. Keep prior statements in history with revision, supersedes ID/reason and current/superseded status per D-11. Produce readable Markdown and JSON review navigation from the same data. The actual capability round trip must show its remaining original/native Windows acceptance; a report link is not a newly executed run. Require finite bounded data and safe repository/local artifact references. Validate conflicting duplicate records and deterministic ordering before rendering, with stable IDs as tie-breakers.</action>
<acceptance_criteria>A reviewer can follow one real capability through source, implementation, bounded platform proof, prior narrative and remaining acceptance; generated navigation agrees with the authoritative JSON; tamper/empty/history failures are test-covered.</acceptance_criteria>
<verify>
<automated>python3 -c 'import sys,unittest; s=unittest.defaultTestLoader.discover("tests",pattern="test_fidelity_ledger.py"); assert s.countTestCases() >= 12,"fewer than 12 ledger tests"; sys.exit(not unittest.TextTestRunner(verbosity=2).run(s).wasSuccessful())'</automated>
<fails_when>Nonzero exit, fewer than 12 tests, missing round-trip result, or any stale/empty/conflicting/history negative case passes.</fails_when>
</verify>
<done>One real capability is auditable through generated navigation with truthful current applicability and visible open acceptance.</done>
</task>
<task type="auto" tdd="true" id="01-03-02">
<name>Account for the complete game and rank actionable discrepancies</name>
<files>docs/evidence/capabilities.json, docs/evidence/README.md, tools/recon/fidelity_ledger.py, tests/test_fidelity_ledger.py</files>
<read_first>docs/progress.md; docs/tasks.md; docs/decisions.md; docs/checkpoint/implementation-plan.md; docs/checkpoint/next-work-plan.md; .planning/REQUIREMENTS.md; all source reports linked by the capability rows being reconciled, read only as needed.</read_first>
<behavior>Extend to at least 16 tests, requiring all 33 requirement IDs and all six locked capability groups; test unimplemented rows, receipt/scenario links, current/history separation, missing-proof open status and impact order blocking→disruptive→subtle→missing-verification with stable ties.</behavior>
<action>Populate every full-game requirement category per D-09 using existing recovery and implementation reports, including unimplemented/unverified work. Preserve all existing checkpoint coverage rows by a corresponding detail row or explicit linked source; record reconciliation so no historical source row disappears silently. Include movement, contacts/helpers, gadgets/vehicles, actors/hazards, authored progression/content, menus/persistence, visuals/cameras, audio and native delivery. Map all 33 requirement IDs without claiming they are implemented. For each row lead with D-10 fields and link the relevant scenarios/source/platform proof; retain exact historical package revisions and limited Wine/component/cross-publish classifications. Rank player-impact discrepancies per D-12 with deterministic ties, but keep verification gaps in acceptance even when displayed later. Export grouping, current summary, expandable history data and scenario links using the shared contract so the viewer can consume it without editing its files. validate must fail on unmapped requirements, missing critical fields, dead source links, contradictory current claims and invalid receipt classifications. Record explicitly missing generated artifacts as known gaps instead of dropping their entries. Generate README.md rather than maintaining a second independent status table.</action>
<acceptance_criteria>All 33 requirement IDs and existing checkpoint coverage entries are accounted for; current and superseded evidence retain exact revisions; missing evidence is visible and open; deterministic discrepancy sorting matches D-12.</acceptance_criteria>
<verify>
<automated>python3 -c 'import sys,unittest; s=unittest.defaultTestLoader.discover("tests",pattern="test_fidelity_ledger.py"); assert s.countTestCases() >= 16,"fewer than 16 ledger tests"; sys.exit(not unittest.TextTestRunner(verbosity=2).run(s).wasSuccessful())'</automated>
<fails_when>Nonzero exit, fewer than 16 tests, or any requirement-coverage/impact/applicability assertion fails.</fails_when>
<automated>python3 tools/recon/fidelity_ledger.py validate --ledger docs/evidence/capabilities.json --requirements .planning/REQUIREMENTS.md</automated>
<fails_when>Nonzero exit or missing summary requirements=33 unmapped=0; any contradictory current record or unresolved broken source link.</fails_when>
</verify>
<done>The full game is traceable in one authoritative capability ledger, and its navigation never conflates implementation, recovered source, bounded execution and remaining acceptance.</done>
</task>
</tasks>
<threat_model>
ASVS level 1; unresolved high/critical threats block acceptance.
| Boundary | Description |
|---|---|
| Historical reports → current capability claims | Report scope and actual identity must survive reconciliation |
| Ledger references → generated navigation | Untrusted labels/paths are emitted as readable local data |
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|---|---|---|---|---|---|
| T-01-07 | Spoofing | select_current_evidence | high | mitigate | Exact content/platform/scope checks; explicit supersession; contradictory current evidence blocks validation |
| T-01-08 | Repudiation | Evidence/history import | medium | mitigate | Stable record IDs, duplicate conflict rejection, source-row reconciliation and deterministic history ordering |
| T-01-09 | Tampering | Ledger render/export | medium | mitigate | Escaped text and validated local/repository links; no executable imported commands |
| T-01-SC | Tampering | Package installation | high | mitigate | Stdlib-only ledger tools; no new package installation |
</threat_model>
<verification>Run counted ledger tests and full 33-ID validation. Inspect generated capability summary/history against the authoritative TSK and current platform reports. No native execution is claimed by ledger completion.</verification>
<success_criteria>Full-game proof and remaining acceptance can be reviewed by capability, with current applicability and discrepancies preserved.</success_criteria>
<output>Create .planning/phases/01-reproducible-fidelity-baseline/01-03-SUMMARY.md with reconciliation counts, authoritative model and open evidence.</output>