fix(review): expose immutable candidate diff and changed-path manifest from START

[AndySabina]

Pre-flight Checklist

• I have searched existing issues, including open and closed results, and this is not a duplicate
• I understand that PRs will be rejected if the linked issue does not have status:approved

📝 Bug Description

Gentle AI 2.1.8 ordinary compact review start does not expose the exact immutable candidate diff and changed-path manifest, or public content-bound artifact references to them, even though the shipped review ledger contract requires orchestrators to append both inputs before launching each selected lens and to stop when they are unavailable.

PR #1395 partially fixed #1394 by emitting target_identity and lens_bindings and preserving full lens names. It did not expose the immutable diff, changed-path manifest, or public references cryptographically bound to those exact contents. This remaining gap was documented in a comment on #1394, but #1394 was closed after the partial fix and no active issue tracks the remaining contract mismatch.

This is not a duplicate of:

• fix(review): preserve reviewer output and recover from capture binding incidents #1411, which covers capture preflight, result preservation, and recovery after a reviewer is launched.
• fix(review): bind ordinary review to exact staged or manifest candidates #1250, which tracks staged/manifest candidate projection and exact index authorization, not delivery of an already-frozen candidate's lens inputs through the public START interface.

🔄 Steps to Reproduce

1. Install and sync Gentle AI 2.1.8.
2. In a disposable Git repository, create and stage an ordinary executable-code change.
3. Run gentle-ai review capabilities --contract gentle-ai.review-integration/v1.
4. Run gentle-ai review start --cwd <repo> --projection staged.
5. Inspect only the public START response and supported public review status output.
6. Attempt to obtain the exact immutable candidate diff and changed-path manifest, or public content-bound references to them, without reading private .git/gentle-ai implementation storage or reconstructing inputs from mutable Git state.
7. Observe that START provides identity and lens bindings but no supported public immutable diff/manifest inputs.
8. Follow internal/assets/skills/_shared/review-ledger-contract.md, which requires both inputs before every lens and says if unavailable, stop.

✅ Expected Behavior

Every created, resumed, or continued compact START that selects lenses should expose public, immutable, content-bound lens inputs:

• the exact candidate diff;
• the canonical changed-path manifest, including modes, deletions, and intended-untracked paths where applicable;
• or stable public artifact references carrying native hashes/signatures that bind those exact bytes to the returned target_identity, lineage, projection, base tree, and candidate tree.

The interface should let an orchestrator launch lenses exclusively from supported START output without reading private authority storage or reconstructing evidence from mutable repository state.

❌ Actual Behavior

START emits target_identity and lens_bindings, but not the exact immutable candidate diff, changed-path manifest, or public content-bound references to either artifact.

The shipped orchestration contract therefore requires a conformant orchestrator to stop before launching reviewers. With no captured lens results, no receipt can be finalized, and lifecycle validation later reports that the facade review receipt is unavailable.

Gentle AI Version

v2.1.8

Operating System

Linux

Agent / Client

OpenCode

📋 Affected Area

CLI / review integration contract / OpenCode review orchestration

Shell

bash

💡 Logs / Error Output

review start: target identity and lens bindings emitted; immutable diff/manifest inputs unavailable
orchestration contract: "Before each lens, append the exact immutable candidate diff and changed-path manifest from START; if unavailable, stop."
review validate --gate pre-commit: Error: facade review receipt is not available

Additional Context

Relevant sources and history:

• Review ledger contract: internal/assets/skills/_shared/review-ledger-contract.md
• START schema: contracts/review-integration/v1/schemas/start.schema.json
• Partial predecessor: fix(review): START omits binding inputs and OpenCode plugin rewrites lens names #1394 / PR fix(review): emit START binding inputs and stop plugin lens rewrite #1395
• Remaining-gap reproduction: fix(review): START omits binding inputs and OpenCode plugin rewrites lens names #1394 (comment)
• Related but distinct: fix(review): preserve reviewer output and recover from capture binding incidents #1411 and fix(review): bind ordinary review to exact staged or manifest candidates #1250
• Release: https://github.com/Gentleman-Programming/gentle-ai/releases/tag/v2.1.8

No private repository paths, candidate code, active lineage identifiers, or private hashes are included in this report.

[Alan-TheGentleman]

Independent corroboration from maintainer use, plus a concrete failure this gap caused.

Over roughly seven native bounded 4R reviews driven end to end today on v2.1.9, review start returned target_identity, lens_bindings, projection, changed_files, changed_lines, risk_level and correction_budget — and no candidate diff, no changed-path manifest, and no content-bound reference to either. Every one of those reviews required deriving both inputs by hand from mutable Git state and feeding them to the lenses, which is exactly the reconstruction this issue says a conformant orchestrator should not have to perform. The shipped ledger contract says to append both from START and stop if unavailable; in practice the only way to proceed is to ignore that instruction and rebuild the inputs locally.

The predicted harm is not theoretical. One of those hand-derivations was wrong: git diff origin/main..HEAD (two-dot) against a main that had advanced produced a candidate of 1,936 changed lines across 17 files when the real change was two commits. review start froze that contaminated target, the lens work was scoped to code the author never wrote, and the entire 4R pass had to be discarded and re-run after merging main and re-deriving the diff with three-dot. Nothing in the START response could have caught this, because START never asserted what the candidate's contents were — only its identity.

