cohorte 1.5.0 → 1.6.0

package/dashboard/dist/index.html

@@ -7,8 +7,8 @@
     <link rel="icon" type="image/png" sizes="16x16" href="./favicon-16.png" />
     <link rel="apple-touch-icon" sizes="180x180" href="./apple-touch-icon-180.png" />
     <title>cohorte · dashboard</title>
-    <script type="module" crossorigin src="./assets/index-8owBnqyv.js"></script>
-    <link rel="stylesheet" crossorigin href="./assets/index-dkO8UUVl.css">
+    <script type="module" crossorigin src="./assets/index-DYyn4p93.js"></script>
+    <link rel="stylesheet" crossorigin href="./assets/index-BZ_LQlEj.css">
   </head>
   <body>
     <div id="root"></div>

package/dashboard/server/doctor.js

@@ -19,7 +19,10 @@ const FIXED_AGENTS = new Set([
   'implementer.template',
 ]);
 
-const VALID_STATUS = ['draft', 'frozen', 'in-review', 'shipped'];
+// The spec lifecycle (SCHEMA.md §Spec status). `in-progress` and `blocked` are written by
+// the /drive driver — they are what makes an interrupted autonomous loop resumable, so a
+// dashboard that flagged them as invalid would report the pipeline's own state as a defect.
+const VALID_STATUS = ['draft', 'frozen', 'in-progress', 'in-review', 'shipped', 'blocked'];
 
 // Artifacts the pipeline itself writes into specs/ that are NOT feature specs and have no
 // front-matter status. `/audit` writes specs/refactor-backlog.md by design, so scanning it
@@ -281,12 +284,16 @@ function scanSpecs(projectRoot) {
     const body = fm ? fm[1] : '';
     const get = k => { const m = body.match(new RegExp(`^${k}:\\s*(.*)$`, 'm')); return m ? m[1].trim() : null; };
     const status = get('status');
+    // The loop driver's resume state, when a /drive is (or was) running on this spec.
+    const pass = parseInt(get('loop_pass'), 10);
+    const phase = get('loop_phase');
     specs.push({
       file: f,
       id: get('feature_id') || f.replace(/\.md$/, ''),
       title: get('title'),
       status: status ? status.split('#')[0].trim() : null,
       branch: get('branch'),
+      loop: pass > 0 ? { pass, phase: phase && phase !== 'done' ? phase : null } : null,
     });
   }
   return specs;

package/install.ps1

