cohorte 1.4.0 → 1.6.0

package/dashboard/server/doctor.js

@@ -12,11 +12,17 @@ const { versions } = require('./versions');
 // Rendered surface agents live alongside these fixed (non-surface) agents; exclude them
 // from the orphan check so they're never mistaken for a stray surface agent.
 const FIXED_AGENTS = new Set([
-  'review', 'release', 'smoke', 'profile-reader',
+  'review', 'release', 'profile-reader',
+  // retired (1.5.0) — still excluded so a stale install's leftover file isn't
+  // reported as a stray surface agent.
+  'smoke',
   '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
@@ -126,7 +132,7 @@ function checkGate(profile, projectRoot) {
   const wantPf = gate.preflight || {};
   const havePf = (cfg.preflight && typeof cfg.preflight === 'object') ? cfg.preflight : {};
   if (!!wantPf.enabled !== !!havePf.enabled
-      || !sameSet(wantPf.agents || ['review', 'smoke'], havePf.agents || ['review', 'smoke'])
+      || !sameSet(wantPf.agents || ['review'], havePf.agents || ['review'])
       || Number(wantPf.max_age_minutes || 30) !== Number(havePf.max_age_minutes || 30)) {
     drifted.push('preflight');
   }
@@ -278,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/dashboard/server/index.js

@@ -11,6 +11,7 @@ const { versions } = require('./versions');
 const { state } = require('./doctor');
 const { kanban } = require('./kanban');
 const { metrics } = require('./metrics');
+const { usage } = require('./usage');
 const fleet = require('./fleet');
 
 const MIME = {
@@ -321,6 +322,12 @@ function start({ projectRoot, globalDir, port, host, openBrowser, pkgRoot, versi
         const root = q ? path.resolve(q) : projectRoot;
         return sendJson(res, 200, metrics({ projectRoot: root }));
       }
+      if (url === '/api/usage') {
+        const q = new URL(req.url, 'http://localhost');
+        const root = q.searchParams.get('project') ? path.resolve(q.searchParams.get('project')) : projectRoot;
+        const days = Number(q.searchParams.get('days')) || null;
+        return sendJson(res, 200, usage({ projectRoot: root, days }));
+      }
       if (url === '/api/projects') {
         const body = await readBody(req);
         if (req.method === 'POST') {

package/dashboard/server/metrics.js

@@ -1,6 +1,6 @@
 'use strict';
 // Read a project's `.claude/pipeline-metrics.jsonl` (one line per phase batch, appended by
-// /build, /review, /fix and /smoke) and aggregate it per feature: wall-clock per phase, fix
+// /build, /review and /fix) and aggregate it per feature: wall-clock per phase, fix
 // rounds, and per-surface results. Dependency-free; a missing file is simply "no data yet".
 //
 // Two line formats coexist in the file:
@@ -11,9 +11,9 @@
 const fs = require('fs');
 const path = require('path');
 
-// `cycle` is a RETIRED phase, kept so metrics files written before its removal still render.
-// Without it in this list its per-surface results parse fine but land in no column — the
-// surface table showed rows with every cell empty.
+// `smoke` and `cycle` are RETIRED phases, kept so metrics files written before their removal
+// still render. Without them in this list their per-surface results parse fine but land in no
+// column — the surface table showed rows with every cell empty.
 const PHASES = ['build', 'review', 'fix', 'smoke', 'cycle'];
 
 // Parse the raw JSONL into normalized batches ({ts, feature, phase, seconds, surfaces}),

package/dashboard/server/usage.js

@@ -0,0 +1,61 @@
+'use strict';
+// Serve the metrics collector's rollup (scripts/metrics/collect.mjs) to the dashboard:
+// real cost and runtime per command, read from Claude Code's own transcripts.
+//
+// This is the SECOND metrics source in the cockpit, and the two answer different questions.
+// `metrics.js` reads `.claude/pipeline-metrics.jsonl` — written by the model itself, so it
+// carries per-surface verdicts (ok / REVISE:2 / error) that only the model knows, but it
+// misses any run that ended early and can never report tokens. This one is derived from the
+// transcripts, so it is complete and exact on cost and time but knows nothing about verdicts.
+// Verdicts from one, money from the other; neither is a replacement for the other.
+//
+// The collector is ESM and this server is CommonJS, so it runs as a child process — the same
+// bridge `bin/cli.js` uses. A spawn is ~1-2s on a large history, which is why the result is
+// cached: the panel polls, and re-parsing tens of MB of transcripts on every poll would make
+// the whole cockpit feel broken.
+
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const COLLECT = path.join(__dirname, '..', '..', 'scripts', 'metrics', 'collect.mjs');
+
+// Transcripts only grow, and nobody needs sub-minute freshness on a spend figure.
+const CACHE_MS = 60_000;
+const cache = new Map(); // projectRoot → { at, value }
+
+function usage({ projectRoot, days = null, force = false }) {
+  const key = `${projectRoot}|${days || ''}`;
+  const hit = cache.get(key);
+  if (!force && hit && Date.now() - hit.at < CACHE_MS) return hit.value;
+
+  const args = [COLLECT, projectRoot, '--json'];
+  if (days) args.push(`--days=${days}`);
+
+  let value;
+  try {
+    const r = spawnSync(process.execPath, args, {
+      encoding: 'utf8',
+      // A pathological history must not wedge the cockpit's event loop forever.
+      timeout: 60_000,
+      maxBuffer: 64 * 1024 * 1024,
+    });
+    if (r.status !== 0 || !r.stdout) {
+      value = { present: false, error: (r.stderr || '').trim().split('\n').slice(-1)[0] || 'collector failed' };
+    } else {
+      const parsed = JSON.parse(r.stdout);
+      // No transcripts for this project is a normal state (a fresh checkout, or a project
+      // driven from another machine), not an error — say so rather than rendering zeros
+      // that look like "this pipeline is free".
+      value = parsed.totals && parsed.totals.sessions
+        ? { present: true, ...parsed }
+        : { present: false, error: 'no Claude Code transcripts found for this project' };
+    }
+  } catch (e) {
+    value = { present: false, error: String((e && e.message) || e) };
+  }
+
+  cache.set(key, { at: Date.now(), value });
+  return value;
+}
+
+module.exports = { usage };

package/install.ps1

@@ -151,6 +151,7 @@ try {
         Copy-Item (Join-Path $src 'scripts\kanban-move.sh')       (Join-Path $dest 'pipeline\scripts') -Force
         Copy-Item (Join-Path $src 'scripts\telemetry-send.sh')    (Join-Path $dest 'pipeline\scripts') -Force
         Copy-Item (Join-Path $src 'scripts\preflight.sh')         (Join-Path $dest 'pipeline\scripts') -Force
+        Copy-Item (Join-Path $src 'scripts\loop.sh')              (Join-Path $dest 'pipeline\scripts') -Force
         Copy-Item (Join-Path $src 'core\agents\implementer.template.md') (Join-Path $dest 'pipeline') -Force
         if (Test-Path (Join-Path $src 'CHANGELOG.md')) { Copy-Item (Join-Path $src 'CHANGELOG.md') (Join-Path $dest 'pipeline') -Force }
         [System.IO.File]::WriteAllText((Join-Path $dest 'pipeline\VERSION'), "$ver`n", [System.Text.UTF8Encoding]::new($false))
@@ -188,8 +189,18 @@ try {
         New-Item -ItemType Directory -Force -Path (Join-Path $dest 'agents') | Out-Null
         Copy-Item (Join-Path $src 'core\agents\review.md'),
                   (Join-Path $src 'core\agents\release.md'),
-                  (Join-Path $src 'core\agents\smoke.md'),
                   (Join-Path $src 'core\agents\profile-reader.md') (Join-Path $dest 'agents') -Force
+        # 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

@@ -107,8 +107,9 @@ copy_core() {
   cp "$src/scripts/kanban-move.sh"       "$dest/pipeline/scripts/"
   cp "$src/scripts/telemetry-send.sh"    "$dest/pipeline/scripts/"
   cp "$src/scripts/preflight.sh"         "$dest/pipeline/scripts/"
+  cp "$src/scripts/loop.sh"              "$dest/pipeline/scripts/"
   chmod +x "$dest/pipeline/scripts/kanban-move.sh" "$dest/pipeline/scripts/telemetry-send.sh" \
-           "$dest/pipeline/scripts/preflight.sh" 2>/dev/null || true
+           "$dest/pipeline/scripts/preflight.sh" "$dest/pipeline/scripts/loop.sh" 2>/dev/null || true
   cp "$src/core/agents/implementer.template.md" "$dest/pipeline/"
   [ -f "$src/CHANGELOG.md" ] && cp "$src/CHANGELOG.md" "$dest/pipeline/"
   printf '%s\n' "$ver" > "$dest/pipeline/VERSION"
@@ -149,8 +150,17 @@ PY
 copy_fixed_agents() {
   mkdir -p "$dest/agents"
   cp "$src/core/agents/review.md" "$src/core/agents/release.md" \
-     "$src/core/agents/smoke.md" "$src/core/agents/profile-reader.md" \
+     "$src/core/agents/profile-reader.md" \
      "$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.4.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/PIPELINE.template.md

@@ -106,7 +106,7 @@ commands:
   format: pnpm format
   typecheck: pnpm check-types
   test: pnpm test
-  test_quiet: pnpm test --reporter=dot       # bridled variant — what /review·/smoke preflight runs
+  test_quiet: pnpm test --reporter=dot       # bridled variant — what the /review preflight runs
   # migration commands — omit / leave "" if the project has no DB migrations
   migrate: "cd apps/api && node ace migration:run"
   make_migration: "cd apps/api && node ace make:migration"
@@ -164,12 +164,12 @@ gate:
     - "git rebase"
     - "git reset"
     - "docker compose"
-  # Phase gate: review/smoke dispatches require a fresh `.claude/preflight.ok` stamp,
+  # Phase gate: review dispatches require a fresh `.claude/preflight.ok` stamp,
   # written by pipeline/scripts/preflight.sh when typecheck+lint+tests are green —
   # gate.py "ask"s the dispatch when the stamp is missing, stale, or HEAD moved.
   preflight:
     enabled: true
-    agents: [review, smoke]                   # subagent_types the stamp gates
+    agents: [review]                          # subagent_types the stamp gates
     max_age_minutes: 30
 
 ```

package/profile/SCHEMA.md

@@ -34,7 +34,7 @@ generic pipeline uses it, so a stateless agent can read/regenerate the profile c
 | `contract.path` `.ext` `.index`      | string       | build                             | Where `<feature_id>` contract is authored + barrel.           |
 | `contract.authored_by`               | const `lead` | build                             | Implementers import it read-only, never edit.                 |
 | `commands.*`                         | string       | all                               | Repo-wide install/dev/lint/format/typecheck/test + migrate.   |
-| `commands.test_quiet` `.lint_quiet`  | string       | review, smoke, audit, workflows   | Repo-wide bridled variants — what the `/review`·`/smoke` pre-flight runs. Same fallback as the per-surface ones. |
+| `commands.test_quiet` `.lint_quiet`  | string       | review, audit, workflows          | Repo-wide bridled variants — what the `/review` pre-flight runs. Same fallback as the per-surface ones. |
 | `rbac.enabled`                       | bool         | brainstorm, review                | Toggle RBAC personas + authz audit.                           |
 | `rbac.hierarchy`                     | list         | review                            | Highest→lowest role list.                                     |
 | `design.enabled`                     | bool         | build, frontend, align-ds         | `false` ⇒ design steps are no-ops.                            |
@@ -52,8 +52,8 @@ generic pipeline uses it, so a stateless agent can read/regenerate the profile c
 | `gate.ask[]`                         | list         | hooks/gate.py, settings           | Command substrings that require confirm, on any branch.       |
 | `gate.ask_on_default_branch[]`       | list         | hooks/gate.py                     | Confirm ONLY on `default_branch`; free on feature branches.   |
 | `gate.default_branch`                | string       | hooks/gate.py                     | Protected branch (default `main`); gate resolves via git.     |
-| `gate.preflight.enabled`             | bool         | hooks/gate.py, review, smoke      | Phase gate: review/smoke dispatches need a fresh preflight stamp. See §Preflight. |
-| `gate.preflight.agents[]`            | list         | hooks/gate.py                     | `subagent_type`s the stamp gates (default `[review, smoke]`). |
+| `gate.preflight.enabled`             | bool         | hooks/gate.py, review             | Phase gate: review dispatches need a fresh preflight stamp. See §Preflight. |
+| `gate.preflight.agents[]`            | list         | hooks/gate.py                     | `subagent_type`s the stamp gates (default `[review]`).        |
 | `gate.preflight.max_age_minutes`     | number       | hooks/gate.py                     | Stamp freshness window (default 30).                          |
 
 ## Prose sections
@@ -161,8 +161,8 @@ the frozen contract as the only cross-surface channel**. So specialization means
 Coarse first, specialize on evidence: start with one `frontend` / `backend` surface each; split only a
 surface that's proven slow and cleanly separable. The evidence lives in
 the **main checkout's** `.claude/pipeline-metrics.jsonl` (gitignored) — one JSONL line per phase batch
-(`ts`/`feature`/`phase`/`seconds`/`surfaces:{key: result}`), appended by `/build`, `/review`, `/fix`
-and `/smoke`.
+(`ts`/`feature`/`phase`/`seconds`/`surfaces:{key: result}`), appended by `/build`, `/review`
+and `/fix`.
 **`surfaces` keys are surface keys, nothing else** — run-level facts go in their own top-level
 fields. Anything put inside `surfaces` is read
 as a surface: the dashboard renders it as a row in the per-surface table and scores a non-`ok`
@@ -188,7 +188,7 @@ to log it. For what's EXPENSIVE, use Claude Code's own accounting:
   per-subagent attribution needs traces (`CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`, beta).
 
 **Lead context discipline — the silent bill.** The lead session's conversation history is re-sent as
-input on EVERY turn; a session that spans spec→build→smoke→review→fix without clearing re-pays the
+input on EVERY turn; a session that spans spec→build→review→fix without clearing re-pays the
 accumulated spec walk-through, handoffs, and reports on each turn. The pipeline is built so this is
 never necessary: every phase handoff (spec, contract, diff, staged reports) lives on disk, so `/clear`
 at each phase boundary is always safe — each command's closing line recommends it. Corollaries the
@@ -217,9 +217,132 @@ 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` and `/smoke` start by running `pipeline/scripts/preflight.sh` — a plain shell script (no
+`/review` starts by running `pipeline/scripts/preflight.sh` — a plain shell script (no
 agent) that executes the profile's mechanical checks in order (typecheck → lint → tests, quiet
 variants) with all output redirected to `specs/reports/<id>.preflight.txt`:
 
@@ -231,7 +354,7 @@ variants) with all output redirected to `specs/reports/<id>.preflight.txt`:
 
 `hooks/gate.py` enforces the stamp as a **phase gate** (the `preflight` block of `gate-config.json`,
 generated from `gate.preflight`): a Task dispatch of a listed `subagent_type` (default
-`review`/`smoke`) with a missing/stale stamp — older than `max_age_minutes`, or HEAD moved — gets an
+`review`) with a missing/stale stamp — older than `max_age_minutes`, or HEAD moved — gets an
 "ask", so a lead can't accidentally skip the gate but a human can consciously override it. The gate
 hook fires for **every** agent in the session, including subagents spawned by the Workflow runtime
 (they run in `acceptEdits` whatever the session mode — Write/Edit auto-approved — but Bash and Task
@@ -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.
@@ -409,14 +544,18 @@ card created in the target column if missing.
 | `/spec` opens (draft)                   | `spec`          |
 | `/spec` freezes (`status: frozen`)      | `ready`         |
 | `/build`                                | `building`      |
-| `/review` (owns the move — `/smoke` never moves the card) | `review`        |
+| `/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.
@@ -437,7 +576,7 @@ pre-telemetry installs) ask ONE question, once per machine, default **No**, and
 `|| true`, so a **missing** script is equally silent: `/doctor` check 1 verifies `pipeline/scripts/`
 is fully populated.
 
-**Which commands ping** — the seven that make up the feature funnel, and only those. The point is to
+**Which commands ping** — the six that make up the feature funnel, and only those. The point is to
 see where features stall, so every stage of `idea → PR` reports and nothing else does:
 
 | phase | fired when | `seconds` | `results` |
@@ -445,7 +584,6 @@ see where features stall, so every stage of `idea → PR` reports and nothing el
 | `brainstorm` | the return is staged | `0` | — |
 | `spec` | a freeze lands (Mode A only) | `0` | `frozen` |
 | `build` | after the batch metrics line | wall-clock | `ok,ok` / `error` |
-| `smoke` | after the verdict | wall-clock | `PASS` / `FAIL:<n>` |
 | `review` | after the merged verdict | wall-clock | `<verdict>:<count>` |
 | `fix` | after the batch metrics line | wall-clock | `<fixed>/<found>` |
 | `ship` | the release agent succeeded | `0` | `pr` / `compare` |