fix: stop reviewer-receipt invalidation loop with deterministic review freeze (2.5.39)

[apackeer]

Fixes #698.

The bug

Reviewer-bearing stages could wedge at approval. If a conductor applied a suggestion after recording the terminal REVIEW_COMPLETED receipt, the later artifact write invalidated that receipt, causing another review/edit cycle instead of reaching the gate.

The fix

• Stage protocol section 12a makes a READY receipt terminal: apply fixes inside the reviewer loop, stop artifact writes after the terminal receipt, quote optional suggestions at the gate, and keep Approve as the first option.
• New aidlc-review-freeze.ts PreToolUse enforcement blocks file-tool, apply-patch, and mutation-capable shell writes to declared produces[] artifacts while a fresh READY receipt covers them. It exports the compiled run(input) contract and is registered on Claude, Codex, every writable Kiro CLI conductor/delegate surface, and opencode. Kiro IDE remains prose-governed.
• Every completed review records a SHA-256 fingerprint of its declared artifact set. Approval and swarm finalization require that fingerprint to remain current, so unobserved shell, interpreter, or delegated writes cannot preserve a stale receipt.
• A gate rejection, jump, or workflow restart reopens artifact work. NOT-READY never freezes. AIDLC_DISABLE_REVIEW_FREEZE_HOOK=1 disables enforcement.

Rebase reconciliation

PR #703 landed first as 2.5.38 with the mandatory summary-confirmation receipt. This branch is rebased onto that head and published as 2.5.39; both receipt systems coexist, and REVIEW_FREEZE_BLOCKED raises the audit taxonomy to 76 events.

The current TUI driver uses the overall deadline as its hang backstop, superseding this branch's earlier fixed 900-second per-gate workaround.

Verification

• bun run check: package parity, all TypeScript configs, and Biome pass.
• Full smoke + unit: 190 files, 4,684 assertions, 0 failures.
• Focused swarm integration (t135): 12 assertions, 0 failures.
• Focused terminal-ordering, review-freeze, dispatcher, packaging, version, and taxonomy tests pass.

Upgrade: re-copy your selected dist/<harness>/ shell into the project so the updated protocol, skills, hooks, tools, and agent configs are installed.

[leandrodamascena]

Thanks for the thorough investigation and for addressing the terminal-receipt ordering in both prose and enforcement. The focused official suites and package parity pass, but I found three behavioral gaps plus a release-version conflict that should block merge.

1. P1: review-freeze is unavailable through the compiled dispatcher

core/hooks/aidlc-review-freeze.ts implements all runtime behavior inside if (import.meta.main) and does not export run(input). The compiled adapter path invokes core hooks through aidlc hook <name>, whose dispatcher requires exactly that export.

Reproduction:

$ bun core/tools/aidlc.ts hook review-freeze <<<"{}"
aidlc hook review-freeze: hook does not export run(input)

Codex and Kiro adapters use AIDLC_COMPILED_EXECUTABLE when running under the compiled distribution. The dispatcher exits 1, while both adapter arms block only on exit 2, so the failure becomes a silent allow and review-freeze is disabled on that supported path.

References: core/hooks/aidlc-review-freeze.ts:164, core/tools/aidlc.ts:976-986, harness/codex/hooks/aidlc-codex-adapter.ts:194-197, and harness/kiro/hooks/aidlc-kiro-adapter.ts:589-610.

Please move the hook body into an exported run(input): Promise<number> and keep the direct entrypoint as process.exit(await run(...)). Add a binary/dispatcher test, not only a source-registration assertion.

2. P1: Bash writes preserve a stale READY receipt as fresh

The hook deliberately excludes Bash, and the PostToolUse audit logger is also registered only for Write/Edit. After a READY receipt, a conductor can therefore mutate reviewed bytes with a normal shell command such as:

printf "change" >> aidlc/.../requirements-analysis/requirements.md

