feat(ratification): gate ratification record, unified completion authority, ruling trailer validation (#627 Stage 2)

CHANGELOG.md

@@ -9,6 +9,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### New
 
+- **Unified `.DONE` completion authority + ruling commit-trailer validation
+  (#627, Stage 2b).** Closes the two remaining gaps in the held-state completion
+  model. (1) A single predicate, `authorizeCompletion()`
+  (`completion-authority.ts`), now decides completion for BOTH the lane-runner's
+  live finalize gate AND resume's `.DONE` acceptance
+  (`collectDoneTaskIdsForResume`): it composes hold authority, blocking review
+  gates (latest REVISE/RETHINK) and linked-APPROVE ratification validity,
+  reporting all blockers. A worker-written `.DONE` left over a blocking gate — or
+  a valid ratification whose worktree carries uncommitted **source** drift — is
+  now refused on resume exactly as it is live (runtime-owned task artifacts
+  remain exempt). (2) Workers may cite a ruling that released a hold ONLY through
+  the structured commit trailer `Taskplane-Ruling: <id>`. After each iteration
+  the runtime enumerates the commits the worker created and validates every
+  citation against the durable hold table: an unknown id, an id whose hold binds
+  another unit, or a prose claim of a ruling with no trailer is **flagged** —
+  logged to STATUS.md (`Ruling citation flagged`), written to the supervisor
+  audit trail (`ruling_citation_flagged`, classification `diagnostic`) and
+  surfaced as one supervisor alert per iteration. A citation flag is a diagnostic
+  only: it never changes task status, releases a hold, counts toward
+  progress/stall, or serves as approval.
+- **Gate ratification record + finalize binding (#627, Stage 2a).** Gives the
+  "delegated closure" pattern a first-class, verifiable artifact. When a review
+  gate hits its revision cap, the supervisor closes it with the new trusted
+  operation — the `ratify_gate` tool (stamps role `supervisor`) or the
+  `/orch-ratify <taskId> <gate> <rulingId> <proofRevision> -- <summary>`
+  operator command (stamps role `operator`) — instead of hand-writing an APPROVE
+  review file. The operation builds a validated `GateRatification` record
+  (`R{NNN}-{gate}.ratification.json`), canonicalizes the proof to an immutable
+  commit id equal to the current worktree HEAD, requires a clean source working
+  tree, writes the next R-numbered APPROVE review with a `Ratification: <id>`
+  link, and audits `gate_ratified`. The finalize gate in the lane-runner now
+  treats an APPROVE that claims a ratification as **blocking** unless the linked
+  record validates (reference, unit/gate scope, authority, proof == HEAD,
+  superseded-review hash) and is not stale — refusing `.DONE` with the new
+  `review_gate_refusal` / `reviewInterventionKind: "invalid-ratification"`
+  alert. An APPROVE with no `Ratification:` link keeps today's behaviour.
 - **First-class `held` state for escalations (#627, Stage 1).** When a worker
   calls `escalate_to_supervisor`, the runtime now holds the unit itself: a
   durable hold record is persisted (strictly — a persist failure blocks, never

docs/reference/commands.md

@@ -214,6 +214,36 @@ does not approve the result; review gates still apply. If the batch is parked
 
 ---
 
+### `/orch-ratify <taskId> <gate> <rulingId> <proofRevision> -- <summary>`
+
+Close a review **gate** that hit its revision cap by writing a validated
+**ratification** as the **operator** (#627 Stage 2a). A ruling releases a held
+lane; a *ratification* is what makes the APPROVE that closes the gate
+trustworthy. This is the only operator path (mirroring `/orch-rule`) that stamps
+role `operator` on a ratification; the supervisor equivalent is the `ratify_gate`
+tool (role `supervisor`). Use it ONLY after ruling on the findings, verifying the
+worker's fold, and confirming the proof commit — never hand-write an APPROVE
+review file, which the runtime cannot trust.
+
+**Syntax**
+
+```text
+/orch-ratify TP-198 code-step3 1788817706765-cd7b6 a1b2c3d -- Findings 1-2 fixed at HEAD; finding 3 ruled out of authority.
+```
+
+- `gate` is the gate key `{type}-step{N}` (e.g. `code-step3`).
+- `rulingId` is the ruling message id that released the lane (from the hold).
+- `proofRevision` MUST be the current worktree HEAD (an immutable sha) with a
+  clean working tree — a symbolic ref, an older commit, or uncommitted source
+  changes are refused.
+
+On success it writes `R{NNN}-{gate}.ratification.json` AND the next R-numbered
+APPROVE review file carrying a `Ratification: <id>` link, and audits
+`gate_ratified`. The finalize gate then trusts that APPROVE only while the record
+validates and is not stale. The worker never writes the APPROVE file itself.
+
+---
+
 ### `/orch-confirm-engine-shutdown [--batch <batchId>] <note>`
 
 Record that the operator verified **no engine process is running** for a batch

docs/specifications/taskplane/held-state-spec.md

@@ -1,6 +1,6 @@
 # Held state and typed rulings — design spec (#627, companion to #626/#628/#630/#631)
 
-Status: **Stage 1 implemented** on `feat/held-state` (design Sage-reviewed 2026-09-07). Stages 2–4 below.
+Status: **Stage 1 implemented**; **Stage 2a (ratification record + finalize binding) implemented** (#627, TP-198); **Stage 2b (`authorizeCompletion()` unification + `Taskplane-Ruling:` trailer validation) implemented** (#627, TP-199). Design Sage-reviewed 2026-09-07. Stages 3–4 below.
 
 ## Problem
 
@@ -117,12 +117,39 @@ interface GateRatification {
 
 A trusted operation validates and persists the record, then writes the next R-numbered APPROVE file
 referencing it; the finalize gate validates reference, scope, authority and proof binding. Later
-blocking reviews or relevant code changes invalidate a stale ratification. One centralized
-`authorizeCompletion()` is called from: pre-spawn completion shortcuts, step-status heuristic, segment
-success and final `.DONE`, monitor and resume completion recognition, merge/recovery eligibility. An
-unauthorized worker-written `.DONE` is quarantined; failure to remove it never makes it authoritative.
-Commits reference rulings via a structured trailer `Taskplane-Ruling: <id>`; unknown/wrong-scope ids
-are logged via `logRecoveryAction()` and are never evidence of approval.
+blocking reviews or relevant code changes invalidate a stale ratification.
+
+**Stage 2a implemented (TP-198).** The record is written to
+`R{NNN}-{gate}.ratification.json` (same `{NNN}` as the APPROVE markdown it
+authorizes, allocated from the global `**Review Counter:**`), and the authorizing
+APPROVE review file carries the exact link line `Ratification: <id>`. The trusted
+operation is the `ratify_gate` supervisor tool (stamps role `supervisor`) and the
+`/orch-ratify` operator command (stamps role `operator`); it canonicalizes the
+proof to an immutable object id equal to the current worktree HEAD, requires a
+clean (source) working tree, and audits `gate_ratified`. The finalize gate
+(`findBlockingReviewGates` in `lane-runner.ts`) treats a linked APPROVE as
+blocking unless the record validates (via `validateRatification`) and is not
+`isRatificationStale`, emitting `review_gate_refusal` with
+`reviewInterventionKind: "invalid-ratification"`. An APPROVE with NO
+`Ratification:` link keeps today's behaviour (not blocking — the full coverage
+gate is #626).
+
+**Stage 2b implemented (TP-199).** `authorizeCompletion()` (`completion-authority.ts`)
+is now the single completion predicate: it composes hold authority
+(`evaluateCompletionAuthority`) → blocking review gates (latest REVISE/RETHINK) →
+linked-APPROVE ratification validity, reporting ALL blockers. The lane-runner's
+finalize path and resume's `.DONE` acceptance (`collectDoneTaskIdsForResume`)
+both call it, so a worker-written `.DONE` over a blocking gate is refused on
+resume exactly as it is live (including the clean-source-tree drift binding when
+the lane worktree exists). An unauthorized worker-written `.DONE` is quarantined;
+failure to remove it never makes it authoritative. Commits reference rulings via
+a structured trailer `Taskplane-Ruling: <id>` (`ruling-trailer.ts`); after each
+iteration the runtime validates every citation against the durable hold table and
+FLAGS unknown ids, wrong-unit ids, and prose ruling claims — logged to STATUS,
+written to the audit trail (`ruling_citation_flagged`, classification
+`diagnostic`) and surfaced to the supervisor as one alert per iteration. A flag
+never changes task status, releases a hold, or counts toward progress/stall, and
+is never evidence of approval.
 
 ## Staging
 
@@ -132,8 +159,15 @@ are logged via `logRecoveryAction()` and are never evidence of approval.
   replacing `pendingEscalation`/`MAX_HOLD_RELAUNCHES`, execution/engine (persistence callback, held
   monitoring, wave accounting, `hold-timeout` pause), resume hold-first + lane-parallel restart,
   extension/supervisor/merge/cleanup/worktree safeguards, dashboard `held`, primer/docs.
-- **Stage 2 — ratification** (#627 remainder, feeds #626): `GateRatification`, trusted ratify
-  operation, finalize-gate binding, `authorizeCompletion()` unification, commit trailer validation.
+- **Stage 2 — ratification** (#627 remainder, feeds #626):
+  - **Stage 2a (DONE, TP-198):** `GateRatification` record + validation + staleness (`ratification.ts`),
+    trusted ratify operation (`ratifyGate` in `ratification-op.ts`; `ratify_gate` tool + `/orch-ratify`
+    command), finalize-gate binding (`invalid-ratification` refusal), record filename
+    `R{NNN}-{gate}.ratification.json` + `Ratification: <id>` link line.
+  - **Stage 2b (DONE, TP-199):** `authorizeCompletion()` unification (`completion-authority.ts`)
+    across the live finalize gate and resume `.DONE` acceptance, commit trailer
+    (`Taskplane-Ruling: <id>`) parsing + validation (`ruling-trailer.ts`) with per-iteration
+    citation flagging (`ruling_citation_flagged` audit + supervisor alert; diagnostic-only).
 - **Stage 3 — #631 lease/generation** (fencing for split-brain; prerequisite for trusting single-writer).
 - **Stage 4 — #628 takeover state machine**, **#626 full coverage gate**.