cohorte 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -3,6 +3,73 @@
 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.5.0 — 2026-08-01
+
+> **Re-run `npx cohorte@latest update --global` (or `update`)** to pick up the collector and the
+> `/smoke` removal — the update *deletes* the command and its agent from your install, it does not
+> just stop shipping them. The new dashboard panel comes with `npx cohorte dashboard`.
+
+- **New — `/loop <id>`: the review ⇄ fix cycle, run for you.** `/build` → `/review` → `/fix` →
+  `/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
@@ -217,9 +217,9 @@ it in `.claude/pipeline/VERSION` and bundled repos in their committed `pipeline.
 | `/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. |
+| `/fix <id>`          | Apply a review report: remediation into the spec, re-dispatch only the surfaces with findings. |
+| `/loop <id>`         | Autonomous `/build → /review → /fix → /review …` until no blocking finding is left (see below). |
 | `/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 +230,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 +243,29 @@ lever: long sessions (>150k) are expensive even when cached. Each command tells
 safe to clear. If you'd rather stay in one session, `/compact` mid-task does the lighter version. (Claude
 can't fire `/clear` itself — it's a client-side command; the pipeline just makes it always safe to type.)
 
+### Let it run itself — `/loop`
+
+```
+/loop feat-x              # /build, then /review ⇄ /fix until clean (max 5 passes)
+/loop feat-x --no-build   # already built — just re-run the /review ⇄ /fix loop
+/loop feat-x --max=8
+```
+
+It stops when `/review` reports **zero blocking findings** (a CRITICAL or a security issue — a LOW
+nit never costs a pass), at the pass ceiling, or as soon as two consecutive reviews return the same
+blocking findings, which means the fix is treading water and more passes won't help. **Each fix pass
+is committed** (`loop(<id>): fix pass <i>`) — that's your way back after N autonomous passes — and
+**no fix runs on the last pass**, since fixing without a review behind it leaves unaudited code.
+
+**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 +279,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 +289,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 +354,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,9 @@ 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 });
   scrubResearchQuestionnaire();
 }
 

package/core/commands/build.md

@@ -105,10 +105,10 @@ Bash call, chain the opt-in usage ping — **the shared form every phase command
 `<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`.
+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
@@ -88,7 +88,7 @@ fix only with the human's go-ahead (or hand them the command).
    `_`-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
    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.

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
@@ -65,7 +65,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/loop.md

@@ -0,0 +1,61 @@
+---
+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]
+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 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`) and exits 64 on anything it doesn't know. Don't validate flags yourself,
+don't rewrite them, don't add any.
+
+**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.
+
+| 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) |
+| `64` | usage | relay the script's own message verbatim |
+
+Then print exactly three lines and nothing else:
+
+```
+outcome:    <one clause — clean / ceiling / no verdict / non-convergent / usage>
+iterations: <n> review pass(es)<, m fix pass(es) committed>
+remaining:  <blocking count + one short phrase per blocking item, or "none">
+```
+
+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/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.
 
@@ -91,6 +95,33 @@ 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 (`/loop`), which parses no prose:
+
+```json
+{ "id": "$ARGUMENTS", "phase": "review", "ts": "<ISO>", "verdict": "REVISE",
+  "findings": 7, "blocking": 2, "security": 1,
+  "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.
+
 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:
@@ -98,9 +129,11 @@ 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
   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

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/spec.template.md

@@ -53,7 +53,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 `/loop` 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 `/loop` 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.