That write is neither blocked nor recorded as ARTIFACT_UPDATED. freshReviewReceipts() therefore continues returning the old READY receipt, and the gate can approve content that was changed after review. This is worse than merely reopening the original loop: the stale receipt can certify different bytes.

References: core/hooks/aidlc-review-freeze.ts:43-48 and :76-85; harness/claude/settings.json:95-103.

The stated symmetry keeps both mechanisms blind, but it does not preserve the invariant that the receipt covers final artifact bytes. Please either inspect mutation-capable shell commands, make freshness content-based, or otherwise ensure shell writes invalidate the receipt.

3. P1: Kiro delegated writes are outside both freeze and invalidation

Kiro registers review-freeze only on the conductor config. Delegated agents retain fs_write, but their configs do not register review-freeze or the audit feed. This is reachable on reviewer-bearing dispatched stages: code-generation is both mode: subagent and reviewer-bearing.

If the conductor incorrectly re-invokes the lead after READY to apply a suggestion, the delegated writer can change code-generation-plan.md or code-summary.md; the change is neither blocked nor audited, so the old receipt remains fresh.

References: harness/kiro/agents/aidlc.json:74-89, harness/kiro/hooks/aidlc-kiro-adapter.ts:569-579, and core/aidlc-common/stages/construction/code-generation.md:8-15.

Please register the freeze for mutation-capable delegated agents as well, or provide an equivalent deterministic boundary. The current t264 Kiro assertion only verifies the conductor registration and therefore pins the gap rather than detecting it.

4. Merge blocker: version 2.5.35 is already occupied

This branch publishes 2.5.35, but current v2 is 2.5.37 and already contains an unrelated 2.5.35 release. The PR is consequently CONFLICTING / DIRTY. Per the repository conflict-trap policy, it needs to be rebased and re-bumped to the next available version, currently likely 2.5.38, with README and CHANGELOG kept in sync.

References: core/tools/aidlc-version.ts:4 and CHANGELOG.md:4.

Verification

• Official focused runner for t263/t264: 21/21 passed.
• Existing Codex/Kiro/OpenCode adapter tests: 34/34 passed.
• bun scripts/package.ts --check: all five branch harnesses in sync.
• Remote CI is green.

These results show that the added tests cover the direct hook and registration text, but not the compiled dispatch path or the mutation surfaces above. I recommend keeping this at CHANGES_REQUESTED until the three enforcement gaps are closed and the branch is rebased/re-versioned.

[apackeer]

Addressed all four blockers from the latest review in 2b010324:

• Exported run(input) from aidlc-review-freeze.ts and added dispatcher/compiled-binary coverage.
• Added mutation-capable shell targeting plus SHA-256 artifact fingerprints, so approval and swarm finalization reject changed or missing reviewed artifacts regardless of write mechanism.
• Registered review freeze and post-write invalidation across writable Kiro CLI conductor/delegate surfaces.
• Rebased onto current v2 and synchronized the release version, README badge, and changelog at 2.5.38.

Follow-up review also hardened shell operand handling for target-directory commands, mv sources, multi-file sed/perl, truncate options, and read-only source/reference operands.

Verification:

• Focused smoke/unit/integration/e2e slice: 222 assertions passed, 0 failed.
• Final review-freeze slice: 19 passed, 0 failed.
• bun run check: package parity, all TypeScript projects, and Biome passed.
• Coverage registry freshness/ratchet check passed.
• Independent final re-review found no remaining issue in the follow-up parser changes.

[leandrodamascena]

The four blockers from my previous review are resolved:

• Compiled dispatcher support now exports and tests run(input).
• Shell and unobserved writes are covered by pre-write detection plus artifact fingerprints.
• Kiro delegated writers now receive freeze and invalidation hooks.
• The branch is rebased and versioned as 2.5.38.

Focused tests, swarm integration, package parity, and remote CI pass. No remaining blocking findings.

Approved.