cohorte 1.4.0 → 1.6.0

package/core/commands/drive.md

@@ -0,0 +1,80 @@
+---
+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] [--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
+> re-sent at input price on every turn. Running the loop conversationally here would cost more than
+> the loop saves.
+
+## 1. Launch
+
+Probe the core, then run the script — ONE Bash call, and let it run to completion:
+
+```
+test -f .claude/pipeline/scripts/loop.sh \
+  && bash .claude/pipeline/scripts/loop.sh $ARGUMENTS \
+  || bash ~/.claude/pipeline/scripts/loop.sh $ARGUMENTS
+```
+
+Pass `$ARGUMENTS` through untouched — the script owns its own flag parsing (`--max=N`,
+`--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
+exactly the context the loop was built to keep out, and it is the one mistake that turns this
+command into the most expensive one in the pipeline. Point the human at the path instead; they can
+open it in an editor for free. The same goes for the per-surface `.diff` and `.preflight.txt` files.
+
+## 2. Report — three lines, from the exit code
+
+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. 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 |
+| ---- | ------- | ----------- |
+| `0` | clean | no blocking findings left; the human can `/ship <id>` |
+| `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 — 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 / 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
+summarize the log, never open the diff. Each fix pass is already committed
+(`loop(<id>): fix pass <i>`) — say so on a non-zero exit, since those commits are the way back.

package/core/commands/fix.md

@@ -1,6 +1,6 @@
 ---
 model: sonnet
-description: Apply a REVIEW REPORT (or SMOKE failures) — append it to the spec's Remediation, then re-dispatch ONLY the surfaces that have findings.
+description: Apply a REVIEW REPORT — append it to the spec's Remediation, then re-dispatch ONLY the surfaces that have findings.
 argument-hint: <feature_id> [paste REVIEW REPORT]
 ---
 
@@ -16,9 +16,9 @@ that change the *contract*; `/fix` is for everything else.
 
 ## 1. Ingest the report
 
-- The report is either pasted after the feature id, the REVIEW REPORT / SMOKE failures from this
-  session's last `/review` / `/smoke`, or — if the context was cleared — read from
-  `specs/reports/<id>.md`, where `/review` and `/smoke` stage their last report for exactly this reason.
+- The report is either pasted after the feature id (a REVIEW REPORT, or failures the human hit by
+  hand), this session's last `/review` REVIEW REPORT, or — if the context was cleared — read from
+  `specs/reports/<id>.md`, where `/review` stages its last report for exactly this reason.
   If you have none of these, ask for it and wait.
 - Append each finding to `specs/<id>.md` **`## Remediation`** (same format as `/spec` Mode B, under a
   dated/numbered subheading): `- [ ] <severity> · <file:line> · <type> · <concrete fix>`. Set
@@ -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
@@ -65,7 +70,7 @@ When the agents return:
   handoff content — and append ONE metrics line for the batch to `pipeline-metrics.jsonl`
   (see `/build` §4, `phase: "fix"`), chaining the opt-in usage ping in the same Bash call
   (results = items fixed over items found across surfaces, e.g. `"5/6"`).
-- Tell the human: re-run `/smoke` if the failures were runtime ones, and `/review $ARGUMENTS` for the
+- Tell the human: re-test by hand if the failures were runtime ones, and `/review $ARGUMENTS` for the
   re-verdict — the re-review is what *verifies* the ticked items actually hold (a regression simply
   reappears as a new finding in the next round). **Recommend a `/clear`** — all state (spec,
   checkboxes, staged report) is on disk, and the lead's history is re-sent at input price every turn.

package/core/commands/review.md

@@ -28,9 +28,13 @@ with `test -x`); note the epoch (`date +%s`) in the same call — §3's metrics
 
 - **Non-zero exit** ⇒ the script already printed the raw last-40 lines. **STOP: relay them verbatim
   and spawn NO agent** — a compiler/test failure needs `/fix` (or the human), not a review that
-  rediscovers it at agent prices. This abort is the whole point of the step.
+  rediscovers it at agent prices. This abort is the whole point of the step. Before stopping, write
+  the **aborted verdict** (§3's contract, degraded form) so an automated driver gets a diagnosis
+  rather than silence:
+  `{"id":"$ARGUMENTS","phase":"review","ts":"<ISO>","aborted":"preflight","verdict":"BLOCK","blocking":null}`
+  → `specs/reports/$ARGUMENTS.verdict.json`. One `printf`, in the same Bash call.
 - **Zero exit** ⇒ it stamped `.claude/preflight.ok`, which the gate hook checks before letting
-  `review`/`smoke` dispatches through (SCHEMA.md §Preflight). Continue.
+  `review` dispatches through (SCHEMA.md §Preflight). Continue.
 - Script absent (older core) ⇒ run the three commands yourself, each redirected into
   `specs/reports/$ARGUMENTS.preflight.txt`, aborting on the first failure the same way.
 
@@ -82,25 +86,100 @@ 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"`).
 **Stage the full report to `specs/reports/$ARGUMENTS.md`** (overwrite) — a gitignored buffer so a
 `/fix` after a `/clear` can still read the findings; the `specs/reports/` subfolder is skipped by the
 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 (`/drive`), which parses no prose:
+
+```json
+{ "id": "$ARGUMENTS", "phase": "review", "ts": "<ISO>", "verdict": "REVISE",
+  "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"],
+  "fingerprint": "b3f1c2a90d4e5f67" }
+```
+
+- **`blocking` = CRITICAL findings + `security` findings, deduplicated** (a finding that is both
+  counts once). That is exactly the agent's existing verdict rule restated as a number, so
+  `blocking == 0` ⟺ `verdict == SHIP`. HIGH/MEDIUM/LOW quality findings are **not** blocking —
+  they follow the `deferred:<id>` backlog route below, and must never cost a driver an iteration.
+- **`blocking_items`** — one normalized string per blocking finding, `<surface>|<file>|<problem>`:
+  the file path **without the `:line`** (a fix that inserts lines shifts every line below it — a
+  line-bearing identity would change every pass and the drift detection would never fire), and the
+  **problem**, not the fix, cut to its first 8 words, lowercased, every run of non-alphanumerics
+  collapsed to one space. Identity of a finding, not its wording.
+- **`fingerprint`** — computed in the same Bash call, never by hand:
+  `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 + runtime flows (a
-  prior `/smoke`). **Leave `- [ ]` (and say which) any item whose verifying stage didn't run this
-  cycle** — e.g. no `/smoke` ⇒ the mobile-first / runtime item stays open. Ticking is the lead's job
+  copy (this review), tests · lint · typecheck (a green `/build`), mobile-first as far as the code
+  shows it (this review). **Leave `- [ ]` (and say which) any item no stage actually verified** —
+  nothing in the pipeline *runs* the feature, so any criterion that needs the app up (runtime flows,
+  a visual check against the design) stays open unless the human says they exercised it by hand and
+  it held. Ticking is the lead's job
   (the reviewer is read-only). **Then stamp the freshness gate** so `/ship` can refuse to ship code
   edited after this verdict: compute `BASE=$(git merge-base <default_branch> HEAD)` and write into the
   spec front-matter `reviewed_base: $BASE` plus
@@ -108,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._

package/core/commands/spec.md

@@ -13,6 +13,10 @@ You run the **spec** step in the main thread — interactive, with the human. Pa
 > Template paths below (`.claude/templates/…`) resolve to `~/.claude/templates/…` when the core is
 > installed globally — read whichever exists.
 >
+> **Decision journal** (SCHEMA.md §Decisions): read `specs/_decisions.md` §Live if it exists — one
+> line per standing decision, so it is cheap. It is the ONLY place the project's transverse rules
+> live; a spec that contradicts one silently un-decides it. Absent ⇒ nothing to honour yet.
+>
 > **Kanban** (SCHEMA.md §Kanban): when the spec opens, move card `#<feature_id>` → **Spec**; on freeze
 > (`status: frozen`, Mode A) → **Ready to build**. No-op silently if no board is configured.
 
@@ -53,6 +57,22 @@ Detect the mode from the pasted content:
    Ping only on a **landed** freeze, so the funnel counts specs that exist, not attempts. Mode B does
    not ping — it re-enters an already-counted spec, and `/fix` covers that loop. Silent no-op without
    consent; never ask about consent here.
+5b. **Record the transverse decisions — the journal, not a summary.** Walk what the interview settled
+   and keep ONLY the decisions that **outlive this feature**: a rule the next spec would otherwise
+   re-litigate or contradict (auth model, id/naming scheme, where a kind of state lives, an error
+   convention, a deliberate non-goal that binds future features). Typical yield: **0–3 lines**; zero
+   is a normal, healthy outcome for a feature that decided nothing new — never invent lines to fill
+   the section. Append them to `specs/_decisions.md` §Live (create the file from
+   `.claude/templates/decisions.template.md` on first use), each exactly:
+   `- <YYYY-MM-DD> · <area> · <decision> — because <reason> · <feature_id>`
+   - **Never** duplicate what §5, `PIPELINE.md` §Conventions or the code already states — the journal
+     carries the *non-obvious rule*, not the feature's content. A line that restates a spec section is
+     a line every future `/spec` pays for and learns nothing from.
+   - **Contradicting an existing line** is allowed but never silent: tell the human which line this
+     feature overrides, get their go-ahead, then append the new line with
+     `· supersedes <YYYY-MM-DD> <area>` and move the old one to `## Superseded`.
+   - Append with one `>>` Bash call, not a full-file rewrite (the file is append-only, and reading it
+     back to re-write it is the one way to make a bounded file expensive).
 6. Author the **design brief** — `specs/design/<id>.md`, rendered via
    `.claude/templates/design-brief.md` (resolves to `~/.claude/templates/…` on a global install).
    _Only if `design.enabled` / the feature has UI; skip entirely for a backend-only feature._

package/core/commands/update-pipeline.md

@@ -84,7 +84,12 @@ actually connected) and repair whatever fails — wiring that worked at
 init can rot (PATH changes, uninstalls, hand-edits). Report what was reconciled; if nothing was
 missing, say so. This is why `/init-pipeline` never needs re-running for a core upgrade.
 
-Two of the §Reconcile steps matter specifically here:
+Three of the §Reconcile steps matter specifically here:
+
+- **Spec-template top-up** (§Reconcile step 7): `specs/_template.md` was seeded at install and never
+  refreshed since, so add the front-matter fields the current `templates/spec.template.md` has and the
+  repo's copy lacks (1.6 added `loop_pass`/`loop_phase` and two states to the `status:` comment) —
+  front-matter only, never the body.
 
 - **Global config seed** (§Reconcile step 5): if `~/.claude/cohorte.config.yaml` is absent, seed it
   from the template so the kanban + shared-vault config has a home. Never clobber an existing filled

package/core/hooks/gate.py

@@ -28,7 +28,7 @@ prompt that can never be answered.
 Two extra duties beyond Bash patterns:
 
 - Phase gate (`preflight` block in gate-config.json): a Task dispatch of a
-  listed subagent_type (default review/smoke) requires a fresh
+  listed subagent_type (default review) requires a fresh
   `.claude/preflight.ok` stamp, written by pipeline/scripts/preflight.sh when
   typecheck+lint+tests are green. Stale/missing stamp => "ask" — dispatching
   reviewers onto code that doesn't compile burns their whole run.
@@ -70,7 +70,7 @@ def load_config() -> dict:
         # Patterns gated ONLY on the default branch — allowed freely on feature branches.
         "ask_on_default_branch": list(cfg.get("ask_on_default_branch", [])),
         "default_branch": cfg.get("default_branch", "main") or "main",
-        # Phase gate: {"enabled": true, "agents": ["review","smoke"], "max_age_minutes": 30}
+        # Phase gate: {"enabled": true, "agents": ["review"], "max_age_minutes": 30}
         "preflight": preflight,
     }
 
