From 5915128570fd044384e328396fcc69043b3fcc55 Mon Sep 17 00:00:00 2001 From: Cristian Cerroni Date: Fri, 13 Nov 2026 16:58:55 -0500 Subject: [PATCH] docs(01): record final code review findings and disposition --- .../01-REVIEW-DISPOSITION.md | 39 +++++ .../01-REVIEW.md | 137 ++++++++++++++++++ 2 files changed, 176 insertions(+) create mode 100644 .planning/phases/01-reproducible-fidelity-baseline/01-REVIEW-DISPOSITION.md create mode 100644 .planning/phases/01-reproducible-fidelity-baseline/01-REVIEW.md diff --git a/.planning/phases/01-reproducible-fidelity-baseline/01-REVIEW-DISPOSITION.md b/.planning/phases/01-reproducible-fidelity-baseline/01-REVIEW-DISPOSITION.md new file mode 100644 index 0000000..a69bb41 --- /dev/null +++ b/.planning/phases/01-reproducible-fidelity-baseline/01-REVIEW-DISPOSITION.md @@ -0,0 +1,39 @@ +--- +phase: 01 +review: 01-REVIEW.md +titles: json +findings: + - id: CR-01 + severity: critical + disposition: open + title: "Human review is checked against a different file from the selected receipt" + - id: CR-02 + severity: critical + disposition: open + title: "Original applicability never binds the executed executable or preservation inventories" + - id: CR-03 + severity: critical + disposition: open + title: "Fresh-copy continuity accepts a hash that identifies no artifact" + - id: WR-01 + severity: warning + disposition: open + title: "Checkpoint assembly bypasses the capability ledger projection" + - id: WR-02 + severity: warning + disposition: open + title: "An interrupted Windows collector cannot be finalized through the documented recovery command" +open: 5 +total: 5 +recorded: 2026-11-13T21:58:50.502559+00:00 +--- + +# Phase 01: Code Review Disposition + +| Finding | Severity | Disposition | Source | +|---|---|---|---| +| CR-01 | critical | open | Reproduced; fix in progress | +| CR-02 | critical | open | Reproduced; fix in progress | +| CR-03 | critical | open | Reproduced; fix in progress | +| WR-01 | warning | open | Reproduced; fix in progress | +| WR-02 | warning | open | Reproduced; fix in progress | diff --git a/.planning/phases/01-reproducible-fidelity-baseline/01-REVIEW.md b/.planning/phases/01-reproducible-fidelity-baseline/01-REVIEW.md new file mode 100644 index 0000000..e072381 --- /dev/null +++ b/.planning/phases/01-reproducible-fidelity-baseline/01-REVIEW.md @@ -0,0 +1,137 @@ +--- +phase: 01-reproducible-fidelity-baseline +reviewed: 2026-11-13T21:56:48Z +depth: standard +files_reviewed: 44 +files_reviewed_list: + - .codex/hooks.json + - docs/codex-quota-guard.md + - docs/compatibility.md + - docs/decisions.md + - docs/evidence/README.md + - docs/evidence/capabilities.json + - docs/evidence/checkpoint-session.md + - docs/evidence/linux-session.md + - docs/evidence/phase01-baseline.md + - docs/evidence/scenarios.json + - docs/evidence/windows-session.md + - docs/progress.md + - docs/tasks.md + - scripts/collect-fidelity-linux.sh + - scripts/collect-fidelity-windows.cmd + - scripts/collect-fidelity-windows.ps1 + - scripts/prepare-fidelity-checkpoint.sh + - scripts/test.sh + - src/GamePort/Application/FidelityObservation.cs + - src/GamePort/Program.cs + - tests/GamePort.FidelityObservationTests/GamePort.FidelityObservationTests.csproj + - tests/GamePort.FidelityObservationTests/Program.cs + - tests/fidelity-viewer.test.mjs + - tests/fidelity-windows.Tests.ps1 + - tests/test_codex_quota_guard.py + - tests/test_fidelity_acceptance.py + - tests/test_fidelity_capture.py + - tests/test_fidelity_checkpoint.py + - tests/test_fidelity_ledger.py + - tests/test_fidelity_observation.py + - tests/test_fidelity_review.py + - tests/test_fidelity_scenarios.py + - tests/test_fidelity_sessions.py + - tools/recon/fidelity.py + - tools/recon/fidelity_acceptance.py + - tools/recon/fidelity_capture.py + - tools/recon/fidelity_checkpoint.py + - tools/recon/fidelity_ledger.py + - tools/recon/fidelity_receipts.py + - tools/recon/fidelity_review.py + - tools/recon/fidelity_viewer/index.html + - tools/recon/fidelity_viewer/style.css + - tools/recon/fidelity_viewer/viewer.mjs + - tools/workflow/codex_quota_guard.py +findings: + critical: 3 + warning: 2 + info: 0 + total: 5 + necessity: 0 +status: issues_found +--- + +# Phase 01: Code Review Report + +**Reviewed:** 2026-11-13T21:56:48Z +**Depth:** standard +**Files Reviewed:** 44 +**Status:** issues_found + +## Summary + +Three acceptance-integrity defects permit mismatched reviewed bytes, unrelated original executable bytes, or an unbound fresh-copy identity to contribute accepted obligations. The prepared capability viewer also omits current/history evidence, and the Windows finalizer cannot recover the interrupted-run state described by its instructions. + +Scope is the canonical `/tmp/gameport-phase01-review-scope.json` file union at HEAD `215d01e43e103f3fbb7e26b43607cd09f2856492`. Resolver status is **degraded**, reason `no-task-commit-rows`, using its real phase range from `9aa49970e43bc9ca5470b884757e3481e0c0293a`. The union contains 44 files; all seven SUMMARY key-file lists are covered, and none of these paths is ignored. No structural pre-pass or external reviewer evidence was supplied. The necessity rubric was read; no necessity finding was established. + +The pending 0/120 original/native obligations and ten human findings are expected acceptance dependencies, not implementation defects. Findings below concern enforceable identity/continuation contracts. Reproductions used disposable synthetic metadata only; the Windows recovery reproduction used Linux-hosted PowerShell, not native Windows. The existing complete-suite run was not repeated. No original was executed or modified, no source was edited, and no commit was made; unrelated `tools.yaml` was preserved. + +## Narrative Findings (AI reviewer) + +## Critical Issues + +### CR-01: Human review is checked against a different file from the selected receipt + +**Classification:** BLOCKER +**File:** `/home/cristian/codex/Neutron/GamePort/tools/recon/fidelity_acceptance.py:134-143` +**Issue:** `current.json` may select any contained receipt filename. The loop reads that path, discards it, then compares the human-review digest against `directory / 'receipt.json'`. A sibling `selected.json` can therefore supply the accepted record while the human finding binds unrelated `receipt.json` bytes. Raw result directories need not have an import sidecar, so `read_receipt` does not close this gap. This defeats the explicit receipt-byte review boundary; the same mismatch can affect every selected slot. + +**Evidence:** A bounded synthetic reproduction selected `run/selected.json`, stored a different object at `run/receipt.json`, and supplied the latter's digest in `human-review.json`. The real `audit()` returned `matrix.accepted == 1`, `human_needed == []`, and `errors == []`, despite the selected digest differing from the reviewed digest. Only material readiness was mocked to isolate receipt selection; hash checking, parsing and matrix evaluation ran normally. + +**Fix:** Carry the actual selected path/digest alongside each record and compare `receipt_sha256[receipt_id]` with that file. Alternatively, explicitly reject every selected basename other than `receipt.json` before reading it. Missing or different selected-file digests must invalidate the human finding. Add a regression with two different sibling JSON files and no sidecar. + +### CR-02: Original applicability never binds the executed executable or preservation inventories + +**Classification:** BLOCKER +**File:** `/home/cristian/codex/Neutron/GamePort/tools/recon/fidelity_acceptance.py:81-84` +**Issue:** The original-DxWnd branch checks only a `tree_sha256` string inside the receipt's `original_pre` JSON. It does not compare the actual identified executable against its selected pristine inventory member, validate original package/resource identities against that baseline, or check `original_post`. The generic validator checks each referenced file's own hash, which establishes identity but not applicability. Consequently, attaching a correct original-pre inventory to an unrelated executable is sufficient to pass `_bind`. This is weaker than the concrete executable/pre/post mapping promised in `docs/evidence/checkpoint-session.md:90-94`. + +**Evidence:** Starting with the existing complete metadata fixture for an original-DxWnd slot, a synthetic diagnostic replaced only `identity.executable` with the actual size/hash of a new file containing `synthetic wrong original executable`. The expected original-pre record stayed unchanged. `audit_records()` still returned one accepted obligation and no errors. The receipt schema otherwise remained valid; no false artifact hash was required. + +**Fix:** Pass the checkpoint's actual pristine file inventory into original binding, retain the exact selected original member path, and compare the receipt executable identity with that member. Validate package/resources and authoritative pre/post inventories against the same baseline; recompute inventory digests from their file records rather than trusting an embedded digest alone. Writable-copy changes must stay separately recorded. Add negative tests for a wrong executable and inconsistent pre/post inventory content. + +### CR-03: Fresh-copy continuity accepts a hash that identifies no artifact + +**Classification:** BLOCKER +**File:** `/home/cristian/codex/Neutron/GamePort/tools/recon/fidelity_receipts.py:659-669` +**Issue:** All cells require `copy_pre_sha256`, but fresh cells only check its 64-hex syntax. Actual identity membership is checked inside the retained-only branch. Thus a fresh observation can claim a nonexistent copy state and still fill an accepted slot, contrary to the fresh lifetime procedure's separately identified generated execution copy. The executable/package binding does not identify that per-run startup state. + +**Evidence:** With `FidelityScenarios.receipt('fresh-natural-ordinary', 'dialogue-return', 'native_port', 'linux')`, replacing `continuity.copy_pre_sha256` with `'f' * 64` produces `audit_scenarios(...).accepted == 1` and `invalid == []`. No identity file has that digest. This reproduction is a synthetic metadata diagnostic, not gameplay evidence. + +**Fix:** Require `copy_pre_sha256` to match the validated, explicitly named `identity.copy_pre` record for both lifetimes before branching. Bind retained-copy state to its explicitly named retained snapshot as well, rather than any unrelated identity hash. Add fresh-copy negative tests for an unknown digest and a digest belonging to the launcher/package instead of the per-run copy record. + +## Warnings + +### WR-01: Checkpoint assembly bypasses the capability ledger projection + +**Classification:** WARNING +**File:** `/home/cristian/codex/Neutron/GamePort/tools/recon/fidelity_checkpoint.py:165-167` +**Related:** `/home/cristian/codex/Neutron/GamePort/tools/recon/fidelity_viewer/viewer.mjs:228-244` +**Issue:** Assembly passes authoritative `capabilities.json` directly to `export_review()`. That export validates/copies source links but does not call `export_ledger()`, so its rows retain `evidence` without derived `current` and `history`. The browser renders only `row.current` and `row.history`, displaying `Unrecorded` in both sections and concealing the revision/classification details prepared for the reviewer. The separate CLI ledger-to-viewer test exercises the correct projection, but checkpoint assembly does not use that route. + +**Evidence:** In the actual sealed `dist/fidelity/phase01/review/review.json`, all 25 capability rows lack both fields. Applying `export_ledger()` to the authoritative input yields two current and two historical records for `startup-order`; none appears in those viewer sections in the prepared model. This is independent of missing original/native recordings. + +**Fix:** Generate the validated ledger projection before checkpoint review export, then preserve its current/history fields through source-link copying. Make `ready()` reject a malformed viewer ledger rather than checking only source hrefs. Add a preparation-to-renderer regression asserting that named current and superseded records survive the actual checkpoint assembly path. + +### WR-02: An interrupted Windows collector cannot be finalized through the documented recovery command + +**Classification:** WARNING +**File:** `/home/cristian/codex/Neutron/GamePort/scripts/collect-fidelity-windows.ps1:332-336` +**Related:** `/home/cristian/codex/Neutron/GamePort/docs/evidence/windows-session.md:150-152` +**Issue:** Startup writes `incomplete.json` before launching, while `run.json` is written only in the final `finally` block. If the collector is terminated before that block completes, its durable result has only the incomplete record. The instructions explicitly tell the tester to recover that state with `Finish -Outcome aborted`, but `Complete-FidelityRun` unconditionally reads missing `run.json` first. The supplied recovery command therefore cannot retain the interrupted launch's media as a terminal receipt; asking for a fresh launch would misidentify its lifetime. + +**Evidence:** A disposable synthetic prepared bundle with `results/interrupted/incomplete.json` and no `run.json` was passed to the real finalizer through Linux-hosted PowerShell. It failed immediately with `Cannot find path '.../results/interrupted/run.json' because it does not exist.` The failed lookup precedes annotation/media recovery. Existing terminal tests always create `run.json` and do not cover this durable interrupted state. + +**Fix:** Add an explicit aborted-recovery path using the retained initial record when `run.json` is absent. Preserve its launch identity and raw bytes, prohibit captured/reviewed promotion, and leave unavailable end clocks/observations explicitly missing. Recover media into a new write-once diagnostic receipt without inventing elapsed times. Test an incomplete-only result folder and verify that it remains open and structurally importable. + +--- + +_Reviewed: 2026-11-13T21:56:48Z_ +_Reviewer: gsd-code-reviewer_ +_Depth: standard_