cohorte 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -3,13 +3,97 @@
 Entries are shown by `/update-pipeline` ("What's new") after a core refresh. Keep them short,
 user-facing, most recent first. One `## <version> — <YYYY-MM-DD>` section per release.
 
+## 1.6.0 — 2026-08-01
+
+> **Re-run `npx cohorte@latest update --global` (or `update`)** to pick up the readiness gate, the
+> deferred-findings route, the resumable driver and the decision journal — the update *deletes* the
+> shadowed `/loop` command and the long-dead `/cycle` from your install, it does not just stop
+> shipping them. Existing specs keep working: the new front-matter fields are written on demand, and a
+> spec without them simply isn't resumable yet. **`/loop <id>` is now `/drive <id>`.**
+
+- **New — the readiness gate between `/spec` and `/build`.** `/build` §1.6 now scores the frozen spec
+  on **implementability** before authoring the contract and before dispatching anything: contract
+  shapes complete · every area owned by a surface · named dependencies actually exist · no ambiguity a
+  surface would have to guess at · design links present. The verdict goes to
+  `specs/reports/<id>.readiness.json` (`READY` · `RESERVATIONS` · `NOT-READY` + `gaps[]`).
+  **`NOT-READY` stops the build with zero agents spawned** — a spec that can't be built doesn't get
+  cheaper by being built on N surfaces in parallel — and sends you to `/spec`. `RESERVATIONS` never
+  blocks: each gap is inlined into the affected surface's dispatch as an assumption the implementer
+  applies *and* flags in its handoff. It costs **no extra agent**: the lead already holds the spec,
+  the profile and the reconciled surface list.
+- **New — deferred findings: `/review` stops throwing away what isn't blocking.** The review agent
+  now returns a separate `## Deferred` section (max 10) for what is real but **out of this feature's
+  scope** — pre-existing code the diff never touched, adjacent debt the spec never claims to fix —
+  each line carrying its own out-of-scope reason. Deferred items count in no severity row, move no
+  verdict, are never cross-checked, and on **every** verdict get routed into
+  `specs/refactor-backlog.md` under the owning surface's `## <domain>` heading, tagged
+  `deferred:<id>`. So `/review` feeds `/refactor` for free instead of dropping everything
+  non-blocking on the floor. Never into `## Remediation`, which is what `/fix` re-dispatches. Not
+  deferrable, ever: anything the diff touched, any spec violation, any security issue on a path this
+  feature adds or calls. `/audit` now **carries open `deferred:` items over** when it rewrites the
+  backlog. The verdict JSON gains `deferred: <n>` (informational, outside `blocking`).
+- **BREAKING — `/loop` is renamed `/drive`, because Claude Code shadowed it.** Claude Code ships its
+  own built-in `/loop` (run a prompt on a recurring interval), which won the name: typing
+  `/loop <id>` started the *interval runner* with the feature id as its prompt, so cohorte's driver
+  never ran — and the session, having never seen `loop.md`, reported a loop that did not exist. Same
+  command, same flags, same script (`pipeline/scripts/loop.sh` keeps its name — nothing about your
+  install paths changes): type **`/drive <id>`**. The update scrubs the old `commands/loop.md`, so a
+  stale shadowed copy can't linger.
+- **`/drive` is resumable — the spec's status is the state machine.** The lifecycle is now
+  `draft → frozen → in-progress → in-review → shipped` plus `blocked`. Before every phase the driver
+  stamps `status: in-progress` + `loop_pass` + `loop_phase` into the spec's front-matter — plain
+  `awk`, a temp file and `mv`, **zero tokens** — and on exit a terminal `in-review` (clean) or
+  `blocked`. **`/drive <id> --resume`** then continues at the pass it reached instead of re-paying the
+  ones already made, whether the session died, the ceiling hit, or the fix stopped converging.
+  `--max` stays a ceiling on the *total* passes. New **exit 4** (`not implementable`) relays the
+  readiness gate's `NOT-READY`: the one loop outcome more passes cannot fix. The dashboard's specs
+  board gains In-progress and Blocked columns and shows `↻ pass 3 · /review` on the card; `/doctor`
+  names any spec left mid-loop.
+- **Fixed — a dead subagent no longer reads as a clean one on the conversational path.** The
+  "a dead agent is never a clean result" doctrine existed since 1.3.4 — but only inside the
+  **workflows**. `/build`, `/review` and `/fix` had nothing: a subagent that dies (rate limit,
+  transport error, exhausted context) returns *nothing*, and nothing was indistinguishable from
+  "finished, nothing to report". Concretely, a dead **reviewer** produced zero findings ⇒
+  `blocking: 0` ⇒ verdict `SHIP` ⇒ `/drive` exit 0 ⇒ the human sent to `/ship` — a clean bill of
+  health on code no agent ever read. Now every fan-out phase does a **roll call** before integrating:
+  a silent surface is retried **once** alone (byte-identical prompt, so recovery costs one agent, not
+  a rebuild), then `/build` marks it `dead` and verifies the tree with that surface's own quiet
+  commands instead of speaking for the agent, `/review` lists it in the verdict's new `unreviewed[]`
+  and **refuses to score `SHIP`**, and `/fix` leaves every one of its items `- [ ]` (a dead agent
+  never ticks a box). `/build` also writes `specs/reports/<id>.build.json` with `dead[]`, and
+  `loop.sh` aborts on either signal with **exit 2** *before* reading `blocking` — because a dead
+  reviewer makes `blocking == 0` a statement about unread code. `unreviewed` is deliberately kept
+  out of `blocking`: faking a count there would corrupt the one field the driver contract rests on.
+  The metrics line is now written even when a surface died (`"<key>":"dead"`) — an incomplete batch
+  is exactly the batch worth recording.
+- **Fixed — `/cycle` and its workflow were removed in 1.4.0 but no installer ever scrubbed them.**
+  Every install since has kept `commands/cycle.md` + `workflows/cycle.js` on disk, so a dead command
+  stayed listed and invokable — dispatching a workflow whose phases 1.5.0 then deleted. All three
+  installers now remove them (as they already did for `/smoke`), and CI **plants the orphans before
+  re-installing** instead of asserting their absence on a fresh scratch home, which is exactly the
+  blind spot that let this survive four releases.
+- **Reconcile now tops up `specs/_template.md`.** It was seeded once at install and never refreshed,
+  so every repo kept the front-matter its core shipped with. `/update-pipeline` adds the missing
+  front-matter fields (never the body — the section list is yours).
+- **New — `specs/_decisions.md`, the transverse decision journal.** `PIPELINE.md` is a *stack* profile;
+  it says nothing about what the project has **decided**, so every `/spec` re-discovered or
+  contradicted the same choices. The journal is deliberately tiny: **append-only, one line per
+  decision** (`- <date> · <area> · <decision> — because <reason> · <feature_id>`), reversal by a
+  superseding line rather than an edit. Written by `/spec` at freeze (typically 0–3 lines; zero is
+  normal) and by `/build` when it adds or splits a surface. Read by the **deciding** stages only —
+  `/brainstorm`, `/spec`, `/audit`. **Implementers and reviewers never load it:** they have the frozen
+  contract, and shipping them the rationale would cost `surfaces × dispatches` tokens per feature for
+  a fact they can't act on. That exclusion is what keeps it cheap enough to be worth having. The `_`
+  prefix means `/doctor`, the dashboard scanner and the kanban backfill already skip it.
+
 ## 1.5.0 — 2026-08-01
 
 > **Re-run `npx cohorte@latest update --global` (or `update`)** to pick up the collector and the
 > `/smoke` removal — the update *deletes* the command and its agent from your install, it does not
 > just stop shipping them. The new dashboard panel comes with `npx cohorte dashboard`.
 