@@ -130,11 +130,11 @@ def known_heads(cwd: str):
 
 
 def check_preflight(payload: dict, cfg: dict) -> int:
-    """Phase gate on Task dispatches: review/smoke agents need a green preflight stamp."""
+    """Phase gate on Task dispatches: review agents need a green preflight stamp."""
     pf = cfg.get("preflight") or {}
     if not pf.get("enabled"):
         return 0
-    agents = pf.get("agents") or ["review", "smoke"]
+    agents = pf.get("agents") or ["review"]
     subagent = (payload.get("tool_input") or {}).get("subagent_type", "") or ""
     if subagent not in agents:
         return 0

package/core/templates/decisions.template.md

@@ -0,0 +1,42 @@
+# Decisions
+
+> The project's **transverse decision journal** — the non-obvious rules a stateless agent would
+> otherwise re-discover or contradict, one feature at a time. `PIPELINE.md` says *how this repo is
+> built* (surfaces, commands, conventions); this file says *what was decided and why*.
+>
+> **Append-only. One line per decision. No prose blocks, no code.** The bound is the point: this file
+> is read by `/spec`, `/brainstorm` and `/audit` — the deciding stages — and by **nothing else**.
+> Implementers and reviewers never read it: they work from the frozen contract, which already tells
+> them what to do; handing them the rationale too would cost `surfaces × dispatches` tokens per
+> feature for a fact they cannot act on.
+>
+> Line shape (≤ ~160 chars, `·`-separated, no wrapping):
+>
+> ```
+> - <YYYY-MM-DD> · <area> · <the decision, imperative> — because <the reason> · <feature_id>
+> ```
+>
+> `<area>` is a short tag, not a path: `auth`, `data`, `api`, `ui`, `deploy`, `naming`, `surfaces`…
+>
+> **Reversing a decision** never edits or deletes a line — append a superseding one and move the old
+> one to `## Superseded`:
+>
+> ```
+> - <YYYY-MM-DD> · <area> · <the new decision> — because <reason> · supersedes <YYYY-MM-DD> <area> · <feature_id>
+> ```
+>
+> **Keep it bounded:** when `## Live` passes ~100 lines, move every superseded line into
+> `## Superseded` (the audit trail survives; the section the deciding stages actually read stays
+> short). Never summarize or merge live lines — a decision either holds or has been superseded.
+>
+> **What does NOT belong here:** anything the code, the tests, `PIPELINE.md` §Conventions or a spec
+> already states; a feature-local choice (that lives in its spec); a task, a TODO or a finding (those
+> are `## Remediation` and `specs/refactor-backlog.md`).
+
+## Live
+
+<!-- newest last -->
+
+## Superseded
+
+<!-- moved here when a line above supersedes them; never deleted -->

