docs(01-03): complete capability ledger plan

This commit is contained in:
UnixNight committed 2026-11-12 22:59:25 -05:00
1 parent 4d07d60e2f
commit 564b19ad03
1 file changed
+163
@@ -0,0 +1,163 @@
---
phase: 01-reproducible-fidelity-baseline
plan: "03"
subsystem: testing
tags: [python, capability-ledger, fidelity, sha256, reconciliation]
requires:
- phase: 01-01
provides: Version 1 receipts and eight-cell scenario protocol
- phase: 01-02
provides: Actual contained viewer export and source-link normalization
provides:
- Authoritative 25-capability ledger covering all 33 full-game requirements
- Exact reconciliation of 16 checkpoint systems, 11 owners and six assumptions
- Scope/content/platform selection, preserved supersession and generated navigation
affects: [01-04, 01-05, 01-06, 01-07, movement, delivery]
tech-stack:
added: []
patterns: [stdlib-only validation, hashed source rows, explicit documentary scope, generated Markdown and JSON]
key-files:
created:
- tools/recon/fidelity_ledger.py
- tests/test_fidelity_ledger.py
- docs/evidence/capabilities.json
- docs/evidence/README.md
modified: []
key-decisions:
- "Full-game coverage includes bounded, unimplemented and tooling work; coverage and report validity never promote native/reference acceptance."
- "Checkpoint reconciliation hashes every system/ownership row and numbered assumption and requires a retained source link from each mapped capability."
- "Current evidence means exact named content/platform/scope applicability; documentation dates and newer source HEAD never substitute for runtime bytes."
patterns-established:
- "One authoritative JSON model generates Markdown and viewer export; equal receipt IDs merge only byte-identical records across the entire ledger."
- "Imported receipt references bind actual receipt digest, category, platform, scope and historical flag; legacy report records remain separately described."
requirements-completed: [EVID-03]
requirements-acceptance: "OPEN: assigned ledger contribution only. EVID-03 remains Pending because other declaring plans and runtime acceptance are unfinished. All 120 actual original/native obligations remain open."
coverage:
- id: capability-accounting
description: All 33 requirements, six groups and 33 checkpoint source rows are explicitly accounted for
requirement: EVID-03
verification:
- kind: integration
ref: tests/test_fidelity_ledger.py
status: pass
- kind: other
ref: python3 tools/recon/fidelity_ledger.py validate --ledger docs/evidence/capabilities.json --requirements .planning/REQUIREMENTS.md
status: pass
human_judgment: false
- id: review-roundtrip
description: Actual ledger CLI and viewer export preserve all capability/current/history/scenario/acceptance data and copied source links
requirement: EVID-03
verification:
- kind: integration
ref: tests/test_fidelity_ledger.py#test_real_startup_capability_cli_and_viewer_roundtrip
status: pass
human_judgment: false
- id: actual-reference-acceptance
description: Identified whole-original and current native Linux/Windows gameplay and audiovisual comparison
verification: []
human_judgment: true
rationale: "Existing reports and bounded historical fixtures are not the required original-DxWnd/native scenario recordings or human review; actual matrix acceptance remains 0/120."
actuals:
tokens: 78646
tasks: 2
commits: 5
basis: "ceil(chars/4) over the realized four-file production/test/model/navigation diff (314583 chars), excluding planning metadata. Commit count is the actual persisted-ledger range, including the intervening pause handoff commit."
plan_head_before: be18d77ca42b1896540ff21122bbc1e684195dc1
plan_head_after: 4d07d60e2fdbfdb065aaa2e7e780055620984521
duration: 22 min
started: 2026-11-13T00:48:50Z
completed: 2026-11-13
status: complete
---
# Phase 01 Plan 03: Full-Game Capability Ledger Summary
**A generated 25-capability ledger maps all 33 requirements, reconciles 33 hashed checkpoint entries and preserves exact startup-order evidence with open native/reference acceptance.**
## Performance
- Two tasks; four created files. Approximate active execution windows total 22 minutes: prior-plan close at 00:48:50 through pause handoff at 01:02:30, then resumed state at 03:49:05 through verification/commit at 03:57:36 UTC. Approximately 189 wall minutes include the explicitly requested usage pause.
- Persisted base-to-production-HEAD range contains five commits: four task RED/GREEN commits and one pause handoff. Evaluation-scope independently resolves the four task commits on this branch.
- Final ledger suite: 31 tests, 0.980 seconds; all fidelity Python suites: 103 tests, 7.149 seconds (7.229 seconds including process overhead); Node: 27 named tests, 82.360 milliseconds. Original inventory: 539 unchanged files.
## Accomplishments
- The authoritative model accounts for movement, contacts/helpers, actors/hazards, gadgets/vehicles/inventory, authored content/progression, frontend/configuration/persistence, visuals/cameras, audio and native delivery. Its six locked navigation groups contain 25 capabilities: 21 bounded, three explicitly unimplemented full-scope workflows and one tooling capability. Coverage is 33 requirements, zero unmapped.
- Reconciliation retains all 16 system rows, 11 ownership rows and six numbered assumptions from `docs/checkpoint/coverage.md`. Each has exact source-row SHA-256, retained source path and mapped capability IDs. Missing, changed, duplicate or extra source rows and absent retained source links fail validation. Baseline wording remains in its source; continuation summaries explicitly refine it.
- The real startup row retains already-corrected TSK story-entry order, separate fresh direct-scene order, valid landing bank, actual source addresses/REA identifier and exact historical ea04210 Linux/Wine classifications. Prior incorrect fresh-story inference stays explicitly superseded with its successor and reason. Report validity is distinct from runtime applicability.
- Markdown and JSON exports come from the same model. A real subprocess ledger export feeds the existing `fidelity_review.export_review` without viewer edits. All 25 rows preserve their current/history/scenario/acceptance/discrepancy fields; all 153 source-link entries resolve to validated copied text files. Current evidence precedes history; discrepancies sort blocking, disruptive, subtle, missing_verification, then stable ID.
- Validation rejects empty/unmapped ledgers, conflicting duplicate capabilities/receipts/history, cycles, unresolved contradictory current claims, unsafe/dead/tampered sources, nonfinite/unbounded data, unknown scenarios, invalid categories and stale artifact hashes. Actual imported receipts are revalidated and bound to their digest/platform/scope/history instead of accepting a relabeled reference.
## Task Commits
1. Task 01-03-01 RED: `ded848f` — specify capability applicability and review navigation.
2. Task 01-03-01 GREEN: `e6713ea` — trace corrected TSK order through capability evidence.
3. Task 01-03-02 RED: `c21ed7d` — require complete game and checkpoint source coverage.
4. Task 01-03-02 GREEN: `4d07d60` — reconcile full-game capability and checkpoint coverage.
Intervening `fafbd05` is the primary's pause handoff, not another task implementation. Normal hooks ran with explicit scoped staging. No tracked production files were deleted. Main commits use the user-authorized configuration; the primary owns integration and push.
## Files and Interfaces
- `docs/evidence/capabilities.json`: schema_version 1 authoritative facts; 25 capabilities, 28 typed documentary/historical evidence records, 33 reconciliation entries, explicit evidence policy. Unimplemented workflows are honest coverage rows, not implementation stubs.
- `tools/recon/fidelity_ledger.py`: `validate_ledger(data, project, requirements=None)`, `export_ledger(...)`, `render_markdown(...)`, `select_current_evidence(records, target)` and `checkpoint_rows(path)`. Invalid input raises `ValueError`; CLI failures exit 2. Full reconciled CLI models automatically use `.planning/REQUIREMENTS.md` if the optional flag is omitted; singleton API fixtures remain renderable.
- `tests/test_fidelity_ledger.py`: 31 behavior/integration regressions, including actual imported synthetic receipts and the genuine historical startup evidence/viewer round trip.
- `docs/evidence/README.md`: generated capability-first navigation, exact current targets, expandable history, remaining acceptance and source reconciliation. It is not independently maintained status.
```sh
python3 tools/recon/fidelity_ledger.py validate --ledger docs/evidence/capabilities.json --requirements .planning/REQUIREMENTS.md
python3 tools/recon/fidelity_ledger.py render --ledger docs/evidence/capabilities.json --output docs/evidence/README.md
python3 tools/recon/fidelity_ledger.py export --ledger docs/evidence/capabilities.json --output artifacts/fidelity/review/ledger.json
python3 tools/recon/fidelity_review.py export --ledger artifacts/fidelity/review/ledger.json --output artifacts/fidelity/review/new-review
```
Viewer input uses the established capability contract and source links `{label,path,sha256?}`. It adds contained copied `href/validated_local/sha256/size/missing` fields. Ledger source text is contained, tracked, UTF-8/non-NUL and at most 1 MiB per file. Optional source hashes and actual artifact identities are checked. Generated output stays local under the project or `/tmp`, rejects symlinks, and cannot overwrite originals/Git metadata or the authoritative input. No new package dependency, service, runtime endpoint or original-binary investigation was introduced.
## Evidence and Acceptance Limits
The expansion's current evidence records are explicitly **static documentary coverage**, bound to retained report content and named documentary scopes. They do not manufacture fresh component or native receipts. Implementation revisions identify recorded code changes separately from runtime/package identity. Existing copied-original/managed/Linux scene results are described with their narrower scope. Historical package revisions remain exact: current packaged924ad2f versus earlier ea04210 Wine64 and later integrated bf876e9 source checks are not conflated. Scooter/Rocketship milestones and current bounded scene limitations remain visible.
No new game, GPU, DxWnd, Wine or Windows execution, build or package was performed. Native Linux/Windows/original reference captures and human audiovisual review remain open at **0/120 actual obligations**. Shared EVID-03 is not checked complete in REQUIREMENTS.md. The preserved TSK correction is implemented, not an untouched defect; no leveling reset, movement replacement, new gadget, actor admission or lab/outside solver replacement was made. Missing generated original/native recordings retain explicit reasons in the startup evidence rather than being dropped.
## TDD Gate Compliance
- Task 1 RED evidence: `artifacts/fidelity/tdd/01-03-01-red.json`, recorded before implementation; the real CLI-presence/round-trip target failed its intended planned behavior assertion. Existing RED/GREEN commits and the previously verified 18-test tracer were reconciled rather than repeated.
- Task 2 RED evidence: `artifacts/fidelity/tdd/01-03-02-red.json`; the named full-game set-equality target ran and failed because only two movement requirements were mapped. The actual 26-test report retains the three expected missing coverage/reconciliation/unimplemented assertions. The classifier was re-run on resume and returned `RED_EVIDENCE_OK`; semantic inspection confirms intended assertions, not setup/import failures. Final suite passes all 31 tests.
- Each RED commit precedes its GREEN by ancestry. No separate refactor was necessary. Both exact counted plan commands and full 33-ID validation pass; singleton/negative cases remain covered. No skipped tests or unrun planned automated checks remain.
## Decisions Made
One JSON source owns all navigation. Current evidence selects exact content/platform/scope, including explicitly named historical bytes; latest documentation dates do not imply newer execution. Full-game rows and source-row reconciliation expose unfinished work without expanding gameplay. Future imported receipt references require exact receipt SHA-256 plus matching platform/scope/category/history.
## Deviations from Plan
No architecture or scope change. During planned validation, report-content hash binding, ledger-wide receipt duplicate checks, complete category validation and actual imported-receipt identity matching were completed as correctness controls for T-01-07/08. These are within the planned evidence-validation boundary and commit `4d07d60`.
## Threat/Test Coverage
| Threat | Implemented controls and verification |
|---|---|
| T-01-07 | Exact named content/platform/scope targets, explicit supersession/cycles and contradictory-current rejection; changed runtime/resource/package, docs-only and imported receipt tests |
| T-01-08 | Byte-identical duplicate merging, global receipt conflicts, stable ordering and 33 hashed source-row reconciliation entries; retained linked source required |
| T-01-09 | Escaped Markdown, bounded contained tracked UTF-8 source references, actual hashes, no imported command execution; hostile source and real viewer-copy tests |
| T-01-SC | Python standard library only; no package installation |
No additional threat surface beyond the plan's existing local file/navigation boundary was introduced. Cooperative local filesystem assumptions remain; revalidate/re-export after evidence changes.
## Issues Encountered
The user-requested pause interrupted task 2 after its RED commit and 41-line patch. Resume preserved those changes, validated ancestry/evidence and completed GREEN. Primary-owned HANDOFF deletion/STATE/continuation edits and untracked `tools.yaml` were preserved. Socket/Node checks used authorized local-test escalation to avoid the known sandbox false failures/file-only results. All-fidelity log: ignored `artifacts/fidelity/verification/01-03-all-python.log`.
No implementation stubs remain. Missing real recordings and unimplemented full-game workflows are intentional transparent evidence/coverage states whose later owning plans/phases remain open.
## User Setup Required
None for these local tooling checks. The combined Windows/original/native capture and human audiovisual session belongs to later plans; no premature hands-on request was created.
## Next Phase Readiness
Plans 01-04 through 01-07 can consume the coordinated ledger and provide real observer/checkpoint/capture receipts. The primary owns root continuity documents, consumed handoff cleanup, wave regression checks and push. Full-game and phase acceptance remain separate from this completed ledger implementation.
## Self-Check: PASSED
All four created files exist; all four task commits are ancestors of HEAD and evaluation-scope resolves them on this branch. Both exact counted plan checks, full 33-requirement/six-group/33-row validation, real CLI/viewer round trip, 103 fidelity Python tests, 27 named Node tests, whitespace checks and 539 original hashes pass. No tracked production deletions, skipped tests, placeholder implementation or unexplained generated untracked output was introduced.