@@ -193,6 +193,14 @@ try {
         # 1.5.0 removed the /smoke phase; copy-over never deletes, so scrub the orphan agent.
         Remove-Item -LiteralPath (Join-Path $dest 'agents\smoke.md') -Force -ErrorAction SilentlyContinue
         Remove-Item -LiteralPath (Join-Path $dest 'commands\smoke.md') -Force -ErrorAction SilentlyContinue
+        # 1.4.0 removed /cycle and its workflow — and no installer ever scrubbed them, so every
+        # install since has kept offering a command that dispatches a workflow whose phases were
+        # later deleted. A dead command is worse than a missing one: the model can still fire it.
+        Remove-Item -LiteralPath (Join-Path $dest 'commands\cycle.md') -Force -ErrorAction SilentlyContinue
+        Remove-Item -LiteralPath (Join-Path $dest 'workflows\cycle.js') -Force -ErrorAction SilentlyContinue
+        # 1.6.0 renamed /loop → /drive: Claude Code's own built-in /loop shadowed ours, so a leftover
+        # commands\loop.md is a command the user can never reach — scrub it rather than leave a decoy.
+        Remove-Item -LiteralPath (Join-Path $dest 'commands\loop.md') -Force -ErrorAction SilentlyContinue
         # 0.1.19 split the bi-mode questionnaire-researcher into research-agent + questionnaire-architect;
         # copy-over never deletes, so scrub the retired agent lest a dead subagent_type linger.
         Remove-Item -LiteralPath (Join-Path $dest 'agents\questionnaire-researcher.md') -Force -ErrorAction SilentlyContinue

package/install.sh

@@ -154,6 +154,13 @@ copy_fixed_agents() {
      "$dest/agents/"
   # 1.5.0 removed the /smoke phase; copy-over never deletes, so scrub the orphan agent.
   rm -f "$dest/agents/smoke.md" "$dest/commands/smoke.md"
+  # 1.4.0 removed /cycle and its workflow — and no installer ever scrubbed them, so every
+  # install since has kept offering a command that dispatches a workflow whose phases were
+  # later deleted. A dead command is worse than a missing one: the model can still fire it.
+  rm -f "$dest/commands/cycle.md" "$dest/workflows/cycle.js"
+  # 1.6.0 renamed /loop → /drive: Claude Code's own built-in /loop shadowed ours, so a leftover
+  # commands/loop.md is a command the user can never reach — scrub it rather than leave a decoy.
+  rm -f "$dest/commands/loop.md"
   # 0.1.19 split the bi-mode questionnaire-researcher into research-agent + questionnaire-architect;
   # copy-over never deletes, so scrub the retired agent lest a dead subagent_type linger.
   rm -f "$dest/agents/questionnaire-researcher.md"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cohorte",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Portable, stack-agnostic multi-agent development pipeline for Claude Code — install the core, run /init-pipeline, and it adapts to your project's stack.",
   "bin": {
     "cohorte": "bin/cli.js"

package/profile/SCHEMA.md

@@ -217,6 +217,129 @@ Rules for every consumer (implementers, preflight, `/audit` gates, workflow agen
 `/init-pipeline` **asks** for these variants (detected defaults offered first) instead of silently
 storing a bare `pnpm test` as the thing agents execute; `/update-pipeline` tops up older profiles.
 
+## Spec status — the lifecycle state machine (and the loop's resume state)
+
+A spec's front-matter `status` is not a label, it is the pipeline's **state**: every command routes on
+it, the dashboard boards on it, the kanban backfill maps it to a column, and `/drive --resume` reads it
+back to continue an interrupted autonomous run. Six states, and exactly one writer each:
+
+| status | meaning | written by | who may build it |
+| --- | --- | --- | --- |
+| `draft` | the interview is open, nothing is frozen | `/spec` Mode A | no |
+| `frozen` | the contract is frozen — the handoff to `/build` | `/spec` Mode A freeze | yes |
+| `in-progress` | a `/drive` is driving this spec right now (or died doing it) | `scripts/loop.sh`, before each phase | yes |
+| `in-review` | reviewed / awaiting the next round or `/ship` | `/spec` Mode B, `/fix`, `loop.sh` on a clean exit | yes |
+| `blocked` | a loop gave up here (ceiling, non-convergent, no verdict, not implementable) | `loop.sh` on any non-zero exit | yes, with the reason named |
+| `shipped` | the PR is open; the status flip is part of the release commit | `/ship` | no |
+
+**The resume contract.** Before every phase, `loop.sh` stamps `status: in-progress` plus `loop_pass`
+(the review pass it is on) and `loop_phase` (`build`/`review`/`fix`) into the spec — deterministically,
+with `awk`, spending **no tokens** on state it will need later. On exit it stamps a terminal status:
+`in-review` + `loop_phase: done` when clean, `blocked` otherwise. `/drive <id> --resume` then continues
+at the recorded pass instead of pass 1, so a session killed at pass 3 of 5 does not re-pay passes 1–2.
+The build is still skipped or redone by the build stamp alone (`specs/reports/<id>.built`, written only
+after a build that finished), so an interrupted *build* correctly rebuilds.
+
+Corollaries worth knowing:
+
+- A spec with no front-matter makes every stamp a **silent no-op** — the state is bookkeeping, and the
+  loop must never die over a status line.
+- Child commands write `status` too (`/fix` sets `in-review`); re-stamping before each phase is what
+  keeps `in-progress` true for the duration of the run rather than for its first phase.
+- `blocked` is not a failure to hide: it is the resumable state. `/build` accepts it, names it, and
+  routes by the spec's `## Remediation` (open items ⇒ `/fix`).
+
+## Dead agents — silence is not a green light
+
+A subagent can die mid-run: a rate limit, a transport error that outlived its retries, its own context
+exhausted on a big surface. When it does it returns **nothing** — and nothing is byte-identical to
+"finished, nothing to report". Every phase that fans out therefore does a **roll call** before it
+integrates anything, because the default reading of silence is the most dangerous one available:
+
+| phase | what a dead agent looks like | what the phase must do |
+| --- | --- | --- |
+| `/build` | a surface with no handoff | retry it **once** alone (byte-identical prompt), then mark it `dead`, verify the tree with that surface's own quiet commands, never call the batch ok |
+| `/review` | a reviewer with no report ⇒ **zero findings** | retry once, then list the surface in `unreviewed` and refuse to score `SHIP` |
+| `/fix` | a re-dispatched agent with no handoff | retry once, then leave **every** one of its items `- [ ]` — a dead agent never ticks a box |
+| workflows | `agent()` resolves to `null` | already enforced (`review.js` `unreviewedSurfaces`) — the doctrine started here |
+
+Non-negotiables, in every phase:
+
+- **Retry once, alone, byte-identical.** Most deaths are transient, and the other surfaces' work is
+  already on disk — so recovery costs one agent, never a rebuild. Never retry an agent that answered.
+- **Never speak for a dead agent.** You did not see its work: report what the *tree* says (quiet
+  commands, redirected to a file, grepped), not what a handoff would have said.
+- **Never let it reach a driver as clean.** `/build` writes `dead[]` into
+  `specs/reports/<id>.build.json`, `/review` writes `unreviewed[]` into the verdict; `scripts/loop.sh`
+  aborts on either with **exit 2** *before* it reads `blocking`, since a dead reviewer makes
+  `blocking == 0` a statement about code nobody read.
+- **`unreviewed` is separate from `blocking` on purpose.** Faking a count in `blocking` to force a
+  driver's hand would corrupt the one field the whole contract rests on; a driver reads them as two
+  different facts — "what was found" and "what was covered".
+- **Write the metrics line anyway** (`"<key>":"dead"`). An incomplete batch is exactly the batch worth
+  recording; holding the append back "until it's complete" deletes the evidence that anything failed.
+
+## Readiness — the gate between a frozen spec and N implementers
+
+`/build` §1.6 scores the frozen spec on **implementability** before authoring the contract and before
+dispatching anything, and writes `specs/reports/<id>.readiness.json`
+(`verdict`: `READY` · `RESERVATIONS` · `NOT-READY`, plus `gaps[]`). It costs **zero extra agents** — the
+lead already holds the spec, the profile and the reconciled surface list — which is the whole economics
+of the step: a spec that cannot be built does not get cheaper by being built on N surfaces in parallel.
+
+- Five checks: contract completeness · surface coverage · dependencies exist · residual ambiguity ·
+  the design gate. Each maps to `NOT-READY` (a surface would have to invent the answer) or
+  `RESERVATIONS` (a surface can proceed on a stated assumption).
+- **`NOT-READY` aborts the build with no agent spawned** and sends the human to `/spec`.
+  `scripts/loop.sh` reads the same file and exits **4** (`not implementable`) — the one loop outcome
+  that more passes cannot fix.
+- **`RESERVATIONS` never blocks.** Each gap is inlined verbatim into the dispatch of the surface it
+  affects, as an assumption the implementer must apply *and* flag in its handoff. A gate that stalled a
+  sound build on a missing error case would cost more human round-trips than it saves.
+
+## Deferred findings — real, but not this feature's problem
+
+`/review` ends on "zero blocking findings", so everything non-blocking used to be discarded with the
+report. A **deferred** finding is one the reviewer judges true and **out of this feature's scope**
+(pre-existing code the staged diff never touched, adjacent debt the spec never claims to fix). The
+review agent returns them in their own `## Deferred` section — never in `findings` — each carrying its
+own out-of-scope reason.
+
+- They count in **no** severity row, enter **no** verdict, and are **never** cross-checked: a deferred
+  item cannot cost a fix loop an iteration, and refuting one would spend an agent arguing about
+  something that cannot change the outcome.
+- **Not deferrable, ever:** anything the diff touched or introduced, any spec violation, any security
+  issue on a path this feature adds, calls or modifies.
+- `/review` §3.5 routes them, **on every verdict**, into `specs/refactor-backlog.md` under the
+  `## <domain>` heading of the owning surface, tagged `deferred:<feature_id>` — the same grouping
+  `/audit` writes, so `/refactor <domain>` picks them up with no extra plumbing. Never into the spec's
+  `## Remediation`, which is what `/fix` re-dispatches.
+- `/audit` **carries open `deferred:` items over** when it rewrites the backlog; overwriting them away
+  is the one way they silently vanish.
+- The verdict JSON carries `deferred: <n>` (informational, outside `blocking`), so `/drive` can name
+  them in its closing line without reading a report.
+
+## Decisions — the transverse decision journal
+
+`PIPELINE.md` is a **stack profile** (surfaces, commands, conventions); it says nothing about what this
+project has *decided*. Without somewhere for those, every `/spec` re-discovers or contradicts them.
+`specs/_decisions.md` (from `core/templates/decisions.template.md`) is that place, deliberately small:
+
+- **Append-only, one line per decision, ≤ ~160 chars:**
+  `- <YYYY-MM-DD> · <area> · <decision> — because <reason> · <feature_id>`. Reversal never edits a line:
+  append a superseding one (`· supersedes <date> <area>`) and move the old one to `## Superseded`. When
+  `## Live` passes ~100 lines, sweep the superseded ones down.
+- **Written by** `/spec` at freeze (the decisions that outlive the feature — typically 0–3 lines, and
+  zero is a normal outcome) and `/build` §1.5 when it adds or splits a surface.
+- **Read by the deciding stages only** — `/brainstorm` (so the panel argues about the idea, not about
+  settled ground), `/spec` (so a new spec does not silently un-decide something), `/audit` (standing
+  decisions are part of the rulebook it audits against).
+- **Never read by implementers or reviewers.** They work from the frozen contract, which already tells
+  them what to do; shipping them the rationale would cost `surfaces × dispatches` tokens per feature
+  for a fact they cannot act on. This is what keeps the journal cheap enough to be worth having.
+- The `_` prefix is load-bearing: `/doctor`, the dashboard spec scanner and the kanban backfill all skip
+  `specs/_*.md`, so the journal is never mistaken for a spec (no phantom card, no bogus stage).
+
 ## Preflight — the deterministic phase gate
 
 `/review` starts by running `pipeline/scripts/preflight.sh` — a plain shell script (no
@@ -313,6 +436,15 @@ files automatically. It works because every generated artifact is a **determinis
    clobber an existing filled file; report what was seeded.
 6. **Kanban sync.** Run the §Kanban reconcile: link/create the project's board if configured, verify
    its columns, and backfill/sync cards from `specs/*.md`. See §Kanban.
+7. **Spec-template top-up.** `specs/_template.md` is seeded once at install and then **never**
+   refreshed, so a repo keeps whatever front-matter the core shipped the day it was installed (a
+   pre-1.6 copy has no `loop_pass`/`loop_phase`, and its `status` comment still lists four states).
+   Top it up the same way as the profile: add the **front-matter fields** the current
+   `templates/spec.template.md` has and the repo's copy lacks, with their documented defaults, and
+   refresh the `status:` comment. Never rewrite its body — the section list is the human's to shape,
+   and some repos have deliberately trimmed it. Nothing breaks without this (the fields are written on
+   demand when a driver needs them); it just keeps a new spec's front-matter honest about the states
+   the pipeline can put it in.
 
 Re-running `/init-pipeline` remains possible (it reconciles too) but is only *needed* when the stack
 itself changes in ways `/build` §1.5 can't auto-grow (e.g. package manager or contract mechanism swap).
@@ -347,6 +479,9 @@ Shared design, all four scripts:
   that never answered: `review.js` names them in `unreviewedSurfaces` and refuses to score
   `SHIP`. `scripts/test-workflows.mjs`
   pins this — it is the one invariant the structural checks in `validate-core.mjs` cannot see.
+  The conversational commands enforce the same rule by roll call (§Dead agents); it was the workflows
+  that had it first, and for three releases they had it **alone** — the same crash on the
+  conversational path went unreported.
 - **`review.js`** — preflight gate (aborts red, zero agents), one `git diff --stat` staged per
   touched surface, one reviewer per surface in parallel, then an **adversarial cross-check** phase
   that tries to refute each CRITICAL/security finding before it can trigger a fix loop.
@@ -411,12 +546,16 @@ card created in the target column if missing.
 | `/build`                                | `building`      |
 | `/review`                               | `review`        |
 | `/fix`                                  | `fix`           |
+| a `/drive` is driving it (`in-progress`) | the current phase's column |
+| a `/drive` gave up (`blocked`)            | `fix`           |
 | `/ship` starts                          | `ship`          |
 | PR opened (`status: shipped`)           | `shipped` (+ `PR #<num>` on the card) |
 
 **Backfill / sync from specs (reconcile).** `specs/*.md` is the source of truth. For each spec, read its
 `feature_id` (front-matter or filename) and `status`, map `status`→column — `frozen`→`ready`,
-`in-review`→`review`, `shipped`→`shipped`, anything else / a spec with no status→`spec` — then **full
+`in-progress`→the `loop_phase`'s column (`build`→`building`, `review`→`review`, `fix`→`fix`; unset ⇒
+`building`), `in-review`→`review`, `blocked`→`fix`, `shipped`→`shipped`, anything else / a spec with no
+status→`spec` — then **full
 sync**: card absent ⇒ add it in that column; card present ⇒ **move it** to that column so the board
 always reflects the specs (this repositions cards the human may have moved by hand). Report cards
 added vs. moved vs. already-correct.

package/scripts/loop.sh

@@ -2,20 +2,26 @@
 #
 # loop.sh — autonomous /build → /review → /fix → /review … loop for ONE feature.
 #
-#   loop.sh <feature-id> [--max=N] [--no-build] [--rebuild]
+#   loop.sh <feature-id> [--max=N] [--no-build] [--rebuild] [--resume]
 #
 # THE POINT: every phase runs as a SEPARATE `claude -p` child with its own fresh
-# context. The session that typed /loop never sees the diff, the N review reports
+# context. The session that typed /drive never sees the diff, the N review reports
 # or the N contracts — it reads only this script's one-line-per-phase stdout and,
 # at the end, the verdict JSON. Running the loop inside the calling session would
 # accumulate all of it in a history that is re-sent at input price on every turn,
 # which is the exact cost the pipeline's /clear discipline exists to avoid.
 #
 # Contract with the pipeline: /review writes specs/reports/<id>.verdict.json on
-# every run. That file — `blocking` and `fingerprint` — is the ONLY channel
-# between cohorte and this driver. No prose is parsed.
+# every run, and /build writes <id>.readiness.json + <id>.build.json. Those three
+# files — `blocking`, `fingerprint`, `unreviewed`, `verdict`, `dead` — are the ONLY
+# channel between cohorte and this driver. No prose is parsed.
 #
-# Exit codes (three distinct diagnostics, do not collapse them):
+# Two of those fields exist for the same reason: a subagent that DIES returns
+# nothing, and nothing is byte-identical to "clean". A dead implementer means a
+# surface was never built; a dead reviewer means a surface was never audited, and
+# `blocking == 0` would then certify code no one read. Both abort as exit 2.
+#
+# Exit codes (distinct diagnostics, do not collapse them):
 #   0   clean — a review returned blocking == 0
 #   1   ceiling — --max passes used, still blocking (the fix was progressing;
 #       re-run with a higher --max)
@@ -23,22 +29,37 @@
 #       preflight (typecheck/lint/tests broken; the message says which)
 #   3   non-convergent — two consecutive reviews returned the SAME blocking
 #       fingerprint: the fix is treading water, a higher --max will not help
+#   4   not implementable — /build's readiness gate returned NOT-READY and spawned
+#       no agent: the frozen spec cannot be built (missing contract shape, unowned
+#       area, absent dependency). Needs /spec, not more passes.
 #   64  usage — bad flag, bad id, missing spec, no `claude` on PATH
 #
 # No /fix runs on the last pass: fixing without a review behind it ships
 # unaudited code. Each fix pass is committed — that commit is the only way back
 # after N autonomous passes.
+#
+# RESUME: the spec's front-matter IS the loop's state (SCHEMA.md §Spec status).
+# Before every phase this script stamps `status: in-progress` + `loop_phase` +
+# `loop_pass` into specs/<id>.md — deterministically, with awk, costing no tokens
+# — and on exit stamps a terminal status (`in-review` clean, `blocked` otherwise).
+# `--resume` reads `loop_pass` back and continues from that pass instead of 1, so
+# a session that died at pass 3 of 5 does not re-pay passes 1 and 2. The build is
+# skipped or redone by the same stamp logic as always (the stamp is only written
+# on a build that finished), so an interrupted build still rebuilds.
 
 set -uo pipefail
 
 usage() {
   cat >&2 <<'EOF'
-usage: loop.sh <feature-id> [--max=N] [--no-build] [--rebuild]
+usage: loop.sh <feature-id> [--max=N] [--no-build] [--rebuild] [--resume]
 
-  --max=N      stop after N review passes (default 5)
+  --max=N      stop after N review passes (default 5) — a ceiling on the TOTAL
+               pass count, so it still means "5 passes" when resuming at pass 3
   --no-build   never build — re-run the /review ⇄ /fix loop on a feature that
                is already built (the common case; the build stamp is ignored)
   --rebuild    force a /build even if the stamp says it was already built
+  --resume     continue from the pass recorded in the spec's front-matter
+               (loop_pass), instead of starting over at pass 1
 
   env CLAUDE_FLAGS   flags for every child session
                      (default: --permission-mode acceptEdits)
@@ -49,6 +70,7 @@ EOF
 id=""
 max=5
 build_mode="auto"          # auto | never | force
+resume=0
 
 for arg in "$@"; do
   case "$arg" in
@@ -61,6 +83,7 @@ for arg in "$@"; do
       ;;
     --no-build) build_mode="never" ;;
     --rebuild)  build_mode="force" ;;
+    --resume)   resume=1 ;;
     -h|--help)  usage ;;
     -*)         echo "loop: unknown flag: $arg" >&2; usage ;;
     *)