package/core/templates/spec.template.md

@@ -1,9 +1,11 @@
 ---
 feature_id: <slug>
 title: <Feature title>
-status: draft # draft → frozen → in-review → shipped
+status: draft # draft → frozen → in-progress → in-review → shipped · blocked (see SCHEMA.md §Spec status)
 branch: <feature_branch_prefix><slug>
 created: <YYYY-MM-DD>
+loop_pass: 0 # /drive bookkeeping — the review pass it is on; 0 = no loop running. Written by the driver, not by hand
+loop_phase: # /drive bookkeeping — build | review | fix | done. With loop_pass, this is what `--resume` reads back
 reviewed_base: # merge-base sha at the last SHIP verdict — freshness-gate anchor (written by /review)
 reviewed_digest: # sha256 (16 hex) of the reviewed source diff vs reviewed_base, specs excluded — /ship re-checks
 design_files: [] # design page links — full URLs of the form https://claude.ai/design/p/<projectId>?file=<file> (each carries its own project + page); blank until designed; omit if no UI
@@ -53,7 +55,7 @@ design_files: [] # design page links — full URLs of the form https://claude.ai
 
 > One `###` subsection per surface in `PIPELINE.md` §surfaces (e.g. backend, frontend), each TDD.
 > Surfaces are subsections of §6, never top-level sections — §8 and §9 are referenced by number