That is the load-bearing point. target_identity binds a candidate the caller cannot obtain. An orchestrator can prove that it has the right target only after it has already guessed what the target is, from a source START does not control. Emitting the immutable diff and changed-path manifest — or content-bound references to them — closes the loop: the inputs the lenses review would be the same bytes the identity attests, by construction rather than by the caller's care.

Two notes for whoever implements this:

• The failure mode above argues for the manifest as much as the diff. The wrong-candidate case was visible in the path list long before it was visible in the content; a changed-path manifest bound to the frozen target would have made it immediately obvious.
• Scope discipline matters here more than usual. The delivery attempt on this issue reportedly reached ~1,300 lines across code, tests, contracts, fixtures and docs and never converged, partly for reasons unrelated to the change itself (tracked in fix(review): work spanning multiple worktrees forces full session restarts and fragments review context #1530 and fix(review): honoring the 400-line review budget via chained PRs is disproportionately expensive under content-bound receipts #1531). Landing the artifact emission and its binding first, with schema and fixtures alongside, and leaving documentation and any SDD/OpenSpec surface to follow-ups, would keep each slice independently reviewable instead of dependent.

Still valid on v2.1.9. status:approved stands.

[goridragon]

Additional read-only confirmation on gentle-ai 2.1.9 under WSL/Linux, OpenCode, and bash:

• Negotiated gentle-ai review start created a high-risk lineage/target, selected lenses, and froze base/candidate Git trees, but emitted neither immutable candidate-diff bytes nor a changed-path manifest/artifact path.
• Re-running the same START resumed authority and still emitted neither required lens input.
• Target-scoped review status --contract gentle-ai.review-integration/v1 --lineage <lineage> exposed target identity, base tree, initial/current candidate tree, paths digest, and the path list only.
• review capabilities exposed no candidate-artifact retrieval operation, and review start --help exposed no artifact output/retrieval flag.
• The generalized authority directory contained only review-state.json; no canonical diff artifact was persisted.

A Git diff can be reconstructed from the frozen trees, but no documented canonical flags or byte format bind that reconstruction as START's immutable artifact. Under the shipped lens contract, review therefore had to stop before launching lenses.

Expected: START emits or persists authoritative immutable candidate-diff bytes and the changed-path manifest, or returns documented target-bound artifact paths retrievable for lens prompts. Actual: only tree/identity/path metadata is available, so review cannot proceed safely. No destructive workaround was attempted; the existing lineage remains untouched.

[fedemeson777]

I can confirm this is still reproducible with OpenCode on Windows using gentle-ai 2.1.10.

review start created lineage review-1f1198d25e4dc814 with a frozen target and selected lenses. However, START and the read-only status contract expose only paths, digests, and tree identities. They do not provide immutable candidate diff bytes or a complete path/mode manifest.

Because the lifecycle requires those exact frozen inputs before a lens can run, the review cannot proceed to finalize, commit, push, or deploy without bypassing the contract. review recover is not a read-only workaround because it creates successor authority.

A native identity-bound snapshot export, or emitting the diff and path/mode manifest directly from START, would unblock this safely.

[goridragon]

Still blocking on 2.1.11 after sequential upgrade

This remains reproducible after upgrading Gentle AI 2.1.9 -> 2.1.10 -> 2.1.11.

Environment

• Host/runtime: Windows host via WSL2
• Linux distribution: Ubuntu 24.04.4 LTS
• Kernel: Linux 6.18.33.2-microsoft-standard-WSL2 on x86_64
• Shell: GNU bash 5.2.21
• Agent/client: OpenCode

Latest reproduction

1. Resume an existing high-risk review lineage already in reviewing.
2. Restore its exact frozen target. Applicability reports current_target.
3. Verify every frozen candidate path remains byte- and mode-identical.
4. Before retry, remove an accidental untracked .env.local from review scope. That file had caused transient target drift only; it was not part of the frozen candidate and is not the root defect.
5. Inspect the native next transition. It is collect with reason reviewer_results_required. A new START is forbidden because the review budget and lineage already exist.
6. Inspect the supported START, status, and capabilities surfaces for the exact inputs required to launch the selected lenses.

The orchestrator contract requires every selected lens to receive the exact immutable candidate diff and changed-path manifest from START. However, START/status/capabilities still expose neither:

• authoritative immutable candidate-diff bytes or an artifact path; nor
• authoritative changed-path-manifest bytes or an artifact path.

Only inline path projection and tree/identity metadata are available. Reconstructing git diff from repository state is not an authoritative START artifact and would violate the binding requirement, even when the frozen trees are known.

Blocking result

The existing review cannot legally launch its lenses, cannot collect reviewer results, and therefore cannot finalize. Verification and publication remain blocked while the frozen candidate itself stays immutable.

This confirms the defect tracked here is still present in 2.1.11. The temporary .env.local drift was diagnosed and removed from scope before retry; exact target restoration did not make the required artifacts retrievable.

Expected behavior

Provide a documented native retrieval or output surface for the canonical target-bound candidate diff and changed-path manifest of an already-started lineage. The returned artifacts should be bound to the existing lineage and frozen target, and validators should require those canonical artifacts rather than permitting reconstruction from mutable Git state.

Once artifact support lands, what is the supported recovery/resume procedure for lineages that are already active in reviewing and have no reviewer results? The procedure needs to preserve the current lineage, target, and correction budget rather than opening a second budget.