@@ -93,9 +116,47 @@ spec="specs/$id.md"
 reports="specs/reports"
 mkdir -p "$reports"
 verdict="$reports/$id.verdict.json"
+readiness="$reports/$id.readiness.json"
+buildjson="$reports/$id.build.json"
 stamp="$reports/$id.built"
 log="$reports/$id.loop.log"
 
+# --- the spec front-matter as loop state -------------------------------------
+# Best-effort by design: a spec with no front-matter (or an unwritable one) makes
+# every fm_* call a silent no-op. This is bookkeeping for resume + the dashboard,
+# never a precondition — the loop must not die over a status line.
+fm_get() {                        # fm_get <key>  → value, or empty
+  [ -f "$spec" ] || return 0
+  awk -v k="$1" '
+    NR==1 && $0=="---" { fm=1; next }
+    fm==1 && $0=="---" { exit }
+    fm==1 && $0 ~ "^"k":" {
+      sub("^"k":[[:space:]]*", ""); sub("#.*", "")
+      gsub(/^[[:space:]]+|[[:space:]]+$/, ""); print; exit
+    }
+  ' "$spec"
+}
+
+fm_set() {                        # fm_set <key> <value>  (replace, else append)
+  [ -f "$spec" ] || return 0
+  awk -v k="$1" -v v="$2" '
+    NR==1 && $0!="---" { nofm=1 }
+    nofm { print; next }
+    NR==1 { fm=1; print; next }
+    fm==1 && $0=="---" {
+      if (!done) print k ": " v          # key absent: add it before the closing ---
+      fm=2; print; next
+    }
+    fm==1 && $0 ~ "^"k":" {
+      if (done) next                     # a duplicate key: drop it
+      c=""; i=index($0, "#"); if (i>0) c=" " substr($0, i)   # keep a trailing comment
+      print k ": " v c; done=1; next
+    }
+    { print }
+  ' "$spec" >"$spec.loop.tmp" 2>/dev/null &&
+    mv "$spec.loop.tmp" "$spec" 2>/dev/null || rm -f "$spec.loop.tmp"
+}
+
 : "${CLAUDE_FLAGS:=--permission-mode acceptEdits}"
 
 : >"$log"
