cohorte 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -3,6 +3,157 @@
 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.** _(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
+  passes won't help. `--no-build` re-runs the loop on an already-built feature; `--rebuild` forces
+  a build. Every fix pass is committed (`loop(<id>): fix pass <i>`) — 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. Exit codes distinguish clean · ceiling · no verdict · non-convergent ·
+  usage, so a wrapper can tell "needs more passes" from "needs a human".
+- **The loop does not run in your session — that's the whole design.** Each phase is a separate
+  `claude -p` child with its own fresh context, driven by the new shipped `loop.sh`; all child
+  output goes to `specs/reports/<id>.loop.log`, which the command is forbidden to read back. Your
+  session sees one line per phase and a three-line summary. A slash command cannot `/clear` itself,
+  so a conversational loop would pile the diff plus N review reports plus N contracts into a
+  history re-sent at input price every turn — it would cost more than the loop saves.
+  `disable-model-invocation: true`: an autonomous loop only ever starts because you asked.
+- **`/review` now writes a machine-readable verdict** to `specs/reports/<id>.verdict.json` on every
+  run — verdict, finding counts by severity, per-surface breakdown, the normalized blocking items
+  and a stable `fingerprint` over them. It is the only contract between the pipeline and any
+  driver; no prose is parsed. `blocking` restates the reviewer's existing rule as a number
+  (CRITICAL + security, deduplicated), so `blocking == 0` ⟺ `SHIP`. The fingerprint hashes
+  *surface + file + problem* with the line number deliberately dropped — a fix that inserts lines
+  would otherwise change it every pass and the drift detection would never fire. A red preflight
+  writes a degraded `{"aborted":"preflight"}` verdict rather than nothing, so an abort is a
+  diagnosis instead of a silence.
+- **BREAKING — `/smoke` and the `smoke` agent are removed.** The end-to-end run phase is gone:
+  the command, the agent, its preflight wiring, its telemetry phase and its documentation. The
+  loop is now `/brainstorm` → `/spec` → `/build` → `/review` → (`/fix` → `/review`)* → `/ship`,
+  with `/clear` safe between each. Nothing else depended on it; a `/smoke` in an old habit will
+  report an unknown command.
+- **Nothing in the pipeline runs your app any more — that part is yours.** `/build` now closes by
+  telling you to exercise the feature by hand if it's worth it, and `/fix` says the same for
+  runtime failures. `/review` follows suit at the SHIP verdict: it ticks only what a stage
+  actually verified, and **leaves any DoD criterion that needs the app up open** (runtime flows,
+  a visual check against the design) unless you say you exercised it yourself and it held.
+- **The preflight phase gate now gates `review` alone** (`gate.preflight.agents` defaults to
+  `[review]`). Existing profiles that list `smoke` keep working — the hook just never sees that
+  dispatch. `/doctor` compares against the new default, so re-run it after the update if it
+  flags gate drift.
+- **Retired-phase data still renders.** Metrics files and dashboards carrying `phase: "smoke"`
+  keep their column, the transcript collector keeps attributing past `/smoke` runs to `/smoke`
+  instead of silently reclassifying them, and `telemetry-send.sh` still accepts the phase from a
+  stale install. Same treatment `/cycle` got in 1.4.0.
+- **The cockpit now shows what a feature actually cost.** The dashboard's only metrics source
+  was `pipeline-metrics.jsonl`, written by the model itself — so it misses any run that ended
+  early and can never report tokens. On a real project it had captured 18 phase batches where
+  the transcripts hold 53 runs. The new **Cost & runtime** panel reads
+  `cohorte metrics` instead: per command, the number of runs, $ per run, $ total, tokens, wall
+  and active time, and the median number of subagents dispatched. That last column is the one
+  that makes a broken run obvious — a `/build` reporting 0 agents did no fan-out at all.
+- **Both metrics sources are kept, because they answer different questions.** `pipeline-metrics.jsonl`
+  carries per-surface verdicts (`ok`, `REVISE:2`, `error`) that only the model knows and the
+  transcripts never contain; the collector carries money and time, which the model cannot report
+  and the transcripts record exactly. The two panels sit side by side and each says what it is
+  for. Neither replaces the other.
+- **Fixed: discussing a command counted as running it.** An inline command mention was treated
+  as an invocation regardless of context, so a long message *about* `/review` billed that whole
+  conversation to `/review` — in cohorte's own repo it invented five `/cycle` runs out of a
+  design discussion. Inline mentions are now length-gated (an instruction is short; a discussion
+  is not); an explicit slash-command invocation is always counted.
+
 ## 1.4.0 — 2026-08-01
 
 > **Re-run `npx cohorte@latest update --global` (or `update`)** — the workflow fixes only apply

package/README.md

@@ -20,7 +20,7 @@ then one command per project (`/init-pipeline`) adapts it to that project's stac
   **stateless agents** that only communicate through a frozen contract:
 
   ```
-  /brainstorm → /spec → (design) → /build <id> → /smoke → /review → (/fix) → /ship
+  /brainstorm → /spec → (design) → /build <id> → /review → (/fix) → /ship
   ```
 
 ## How it works — three layers
@@ -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.   |
-| `/smoke <id>`        | Run the feature for real: infra up, contract endpoints, UI flows, design conformance. |
-| `/review <id>`       | Read-only review agents (one per touched surface, parallel) audit the diff vs the spec. |
-| `/fix <id>`          | Apply a review/smoke report: remediation into the spec, re-dispatch only the surfaces with findings. |
+| `/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. |
+| `/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.                                         |
@@ -230,12 +231,12 @@ it in `.claude/pipeline/VERSION` and bundled repos in their committed `pipeline.
 ### Run the loop cheaply — `/clear` between stages
 
 Every command reloads all the state it needs **from disk** — the frozen spec, the contract, the diff, the
-Remediation checkboxes, the freshness stamp, and the last `/review`·`/smoke` report (staged to a gitignored
+Remediation checkboxes, the freshness stamp, and the last `/review` report (staged to a gitignored
 `specs/reports/<id>.md`). Nothing essential lives in the conversation. So the loop is **`/clear`-safe at
 every boundary**:
 
 ```
-/spec → /clear → /build → /clear → /smoke → /clear → /review → /clear → /fix → /clear → /review → /ship
+/spec → /clear → /build → /clear → /review → /clear → /fix → /clear → /review → /ship
 ```
 
 `/clear`-ing between stages sheds the accumulated main-thread context, which is the single biggest token
@@ -243,6 +244,36 @@ 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 — `/drive`
+
+```
+/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, 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
+`specs/reports/<id>.loop.log`, which the command is forbidden to read back. Your session sees one
+line per phase and a three-line summary. That's the whole design: a slash command can't `/clear`
+itself, so a conversational loop would pile the diff plus N review reports plus N contracts into a
+history that is re-sent at input price every turn — it would cost more than the loop saves. The
+machine contract is `specs/reports/<id>.verdict.json`, which `/review` now writes on every run; no
+prose is ever parsed.
+
 ### Run features in parallel — one session per feature
 
 With `isolation.enabled`, every feature already gets its own worktree, ports, and database
@@ -256,8 +287,8 @@ The pattern:
 ```
 session 1 (main checkout):   /spec feat-a → /build feat-a  (agents run…)
 session 2 (main checkout):   /spec feat-b → /build feat-b  (agents run…)
-session 1:                   /smoke feat-a → /review feat-a → /ship feat-a
-session 2:                   /smoke feat-b → …
+session 1:                   /review feat-a → /ship feat-a
+session 2:                   /review feat-b → …
 ```
 
 Rules that make it safe:
@@ -266,7 +297,7 @@ Rules that make it safe:
   (`specs/<id>.md`, `<contract.path>/<id>.*`, `specs/reports/<id>*`), so sessions never share state —
   but a single session interleaving two features accumulates both in its context, paying for both.
 - **Disjoint surfaces per feature are guaranteed** (each worktree is a full checkout), and each
-  feature's DB/ports come from its slot — `/smoke` runs collide on neither.
+  feature's DB/ports come from its slot — two features' dev servers collide on neither.
 - **The contract package is the one shared tree.** Two features editing
   `<contract.path>/<their-own-id>.<ext>` never conflict (one file per feature); merge order only
   matters if a later feature *imports* an earlier one's contract — ship the dependency first.
@@ -331,7 +362,7 @@ bin/cli.js              # the npm CLI: install / update / dashboard / version (c
 install.sh              # script installer (fresh + --update) for no-Node environments
 install.ps1             # same installer for Windows PowerShell (fresh + -Update)
 core/                   # copied verbatim into ~/.claude (global) or <project>/.claude (bundled)
-  agents/               # implementer.template.md (rendered per surface) + review / release / smoke / profile-reader
+  agents/               # implementer.template.md (rendered per surface) + review / release / profile-reader
   commands/             # init-pipeline + the pipeline commands + /update-pipeline
   hooks/                # gate.py (destructive-command gate; branch-aware; preflight phase gate)
   templates/            # handoff / brainstorm-return / design-brief / review-feedback / pr-body / spec

package/bin/cli.js

@@ -213,8 +213,8 @@ function copyFixedAgents() {
   fs.mkdirSync(path.join(dest, 'agents'), { recursive: true });
   // Every agent in core/agents/ EXCEPT the *.template.md ones, which /init-pipeline renders
   // per-surface. Until 1.2.6 this was a hardcoded ['review.md', 'release.md'] that never grew
-  // the `smoke.md` the shell installers copy, so `npx cohorte install` shipped the /smoke
-  // command with no `smoke` agent to dispatch — the run reported /smoke as not installed.
+  // the agents the shell installers copy, so `npx cohorte install` shipped a command with no
+  // agent to dispatch — the run reported the command as not installed.
   // Reading the directory needs no list to keep in sync with the shell installers.
   const agentDir = path.join(src, 'core', 'agents');
   for (const f of fs.readdirSync(agentDir)) {
@@ -224,6 +224,17 @@ function copyFixedAgents() {
   // 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.
   fs.rmSync(path.join(dest, 'agents', 'questionnaire-researcher.md'), { force: true });
+  // 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,28 +143,57 @@ 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`
 (`<core>` = `~/.claude` global / `.claude` bundled; here `<phase>` = `build`, `<results>` =
 `<ok,ok|error,…>`) — a silent no-op unless the human explicitly consented (SCHEMA.md §Telemetry);
-never ask about consent here. `/review`, `/fix` and `/smoke` chain the same line with their own
+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: run `/smoke $ARGUMENTS` to exercise the feature end-to-end (or test by hand),
-then `/review $ARGUMENTS`. Do not run the app or migrations yourself here — `/smoke` is the
-sanctioned path for that. **Recommend a `/clear` now** — the spec, contract and diff are all on
+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

@@ -21,7 +21,7 @@ fix only with the human's go-ahead (or hand them the command).
    commands' step files are present — `templates/steps/init-pipeline/` non-empty (a router whose
    `templates/steps/<cmd>/` dir is missing is a partial/stale install ⇒
    re-run install/update). **Shipped scripts present and executable** in `<core>/pipeline/scripts/`:
-   `kanban-move.sh`, `telemetry-send.sh`, `preflight.sh`, `new-feature.sh.template`,
+   `kanban-move.sh`, `telemetry-send.sh`, `preflight.sh`, `loop.sh`, `new-feature.sh.template`,
    `remove-feature.sh.template` — ❌ any missing one. Every caller chains these with `|| true`, so an absent script is a **silent**
    no-op (no kanban card moves, no telemetry ping, no error anywhere) — this check is the only thing
    that sees it. Also flag ❌ a `VERSION` **newer than** the other `pipeline/` files (compare mtimes):
@@ -34,9 +34,9 @@ fix only with the human's go-ahead (or hand them the command).
    its `surfaces[].model` — ❌ if missing, mismatched, or a literal `<SURFACE_MODEL>` placeholder
    (all three silently fall back to inheriting the lead session's model — often Opus — on every
    dispatch); ⚠️ any `inherit` with the note that it bills at the lead's tier. The generic agents
-   (`review.md`, `release.md`, `smoke.md`, `profile-reader.md` — repo or `~/.claude/agents/`) must
-   each carry their `model:` line too (sonnet/haiku/sonnet/haiku). **Command pins:** every mechanical command file
-   (`build`, `review`, `fix`, `smoke`, `ship`, `audit`, `refactor`, `doctor`, `align-ds`,
+   (`review.md`, `release.md`, `profile-reader.md` — repo or `~/.claude/agents/`) must
+   each carry their `model:` line too (sonnet/haiku/haiku). **Command pins:** every mechanical command file
+   (`build`, `review`, `fix`, `loop`, `ship`, `audit`, `refactor`, `doctor`, `align-ds`,
    `update-pipeline` — in `.claude/commands/` or `~/.claude/commands/`) carries `model: sonnet` in
    its frontmatter — ⚠️ if missing (the lead's orchestration turn then bills at the session model,
    e.g. Opus/Fable). `brainstorm`, `spec`, and `init-pipeline` are intentionally unpinned
@@ -84,11 +84,16 @@ 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`·`/smoke` report buffer that lets a `/fix` survive a `/clear`) are gitignored. Metrics
+   `/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
    stale-core sign (its lines die at teardown) ⇒ suggest appending its lines to the main checkout's
    file and deleting the stray.