fix(review): negotiated START freezes an empty candidate on a clean post-apply worktree

[aparragithub]

Pre-flight Checklist

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

📝 Bug Description

On a clean feature branch whose SDD implementation is already committed, the negotiated review loop freezes a candidate that reviews nothing, approves it, and only fails three gates later with a message that describes the wrong problem.

review status --contract gentle-ai.review-integration/v2 --next-transition proposes review.start with projection: workspace. Because the worktree is clean, START freezes changed_files: 0, changed_lines: 0, paths: [], and base_tree == candidate_tree. The zero-lens low-risk review finalizes as approved and pre-commit returns allow. Delivery then fails at pre-push, and no base selector can repair it, because the reviewed scope is empty rather than merely mis-based.

This is a distinct mechanism from #2090 (closed by #2169), where the freeze was correct and the emptiness appeared later at validation after a strict-subset correction and a recovered successor. Here the freeze itself is born empty, with no correction and no recovery involved. It is also the START-side sibling of #1203, which fixed the post-apply variant of "clean worktree after the approved candidate was committed".

Root trigger: internal/cli/review_next_transition.go proposes review.start with TargetCurrentChanges whenever target applicability is unrelated, with no clean-workspace check. This is the standard STATUS-driven loop, not a misuse.

🔄 Steps to Reproduce

1. Create a feature branch with three commits ahead of origin/main, and leave the worktree clean (git status reports nothing pending).
2. Run negotiated STATUS and execute exactly the review.start transition it returns:

   gentle-ai review status --cwd <repo> --contract gentle-ai.review-integration/v2 --next-transition
   

3. Observe the frozen authority: projection: workspace, changed_files: 0, changed_lines: 0, paths: [], and equal base/candidate trees.
4. Finalize the zero-lens review and validate pre-commit. Observe allow.
5. Validate delivery without a base selector:

   gentle-ai review validate --cwd <repo> --lineage <lineage-id> --gate pre-push
   

   Observe invalidated: configured upstream is missing or ambiguous; pass --base-ref <remote>/<branch>.
6. Retry with the explicit base:

   gentle-ai review validate --cwd <repo> --lineage <lineage-id> --gate pre-push --base-ref origin/main
   

   Observe invalidated: compact gate inputs cannot be derived: reviewed delivery is not exactly one commit from its reviewed base.

✅ Expected Behavior

For a post-apply candidate whose implementation is already committed, negotiated START should either freeze the committed delivery range against the intended base, or refuse before issuing an approval that no delivery gate can consume — naming --base-ref <commit> as the way to review committed work.

The repository already contains exactly that guidance as reviewStartEmptyCandidateHint in internal/cli/review_facade.go:

the candidate has no pending changes; already-committed work can be reviewed by rerunning review start with --base-ref <commit> naming the base to compare against

It is emitted only on the unnegotiated path, so the negotiated contract path never receives it.

❌ Actual Behavior

Negotiated START approves an empty workspace projection. pre-commit allows it. Delivery validation then evaluates the non-empty committed range against a receipt that covers nothing.

The emitted error is also misleading. reviewedDeliveryBase in internal/reviewtransaction/gate.go scans the publication range for the commit whose tree equals the receipt's delivery base tree. With base_tree == candidate_tree == HEAD's tree, the only match is HEAD itself, so the derived range holds zero commits — not "more than one", which is what reviewed delivery is not exactly one commit from its reviewed base implies.

A precise diagnostic for this shape already exists in internal/reviewtransaction/compact_gate.go (pre-push current-changes receipt requires a delivered tree change), but it is unreachable here: target derivation fails first and returns the opaque derivation error, and the retry beside it only applies when a recovery chain exists.

The explicit-maintainer action can supply a base selector, but cannot repair an empty reviewed scope.

💡 Logs / Error Output

$ gentle-ai review validate --cwd <repo> --lineage <lineage-id> --gate pre-push --base-ref origin/main
{
  "schema": "gentle-ai.review-gate-result/v1",
  "result": "invalidated",
  "allowed": false,
  "action": "explicit-maintainer-action",
  "reason": "compact gate inputs cannot be derived: reviewed delivery is not exactly one commit from its reviewed base",
  "context": {
    "gate": "pre-push",
    "generation": 1,
    "base_tree": "<tree-sha>",
    "candidate_tree": "<tree-sha>",
    "paths_digest": "<digest of the empty path set>"
  }
}