@@ -110,6 +171,13 @@ log="$reports/$id.loop.log"
 # $CLAUDE_FLAGS is intentionally unquoted — it is a flag list, not one word.
 run_phase() {
   cmd="$1"
+  # Stamp the state BEFORE the phase runs: if this child dies (or the whole
+  # session does), the spec already says where the loop was — that is what
+  # --resume reads back. Child commands write `status` themselves (/fix sets
+  # in-review); re-stamping here each phase is what keeps `in-progress` true.
+  fm_set status in-progress
+  fm_set loop_pass "$pass"
+  fm_set loop_phase "$cmd"
   printf '▶ /%-6s %-24s ' "$cmd" "$id"
   printf '\n\n===== /%s %s =====\n' "$cmd" "$id" >>"$log"
   # shellcheck disable=SC2086
@@ -127,7 +195,31 @@ run_phase() {
 json_num() { sed -n 's/.*"'"$2"'"[[:space:]]*:[[:space:]]*\([0-9][0-9]*\).*/\1/p' "$1" | head -n1; }
 json_str() { sed -n 's/.*"'"$2"'"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$1" | head -n1; }
 
-finish() { echo "$2"; exit "$1"; }
+# Terminal status goes into the spec, not just into this stdout: a clean run
+# leaves the feature ready to /ship, any failure leaves it visibly `blocked` for
+# the human and for the dashboard. Exit 64 never reaches here (usage dies earlier),
+# so every code handled below is a real run outcome.
+finish() {
+  if [ "$1" -eq 0 ]; then
+    fm_set status in-review
+    fm_set loop_pass 0
+    fm_set loop_phase done
+  else
+    fm_set status blocked
+  fi
+  echo "$2"
+  exit "$1"
+}
+
+# One short clause naming the deferred findings, appended to a closing line.
+# They are NOT blocking (they live in the backlog, not in ## Remediation), so
+# they never change an exit code — but a loop that silently drops them is the
+# leak /review §3.5 exists to close, so the driver names them.
+def_note() {
+  d="$(json_num "$verdict" deferred 2>/dev/null)"
+  case "$d" in ''|0) return 0 ;; esac
+  printf ' · %s deferred finding(s) parked in specs/refactor-backlog.md' "$d"
+}
 
 # --- build -------------------------------------------------------------------
 # The stamp is the driver's own bookkeeping — /build knows nothing about it.
@@ -137,14 +229,44 @@ case "$build_mode" in
   auto)  [ -f "$stamp" ] && do_build=0 || do_build=1 ;;
 esac
 
+# --resume: continue from the pass the spec records, not from 1. A missing or
+# junk value falls back to 1 — resuming must never be less safe than starting.
+pass=1
+if [ "$resume" -eq 1 ]; then
+  rp="$(fm_get loop_pass)"
+  case "$rp" in ''|*[!0-9]*|0) rp=1 ;; esac
+  [ "$rp" -le "$max" ] || {
+    echo "loop: --resume says pass $rp but --max=$max — raise --max to continue" >&2; exit 64; }
+  pass="$rp"
+  [ "$pass" -eq 1 ] || printf '↻ resuming at review pass %s (from %s)\n' "$pass" "$spec"
+fi
+
 if [ "$do_build" -eq 1 ]; then