-> across the whole pipeline (`/smoke` drives "§8 flows", `/review` checks "§9 acceptance"), so a
+> across the whole pipeline (`/build` implements "§8 flows", `/review` checks "§9 acceptance"), so a
 > third surface must not become a §8 of its own.
 
 ### <surface.key>

package/core/templates/steps/init-pipeline/02-interview-gaps.md

@@ -20,7 +20,7 @@ Ask ONLY what you couldn't confidently detect. Batch related questions. Cover:
   Recommended option: dot/failures-only reporter (`--reporter=dot` vitest/playwright, `--silent`
   jest, `-q` pytest, `--quiet` eslint/ruff — whatever the detected runner supports). These land in
   `test_quiet_cmd`/`lint_quiet_cmd` + `commands.test_quiet`/`lint_quiet` and are what agents and the
-  `/review`·`/smoke` pre-flight actually run (SCHEMA.md §Output discipline). If the human declines or
+  `/review` pre-flight actually run (SCHEMA.md §Output discipline). If the human declines or
   the runner has no such flag, leave `""` — consumers then fall back to `<cmd> 2>&1 | tail -40`.
 - **Contract** — mechanism (`shared-types-zod` / `openapi` / `protobuf` / `json-schema` / `none`) and
   where feature contracts are authored. If `none`, surfaces sync by the spec prose alone.