-- **New — `/loop <id>`: the review ⇄ fix cycle, run for you.** `/build` → `/review` → `/fix` →
+- **New — `/loop <id>`: the review ⇄ fix cycle, run for you.** _(renamed `/drive` in 1.6.0 — see
+  there.)_ `/build` → `/review` → `/fix` →
   `/review` … until a review reports **zero blocking findings** (a CRITICAL or a security issue —
   a LOW nit never costs a pass), or the pass ceiling (`--max=N`, default 5), or two consecutive
   reviews returning the *same* blocking findings, which means the fix is treading water and more

package/README.md

@@ -131,7 +131,8 @@ design system), **interviews** you for the gaps, and **generates**:
   symbols instead of grep-and-reading whole files; `graphify` or `none` also available via the
   profile's `retrieval.provider`)
 - `scripts/new-feature.sh` + `remove-feature.sh` — parallel worktree isolation (if you enable it)
-- `specs/_template.md`
+- `specs/_template.md` (and, on first decision, `specs/_decisions.md` — the project's one-line-per-decision
+  journal, read by `/brainstorm`, `/spec` and `/audit` so features stop re-litigating settled ground)
 
 Sanity-check `PIPELINE.md`, commit it, and run `/brainstorm`.
 
@@ -216,10 +217,10 @@ it in `.claude/pipeline/VERSION` and bundled repos in their committed `pipeline.
 | `/init-pipeline`     | Detect stack → interview → generate the profile + agents. Run once per project.       |
 | `/brainstorm`        | Interactive persona panel that pressure-tests a feature idea.                         |
 | `/spec`              | Freeze the feature spec + contract into `specs/<id>.md` (UI features also get a standalone design brief at `specs/design/<id>.md`). Also applies review returns. |
-| `/build <id>`        | Lead authors the contract, then dispatches one implementer per surface in parallel.   |
-| `/review <id>`       | Read-only review agents (one per touched surface, parallel) audit the diff vs the spec. |
+| `/build <id>`        | Readiness gate on the frozen spec, then the lead authors the contract and dispatches one implementer per surface in parallel. |
+| `/review <id>`       | Read-only review agents (one per touched surface, parallel) audit the diff vs the spec; out-of-scope findings go to the refactor backlog. |
 | `/fix <id>`          | Apply a review report: remediation into the spec, re-dispatch only the surfaces with findings. |
-| `/loop <id>`         | Autonomous `/build → /review → /fix → /review …` until no blocking finding is left (see below). |
+| `/drive <id>`         | Autonomous `/build → /review → /fix → /review …` until no blocking finding is left (see below). |
 | `/ship <id>`         | Release agent commits, pushes, opens the PR; watches CI; proposes worktree teardown.  |
 | `/audit [path]`      | Prioritized refactor backlog for existing code.                                       |
 | `/refactor <domain>` | Apply the backlog for one surface, TDD-first.                                         |
@@ -243,19 +244,26 @@ lever: long sessions (>150k) are expensive even when cached. Each command tells
 safe to clear. If you'd rather stay in one session, `/compact` mid-task does the lighter version. (Claude
 can't fire `/clear` itself — it's a client-side command; the pipeline just makes it always safe to type.)
 
-### Let it run itself — `/loop`
+### Let it run itself — `/drive`
 
 ```
