@1aboveio/skills 0.10.0

package/skills/engineering/resolve-issues/scripts/fix-rounds.mjs

@@ -0,0 +1,3307 @@
+// Contract-complete fix/review state transitions.
+//
+// The functions in this module are pure. Every transition clones the manifest,
+// validates its old state, builds a candidate, validates the complete candidate,
+// and only then returns it. The run-state CLI is therefore unable to persist a
+// state that this module would reject on read-back.
+
+// Deliberate cross-skill import: this skill ships as a sibling of `review-pr`
+// in the symlink-farm distribution model, never standalone. Testing this file
+// from a bare copy (e.g. for mutation testing) needs `review-pr` symlinked
+// beside the copy — see references/sandboxed-testing.md.
+import {
+  stateSpaceCells,
+  validateTheme,
+  CONTRACT_COMPLETE_KINDS,
+} from '../../review-pr/scripts/theme-contract.mjs'
+import {
+  REVIEW_VERDICTS,
+  validateFinding,
+  validateReviewDocument,
+  migrateLegacyFinding,
+  findingWarnings,
+} from '../../review-pr/scripts/finding-contract.mjs'
+import {
+  CHANGED_SURFACES,
+  LEGACY_CHANGED_SURFACE,
+  assertChangedSurfacesMatch,
+  normalizeChangedSurfaces,
+} from './round-metadata.mjs'
+import { terminalDisposition } from './terminal-dispositions.mjs'
+import { completionBlockers, effectiveUnitKind } from './unit-lifecycle.mjs'
+
+export { stateSpaceCells, validateTheme, CONTRACT_COMPLETE_KINDS }
+
+const clone = (value) => structuredClone(value)
+const isObject = (value) => value != null && typeof value === 'object' && !Array.isArray(value)
+const nonEmptyString = (value) => typeof value === 'string' && value.trim().length > 0
+const LOCATOR_RE = /(?:^|\/)\S+:\d+(?:$|\s)|^\S+:\d+$|`[^`]+`|https?:\/\/|#\d+/i
+const isLocator = (value) => nonEmptyString(value) && LOCATOR_RE.test(value)
+const ROUND1_DEPTH_OBLIGATIONS = ['liveEndpointProbing', 'sharedConsumerImpact']
+// The round circuit-breaker (SKILL.md "Round circuit-breaker"). The founding
+// incident is epic-848's unit #848 — nine review rounds without converging, a
+// round-6 PASS reversed by later rounds; it is why the threshold was set to 4
+// then lowered to 3 (distilled record:
+// ../references/incidents/848/README.md). Prose alone did not hold: issue #936
+// then ran seven review rounds over ~6.4 hours with no breaker state ever
+// written, because nothing refused the round-4 transition. It is the ONLY gate
+// that blocks a fix/review transition: a required human decision stops the loop.
+export const BREAKER_ROUND_LIMIT = 3
+export const BREAKER_DECISIONS = ['design', 'split', 'descope', 'continue']
+// `'produce-passes'` is retained here as a READ-ONLY legacy value. A produce-pass
+// circuit-breaker (issue #382) once fired independently of the review-round threshold and
+// stamped `breaker.firedOn: 'produce-passes'` on historical manifests. It was removed: it
+// counted producer/fix spawns AT SPAWN TIME (`record-produce-pass` "in the same turn you
+// spawn it"), so a spawn that died with zero code — no completed review — still advanced
+// the count and could false-fire "the contract keeps changing" before any review ran.
+// That contradicted spawn-contract.md's own rule that a partial counts exactly as a
+// missing one for every gate. Its #376 capability (fire before any review runs) is a
+// deliberately accepted loss. The surviving breaker counts completed review rounds only,
+// so a dead spawn can never inflate it. The value stays accepted so legacy manifests still
+// validate on read-back; the code NEVER writes it — every new firing is `'review-rounds'`.
+export const BREAKER_FIRED_ON = ['review-rounds', 'produce-passes']
+
+// ---- the breaker DIAGNOSIS, mechanized (2026-07-22) ----
+//
+// The breaker always handed the human a diagnosis, and SKILL.md stated the routing rule
+// in prose: "mostly NEW themes each round -> the loop is discovering an unwritten design,
+// recommend the design pass; the SAME theme recurring -> the unit is stuck or mis-sized,
+// recommend split or descope". An audit of 127 run manifests (522 units, 18 that fired,
+// 27 firings) found the recurring-theme branch had NEVER once been taken:
+//
+//   #523  theme `deploy-prod-auto-promote`   in 5 of 5 rounds  -> continue, continue
+//   #400  theme `help-usage-accuracy`        in 3 of 4 rounds  -> continue
+//   #405  theme `condition-c-prose-evidence` in 2 of 5 rounds  -> continue, continue
+//
+// 19 of 27 decisions were `continue`; `descope` was chosen zero times in 522 units and
+// `split` never on a real unit. A rule an agent applies from memory mid-gate is a rule
+// that degrades to its cheapest branch — the same failure class as the `/grill-with-docs`
+// paraphrase and the relative-skillsRoot lookalike. The data to decide it was already in
+// the manifest the whole time (`units[].rounds[].themeIds`), so the diagnosis is a
+// computation, not a judgment, and it belongs in code.
+//
+// The ceiling. With the diagnosis mechanized the decision can also be APPLIED
+// autonomously (see autoBreakerDecision), which removes the human stop that used to bound
+// the loop — so something else must. This is that bound: no auto-decision above it, ever.
+// Observed round counts across the audited units were 1:23  2:14  3:10  4:5  5:3  8:1,
+// so 8 is the observed maximum and a unit reaching it has already spent more rounds than
+// any that ever converged. Past the ceiling the breaker is a hard stop-and-ask again,
+// whatever the diagnosis says — the epic-848 grind (nine rounds, ~6.5 unattended hours)
+// is the failure this number exists to make unreachable.
+export const BREAKER_TOTAL_ROUND_CEILING = 8
+// How many of the recent rounds one theme must dominate before the unit reads as stuck on
+// it rather than working through it. Two consecutive is explicitly NOT enough — SKILL.md
+// keeps that as an input to the diagnosis, not a rung, because the loop cannot tell an
+// implementer circling a blind spot from a reviewer over-blocking. Three is the first
+// count that outruns that ambiguity, and it is what #400/#523 both exhibited.
+export const THEME_RECURRENCE_LIMIT = 3
+// Which decisions the loop may take on its own. The split is by REVERSIBILITY, not by
+// convenience:
+//   `continue` — spends one more bounded round. Cheap, reversible, ceiling-capped.
+//   `design`   — routes to `/grill-with-docs`, which is ITSELF a human interview, and
+//                record-intake-reentry already refuses it unless the contract SHA moved.
+//                Automating the decision does not remove the human; it stops asking
+//                permission to ask them.
+// `descope` is deliberately absent, at every level: it decides that LESS SHIPS than the
+// issue asked for, and a loop that can quietly decide to build less is the one failure
+// that leaves no trace in the handoff — every other autonomous decision shows up as
+// rounds spent, which is visible.
+// `split` is absent from THIS set for a different reason, not the same one: it is
+// auto-decidable, but only where the human pre-authorized it. See
+// AUTONOMOUS_ONLY_AUTO_DECISIONS below for why the reversibility argument reaches a
+// re-slice and not a descope.
+export const AUTO_BREAKER_DECISIONS = ['continue', 'design']
+
+// Auto-decidable only when pre-flight recorded `autonomy: autonomous`. `split` sits here
+// rather than beside continue/design because a supervised run should keep being asked.
+//
+// It moved out of the always-human set on evidence, and the evidence it replaced was
+// stale. breaker.md long claimed `split` was "never chosen on a real unit" from an early
+// audit; measured across 246 live manifests / 602 units the real distribution is
+// **continue 17 · design 6 · split 5 · descope 0** — split is the second most common
+// explicit decision, and epic-848 carries three MORE splits recorded only as blocker prose
+// ("approved implementation split is #936…") that never reached the breaker at all, so the
+// true rate is higher still.
+//
+// Why it is safe in a way `descope` is not: a split re-slices, it does not ship less. It
+// also fires exactly where the loop hurts most — a unit that survived three failing review
+// rounds plus a class-complete mandate carries the largest diff and the longest finding
+// list, so every further round costs the producer and the reviewer their scarcest
+// resource. Splitting is the one remedy that shrinks the per-round load instead of adding
+// to it, which matters more the tighter the implementer's context is.
+//
+// `descope` stays human at every level: zero uses in 602 units, and it is the one decision
+// that genuinely delivers less than was asked. A split that quietly drops a slice IS a
+// descope wearing another label — which is why an auto-split owes a `deferrals[]` entry
+// with a tracking issue for anything not carried forward, and `deferrals` already refuses
+// an untracked one.
+export const AUTONOMOUS_ONLY_AUTO_DECISIONS = ['split']
+
+// The record carries its own authorization. Threading the manifest's autonomy level into
+// per-unit breaker validation would have meant every caller passing it; stamping the level
+// that authorized the decision onto the decision makes the guard self-contained AND makes
+// the handoff able to say why the loop was allowed to take it.
+export function autoDecisionAllowed(decision, autonomyAtDecision) {
+  if (AUTO_BREAKER_DECISIONS.includes(decision)) return true
+  return AUTONOMOUS_ONLY_AUTO_DECISIONS.includes(decision) && autonomyAtDecision === 'autonomous'
+}
+export const BREAKER_AUTONOMY = ['auto', 'ask']
+export const BREAKER_SIGNALS = ['recurring-theme', 'churning-themes', 'converging', 'insufficient-data']
+
+// Themes recorded per round, oldest first, with empty rounds preserved so "this round
+// named no theme" stays distinguishable from "this round did not happen".
+function roundThemes(unit) {
+  const rounds = Array.isArray(unit?.rounds) ? unit.rounds : []
+  return rounds.map((r) => (Array.isArray(r?.themeIds) ? r.themeIds.filter(nonEmptyString) : []))
+}
+
+// The theme that dominates the round log, with the count of rounds naming it. Counts
+// ROUNDS not mentions — a round listing eight themes is one round of evidence about each,
+// and counting mentions would let a single scattergun review outvote a genuine streak.
+function dominantTheme(unit, themesByRound) {
+  const rounds = Array.isArray(unit?.rounds) ? unit.rounds : []
+  const counts = new Map()
+  themesByRound.forEach((themes, i) => {
+    const rn = roundNumber(rounds[i], i)
+    for (const t of new Set(themes)) {
+      if (rn >= themeWindowStart(unit, t)) counts.set(t, (counts.get(t) || 0) + 1)
+    }
+  })
+  let top = null
+  for (const [theme, count] of counts) {
+    // Ties break on the theme id so the diagnosis is deterministic across runs — an
+    // unstable recommendation is one nobody can reproduce from the manifest.
+    if (!top || count > top.count || (count === top.count && theme < top.theme)) top = { theme, count }
+  }
+  return top
+}
+
+// Every class-complete mandate whose authorized round has actually COMPLETED, current and
+// archived alike.
+//
+// "Spent" is the load-bearing word, and both ways of getting it wrong break the remedy in
+// opposite directions. Reading a mandate as spent the moment it is *recorded* flips the
+// diagnosis to `split` before the class-complete round ever runs, so every recurring theme
+// escalates straight to a human — worse than the prose version this replaces. Reading an
+// archived mandate as spent *by construction* is the same error wearing a different hat:
+// a mandate can be archived without its round ever happening (the unit's next producer
+// spawn trips the produce-pass breaker first, and recording that decision archives the
+// still-unspent mandate), after which the theme reads as "already remedied" and escalates
+// early. So neither position in the log decides it — only the round count does.
+function spentMandates(unit) {
+  const all = [...(Array.isArray(unit?.breakerLog) ? unit.breakerLog : []), ...(isObject(unit?.breaker) ? [unit.breaker] : [])]
+  const completed = completedReviewRounds(unit)
+  return all.filter((b) => isObject(b)
+    && nonEmptyString(b.classCompleteFor)
+    && Number.isInteger(b.authorizedThroughRound)
+    && completed >= b.authorizedThroughRound)
+}
+
+function mandateSpentFor(unit, theme) {
+  return spentMandates(unit).some((b) => b.classCompleteFor === theme)
+}
+
+const roundNumber = (entry, index) => (Number.isInteger(entry?.round) ? entry.round : index + 1)
+
+const countRounds = (themesByRound, theme) => themesByRound.filter((t) => t.includes(theme)).length
+
+// Was `theme` raised in round `from` or any round after it? This is how a mandate is
+// judged: the mandated round is the first evidence of whether the class-complete fix held,
+// so it is included, and every later round counts too (a theme that goes quiet for a round
+// and comes back was not closed either).
+function themeRaisedFrom(unit, themesByRound, theme, from) {
+  if (!nonEmptyString(theme) || !Number.isInteger(from)) return false
+  const rounds = Array.isArray(unit?.rounds) ? unit.rounds : []
+  return themesByRound.some((themes, i) => roundNumber(rounds[i], i) >= from && themes.includes(theme))
+}
+
+// The round from which a theme's recurrence is counted: just after its OWN class-complete
+// remedy, or round 1 if it never had one.
+//
+// Per-theme, not per-unit, and that distinction is the whole fix. Counting every theme
+// over the whole log lets a theme's history outlive the fix that closed it; counting every
+// theme from one shared post-mandate cursor does the opposite damage, suppressing the
+// history of themes that were never remedied at all. Both failures showed up under
+// adversarial audit and neither was caught by the tests, whose fixtures happened to have
+// no stale dominant theme:
+//   - A mandate that WORKED still escalates: theme X in rounds 1-3, mandated, round 4 comes
+//     back with only theme Y. Whole-log counting still shows X at 3-of-4 with its mandate
+//     spent, so the loop tells the human "X survived a class-complete round" — false, X was
+//     not raised in the mandated round at all, and the human is sent to split a unit whose
+//     remedy just worked.
+//   - One-shot-per-theme fails: X remedied at round 2, Y recurring in rounds 1-3 and never
+//     remedied. A shared cursor at round 2 hides Y's first round and Y never gets the
+//     class-complete round it is owed.
+// Asking each theme "how often since we last tried to fix YOU" answers both.
+function themeWindowStart(unit, theme) {
+  const own = spentMandates(unit).filter((b) => b.classCompleteFor === theme)
+  return own.length ? Math.max(...own.map((b) => b.authorizedThroughRound)) : 1
+}
+
+// The diagnosis: a pure read of the round log. Returns the signal, the recommended
+// decision, the evidence that produced it, and the VERBATIM text to hand the human (or
+// to record) — verbatim because the one thing the prose version reliably lost was the
+// literal `/grill-with-docs` redirect, and a string in code cannot be paraphrased.
+export function diagnoseBreaker(unit) {
+  const themesByRound = roundThemes(unit)
+  const rounds = themesByRound.length
+  const withThemes = themesByRound.filter((t) => t.length > 0).length
+  const completed = completedReviewRounds(unit)
+  const atCeiling = completed >= BREAKER_TOTAL_ROUND_CEILING
+
+  const base = { rounds, roundsWithThemes: withThemes, completedRounds: completed, atCeiling }
+  const missingMetadata = []
+  for (const [index, round] of (Array.isArray(unit?.rounds) ? unit.rounds : []).entries()) {
+    if (!Array.isArray(round?.themeIds)) missingMetadata.push(`rounds[${index}].themeIds`)
+    if (classifyRoundMetadata(round).changedSurfaces.includes(LEGACY_CHANGED_SURFACE)) {
+      missingMetadata.push(`rounds[${index}].changedSurfaces`)
+    }
+  }
+  if (missingMetadata.length) {
+    return {
+      ...base,
+      signal: 'insufficient-data',
+      recommendation: null,
+      dominantTheme: null,
+      dominantThemeRounds: 0,
+      missingMetadata,
+      text: `The breaker refuses auto-continue because required theme/change metadata is absent (${missingMetadata.join(', ')}). Record the missing round metadata or hand back the unit; reconstruct only from the review/diff evidence.`,
+    }
+  }
+
+  // The log has to be dense enough to carry a verdict. Two ways it is not, and both route
+  // to the human rather than to a guess, because an unfounded auto-decision is worse than
+  // an interrupt:
+  //   - too few themed rounds to see a pattern at all;
+  //   - a log that covers less than half the rounds the unit actually completed, which is
+  //     the shape that let a 2-of-7 sample produce a confident `design`. The round count
+  //     comes from max(reviewHistory, reviewRounds, rounds) — so a unit can genuinely have
+  //     run seven rounds while logging two, and the diagnosis must not mistake the two it
+  //     can see for the seven that happened.
+  const sparse = withThemes < 2 || withThemes * 2 < completed
+  if (sparse) {
+    return {
+      ...base,
+      signal: 'insufficient-data',
+      recommendation: null,
+      dominantTheme: null,
+      dominantThemeRounds: 0,
+      text: `The round log carries themes for ${withThemes} round(s) against ${completed} completed review round(s) — too sparse to say whether this unit is circling one invariant or discovering an unwritten design. Record \`themeIds\` on every round (run-state.mjs record-round) — until then this decision is the human's.`,
+    }
+  }
+
+  // Did a mandated class-complete fix FAIL to close its theme? That is the escalation
+  // trigger, and the test is whether the theme was raised again in the mandated round or
+  // any round after it — not whether it recurs another THEME_RECURRENCE_LIMIT times. The
+  // mandate's whole claim is "this round closes the class"; one reappearance falsifies it,
+  // and waiting for three more would spend the rounds the remedy was supposed to save.
+  // Equally, a theme absent from the mandated round onward was CLOSED by the remedy, and
+  // saying it "survived" on the strength of its pre-mandate history is a false report that
+  // sends the human to split a unit whose fix just worked.
+  const survived = spentMandates(unit).find((b) => themeRaisedFrom(unit, themesByRound, b.classCompleteFor, b.authorizedThroughRound))
+  if (survived) {
+    const theme = survived.classCompleteFor
+    return {
+      ...base,
+      signal: 'recurring-theme',
+      recommendation: 'split',
+      dominantTheme: theme,
+      dominantThemeRounds: countRounds(themesByRound, theme),
+      // The autonomy level is deliberately NOT threaded in (this function takes the unit
+      // and nothing else), so the sentence has to be true at both levels: a split is the
+      // loop's under `autonomous` and yours under `supervised`, a descope is yours always.
+      text: `Theme \`${theme}\` was raised again at or after its mandated class-complete round (round ${survived.authorizedThroughRound}) — the fix that was supposed to close the whole invariant class did not. This is the mis-sized shape, not a fixable one: split the unit at the seam \`${theme}\` names, or descope it. Under \`autonomy: autonomous\` the split is the loop's to take — it re-slices rather than shipping less, and anything it drops owes a tracked \`deferrals[]\` entry; under \`supervised\` it is yours to decide. A descope is yours at every level.`,
+    }
+  }
+
+  const top = dominantTheme(unit, themesByRound)
+  if (top && top.count >= THEME_RECURRENCE_LIMIT && !mandateSpentFor(unit, top.theme)) {
+    // The doctrine's own remedy for a recurring theme is a class-complete fix at full
+    // scope (SKILL.md: "close the invariant class, not the counterexample"). #523 spent
+    // five rounds on one theme and every one of them was an INSTANCE fix — the remedy was
+    // never applied. So apply it once, autonomously, before spending a human on scope.
+    return {
+      ...base,
+      signal: 'recurring-theme',
+      recommendation: 'continue',
+      dominantTheme: top.theme,
+      dominantThemeRounds: top.count,
+      classCompleteFor: top.theme,
+      text: `Theme \`${top.theme}\` has been raised in ${top.count} of the ${rounds} rounds under review — the previous fixes closed the counterexample, not the invariant class. One more round, MANDATED class-complete on that theme: force full scope (withhold lastReviewedSha) and require the fix to name the invariant class it closes and the adjacent members it checked. If \`${top.theme}\` is raised again in that round, the unit is mis-sized and the next firing decides split or descope — the split is the loop's under \`autonomy: autonomous\` and yours under \`supervised\`; a descope is yours at every level.`,
+    }
+  }
+
+  // Mostly-new themes each round: the reviewer keeps finding DIFFERENT contracts to
+  // violate, which is what discovering an unwritten design looks like from outside.
+  // Churn is measured over the window too, and needs at least THEME_RECURRENCE_LIMIT themed
+  // rounds before it can fire. Below that a single scattergun review — one round naming
+  // twenty themes beside one naming a single theme — clears the ratio on its own, and
+  // "twenty findings in one round" is not the same evidence as "a different contract every
+  // round", which is what the design redirect is actually diagnosing.
+  const distinct = new Set(themesByRound.flat()).size
+  const churn = withThemes ? distinct / withThemes : 0
+  if (churn >= 2 && withThemes >= THEME_RECURRENCE_LIMIT) {
+    return {
+      ...base,
+      signal: 'churning-themes',
+      recommendation: 'design',
+      dominantTheme: top ? top.theme : null,
+      dominantThemeRounds: top ? top.count : 0,
+      text: `${distinct} distinct themes across ${withThemes} rounds with no theme repeating ${THEME_RECURRENCE_LIMIT}x — the loop is discovering an unwritten design one invariant per round. Run \`/grill-with-docs\` on ${unit?.id ?? 'this unit'}; the resulting ADR re-enters intake as the design input.`,
+    }
+  }
+
+  return {
+    ...base,
+    signal: 'converging',
+    recommendation: 'continue',
+    dominantTheme: top ? top.theme : null,
+    dominantThemeRounds: top ? top.count : 0,
+    text: `${distinct} distinct themes across ${withThemes} rounds, none recurring ${THEME_RECURRENCE_LIMIT}x — the unit is working through findings rather than circling one. One more round.`,
+  }
+}
+
+// The decision the loop may take on its own, or null when this firing owes a human.
+// Three independent ways to land on the human, each failing CLOSED:
+//   - autonomy is 'ask' (the human opted out of autonomous decisions entirely)
+//   - the diagnosis reached no recommendation, or reached one this run's autonomy level
+//     does not authorize (`autoDecisionAllowed`: a `split` needs `autonomous`, a `descope`
+//     is the human's at every level)
+//   - the unit is at BREAKER_TOTAL_ROUND_CEILING (the grind bound; no diagnosis overrides it)
+export function autoBreakerDecision(unit, { autonomy = 'auto', autonomyLevel = 'supervised' } = {}) {
+  if (autonomy !== 'auto') return null
+  const d = diagnoseBreaker(unit)
+  if (d.atCeiling) return null
+  if (!d.recommendation || !autoDecisionAllowed(d.recommendation, autonomyLevel)) return null
+  return {
+    decision: d.recommendation,
+    diagnosis: d.text,
+    signal: d.signal,
+    autoApplied: true,
+    autonomyAtDecision: autonomyLevel,
+    ...(d.classCompleteFor ? { classCompleteFor: d.classCompleteFor } : {}),
+  }
+}
+
+// Surfaced by `validate`, never thrown: a decision that contradicts the computed
+// diagnosis is a judgment call the human is allowed to make (they can see things the
+// round log cannot), but it must not pass silently — this warning is exactly what would
+// have flagged #523, #400 and #405 while they were still running.
+export function breakerDiagnosisWarnings(unit) {
+  const breaker = isObject(unit?.breaker) ? unit.breaker : null
+  if (!breaker || !nonEmptyString(breaker.decision)) return []
+  const d = diagnoseBreaker(unit)
+  const out = []
+  if (d.recommendation && breaker.decision !== d.recommendation) {
+    out.push(`breaker.decision is "${breaker.decision}" but the round log diagnoses "${d.signal}" and recommends "${d.recommendation}" — ${d.text}`)
+  }
+  if (d.signal === 'recurring-theme' && breaker.decision === 'continue' && !breaker.classCompleteFor) {
+    out.push(`breaker: theme \`${d.dominantTheme}\` recurs in ${d.dominantThemeRounds} of ${d.rounds} rounds and this "continue" mandates no class-complete fix — that is the #523 shape (five rounds, five instance fixes on one invariant); set classCompleteFor to force the class-complete round`)
+  }
+  return out
+}
+
+// ---- delivery: the merge-ready EXIT gate (epic-986) ----
+//
+// `merge-ready` used to be terminal with no transition out of it: every other move in this
+// skill is gated in state and refuses an invalid transition, but merge-ready -> merged had
+// no gate, no counter and nothing refusable, so a unit could sit there forever and the
+// manifest was never wrong. epic-986 recorded mergeShippable: true, targetBranch: main,
+// four units merge-ready with lastVerdict PASS and their PR refs — and mergedSha: null on
+// all four. Authorization present, bar met, PR known, no delivery performed, twelve hours.
+//
+// TWO MODES, and picking the wrong one fails SILENTLY IN BOTH DIRECTIONS — `gh pr merge`
+// on a queue repo bypasses or errors, an enqueue on a direct repo does nothing at all.
+// That silence is the incident. So the mode is settled at pre-flight, recorded on the
+// manifest, and ENFORCED here: an action that does not belong to the run's mode is
+// refused rather than quietly performed against the wrong merge path.
+//   direct — the legacy path: `gh pr merge`, synchronous, one action.
+//   queue  — enqueue, then WATCH to a terminal queue outcome.
+export const DELIVERY_MODES = ['direct', 'queue']
+export const DELIVERY_ACTIONS = { direct: ['merge'], queue: ['enqueue', 'dequeue'] }
+// `requested` (epic-867 / #946): command posted; no ack and not in queue yet.
+// Distinct from `waiting` (ack OR queue membership observed). Without this split,
+// orchestrators either lied about ack on first post or could not record the truth.
+export const DELIVERY_ATTEMPT_OUTCOMES = ['merged', 'dequeued', 'waiting', 'rejected', 'requested']
+
+// ---- the two flows, as DATA ----
+//
+// `deliveryMode` picks the STATE MACHINE (synchronous merge vs enqueue-and-watch).
+// `queueProvider` picks the MECHANICS (how you enqueue, where state is read, whether a
+// nudge or an acknowledgement even exists). Collapsing the second into the first is a
+// real bug and it was already in the prose: delivery.md offered "`@mergifyio queue`, or
+// `gh pr merge --auto`" as if they were two spellings of one action. They are two
+// providers with different state sources, different dequeue vocabularies, and only one
+// of which has a re-evaluation command at all.
+//
+// This table is the mechanization: every validator below reads capabilities from here,
+// so adding a provider is a row rather than a sweep through branching prose.
+export const QUEUE_PROVIDERS = ['mergify', 'github']
+
+export const DELIVERY_FLOWS = {
+  direct: {
+    key: 'direct',
+    mode: 'direct',
+    provider: null,
+    verified: true,
+    actions: ['merge'],
+    // Synchronous: `gh pr merge` returns the result. There is no queue to watch, and an
+    // observation recorded here means the run believes it is in a queue when it is not —
+    // the wrong-mode failure detect-delivery-mode exists to prevent, one layer downstream.
+    watchable: false,
+    supportsAck: false,
+    supportsNudge: false,
+    attemptFields: ['at', 'action', 'headSha', 'outcome', 'reason', 'detail'],
+    ops: {
+      merge: 'gh pr merge <pr> --merge|--squash --delete-branch',
+      readState: null,
+      nudge: null,
+      dequeue: null,
+    },
+  },
+  'queue:mergify': {
+    key: 'queue:mergify',
+    mode: 'queue',
+    provider: 'mergify',
+    verified: true, // exercised live against this skills repo, PR #529, 2026-07-23
+    actions: ['enqueue', 'dequeue'],
+    watchable: true,
+    // The command is a PR comment, so "did anything read it?" is a real question with a
+    // real answer: Mergify reacts 👍 and posts a status comment carrying a machine-readable
+    // payload. No ack means the request never landed — a different state from "the queue is
+    // considering it", and indistinguishable without this.
+    supportsAck: true,
+    supportsNudge: true,
+    // `pr` is accepted as an optional alias/detail for multi-PR components (#946).
+    attemptFields: ['at', 'action', 'headSha', 'outcome', 'reason', 'rawReason', 'detail', 'queueState', 'ack', 'unmetConditions', 'pr'],
+    ops: {
+      merge: null,
+      enqueue: 'gh pr comment <pr> --body "@mergifyio queue"',
+      // `mergify queue show` reports NOTHING during pre-admission ("PR #N is not in the
+      // merge queue" while the PR is genuinely accepted and waiting on conditions), so the
+      // pre-admission state is read from Mergify's own status comment instead — it carries
+      // `-*- Mergify Payload -*-` JSON with `state` plus the rendered condition tree.
+      readState: 'mergify queue show <pr> --json',
+      readPreAdmissionState: 'gh pr view <pr> --json comments --jq \'.comments[] | select(.author.login=="mergify") | .body\'',
+      nudge: 'gh pr comment <pr> --body "@mergifyio refresh"',
+      dequeue: 'gh pr comment <pr> --body "@mergifyio dequeue"',
+    },
+  },
+  'queue:github': {
+    key: 'queue:github',
+    mode: 'queue',
+    provider: 'github',
+    // NOT verified against a live GitHub-native merge queue. The capability flags are the
+    // load-bearing part and they are conservative (no ack, no nudge — GitHub's enqueue is
+    // an API call that succeeds or fails, and it has no re-evaluation command); the `ops`
+    // strings are best-effort and are printed with a warning by `run-state delivery-flow`.
+    verified: false,
+    actions: ['enqueue', 'dequeue'],
+    watchable: true,
+    supportsAck: false,
+    supportsNudge: false,
+    attemptFields: ['at', 'action', 'headSha', 'outcome', 'reason', 'rawReason', 'detail', 'queueState', 'unmetConditions', 'pr'],
+    ops: {
+      merge: null,
+      enqueue: 'gh pr merge <pr> --auto --squash',
+      readState: 'gh api graphql -f query=\'{repository(owner:"<owner>",name:"<repo>"){pullRequest(number:<pr>){mergeQueueEntry{state position}}}}\'',
+      readPreAdmissionState: null,
+      nudge: null,
+      dequeue: 'gh pr merge <pr> --disable-auto',
+    },
+  },
+}
+
+export function deliveryFlowKey(mode, provider) {
+  return mode === 'queue' ? `queue:${provider ?? ''}` : 'direct'
+}
+
+// Resolve the flow for a manifest. Returns null when the flow cannot be determined —
+// a `queue` run with no `queueProvider` is UNKNOWN mechanics, not a default provider,
+// and every provider-specific gate below refuses rather than guessing which one.
+export function deliveryFlow(manifest) {
+  return DELIVERY_FLOWS[deliveryFlowKey(deliveryMode(manifest), deliveryProvider(manifest))] ?? null
+}
+
+export function deliveryProvider(manifest) {
+  const p = manifest?.queueProvider
+  return p === undefined || p === null ? null : p
+}
+// Why a dequeue reason is REQUIRED and read from the queue tool rather than inferred: the
+// reasons route to opposite places. A merge queue tests *PR merged with base* — a tree
+// that never existed at review time and that per-PR CI structurally cannot have covered —
+// so `checks-failed` is new information about code that is about to land and re-enters the
+// loop as a round. The rest are hand-backs. There is deliberately no `batch-bystander`:
+// Mergify's own `bisecting` state resolves a red batch and the innocent PRs carry on, so
+// while the queue bisects the unit is in-flight and the skill simply keeps watching.
+export const DELIVERY_DEQUEUE_REASONS = ['checks-failed', 'conflict', 'conditions-unmet', 'frozen', 'manual', 'pull-request-updated']
+export const DELIVERY_OUTCOMES = ['merged', 'handed-back']
+
+// The canonical reasons above are the ROUTING classes. The queue's own vocabulary is
+// wider than they are — Mergify's `queue-dequeue-reason` type alone carries ~40 values —
+// so demanding one of ours "read from the queue tool, never inferred" was self-
+// contradictory: the tool says `pull-request-updated` and the taxonomy accepted neither
+// that string nor any honest translation of it. So the raw string is kept verbatim in
+// `rawReason` and mapped here, and anything unmapped routes to a HAND-BACK: a reason this
+// table has not seen is not evidence about the code, and guessing is what the raw field
+// exists to stop.
+export const DELIVERY_DEQUEUE_ROUTES = {
+  // The queue tested "PR merged with base" and it failed — a tree per-PR CI structurally
+  // never covered. New information about code about to land ⇒ a round of the loop.
+  'checks-failed': { canonical: 'checks-failed', route: 'fresh-verdict' },
+  // The loop's own push ejected it. HEAD moved, so the last verdict is stale by
+  // guarantee 3 and the unit owes a fresh one before it can be enqueued again.
+  'pull-request-updated': { canonical: 'pull-request-updated', route: 'fresh-verdict' },
+  'draft-pull-request-changed': { canonical: 'pull-request-updated', route: 'fresh-verdict' },
+  // A rebase is an evidence refresh, not a new review.
+  conflict: { canonical: 'conflict', route: 'evidence-lane' },
+  'conflict-with-base-branch': { canonical: 'conflict', route: 'evidence-lane' },
+  // Everything else the queue is telling you about ITSELF or about a human's decision.
+  'conditions-unmet': { canonical: 'conditions-unmet', route: 'hand-back' },
+  frozen: { canonical: 'frozen', route: 'hand-back' },
+  manual: { canonical: 'manual', route: 'hand-back' },
+  'pr-manually-dequeued': { canonical: 'manual', route: 'hand-back' },
+  // A timeout is not evidence the code is broken, and re-enqueueing the same HEAD is
+  // refused anyway — so the honest exit is a hand-back quoting the queue.
+  'checks-timeout': { canonical: 'conditions-unmet', route: 'hand-back' },
+}
+
+export function dequeueRouting(rawReason) {
+  const known = Object.prototype.hasOwnProperty.call(DELIVERY_DEQUEUE_ROUTES, rawReason)
+  if (known) return { ...DELIVERY_DEQUEUE_ROUTES[rawReason], rawReason, known: true }
+  return {
+    canonical: 'manual',
+    route: 'hand-back',
+    rawReason,
+    known: false,
+    note: `"${rawReason}" is not in the routing table — routed to hand-back, which is the fail-closed default; add a row if the queue emits it routinely`,
+  }
+}
+
+// The bound on WATCHING is the one delivery needs, and it is a stall bound rather than
+// a total-elapsed one. A unit can sit in `waiting_for_previous_batches` for a long time
+// while making steady progress, and a flat timeout hands back healthy units; what
+// distinguishes wedged from slow-but-moving is whether the observed (state, position)
+// pair ever changes. epic-986 sat twelve hours on a queue state that never moved once.
+//
+// This number and the two watcher scripts' stall bounds (`watch-delivery.mjs`'s
+// `DEFAULT_BOUND_MINUTES`, the mergify skill's `DEFAULT_STALL_MINUTES`) are ONE doctrine with
+// two implementations: this one bounds an observation recorded into the manifest, they bound
+// the process doing the observing. They must agree, and for a while they did not — this sat at
+// 30 while the watchers moved to 15 and then 10, which made the documented number one nobody
+// ever experienced: the script returns a verdict at its own bound, the orchestrator stops
+// observing, and a 30-minute manifest bound simply never fires on the scripted path. A bound
+// that cannot be reached is not a bound, so the agreement is pinned by test rather than left to
+// whoever edits one of the three next.
+export const DELIVERY_WATCH_BOUND_MINUTES = 10
+// Two queue states are SELF-EXPLAINING blocks: the queue is already telling you what is
+// wrong and no amount of waiting changes it. Waiting out the bound to rediscover
+// "the queue is frozen" is pure latency, so these hand back on first observation.
+// `waiting_schedule` matters most: it can legitimately mean "Monday", and holding a
+// session open until then is never the right answer.
+export const DELIVERY_BLOCKING_QUEUE_STATES = ['frozen', 'waiting_schedule']
+
+// PRE-ADMISSION — the phase the model did not name, and where PR #529 spent its first
+// minutes on 2026-07-23: the enqueue command is acknowledged, every condition is green,
+// and the PR is still not in the queue. `mergify queue show` answers "PR #N is not in the
+// merge queue" and `queue status` answers "Queue is empty", both of which read exactly
+// like "your enqueue never happened". They are different states and the loop must route
+// them differently, so they are named:
+//   waiting-for-queue-conditions  the queue accepted the request and is holding the PR
+//   not-enqueued                  nothing is holding it — the request never landed
+export const DELIVERY_PREADMISSION_STATES = ['waiting-for-queue-conditions', 'not-enqueued']
+export const DELIVERY_KEEP_WATCHING_STATES = [
+  'waiting-for-queue-conditions',
+  'waiting_for_batch', 'preparing', 'running', 'bisecting',
+  'waiting_for_previous_batches', 'waiting_for_merge',
+]
+
+// The nudge: ONE re-evaluation request, and only where the provider has one.
+//
+// PR #529 sat pre-admission with `Mergify Merge Protections` already SUCCESS; a single
+// `@mergifyio refresh` was followed by admission at position 0 within one poll. That is
+// ONE observation and correlation, not proof of causation — which is exactly why this is
+// bounded to a single nudge rather than a retry loop: if the refresh does nothing, the
+// stall bound still fires and the unit still hands back, so the cost of being wrong is
+// one comment. Under the un-nudged rules that PR would have burned the full stall bound
+// and handed back a healthy unit.
+//
+// The nudge fires at 5 minutes against a 10-minute bound, so the window between "nudge is
+// due" and "hand back" is 5 minutes — and because a spent nudge restarts the stall clock, a
+// nudged unit still gets a full bound afterwards. Shortening the bound therefore costs the
+// nudge none of its room; it only shortens how long an UN-nudged wedge stays unnoticed.
+//
+// This is NOT a retry of the merge path (the rule at recordDeliveryAttempt): it attempts
+// nothing, touches no HEAD, and asks the queue to re-read state it already has.
+export const DELIVERY_NUDGE_AFTER_MINUTES = 5
+export const DELIVERY_MAX_NUDGES = 1
+const WORKFLOW_REVIEW_REQUIRED = [
+  'unitId', 'verdict', 'findings', 'overMockFindings', 'previousFindingsResolution',
+  'reviewModel', 'independent', 'contractValidates', 'round1Depth',
+  'headSha', 'reviewSubject', 'authorizationBoundary',
+]
+
+function cellKey(cell) {
+  return `${cell.state}\u0000${cell.taskKind}`
+}
+
+function proofKey(proof) {
+  return `${proof.reviewRound}\u0000${proof.themeId}`
+}
+
+function persistedTheme(theme) {
+  return {
+    themeId: theme.id,
+    kind: theme.kind,
+    contract: theme.contract,
+    ...(theme.stateSpace ? { stateSpace: clone(theme.stateSpace) } : {}),
+  }
+}
+
+function themeFromPersisted(theme) {
+  if (!isObject(theme)) throw new Error('persisted theme must be an object')
+  const unknown = Object.keys(theme).filter((key) => !['themeId', 'kind', 'contract', 'stateSpace'].includes(key))
+  if (unknown.length) throw new Error(`persisted theme has unknown property: ${unknown[0]}`)
+  const out = {
+    id: theme.themeId,
+    kind: theme.kind,
+    contract: theme.contract,
+    ...(theme.stateSpace ? { stateSpace: clone(theme.stateSpace) } : {}),
+  }
+  if (!nonEmptyString(theme.themeId)) throw new Error('persisted theme requires themeId')
+  const errors = validateTheme(out)
+  if (errors.length) throw new Error(errors.join('; '))
+  return out
+}
+
+function themeFingerprint(theme) {
+  return JSON.stringify({
+    id: theme.id,
+    kind: theme.kind,
+    contract: theme.contract,
+    stateSpace: theme.stateSpace || null,
+  })
+}
+
+function themeFromFinding(finding) {
+  const findingErrors = validateFinding(finding)
+  if (findingErrors.length) throw new Error(findingErrors.join('; '))
+  return clone(finding.theme)
+}
+
+function themesInRound(round) {
+  if (Array.isArray(round?.themes) && round?.findings === undefined) return round.themes.map(themeFromPersisted)
+  if (Array.isArray(round?.findings) && round?.themes === undefined) return round.findings.map(themeFromFinding)
+  throw new Error('review round must contain exactly one themes (current) or findings (legacy) array')
+}
+
+function uniqueThemes(themes) {
+  const byId = new Map()
+  for (const theme of themes) {
+    const previous = byId.get(theme.id)
+    if (previous && themeFingerprint(previous) !== themeFingerprint(theme)) {
+      throw new Error(`theme identity ${theme.id} has conflicting contract/state-space definitions in one review round`)
+    }
+    byId.set(theme.id, theme)
+  }
+  return [...byId.values()]
+}
+
+function unitOrThrow(manifest, unitId) {
+  const units = Array.isArray(manifest?.units) ? manifest.units : []
+  const index = units.findIndex((unit) => unit?.id === unitId)
+  if (index === -1) throw new Error(`unknown unit: ${unitId}`)
+  return { units, index }
+}
+
+// The breaker fires on completed review rounds, not on fix rounds: a unit that has
+// absorbed BREAKER_ROUND_LIMIT independent verdicts without exiting is the signal.
+// `continue` authorizes exactly one further round, after which the breaker re-fires;
+// design/split/descope route the unit out of the loop entirely, so they keep blocking
+// until the unit re-enters intake (which clears the decision).
+// Round count must come from BOTH shapes. `reviewHistory` is the opt-in deep-audit
+// layer (run-state.md) — the lean loop records only the `reviewRounds` integer, so a
+// breaker that reads history alone silently never fires on the majority tier, which
+// is the same "gate looks present, does nothing" failure it was built to end.
+export function completedReviewRounds(unit) {
+  const history = Array.isArray(unit?.reviewHistory) ? unit.reviewHistory.length : 0
+  const counter = Number.isInteger(unit?.reviewRounds) && unit.reviewRounds > 0 ? unit.reviewRounds : 0
+  // The round log counts too. It is the lean lane's own record, so a unit that logs
+  // rounds but never bumps reviewRounds must still hit the breaker budget — the same
+  // reason the counter was folded in beside reviewHistory.
+  const log = Array.isArray(unit?.rounds) ? unit.rounds.length : 0
+  return Math.max(history, counter, log)
+}
+
+// ---- the round log: the LEAN record every unit writes ----
+//
+// Distinct from reviewHistory, which is the deep lane's opt-in audit layer and was
+// written by 17 of 394 observed units — none of them the ones that churned. So the
+// two questions the loop most needs answered ("is the same invariant coming back?"
+// and "did this round change any code?") were unanswerable from state, and had to be
+// reconstructed from PR archaeology.
+//
+// That reconstruction does not work. A rebase rewrites commit identity and dates, so
+// old boolean records cannot be split honestly into runtime, tests, harness, evidence,
+// and docs after the fact. New writes classify the actual Git tree delta and persist a
+// closed surface set. Legacy booleans stay readable but project to explicit `unknown`.
+export const ROUND_SCOPES = ['full', 'delta']
+export { CHANGED_SURFACES }
+export const REVIEW_SUBJECTS = ['code', 'evidence']
+// #941 / epic-876: `external-review` is the vera932 shape — independent PASS, then a
+// non-self CHANGES_REQUESTED (or equivalent) that names a real AC gap. It is NOT a
+// note-chase: the production tree moves, and postmortem must not demote it as a
+// probable rebase. Boundary is still `head` because the fix lands as a new head.
+export const REOPEN_REASONS = ['ci-red', 'head-rewritten', 'contract-revised', 'integration-finding', 'external-review']
+export const AUTHORIZATION_BOUNDARY_KINDS = ['head', 'ci', 'contract', 'integration']
+const REOPEN_BOUNDARY_KIND = {
+  'ci-red': 'ci',
+  'head-rewritten': 'head',
+  'contract-revised': 'contract',
+  'integration-finding': 'integration',
+  'external-review': 'head',
+}
+
+// ---- what an evidence round was actually about ----
+export const EVIDENCE_CLASSES = [
+  'stale-locator',
+  'unrun-gate-row',
+  'stale-stamp',
+  'contract-drift',
+  'checklist-row',
+  'other',
+]
+
+export const SCREENED_EVIDENCE_CLASSES = ['stale-locator', 'unrun-gate-row', 'stale-stamp']
+
+// `productionMoved` is read-only compatibility. New writes carry the independent
+// changed-surface and review-subject axes; an old manifest is projected explicitly to
+// unknown rather than guessed into either axis.
+export const ROUND_FIELDS = [
+  'round', 'verdict', 'headSha', 'changedSurfaces', 'reviewSubject', 'themeIds',
+  'scope', 'at', 'evidenceClasses', 'reopenReason', 'authorizationBoundary',
+  'productionMoved',
+]
+
+const hasTypedRoundMetadata = (entry) => isObject(entry) && [
+  'changedSurfaces', 'reviewSubject', 'reopenReason', 'authorizationBoundary',
+].some((field) => Object.prototype.hasOwnProperty.call(entry, field))
+
+export function classifyRoundMetadata(entry) {
+  if (!hasTypedRoundMetadata(entry)) {
+    return {
+      changedSurfaces: [LEGACY_CHANGED_SURFACE],
+      reviewSubject: 'unknown',
+      reopenReason: 'unknown',
+      authorizationBoundary: 'unknown',
+      legacy: true,
+    }
+  }
+  return {
+    changedSurfaces: Array.isArray(entry.changedSurfaces) ? [...entry.changedSurfaces] : [],
+    reviewSubject: entry.reviewSubject,
+    reopenReason: entry.reopenReason ?? null,
+    authorizationBoundary: entry.authorizationBoundary,
+    legacy: false,
+  }
+}
+
+function validateEvidenceClasses(entry, at, errors, { legacy }) {
+  if (entry.evidenceClasses !== undefined) {
+    if (!Array.isArray(entry.evidenceClasses) || !entry.evidenceClasses.length) {
+      errors.push(`${at}.evidenceClasses must be a non-empty array when present`)
+    } else {
+      const bad = entry.evidenceClasses.filter((c) => !EVIDENCE_CLASSES.includes(c))
+      if (bad.length) errors.push(`${at}.evidenceClasses[] must each be one of ${EVIDENCE_CLASSES.join('|')} (got ${JSON.stringify(bad[0])})`)
+    }
+  }
+  if (legacy) {
+    if (entry.evidenceClasses !== undefined && entry.productionMoved === true) {
+      errors.push(`${at} sets evidenceClasses on a legacy round with productionMoved: true — an evidence round is by definition one where production stood still`)
+    }
+    return
+  }
+  if (entry.reviewSubject === 'evidence' && entry.evidenceClasses === undefined) {
+    errors.push(`${at}: reviewSubject "evidence" requires evidenceClasses`)
+  }
+  if (entry.reviewSubject !== 'evidence' && entry.evidenceClasses !== undefined) {
+    errors.push(`${at}.evidenceClasses are legal only when reviewSubject is "evidence"`)
+  }
+}
+
+export function validateRoundLog(unit) {
+  const errors = []
+  if (unit?.rounds === undefined) return errors
+  if (!Array.isArray(unit.rounds)) return ['rounds must be an array']
+  let previous = 0
+  let prior = null
+  let awaitingReopen = false
+  let passBoundaryKnown = false
+  for (const [i, entry] of unit.rounds.entries()) {
+    const at = `rounds[${i}]`
+    if (!isObject(entry)) { errors.push(`${at} must be an object`); continue }
+    const unknown = Object.keys(entry).filter((k) => !ROUND_FIELDS.includes(k))
+    if (unknown.length) errors.push(`${at} has unknown property: ${unknown[0]}`)
+    if (!Number.isInteger(entry.round) || entry.round !== previous + 1) {
+      errors.push(`${at}.round must advance exactly from ${previous} to ${previous + 1}`)
+    } else previous = entry.round
+    if (!REVIEW_VERDICTS.includes(entry.verdict)) errors.push(`${at}.verdict must be one of ${REVIEW_VERDICTS.join('|')}`)
+    if (!nonEmptyString(entry.headSha)) errors.push(`${at}.headSha is required (the SHA the verdict was rendered against)`)
+    if (entry.themeIds !== undefined && (!Array.isArray(entry.themeIds) || !entry.themeIds.every(nonEmptyString))) {
+      errors.push(`${at}.themeIds must be an array of non-empty strings when present`)
+    }
+    if (entry.scope !== undefined && !ROUND_SCOPES.includes(entry.scope)) {
+      errors.push(`${at}.scope must be one of ${ROUND_SCOPES.join('|')}`)
+    }
+    if (entry.at !== undefined && !nonEmptyString(entry.at)) errors.push(`${at}.at must be a non-empty ISO string when present`)
+
+    const legacy = !hasTypedRoundMetadata(entry)
+    if (legacy) {
+      if (typeof entry.productionMoved !== 'boolean') {
+        errors.push(`${at}.productionMoved must be a boolean on a legacy round; its typed classifications read as unknown`)
+      }
+      validateEvidenceClasses(entry, at, errors, { legacy: true })
+      if (awaitingReopen && passBoundaryKnown) {
+        errors.push(`${at}: a legacy round cannot reopen a typed PASS; record typed reopenReason and a changed authorizationBoundary`)
+        awaitingReopen = false
+        passBoundaryKnown = false
+      }
+      if (entry.verdict === 'PASS') {
+        awaitingReopen = true
+        passBoundaryKnown = false
+      }
+      prior = entry
+      continue
+    }
+
+    if (entry.productionMoved !== undefined) {
+      errors.push(`${at}.productionMoved is legacy-only; new rounds use changedSurfaces`)
+    }
+    try { normalizeChangedSurfaces(entry.changedSurfaces) } catch (error) { errors.push(`${at}.${error.message}`) }
+    if (!REVIEW_SUBJECTS.includes(entry.reviewSubject)) {
+      errors.push(`${at}.reviewSubject must be one of ${REVIEW_SUBJECTS.join('|')}`)
+    }
+    if (!Array.isArray(entry.themeIds) || !entry.themeIds.every(nonEmptyString)) {
+      errors.push(`${at}.themeIds is required and must be an array of non-empty strings`)
+    }
+    if (!isObject(entry.authorizationBoundary)) {
+      errors.push(`${at}.authorizationBoundary is required and must be an object`)
+    } else {
+      const boundaryUnknown = Object.keys(entry.authorizationBoundary).filter((key) => !['kind', 'value'].includes(key))
+      if (boundaryUnknown.length) errors.push(`${at}.authorizationBoundary has unknown property: ${boundaryUnknown[0]}`)
+      if (!AUTHORIZATION_BOUNDARY_KINDS.includes(entry.authorizationBoundary.kind)) {
+        errors.push(`${at}.authorizationBoundary.kind must be one of ${AUTHORIZATION_BOUNDARY_KINDS.join('|')}`)
+      }
+      if (!nonEmptyString(entry.authorizationBoundary.value)) {
+        errors.push(`${at}.authorizationBoundary.value must be a non-empty string`)
+      }
+    }
+    validateEvidenceClasses(entry, at, errors, { legacy: false })
+
+    if (awaitingReopen) {
+      if (!isObject(prior?.authorizationBoundary)) {
+        errors.push(`${at}: prior PASS authorizationBoundary is unknown; reconstruct that boundary before reopening`)
+      }
+      if (!REOPEN_REASONS.includes(entry.reopenReason)) {
+        errors.push(`${at}.reopenReason must be one of ${REOPEN_REASONS.join('|')} after a PASS`)
+      } else if (isObject(entry.authorizationBoundary) && entry.authorizationBoundary.kind !== REOPEN_BOUNDARY_KIND[entry.reopenReason]) {
+        errors.push(`${at}.reopenReason ${entry.reopenReason} requires authorizationBoundary.kind ${REOPEN_BOUNDARY_KIND[entry.reopenReason]}`)
+      }
+      if (isObject(prior?.authorizationBoundary) && isObject(entry.authorizationBoundary)
+        && prior.authorizationBoundary.kind === entry.authorizationBoundary.kind
+        && prior.authorizationBoundary.value === entry.authorizationBoundary.value) {
+        errors.push(`${at}.authorizationBoundary must change after a PASS`)
+      }
+      awaitingReopen = false
+      passBoundaryKnown = false
+    } else if (entry.reopenReason !== undefined) {
+      errors.push(`${at}.reopenReason is legal only after a prior PASS`)
+    }
+    if (entry.verdict === 'PASS') {
+      awaitingReopen = true
+      passBoundaryKnown = true
+    }
+    prior = entry
+  }
+  return errors
+}
+
+export function sanitizeRoundEntry(entry) {
+  if (!isObject(entry)) return { entry, dropped: [] }
+  const out = {}
+  const dropped = []
+  for (const [k, v] of Object.entries(entry)) {
+    if (!ROUND_FIELDS.includes(k)) {
+      dropped.push(`${k}: not a round-log field — dropped`)
+      continue
+    }
+    out[k] = v
+  }
+  if (out.scope !== undefined && !ROUND_SCOPES.includes(out.scope)) {
+    dropped.push(`scope: ${JSON.stringify(out.scope)} is not one of ${ROUND_SCOPES.join('|')} — dropped; use reviewSubject: "evidence" with evidenceClasses for an evidence review`)
+    delete out.scope
+  }
+  return { entry: out, dropped }
+}
+
+export function recordRound(manifest, unitId, entry, { at = null, onDrop = null, derivedChangedSurfaces } = {}) {
+  if (!isObject(entry)) throw new Error('round entry must be an object')
+  const typedWrite = hasTypedRoundMetadata(entry) || derivedChangedSurfaces !== undefined
+  let candidateEntry = entry
+  if (typedWrite) {
+    if (derivedChangedSurfaces === undefined) {
+      throw new Error('record-round requires diff-derived changedSurfaces; callers may override only when validated against that diff')
+    }
+    const changedSurfaces = entry.changedSurfaces === undefined
+      ? normalizeChangedSurfaces(derivedChangedSurfaces)
+      : assertChangedSurfacesMatch(entry.changedSurfaces, derivedChangedSurfaces)
+    candidateEntry = { ...entry, changedSurfaces }
+  }
+  const { entry: clean, dropped } = sanitizeRoundEntry(candidateEntry)
+  if (dropped.length && typeof onDrop === 'function') onDrop(dropped)
+  const out = clone(manifest)
+  const { units, index } = unitOrThrow(out, unitId)
+  const unit = units[index]
+  unit.rounds = Array.isArray(unit.rounds) ? unit.rounds : []
+  const expected = (unit.rounds.at(-1)?.round || 0) + 1
+  const candidate = { ...clean, round: clean.round === undefined ? expected : clean.round, ...(at ? { at } : {}) }
+  const errors = validateRoundLog({ rounds: [...unit.rounds, candidate] })
+  if (errors.length) throw new Error(errors[0])
+  unit.rounds.push(candidate)
+  return out
+}
+
+// A round whose HEAD matches the one before it reviewed code that did not move. That is
+// sometimes exactly right (a flaky gate held the previous verdict; a forced full-scope
+// re-review after a contract revision landed) and sometimes a round the loop bought for
+// nothing — the "no code delta" incident in SKILL.md step 3. Which one it is depends on
+// facts the log does not hold, so this reports rather than refuses: it is the signal the
+// loop-tuning pass reads, not a gate. The repeated SHA says the reviewed HEAD stood still;
+// `reviewSubject` separately says whether the reviewer assessed code or evidence.
+// Compared by common prefix: the same commit recorded short in one round and full in
+// the next is the same HEAD, and a warning nobody sees is worth nothing. One definition,
+// because `evidenceAudit` below asks the same question and two spellings would drift.
+function sameHead(a, b) {
+  if (!nonEmptyString(a) || !nonEmptyString(b)) return false
+  return a.startsWith(b) || b.startsWith(a)
+}
+
+// A PASS is terminal (SKILL.md step 3). A round logged AFTER one is therefore either a
+// carve-out — the diff moved: CI came back red on that head, the head was rewritten, a
+// contract revision landed — or the failure this exists to name: an orchestrator spending
+// rounds on findings the reviewer declined to block on, which has no stopping rule.
+//
+// The log DOES prove whether the head moved (#760): `headSha` is recorded on every round,
+// so a round whose head differs from the one right before it proves the diff moved. What it
+// does NOT prove is WHY — a genuine rebase and the failure this finding exists to name both
+// move the head the same way, because closing a finding the reviewer itself classed
+// non-blocking means a new commit too (see why.md's epic-563 measurement: one of #572's two
+// extra cycles was a rebase, the other was exactly that, and both moved the SHA). So a moved
+// head is not an automatic carve-out — it is reported, demoted below the rounds the log truly
+// cannot explain, and labelled a probable rebase for a human to confirm from the round's own
+// notes. A round on an UNMOVED head is the opposite case: the log rules OUT "it was a
+// rebase", which leaves only a held verdict, a contract revision with no diff of its own, or
+// the failure this finding exists to name — and those three still look identical without a
+// human reading the round's own notes. So this classifies rather than refuses — every round
+// after the pass is returned, each tagged with whether its head moved relative to the round
+// before it — and leaves the caller to decide what to do with each class. `findRoundsAfterPass`
+// in postmortem.mjs is that caller: it ranks the rounds the log cannot explain any other way
+// first, and still reports the moved-head ones, demoted, rather than deleting them from the
+// signal. Named on the round that FOLLOWS the pass, because that is the one whose existence
+// has to be justified.
+export function roundsAfterPass(unit) {
+  const rounds = Array.isArray(unit?.rounds) ? unit.rounds : []
+  // PASS only, matching the recorded enum. `APPROVE` is the GitHub review EVENT the verdict
+  // is posted as; the round log refuses it as a verdict, so accepting it here would be a
+  // branch that can never run and a reader's false impression that both spellings occur.
+  const firstPass = rounds.findIndex((r) => r?.verdict === 'PASS')
+  if (firstPass < 0) return []
+  return rounds.slice(firstPass + 1).map((entry, k) => {
+    const index = firstPass + 1 + k
+    const prior = rounds[index - 1]
+    const headKnown = nonEmptyString(entry?.headSha) && nonEmptyString(prior?.headSha)
+    // true: the log proves the head moved — probably a rebase, but the log cannot prove
+    // that's WHY (a fix round closing non-blocking notes moves the head too). Reported,
+    // demoted, and labelled a probable rebase rather than dropped.
+    // false: the log proves the head did NOT move (the residue — ranked first, undemoted).
+    // null: headSha is missing on one side, so the log cannot tell — falls back to
+    // reporting it (AC5) rather than silently suppressing it.
+    const headMoved = headKnown ? !sameHead(entry.headSha, prior.headSha) : null
+    // `priorAt` is carried for a consumer's benefit, not this module's: it is the one piece
+    // a per-round cost figure over the REPORTED rounds needs and the manifest alone does
+    // not hand a caller without re-deriving this same index walk.
+    return { ...entry, index, passedAt: rounds[firstPass], priorAt: prior?.at ?? null, headMoved }
+  })
+}
+
+// One warning per ROUND, never one per rule that matched it (#768).
+//
+// Two of the rules below overlap exactly: a round on a proven-unmoved head after a PASS
+// satisfies the same-HEAD rule and the rounds-after-pass rule at once, and used to emit a
+// line for each. Nothing counted warnings, so it cost nothing — but the count is the obvious
+// thing for a future consumer to read, and a rule-shaped count answers "how many rules fired"
+// when every caller means "how many rounds are questionable". That is a miscount waiting for
+// its first reader, so the emit side is the place to settle it: `warnings.length` is now the
+// number of rounds with something to answer for.
+//
+// Deduped by MERGING, not by dropping a rule. The two rules genuinely say different things —
+// one names the repeated HEAD and the SHA, the other names the terminal PASS and the
+// carve-outs owed — and a reader losing either would be worse off than reading both twice.
+// The overlap is exact and provable rather than heuristic: `headMoved === false` is computed
+// as `!sameHead(entry.headSha, prior.headSha)` over the same adjacent pair the same-HEAD rule
+// compares, so those indices are precisely the ones both rules claim. `headMoved === null`
+// cannot overlap — it means a headSha was missing, and `sameHead` already answers false for
+// that — so the missing-SHA branch keeps its own wording untouched.
+export function roundLogWarnings(unit) {
+  const rounds = Array.isArray(unit?.rounds) ? unit.rounds : []
+  const after = roundsAfterPass(unit)
+  // The exact indices the same-HEAD rule would restate: proven-unmoved rounds after the pass.
+  // Their merged line is emitted below, in the rounds-after-pass group.
+  const mergedIntoAfterPass = new Set(after.filter((entry) => entry.headMoved === false).map((entry) => entry.index))
+  const sameHeadWarnings = rounds.flatMap((entry, i) => {
+    const prior = rounds[i - 1]
+    if (!prior || !sameHead(entry?.headSha, prior.headSha)) return []
+    if (mergedIntoAfterPass.has(i)) return []
+    return [`rounds[${i}]: round ${entry.round} re-reviewed ${entry.headSha}, the same HEAD as round ${prior.round} — confirm it was worth buying (a held verdict or a landed contract revision) rather than a round spent on unmoved code`]
+  })
+  // Head-aware here too (#760's class fix, not just the post-mortem's instance of it) — but
+  // head-aware means DEMOTED, not dropped: the log proves WHETHER a round's head moved, never
+  // WHY, since a genuine rebase and a fix round that closes findings the reviewer itself
+  // called non-blocking both produce a new commit (why.md's epic-563 measurement: #572 had
+  // exactly one of each). A moved head is therefore still named here — ranked after the
+  // rounds the log cannot explain any other way, and worded as a probable rebase rather than
+  // an unjustified round.
+  const unmovedOrUnknown = after.filter((entry) => entry.headMoved !== true).map((entry) => {
+    // The proven-unmoved branch carries the same-HEAD rule's content too (#768): its SHA, the
+    // round it repeats, and "a held verdict" as a carve-out — the one item that rule named and
+    // this one did not. Merged rather than emitted twice, so the line count stays one-per-round.
+    const owed = entry.headMoved === null
+      ? 'one of the three carve-outs (red CI on that head, a rewritten head, a landed contract revision) — headSha is missing on one side, so the log cannot tell which'
+      : 'one of the carve-outs still reachable from an unmoved head (red CI on that head, a held verdict, or a landed contract revision with no diff of its own) — the log proves this head was NOT rewritten'
+    const repeated = entry.headMoved === false
+      ? ` (it re-reviewed ${entry.headSha}, the same HEAD as the round before it, so no commit landed in between)`
+      : ''
+    return `rounds[${entry.index}]: round ${entry.round} was bought AFTER round ${entry.passedAt.round} already returned ${entry.passedAt.verdict}${repeated} — a PASS is terminal, so this round owes ${owed}. None of them is "the notes inside the PASS were worth closing": those are deferrals[] with tracking issues, not rounds`
+  })
+  const movedHead = after.filter((entry) => entry.headMoved === true).map((entry) => (
+    `rounds[${entry.index}]: round ${entry.round} was bought AFTER round ${entry.passedAt.round} already returned ${entry.passedAt.verdict} — a PASS is terminal, and this round's head moved from the one before it, so it is probably a rebase (legitimate: the tree moved, the delta is genuinely unreviewed) — but the log cannot rule out a fix round that closed findings the reviewer itself called non-blocking, since that also produces a new commit. Confirm which in the round's own notes`
+  ))
+  return [...sameHeadWarnings, ...unmovedOrUnknown, ...movedHead]
+}
+
+// ---- the evidence audit: which screen is missing, or which one was skipped ----
+//
+// This is the consumer that makes `evidenceClasses` worth writing. `delivery` was
+// fully mechanized, documented, and written 0 of 522 times because nothing read
+// it; the distinguishing property of a field that gets written has never been
+// mechanization, it is whether a later gate reads the value. This is that gate.
+//
+// It answers one question the handoff could not: of the rounds this run spent on
+// claims rather than code, which class recurred — and is the repair to run an
+// existing screen or to build a missing one.
+//
+// One correction the count owes the reader, added 2026-08-04. `productionMoved: false`
+// is recorded by hand, and the loop was observed reading it as "did THIS record change
+// code" rather than "has production moved since the last round". In
+// `epic-25-proposal-generator` that produced a round per loop *action* — the fix at head
+// H marked `true`, then its review at the same head H marked `false` — and 7 of 13
+// rounds landed in the evidence bucket with no class on any of them. `validate` already
+// flags every one of those (`roundLogWarnings`: same HEAD as the round before), but that
+// warning never reaches the place the evidence *number* is read, so the headline said
+// this run spent 54% of its rounds on claims when what it did was double-record.
+//
+// So the audit reports the overlap rather than guessing. It does NOT exclude these
+// rounds: a terminal review at an unmoved head is a real round with `productionMoved:
+// false` (identity #561's round 8 is one), and silently dropping them would trade an
+// overstatement for an undercount. Naming the overlap lets a reader take the headline
+// at the right strength, and gives a recurring double-record its own repair — which is
+// neither "run the screen" nor "build the screen" but "fix the recording".
+export function evidenceAudit(units) {
+  const list = Array.isArray(units) ? units : [units].filter(Boolean)
+  const counts = new Map()
+  let evidenceRounds = 0
+  let totalRounds = 0
+  let unclassified = 0
+  let unknownClassifications = 0
+  let sameHeadAsPrevious = 0
+  // epic-867 / #948: clean first-pass PASS (single PASS, no prior NEEDS_CHANGES on the
+  // unit) is not an evidence-lane round. Counting it as one trained orchestrators to stuff
+  // fake evidenceClasses or ignore the warn. A true evidence round is still either a
+  // typed reviewSubject:"evidence" or a legacy productionMoved:false that is not that
+  // first-pass happy path.
+  for (const unit of list) {
+    const rounds = (Array.isArray(unit?.rounds) ? unit.rounds : []).filter(isObject)
+    const hasPriorNeedsChanges = rounds.some((r) => r?.verdict === 'NEEDS_CHANGES')
+    for (const [i, entry] of rounds.entries()) {
+      totalRounds += 1
+      const metadata = classifyRoundMetadata(entry)
+      const cleanFirstPass = !hasPriorNeedsChanges
+        && entry.verdict === 'PASS'
+        && rounds.filter((r) => r?.verdict === 'PASS').length === 1
+      const evidenceRound = metadata.legacy
+        ? (entry.productionMoved === false && !cleanFirstPass)
+        : metadata.reviewSubject === 'evidence'
+      if (!evidenceRound) continue
+      evidenceRounds += 1
+      if (metadata.legacy) unknownClassifications += 1
+      // No commit landed between this round and the one before it, so nothing was
+      // fixed in between — not even the evidence-only commit a real lane round makes.
+      if (i > 0 && sameHead(entry.headSha, rounds[i - 1].headSha)) sameHeadAsPrevious += 1
+      // Deduped per round because the field is counted in ROUNDS, and the finding
+      // threshold is "this recurred". A class listed twice in one round would cross
+      // that threshold on its own — inventing a recurrence out of a single round,
+      // which is precisely the wrong signal to hand someone deciding whether to
+      // build a new gate. Deduped at READ rather than refused at write: this is a
+      // compatibility read. Typed writes reject duplicates and incomplete metadata;
+      // legacy records remain readable so the audit can report what is unknown.
+      const classes = [...new Set(Array.isArray(entry.evidenceClasses) ? entry.evidenceClasses : [])]
+      if (!classes.length) { unclassified += 1; continue }
+      for (const c of classes) {
+        const seen = counts.get(c) || { evidenceClass: c, rounds: 0, units: new Set(), screened: SCREENED_EVIDENCE_CLASSES.includes(c) }
+        seen.rounds += 1
+        if (unit?.id) seen.units.add(unit.id)
+        counts.set(c, seen)
+      }
+    }
+  }
+  const classes = [...counts.values()]
+    .map((c) => ({ evidenceClass: c.evidenceClass, rounds: c.rounds, units: [...c.units].sort(), screened: c.screened }))
+    .sort((a, b) => b.rounds - a.rounds || a.evidenceClass.localeCompare(b.evidenceClass))
+  const findings = []
+  for (const c of classes) {
+    if (c.rounds < 2) continue
+    findings.push(c.screened
+      ? { evidenceClass: c.evidenceClass, rounds: c.rounds, repair: 'run-the-screen', detail: `${c.evidenceClass} cost ${c.rounds} rounds, and a screen already decides it — the screen was skipped or run without the flag that makes it resolve (coverage-checklist validate needs --diff; evidence-block validate is owed on the terminal round). Fix the call, do not add a gate.` }
+      : { evidenceClass: c.evidenceClass, rounds: c.rounds, repair: 'build-the-screen', detail: `${c.evidenceClass} cost ${c.rounds} rounds and nothing mechanized decides it — this is the reviewer catching what no screen can. A candidate for a new check, with these rounds as its named incident.` })
+  }
+  // Recurrence threshold matched to the class findings above: two is the point at
+  // which "the loop does this" beats "this happened once". Reported as a finding
+  // rather than folded into the count, because the repair is a recording habit and
+  // no screen — existing or new — would ever catch it.
+  if (sameHeadAsPrevious >= 2) {
+    findings.push({
+      evidenceClass: null,
+      rounds: sameHeadAsPrevious,
+      repair: 'fix-the-recording',
+      detail: `${sameHeadAsPrevious} of ${evidenceRounds} evidence round(s) sat at the same HEAD as the round before, so no commit landed between them — not even the evidence-only commit a real lane round makes. Read the headline as ${evidenceRounds - sameHeadAsPrevious} evidence round(s) plus ${sameHeadAsPrevious} double-record(s). The usual cause is recording one round per loop ACTION (the fix, then its review, at one head) instead of one per review verdict. run-state.mjs validate names each one.`,
+    })
+  }
+  // Not a finding, but the number that says whether the audit itself is trustworthy:
+  // an unclassified evidence round is one nobody can learn anything from.
+  return { totalRounds, evidenceRounds, unclassified, unknownClassifications, sameHeadAsPrevious, classes, findings }
+}
+
+// The review-round breaker, unchanged. Its return shape is load-bearing (callers and
+// tests deepEqual it), so firedOn is NOT added here — it belongs on the persisted
+// breaker object, written by record-breaker-decision.
+function pendingReviewBreaker(unit) {
+  const completedRounds = completedReviewRounds(unit)
+  const breaker = isObject(unit?.breaker) ? unit.breaker : null
+  if (!breaker) {
+    return completedRounds >= BREAKER_ROUND_LIMIT ? { completedRounds, reason: 'no-breaker-decision' } : null
+  }
+  if (breaker.decision === 'continue') {
+    return completedRounds >= breaker.authorizedThroughRound
+      ? { completedRounds, reason: 'continue-authorization-exhausted', authorizedThroughRound: breaker.authorizedThroughRound }
+      : null
+  }
+  // design/split/descope keep blocking every transition until the unit actually
+  // re-enters intake — regardless of which threshold fired, since one breaker object and
+  // one decision cover both. firedOn on the object records which shape the human faced.
+  if (!breaker.reenteredAt) {
+    return { completedRounds, decision: breaker.decision, reason: `breaker-decision-${breaker.decision}` }
+  }
+  // Re-entry grants a fresh budget measured from where the breaker fired — the
+  // history is evidence and is never rewritten, so the count has to be relative.
+  return completedRounds - breaker.firedAtRound >= BREAKER_ROUND_LIMIT
+    ? { completedRounds, reason: 'no-breaker-decision' }
+    : null
+}
+
+// The breaker fires on completed review rounds only. (A produce-pass threshold once fired
+// here too, counting producer/fix spawns at spawn time; it was removed because a spawn
+// that died with zero code still advanced it — see BREAKER_FIRED_ON.)
+export function pendingBreaker(unit) {
+  return pendingReviewBreaker(unit)
+}
+
+function throwForPendingBreaker(pending, unit, transition) {
+  if (pending.reason === 'no-breaker-decision') {
+    throw new Error(`${transition} blocked: ${pending.completedRounds} review rounds completed on ${unit.id} — the round circuit-breaker requires a recorded decision before round ${pending.completedRounds + 1} — run diagnose-breaker and, when it exits 0, record-breaker-decision --auto; exit 1 means this firing owes the human an answer`)
+  }
+  if (pending.reason === 'continue-authorization-exhausted') {
+    throw new Error(`${transition} blocked: "continue" authorized rounds through ${pending.authorizedThroughRound} and ${pending.completedRounds} are complete — the breaker re-fires; record a fresh decision`)
+  }
+  throw new Error(`${transition} blocked: the breaker decision "${pending.decision}" routes ${unit.id} out of the loop; no fix or review transition may run until the unit re-enters intake`)
+}
+
+// Gates a fix transition (record-fix-round — the transition that spends another pass).
+// The review-round breaker blocks it: a firing refuses every fix/review transition until
+// a decision is recorded.
+function assertNoPendingBreaker(unit, transition) {
+  const pending = pendingBreaker(unit)
+  if (pending) throwForPendingBreaker(pending, unit, transition)
+}
+
+// Gates the review-verdict recorder (record-review-round). The review-round breaker gates
+// it: once BREAKER_ROUND_LIMIT completed rounds have no PASS, no further review round
+// records until a decision is taken. (record-round, the lean review recorder, stays
+// ungated — the budget binds it via read-back validation.)
+function assertNoPendingReviewBreaker(unit, transition) {
+  const pending = pendingReviewBreaker(unit)
+  if (pending) throwForPendingBreaker(pending, unit, transition)
+}
+
+// How many rounds the unit is currently allowed to have completed. Reaching the
+// budget is a legal state — it is exactly where the breaker fires and the human is
+// asked. Recording a round BEYOND it is the violation.
+export function breakerAuthorizedRounds(unit) {
+  const breaker = isObject(unit?.breaker) ? unit.breaker : null
+  if (!breaker) return BREAKER_ROUND_LIMIT
+  if (breaker.decision === 'continue') return breaker.authorizedThroughRound
+  if (!breaker.reenteredAt) return breaker.firedAtRound
+  return breaker.firedAtRound + BREAKER_ROUND_LIMIT
+}
+
+// A lean-lane unit never calls record-fix-round/record-review-round — it advances
+// through `upsert-unit`, so the transition gates have no code path to sit on for the
+// majority tier and the budget is enforced on the state itself: an in-progress unit
+// past the budget with no decision is invalid.
+//
+// Statuses that genuinely owe no decision: the breaker's job is to stop further
+// rounds, and a unit that already stopped does not owe one to record that it stopped.
+// `merge-ready` is deliberately NOT among them. It is an *exit*, not a stop, and
+// exempting every non-in-progress status let an over-budget unit reach that exit
+// without the breaker ever being answered — the one transition the budget most needs
+// to bind. What this buys is precise and worth stating honestly: it does not make the
+// rounds un-bankable (a decision recorded late still sets `firedAtRound` to the rounds
+// already completed), it forces the diagnosis to be written down before a unit can
+// claim success. `queued` is likewise checked: a unit sent back through intake gets a
+// fresh budget from `reenteredAt`, so a legitimate re-entry still passes — verified
+// against both orderings of the status write and the re-entry record — while rounds
+// banked on a unit that never re-entered do not.
+const BUDGET_EXEMPT_STATUSES = ['blocked', 'skipped-already-done']
+
+function validateBreakerBudget(unit) {
+  if (terminalDisposition(unit) !== null) return []
+  const completedRounds = completedReviewRounds(unit)
+  const authorized = breakerAuthorizedRounds(unit)
+  if (!Number.isInteger(authorized) || completedRounds <= authorized) return []
+  return [`${completedRounds} review rounds recorded but only ${authorized} authorized — the round circuit-breaker requires a recorded decision (record-breaker-decision, or --auto) before the budget is exceeded`]
+}
+
+// BACK-COMPAT: a historical `units[].producePasses` field (the removed produce-pass
+// breaker's counter, issue #382) is deliberately NOT validated — it is ignored on
+// read-back so legacy manifests still validate. No live code reads or writes it.
+
+// Guarantee 3 in state: a unit exits on a fresh passing verdict, never on a claim.
+// The budget check above cannot cover this — it counts rounds, and a stuck unit's
+// round count is legal. A unit that has absorbed the full budget and is still red
+// sits at exactly BREAKER_ROUND_LIMIT (the transition gates refuse round 4), which
+// is inside the budget, so "3 rounds, last verdict NEEDS_CHANGES, status
+// merge-ready" validated clean. Verdict is the discriminator the round count isn't:
+// passing on round 3 is the ordinary happy path and must stay valid, while claiming
+// the exit on a blocking verdict is false at any round count.
+//
+// Fail-closed on the verdict itself, not just on the blocking values: an earlier
+// version only rejected `NEEDS_CHANGES`/`FAIL`/`BLOCKED`, so `merge-ready` with
+// `lastVerdict` missing entirely validated clean — a unit could claim the exit
+// having never recorded a verdict at all, which is exactly the claim-not-verdict
+// exit guarantee 3 exists to refuse. `PASS` is the only value REVIEW_VERDICTS
+// treats as non-blocking, so it is the only value this check accepts (#388 audit).
+function validateTerminalVerdict(unit) {
+  if (unit?.status !== 'merge-ready') return []
+  if (unit?.lastVerdict === 'PASS') return []
+  return [`status is merge-ready but lastVerdict is ${unit?.lastVerdict === undefined ? 'unset' : unit.lastVerdict} — a unit exits on a fresh passing verdict against its current HEAD, never on a claim (guarantee 3); include "lastVerdict":"PASS" in this same write once a fresh independent review actually returned PASS on this unit's HEAD — never write merge-ready ahead of that verdict`]
+}
+
+function validateBreakerObject(breaker, label) {
+  if (!isObject(breaker)) return [`${label} must be an object`]
+  const errors = Object.keys(breaker)
+    .filter((key) => !['firedAtRound', 'firedOn', 'decision', 'diagnosis', 'decidedAt', 'authorizedThroughRound', 'reenteredAt', 'contractShaAtDecision', 'autoApplied', 'signal', 'classCompleteFor', 'autonomyAtDecision'].includes(key))
+    .map((key) => `${label} has unknown property: ${key}`)
+  // Who decided. Absent reads as false (every manifest written before 2026-07-22 was a
+  // human decision), so the handoff can separate "the loop decided this" from "you did"
+  // without a migration.
+  if (breaker.autoApplied !== undefined && typeof breaker.autoApplied !== 'boolean') {
+    errors.push(`${label}.autoApplied must be a boolean`)
+  }
+  if (breaker.signal !== undefined && !BREAKER_SIGNALS.includes(breaker.signal)) {
+    errors.push(`${label}.signal must be one of ${BREAKER_SIGNALS.join('|')}`)
+  }
+  // The theme this firing mandated a class-complete fix for. It is the ONE-SHOT marker:
+  // diagnoseBreaker reads it back to tell "recurring theme, remedy not yet tried" from
+  // "recurring theme, remedy already spent" — the second of which routes to a human.
+  if (breaker.classCompleteFor !== undefined && !nonEmptyString(breaker.classCompleteFor)) {
+    errors.push(`${label}.classCompleteFor must be a non-empty theme id`)
+  }
+  if (breaker.classCompleteFor !== undefined && breaker.decision !== 'continue') {
+    errors.push(`${label}.classCompleteFor applies only to a "continue" decision — it mandates how the authorized round is spent`)
+  }
+  // An autonomous decision may only ever be one of the reversible ones. This is the
+  // scope guard in state: even a caller that hand-writes the manifest cannot record the
+  // loop having decided to split or descope a unit on its own.
+  if (breaker.autoApplied === true && !autoDecisionAllowed(breaker.decision, breaker.autonomyAtDecision)) {
+    errors.push(`${label}.decision "${breaker.decision}" cannot be autoApplied${breaker.decision === 'split' ? ' without `autonomyAtDecision: "autonomous"` recorded on the same breaker entry' : ''} — ${AUTO_BREAKER_DECISIONS.join('/')} are always the loop's, ${AUTONOMOUS_ONLY_AUTO_DECISIONS.join('/')} only under autonomy "autonomous"; descope delivers less than was asked and stays the human's call at every level`)
+  }
+  // The unit's contract pointer AT FIRE TIME, so a later re-entry can prove the design
+  // input actually moved. `null` records "no contract pointer when this fired" — a real
+  // state, and distinct from a legacy manifest written before this field existed (absent,
+  // read as null by recordIntakeReentry).
+  if (breaker.contractShaAtDecision !== undefined && breaker.contractShaAtDecision !== null && !nonEmptyString(breaker.contractShaAtDecision)) {
+    errors.push(`${label}.contractShaAtDecision must be a non-empty sha or null`)
+  }
+  // firedOn is optional (a manifest written before #382 has none — it reads back as a
+  // review-rounds firing) but must be a known value when present.
+  if (breaker.firedOn !== undefined && !BREAKER_FIRED_ON.includes(breaker.firedOn)) {
+    errors.push(`${label}.firedOn must be one of ${BREAKER_FIRED_ON.join('|')}`)
+  }
+  // BACK-COMPAT: a legacy `firedOn: 'produce-passes'` firing could happen with zero
+  // completed reviews (the #376 shape), so firedAtRound was allowed to be 0 there. Kept so
+  // those manifests still read back; new firings are always review-rounds, floor 1.
+  const firedAtRoundFloor = breaker.firedOn === 'produce-passes' ? 0 : 1
+  if (!Number.isInteger(breaker.firedAtRound) || breaker.firedAtRound < firedAtRoundFloor) {
+    errors.push(`${label}.firedAtRound must be a ${firedAtRoundFloor === 0 ? 'non-negative' : 'positive'} integer`)
+  }
+  if (!BREAKER_DECISIONS.includes(breaker.decision)) errors.push(`${label}.decision must be one of ${BREAKER_DECISIONS.join('|')}`)
+  // The breaker's whole purpose is that the ask leads with a diagnosis, never a
+  // neutral menu (SKILL.md); an undiagnosed decision is the failure it guards.
+  if (!nonEmptyString(breaker.diagnosis)) errors.push(`${label}.diagnosis is required — the breaker hands a diagnosis, not a menu`)
+  if (!nonEmptyString(breaker.decidedAt)) errors.push(`${label}.decidedAt is required`)
+  if (breaker.decision === 'continue') {
+    if (breaker.authorizedThroughRound !== breaker.firedAtRound + 1) {
+      errors.push(`${label}.authorizedThroughRound must be firedAtRound + 1 — "continue" authorizes exactly one more round`)
+    }
+    if (breaker.reenteredAt !== undefined) errors.push(`${label}.reenteredAt applies only to a design/split/descope decision`)
+  } else {
+    if (breaker.authorizedThroughRound !== undefined) errors.push(`${label}.authorizedThroughRound applies only to a "continue" decision`)
+    if (breaker.reenteredAt !== undefined && !nonEmptyString(breaker.reenteredAt)) errors.push(`${label}.reenteredAt must be a non-empty timestamp`)
+  }
+  return errors
+}
+
+export function validateBreaker(unit) {
+  const errors = []
+  if (unit?.breaker !== undefined) errors.push(...validateBreakerObject(unit.breaker, 'breaker'))
+  // The append-only audit log of prior firings (see recordBreakerDecision). Each
+  // entry is a complete past breaker object; the log is validated with the same bar.
+  if (unit?.breakerLog !== undefined) {
+    if (!Array.isArray(unit.breakerLog)) errors.push('breakerLog must be an array')
+    else unit.breakerLog.forEach((entry, i) => errors.push(...validateBreakerObject(entry, `breakerLog[${i}]`)))
+  }
+  return errors
+}
+
+function validateCoverage(coverage, theme) {
+  const errors = []
+  if (!Array.isArray(coverage)) return ['contract-complete round requires coverage for every state/task-kind cell']
+  const expected = stateSpaceCells(theme)
+  const seen = new Set()
+  for (const cell of coverage) {
+    if (!isObject(cell)) {
+      errors.push('coverage cells require state and taskKind')
+      continue
+    }
+    errors.push(...Object.keys(cell).filter((key) => !['state', 'taskKind', 'outcome', 'test', 'evidence'].includes(key)).map((key) => `coverage cell has unknown property: ${key}`))
+    if (!nonEmptyString(cell.state) || !nonEmptyString(cell.taskKind)) {
+      errors.push('coverage cells require non-empty state and taskKind')
+      continue
+    }
+    if (cell.outcome !== 'accept' && cell.outcome !== 'reject') errors.push(`coverage for ${cell.state} × ${cell.taskKind} requires an accept/reject outcome`)
+    const key = cellKey(cell)
+    if (seen.has(key)) errors.push(`duplicate coverage for ${cell.state} × ${cell.taskKind}`)
+    seen.add(key)
+    if (!isLocator(cell.test)) errors.push(`coverage for ${cell.state} × ${cell.taskKind} requires a checkable test locator`)
+    if (!isLocator(cell.evidence)) errors.push(`coverage for ${cell.state} × ${cell.taskKind} requires a checkable evidence locator`)
+  }
+  for (const cell of expected) {
+    if (!seen.has(cellKey(cell))) errors.push(`missing coverage for ${cell.state} × ${cell.taskKind}`)
+  }
+  for (const cell of coverage) {
+    if (isObject(cell) && nonEmptyString(cell.state) && nonEmptyString(cell.taskKind) && !expected.some((expectedCell) => cellKey(expectedCell) === cellKey(cell))) {
+      errors.push(`coverage includes an undeclared state/task-kind cell: ${cell.state} × ${cell.taskKind}`)
+    }
+  }
+  return errors
+}
+
+function validateAdjacentReview(selfReview, theme) {
+  const errors = []
+  if (!isObject(selfReview) || Object.keys(selfReview).some((key) => key !== 'adjacentStates')) {
+    errors.push('self-review must contain only adjacentStates')
+  }
+  const adjacent = selfReview?.adjacentStates
+  if (!Array.isArray(adjacent)) return [...errors, 'self-review must provide one adjacent-state entry per declared state']
+  const seen = new Set()
+  for (const entry of adjacent) {
+    if (!isObject(entry) || !nonEmptyString(entry.state)) {
+      errors.push('adjacent-state review entries require a non-empty state')
+      continue
+    }
+    errors.push(...Object.keys(entry).filter((key) => !['state', 'evidence'].includes(key)).map((key) => `adjacent-state review has unknown property: ${key}`))
+    if (seen.has(entry.state)) errors.push(`duplicate adjacent-state review: ${entry.state}`)
+    seen.add(entry.state)
+    if (!isLocator(entry.evidence)) errors.push(`adjacent-state review for ${entry.state} requires a checkable evidence locator`)
+    if (!theme.stateSpace.states.includes(entry.state)) errors.push(`adjacent-state review includes undeclared state: ${entry.state}`)
+  }
+  for (const state of theme.stateSpace.states) {
+    if (!seen.has(state)) errors.push(`missing adjacent-state review for declared state: ${state}`)
+  }
+  return errors
+}
+
+// Validate the durable, canonical fix record. The caller-facing proof is
+// validated by validateFixProof and never contains a redeclared theme.
+export function validateContractComplete(round, expectedTheme = null) {
+  const errors = []
+  if (!isObject(round)) return ['fix round must be an object']
+  errors.push(...Object.keys(round).filter((key) => !['round', 'reviewRound', 'themeId', 'theme', 'coverage', 'selfReview'].includes(key)).map((key) => `fix round has unknown property: ${key}`))
+  if (!Number.isInteger(round.round) || round.round < 1) errors.push('fix round must be a positive integer')
+  if (!Number.isInteger(round.reviewRound) || round.reviewRound < 1) errors.push('fix round reviewRound must be a positive integer')
+  if (!nonEmptyString(round.themeId)) errors.push('fix round themeId must be a non-empty string')
+  let theme = expectedTheme
+  if (!theme) {
+    try { theme = themeFromPersisted(round.theme) } catch (error) { errors.push(error.message) }
+  }
+  if (theme) {
+    errors.push(...validateTheme(theme))
+    if (round.themeId !== theme.id) errors.push(`fix round themeId ${round.themeId} does not match canonical theme ${theme.id}`)
+    if (CONTRACT_COMPLETE_KINDS.has(theme.kind)) {
+      errors.push(...validateCoverage(round.coverage, theme))
+      errors.push(...validateAdjacentReview(round.selfReview, theme))
+    }
+  }
+  return errors
+}
+
+export function validateFixProof(proof, expectedTheme) {
+  const errors = []
+  if (!isObject(proof)) return ['fix proof must be an object']
+  errors.push(...Object.keys(proof).filter((key) => !['round', 'reviewRound', 'themeId', 'coverage', 'selfReview'].includes(key)).map((key) => `fix proof has unknown property: ${key}`))
+  if (!Number.isInteger(proof.round) || proof.round < 1) errors.push('fix round must be a positive integer')
+  if (!Number.isInteger(proof.reviewRound) || proof.reviewRound < 1) errors.push('fix round reviewRound must be a positive integer')
+  if (!nonEmptyString(proof.themeId)) errors.push('fix proof themeId must be a non-empty string')
+  if (!expectedTheme) return [...errors, 'fix proof must resolve a reviewed theme']
+  if (proof.themeId !== expectedTheme.id) errors.push(`fix proof themeId ${proof.themeId} is not declared by review round`)
+  if (CONTRACT_COMPLETE_KINDS.has(expectedTheme.kind)) {
+    errors.push(...validateCoverage(proof.coverage, expectedTheme))
+    errors.push(...validateAdjacentReview(proof.selfReview, expectedTheme))
+  }
+  return errors
+}
+
+function validateReviewRoundShape(round) {
+  if (!isObject(round)) return ['round must be an object']
+  const hasThemes = Object.prototype.hasOwnProperty.call(round, 'themes')
+  const hasFindings = Object.prototype.hasOwnProperty.call(round, 'findings')
+  // `oracleEscalation` is tolerated and ignored, never written — history from the
+  // removed oracle slot must still read back rather than fail closed.
+  // `headSha` accepted on deep history too (#792) — same dual-schema trap as the write path.
+  const allowed = hasThemes
+    ? ['round', 'verdict', 'themes', 'oracleEscalation', 'round1Depth', 'headSha']
+    : ['round', 'verdict', 'findings', 'oracleEscalation', 'round1Depth', 'headSha']
+  const errors = Object.keys(round).filter((key) => !allowed.includes(key)).map((key) => `unknown property: ${key}`)
+  if (!Number.isInteger(round.round) || round.round < 1) errors.push('round must be a positive integer')
+  if (!REVIEW_VERDICTS.includes(round.verdict)) errors.push(`invalid verdict ${round.verdict}`)
+  if (hasThemes === hasFindings) errors.push('round must contain exactly one themes or findings array')
+  if (hasThemes && !Array.isArray(round.themes)) errors.push('themes must be an array')
+  if (hasFindings && !Array.isArray(round.findings)) errors.push('findings must be an array')
+  if (round.round1Depth !== undefined) errors.push(...validateRound1Depth(round.round1Depth))
+  return errors
+}
+
+// This mirrors the import-free workflow's round1Depth schema. The workflow
+// result is not a generic review document: it is a transition envelope with
+// two mandatory depth obligations that must survive into durable history.
+export function validateRound1Depth(depth) {
+  if (!isObject(depth)) return ['round1Depth must be an object']
+  const errors = Object.keys(depth)
+    .filter((key) => !ROUND1_DEPTH_OBLIGATIONS.includes(key))
+    .map((key) => `round1Depth has unknown property: ${key}`)
+  for (const obligation of ROUND1_DEPTH_OBLIGATIONS) {
+    const result = depth[obligation]
+    if (!isObject(result)) {
+      errors.push(`round1Depth.${obligation} must be an object`)
+      continue
+    }
+    errors.push(...Object.keys(result)
+      .filter((key) => !['status', 'evidence'].includes(key))
+      .map((key) => `round1Depth.${obligation} has unknown property: ${key}`))
+    if (!['completed', 'not-applicable'].includes(result.status)) {
+      errors.push(`round1Depth.${obligation}.status must be completed|not-applicable`)
+    }
+    if (!nonEmptyString(result.evidence)) errors.push(`round1Depth.${obligation}.evidence must be a non-empty string`)
+  }
+  return errors
+}
+
+function owedThemes(history, review) {
+  if (review?.verdict !== 'NEEDS_CHANGES') return []
+  return themesInRound(review).filter((theme) => CONTRACT_COMPLETE_KINDS.has(theme.kind))
+}
+
+function validateFixReferences(unit, history, errors) {
+  const fixes = Array.isArray(unit.fixRounds) ? unit.fixRounds : []
+  const seenKeys = new Set()
+  let previousFixRound = 0
+  let previousReviewRound = 0
+  for (const [index, fix] of fixes.entries()) {
+    const prefix = `fixRounds[${index}]`
+    errors.push(...validateContractComplete(fix).map((error) => `${prefix}: ${error}`))
+    if (Number.isInteger(fix?.round)) {
+      if (fix.round < previousFixRound) errors.push(`${prefix}: fix rounds must be append-only and ordered`)
+      previousFixRound = fix.round
+    }
+    if (Number.isInteger(fix?.reviewRound)) {
+      if (fix.reviewRound < previousReviewRound) errors.push(`${prefix}: review rounds referenced by fixes must be ordered`)
+      previousReviewRound = fix.reviewRound
+    }
+    if (isObject(fix) && nonEmptyString(fix.themeId) && Number.isInteger(fix.reviewRound)) {
+      const key = proofKey(fix)
+      if (seenKeys.has(key)) errors.push(`${prefix}: duplicate fix proof for review round ${fix.reviewRound} and theme ${fix.themeId}`)
+      seenKeys.add(key)
+      const review = history.find((entry) => entry?.round === fix.reviewRound)
+      if (!review) {
+        errors.push(`${prefix}: fix proof has no referenced review round ${fix.reviewRound}`)
+        continue
+      }
+      let reviewedThemes = []
+      try { reviewedThemes = themesInRound(review) } catch (error) { errors.push(`${prefix}: cannot resolve referenced review: ${error.message}`); continue }
+      const reviewed = reviewedThemes.find((theme) => theme.id === fix.themeId)
+      if (!reviewed) errors.push(`${prefix}: fix proof theme ${fix.themeId} is not declared by review round ${fix.reviewRound}`)
+      else if (themeFingerprint(reviewed) !== themeFingerprint({ ...fix.theme, id: fix.theme?.themeId })) errors.push(`${prefix}: fix proof theme snapshot drift for ${fix.themeId}`)
+    }
+  }
+  for (let index = 0; index < history.length - 1; index++) {
+    const review = history[index]
+    const owed = owedThemes(history, review)
+    for (const theme of owed) {
+      if (!fixes.some((fix) => fix.reviewRound === review.round && fix.themeId === theme.id)) errors.push(`reviewHistory[${index}]: missing contract-complete fix proof for ${theme.id} before next review`)
+    }
+  }
+}
+
+function convertLegacyReview(review, warnings = []) {
+  if (!isObject(review)) throw new Error('legacy review round must be an object')
+  if (Object.prototype.hasOwnProperty.call(review, 'themes')) {
+    throw new Error('legacy review round cannot contain current themes; reconstruct it explicitly')
+  }
+  const allowed = ['round', 'verdict', 'findings', 'oracleEscalation']
+  const unknown = Object.keys(review).filter((key) => !allowed.includes(key))
+  if (unknown.length) throw new Error(`legacy review round has unknown property: ${unknown[0]}`)
+  if (!Array.isArray(review.findings)) throw new Error('legacy review round requires findings')
+  // An obsolete key on a legacy finding is dropped, not refused — surface it the same
+  // way validate() surfaces obsolete slots so the migration is visible, not silent.
+  review.findings.forEach((finding, index) => {
+    for (const warning of findingWarnings(finding, index)) warnings.push(`round ${review.round}: ${warning}`)
+  })
+  const findings = review.findings.map((finding) => migrateLegacyFinding(finding, { version: 1 }))
+  const themes = uniqueThemes(findings.map(themeFromFinding)).map(persistedTheme)
+  // A legacy `oracleEscalation` is read and dropped, never carried into v2 —
+  // migrating it forward would persist state nothing reads.
+  return {
+    round: review.round,
+    verdict: review.verdict,
+    themes,
+  }
+}
+
+function convertLegacyUnitState(unit, warnings = []) {
+  if (!isObject(unit)) throw new Error('legacy unit must be an object')
+  if (unit.stateVersion !== undefined) throw new Error('legacy migration requires a unit without stateVersion')
+  if (Object.prototype.hasOwnProperty.call(unit, 'reviewHistory') && !Array.isArray(unit.reviewHistory)) {
+    throw new Error('legacy reviewHistory must be an array when present')
+  }
+  if (Object.prototype.hasOwnProperty.call(unit, 'fixRounds') && !Array.isArray(unit.fixRounds)) {
+    throw new Error('legacy fixRounds must be an array when present')
+  }
+  const history = Array.isArray(unit.reviewHistory) ? unit.reviewHistory.map((review) => convertLegacyReview(review, warnings)) : []
+  const fixes = Array.isArray(unit.fixRounds) ? unit.fixRounds.map((fix) => {
+    if (!isObject(fix)) throw new Error('legacy fix round must be an object')
+    const allowed = ['round', 'theme', 'coverage', 'selfReview']
+    const unknown = Object.keys(fix).filter((key) => !allowed.includes(key))
+    if (unknown.length) throw new Error(`legacy fix round has unknown/current property: ${unknown[0]}`)
+    if (fix.reviewRound !== undefined || fix.themeId !== undefined) throw new Error('legacy fix round has current identity; reconstruct it explicitly')
+    const legacyTheme = fix.theme
+    if (!isObject(legacyTheme)) throw new Error(`legacy fix round ${fix.round} requires a theme`)
+    const candidates = history.flatMap((review) => {
+      let themes = []
+      try { themes = themesInRound(review) } catch { return [] }
+      return themes.filter((theme) => themeFingerprint(theme) === themeFingerprint(legacyTheme)).map((theme) => ({ reviewRound: review.round, theme }))
+    })
+    if (candidates.length !== 1) throw new Error(`legacy fix round ${fix.round} does not map uniquely to one reviewed theme; reconstruct it explicitly`)
+    const { reviewRound, theme } = candidates[0]
+    return {
+      round: fix.round,
+      reviewRound,
+      themeId: theme.id,
+      theme: persistedTheme(theme),
+      coverage: clone(fix.coverage),
+      selfReview: clone(fix.selfReview),
+    }
+  }) : undefined
+  const out = clone(unit)
+  out.reviewHistory = history
+  if (fixes) out.fixRounds = fixes
+  if (out.status === 'skipped-already-done' && !out.scopeDecision) out.disposition = 'already-done'
+  else if (out.delivery?.outcome === 'merged') out.disposition = 'delivered'
+  else if (out.delivery?.outcome === 'handed-back') out.disposition = 'handed-back'
+  else if (out.status === 'blocked') out.disposition = 'blocked'
+  out.stateVersion = 2
+  return out
+}
+
+// The legacy hand-off re-enters validateUnitRoundState on the migrated unit, so it has to
+// carry the run's delivery mode through. Dropping it made the re-entry silently re-validate
+// delivery against the DEFAULT 'direct' mode: a lean unit (the majority tier — versionless,
+// so always routed here) on a queue-mode run had every legal `enqueue` reported as an
+// illegal direct action, while validateDelivery on its own returned clean.
+function validateLegacyUnitState(unit, mode, provider = null) {
+  try {
+    return validateUnitRoundState(convertLegacyUnitState(unit), mode, provider)
+  } catch (error) {
+    return [error.message]
+  }
+}
+
+// `mode` is the run's delivery mode; it defaults to 'direct' for the same reason
+// `deliveryMode()` does — a manifest with no mode recorded ran the legacy merge path.
+// Callers holding the manifest (run-state validate, the settle path) pass the real one.
+// Known review-round numbers for a unit — the lean round log (`rounds[]`) and/or deep
+// `reviewHistory`. Used by lean fix referential integrity: a leanFixRound.reviewRound must
+// point at a review that actually exists (#792 / review finding lean-fix-round.referential-integrity).
+export function knownReviewRoundNumbers(unit) {
+  const known = new Set()
+  if (Array.isArray(unit?.rounds)) {
+    for (const entry of unit.rounds) {
+      if (Number.isInteger(entry?.round) && entry.round >= 1) known.add(entry.round)
+    }
+  }
+  if (Array.isArray(unit?.reviewHistory)) {
+    for (const entry of unit.reviewHistory) {
+      if (Number.isInteger(entry?.round) && entry.round >= 1) known.add(entry.round)
+    }
+  }
+  return known
+}
+
+// Lean fix log integrity: each leanFixRounds[i].reviewRound must refer to a known review
+// for that unit. Orphan references make the manifest claim a fix closed findings from a
+// review that never happened.
+export function validateLeanFixRounds(unit) {
+  const errors = []
+  if (unit?.leanFixRounds === undefined) return errors
+  if (!Array.isArray(unit.leanFixRounds)) return ['leanFixRounds must be an array']
+  const known = knownReviewRoundNumbers(unit)
+  for (const [i, entry] of unit.leanFixRounds.entries()) {
+    const at = `leanFixRounds[${i}]`
+    if (!isObject(entry)) { errors.push(`${at} must be an object`); continue }
+    if (!Number.isInteger(entry.reviewRound) || entry.reviewRound < 1) {
+      errors.push(`${at}.reviewRound must be a positive integer`)
+      continue
+    }
+    if (!known.has(entry.reviewRound)) {
+      errors.push(`${at}: reviewRound ${entry.reviewRound} has no matching review round on this unit (rounds[] / reviewHistory)`)
+    }
+    if (entry.changedSurfaces !== undefined) {
+      try { normalizeChangedSurfaces(entry.changedSurfaces) } catch (error) { errors.push(`${at}.${error.message}`) }
+      if (entry.productionMoved !== undefined) errors.push(`${at}.productionMoved is legacy-only and cannot accompany changedSurfaces`)
+    } else if (typeof entry.productionMoved !== 'boolean') {
+      errors.push(`${at} requires changedSurfaces; legacy records require productionMoved: boolean and read as unknown`)
+    }
+  }
+  return errors
+}
+
+export function validateUnitRoundState(unit, mode = 'direct', provider = null) {
+  const errors = []
+  if (!unit || typeof unit !== 'object' || Array.isArray(unit)) return ['unit must be an object']
+  // Before any version routing: the budget binds every tier, and a lean unit is
+  // often versionless — checking after the legacy hand-off would skip exactly the
+  // units that have no transition-command gate to fall back on.
+  const budgetErrors = [...validateBreakerBudget(unit), ...validateTerminalVerdict(unit), ...validateDelivery(unit, mode, provider)]
+  // The round log is checked before version routing for the same reason as the budget:
+  // it is the lean lane's record, and lean units are often versionless.
+  const roundLogErrors = validateRoundLog(unit)
+  // Lean fix referential integrity is lane-agnostic: orphan leanFixRounds must fail closed
+  // on both versionless and deep units (the field is not gated on stateVersion).
+  const leanFixErrors = validateLeanFixRounds(unit)
+  // The legacy hand-off re-enters this function on the migrated unit, which recomputes
+  // the budget/verdict errors — passing ours through as well printed each one twice.
+  if (unit.stateVersion === undefined) return [...new Set([...budgetErrors, ...roundLogErrors, ...leanFixErrors, ...validateLegacyUnitState(unit, mode, provider)])]
+  errors.push(...roundLogErrors, ...leanFixErrors)
+  if (unit.stateVersion !== undefined && unit.stateVersion !== 2) errors.push('stateVersion must be 2; run explicit migrate-unit --version 1 for legacy state')
+  if (unit.fixRounds !== undefined && !Array.isArray(unit.fixRounds)) errors.push('fixRounds must be an array')
+  if (unit.reviewHistory !== undefined && !Array.isArray(unit.reviewHistory)) errors.push('reviewHistory must be an array')
+  const history = Array.isArray(unit.reviewHistory) ? unit.reviewHistory : []
+  let previousRound = 0
+  const knownThemes = new Map()
+  history.forEach((round, index) => {
+    errors.push(...validateReviewRoundShape(round).map((error) => `reviewHistory[${index}]: ${error}`))
+    if (Number.isInteger(round?.round)) {
+      if (round.round !== previousRound + 1) errors.push(`reviewHistory[${index}]: rounds must start at 1 and advance exactly by one`)
+      previousRound = round.round
+    }
+    let themes = []
+    try { themes = uniqueThemes(themesInRound(round)) } catch (error) { errors.push(`reviewHistory[${index}]: ${error.message}`) }
+    for (const theme of themes) {
+      const fingerprint = themeFingerprint(theme)
+      const prior = knownThemes.get(theme.id)
+      if (prior && prior !== fingerprint) errors.push(`reviewHistory[${index}]: theme contract/state-space drift for ${theme.id}`)
+      knownThemes.set(theme.id, fingerprint)
+    }
+  })
+  validateFixReferences(unit, history, errors)
+  errors.push(...budgetErrors, ...validateBreaker(unit))
+  return errors
+}
+
+function assertMigratedUnit(unit, transition) {
+  if (unit?.stateVersion === undefined) {
+    throw new Error(`${transition} rejects legacy unit state without stateVersion; run explicit migrate-unit --version 1`)
+  }
+  if (unit.stateVersion !== 2) {
+    throw new Error(`${transition} requires stateVersion 2; run explicit migrate-unit --version 1 for legacy state`)
+  }
+}
+
+function candidateOrThrow(manifest, unitId, out) {
+  const { units } = unitOrThrow(out, unitId)
+  const unit = units.find((entry) => entry.id === unitId)
+  assertMigratedUnit(unit, 'candidate state')
+  const errors = validateUnitRoundState(unit, deliveryMode(out), deliveryProvider(out))
+  if (errors.length) throw new Error(`candidate state is invalid: ${errors[0]}`)
+  return out
+}
+
+// The breaker binds BOTH lanes — completedReviewRounds folds in the lean round log
+// precisely so a unit that logs rounds without touching reviewHistory still hits the
+// budget — so *clearing* it has to be reachable from both. Routing the decision
+// through candidateOrThrow made it stateVersion-2-only, while the documented
+// unit-creation call (references/run-state.md) writes no stateVersion: the majority
+// tier could fire the breaker and never clear it, dead-ending at round 3 for exactly
+// the units it was built for. A dead-ended gate is worse than an absent one — it
+// gives the orchestrator a reason to stop recording state, and an orchestrator that
+// stops recording is one no later gate can refuse. Same reasoning as recordRound's,
+// one transition later.
+// The discriminator is the ABSENCE of deep-lane state, not `stateVersion` alone: a
+// versionless unit carrying reviewHistory/fixRounds is a deep-lane unit that never got
+// migrated, and sending it down the lean path would skip exactly the validation those
+// fields need. And the lean path still owes the budget check — this module's contract
+// (see the header) is that the CLI cannot persist a state the module would reject on
+// read-back, so a write that succeeds while `validate` goes red is the dead-end shape
+// this change set exists to remove, not to relocate.
+function settleBreakerOrThrow(manifest, unitId, out) {
+  const { units } = unitOrThrow(out, unitId)
+  const unit = units.find((entry) => entry.id === unitId)
+  const isLean = unit?.stateVersion === undefined && unit?.reviewHistory === undefined && unit?.fixRounds === undefined
+  if (!isLean) return candidateOrThrow(manifest, unitId, out)
+  // Include lean-fix referential integrity so a write that would fail validate on
+  // read-back cannot persist (same contract as the deep path's candidateOrThrow).
+  const errors = [
+    ...validateRoundLog(unit),
+    ...validateLeanFixRounds(unit),
+    ...validateBreaker(unit),
+    ...validateBreakerBudget(unit),
+    ...validateDelivery(unit, deliveryMode(out), deliveryProvider(out)),
+  ]
+  if (errors.length) throw new Error(`candidate state is invalid: ${errors[0]}`)
+  return out
+}
+
+// ---- lean vs deep recording (#792 / issue-664 / identity#669) ----
+//
+// The deep-audit matrix (reviewHistory themes + fixRounds coverage/selfReview) is the
+// high-risk protocol's optional mechanization (high-risk.md). Routine units only need
+// the lean round log. Before #792, record-review-round rejected `headSha` as unknown and
+// record-fix-round required migrate-unit + the full matrix even for an env-guard fix —
+// schema thrash that burned turns on identity#669.
+//
+// Lean shapes (no stateVersion / no deep fields required):
+//   record-review-round { round, verdict, headSha?, scope?, themeIds?, findings?: lean[] }
+//   record-fix-round    { reviewRound, headSha, themeIds[], changedSurfaces?, classesClosed? }
+// Deep shape is unchanged: full finding.theme objects + coverage/selfReview matrix.
+// A payload that carries the deep fields (coverage, selfReview, or findings with theme
+// objects) takes the deep path and still requires stateVersion 2.
+
+const LEAN_REVIEW_FIELDS = new Set([
+  'round', 'verdict', 'headSha', 'scope', 'themeIds', 'findings', 'summary',
+  'overall_correctness', 'overMockFindings', 'previousFindingsResolution',
+  'reviewModel', 'independent', 'contractValidates', 'round1Depth',
+  'changedSurfaces', 'reviewSubject', 'evidenceClasses', 'reopenReason', 'authorizationBoundary',
+])
+
+const LEAN_FIX_FIELDS = new Set([
+  'round', 'reviewRound', 'headSha', 'themeIds', 'themeId', 'changedSurfaces', 'productionMoved',
+  'classesClosed', 'coverage', 'selfReview',
+])
+
+function isLeanFinding(finding) {
+  if (!isObject(finding)) return false
+  // A deep finding carries a full theme object (kind/contract/stateSpace). A lean one
+  // carries at most themeId (+ file/line/subject/confidence).
+  return finding.theme === undefined
+}
+
+function isDeepReviewPayload(review) {
+  if (!isObject(review)) return false
+  if (review.round1Depth !== undefined) return true
+  if (Array.isArray(review.findings) && review.findings.some((f) => isObject(f) && f.theme !== undefined)) return true
+  // Full review-document fields imply the deep path (workflow / independent-review envelope).
+  if (review.overMockFindings !== undefined || review.previousFindingsResolution !== undefined) return true
+  if (review.contractValidates !== undefined || review.independent !== undefined) return true
+  return false
+}
+
+// Lean signature: headSha present, no deep finding.theme objects, no deep envelope fields.
+// Without headSha, `{round, verdict, findings:[]}` is the pre-#792 deep API and must keep
+// requiring stateVersion 2 / migrate-unit — otherwise legacy rejection tests (and real deep
+// callers) silently become lean round-log writes.
+function isLeanReviewPayload(review) {
+  if (!isObject(review)) return false
+  if (isDeepReviewPayload(review)) return false
+  if (!nonEmptyString(review.headSha)) return false
+  if (Array.isArray(review.findings) && review.findings.some((f) => isObject(f) && !isLeanFinding(f))) return false
+  return true
+}
+
+function isDeepFixPayload(proof) {
+  if (!isObject(proof)) return false
+  return proof.coverage !== undefined || proof.selfReview !== undefined
+}
+
+function validateLeanReviewFinding(finding, index = 0) {
+  if (!isObject(finding)) return [`findings[${index}] must be an object`]
+  const allowed = new Set(['file', 'line', 'line_start', 'themeId', 'subject', 'confidence', 'title', 'why', 'axis', 'priority'])
+  const unknown = Object.keys(finding).filter((k) => !allowed.has(k))
+  if (unknown.length) return [`findings[${index}] has unknown property: ${unknown[0]}`]
+  if (!nonEmptyString(finding.file)) return [`findings[${index}].file is required`]
+  const line = finding.line ?? finding.line_start
+  if (!Number.isInteger(line) || line < 1) return [`findings[${index}].line must be a positive integer`]
+  if (finding.themeId !== undefined && !nonEmptyString(finding.themeId)) return [`findings[${index}].themeId must be a non-empty string when present`]
+  if (finding.subject !== undefined && !['code', 'evidence'].includes(finding.subject)) {
+    return [`findings[${index}].subject must be code|evidence`]
+  }
+  if (finding.confidence !== undefined) {
+    if (typeof finding.confidence !== 'number' || !Number.isFinite(finding.confidence) || finding.confidence < 0 || finding.confidence > 1) {
+      return [`findings[${index}].confidence must be a number in 0..1`]
+    }
+  }
+  return []
+}
+
+function leanThemeIdsFromReview(review) {
+  const ids = []
+  if (Array.isArray(review.themeIds)) {
+    for (const id of review.themeIds) {
+      if (!nonEmptyString(id)) throw new Error('themeIds must be an array of non-empty strings')
+      ids.push(id)
+    }
+  }
+  if (Array.isArray(review.findings)) {
+    for (const [i, f] of review.findings.entries()) {
+      const errs = validateLeanReviewFinding(f, i)
+      if (errs.length) throw new Error(errs[0])
+      if (nonEmptyString(f.themeId) && !ids.includes(f.themeId)) ids.push(f.themeId)
+    }
+  }
+  return ids
+}
+
+export function recordFixRound(manifest, unitId, proof, { derivedChangedSurfaces } = {}) {
+  if (!isObject(proof)) throw new Error('fix proof must be an object')
+  const candidateUnit = unitOrThrow(manifest, unitId).units.find((unit) => unit.id === unitId)
+  if (effectiveUnitKind(candidateUnit) !== 'implementation') {
+    throw new Error(`record-fix-round is only for implementation units; ${unitId} is ${effectiveUnitKind(candidateUnit)}`)
+  }
+
+  // ---- lean path (#792) ----
+  // Accepts { reviewRound, headSha, themeIds[], changedSurfaces?, classesClosed? }
+  // without migrate-unit or the deep matrix. Operational callers provide a Git-derived
+  // surface set; the no-derivation branch exists only for legacy library compatibility.
+  if (!isDeepFixPayload(proof)) {
+    const unknown = Object.keys(proof).filter((k) => !LEAN_FIX_FIELDS.has(k))
+    if (unknown.length) throw new Error(`fix round has unknown property: ${unknown[0]}`)
+    if (!Number.isInteger(proof.reviewRound) || proof.reviewRound < 1) {
+      throw new Error('fix round reviewRound must be a positive integer')
+    }
+    if (!nonEmptyString(proof.headSha)) throw new Error('lean fix round requires headSha')
+    const typedWrite = derivedChangedSurfaces !== undefined
+    let changedSurfaces
+    if (typedWrite) {
+      changedSurfaces = proof.changedSurfaces === undefined
+        ? normalizeChangedSurfaces(derivedChangedSurfaces)
+        : assertChangedSurfacesMatch(proof.changedSurfaces, derivedChangedSurfaces)
+      if (proof.productionMoved !== undefined) throw new Error('productionMoved is legacy-only; new lean fix rounds use changedSurfaces')
+    } else if (typeof proof.productionMoved !== 'boolean') {
+      throw new Error('legacy lean fix round requires productionMoved: boolean')
+    }
+    // themeIds[] is preferred; a single themeId is accepted as a one-element list so a
+    // deep-shaped call that only drops coverage still has a soft landing.
+    let themeIds = Array.isArray(proof.themeIds) ? proof.themeIds : undefined
+    if (themeIds === undefined && nonEmptyString(proof.themeId)) themeIds = [proof.themeId]
+    if (!Array.isArray(themeIds) || !themeIds.length || !themeIds.every(nonEmptyString)) {
+      throw new Error('lean fix round requires themeIds: non-empty string[]')
+    }
+    if (proof.classesClosed !== undefined) {
+      if (!Array.isArray(proof.classesClosed) || !proof.classesClosed.every(nonEmptyString)) {
+        throw new Error('classesClosed must be an array of non-empty strings when present')
+      }
+    }
+    const out = clone(manifest)
+    const { units, index } = unitOrThrow(out, unitId)
+    const unit = units[index]
+    assertNoPendingBreaker(unit, 'record-fix-round')
+    // Referential integrity (#792): reviewRound must point at a review that exists on
+    // this unit (lean rounds[] and/or deep reviewHistory). Without this, a call with
+    // reviewRound: 99 against a unit that never had a review records cleanly and the
+    // manifest claims a fix closed findings from a non-existent review.
+    const knownReviews = knownReviewRoundNumbers(unit)
+    if (!knownReviews.has(proof.reviewRound)) {
+      throw new Error(
+        `lean fix round reviewRound ${proof.reviewRound} has no matching review round on this unit (rounds[] / reviewHistory)`,
+      )
+    }
+    // Fix proofs stay in their append-only side log; they do not increment the review-round budget.
+    unit.leanFixRounds = Array.isArray(unit.leanFixRounds) ? unit.leanFixRounds : []
+    unit.leanFixRounds.push({
+      reviewRound: proof.reviewRound,
+      headSha: proof.headSha,
+      themeIds: [...themeIds],
+      ...(typedWrite ? { changedSurfaces } : { productionMoved: proof.productionMoved }),
+      ...(Array.isArray(proof.classesClosed) ? { classesClosed: [...proof.classesClosed] } : {}),
+    })
+    return settleBreakerOrThrow(manifest, unitId, out)
+  }
+
+  // ---- deep path (unchanged) ----
+  if (!Number.isInteger(proof?.round) || proof.round < 1) throw new Error('fix round must be a positive integer')
+  const out = clone(manifest)
+  const { units, index } = unitOrThrow(out, unitId)
+  const unit = units[index]
+  assertMigratedUnit(unit, 'record-fix-round')
+  assertNoPendingBreaker(unit, 'record-fix-round')
+  const persistedErrors = validateUnitRoundState(unit, deliveryMode(out), deliveryProvider(out))
+  if (persistedErrors.length) throw new Error(`cannot record fix round from invalid persisted state: ${persistedErrors[0]}`)
+  const latestReview = unit.reviewHistory?.at(-1)
+  if (!latestReview) throw new Error('record-fix-round requires a referenced review round')
+  if (proof?.reviewRound !== latestReview.round) throw new Error(`fix proof must reference the latest review round ${latestReview.round}`)
+  const reviewedTheme = themesInRound(latestReview).find((theme) => theme.id === proof?.themeId)
+  const errors = validateFixProof(proof, reviewedTheme)
+  if (errors.length) throw new Error(errors[0])
+  unit.fixRounds = Array.isArray(unit.fixRounds) ? unit.fixRounds : []
+  const key = proofKey(proof)
+  if (unit.fixRounds.some((existing) => proofKey(existing) === key)) throw new Error(`duplicate fix proof for review round ${proof.reviewRound} and theme ${proof.themeId}`)
+  const previous = unit.fixRounds.at(-1)
+  if (previous && proof.round < previous.round) throw new Error(`fix round ${proof.round} is older than ${previous.round}`)
+  if (previous && proof.reviewRound < previous.reviewRound) throw new Error(`fix proof review round ${proof.reviewRound} is older than ${previous.reviewRound}`)
+  unit.fixRounds.push({
+    round: proof.round,
+    reviewRound: proof.reviewRound,
+    themeId: proof.themeId,
+    theme: persistedTheme(reviewedTheme),
+    coverage: clone(proof.coverage),
+    selfReview: clone(proof.selfReview),
+  })
+  return candidateOrThrow(manifest, unitId, out)
+}
+
+export function recordReviewRound(manifest, unitId, review, { derivedChangedSurfaces } = {}) {
+  if (!Number.isInteger(review?.round) || review.round < 1) throw new Error('review round must be a positive integer')
+  if (!isObject(review)) throw new Error('review round must be an object')
+  const candidateUnit = unitOrThrow(manifest, unitId).units.find((unit) => unit.id === unitId)
+  if (effectiveUnitKind(candidateUnit) !== 'implementation') {
+    throw new Error(`record-review-round is only for implementation units; ${unitId} is ${effectiveUnitKind(candidateUnit)}`)
+  }
+
+  // Route by unit state first: a unit already on the deep lane (stateVersion 2 or
+  // reviewHistory present) stays on the deep path even for empty findings — otherwise
+  // a deep unit's PASS with findings:[] would silently become a lean round-log write
+  // and skip the matrix/owed-proof validation the deep lane exists for.
+  // Lean only when the payload carries the lean signature (headSha, no deep themes).
+  const probe = unitOrThrow(manifest, unitId).units.find((u) => u.id === unitId)
+  const unitIsDeep = probe?.stateVersion !== undefined || Array.isArray(probe?.reviewHistory) || Array.isArray(probe?.fixRounds)
+  const useDeep = unitIsDeep || !isLeanReviewPayload(review)
+
+  // Near-miss lean call: a versionless unit, no deep envelope fields, but headSha is
+  // missing or empty. Without this, the deep path's "findings is not an array" / migrate
+  // errors fire and the orchestrator re-learns the dual-schema trap #792 closed. Name
+  // headSha as the missing lean discriminator before falling through.
+  if (!unitIsDeep && !isDeepReviewPayload(review) && !nonEmptyString(review.headSha)) {
+    if (review.headSha !== undefined) {
+      throw new Error('headSha must be a non-empty string when present')
+    }
+    throw new Error('lean review round requires headSha (the SHA the verdict was rendered against); omit deep envelope fields and pass headSha, or migrate-unit for the deep path')
+  }
+
+  // ---- lean path (#792) ----
+  // Accepts headSha + themeIds + minimal findings without the deep-audit matrix and
+  // without migrate-unit. Writes the lean round log (units[].rounds). The deep
+  // reviewHistory path is unchanged for high-risk / full finding.theme payloads.
+  if (!useDeep) {
+    const unknown = Object.keys(review).filter((k) => !LEAN_REVIEW_FIELDS.has(k))
+    if (unknown.length) throw new Error(`review round has unknown property: ${unknown[0]}`)
+    if (!REVIEW_VERDICTS.includes(review.verdict)) {
+      throw new Error(`invalid verdict ${review.verdict}`)
+    }
+    // headSha is accepted here (the dual-schema trap this issue closes): either
+    // record-review-round or record-round may carry it; when present on the lean
+    // review payload it is required non-empty and becomes the round-log headSha.
+    if (review.headSha !== undefined && !nonEmptyString(review.headSha)) {
+      throw new Error('headSha must be a non-empty string when present')
+    }
+    if (!nonEmptyString(review.headSha)) {
+      throw new Error('lean review round requires headSha (the SHA the verdict was rendered against)')
+    }
+    if (review.scope !== undefined && !ROUND_SCOPES.includes(review.scope)) {
+      throw new Error(`scope must be one of ${ROUND_SCOPES.join('|')}`)
+    }
+    const themeIds = leanThemeIdsFromReview(review)
+    const current = unitOrThrow(manifest, unitId).units.find((entry) => entry.id === unitId)
+    assertNoPendingReviewBreaker(current, 'record-review-round')
+    const typedWrite = derivedChangedSurfaces !== undefined
+    const entry = typedWrite ? {
+      round: review.round,
+      verdict: review.verdict,
+      headSha: review.headSha,
+      changedSurfaces: review.changedSurfaces,
+      reviewSubject: review.reviewSubject,
+      themeIds,
+      authorizationBoundary: review.authorizationBoundary,
+      ...(review.evidenceClasses ? { evidenceClasses: review.evidenceClasses } : {}),
+      ...(review.reopenReason ? { reopenReason: review.reopenReason } : {}),
+      ...(review.scope ? { scope: review.scope } : {}),
+    } : {
+      round: review.round,
+      verdict: review.verdict,
+      headSha: review.headSha,
+      productionMoved: false,
+      ...(themeIds.length ? { themeIds } : {}),
+      ...(review.scope ? { scope: review.scope } : {}),
+    }
+    const logged = recordRound(manifest, unitId, entry, { derivedChangedSurfaces })
+    const { units, index } = unitOrThrow(logged, unitId)
+    units[index].lastVerdict = review.verdict
+    units[index].lastReviewedSha = review.headSha
+    return settleBreakerOrThrow(manifest, unitId, logged)
+  }
+
+  // ---- deep path, plus the typed universal round entry ----
+  const reviewAllowed = new Set([
+    'round', 'verdict', 'summary', 'overall_correctness', 'findings', 'overMockFindings',
+    'previousFindingsResolution', 'reviewModel', 'independent', 'contractValidates', 'round1Depth',
+    // #792: headSha was the dual-schema trap — record-round accepted it, this command
+    // rejected it. Accept and persist on the history entry; it does not change matrix rules.
+    'headSha', 'scope', 'themeIds', 'changedSurfaces', 'reviewSubject',
+    'evidenceClasses', 'reopenReason', 'authorizationBoundary',
+  ])
+  const unknownReviewKeys = Object.keys(review).filter((key) => !reviewAllowed.has(key))
+  if (unknownReviewKeys.length) throw new Error(`review round has unknown property: ${unknownReviewKeys[0]}`)
+  if (review.headSha !== undefined && !nonEmptyString(review.headSha)) {
+    throw new Error('headSha must be a non-empty string when present')
+  }
+  const {
+    round: _round, round1Depth, headSha, scope: _scope, themeIds: _themeIds,
+    changedSurfaces: _changedSurfaces, reviewSubject: _reviewSubject,
+    evidenceClasses: _evidenceClasses, reopenReason: _reopenReason,
+    authorizationBoundary: _authorizationBoundary, ...reviewDocument
+  } = review
+  const reviewErrors = validateReviewDocument(reviewDocument)
+  if (reviewErrors.length) throw new Error(reviewErrors[0])
+  if (round1Depth !== undefined) {
+    const depthErrors = validateRound1Depth(round1Depth)
+    if (depthErrors.length) throw new Error(depthErrors[0])
+  }
+  const themes = uniqueThemes(review.findings.map(themeFromFinding))
+  const out = clone(manifest)
+  const { units, index } = unitOrThrow(out, unitId)
+  const unit = units[index]
+  assertMigratedUnit(unit, 'record-review-round')
+  assertNoPendingReviewBreaker(unit, 'record-review-round')
+  const persistedErrors = validateUnitRoundState(unit, deliveryMode(out), deliveryProvider(out))
+  if (persistedErrors.length) throw new Error(`cannot record review round from invalid persisted state: ${persistedErrors[0]}`)
+  unit.reviewHistory = Array.isArray(unit.reviewHistory) ? unit.reviewHistory : []
+  const previous = unit.reviewHistory.at(-1)
+  const expectedRound = previous ? previous.round + 1 : 1
+  if (review.round !== expectedRound) throw new Error(`review round ${review.round} must advance exactly from ${previous?.round || 0} to ${expectedRound}`)
+  const entry = {
+    round: review.round,
+    verdict: review.verdict,
+    themes: themes.map(persistedTheme),
+    ...(round1Depth === undefined ? {} : { round1Depth: clone(round1Depth) }),
+    ...(nonEmptyString(headSha) ? { headSha } : {}),
+  }
+  const preexistingDeepHistoryWithoutRoundLog = unit.reviewHistory.length > 0 && !Array.isArray(unit.rounds)
+  if (derivedChangedSurfaces !== undefined && preexistingDeepHistoryWithoutRoundLog) {
+    throw new Error('legacy deep reviewHistory has no universal typed rounds; reconstruct explicit unknown round classifications before appending a new review')
+  }
+  unit.reviewHistory.push(entry)
+  if (derivedChangedSurfaces !== undefined) {
+    if (!nonEmptyString(headSha)) throw new Error('typed deep review round requires headSha')
+    const logged = recordRound(out, unitId, {
+      round: review.round,
+      verdict: review.verdict,
+      headSha,
+      changedSurfaces: review.changedSurfaces,
+      reviewSubject: review.reviewSubject,
+      themeIds: themes.map((theme) => theme.id),
+      authorizationBoundary: review.authorizationBoundary,
+      ...(review.evidenceClasses ? { evidenceClasses: review.evidenceClasses } : {}),
+      ...(review.reopenReason ? { reopenReason: review.reopenReason } : {}),
+      ...(review.scope ? { scope: review.scope } : {}),
+    }, { derivedChangedSurfaces })
+    const typedUnit = logged.units.find((candidate) => candidate.id === unitId)
+    typedUnit.lastVerdict = review.verdict
+    typedUnit.lastReviewedSha = headSha
+    return candidateOrThrow(manifest, unitId, logged)
+  }
+  return candidateOrThrow(manifest, unitId, out)
+}
+
+// The independent-review workflow emits this envelope. unitId routes the
+// result and is deliberately not persisted inside reviewHistory; round1Depth
+// is review evidence and is deliberately persisted. The adapter owns the only
+// documented reshaping: it derives the next append-only round from durable
+// history, then delegates to the same transition used by direct reviews.
+export function recordWorkflowReviewResult(manifest, intendedUnitId, result, { derivedChangedSurfaces } = {}) {
+  if (!isObject(result)) throw new Error('workflow review result must be an object')
+  const allowed = new Set([
+    'unitId', 'verdict', 'summary', 'overall_correctness', 'findings', 'overMockFindings',
+    'previousFindingsResolution', 'reviewModel', 'independent', 'contractValidates', 'round1Depth',
+    'headSha', 'reviewSubject', 'evidenceClasses', 'reopenReason', 'authorizationBoundary', 'changedSurfaces',
+  ])
+  const unknown = Object.keys(result).find((key) => !allowed.has(key))
+  if (unknown) throw new Error(`workflow review result has unknown property: ${unknown}`)
+  const missing = WORKFLOW_REVIEW_REQUIRED.find((key) => !Object.prototype.hasOwnProperty.call(result, key))
+  if (missing) throw new Error(`workflow review result requires ${missing}`)
+  if (!nonEmptyString(result.unitId)) throw new Error('workflow review result requires a non-empty unitId')
+  if (result.unitId !== intendedUnitId) {
+    throw new Error(`workflow review result unitId ${result.unitId} does not match intended unit ${intendedUnitId}`)
+  }
+  const { units } = unitOrThrow(manifest, result.unitId)
+  const unit = units.find((entry) => entry.id === result.unitId)
+  const depthErrors = validateRound1Depth(result.round1Depth)
+  if (depthErrors.length) throw new Error(depthErrors[0])
+  const { unitId: _unitId, ...reviewDocument } = result
+  const nextRound = (unit.reviewHistory?.at(-1)?.round || 0) + 1
+  return recordReviewRound(manifest, result.unitId, { ...reviewDocument, round: nextRound }, { derivedChangedSurfaces })
+}
+
+// Explicit v1 migration. Nothing is sorted, inferred, narrowed, or rewritten
+// unless a legacy fix theme maps to exactly one reviewed snapshot.
+// The human's answer to a fired breaker. Recording it is the ONLY way to unblock the
+// next transition, which is what makes the breaker a gate rather than prose. The decision
+// may be the human's or, for the two reversible ones, the loop's own (autoBreakerDecision).
+export function recordBreakerDecision(manifest, unitId, decision) {
+  if (!isObject(decision)) throw new Error('breaker decision must be an object')
+  const out = clone(manifest)
+  const { units, index } = unitOrThrow(out, unitId)
+  const unit = units[index]
+  const completedRounds = completedReviewRounds(unit)
+  // The precondition is exit-reachability: a fresh decision is authorized whenever a
+  // breaker is PENDING — `pendingBreaker(unit)` non-null. That covers both a raw firing
+  // (BREAKER_ROUND_LIMIT completed rounds with no PASS) and a re-fired one (an exhausted
+  // "continue"), and only those — a healthy unit (pendingBreaker null) cannot stamp a
+  // decision.
+  const pending = pendingBreaker(unit)
+  if (!pending) {
+    throw new Error(`record-breaker-decision requires a pending circuit-breaker on ${unitId}: ${BREAKER_ROUND_LIMIT} completed review rounds with no passing review, or a re-fired breaker (an exhausted "continue"); ${unitId} has ${completedRounds} rounds with no breaker pending`)
+  }
+  // Every firing is a review-rounds firing now — the produce-pass threshold was removed
+  // (see BREAKER_FIRED_ON). The code never writes `'produce-passes'`.
+  const firedOn = 'review-rounds'
+  // Two guards on `autoApplied`, ceiling first because it is the more specific reason: at
+  // the ceiling BOTH would refuse, and "you are past the round ceiling" tells the caller
+  // what to do, while "the log authorizes only continue" is true but hides why continue is
+  // nonetheless unavailable.
+  //
+  // The grind bound. Autonomy removed the human stop that used to bound the loop, so the
+  // ceiling is what replaces it — and it binds the AUTONOMOUS path only: a human at the
+  // keyboard on round 9 has already seen the round count and is making an informed call,
+  // which is precisely the state the breaker wanted to reach. What must be unreachable is
+  // the loop granting ITSELF round 9 (epic-848: nine rounds, ~6.5 unattended hours).
+  if (decision.autoApplied === true && completedRounds >= BREAKER_TOTAL_ROUND_CEILING) {
+    throw new Error(`record-breaker-decision refused: ${completedRounds} review rounds on ${unitId} is at or past the autonomous ceiling of ${BREAKER_TOTAL_ROUND_CEILING} — no auto-decision above it. This unit has spent more rounds than any observed unit that converged; hand the human a split/descope decision (record it without autoApplied once they answer).`)
+  }
+  // `autoApplied` is a provenance claim — "the loop decided this, nobody was asked" — so it
+  // has to be true, not merely well-formed. The CLI's `--auto` path always passes what
+  // autoBreakerDecision computed, but the library path takes any object, and a hand-written
+  // {decision:'continue', autoApplied:true} against a diagnosis that says `split` recorded
+  // clean. Worse, when the diagnosis is `insufficient-data` the validate-time warning is
+  // silent too (it needs a recommendation to compare against), so the manifest ends up
+  // asserting the loop made a call it was never entitled to make, with nothing anywhere
+  // contradicting it. Re-deriving the decision here is the only check that closes both.
+  // Both knobs, and the level is NOT optional here. Omitting it re-derives at
+  // autoBreakerDecision's `supervised` default, which authorizes only the always-auto
+  // decisions — so the guard refused every auto-applied `split` on every run, including
+  // the `autonomous` runs that had just computed one. The CLI's `--auto` path passed the
+  // real level to autoBreakerDecision and then handed the result to this guard, which
+  // re-derived it at a level nobody was on: a feature that could be computed but never
+  // written. Reading the level off the manifest keeps one source for it. An absent or
+  // typo'd value fails closed — `autoDecisionAllowed` authorizes on `=== 'autonomous'`
+  // and nothing else — so this cannot silently widen what may be auto-applied.
+  // The level the guard actually authorized against, stamped onto the record below. It is
+  // not read off `decision`: a caller that could assert its own authorization would make
+  // the stamp decorative, and `validateBreaker` refuses an auto-applied `split` that does
+  // not carry it — so a record built without this is one the very next read rejects. That
+  // was the other half of the same dead feature: the guard could be made to pass and the
+  // write still failed validation, because `next` never carried the field.
+  let autonomyAtDecision
+  if (decision.autoApplied === true) {
+    const authorized = autoBreakerDecision(unit, { autonomy: out.breakerAutonomy ?? 'auto', autonomyLevel: out.autonomy })
+    if (!authorized || authorized.decision !== decision.decision) {
+      const d = diagnoseBreaker(unit)
+      throw new Error(`record-breaker-decision refused: "${decision.decision}" cannot be recorded as autoApplied on ${unitId} — the round log diagnoses "${d.signal}"${d.recommendation ? ` and authorizes only "${d.recommendation}"` : ' and authorizes no autonomous decision'}. Record it without autoApplied if a human made this call; autoApplied claims the loop decided it.`)
+    }
+    autonomyAtDecision = authorized.autonomyAtDecision
+  }
+  const next = {
+    firedAtRound: completedRounds,
+    firedOn,
+    decision: decision.decision,
+    diagnosis: decision.diagnosis,
+    decidedAt: decision.decidedAt,
+    ...(decision.autoApplied === true ? { autoApplied: true } : {}),
+    ...(nonEmptyString(autonomyAtDecision) ? { autonomyAtDecision } : {}),
+    ...(nonEmptyString(decision.signal) ? { signal: decision.signal } : {}),
+    ...(nonEmptyString(decision.classCompleteFor) ? { classCompleteFor: decision.classCompleteFor } : {}),
+    // Stamp the contract pointer this firing was decided against. record-intake-reentry
+    // compares against it to prove a "design" decision's input actually landed before it
+    // grants a fresh budget — a decision the human made, not a document, buys nothing.
+    contractShaAtDecision: isObject(unit.contractRevision) && nonEmptyString(unit.contractRevision.sha) ? unit.contractRevision.sha : null,
+    ...(decision.decision === 'continue' ? { authorizedThroughRound: completedRounds + 1 } : {}),
+  }
+  const errors = validateBreaker({ breaker: next })
+  if (errors.length) throw new Error(errors[0])
+  // Append-only audit trail: a unit that fires the breaker, re-enters intake, and
+  // gets stuck again fires it a SECOND time — and the whole point of the breaker is
+  // the forensic record of *why* it went around twice. Archive the prior decision
+  // before overwriting `breaker` (which the round-budget logic reads as "current"),
+  // so no diagnosis is ever lost. (Review finding: a single object silently
+  // discarded the first firing.)
+  if (isObject(unit.breaker)) {
+    unit.breakerLog = Array.isArray(unit.breakerLog) ? unit.breakerLog : []
+    unit.breakerLog.push(unit.breaker)
+  }
+  unit.breaker = next
+  return settleBreakerOrThrow(manifest, unitId, out)
+}
+
+// Set reviewedContractSha to the unit's CURRENT contractRevision.sha — the writer
+// the review found missing (a reader with no writer left the field hand-set, so a
+// wrong/premature value could silently mark a stale review as current). Call it
+// only after a full-scope review actually completed against the current contract;
+// it can then only ever record "reviewed against the contract that is current now",
+// which is exactly the freshness gate's exit condition. Requires a contractRevision
+// to point at — there is nothing to have reviewed against otherwise.
+export function recordReviewedContract(manifest, unitId) {
+  const out = clone(manifest)
+  const { units, index } = unitOrThrow(out, unitId)
+  const unit = units[index]
+  const cr = isObject(unit.contractRevision) ? unit.contractRevision : null
+  if (!cr || !nonEmptyString(cr.sha)) throw new Error(`record-reviewed-contract requires units[${unitId}].contractRevision.sha (nothing to have reviewed against)`)
+  unit.reviewedContractSha = cr.sha
+  return out
+}
+
+// Re-entering intake (after a design pass, split, or descope) is what unblocks the
+// loop again, and it grants a fresh round budget measured from where the breaker
+// fired. It is recorded, not cleared: the fired-and-decided history is the audit
+// trail for why the unit went around twice.
+export function recordIntakeReentry(manifest, unitId, { reenteredAt } = {}) {
+  const out = clone(manifest)
+  const { units, index } = unitOrThrow(out, unitId)
+  const unit = units[index]
+  const breaker = isObject(unit.breaker) ? unit.breaker : null
+  if (!breaker) throw new Error(`record-intake-reentry requires a recorded breaker decision on ${unitId}`)
+  if (breaker.decision === 'continue') throw new Error('a "continue" decision authorizes another round directly; intake re-entry applies to design/split/descope')
+  if (breaker.reenteredAt) throw new Error(`${unitId} has already re-entered intake at ${breaker.reenteredAt}`)
+  // A decision that ALREADY spent a re-entry on this unit cannot buy a second one. The
+  // archive was built to record a unit that "fires, re-enters intake, and gets stuck
+  // again" — this refuses the third lap. The first re-entry demonstrably did not change
+  // the input, so repeating it is not a decision, it is the same loop with a fresh
+  // budget. The human still has the other decisions; what they cannot do is re-buy this
+  // one. (Named incident: epic-986 unit #996 — fired -> "design" -> re-entry -> fired
+  // again at review round 4 -> "design" -> re-entry, both firings correctly diagnosing the
+  // same unwritten trust boundary. The second firing produced the answer the first
+  // re-entry should have carried; two full budgets bought it.)
+  const spent = (Array.isArray(unit.breakerLog) ? unit.breakerLog : [])
+    .find((entry) => isObject(entry) && entry.decision === breaker.decision && nonEmptyString(entry.reenteredAt))
+  if (spent) {
+    throw new Error(`${unitId} already re-entered intake on a "${breaker.decision}" decision at ${spent.reenteredAt} and fired again — a repeat "${breaker.decision}" is a hand-back, not a re-entry. Take a different decision (split/descope/continue) or hand the unit to the human.`)
+  }
+  // A "design" re-entry is authorized by the design ARTIFACT, not by the word. The
+  // decision names the remedy; only a contract pointer that moved proves the remedy
+  // landed. Absent that, the producer re-enters against the same unwritten contract that
+  // fired the breaker — which is exactly how a unit buys a second identical firing.
+  // A legacy firing (field absent) reads as null: it still owes a pointer, just no delta.
+  if (breaker.decision === 'design') {
+    const sha = isObject(unit.contractRevision) && nonEmptyString(unit.contractRevision.sha) ? unit.contractRevision.sha : null
+    const atDecision = breaker.contractShaAtDecision === undefined ? null : breaker.contractShaAtDecision
+    if (!sha) {
+      throw new Error(`a "design" re-entry on ${unitId} requires units[].contractRevision.sha — the approved design input on the target branch. Land the ADR (\`/grill-with-docs\`), record the pointer with \`record-reviewed-contract\`'s source, then re-enter.`)
+    }
+    if (sha === atDecision) {
+      throw new Error(`${unitId} still points at contractRevision.sha ${sha}, the same contract the breaker fired against — the design decision's input has not landed. Re-entering here re-runs the producer against the contract that fired the breaker.`)
+    }
+  }
+  unit.breaker = { ...breaker, reenteredAt: reenteredAt || new Date().toISOString() }
+  return settleBreakerOrThrow(manifest, unitId, out)
+}
+
+// ---- delivery gate ----
+
+// Absent `deliveryMode` reads as 'direct': a manifest written before this gate ran the
+// legacy `gh pr merge` path, so that is what it means (the `firedOn` precedent).
+export function deliveryMode(manifest) {
+  const mode = manifest?.deliveryMode
+  return mode === undefined || mode === null ? 'direct' : mode
+}
+
+export function validateDeliveryAttempt(attempt, mode, label = 'delivery attempt', provider = null) {
+  if (!isObject(attempt)) return [`${label} must be an object`]
+  const flow = DELIVERY_FLOWS[deliveryFlowKey(mode, provider)] ?? null
+  // The field allowlist is PER FLOW, not shared. A queue field on a direct attempt means
+  // the run believes it is enqueueing when it is really calling `gh pr merge` — the
+  // silent wrong-mode failure detect-delivery-mode exists to catch, and nothing
+  // downstream said a word about it. Safe to tighten: `delivery` was written 0 times in
+  // 522 audited units, so there is no legacy shape to preserve here.
+  const allowedFields = flow ? flow.attemptFields : ['at', 'action', 'headSha', 'outcome', 'reason', 'rawReason', 'detail', 'queueState', 'ack', 'unmetConditions', 'pr']
+  const errors = Object.keys(attempt)
+    .filter((key) => !allowedFields.includes(key))
+    .map((key) => `${label} has unknown property: ${key}${flow ? ` for the "${flow.key}" flow (allowed: ${allowedFields.join(', ')})` : ''}`)
+  if (!nonEmptyString(attempt.at)) errors.push(`${label}.at is required`)
+  if (!nonEmptyString(attempt.headSha)) errors.push(`${label}.headSha is required — a delivery attempt is against an exact HEAD`)
+  const allowed = DELIVERY_ACTIONS[mode] || []
+  if (!allowed.includes(attempt.action)) {
+    errors.push(`${label}.action "${attempt.action}" is not a "${mode}" action (expected ${allowed.join('|')}) — the run's delivery mode decides the merge path`)
+  }
+  if (!DELIVERY_ATTEMPT_OUTCOMES.includes(attempt.outcome)) {
+    errors.push(`${label}.outcome must be one of ${DELIVERY_ATTEMPT_OUTCOMES.join('|')} — enqueue path: requested (command posted, no ack yet) → waiting (ack or queue membership) → merged|dequeued|rejected`)
+  }
+  // `requested` is enqueue-only: the first post of the command, before any ack.
+  if (attempt.outcome === 'requested' && attempt.action !== 'enqueue') {
+    errors.push(`${label}.outcome "requested" is only legal on action "enqueue" (got "${attempt.action}") — it means the enqueue command was posted`)
+  }
+  // A dequeue/rejection without a reason is the failure this taxonomy exists to prevent:
+  // "it came back out" collapses a fix round and a hand-back into one indistinguishable
+  // retry. The reason is READ from the queue tool, never inferred by the orchestrator —
+  // which is why `rawReason` (the tool's own string) is what the routing table consumes,
+  // and `reason` is the routing class it maps to.
+  if (attempt.outcome === 'dequeued' || attempt.outcome === 'rejected') {
+    if (!DELIVERY_DEQUEUE_REASONS.includes(attempt.reason)) {
+      errors.push(`${label}.reason must be one of ${DELIVERY_DEQUEUE_REASONS.join('|')} when the attempt did not merge — read it from the queue tool, never infer it (put the tool's own string in rawReason and map it with dequeueRouting)`)
+    }
+    if (!nonEmptyString(attempt.detail)) errors.push(`${label}.detail is required on a non-merge outcome — quote the tool verbatim`)
+    // The mapping must be honest in both directions: a rawReason that routes somewhere
+    // else than the recorded class is how a hand-back gets filed as a fix round.
+    if (nonEmptyString(attempt.rawReason)) {
+      const routed = dequeueRouting(attempt.rawReason)
+      if (routed.known && routed.canonical !== attempt.reason) {
+        errors.push(`${label}.reason "${attempt.reason}" contradicts rawReason "${attempt.rawReason}", which routes to "${routed.canonical}" — record what the queue said, not what you expected it to say`)
+      }
+    }
+  } else if (attempt.reason !== undefined) {
+    errors.push(`${label}.reason applies only to a dequeued/rejected attempt`)
+  }
+  // The acknowledgement, where the provider has one. An enqueue whose command was never
+  // read sits in exactly the same manifest shape as one the queue is actively holding —
+  // epic-986's "waiting for queue conditions" one layer up, and the 👍 is the only thing
+  // that tells them apart. `requested` deliberately does NOT require ack (#946) — that is
+  // how the first post is recorded before Mergify reacts.
+  if (flow?.supportsAck && attempt.action === 'enqueue' && attempt.outcome === 'waiting') {
+    if (!isObject(attempt.ack) || !nonEmptyString(attempt.ack.ref)) {
+      errors.push(`${label}.ack {kind, ref} is required for a "${flow.key}" enqueue recorded as waiting — the queue acknowledges the command (👍 reaction / its status comment), and without that evidence "queued" and "nobody read the comment" are the same record. Use outcome "requested" when the command was posted but not yet acked.`)
+    } else if (!['reaction', 'payload'].includes(attempt.ack.kind)) {
+      errors.push(`${label}.ack.kind must be "reaction" or "payload" (got ${JSON.stringify(attempt.ack.kind)})`)
+    }
+  } else if (attempt.ack !== undefined && attempt.outcome === 'requested') {
+    errors.push(`${label}.ack is not legal on outcome "requested" — that outcome means no ack yet; promote to "waiting" once ack or queue membership is observed`)
+  } else if (attempt.ack !== undefined && flow && !flow.supportsAck) {
+    // Only when the flow is RESOLVED. An unresolved flow (queue mode, provider not yet
+    // settled) knows nothing about acknowledgements either way, and rejecting the field
+    // there would turn "we have not settled the provider" into "this record is corrupt" —
+    // wedging exactly the resumed run that still needs to write its state.
+    errors.push(`${label}.ack is not meaningful in the "${flow.key}" flow — that provider's enqueue is an API call whose return value is the acknowledgement`)
+  }
+  return errors
+}
+
+export function validateDelivery(unit, mode, provider = null) {
+  const d = unit?.delivery
+  if (d === undefined || d === null) return []
+  if (!isObject(d)) return ['delivery must be an object']
+  // `mergedAt` is the PR's own merge time (GitHub `mergedAt` / verified-merge clock).
+  // Optional, recorded so postmortem can distinguish queue-wait from late bookkeeping
+  // (#791 / issue-664 / identity#669 hybrid merge unobserved).
+  const errors = Object.keys(d)
+    .filter((key) => !['attempts', 'outcome', 'mergedSha', 'mergedAt', 'blockedOn', 'watch'].includes(key))
+    .map((key) => `delivery has unknown property: ${key}`)
+  if (d.watch !== undefined && d.watch !== null) {
+    if (!isObject(d.watch)) errors.push('delivery.watch must be an object')
+    else {
+      errors.push(...Object.keys(d.watch)
+        .filter((key) => !['firstObservedAt', 'lastObservedAt', 'lastChangeAt', 'queueState', 'position', 'polls', 'nudges', 'unmetConditions'].includes(key))
+        .map((key) => `delivery.watch has unknown property: ${key}`))
+      for (const f of ['firstObservedAt', 'lastObservedAt', 'lastChangeAt']) {
+        if (!nonEmptyString(d.watch[f])) errors.push(`delivery.watch.${f} is required`)
+      }
+      if (!nonEmptyString(d.watch.queueState)) errors.push('delivery.watch.queueState is required — the state read from the queue, never inferred')
+      // A watch only means something where there is a queue to watch. In `direct` mode the
+      // merge is synchronous, so a watch record means the run thinks it is enqueueing while
+      // it is really calling `gh pr merge` — wrong-mode, failing silently, which is the
+      // whole reason the mode is probed at pre-flight rather than assumed.
+      if (mode === 'direct') {
+        errors.push('delivery.watch is not meaningful in "direct" mode — a direct merge is synchronous and has no queue to observe; a watch here means the run\'s deliveryMode does not match the repo')
+      }
+      if (d.watch.nudges !== undefined) {
+        if (!Array.isArray(d.watch.nudges)) errors.push('delivery.watch.nudges must be an array')
+        else {
+          d.watch.nudges.forEach((n, i) => {
+            if (!isObject(n) || !nonEmptyString(n.at) || !nonEmptyString(n.command)) {
+              errors.push(`delivery.watch.nudges[${i}] requires {at, command} — a nudge nobody can point at is indistinguishable from a poll`)
+            }
+          })
+          if (d.watch.nudges.length > DELIVERY_MAX_NUDGES) {
+            errors.push(`delivery.watch.nudges has ${d.watch.nudges.length} entries (max ${DELIVERY_MAX_NUDGES}) — the nudge is one bounded re-evaluation request, not a poll loop that keeps a wedged unit looking alive`)
+          }
+        }
+      }
+      if (d.watch.unmetConditions !== undefined && d.watch.unmetConditions !== null
+          && (!Array.isArray(d.watch.unmetConditions) || !d.watch.unmetConditions.every(nonEmptyString))) {
+        errors.push('delivery.watch.unmetConditions must be an array of strings — the queue\'s own unmet leaves, quoted verbatim so a hand-back can name one')
+      }
+    }
+  }
+  if (d.attempts !== undefined) {
+    if (!Array.isArray(d.attempts)) errors.push('delivery.attempts must be an array')
+    else d.attempts.forEach((a, i) => errors.push(...validateDeliveryAttempt(a, mode, `delivery.attempts[${i}]`, provider)))
+  }
+  if (d.outcome !== undefined && d.outcome !== null && !DELIVERY_OUTCOMES.includes(d.outcome)) {
+    errors.push(`delivery.outcome must be one of ${DELIVERY_OUTCOMES.join('|')} or null`)
+  }
+  // The whole point of the gate: "merged" is a claim about the target branch, so it owes
+  // the SHA that landed. `combine-and-verify.mjs delivered` is what proves containment
+  // live; this refuses the claim that has no SHA to check.
+  if (d.outcome === 'merged' && !nonEmptyString(d.mergedSha)) {
+    errors.push('delivery.outcome "merged" requires delivery.mergedSha — the commit verified present in the fetched target branch')
+  }
+  if (d.outcome === 'handed-back' && !nonEmptyString(d.blockedOn)) {
+    errors.push('delivery.outcome "handed-back" requires delivery.blockedOn — the unsatisfied condition, quoted from the merge tool')
+  }
+  return errors
+}
+
+// A legacy-shape round stays readable forever, but it CANNOT become component evidence:
+// `record-component-candidate` requires a typed `reviewSubject` on the unit's latest round,
+// and a legacy record projects to `unknown`. The round log is append-only, so by the time
+// the component gate refuses, the omission can no longer be repaired — the only routes left
+// are a fabricated second round at the same head (the epic-25 double-record pathology) or
+// hand-editing a protected log. Both are worse than the bug they would paper over.
+//
+// Hence a warning at the one moment it is still cheap to act on: the unit has reached
+// merge-ready, so its PASS is written and the component candidate is the very next step.
+// fmm-express epic-894 wrote all three units with the legacy shape, validated clean at every
+// checkpoint, and hit the dead end ~4h later at delivery with the merge gate unreachable and
+// no way back. Nothing between the write and the refusal said a word.
+export function legacyRoundWarnings(unit) {
+  if (unit?.status !== 'merge-ready') return []
+  const latest = (Array.isArray(unit.rounds) ? unit.rounds : []).at(-1)
+  if (!isObject(latest) || !classifyRoundMetadata(latest).legacy) return []
+  return [`${unit.id ?? 'unit'} latest round is the legacy shape (reviewSubject projects to "unknown") — `
+    + 'record-component-candidate will refuse this unit, and the round log is append-only so this cannot be '
+    + 'repaired later. Record rounds with typed reviewSubject + authorizationBoundary (references/loop.md).']
+}
+
+// A merge-ready unit whose delivery has not reached a terminal outcome is IN-FLIGHT, not
+// delivered. Mid-run that is legal, so this is a warning; the handoff is where it becomes
+// a finding, because "merge-ready" read as "done" is exactly how epic-986 reported four
+// units as finished while `mergedSha` was null on every one of them.
+export function deliveryWarnings(unit, { now, boundMinutes, flow = null } = {}) {
+  if (unit?.status !== 'merge-ready') return []
+  const delivery = isObject(unit.delivery) ? unit.delivery : null
+  const outcome = delivery ? delivery.outcome : null
+  if (outcome === 'merged' || outcome === 'handed-back') return []
+  const warnings = [`${unit.id ?? 'unit'} is merge-ready with no terminal delivery outcome — undelivered, not done`]
+  // A stalled or explicitly-blocked watch is the actionable half of that: it says the
+  // wait is not going to resolve itself, which is the difference between "in flight"
+  // and "wedged" — precisely what twelve hours of epic-986 could not distinguish.
+  // `nudge-due` and `not-enqueued` are actionable too, but they name a cheap action
+  // instead of a hand-back, so they read differently.
+  const status = watchStatus(delivery?.watch, { now, boundMinutes, flow })
+  if (status.state === 'stalled' || status.state === 'blocked' || status.state === 'unknown') {
+    warnings.push(`${unit.id ?? 'unit'} delivery watch is ${status.state}: ${status.reason}`)
+  }
+  if (status.state === 'nudge-due' || status.state === 'not-enqueued') {
+    warnings.push(`${unit.id ?? 'unit'} delivery watch is ${status.state} (action: ${status.action}): ${status.reason}`)
+  }
+  warnings.push(...deliveryHeadDriftWarnings(unit))
+  if (status.boundWarning) warnings.push(`${unit.id ?? 'unit'}: ${status.boundWarning}`)
+  return warnings
+}
+
+export function recordDeliveryAttempt(manifest, unitId, attempt) {
+  const out = clone(manifest)
+  const { units, index } = unitOrThrow(out, unitId)
+  const unit = units[index]
+  if (effectiveUnitKind(unit) !== 'implementation') {
+    throw new Error(`record-delivery-attempt is only for implementation units; ${unitId} is ${effectiveUnitKind(unit)}`)
+  }
+  const blockedOn = completionBlockers(out, unit)
+  if (blockedOn.length) {
+    throw new Error(`record-delivery-attempt refuses ${unitId}: completion dependency ${blockedOn.join(', ')} is not complete`)
+  }
+  const mode = deliveryMode(out)
+  const provider = deliveryProvider(out)
+  if (!DELIVERY_MODES.includes(mode)) throw new Error(`deliveryMode must be one of ${DELIVERY_MODES.join('|')}`)
+  // A queue run whose provider is unknown cannot be delivered mechanically: the enqueue
+  // command, the state source, and whether a nudge or ack even exists all differ between
+  // Mergify and GitHub's native queue. Refuse HERE rather than at pre-flight, so a legacy
+  // manifest can still be read, resumed and reported — it is stopped only at the moment
+  // it would take a provider-specific action.
+  if (mode === 'queue' && !QUEUE_PROVIDERS.includes(provider)) {
+    throw new Error(`record-delivery-attempt on a "queue" run requires queueProvider (${QUEUE_PROVIDERS.join('|')}) — the mode picks the state machine, the provider picks the mechanics; settle it with detect-delivery-mode.mjs and \`set <slug> queueProvider <${QUEUE_PROVIDERS.join('|')}>\``)
+  }
+  if (unit.status !== 'merge-ready') {
+    throw new Error(`record-delivery-attempt requires ${unitId} to be merge-ready (it is "${unit.status}") — delivery is the exit from merge-ready, not a way into it`)
+  }
+  const delivery = isObject(unit.delivery) ? unit.delivery : { attempts: [], outcome: null, mergedSha: null, blockedOn: null }
+  if (delivery.outcome === 'merged' || delivery.outcome === 'handed-back') {
+    throw new Error(`${unitId} already reached the terminal delivery outcome "${delivery.outcome}"`)
+  }
+  const errors = validateDeliveryAttempt(attempt, mode, 'delivery attempt', provider)
+  if (errors.length) throw new Error(errors[0])
+  const attempts = Array.isArray(delivery.attempts) ? [...delivery.attempts] : []
+  // Re-entry to the merge path is EARNED by a fix and a fresh verdict, never repeated by
+  // the orchestrator. The queue already retries what should be retried (a red batch is
+  // bisected and the innocent PRs carry on); what it deliberately does not retry is a PR
+  // whose own checks failed, because that loops forever on broken code. So an attempt at
+  // an unchanged HEAD after a non-merge outcome is refused here rather than left to
+  // judgment.
+  // Check EVERY prior attempt, not just the last: A -> B -> A is the same unchanged-HEAD
+  // retry wearing a detour, and `attempts.at(-1)` alone let it through.
+  // Recording that the queue MERGED this HEAD is an observation of success, not a retry
+  // of a failed path — the rule's whole rationale ("do not retry what the queue
+  // deliberately did not retry") does not reach it. Exempting it also keeps the happy
+  // path recordable after an honest in-flight `waiting` attempt at the same HEAD.
+  //
+  // #946 / epic-867 carve-out: ONE re-request at the same HEAD is allowed when every
+  // prior attempt at that HEAD is still pre-admission (`requested`, or `waiting` with
+  // queueState `not-enqueued`). That is a re-post of a command that never admitted the
+  // PR — not a retry of a failed merge of broken code. A second re-request, or any prior
+  // dequeued/rejected at that HEAD, still refuses.
+  const priorAtSha = attempt.outcome === 'merged'
+    ? null
+    : attempts.find((a) => a.outcome !== 'merged' && a.headSha === attempt.headSha)
+  if (priorAtSha) {
+    const preAdmission = (a) => a.outcome === 'requested'
+      || (a.outcome === 'waiting' && a.queueState === 'not-enqueued')
+    const priorsAtSha = attempts.filter((a) => a.outcome !== 'merged' && a.headSha === attempt.headSha)
+    const allPreAdmission = priorsAtSha.every(preAdmission)
+    const reRequest = (attempt.outcome === 'requested' || attempt.outcome === 'waiting')
+      && allPreAdmission
+      && priorsAtSha.length === 1
+    if (!reRequest) {
+      const because = priorAtSha.reason ? ` (${priorAtSha.reason})` : ''
+      throw new Error(`${unitId} already attempted delivery at ${attempt.headSha} and it came back "${priorAtSha.outcome}"${because} — the skill does not retry the merge path at an unchanged HEAD; fix and earn a fresh verdict, or hand back. (One re-queue is allowed only when the prior attempt was pre-admission: outcome requested, or waiting with queueState not-enqueued.)`)
+    }
+  }
+  attempts.push(attempt)
+  unit.delivery = { ...delivery, attempts }
+  // Routing is mechanized rather than described, and it is now driven by the TABLE rather
+  // than by one hardcoded reason. Two classes send the unit back through the loop:
+  //   checks-failed          the queue tested PR-merged-with-base and it failed — new
+  //                          information about the tree that would land
+  //   pull-request-updated   HEAD moved under the queue (our own push ejected it), so the
+  //                          last verdict is stale by guarantee 3
+  // Clearing merge-ready is what forces the fresh verdict; everything else stays
+  // merge-ready and terminates as a hand-back or an evidence-lane rebase.
+  if (attempt.outcome === 'dequeued' || attempt.outcome === 'rejected') {
+    const routed = nonEmptyString(attempt.rawReason) ? dequeueRouting(attempt.rawReason) : { route: DELIVERY_DEQUEUE_ROUTES[attempt.reason]?.route ?? 'hand-back' }
+    if (routed.route === 'fresh-verdict') unit.status = 'in-progress'
+  }
+  return settleBreakerOrThrow(manifest, unitId, out)
+}
+
+// Is this watch progressing, explicitly blocked, or wedged? Pure, so the bound can be
+// reasoned about (and tested) without a clock or a queue.
+export function watchStatus(watch, { now, boundMinutes = DELIVERY_WATCH_BOUND_MINUTES, flow = null } = {}) {
+  // A non-numeric bound (`"45m"` from a hand-edited manifest) made every comparison
+  // `x > NaN` — false — so the watchdog silently never fired. One typo disabled the
+  // guard while it still looked configured, which is worse than having no guard.
+  // Fail CLOSED: an unusable bound falls back to the default and says so.
+  let bound = boundMinutes
+  let coerced = null
+  if (typeof bound !== 'number' || !Number.isFinite(bound) || bound <= 0) {
+    coerced = `deliveryWatchBoundMinutes ${JSON.stringify(boundMinutes)} is not a positive number — falling back to the ${DELIVERY_WATCH_BOUND_MINUTES}m default`
+    bound = DELIVERY_WATCH_BOUND_MINUTES
+  }
+  if (!isObject(watch)) return { state: 'unwatched', reason: 'no observation recorded yet', ...(coerced ? { boundWarning: coerced } : {}) }
+  if (DELIVERY_BLOCKING_QUEUE_STATES.includes(watch.queueState)) {
+    return { state: 'blocked', stalledForMs: 0, reason: `the queue reports "${watch.queueState}" — a self-explaining block; hand back with it named rather than waiting out the bound`, ...(coerced ? { boundWarning: coerced } : {}) }
+  }
+  const last = Date.parse(watch.lastObservedAt)
+  const changed = Date.parse(watch.lastChangeAt)
+  const at = now === undefined ? Date.now() : (typeof now === 'string' ? Date.parse(now) : now)
+  if (!Number.isFinite(last) || !Number.isFinite(changed) || !Number.isFinite(at)) {
+    return { state: 'unknown', reason: `watch timestamps are unparseable (lastObservedAt=${JSON.stringify(watch.lastObservedAt)}, lastChangeAt=${JSON.stringify(watch.lastChangeAt)}) — the bound cannot be evaluated, so this is treated as ACTIONABLE, never as progress`, ...(coerced ? { boundWarning: coerced } : {}) }
+  }
+  // A nudge RESTARTS the stall clock, once — that is what "one bounded re-evaluation
+  // request" buys, and it is why the nudge is capped: an uncapped one would keep a wedged
+  // unit looking alive forever, which is the epic-986 shape with extra steps.
+  const nudges = Array.isArray(watch.nudges) ? watch.nudges : []
+  const lastNudge = nudges.length ? Date.parse(nudges[nudges.length - 1].at) : NaN
+  const origin = Number.isFinite(lastNudge) && lastNudge > changed ? lastNudge : changed
+  const stalledForMs = at - origin
+  if (stalledForMs > bound * 60_000) {
+    return { state: 'stalled', stalledForMs, reason: `the queue has reported "${watch.queueState}"${watch.position === undefined || watch.position === null ? '' : ` at position ${watch.position}`} without moving for ${Math.round(stalledForMs / 60_000)}m (bound ${bound}m)${nudges.length ? `, including after ${nudges.length} nudge(s)` : ''} — hand back with the state quoted`, ...(coerced ? { boundWarning: coerced } : {}) }
+  }
+  // The request never landed: nothing is holding this PR. Distinct from "the queue is
+  // holding it pending conditions", and the remedy is the opposite — re-request rather
+  // than wait. Not a retry of the merge path: nothing was ever attempted.
+  if (watch.queueState === 'not-enqueued') {
+    return { state: 'not-enqueued', stalledForMs, action: 'requeue', reason: 'the queue is not holding this PR — the enqueue request never landed (no acknowledgement), so re-request it; waiting cannot fix a command nobody read', ...(coerced ? { boundWarning: coerced } : {}) }
+  }
+  if (
+    flow?.supportsNudge
+    && DELIVERY_PREADMISSION_STATES.includes(watch.queueState)
+    && nudges.length < DELIVERY_MAX_NUDGES
+    && stalledForMs > DELIVERY_NUDGE_AFTER_MINUTES * 60_000
+    // Only when the queue lists nothing outstanding. With a condition still unmet the
+    // queue is not stale, it is correct, and a refresh would just re-read the same red.
+    && !(Array.isArray(watch.unmetConditions) && watch.unmetConditions.length > 0)
+  ) {
+    return { state: 'nudge-due', stalledForMs, action: 'nudge', command: flow.ops?.nudge ?? null, reason: `pre-admission at "${watch.queueState}" for ${Math.round(stalledForMs / 60_000)}m with no condition listed unmet — spend the one ${flow.provider} re-evaluation request (${flow.ops?.nudge ?? 'nudge'}) before waiting out the ${bound}m bound`, ...(coerced ? { boundWarning: coerced } : {}) }
+  }
+  return { state: 'progressing', stalledForMs, reason: `last change ${Math.round(stalledForMs / 60_000)}m ago, within the ${bound}m bound`, ...(coerced ? { boundWarning: coerced } : {}) }
+}
+
+// ---- gate results: making the removal path's rule 2 executable (#468) ----
+//
+// The removal path says the handoff must measure each mechanized gate's unique/blocking
+// findings, attributed fixes, repeated known warnings, noise, and optional cost. Retirement
+// requires durable evidence of zero yield across a configurable run window; narrowing
+// and deduplication are independent recommendations. That audit had never once run
+// because the data did
+// not exist: **a gate that passed and a gate that never ran were indistinguishable.**
+//
+// Measured on merged PRs in the window where all four newer gates existed (n=79): Self-
+// Review evidenced on 35%, reviewer-parity 27%, runtime smoke 10%, evidence-block 9%. Under
+// this skill's own rule — output without its proof did not run the skill — those are gates
+// that mostly did not run, and their *value* is therefore unmeasurable. So is the cost
+// argument for removing any of them, which is why #471 waits on this.
+//
+// Every committed artifact being green is survivorship, not a result: a producer commits
+// the artifact once it is green, so a gate that caught something and got fixed looks
+// exactly like a gate that never fired. `findings` and `fixed` exist to break that tie.
+//
+// THE DESIGN CONSTRAINT, learned from this manifest set: mechanizing a record works only
+// when something downstream READS it. From 522 units — `units[].rounds` 0 -> 83% adoption
+// (the breaker reads it), `skillsRoot` 0 -> 90% (`validate` reads it), `contractRevision`
+// 0 -> 57% (`contract-revision.mjs` reads it), and `delivery` **0 of 522** — fully
+// mechanized, documented, dedicated commands, and never once written, because nothing
+// consumes it. Hence `gateAudit` ships beside the writer rather than after it.
+export const GATE_NAMES = ['scan-diff', 'coverage-checklist', 'evidence-block', 'runtime-smoke', 'self-review', 'smoke']
+export const GATE_RESULTS = ['clean', 'findings', 'failed', 'skipped']
+export const GATE_FINDING_OUTCOMES = ['open', 'fixed', 'noise']
+export const GATE_RETIREMENT_MINIMUM_RUNS = 10
+
+function validateGateFinding(finding, label) {
+  if (!isObject(finding)) return [`${label} must be an object`]
+  const errors = []
+  if (!nonEmptyString(finding.class)) errors.push(`${label}.class must be a non-empty string`)
+  if (!nonEmptyString(finding.locator)) errors.push(`${label}.locator must be a non-empty string`)
+  if (typeof finding.blocking !== 'boolean') errors.push(`${label}.blocking must be a boolean`)
+  if (!GATE_FINDING_OUTCOMES.includes(finding.outcome)) errors.push(`${label}.outcome must be one of ${GATE_FINDING_OUTCOMES.join('|')}`)
+  const unknown = Object.keys(finding).filter((key) => !['class', 'locator', 'blocking', 'outcome'].includes(key))
+  if (unknown.length) errors.push(`${label} has unknown property: ${unknown[0]}`)
+  return errors
+}
+
+function gateFinding(finding) {
+  return {
+    class: finding.class.trim(),
+    locator: finding.locator.trim(),
+    blocking: finding.blocking,
+    outcome: finding.outcome,
+  }
+}
+
+const gateFingerprint = (finding) => `${finding.class}\u0000${finding.locator}`
+
+// Refused ONLY on its own shape — never on unrelated unit state, and never by the breaker.
+// Same discipline as record-round and record-delivery-observation: a logging call that can
+// hard-fail is one an orchestrator learns to stop making, and non-adoption is exactly the
+// failure this exists to end.
+export function recordGateResult(manifest, unitId, entry) {
+  if (!isObject(entry)) throw new Error('gate result must be an object')
+  if (!GATE_NAMES.includes(entry.gate)) {
+    throw new Error(`gate must be one of ${GATE_NAMES.join('|')} (got ${JSON.stringify(entry.gate)})`)
+  }
+  if (typeof entry.ran !== 'boolean') throw new Error('gate result requires ran: true|false — "it did not run" is the answer this record exists to make sayable')
+  if (!GATE_RESULTS.includes(entry.result)) {
+    throw new Error(`result must be one of ${GATE_RESULTS.join('|')} (got ${JSON.stringify(entry.result)})`)
+  }
+  if (entry.ran === false && entry.result !== 'skipped') {
+    throw new Error('a gate result with ran:false must use result:"skipped" — a gate that did not execute cannot be clean, failed, or findings')
+  }
+  // A gate that did not run, or was skipped, owes WHY. Without it the audit can report a
+  // count but not a decision, and "skipped 12 times" with no reason is indistinguishable
+  // from a gate nobody bothered with — which is the state this issue found the loop in.
+  if ((entry.ran === false || entry.result === 'skipped') && !nonEmptyString(entry.reason)) {
+    throw new Error('a gate result with ran:false or result:"skipped" requires a reason — a silent skip is what made the removal-path audit unrunnable')
+  }
+  if (entry.findings !== undefined && (!Number.isInteger(entry.findings) || entry.findings < 0)) {
+    throw new Error('gate result findings must be a non-negative integer')
+  }
+  // `result: 'findings'` with no count is the shape that breaks the tie this record was
+  // built to break. `findings` is optional in general — a clean run has nothing to count —
+  // but a gate ASSERTING it found something and then not saying how many audits as zero,
+  // and zero findings with zero rejections is precisely the retirement verdict. So a gate
+  // that just caught a bug gets flagged for removal. Require the count where the result
+  // claims one, and require it to be at least 1: zero findings is `clean`, by definition.
+  if (entry.result === 'findings' && !(Number.isInteger(entry.findings) && entry.findings >= 1)) {
+    throw new Error('result "findings" requires findings >= 1 — a gate that reports a catch without a count audits as zero, and zero findings with zero rejections is the retirement verdict; if it found nothing, the result is "clean"')
+  }
+  if (entry.result !== 'findings' && Number.isInteger(entry.findings) && entry.findings > 0) {
+    throw new Error(`result "${entry.result}" cannot report positive findings — use result:"findings" so the observation is not mislabeled or discarded`)
+  }
+  if (entry.result !== 'findings' && Array.isArray(entry.findingDetails) && entry.findingDetails.length > 0) {
+    throw new Error(`result "${entry.result}" cannot carry findingDetails — use result:"findings" so the observation is not mislabeled or discarded`)
+  }
+  if (entry.result !== 'findings' && Array.isArray(entry.fixed) && entry.fixed.length > 0) {
+    throw new Error(`result "${entry.result}" cannot carry fixed evidence — use result:"findings" so the attributed value is not discarded`)
+  }
+  // Silent coercion is data loss in a record whose whole premise is that gate history stops
+  // going unrecorded. `round` and `headSha` are what tie a catch back to the round and
+  // commit that made it, and a stringified round or numeric sha used to be dropped without
+  // a word — the caller believing it recorded provenance that is not there.
+  if (entry.round !== undefined && !Number.isInteger(entry.round)) {
+    throw new Error('gate result round must be an integer — a stringified round is dropped silently otherwise, losing the link between a catch and the round that made it')
+  }
+  if (entry.headSha !== undefined && !nonEmptyString(entry.headSha)) {
+    throw new Error('gate result headSha must be a non-empty string')
+  }
+  if (entry.fixed !== undefined && (!Array.isArray(entry.fixed) || !entry.fixed.every(nonEmptyString))) {
+    throw new Error('gate result fixed must be an array of non-empty strings')
+  }
+  if (entry.fixed !== undefined && entry.findingDetails !== undefined) {
+    throw new Error('gate result must not combine fixed and findingDetails — record each attributable fix once')
+  }
+  if (entry.durationMs !== undefined && (!Number.isFinite(entry.durationMs) || entry.durationMs < 0)) {
+    throw new Error('gate result durationMs must be a non-negative number')
+  }
+  if (entry.findingDetails !== undefined) {
+    if (!Array.isArray(entry.findingDetails)) throw new Error('gate result findingDetails must be an array')
+    const errors = entry.findingDetails.flatMap((finding, index) => validateGateFinding(finding, `findingDetails[${index}]`))
+    if (errors.length) throw new Error(`gate result ${errors[0]}`)
+  }
+  const out = clone(manifest)
+  const { units, index } = unitOrThrow(out, unitId)
+  const unit = units[index]
+  const log = Array.isArray(unit.gateResults) ? unit.gateResults : []
+  log.push({
+    gate: entry.gate,
+    ran: entry.ran,
+    result: entry.result,
+    ...(Number.isInteger(entry.round) ? { round: entry.round } : {}),
+    ...(nonEmptyString(entry.headSha) ? { headSha: entry.headSha } : {}),
+    ...(entry.findings !== undefined ? { findings: entry.findings } : {}),
+    ...(Array.isArray(entry.fixed) && entry.fixed.length ? { fixed: entry.fixed } : {}),
+    ...(nonEmptyString(entry.reason) ? { reason: entry.reason } : {}),
+    ...(Array.isArray(entry.findingDetails) ? { findingDetails: entry.findingDetails.map(gateFinding) } : {}),
+    ...(Number.isFinite(entry.durationMs) ? { durationMs: entry.durationMs } : {}),
+    at: nonEmptyString(entry.at) ? entry.at : new Date().toISOString(),
+  })
+  unit.gateResults = log
+  return out
+}
+
+export function validateGateResults(unit) {
+  const log = unit?.gateResults
+  if (log === undefined) return []
+  if (!Array.isArray(log)) return ['gateResults must be an array']
+  const errors = []
+  log.forEach((e, i) => {
+    const at = `gateResults[${i}]`
+    if (!isObject(e)) { errors.push(`${at} must be an object`); return }
+    if (!GATE_NAMES.includes(e.gate)) errors.push(`${at}.gate must be one of ${GATE_NAMES.join('|')}`)
+    if (typeof e.ran !== 'boolean') errors.push(`${at}.ran must be a boolean`)
+    if (!GATE_RESULTS.includes(e.result)) errors.push(`${at}.result must be one of ${GATE_RESULTS.join('|')}`)
+    if (e.ran === false && e.result !== 'skipped') {
+      errors.push(`${at} has ran:false but result is not "skipped" — a non-execution cannot be clean, failed, or findings`)
+    }
+    if ((e.ran === false || e.result === 'skipped') && !nonEmptyString(e.reason)) {
+      errors.push(`${at} has ran:false or result:"skipped" but no reason — a silent skip is unauditable`)
+    }
+    // These mirror recordGateResult exactly. They have to: `merge`, `set`, a hand-edit or a
+    // future migration can all write this array, and anything validate does not check is
+    // data the audit will silently believe.
+    if (e.findings !== undefined && (!Number.isInteger(e.findings) || e.findings < 0)) {
+      errors.push(`${at}.findings must be a non-negative integer`)
+    }
+    if (e.result === 'findings' && !(Number.isInteger(e.findings) && e.findings >= 1)) {
+      errors.push(`${at} has result:"findings" but no findings >= 1 — it audits as zero, which is the retirement verdict for a gate that caught something`)
+    }
+    if (e.result !== 'findings' && Number.isInteger(e.findings) && e.findings > 0) {
+      errors.push(`${at} has result:"${e.result}" but positive findings — the observation is mislabeled`)
+    }
+    if (e.result !== 'findings' && Array.isArray(e.findingDetails) && e.findingDetails.length > 0) {
+      errors.push(`${at} has result:"${e.result}" but findingDetails — the observation is mislabeled`)
+    }
+    if (e.result !== 'findings' && Array.isArray(e.fixed) && e.fixed.length > 0) {
+      errors.push(`${at} has result:"${e.result}" but fixed evidence — the attributed value would be discarded`)
+    }
+    if (e.fixed !== undefined && (!Array.isArray(e.fixed) || !e.fixed.every(nonEmptyString))) {
+      errors.push(`${at}.fixed must be an array of non-empty strings`)
+    }
+    if (e.fixed !== undefined && e.findingDetails !== undefined) {
+      errors.push(`${at} must not combine fixed and findingDetails — it double-counts attributable fixes`)
+    }
+    if (e.round !== undefined && !Number.isInteger(e.round)) errors.push(`${at}.round must be an integer`)
+    if (e.headSha !== undefined && !nonEmptyString(e.headSha)) errors.push(`${at}.headSha must be a non-empty string`)
+    if (e.durationMs !== undefined && (!Number.isFinite(e.durationMs) || e.durationMs < 0)) {
+      errors.push(`${at}.durationMs must be a non-negative number`)
+    }
+    if (e.findingDetails !== undefined) {
+      if (!Array.isArray(e.findingDetails)) errors.push(`${at}.findingDetails must be an array`)
+      else errors.push(...e.findingDetails.flatMap((finding, index) => validateGateFinding(finding, `${at}.findingDetails[${index}]`)))
+    }
+    const unknown = Object.keys(e).filter((k) => !['gate', 'ran', 'result', 'round', 'headSha', 'findings', 'fixed', 'findingDetails', 'durationMs', 'reason', 'at'].includes(k))
+    if (unknown.length) errors.push(`${at} has unknown property: ${unknown[0]}`)
+  })
+  return errors
+}
+
+// THE CONSUMER. Without this the field is `delivery` all over again — mechanized,
+// documented, and never written. Returns one row per gate that has any record, plus the
+// gates that have none, because "no record at all" is the finding the removal path most
+// needs and the one an aggregate over present rows would hide.
+function gateAccumulator(gate) {
+  return {
+    gate, ran: 0, skipped: 0, notRun: 0, failed: 0, findings: 0, fixed: 0, clean: 0,
+    unreadable: 0, reasons: [], units: new Set(), durationMs: [],
+    structuredOccurrences: 0, unique: new Map(), legacyFixes: new Set(),
+  }
+}
+
+function mergeFinding(row, finding, occurrences = 1) {
+  if (!isObject(finding) || !nonEmptyString(finding.class) || !nonEmptyString(finding.locator)) return false
+  const normalized = {
+    class: finding.class.trim(),
+    locator: finding.locator.trim(),
+    blocking: finding.blocking === true,
+  }
+  const fingerprint = nonEmptyString(finding.fingerprint) ? finding.fingerprint : gateFingerprint(normalized)
+  const current = row.unique.get(fingerprint) || {
+    fingerprint,
+    class: normalized.class,
+    locator: normalized.locator,
+    blocking: false,
+    outcomes: new Set(),
+    occurrences: 0,
+  }
+  current.blocking ||= normalized.blocking
+  const outcomes = Array.isArray(finding.outcomes) ? finding.outcomes : [finding.outcome]
+  for (const outcome of outcomes) if (GATE_FINDING_OUTCOMES.includes(outcome)) current.outcomes.add(outcome)
+  const count = Number.isInteger(occurrences) && occurrences > 0 ? occurrences : 1
+  current.occurrences += count
+  row.structuredOccurrences += count
+  row.unique.set(fingerprint, current)
+  return true
+}
+
+function normalizedUnique(row) {
+  return [...row.unique.values()].map((finding) => ({
+    ...finding,
+    outcomes: [...finding.outcomes].sort(),
+  })).sort((a, b) => a.fingerprint.localeCompare(b.fingerprint))
+}
+
+function localGateAudit(manifest) {
+  const units = Array.isArray(manifest?.units) ? manifest.units : []
+  const rows = new Map(GATE_NAMES.map((gate) => [gate, gateAccumulator(gate)]))
+  for (const unit of units) {
+    for (const entry of (Array.isArray(unit?.gateResults) ? unit.gateResults : [])) {
+      const row = rows.get(entry?.gate)
+      if (!row) continue
+      row.units.add(unit.id)
+      if (!isObject(entry) || validateGateResults({ gateResults: [entry] }).length > 0) {
+        row.unreadable += 1
+        continue
+      }
+      if (entry.ran === false || entry.result === 'skipped') {
+        if (entry.ran === false) row.notRun += 1
+        else row.skipped += 1
+        if (nonEmptyString(entry.reason)) row.reasons.push(entry.reason)
+        continue
+      }
+      row.ran += 1
+      if (entry.result === 'clean') row.clean += 1
+      if (entry.result === 'failed') row.failed += 1
+      if (Number.isInteger(entry.findings) && entry.findings > 0) row.findings += entry.findings
+      if (Array.isArray(entry.fixed)) {
+        row.fixed += entry.fixed.length
+        for (const fixed of entry.fixed) row.legacyFixes.add(fixed)
+      }
+      if (Array.isArray(entry.findingDetails)) {
+        for (const finding of entry.findingDetails) mergeFinding(row, finding)
+      }
+      if (Number.isFinite(entry.durationMs)) row.durationMs.push(entry.durationMs)
+    }
+  }
+  return GATE_NAMES.map((gate) => {
+    const row = rows.get(gate)
+    const unique = normalizedUnique(row)
+    const totalDurationMs = row.durationMs.reduce((sum, value) => sum + value, 0)
+    const recorded = row.ran + row.skipped + row.notRun + row.unreadable
+    const repeatedKnownWarnings = unique.filter((finding) => !finding.blocking).reduce((sum, finding) => sum + Math.max(0, finding.occurrences - 1), 0)
+    const noiseFindings = unique.filter((finding) => finding.outcomes.includes('noise')).length
+    const fixesAttributed = unique.filter((finding) => finding.outcomes.includes('fixed')).length + row.legacyFixes.size
+    return {
+      gate,
+      ran: row.ran,
+      skipped: row.skipped,
+      failed: row.failed,
+      findings: row.findings,
+      fixed: row.fixed,
+      units: row.units.size,
+      reasons: [...new Set(row.reasons)].slice(0, 5),
+      uniqueFindings: unique.length,
+      blockingFindings: unique.filter((finding) => finding.blocking).length,
+      repeatedKnownWarnings,
+      fixesAttributed,
+      noiseFindings,
+      unclassifiedFindings: Math.max(0, row.findings - row.structuredOccurrences),
+      unique,
+      states: { ranClean: row.clean, notRun: row.notRun, skipped: row.skipped, unreadable: row.unreadable },
+      cost: {
+        observedRuns: row.durationMs.length,
+        totalDurationMs,
+        approximateMeanMs: row.durationMs.length ? Math.round(totalDurationMs / row.durationMs.length) : null,
+      },
+      unrecorded: recorded === 0,
+      retirementCandidate: false,
+      recommendations: { retirement: false, narrowing: noiseFindings > 0 || repeatedKnownWarnings > 0, deduplication: repeatedKnownWarnings > 0 },
+      observationWindow: { runs: 1, minimumRuns: GATE_RETIREMENT_MINIMUM_RUNS, sufficient: false },
+    }
+  })
+}
+
+function mergeAuditRow(target, source) {
+  if (!isObject(source)) {
+    target.unreadable += 1
+    return
+  }
+  for (const key of ['ran', 'skipped', 'failed', 'findings', 'fixed']) {
+    if (Number.isInteger(source[key]) && source[key] >= 0) target[key] += source[key]
+  }
+  if (Number.isInteger(source.states?.ranClean) && source.states.ranClean >= 0) target.clean += source.states.ranClean
+  if (Number.isInteger(source.states?.notRun) && source.states.notRun >= 0) target.notRun += source.states.notRun
+  if (Number.isInteger(source.states?.unreadable) && source.states.unreadable >= 0) target.unreadable += source.states.unreadable
+  if (Array.isArray(source.reasons)) target.reasons.push(...source.reasons.filter(nonEmptyString))
+  if (Array.isArray(source.unique)) {
+    for (const finding of source.unique) mergeFinding(target, finding, finding?.occurrences)
+  }
+  if (Number.isInteger(source.cost?.observedRuns) && source.cost.observedRuns > 0 && Number.isFinite(source.cost.totalDurationMs)) {
+    const mean = source.cost.totalDurationMs / source.cost.observedRuns
+    target.durationMs.push(...Array.from({ length: source.cost.observedRuns }, () => mean))
+  }
+}
+function isZeroYieldObservation(observation, gate) {
+  if (!isObject(observation) || observation.unreadable === true || !Array.isArray(observation.gateValue)) return false
+  const row = observation.gateValue.find((candidate) => candidate?.gate === gate)
+  if (!isObject(row)) return false
+  return row.ran > 0
+    && row.failed === 0
+    && row.findings === 0
+    && row.uniqueFindings === 0
+    && row.states?.notRun === 0
+    && row.states?.skipped === 0
+    && row.states?.unreadable === 0
+}
+
+
+export function gateAudit(manifest, options = {}) {
+  const minimumRuns = Number.isInteger(options.minimumObservationRuns) && options.minimumObservationRuns > 0
+    ? options.minimumObservationRuns
+    : GATE_RETIREMENT_MINIMUM_RUNS
+  const local = localGateAudit(manifest)
+  if (!Array.isArray(options.series)) {
+    return local.map((row) => ({
+      ...row,
+      observationWindow: { runs: 1, minimumRuns, zeroYieldStreak: row.ran > 0 && row.findings === 0 && row.failed === 0 && row.uniqueFindings === 0 && row.skipped === 0 && row.states.unreadable === 0 ? 1 : 0, sufficient: false },
+    }))
+  }
+
+  return GATE_NAMES.map((gate) => {
+    const aggregate = gateAccumulator(gate)
+    let absentRuns = 0
+    for (const observation of options.series) {
+      if (!isObject(observation) || observation.unreadable === true || !Array.isArray(observation.gateValue)) {
+        aggregate.unreadable += 1
+        continue
+      }
+      const source = observation.gateValue.find((row) => row?.gate === gate)
+      if (!source) {
+        absentRuns += 1
+        continue
+      }
+      mergeAuditRow(aggregate, source)
+    }
+    const unique = normalizedUnique(aggregate)
+    const repeatedKnownWarnings = unique.filter((finding) => !finding.blocking).reduce((sum, finding) => sum + Math.max(0, finding.occurrences - 1), 0)
+    const blockingFindings = unique.filter((finding) => finding.blocking).length
+    const fixesAttributed = unique.filter((finding) => finding.outcomes.includes('fixed')).length + aggregate.fixed
+    const noiseFindings = unique.filter((finding) => finding.outcomes.includes('noise')).length
+    const totalDurationMs = aggregate.durationMs.reduce((sum, value) => sum + value, 0)
+    const runs = options.series.length
+    let zeroYieldStreak = 0
+    for (let index = options.series.length - 1; index >= 0 && isZeroYieldObservation(options.series[index], gate); index--) zeroYieldStreak += 1
+    const sufficient = zeroYieldStreak >= minimumRuns
+    const states = { ranClean: aggregate.clean, notRun: aggregate.notRun + absentRuns, skipped: aggregate.skipped, unreadable: aggregate.unreadable }
+    const retirement = sufficient
+    return {
+      gate,
+      ran: aggregate.ran,
+      skipped: aggregate.skipped,
+      failed: aggregate.failed,
+      findings: aggregate.findings,
+      fixed: aggregate.fixed,
+      units: null,
+      reasons: [...new Set(aggregate.reasons)].slice(0, 5),
+      uniqueFindings: unique.length,
+      blockingFindings,
+      repeatedKnownWarnings,
+      fixesAttributed,
+      noiseFindings,
+      unclassifiedFindings: Math.max(0, aggregate.findings - aggregate.structuredOccurrences),
+      unique,
+      states,
+      cost: {
+        observedRuns: aggregate.durationMs.length,
+        totalDurationMs,
+        approximateMeanMs: aggregate.durationMs.length ? Math.round(totalDurationMs / aggregate.durationMs.length) : null,
+      },
+      unrecorded: aggregate.ran + aggregate.skipped + aggregate.notRun + aggregate.unreadable === 0,
+      retirementCandidate: retirement,
+      recommendations: {
+        retirement,
+        narrowing: noiseFindings > 0 || repeatedKnownWarnings > 0,
+        deduplication: repeatedKnownWarnings > 0,
+      },
+      observationWindow: { runs, minimumRuns, zeroYieldStreak, sufficient },
+    }
+  })
+}
+
+// Surfaced by validate. A merge-ready unit with no gate results at all is the state that
+// made this issue necessary — it reads as "all gates passed" and means "nobody said".
+export function gateResultWarnings(unit) {
+  if (unit?.status !== 'merge-ready') return []
+  const log = Array.isArray(unit?.gateResults) ? unit.gateResults : []
+  if (log.length) return []
+  return ['status is merge-ready but no gate results were recorded — a gate that passed and a gate that never ran are indistinguishable here; record them with `record-gate-result` so the handoff\'s gate audit means something (removal path, rule 2)']
+}
+
+// Recording an observation is NEVER refused, for the same reason record-round is not: a
+// logging call that can hard-fail is one an orchestrator learns to stop making, and a
+// watch nobody writes is the failure this bound exists to end. The signal is the
+// returned status (and the CLI's exit code), not a throw.
+export function recordDeliveryObservation(manifest, unitId, observation) {
+  if (!isObject(observation)) throw new Error('delivery observation must be an object')
+  if (!nonEmptyString(observation.queueState)) throw new Error('delivery observation requires queueState — read it from the queue tool, never infer it')
+  const at = nonEmptyString(observation.at) ? observation.at : new Date().toISOString()
+  const out = clone(manifest)
+  const { units, index } = unitOrThrow(out, unitId)
+  const unit = units[index]
+  const delivery = isObject(unit.delivery) ? unit.delivery : { attempts: [], outcome: null, mergedSha: null, blockedOn: null }
+  const prev = isObject(delivery.watch) ? delivery.watch : null
+  const position = observation.position === undefined ? null : observation.position
+  // The queue's own unmet leaves, quoted. Pre-admission this is the difference between
+  // "stale evaluation" and "correctly waiting on a red check" — the first is nudgeable,
+  // the second is not — and on a hand-back it is the condition the loop owes verbatim.
+  const unmetConditions = Array.isArray(observation.unmetConditions) ? [...observation.unmetConditions] : (prev?.unmetConditions ?? null)
+  const conditionsKey = (list) => (Array.isArray(list) ? list.join('\u0000') : '')
+  // The (state, position) pair is what "moving" means — plus the unmet-condition set,
+  // because a condition going green is progress by any honest reading even while the
+  // state string sits at "waiting". A poll that observes all three unchanged is evidence
+  // of a stall, not of life.
+  const moved = !prev
+    || prev.queueState !== observation.queueState
+    || (prev.position ?? null) !== position
+    || conditionsKey(prev.unmetConditions) !== conditionsKey(unmetConditions)
+  unit.delivery = {
+    ...delivery,
+    watch: {
+      firstObservedAt: prev?.firstObservedAt || at,
+      lastObservedAt: at,
+      lastChangeAt: moved ? at : prev.lastChangeAt,
+      queueState: observation.queueState,
+      position,
+      polls: (prev?.polls ?? 0) + 1,
+      ...(Array.isArray(prev?.nudges) && prev.nudges.length ? { nudges: prev.nudges } : {}),
+      ...(unmetConditions === null ? {} : { unmetConditions }),
+    },
+  }
+  // NOT settleBreakerOrThrow. A watch write cannot violate a breaker or budget
+  // invariant, and routing it through the full unit gate meant a unit carrying
+  // UNRELATED pre-existing invalid state (a stateVersion-2 unit `merge-ready` with
+  // `lastVerdict` unset — a resumable legacy shape run-state.md documents) could not
+  // record observations at all. That recreates the silent stall this bound exists to
+  // end, on exactly the resumed run that most needs it. Validate what we touched.
+  const errors = validateDelivery(unit, deliveryMode(out), deliveryProvider(out))
+  if (errors.length) throw new Error(errors[0])
+  return out
+}
+
+// The nudge, recorded. Refusable on its own shape and on the flow's capabilities — a
+// nudge on a provider that has no re-evaluation command is a fiction, and a second nudge
+// is the poll loop the cap exists to prevent. It deliberately does NOT go through
+// `recordDeliveryAttempt`: a nudge attempts no merge and touches no HEAD, so the
+// unchanged-HEAD retry refusal does not reach it and must not be made to.
+export function recordDeliveryNudge(manifest, unitId, nudge) {
+  if (!isObject(nudge)) throw new Error('delivery nudge must be an object')
+  const out = clone(manifest)
+  const { units, index } = unitOrThrow(out, unitId)
+  const unit = units[index]
+  const mode = deliveryMode(out)
+  const provider = deliveryProvider(out)
+  const flow = DELIVERY_FLOWS[deliveryFlowKey(mode, provider)] ?? null
+  if (!flow) throw new Error(`record-delivery-nudge cannot resolve the delivery flow (mode "${mode}", provider ${JSON.stringify(provider)}) — settle queueProvider before acting on the queue`)
+  if (!flow.supportsNudge) {
+    throw new Error(`the "${flow.key}" flow has no re-evaluation command — a nudge here would be a fiction; wait out the stall bound and hand back with the queue state quoted`)
+  }
+  const delivery = isObject(unit.delivery) ? unit.delivery : { attempts: [], outcome: null, mergedSha: null, blockedOn: null }
+  if (delivery.outcome === 'merged' || delivery.outcome === 'handed-back') {
+    throw new Error(`${unitId} already reached the terminal delivery outcome "${delivery.outcome}"`)
+  }
+  const watch = isObject(delivery.watch) ? delivery.watch : null
+  if (!watch) throw new Error(`${unitId} has no delivery watch to nudge — record an observation first; a nudge with nothing observed is a poke in the dark`)
+  const nudges = Array.isArray(watch.nudges) ? [...watch.nudges] : []
+  if (nudges.length >= DELIVERY_MAX_NUDGES) {
+    throw new Error(`${unitId} already spent its ${DELIVERY_MAX_NUDGES} nudge(s) — the second one is a poll loop, and the stall bound is what ends this unit now: hand back with "${watch.queueState}" quoted`)
+  }
+  const at = nonEmptyString(nudge.at) ? nudge.at : new Date().toISOString()
+  nudges.push({ at, command: nonEmptyString(nudge.command) ? nudge.command : (flow.ops?.nudge ?? 'nudge'), ...(nonEmptyString(nudge.ref) ? { ref: nudge.ref } : {}) })
+  unit.delivery = { ...delivery, watch: { ...watch, nudges } }
+  const errors = validateDelivery(unit, mode, provider)
+  if (errors.length) throw new Error(errors[0])
+  return out
+}
+
+// A queued PR whose HEAD has moved is a PR the queue is about to eject (`pull-request-
+// updated`), or has already ejected without anyone reading the reason. The loop pushes
+// for several ordinary purposes — an evidence-lane commit, a rebase, `mergify stack push`
+// — so the freeze cannot be enforced by refusing writes; it is surfaced instead, at the
+// one place that compares what is enqueued against what the unit's rounds now say.
+export function deliveryHeadDriftWarnings(unit) {
+  const delivery = isObject(unit?.delivery) ? unit.delivery : null
+  if (!delivery || delivery.outcome === 'merged' || delivery.outcome === 'handed-back') return []
+  const attempts = Array.isArray(delivery.attempts) ? delivery.attempts : []
+  const waiting = [...attempts].reverse().find((a) => a.outcome === 'waiting')
+  if (!waiting) return []
+  const rounds = Array.isArray(unit.rounds) ? unit.rounds : []
+  const latest = [...rounds].reverse().find((r) => nonEmptyString(r?.headSha))
+  if (!latest || latest.headSha === waiting.headSha) return []
+  return [`${unit.id ?? 'unit'} has ${waiting.headSha} sitting in the queue while its latest round is at ${latest.headSha} — a push under an enqueued PR ejects it (dequeue reason "pull-request-updated"); dequeue explicitly before writing to an enqueued branch, and expect the queue to have dropped it already`]
+}
+
+export function recordDeliveryOutcome(manifest, unitId, outcome) {
+  if (!isObject(outcome)) throw new Error('delivery outcome must be an object')
+  const out = clone(manifest)
+  const { units, index } = unitOrThrow(out, unitId)
+  const unit = units[index]
+  if (effectiveUnitKind(unit) !== 'implementation') {
+    throw new Error(`record-delivery-outcome is only for implementation units; ${unitId} is ${effectiveUnitKind(unit)}`)
+  }
+  const blockedOn = completionBlockers(out, unit)
+  if (blockedOn.length) {
+    throw new Error(`record-delivery-outcome refuses ${unitId}: completion dependency ${blockedOn.join(', ')} is not complete`)
+  }
+  if (!DELIVERY_OUTCOMES.includes(outcome.outcome)) throw new Error(`delivery outcome must be one of ${DELIVERY_OUTCOMES.join('|')}`)
+  const delivery = isObject(unit.delivery) ? unit.delivery : { attempts: [], outcome: null, mergedSha: null, blockedOn: null }
+  // Terminal is terminal for *re-decision* — you cannot flip merged→handed-back or
+  // re-merge at a different SHA. Enrichment of the merge clock is different: #791's
+  // postmortem prefers delivery.mergedAt, and an orchestrator that recorded `merged`
+  // before the watch returned mergedAt (or against a skill build that did not yet
+  // accept the field) must be able to fill it in without inventing a second outcome.
+  // Refuse anything that would change outcome/mergedSha/blockedOn; accept only a
+  // same-outcome merge that supplies a non-empty mergedAt when the stored one is empty.
+  if (delivery.outcome === 'merged' || delivery.outcome === 'handed-back') {
+    const sameOutcome = outcome.outcome === delivery.outcome
+    const sameSha = outcome.outcome !== 'merged'
+      || !nonEmptyString(outcome.mergedSha)
+      || outcome.mergedSha === delivery.mergedSha
+    const enrichingMergedAt = delivery.outcome === 'merged'
+      && sameOutcome
+      && sameSha
+      && !nonEmptyString(delivery.mergedAt)
+      && nonEmptyString(outcome.mergedAt)
+    if (!enrichingMergedAt) {
+      throw new Error(`${unitId} already reached the terminal delivery outcome "${delivery.outcome}"`)
+    }
+    const next = { ...delivery, mergedAt: outcome.mergedAt }
+    const errors = validateDelivery({ ...unit, delivery: next }, deliveryMode(out), deliveryProvider(out))
+    if (errors.length) throw new Error(errors[0])
+    unit.delivery = next
+    return settleBreakerOrThrow(manifest, unitId, out)
+  }
+  // The terminal write is the one that CLAIMS SUCCESS, so it is gated at least as hard
+  // as the attempt that precedes it. It was gated on nothing: `merged` was accepted on a
+  // `queued` unit with zero attempts, and on a unit just moved to `in-progress` by a
+  // checks-failed dequeue — the exact state the doctrine says "owes a fresh verdict".
+  if (unit.status !== 'merge-ready') {
+    throw new Error(`record-delivery-outcome requires ${unitId} to be merge-ready (it is "${unit.status}") — a unit routed back into the loop owes a fresh verdict before it can claim delivery`)
+  }
+  const priorAttempts = Array.isArray(delivery.attempts) ? delivery.attempts : []
+  // Only `merged` owes an attempt. A HAND-BACK is precisely the honest exit for a
+  // delivery that could never be attempted — a unit whose first observation is `frozen`
+  // (a prod incident you would not enqueue into) has zero attempts by construction, and
+  // requiring one left it unable to terminate honestly at all: fabricate an attempt, or
+  // stay "undelivered" forever.
+  if (outcome.outcome === 'merged' && priorAttempts.length === 0) {
+    throw new Error(`record-delivery-outcome "merged" on ${unitId} requires at least one recorded delivery attempt — a success with no action behind it is a claim, not a delivery`)
+  }
+  // Deliberately NOT gated on the last attempt's outcome. The documented queue flow
+  // records the attempt as `waiting` and then watches; the queue merges at that same
+  // HEAD, and demanding a second attempt that says `merged` made the only reachable
+  // terminal for a successfully merged PR `handed-back` — the two refusals pointed at
+  // each other. It was also the wrong instrument: an attempt outcome is a recorded
+  // CLAIM, exactly what this gate's own doctrine says is not evidence. `mergedSha` is
+  // required above, and `combine-and-verify.mjs delivered` is what proves it — only
+  // ancestry is a result.
+  const next = {
+    ...delivery,
+    outcome: outcome.outcome,
+    mergedSha: outcome.outcome === 'merged' ? (outcome.mergedSha ?? null) : (delivery.mergedSha ?? null),
+    // Prefer an explicit caller-supplied `mergedAt` (from watch-delivery / gh pr view) over
+    // anything previously recorded. Only meaningful on a merged outcome — a hand-back has
+    // no merge time, so drop a stale value rather than keep one that would lie.
+    // (#791 / issue-664 / identity#669 hybrid merge unobserved)
+    ...(outcome.outcome === 'merged'
+      ? { mergedAt: nonEmptyString(outcome.mergedAt) ? outcome.mergedAt : (delivery.mergedAt ?? null) }
+      : {}),
+    blockedOn: outcome.outcome === 'handed-back' ? (outcome.blockedOn ?? null) : (delivery.blockedOn ?? null),
+  }
+  if (outcome.outcome !== 'merged' && 'mergedAt' in next) delete next.mergedAt
+  const errors = validateDelivery({ ...unit, delivery: next }, deliveryMode(out), deliveryProvider(out))
+  if (errors.length) throw new Error(errors[0])
+  unit.delivery = next
+  unit.disposition = outcome.outcome === 'merged' ? 'delivered' : 'handed-back'
+  return settleBreakerOrThrow(manifest, unitId, out)
+}
+
+// `warnings` is an optional sink the caller passes to collect migration warnings
+// (e.g. an obsolete `blocking` dropped from a legacy finding); the return stays the
+// migrated manifest so existing callers are unaffected.
+export function migrateLegacyUnitState(manifest, unitId, { version, warnings = [] } = {}) {
+  if (version !== 1) throw new Error('legacy run-state migration requires version 1')
+  const out = clone(manifest)
+  const { units, index } = unitOrThrow(out, unitId)
+  const unit = units[index]
+  if (unit.stateVersion !== undefined) throw new Error('migrate-unit requires a legacy unit without stateVersion; repeated migration is not allowed')
+  const migrated = convertLegacyUnitState(unit, warnings)
+  units[index] = migrated
+  return candidateOrThrow(manifest, unitId, out)
+}