package/core/templates/steps/init-pipeline/04-write-render.md

@@ -15,7 +15,7 @@
    (`<SURFACE_EXTRA_NEVER>`, `<SURFACE_DESIGN_INPUT>`, `<SURFACE_TDD_STEP1>` — fill design-related ones
    only when `uses_design`).
    Leave the fixed agents as-is (generic, shipped by the installer): `review.md`, `release.md`,
-   `smoke.md`, `profile-reader.md`.
+   `profile-reader.md`.
 4. **Generate `.claude/gate-config.json`** from the `gate` block — copy all five keys verbatim:
    `{"deny": [...], "ask": [...], "ask_on_default_branch": [...], "default_branch": "<vcs.default_branch>",
    "preflight": {"enabled": <gate.preflight.enabled>, "agents": [...], "max_age_minutes": <n>}}`
@@ -27,7 +27,11 @@
    variants** and repo-wide `commands.*` equivalents as `Bash(<cmd>:*)` rules, plus read-only git —
    `Bash(git status:*)`, `Bash(git diff:*)`, `Bash(git log:*)`, `Bash(git rev-parse:*)` — plus the
    shipped pipeline scripts for BOTH cores (`Bash(.claude/pipeline/scripts/:*)` and
-   `Bash(~/.claude/pipeline/scripts/:*)` — preflight, kanban-move, telemetry-send), and the
+   `Bash(~/.claude/pipeline/scripts/:*)` — preflight, kanban-move, telemetry-send) **plus the
+   `bash`-prefixed form the `/drive` driver uses** (`Bash(bash .claude/pipeline/scripts/loop.sh:*)`
+   and `Bash(bash ~/.claude/pipeline/scripts/loop.sh:*)`) — those prefix rules match a command
+   *starting* with the path, so `bash <path>` needs its own entry or `/drive` stalls on a permission
+   prompt at every launch, and the
    retrieval provider's MCP tools when wired (e.g. `mcp__serena`). Never allowlist anything matching
    a `gate.ask`/`gate.deny` pattern. Mention the human can widen it later with
    `/fewer-permission-prompts`) + the hooks, **conditioned on the install mode:**
@@ -86,8 +90,8 @@
     `build_cmd`s that are non-empty). Derive the setup steps from the detected stack — mirror what a
     sibling workflow does if one exists. `/ship` watches these checks before the merge.
 11. **Metrics sink & report buffer:** add `.claude/pipeline-metrics.jsonl` to `.gitignore` — `/build`,