-  run_phase build || finish 2 "✗ /build failed — see $log"
+  # Delete first: a NOT-READY left by a previous build would abort this one on
+  # someone else's verdict (and a stale READY would hide a gate that never ran).
+  rm -f "$readiness" "$buildjson"
+  build_ok=0
+  run_phase build && build_ok=1
+  # The readiness gate is checked BEFORE the child's exit status: /build aborting
+  # on NOT-READY is a cleaner diagnosis than "/build failed", and it is the one
+  # outcome that more passes cannot fix.
+  if [ -f "$readiness" ] &&
+     grep -q '"verdict"[[:space:]]*:[[:space:]]*"NOT-READY"' "$readiness"; then
+    finish 4 "✗ spec not implementable — /build's readiness gate returned NOT-READY and spawned no agent; see $readiness, then /spec $id"
+  fi
+  # A dead implementer returns nothing, so /build can finish "successfully" having
+  # built one surface of two. Reviewing that would spend N reviewers auditing a
+  # half-built feature and report its gaps as findings to fix — the wrong diagnosis
+  # at the wrong price. `dead` is a non-empty array only when a surface died twice.
+  if [ -f "$buildjson" ] && grep -q '"dead"[[:space:]]*:[[:space:]]*\[[^]]' "$buildjson"; then
+    finish 2 "✗ an implementer died — the surface(s) in \"dead\" were never built; see $buildjson and $log"
+  fi
+  [ "$build_ok" -eq 1 ] || finish 2 "✗ /build failed — see $log"
   date -u +%Y-%m-%dT%H:%M:%SZ >"$stamp"
 fi
 
 # --- review ⇄ fix ------------------------------------------------------------
 prev_fp=""
