feat(gate-integrity): task must not finalize succeeded while steps lack an explicit APPROVE in their review files

[HenryLach]

Follow-up from #624 (second observed failure mode, task TP-2019 in the reporter's run).

Problem

A worker implemented Steps 1–4 as one changeset, got the Step-1 code review to APPROVE, then self-attributed that approval to Steps 2–6 and the task finalized (succeeded + .DONE) with Steps 2–6 never independently review-gated. The review gate is currently enforced only by worker-prompt convention — the engine does not verify per-step review coverage before accepting .DONE.

The #624 verdict-extraction fixes (robust parseReviewVerdict, fail-closed review_step tool, file-authoritative disposition) close the mis-read verdict path, but nothing prevents a worker from simply not calling review_step for a step, or reusing one step's approval for others.

Proposed direction

A completion-gate assertion at task finalization (lane-runner, where .DONE is validated): for each step requiring review under the task's Review Level, verify .reviews/ contains a review file for that step whose verdict (via parseReviewVerdict) is APPROVE. On violation: refuse finalization, log the gap to STATUS.md, and surface a review-intervention-needed (order-violation) alert so the supervisor adjudicates.

Design questions to settle before building:

• Review Level semantics: which steps require which review types (plan/code/test) — reuse the level definitions in the worker prompt/TP-117.
• Escape hatch: supervisor/operator-approved waiver for legitimately unreviewable steps (docs-only, etc.), so the gate doesn't hard-block edge cases.
• Segment-scoped tasks: per-segment vs per-step coverage in workspace mode.
• Interaction with maxReviewCycles (soft cap) and the bug: review-boundary path emits spurious "Reviewer unavailable" (review_failed) on every successful review (0.30.5) #624 spiral escalation.

References

• bug: review-boundary path emits spurious "Reviewer unavailable" (review_failed) on every successful review (0.30.5) #624 comment with the TP-2019 evidence (steps 2–6 finalized unreviewed).
• parseReviewVerdict (extensions/taskplane/review-analysis.ts) — the shared verdict parser the gate should reuse.
• TP-186 isStepMarkedComplete — the existing narrow order-of-operations guard this generalizes.

[HenryLach]

Concrete instance where this check would have prevented a merge: penster TP-2037, batch henrylach-20260903T134933. Code gate round 2 (R004) returned REVISE at the cap; the worker self-released ~8 minutes later, wrote .DONE, and the wave merged with the step's latest review file still reading REVISE. Details and the complementary escalation-hold proposal in #627.

[HenryLach]

Minimal cut implemented (commit a32cde3, on the review-boundary bundle branch): the lane-runner now refuses .DONE when any gate's LATEST review file verdict is REVISE/RETHINK — checked via latestReviewFilesPerGate + the shared parseReviewVerdict right before .DONE creation/acceptance. On refusal: worker-written .DONE is deleted, STATUS logs 'Finalize refused', a steer-delivered review-intervention-needed alert (kind unresolved-verdict) reaches the supervisor with remediation guidance (address findings + re-review + orch_retry_task/orch_resume, or record an operator ratification as the next R-numbered review file with an explicit APPROVE), and the task returns failed with a clear exitReason instead of merging.

This blocks the TP-2037 and TP-2039 closure classes (both had latest file = REVISE). Kept open for the designed follow-up this issue proposes: the full coverage gate (steps with NO review at all — the TP-2019 class), Review-Level semantics, waiver path, and segment-scoped coverage. The held state (#627) complements this for in-flight holds.

[HenryLach]

The documented remedy path is not reachable on the v2 runtime. Observed in penster batch henrylach-20260905T165645 (TP-2048, 2026-09-05): the minimal-cut gate refused finalization correctly (R004-code-step4.md: REVISE was the latest review at refusal time; the ratification R005-code-step4.md: APPROVE was committed 35 s later). The supervisor then followed this comment's remedy — ratification as the next R-numbered APPROVE file, then orch_retry_task + orch_resume — and the batch could not be re-driven: orch_retry_task resets the task record but not the v2 segment record, so computeResumePoint counts the wave as done and the resume loop runs nothing (twice, zero events, waveIndex persisted past the end of a 1-wave plan). Filed as #629 with the timeline, log lines, and code pointers. Recovery was a manual finalize.

Second observation for this gate: the refusal is recorded as a worker crash. events-exit.json shows exitCode: 0, exitSignal: null, error: null, yet the lane record has worker.status: "crashed" and no exitDiagnostic, so tier-0 logs has no exit diagnostic classification — skipping auto-retry (conservative) and the diagnostics report cannot distinguish a governance refusal from a real crash. The refusal path in lane-runner.ts (makeResult(..., "failed", ..., "Review gate: cannot finalize — ...")) should carry a distinct exit classification (e.g. finalize_refused / unresolved-verdict) so it is neither auto-retried nor reported as a crash.

Until #629 lands, the working recovery for a refusal whose ratification arrives after the fact is the manual-finalize playbook (write .DONE with provenance, merge lane→orch, reconcile history), not retry+resume.

[HenryLach]

Status update (for agents reading this issue) — remedy path is now reachable

Supersedes the 2026-09-06 comment above ("the documented remedy path is not reachable on the v2 runtime"): that was #629, fixed in PR #632 (commit 6afe3640). Both halves are in v0.30.6:

The gate (minimal cut, a32cde3e)

• Before .DONE is created/accepted, the lane-runner checks each review gate ({type}-step{N}): the latest R{NNN}-{type}-step{N}.md must not read REVISE/RETHINK. If it does: worker-written .DONE deleted, STATUS Finalize refused, task fails with exit classification review_gate_refusal (exit code 0 — not a crash, never auto-retried), and the supervisor gets a steer-delivered review-intervention-needed alert (kind unresolved-verdict).
• Steps with no review file are not blocked by this cut (full coverage gate = this issue's remaining scope).

The remedy (now working, 6afe3640)

• Worker path: when all checkboxes are checked but a gate's latest verdict is REVISE/RETHINK, the lane spawns a bounded (2) remediation iteration focused on that step: read the review file, address every finding, commit, re-run review_step for that step. Do not un-check/re-check boxes; do not write .DONE. review_step's complete-step guard is exempted for this re-review.
• Supervisor path: orch_retry_task <id> now also resets the task's segment records, so orch_resume(force=true) re-drives the wave instead of no-op'ing.
• Operator ratification path: record the ruling as the next R-numbered review file for that gate with an explicit ## Verdict: APPROVE, then retry + resume.

Still open here: the full coverage gate (steps with no review at all), Review-Level semantics, waiver path, segment-scoped coverage — the held state (#627) is the designed companion.

[HenryLach]

Partial fix shipped in v0.30.6 (the minimal / Tier-1 cut described above, live-verified on Penster). This issue stays open for its Tier-2 scope, which is the next design pass together with #627 (held state, durable hold record, typed rulings, takeover state machine, full coverage gate, engine lease/generation).