candidate_tree is byte-identical to base_tree. Frozen scope on the approved authority: changed_files: 0, changed_lines: 0, paths: [].

Worktree and index remained clean throughout. No push, PR, merge, history rewrite, recovery, additional review, or authority mutation was attempted, and no delivery side effect occurred.

Additional Context

Verified against a branch with three commits, which matters for the fix shape: auto-deriving a base such as HEAD~1 would have silently frozen one third of the work as if it had succeeded. The correct base was origin/main, i.e. HEAD~3. Choosing the base is the reporter's call, so the tool should state that a base is required rather than guess one.

Related: #2090 (closed by #2169) shares the empty-receipt symptom but not the cause. #1203 fixed the post-apply variant of the same committed-clean-worktree family.

[Juangarciaing]

Confirmed another occurrence with the same mechanism. Privacy scan completed: this report contains no raw argv, absolute paths, repository names, usernames, hostnames, credentials, diffs, source contents, or environment values.

Environment

• gentle-ai 2.2.4
• Linux x86_64
• OpenCode client
• Clean feature branch, 19 commits ahead of origin/main

Operation and bounded outcomes

1. Negotiated status exposed an already-approved compact-v2 authority for a workspace / current-changes projection with original_changed_lines: 0, paths: [], and equal base/candidate trees.
2. pre-commit validation returned allow.
3. One pre-push attempt without a selector returned invalidated: configured upstream is missing or ambiguous; pass --base-ref <remote>/<branch>.
4. After querying negotiated status again, one pre-push attempt with --base-ref origin/main returned invalidated: compact gate inputs cannot be derived: reviewed delivery is not exactly one commit from its reviewed base.

Opaque authority evidence: lineage review-39a26c08e7de89e9, generation 1, revision prefix sha256:fdb111d55949.

Expected

Negotiated review should bind the committed candidate range against an explicitly supplied base, or stop before approving an empty candidate and explain how to start a review for committed work.

Actual

An empty workspace candidate is approved, but its receipt cannot authorize delivery of the committed branch. Supplying the requested base selector does not recover it.

Minimal reproduction

• Create a clean feature branch with multiple commits ahead of origin/main.
• Follow negotiated review status transitions until the zero-change authority is approved.
• Validate pre-commit and observe allow.
• Validate pre-push first without and then with --base-ref origin/main; observe the two failures above.

Preserved state

No push, PR, merge, commit, reset, rebase, source mutation, or review repair was performed. The clean branch and all consumer state remain preserved.

[biggs-100]

Confirmed another occurrence with the same mechanism on Windows (win32, build 26200), OpenCode client, gentle-ai 2.2.4.

Occurrence sequence:

1. On a clean worktree (feature work already committed), negotiated review.status --next-transition returned review.start with a workspace projection; executing START created a review with changed_files: 0, risk_level: low (non_executable_only) and no artifact subjects.
2. Following the route, review.finalize approved that empty review and produced a receipt.
3. A second, real review was started directly with --base-ref <base> --committed-only over the committed change: risk_level: medium, one lens (review-reliability), 22 changed files, 1454 lines, correction budget 200, one artifact subject. Consent was granted through the negotiated form.
4. After that, negotiated review.status never served the collect transition for the second lineage: it keeps returning review.validate for the first (empty) lineage (approved_receipt_ready) on every call.
5. review.capture-result --preflight for the bound subject returned valid (binding matches). But launching the lens reviewer task failed twice, both provider-owned: first repository_context_capture_failed (raw result preserved as rinc1_5a18ec74...), then native admission rejected the reviewer result as out_of_scope (result preserved as rinc1_0e5ac902...).

Expected: after a consented START with subjects, STATUS should serve collect for that lineage so the reviewer result can be captured and finalized into a receipt.

Actual: the empty review's lineage anchors the negotiated route; the real lineage never gets a collect transition, and the task-integration capture fails (context capture, then out-of-scope admission).

Mutation outcome: no source changes; first lineage approved with an empty receipt; second lineage left in reviewing state with no persisted capture; working tree remained clean.

Minimal reproduction (sanitized): in any repo with committed changes and a clean tree, (1) run negotiated status -> START freezes an empty candidate; (2) finalize it; (3) start a second review with --base-ref and grant consent; (4) run status repeatedly: collect for the second lineage is never offered; (5) attempt the reviewer capture via the task integration: fails as described.