-/loop feat-x              # /build, then /review ⇄ /fix until clean (max 5 passes)
-/loop feat-x --no-build   # already built — just re-run the /review ⇄ /fix loop
-/loop feat-x --max=8
+/drive feat-x              # /build, then /review ⇄ /fix until clean (max 5 passes)
+/drive feat-x --no-build   # already built — just re-run the /review ⇄ /fix loop
+/drive feat-x --max=8
+/drive feat-x --resume     # continue a run that died / hit the ceiling, at the pass it reached
 ```
 
 It stops when `/review` reports **zero blocking findings** (a CRITICAL or a security issue — a LOW
-nit never costs a pass), at the pass ceiling, or as soon as two consecutive reviews return the same
-blocking findings, which means the fix is treading water and more passes won't help. **Each fix pass
-is committed** (`loop(<id>): fix pass <i>`) — that's your way back after N autonomous passes — and
-**no fix runs on the last pass**, since fixing without a review behind it leaves unaudited code.
+nit never costs a pass), at the pass ceiling, as soon as two consecutive reviews return the same
+blocking findings (the fix is treading water and more passes won't help), or immediately if `/build`'s
+readiness gate says the frozen spec **cannot be built** — that one needs `/spec`, not passes. **Each
+fix pass is committed** (`loop(<id>): fix pass <i>`) — that's your way back after N autonomous passes —
+and **no fix runs on the last pass**, since fixing without a review behind it leaves unaudited code.
+
+**It's resumable.** Before each phase the driver stamps `status: in-progress` + `loop_pass` +
+`loop_phase` into the spec's front-matter (plain `awk`, zero tokens), and a terminal `in-review` or
+`blocked` on exit. So `--resume` continues at pass 3 instead of re-paying passes 1 and 2 — and the spec
+itself tells you, `/doctor` and the dashboard where the loop got to.
 
 **The loop does not run in your session.** Each phase is a separate `claude -p` child with its own
 fresh context, driven by `pipeline/scripts/loop.sh`; all of their output goes to

package/bin/cli.js

@@ -227,6 +227,14 @@ function copyFixedAgents() {
   // 1.5.0 removed the /smoke phase; copy-over never deletes, so scrub the orphan agent+command.
   fs.rmSync(path.join(dest, 'agents', 'smoke.md'), { force: true });
   fs.rmSync(path.join(dest, 'commands', 'smoke.md'), { force: true });
+  // 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.
+  fs.rmSync(path.join(dest, 'commands', 'cycle.md'), { force: true });
+  fs.rmSync(path.join(dest, 'workflows', 'cycle.js'), { force: true });
+  // 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.
+  fs.rmSync(path.join(dest, 'commands', 'loop.md'), { force: true });
   scrubResearchQuestionnaire();
 }
 

package/core/agents/review.md

@@ -81,6 +81,24 @@ domain** (same finding-line shape) instead of a SHIP/REVISE/BLOCK verdict.
 - Any **security vulnerability** ⇒ verdict **BLOCK**.
 - No CRITICAL and no security issue ⇒ verdict **SHIP**.
 
+## Deferred — real, but not this feature's problem
+
+A finding is **deferred** when it is genuinely true and genuinely **out of this feature's scope**:
+pre-existing code the staged diff did not touch, adjacent debt the spec never claims to fix, a
+convention violation that predates this work. Deferring is not softening — it is naming the right
+owner. The lead routes deferred findings to `specs/refactor-backlog.md` (they feed `/refactor`), so
+they are **never lost and never cost a fix loop**.
+
+- **Deferred findings are separate from your findings list** and count in **no** severity row: the
+  severity table drives the verdict, and a deferred item must never force one.
+- **Deferrable:** a problem entirely in lines/files the diff did not change, whose fix is not required
+  by any acceptance criterion of this spec.
+- **NOT deferrable, ever:** anything the diff touched or introduced; any spec violation; any
+  **security** issue on a path this feature adds, calls or modifies (a pre-existing hole this feature
+  now exposes to new traffic is this feature's problem). When in doubt, it is a finding, not a deferral.
+- Cap the deferred list at **10 lines**, worst first; each carries its own out-of-scope reason so the
+  lead can route it without re-reading anything.
+
 ## Your return — the REVIEW REPORT, exactly this shape
 
 Every finding must be **self-sufficient for a stateless agent**: `file:line` · severity ·
@@ -110,6 +128,11 @@ Verdict: <SHIP | REVISE | BLOCK>
 - **[<SEVERITY>]** `<file>:<line>` · <spec-violation|quality|security> · <problem> → **Fix:** <concrete change>
 (order by severity; "None." if none; max 20 lines, one per finding, no code excerpts)
 
+## Deferred
+
+- **[<SEVERITY>]** `<file>:<line>` · <quality|security> · <problem> → **Fix:** <concrete change> · out of scope: <why this feature does not own it>
+(real but out of this feature's scope — see §Deferred; worst first; "None." if none; max 10 lines)
+
 ## Notes
 (ONLY the RBAC / mobile-first assessment when the profile enables them; omit the section otherwise)
 ```

package/core/commands/audit.md

@@ -7,7 +7,9 @@ argument-hint: [path or domain, default = whole repo]
 You are the **lead**. Audit **$ARGUMENTS** (default: whole repo) to drive it to a clean base. Read +
 analyze only — no fixes (those go through `/refactor`).
 
-> Read `PIPELINE.md` §`commands` (the mechanical gates), `surfaces`, and §Conventions.
+> Read `PIPELINE.md` §`commands` (the mechanical gates), `surfaces`, and §Conventions — plus
+> `specs/_decisions.md` §Live if it exists (SCHEMA.md §Decisions): those standing decisions are part
+> of the rulebook you audit against, and code that contradicts one is a finding like any other.
 >
 > **Workflow variant** (opt-in — SCHEMA.md §Workflows): on Claude Code ≥ 2.1.154 with workflows
 > enabled, the human can ask to "run the audit workflow" (`<core>/workflows/audit.js` — one auditor
@@ -39,5 +41,11 @@ from your instructions), grouped by domain (one group per surface + shared). —
 Merge mechanical + convention findings into one prioritized backlog and **write
 `specs/refactor-backlog.md`**, grouped by domain, each item:
 `- [ ] <SEVERITY> · <file:line> · <rule|tdd|lint|format|type|security> · <concrete fix>`