-    `/review`, `/fix` and `/smoke` append per-dispatch evidence there (SCHEMA §Specialization reads it).
-    Also add `specs/reports/` — `/review` and `/smoke` stage their last report there so a `/fix` (or
+    `/review` and `/fix` append per-dispatch evidence there (SCHEMA §Specialization reads it).
+    Also add `specs/reports/` — `/review` stages its last report there so a `/fix` (or
     `/spec` Mode B) survives a `/clear`; it's a derived buffer, not a versioned artifact.
 12. **Design system:** if `design.enabled` with a snapshot dir, note that `/align-ds` is active; else the
     `/align-ds` command will no-op with a clear message.

package/core/workflows/review.js

@@ -131,11 +131,29 @@ const FINDING = {
   },
 }
 
+// A DEFERRED finding is real but out of this feature's scope (pre-existing code the
+// diff never touched). It carries its own out-of-scope reason, counts in no severity
+// row, is never cross-checked, and can never move the verdict — it is routed to
+// specs/refactor-backlog.md so /refactor owns it. See core/agents/review.md §Deferred.
+const DEFERRED = {
+  type: 'object', required: ['severity', 'file', 'line', 'kind', 'problem', 'fix', 'outOfScope'],
+  additionalProperties: false,
+  properties: {
+    severity: { enum: ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW'] },
+    file: { type: 'string' }, line: { type: 'integer' },
+    kind: { enum: ['quality', 'security', 'rule'] },
+    problem: { type: 'string', description: 'one line, no code excerpts' },
+    fix: { type: 'string', description: 'one concrete change, one line' },
+    outOfScope: { type: 'string', description: 'one line: why this feature does not own it' },
+  },
+}
+
 const REPORT = {
   type: 'object', required: ['verdict', 'findings'], additionalProperties: false,
   properties: {
     verdict: { enum: ['SHIP', 'REVISE', 'BLOCK'] },
     findings: { type: 'array', maxItems: 20, items: FINDING },
+    deferred: { type: 'array', maxItems: 10, items: DEFERRED },
     overflow: { type: 'integer', description: 'findings beyond the 20-item cap, if any' },
     notes: { type: 'string', description: 'RBAC / mobile-first assessment only, when the profile enables them' },
   },
@@ -222,7 +240,8 @@ const reviewed = await pipeline(
   s => agent(
     'Review one feature surface against its frozen spec, per your agent instructions (read the staged ' +
     'diff FIRST; open a full source file only when a finding demands it; capped shape — max 20 findings, ' +
-    'one line each, no code excerpts). — Variable slots: ' +
+    'one line each, no code excerpts). Put anything real but OUT of this feature\'s scope in `deferred` ' +
+    '(max 10, each with its out-of-scope reason) per your §Deferred rules — never in `findings`. — Variable slots: ' +
     `feature ${feature} · scope: the ${s.key} surface only · spec: specs/${feature}.md · ` +
     `staged diff: ${s.diff} · changed files: ${s.files.join(', ')}`,
     { agentType: 'review', label: `review:${s.key}`, phase: 'Review', schema: REPORT },
@@ -231,7 +250,10 @@ const reviewed = await pipeline(
     if (!report) return null
     const hard = report.findings.filter(f => f.severity === 'CRITICAL' || f.kind === 'security')
     const rest = report.findings.filter(f => !hard.includes(f))
-    if (!hard.length) return { key: s.key, report, kept: rest, refuted: [] }
+    // Deferred items skip the cross-check entirely: refuting one would spend an agent
+    // to argue about something that cannot affect the verdict either way.
+    const deferred = report.deferred || []
+    if (!hard.length) return { key: s.key, report, kept: rest, refuted: [], deferred }
     const votes = await parallel(hard.map(f => () => agent(
       'Adversarially verify ONE review finding — your job is to REFUTE it if you can. Read the staged ' +
       'diff and the exact file:line; refuted=true when the code, a guard, a test, or the spec shows the ' +
@@ -246,6 +268,7 @@ const reviewed = await pipeline(
       report,
       kept: rest.concat(checkedVotes.filter(v => !v.refuted).map(v => v.f)),
       refuted: checkedVotes.filter(v => v.refuted).map(v => ({ ...v.f, reason: v.reason })),
+      deferred,
     }
   },
 )
@@ -259,6 +282,9 @@ const unreviewed = touched.filter(s => !results.some(r => r.key === s.key)).map(
 if (unreviewed.length) log(`Reviewer died on: ${unreviewed.join(', ')} — those surfaces are NOT reviewed`)
 const kept = results.flatMap(r => r.kept.map(f => ({ ...f, surface: r.key })))
 const refuted = results.flatMap(r => r.refuted.map(f => ({ ...f, surface: r.key })))
+// Deferred findings are deliberately kept OUT of `counts`, out of `verdict` and out
+// of `clean`: they belong to /refactor, not to this feature's fix loop.
+const deferredAll = results.flatMap(r => (r.deferred || []).map(f => ({ ...f, surface: r.key })))
 const counts = { CRITICAL: 0, HIGH: 0, MEDIUM: 0, LOW: 0 }
 for (const f of kept) counts[f.severity] = (counts[f.severity] || 0) + 1
 // Verdict from the findings that SURVIVED the cross-check (a refuted CRITICAL
@@ -283,6 +309,10 @@ const reportBody = [
   ...['CRITICAL', 'HIGH', 'MEDIUM', 'LOW'].map(s => `| ${s} | ${counts[s] || 0} |`), '',
   `Verdict: ${verdict}`, '', '## Findings', '',
   kept.length ? kept.map(findingLine).join('\n') : 'None.',
+  '', '## Deferred', '',
+  deferredAll.length
+    ? deferredAll.map(f => `${findingLine(f)} · out of scope: ${f.outOfScope} · deferred:${feature}`).join('\n')
+    : 'None.',
   ...(unreviewed.length ? ['', '## NOT reviewed (reviewer died — no verdict on these)', '',
     unreviewed.map(k => `- \`${k}\` — re-run /review ${feature} (or the review workflow)`).join('\n')] : []),
   ...(refuted.length ? ['', '## Refuted by cross-check (no action needed)', '',
@@ -295,6 +325,17 @@ const staging = await agent(
   `{"ts":"<ISO now>","feature":"${feature}","phase":"review","seconds":0,"surfaces":{${results.map(r => `"${r.key}":"${verdict}:${r.kept.length}"`).join(',')}}}\n` +
   `3. Chain the opt-in usage ping: <core>/pipeline/scripts/telemetry-send.sh review "${feature}" 0 "${verdict}:${kept.length}" || true ` +
   '(<core> = .claude if .claude/pipeline/scripts/telemetry-send.sh exists, else ~/.claude; script on neither ⇒ skip the ping).\n' +
+  // Deferred findings must land in the backlog on EVERY verdict — parked only on a
+  // SHIP is parked nowhere the rest of the time, which is the leak this closes.
+  (deferredAll.length
+    ? `3b. Route the deferred findings to specs/refactor-backlog.md (create it if absent): for each line below, ` +
+      `append it under the \`## <domain>\` heading named in its prefix (create that heading if absent) — with \`>>\`, ` +
+      `never by rewriting the file, and skip any whose file path + first words already appear there (grep -F first, ` +
+      `they may be left from a prior round or an /audit):\n` +
+      deferredAll.map(f =>
+        `${f.surface}||- [ ] ${f.severity} · ${f.file}:${f.line} · ${f.kind} · ${f.fix} · deferred:${feature}`).join('\n') +
+      '\n'
+    : '') +
   // Stamp + tick only when nothing above LOW survived: the conversational /review
   // keeps the stamp only for LOW findings, and a SHIP verdict here can still carry
   // HIGH/MEDIUM ones — certifying those for /ship would ship known defects. A dead
@@ -318,6 +359,7 @@ const staged_ok = staging != null && /done/i.test(String(staging))
 return {
   verdict,
   counts,
+  deferred: deferredAll.length,     // parked in the backlog for /refactor — never blocking
   refutedByCrossCheck: refuted.length,
   reportStaged: staged_ok,
   unreviewedSurfaces: unreviewed,   // reviewers that died — these carry NO verdict