-pass=1
 while [ "$pass" -le "$max" ]; do
   # Delete first: a stale verdict from the previous pass read as this pass's
   # answer would end the loop on someone else's numbers.
@@ -158,12 +280,19 @@ while [ "$pass" -le "$max" ]; do
     finish 2 "✗ /review aborted on a red preflight — typecheck/lint/tests are broken, see $reports/$id.preflight.txt"
   fi
 
+  # A reviewer that died twice leaves its surface unaudited, and `blocking` counts only
+  # what the SURVIVING reviewers found — so blocking == 0 here would mean "clean" about
+  # code nobody read. Checked BEFORE blocking, because it invalidates it.
+  if grep -q '"unreviewed"[[:space:]]*:[[:space:]]*\[[^]]' "$verdict"; then
+    finish 2 "✗ a reviewer died — the surface(s) in \"unreviewed\" carry no verdict (pass $pass); see $verdict"
+  fi
+
   blocking="$(json_num "$verdict" blocking)"
   [ -n "$blocking" ] || finish 2 \
     "✗ verdict has no usable 'blocking' count (pass $pass) — see $verdict"
 
   [ "$blocking" -eq 0 ] && finish 0 \
-    "✓ clean after $pass review pass(es) — no blocking findings"
+    "✓ clean after $pass review pass(es) — no blocking findings$(def_note)"
 
   fp="$(json_str "$verdict" fingerprint)"
   if [ -n "$fp" ] && [ "$fp" = "$prev_fp" ]; then
@@ -173,7 +302,7 @@ while [ "$pass" -le "$max" ]; do
 
   # Last pass: report and stop. A /fix here would leave unreviewed code behind.
   [ "$pass" -eq "$max" ] && finish 1 \
-    "✗ ceiling — $blocking blocking finding(s) after $max pass(es); re-run with a higher --max"
+    "✗ ceiling — $blocking blocking finding(s) after $max pass(es); re-run with a higher --max --resume$(def_note)"
 
   run_phase fix || true