+
+**Carry over the deferred items** before overwriting: `grep -n 'deferred:' specs/refactor-backlog.md`
+and re-emit every **open** (`- [ ]`) match verbatim under its domain, tag included. Those lines were
+put there by `/review` §3.5 — a real finding a feature deliberately did not own — and an audit that
+blindly overwrites the file is the one way they silently disappear. Already-ticked (`- [x]`) ones are
+done: drop them.
 Print a short summary (counts per domain + top items). Tell the human: refactor a domain with
 `/refactor <domain>`.

package/core/commands/brainstorm.md

@@ -11,6 +11,12 @@ at Finish, when a board is configured.
 > Read `PIPELINE.md` §Personas (the panel) and §`rbac` first. If `rbac.enabled`, the panel must
 > pressure-test the idea so it serves **every** role, not just admins.
 >
+> Also read `specs/_decisions.md` §Live if it exists (SCHEMA.md §Decisions) — one line per standing
+> decision. The panel argues about the idea, not about settled ground: a persona that proposes
+> something a live line already decided must be told so by another persona, and an idea that genuinely
+> needs to overturn one must say which line, out loud, so the human decides it here rather than
+> discovering the contradiction at `/spec`.
+>
 > Template paths below (`.claude/templates/…`) resolve to `~/.claude/templates/…` when the core is
 > installed globally — read whichever exists.
 >

package/core/commands/build.md