Opaque identifiers for correlation: lineages review-c659da9e... and review-4b7b12c7...; target sha256:4b7b12c7...; preserved raw results rinc1_5a18ec74... and rinc1_0e5ac902....

Happy to provide more detail if useful.

[napisolutions]

Confirming on gentle-ai 2.2.4, Linux x86_64 (WSL2). Same root trigger as the OP: negotiated STATUS on a clean feature branch (commits ahead of base, nothing pending) proposes review.start with projection: workspace, freezing an empty candidate (paths: [], base_tree == candidate_tree).

Adding a data point on the unnegotiated --base-ref workaround that the existing reviewStartEmptyCandidateHint points users toward: it starts and captures, but the resulting lineage stays orphaned from finalize / status / validate.

Reproduction

Feature branch with an SDD change whose implementation is already committed (multiple work-unit commits ahead of base); git status clean.

1. review start --base-ref <base-ref> --committed-only=true → succeeds. Creates a real review lineage, state: reviewing, risk_level: medium, 1 lens (review-reliability), non-zero changed_files / changed_lines, and emits a full binding (lineage id, target identity, base_tree, candidate_tree, artifact_subject + subject_hash, authority_revision).
2. review capture-result --lineage <lineage> --target <target> --lens review-reliability --order 0 --expected-revision <rev> --subject-hash <hash> --input <reviewer-result.json> → admission_decision: completed; the reviewer result artifact is persisted under .git/gentle-ai/review-transactions/v2/<lineage>/reviewer-results/.
3. review finalize --lineage <lineage> → fails: "review finalize requires all 1 original reviewer result(s); capture each missing one", and directs to review status --contract gentle-ai.review-integration/v1.
4. review status --contract gentle-ai.review-integration/v1 --next-transition (same for v2) → still returns the empty-workspace projection (paths: [], base_tree == candidate_tree), action: start, offering a fresh review.start with the workspace target. The --base-ref lineage is not discovered at all.
5. review validate --gate pre-pr --lineage <lineage> --base-ref <base-ref> → "facade review receipt is not available; run review finalize".

Expected

Once a --base-ref review has started and its lens result has been admitted, finalize / status / validate should discover that lineage and produce a consumable receipt. Otherwise the only documented way to review already-committed work (the --base-ref hint) cannot reach a receipt, and the negotiated path still freezes empty per the OP — leaving committed-delivery review with no working path to a gate-consumable receipt.

Possibly related

#1666 (single-lens FINALIZE stuck at reviewing / operation_outcome_unknown), and the closed committed-delivery recovery work #1744 / #1772.

Happy to attach a scrubbed full command transcript + the JSON envelopes (start/v3, capture-preflight/v1, result-artifact/v2) if useful.

[napisolutions]

Update / partial retraction: the --base-ref committed-diff path does close end-to-end once verification evidence is captured via review capture-evidence before finalize. The earlier "finalize requires all 1 original reviewer result(s)" / "receipt not available" errors occurred because I had not yet captured the runtime verification evidence — finalize needs both the reviewer result (capture-result) and verification evidence (capture-evidence, e.g. test output with --outcome passed) to move from reviewing → validating → approved and emit the receipt.

Sequence that worked on 2.2.4 (feature branch, clean worktree, commits ahead of base):

1. review start --base-ref <base> --committed-only=true → lineage, lens, binding.
2. review capture-result ... --input <reviewer-result.json> → admission_decision: completed.
3. review capture-evidence --lineage <lineage> --expected-revision <rev> --target <target> --outcome passed --input <test-output> → captured.
4. review finalize --lineage <lineage> --captured-evidence=true → state: approved, receipt written.
5. review validate --gate pre-pr --lineage <lineage> --base-ref <base> → result: allow.

Caveat observed: finalize validates the live repository snapshot against the frozen target, so it must run with the worktree in the same state the review was frozen against (committed, clean) — running it from a staged/uncommitted state raises "live repository snapshot no longer matches frozen target". With that, the committed-delivery path reaches a gate-consumable receipt. Retracting the earlier "orphaned lineage" claim; the missing step was verification evidence.

[dnlrsls]

Linked to canonical tracker #1250. Shared clause: authority, status, recovery, and gates must use one canonical target descriptor.

This issue remains open with its own acceptance criteria and regression evidence, and is not being marked as a duplicate.