@@ -16,8 +16,11 @@ You are the **lead**. Build feature **$ARGUMENTS** from its frozen spec.
 ## 1. Load & check
 
 - Check the spec front-matter FIRST — `grep '^status:' specs/$ARGUMENTS.md` (or Read with a ~15-line
-  limit) — before any full read. If missing or `status` not `frozen`/`in-review`, stop — tell the human
-  to run `/spec` first. Only then read the body, selectively: front-matter, §5 contract, the surface
+  limit) — before any full read. Buildable statuses are `frozen`, `in-review` and `in-progress` (the
+  last one means a `/drive` is or was driving this spec — SCHEMA.md §Spec status). `blocked` means a
+  loop gave up here: say so, and route by the spec's `## Remediation` — open items ⇒ `/fix`, none ⇒
+  continue this build. Anything else (`draft`, missing, `shipped`) ⇒ stop and tell the human to run
+  `/spec` first. Only then read the body, selectively: front-matter, §5 contract, the surface
   task sections, and `## Remediation` (fall back to a full read if the spec doesn't follow the
   template's headings).
 - **Route check** — if `## Remediation` has open `- [ ]` items and none requires a contract change,
@@ -56,6 +59,59 @@ shared-code rule (shared trees get a single-owner surface; cross-slice shapes go
 This is the automatic path: you don't send the human back to `/init-pipeline`. If nothing new is needed,
 say so and continue. Dispatch (§3) then covers the reconciled surface list.
 
+**Adding or splitting a surface is an architectural decision** — append ONE line for it to
+`specs/_decisions.md` §Live (SCHEMA.md §Decisions; create from `.claude/templates/decisions.template.md`
+if absent), area `surfaces`, e.g.
+`- <date> · surfaces · <key> owns <path>, single owner of <what> — because <the boundary reason> · $ARGUMENTS`.
+One `>>` in the Bash call you're already making. Nothing added ⇒ nothing to append.
+
+## 1.6 Readiness verdict — the gate before N dispatches
+
+**Zero extra agents: you already hold the spec, the profile and the reconciled surface list.** The
+whole point is that a bancal spec costs one verdict here instead of N implementers discovering it in
+parallel. Judge the frozen contract on **implementability only** — never on whether the feature is a
+good idea (that was `/brainstorm`), never by re-reading files you don't already need:
+
+1. **Contract completeness** (§5) — every endpoint/interface has method+path (or signature), auth,
+   request fields with types + validation, the success shape, and its error cases. A missing
+   **request or success shape** ⇒ `NOT-READY` (an implementer would invent it, and the other surface
+   would invent a different one). A missing **error case** ⇒ `RESERVATIONS`.
+2. **Surface coverage** — every §6 task maps to a surface in the reconciled list, and every contract
+   entry has an owner **on each side it names** (producer and consumer). A contract entry no surface
+   owns ⇒ `NOT-READY`.
+3. **Dependencies exist** — for the modules, packages, tables, env vars and shared helpers the spec
+   names as *pre-existing*: verify them in ONE Bash call (`test -f` / `grep -l` / a package-manifest
+   grep, output redirected — never a file read per name). Named as pre-existing but absent, and not
+   listed as created by this feature ⇒ `NOT-READY`.
+4. **Residual ambiguity** (§10) — an open question a surface would have to *guess* at: blocks a
+   contract decision ⇒ `NOT-READY`; merely narrows an implementation choice ⇒ `RESERVATIONS`.
+5. **Design gate** — a `uses_design` surface in scope with `design_files` still empty ⇒ `NOT-READY`
+   (this is §1's gate restated as a verdict, so an automated driver sees the same fact).
+
+Write the machine-readable verdict to `specs/reports/$ARGUMENTS.readiness.json` (overwrite,
+`mkdir -p specs/reports` first — the same gitignored buffer dir `/review` stages into, which may not
+exist yet on a first build) — on **every** build, including `READY`. It is the only channel between this gate and a driver (`/drive`),
+which parses no prose:
+
+```json
+{ "id": "$ARGUMENTS", "phase": "readiness", "ts": "<ISO>", "verdict": "RESERVATIONS",
+  "gaps": ["contract|POST /orders|no 409 case for a duplicate id"],
+  "surfaces": ["backend", "frontend"] }
+```
+
+- **`gaps`** — one normalized string per gap, `<check>|<where>|<what is missing>`: `<check>` is
+  `contract` · `coverage` · `dependency` · `ambiguity` · `design`; `<where>` is the contract entry,
+  surface key or dependency name (no `:line` — it shifts on every edit); `<what>` is the gap, not the
+  fix. `READY` ⇒ `[]`.
+- **`NOT-READY` ⇒ STOP: author no contract and spawn NO agent.** Print the gaps and send the human to
+  `/spec $ARGUMENTS` to patch the contract, then re-run `/build`. This abort is the whole point of the
+  step — a spec that cannot be built does not get cheaper by being built N times in parallel.
+- **`RESERVATIONS` ⇒ continue.** It never blocks (a gate that stalls a sound build on a missing error
+  case would cost more human round-trips than it saves): inline each gap verbatim into the dispatch of
+  the surface it affects, as an explicit assumption the agent must implement *and* flag in its handoff,
+  and relay the list to the human in one line each.
+- **`READY` ⇒ continue silently** — one line, no restatement.
+
 ## 2. Author the contract (lead-only — the single sync channel)
 
 _Only if `contract.enabled`._ From §5 of the spec, write/update the feature's contract file at
@@ -87,19 +143,46 @@ tree. For each surface in `surfaces`:
 > via `DesignSync get_file`, build mobile-first · or `none` (non-design surface, or a fix loop whose
 > open items are all non-visual)>. Open Remediation items for YOUR surface (self-contained — fix
 > exactly these, reading only the files they name; `none` ⇒ first build, implement the spec's tasks
-> for your surface): <the surface's open `- [ ]` lines verbatim, or `none`>."
+> for your surface): <the surface's open `- [ ]` lines verbatim, or `none`>. Readiness gaps for YOUR
+> surface (§1.6 `RESERVATIONS` — the spec is silent here: implement the stated assumption and flag what
+> you assumed in your handoff): <that surface's `gaps` entries verbatim, or `none`>."
+
+## 3.5 Roll call — account for EVERY dispatch before integrating
+
+A subagent can die: a rate limit mid-run, a transport error after retries, its own context exhausted.
+When it does, it returns **nothing** — and nothing is byte-identical to "a clean surface with nothing
+to report". Silence is not a green light; treat it as the failure it is (SCHEMA.md §Dead agents).
+
+- **Roll call.** Every surface you dispatched in §3 must come back with a handoff in the format its
+  agent instructions define. Missing, empty, or truncated mid-sentence ⇒ that surface is **dead**.
+- **Never infer success from silence,** and never speak for a dead agent — you did not see its work.
+- **Retry that surface ONCE, alone.** Re-dispatch it with the byte-identical §3 prompt. The other
+  surfaces' work is already on disk and untouched, so this costs one agent, not a rebuild — and most
+  deaths are transient. Never retry a surface that *did* answer.
+- **Died twice ⇒ stop guessing and look.** Run that surface's own quiet commands
+  (`<surface>.typecheck_cmd`, `lint_quiet_cmd`, `test_quiet_cmd`) with output redirected to
+  `specs/reports/$ARGUMENTS.<key>.deadcheck.txt`, then grep it — never into your context. Report the
+  three results plus which of the spec's tasks for that surface actually landed, checked against the
+  tree, not against a handoff you never got. Say plainly that the surface is **unverified**.
 
 ## 4. Integrate
 
 When all return, flag any contract mismatch or failing test from the handoffs; otherwise print one
 status line per surface (`<key> · tests pass/fail · <n> TODOs`) — do not restate handoff content.
+A dead surface (§3.5) prints `<key> · DEAD — unverified` and **the batch is never reported as ok**.
 Append **ONE line for the batch** to the **main checkout's** `.claude/pipeline-metrics.jsonl` —
 NOT the worktree's, which dies at teardown while metrics must accumulate across features. Resolve
 it from anywhere: `$(dirname "$(git rev-parse --git-common-dir)")/.claude/pipeline-metrics.jsonl`
 (in the main checkout this resolves to itself). Create it if absent; it must be gitignored.
 Compute the elapsed time in the same Bash call
 (`echo "{...\"seconds\":$(($(date +%s)-<start epoch from §2>)),...}" >> …`):
-`{"ts":"<ISO date>","feature":"$ARGUMENTS","phase":"build","seconds":<wall-clock>,"surfaces":{"<key>":"ok|error",…}}`
+`{"ts":"<ISO date>","feature":"$ARGUMENTS","phase":"build","seconds":<wall-clock>,"surfaces":{"<key>":"ok|error|dead",…}}`
+— **write this line even when a surface died.** An incomplete batch is exactly the batch worth having
+in the record; skipping the append to "wait until it's complete" silently deletes the evidence that
+anything went wrong. In the same call write the machine-readable batch result to
+`specs/reports/$ARGUMENTS.build.json` (overwrite) — the channel an automated driver reads, since it
+never sees your chat:
+`{"id":"$ARGUMENTS","phase":"build","ts":"<ISO>","surfaces":{"<key>":"ok|error|dead",…},"dead":["<key>",…]}`
 — this is the evidence SCHEMA.md §Specialization asks for before splitting a surface. In the same
 Bash call, chain the opt-in usage ping — **the shared form every phase command reuses**:
 `<core>/pipeline/scripts/telemetry-send.sh <phase> "$ARGUMENTS" <seconds> "<results>" || true`
@@ -108,7 +191,9 @@ Bash call, chain the opt-in usage ping — **the shared form every phase command
 never ask about consent here. `/review` and `/fix` chain the same line with their own
 phase + results. The `|| true` swallows a **missing** script too, so a half-copied core goes
 silent rather than loud — `/doctor` check 1 is what catches that.
-Then tell the human: exercise the feature by hand if it's worth it, then run `/review $ARGUMENTS`.
+Then tell the human: exercise the feature by hand if it's worth it, then run `/review $ARGUMENTS` —
+unless a surface is dead, in which case say so first and let them decide whether to re-run `/build`
+(a dead surface has no findings, so `/fix` has nothing to re-dispatch).
 Do not run the app or migrations yourself here — building is not running.
 **Recommend a `/clear` now** — the spec, contract and diff are all on
 disk, and the lead's history is re-sent at input price on every turn it survives.

package/core/commands/doctor.md

@@ -84,9 +84,14 @@ fix only with the human's go-ahead (or hand them the command).
    End the check with ONE summary line, e.g.
    `workflows: available (opt-in — ask to "run the review workflow")` or
    `workflows: unavailable (<first failing prerequisite>) — conversational commands (the default)`.
-9. **Specs & metrics.** Every `specs/*.md` front-matter `status` is a valid stage — excluding
-   `_`-prefixed files and `specs/refactor-backlog.md`, which `/audit` writes as a backlog, not a
-   spec, and which has no front-matter to check; `shipped` specs
+9. **Specs & metrics.** Every `specs/*.md` front-matter `status` is a valid stage — one of
+   `draft · frozen · in-progress · in-review · shipped · blocked` (SCHEMA.md §Spec status; the last two
+   are written by the `/drive` driver, so flagging them would report the pipeline's own state as a
+   defect) — excluding
+   `_`-prefixed files (the spec template and `specs/_decisions.md`, the decision journal) and
+   `specs/refactor-backlog.md`, which `/audit` writes as a backlog, not a
+   spec, and which has no front-matter to check. A spec left `in-progress`/`blocked` with
+   `loop_pass` > 0 is a loop that never finished ⇒ say so and name `/drive <id> --resume`. `shipped` specs
    with a live worktree flagged (see 6). `.claude/pipeline-metrics.jsonl` and `specs/reports/` (the
    `/review` report buffer that lets a `/fix` survive a `/clear`) are gitignored. Metrics
    belong to the **main checkout** — a `pipeline-metrics.jsonl` inside a live feature worktree is a

package/core/commands/{loop.md → drive.md}

@@ -1,13 +1,19 @@
 ---
 model: sonnet
 description: Autonomous /build → /review → /fix → /review loop for one feature, until no blocking finding remains.
-argument-hint: <feature_id> [--max=N] [--no-build] [--rebuild]
+argument-hint: <feature_id> [--max=N] [--no-build] [--rebuild] [--resume]
 allowed-tools: Bash(bash ~/.claude/pipeline/scripts/loop.sh:*), Bash(bash .claude/pipeline/scripts/loop.sh:*), Bash(test:*), Read(specs/reports/**)
 disable-model-invocation: true
 ---
 
 You are the **launcher**, not the loop. Run the driver for **$ARGUMENTS** and relay three lines.
 
+> **This command was `/drive` until 1.6.0.** Claude Code ships its own built-in `/drive` (run a prompt on
+> a recurring interval), which **shadowed** this one: typing `/drive <id>` started the interval runner
+> with the feature id as its prompt, so the driver below never ran and the session reported a loop that
+> did not exist. The shipped script keeps its `loop.sh` name — nothing about a user's install path
+> changes, only what you type.
+>
 > This command exists because a slash command cannot `/clear` itself. Every phase of the loop runs
 > as a **separate `claude -p` child session** with its own fresh context, driven by a bash script —
 > so the diff, the N review reports and the N contracts never accumulate in YOUR history, which is
@@ -25,8 +31,15 @@ test -f .claude/pipeline/scripts/loop.sh \
 ```
 
 Pass `$ARGUMENTS` through untouched — the script owns its own flag parsing (`--max=N`,
-`--no-build`, `--rebuild`) and exits 64 on anything it doesn't know. Don't validate flags yourself,
-don't rewrite them, don't add any.
+`--no-build`, `--rebuild`, `--resume`) and exits 64 on anything it doesn't know. Don't validate flags
+yourself, don't rewrite them, don't add any.
+
+**Resume is the human's call, not yours.** The loop records its position in the spec's front-matter
+(`status: in-progress` · `loop_pass` · `loop_phase` — SCHEMA.md §Spec status), so a run killed by a
+dead session, a ceiling or a `blocked` exit can continue with `--resume` instead of re-paying the
+passes it already made. If the human types `/drive <id>` on a spec whose front-matter says
+`status: in-progress` or `blocked` with `loop_pass` > 1, say so in one line and ask whether to resume
+or restart — never silently add the flag, and never silently restart from pass 1.
 
 **Never read `specs/reports/<id>.loop.log`.** It holds the full transcript of every child session —
 the entire diff, every review report, every fix handoff. Pulling it into this session re-imports
@@ -38,7 +51,9 @@ open it in an editor for free. The same goes for the per-surface `.diff` and `.p
 
 The script prints one line per phase and one closing line; that is your raw material. For exit
 **1** or **3** only, also Read `specs/reports/<id>.verdict.json` (small, structured, safe) to name
-the remaining findings — never the markdown report, which is the findings body in full.
+the remaining findings — never the markdown report, which is the findings body in full. For exit
+**4**, Read `specs/reports/<id>.readiness.json` instead (also small) and relay its `gaps`. On any
+other exit the closing line already carries the deferred count, so read nothing.
 
 | exit | meaning | what to say |
 | ---- | ------- | ----------- |
@@ -46,14 +61,18 @@ the remaining findings — never the markdown report, which is the findings body
 | `1` | ceiling hit | the fix was progressing but ran out of passes ⇒ re-run with a higher `--max` |
 | `2` | no usable verdict | `/review` produced nothing, or aborted on a red preflight — the closing line says which; point at `specs/reports/<id>.preflight.txt` |
 | `3` | non-convergent | the same blocking findings survived a fix pass; a higher `--max` will NOT help — the human needs to look at them (list them from the verdict) |
+| `4` | not implementable | `/build`'s readiness gate returned `NOT-READY` — the frozen spec cannot be built and **no agent ran**; Read `specs/reports/<id>.readiness.json` (small, structured) and relay its `gaps`, then point at `/spec <id>`. More passes cannot fix this |
 | `64` | usage | relay the script's own message verbatim |
 
-Then print exactly three lines and nothing else:
+Then print exactly three lines and nothing else — plus a fourth **only when the verdict carries
+`deferred` > 0** (findings that were real but out of this feature's scope, parked in the backlog by
+`/review` §3.5; they are not blocking and never cost a pass, but they are not nothing either):
 
 ```
-outcome:    <one clause — clean / ceiling / no verdict / non-convergent / usage>
+outcome:    <one clause — clean / ceiling / no verdict / non-convergent / not implementable / usage>
 iterations: <n> review pass(es)<, m fix pass(es) committed>
 remaining:  <blocking count + one short phrase per blocking item, or "none">
+deferred:   <n> parked in specs/refactor-backlog.md — /refactor <domain> when you want them
 ```
 
 Add at most one follow-up sentence: the next command to run. Never restate a finding's fix, never

package/core/commands/fix.md

@@ -50,6 +50,11 @@ that change the *contract*; `/fix` is for everything else.
 
 When the agents return:
 
+- **Roll call first (SCHEMA.md §Dead agents).** A re-dispatched agent that returns nothing has fixed
+  nothing you can verify. Retry that surface ONCE with the byte-identical dispatch; still silent ⇒ leave
+  **every one of its items `- [ ]`** (a dead agent never ticks a box — that would hide an open finding
+  from the next round and from the driver), print `<key> · DEAD — items untouched`, and say the surface
+  is unverified.
 - **Tick the resolved items.** Each handoff's `## Remediation addressed` lists what that agent fixed
   (by `file:line`). For every Remediation item an agent reports fixed, flip its `- [ ]` → `- [x]` in
   `specs/<id>.md` and append a terse ` — fixed: <what/where>` note (the convention prior rounds already

package/core/commands/review.md

@@ -86,9 +86,25 @@ metrics line needs it.
 
 ## 3. Merge & relay the verdict
 
-Merge the returned reports into **one** REVIEW REPORT (same template): findings concatenated and
+**Roll call FIRST — a dead reviewer is not a clean surface.** Every surface you dispatched in §2 must
+come back with a REVIEW REPORT. A reviewer that died (rate limit, transport error, exhausted context)
+returns **nothing**, and zero findings from a dead reviewer is byte-identical to zero findings from a
+genuinely clean one — which is how "every reviewer crashed" reads as the strongest possible verdict
+from no evidence at all (SCHEMA.md §Dead agents). So:
+
+- **Retry a silent surface ONCE**, byte-identical dispatch. Most deaths are transient, and the staged
+  diff is already on disk — the retry costs one agent, not a re-review.
+- **Silent twice ⇒ that surface is `unreviewed`.** Name it in the report under
+  `## NOT reviewed (no verdict on these)`, list it in the verdict JSON's `unreviewed`, and **refuse to
+  score `SHIP`** — the merged verdict is at least `REVISE`. Absence of evidence is not evidence of
+  absence, and it must never reach `/ship` or tick a DoD box.
+- **Never re-review the other surfaces** to compensate: their reports are valid and already on disk.
+
+Then merge the returned reports into **one** REVIEW REPORT (same template): findings concatenated and
 re-ordered by severity, counts summed, duplicates collapsed, verdict = the worst returned
-(`BLOCK` > `REVISE` > `SHIP`). Append ONE metrics line for the batch to `pipeline-metrics.jsonl`
+(`BLOCK` > `REVISE` > `SHIP`). The `## Deferred` sections merge the same way (dedupe by
+`file` + problem) and stay **out of the severity table and out of the verdict** — see §3.5, which
+routes them. Append ONE metrics line for the batch to `pipeline-metrics.jsonl`
 (main-checkout path + rules in `/build` §4): `{"ts":"<ISO>","feature":"$ARGUMENTS","phase":"review","seconds":<wall-clock>,"surfaces":{"<key>":"<verdict>:<finding count>",…}}`.
 In the same Bash call, chain the opt-in usage ping (`/build` §4, `phase: "review"`, results = the
 merged verdict + total finding count, e.g. `"REVISE:3"`).
@@ -97,11 +113,11 @@ merged verdict + total finding count, e.g. `"REVISE:3"`).
 non-recursive `specs/*.md` glob, so it's never mistaken for a spec (no phantom card, no bogus stage).
 **Write the machine-readable verdict** to `specs/reports/$ARGUMENTS.verdict.json` (overwrite) — on
 **every** run, including the small-diff fast path of §2 and a `SHIP`. This file is the ONLY contract
-between the pipeline and an automated driver (`/loop`), which parses no prose:
+between the pipeline and an automated driver (`/drive`), which parses no prose:
 
 ```json
 { "id": "$ARGUMENTS", "phase": "review", "ts": "<ISO>", "verdict": "REVISE",
-  "findings": 7, "blocking": 2, "security": 1,
+  "findings": 7, "blocking": 2, "security": 1, "deferred": 3, "unreviewed": [],
   "severity": {"CRITICAL": 1, "HIGH": 2, "MEDIUM": 3, "LOW": 1},
   "surfaces": {"backend": {"verdict":"BLOCK","findings":4,"blocking":2}},
   "blocking_items": ["backend|apps/api/src/routes/order.ts|missing authz on post"],
@@ -121,12 +137,42 @@ between the pipeline and an automated driver (`/loop`), which parses no prose:
   `printf '%s\n' "<item>" … | LC_ALL=C sort | sha256sum | cut -c1-16` (`shasum -a 256` where there
   is no `sha256sum`). Empty list ⇒ `""`. A driver comparing two consecutive fingerprints detects a
   fix loop that is treading water.
+- **`deferred`** — the count of merged `## Deferred` items §3.5 parked in the backlog. Informational:
+  it never enters `blocking`, so it can never cost a driver an iteration.
+- **`unreviewed`** — the surface keys whose reviewer died twice, `[]` on a complete run. It is
+  **separate from `blocking` on purpose**: `blocking` counts real findings (CRITICAL + security), and
+  faking a number there to force a driver's hand would corrupt the one field the whole contract rests
+  on. A non-empty `unreviewed` means "this run does not cover everything" — a driver treats it as no
+  usable verdict, never as clean, whatever `blocking` says.
+
+## 3.5 Route the deferred findings — the backlog, not the fix loop
+
+Do this on **every** run, before the verdict branch below, and whatever the verdict — a deferred
+finding that is only routed on a `SHIP` is a deferred finding lost on every other verdict, which is
+exactly the leak this step closes. Append each merged `## Deferred` item to
+**`specs/refactor-backlog.md`**, under the `## <domain>` heading of the surface that owns its
+`file:line` (create the file and/or heading if absent — same grouping `/audit` writes, so
+`/refactor <domain>` picks them up with no extra plumbing):
+
+```
+- [ ] <SEVERITY> · <file:line> · <quality|security|rule> · <concrete fix> · deferred:$ARGUMENTS
+```
+
+- **Never into the spec's `## Remediation`** — that list is what `/fix` re-dispatches and what `/drive`
+  waits on, so a deferred item there would re-trigger the very loop it was deferred out of.
+- **Dedupe before appending:** `grep -F` the backlog for the item's `<file>` + the first words of its
+  problem; already there (from a prior round or an `/audit`) ⇒ skip it, don't stack duplicates round
+  after round.
+- Append with `>>` in ONE Bash call; never read the whole backlog into context to rewrite it (it grows
+  with every audit the repo has ever run).
+- Report it as **one line** in chat: `deferred: <n> parked in specs/refactor-backlog.md (<domains>)`.
 
 In chat print ONLY: the verdict, the severity-count table, a one-line digest of each CRITICAL/security
 finding, and `Full report: specs/reports/$ARGUMENTS.md` — never echo the findings body into chat (it
 would sit in this session's history, re-sent every turn). Then:
 
-- **SHIP** → a SHIP verdict *is* the pipeline's statement that the feature meets its Definition of
+- **SHIP** → only reachable with `unreviewed` empty (the roll call above forbids it otherwise). A SHIP
+  verdict *is* the pipeline's statement that the feature meets its Definition of
   Done, so **tick the DoD**: in `specs/$ARGUMENTS.md` §`Acceptance criteria / DoD`, flip each `- [ ]`
   → `- [x]` for the criteria the pipeline has actually verified — spec conformance + `ui_language`
   copy (this review), tests · lint · typecheck (a green `/build`), mobile-first as far as the code
@@ -141,12 +187,15 @@ would sit in this session's history, re-sent every turn). Then:
   of exactly the source you just reviewed (specs excluded, so DoD ticks + the ship status flip don't
   trip it). Then tell the human they can `/ship` — **recommend a `/clear` first**, the handoff is
   fully on disk. **SHIP with leftover LOW findings** (or LOW+MEDIUM at the human's call) does NOT
-  force a fix cycle for nits: park them in `specs/refactor-backlog.md` tagged `deferred:<id>` (NOT as
-  open `## Remediation` items, which would re-trigger the fix loop), keep the SHIP verdict and the
-  freshness stamp, and let the human ship.
+  force a fix cycle for nits: park them through §3.5's exact route (the backlog, under their surface's
+  domain heading, tagged `deferred:$ARGUMENTS` — never as open `## Remediation` items, which would
+  re-trigger the fix loop), keep the SHIP verdict and the freshness stamp, and let the human ship.
 - **REVISE / BLOCK**, or any CRITICAL/HIGH/security finding → tell the human to run
   **`/fix $ARGUMENTS`** — it appends the report to the spec's `## Remediation` and re-dispatches ONLY
-  the surfaces with findings. The full path (`/spec` Mode B then `/build`) remains for findings that
+  the surfaces with findings. (If they'd rather automate the rounds, the autonomous driver is
+  `disable-model-invocation: true` on purpose: **you cannot start it, they must type it**. Name the
+  exact line for them to type rather than attempting it — an attempt that silently fails reads as a
+  loop that is running when nothing is.) The full path (`/spec` Mode B then `/build`) remains for findings that
   change the contract in ways that ripple into clean surfaces. _The report is staged to
   `specs/reports/$ARGUMENTS.md`, so you can `/clear` before `/fix` — it reads the findings back from
   disk._