cohorte 1.3.4 → 1.5.0

package/CHANGELOG.md

@@ -3,6 +3,116 @@
 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
+> once the installed core is refreshed. Both the workflow scripts and the `profile-reader` agent
+> are replaced by the update.
+
+- **BREAKING — `/cycle` and `cycle.js` are removed.** The full-cycle workflow is gone: the command
+  file, the script, its tests and its documentation. The conversational path it wrapped is
+  unchanged and remains the way to run a feature — `/build` → `/smoke` → `/review` → `/fix` →
+  `/ship`, with `/clear` safe between each. `review.js`, `audit.js` and `refactor.js` are
+  untouched. Nothing else in the pipeline depended on it; a `/cycle` in an old habit will simply
+  report an unknown command. Metrics files and dashboards that already carry `phase: "cycle"`
+  lines keep rendering them.
+- **A workflow could dispatch zero agents and still report a verdict.** Phase 0's `profile-reader`
+  (haiku) intermittently returned the profile as a JSON *string* nested under a wrapper field
+  (`{"output": "{\"surfaces\": …}"}`) instead of at the top level. The schema was
+  `{type: 'object', additionalProperties: true}` — no declared properties, no required keys — so
+  the wrapper validated cleanly and every field then read as `undefined`: `surfaces` fell back to
+  `[]`, `parallel([])` dispatched **nothing**, and because every later guard compares against
+  `surfaces`, an empty list made them all vacuously pass. The run finished with a verdict, no code
+  written, and no complaint — indistinguishable from a clean run with an empty diff. Fixed in three
+  places: `profile-reader.md` now states that the profile's keys go at the top level of the
+  structured-output tool (with the wrong shapes shown), the schema declares what it expects, and a
+  profile with no surfaces **aborts loudly** instead of proceeding. All three workflows.
+- **`args` given as a JSON string became the feature id.** A caller that JSON-encoded its arguments
+  got that whole blob used as the id — which is how a report was written to
+  `specs/reports/{"feature": "x"}.md` — and the other options (`maxRounds`, `smoke`) silently read
+  as `undefined` on the same run, so a run could skip smoke without saying so. `args` is now parsed
+  back into an object (a bare slug is still valid shorthand), and a feature id that is not a slug
+  throws with an actionable message **before** anything touches the filesystem — so no junk file
+  can be written, and a path-shaped id is rejected.
+- **`/doctor` warned about a file cohorte itself had written.** `/audit` writes
+  `specs/refactor-backlog.md` by design; the spec scanner globbed `specs/*.md` and flagged it for
+  having no valid front-matter `status`. It fired in every project that had ever run `/audit`. Both
+  the conversational `/doctor` and the dashboard port now exclude it.
+- **New: `cohorte metrics` — real cost and runtime per command.** Reconstructs tokens, USD,
+  wall/active time and subagent counts from Claude Code's own transcripts, so it needs nothing
+  enabled and works retroactively on runs that already happened. It is worktree-aware (a feature
+  built across worktrees adds up instead of being dropped), attributes subagent spend back to the
+  command that spawned it, and de-duplicates the repeated `usage` blocks a single API response
+  writes across several transcript lines — summing those naively inflates tokens ~1.8×.
+  `--json`, `--runs`, `--days=N`, `--since=ISO`. Prices live in `scripts/metrics/prices.json`.
+
 ## 1.3.4 — 2026-07-31
 
 > **Re-run `npx cohorte@latest update --global` (or `update`)** — the workflow and script

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,10 +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.   |
-| `/cycle <id>`        | Launch the full dev-cycle **workflow** on a frozen spec: build → review → fix until zero findings (add `smoke` to run the app each round); deferred questions in the output. Needs workflows enabled (falls back to the conversational path). |
-| `/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.                                         |
@@ -231,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
@@ -244,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
@@ -257,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:
@@ -267,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.
@@ -284,7 +306,6 @@ it out turn by turn:
 
 | Script                  | What it runs                                                                              |
 | ----------------------- | ----------------------------------------------------------------------------------------- |
-| `workflows/cycle.js`    | **The full dev cycle on a frozen spec**: contract → parallel build → review(+cross-check) → fix (∥ smoke each round if opted in via `args.smoke`), looping until zero findings (contract changes handled in-loop by a lead-equivalent agent). Human decisions come back in a `questions` array at the END — empty when `/brainstorm`+`/spec` did their job. Exits SHIP-ready (DoD ticked, freshness stamped) so `/ship` is a straight shot. |
 | `workflows/review.js`   | Preflight gate (aborts while red — zero agents), one reviewer per touched surface, adversarial cross-check of CRITICAL/security findings, merged verdict only. |
 | `workflows/audit.js`    | One auditor per domain (every surface + shared) concurrently, prioritized `specs/refactor-backlog.md`. |
 | `workflows/refactor.js` | Big domains only: `shared` first and alone, then parallel surface implementers, per-domain verify + one retry. |
@@ -297,10 +318,9 @@ The essentials:
 - **Prerequisite: Claude Code ≥ 2.1.154** with workflows enabled. `/doctor` (check 8) tells you
   which path your session will take and why.
 - **No input mid-run — questions at the edges.** A workflow runs to completion without asking
-  anything. `cycle.js` moves the decisions to its boundaries: a readiness gate refuses a non-frozen
-  spec up front, and whatever would have been a mid-run question lands in the result's `questions`
-  array at the end (spec gaps, hit round-cap) — answer them, rerun the cycle. The destructive-
-  command gate still fires inside workflow subagents; in unattended runs its confirms become denies.
+  anything: whatever would have been a mid-run question lands in the result at the end. The
+  destructive-command gate still fires inside workflow subagents; in unattended runs its confirms
+  become denies.
 - Phase 0 of every script is the `profile-reader` agent (haiku) — it reads `PIPELINE.md` and hands
   the script the profile as JSON, since workflow scripts have no filesystem access. Mechanical
   phases run on haiku; judgment phases use the same pinned agents as the commands.
@@ -334,11 +354,11 @@ 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
-  workflows/            # opt-in Workflow-runtime scripts: cycle.js / review.js / audit.js / refactor.js
+  workflows/            # opt-in Workflow-runtime scripts: review.js / audit.js / refactor.js
 profile/
   PIPELINE.template.md  # the profile skeleton /init-pipeline fills
   SCHEMA.md             # field reference

package/bin/cli.js

@@ -35,6 +35,7 @@ Usage:
   cohorte install   [target] [--global]
   cohorte update    [target] [--global]
   cohorte dashboard [target] [--port=N] [--host=ADDR] [--open]
+  cohorte metrics   [target] [--days=N] [--since=ISO] [--runs] [--json]
   cohorte version
 
 Commands:
@@ -49,6 +50,11 @@ Commands:
             by default (loopback only — its actions execute code). --host=ADDR
             to expose (e.g. --host=0.0.0.0, prints a security warning). --open
             to launch the browser.
+  metrics   Cost and runtime per command, reconstructed from Claude Code's own
+            transcripts (tokens, USD, wall/active time, subagent count). Reads
+            ~/.claude/projects — nothing to enable, and it covers runs that
+            already happened. Worktree-aware, so a feature adds up. --json for
+            the raw rollup, --runs to include every individual invocation.
   version   Print the installed CLI version.`);
   process.exit(code);
 }
@@ -64,8 +70,16 @@ let port = parseInt(process.env.COHORTE_DASHBOARD_PORT, 10) || 4317;
 let host = process.env.COHORTE_DASHBOARD_HOST || '127.0.0.1';
 let openBrowser = false;
 
+// Flags that belong to `metrics` and are forwarded verbatim to the collector. They are
+// listed here rather than parsed, so the collector stays the single source of truth for
+// its own options — but the generic "unknown flag" guard below must not reject them.
+const metricsFlags = [];
+const isMetricsFlag = (a) =>
+  a === '--json' || a === '--runs' || a.startsWith('--days=') || a.startsWith('--since=');
+
 for (const a of args) {
-  if (a === 'install' || a === 'update' || a === 'dashboard') mode = a;
+  if (a === 'install' || a === 'update' || a === 'dashboard' || a === 'metrics') mode = a;
+  else if (isMetricsFlag(a)) metricsFlags.push(a);
   else if (a === 'version' || a === '--version' || a === '-v') { console.log(VERSION); process.exit(0); }
   else if (a === '--global' || a === '-g') scope = 'global';
   else if (a.startsWith('--port=')) {
@@ -96,6 +110,19 @@ if (mode === 'dashboard') {
   return;
 }
 
+// --- metrics: cost + runtime per command ------------------------------------
+// The collector is ESM and this CLI is CommonJS, so it runs as a child process rather
+// than being required. stdio is inherited so --json stays pipeable.
+if (mode === 'metrics') {
+  const script = path.join(pkgRoot, 'scripts', 'metrics', 'collect.mjs');
+  if (!fs.existsSync(script)) {
+    console.error(`error: metrics collector not found at ${script}`);
+    process.exit(1);
+  }
+  const r = spawnSync(process.execPath, [script, target, ...metricsFlags], { stdio: 'inherit' });
+  process.exit(r.status == null ? 1 : r.status);
+}
+
 // --- paths -------------------------------------------------------------------
 const globalDir = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
 const dest = scope === 'global' ? globalDir : path.join(target, '.claude');
@@ -109,7 +136,7 @@ fs.mkdirSync(dest, { recursive: true });
 
 // --- helpers (mirror install.sh) --------------------------------------------
 function copyCore() {
-  // `workflows` = the deterministic orchestration scripts (cycle/review/audit/refactor) the
+  // `workflows` = the deterministic orchestration scripts (review/audit/refactor) the
   // Workflow runtime resolves from .claude/workflows (bundled) or ~/.claude/workflows
   // (global) — same copy rule in both modes, like commands.
   for (const d of ['commands', 'hooks', 'templates', 'workflows']) {
@@ -186,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)) {
@@ -197,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/agents/profile-reader.md

@@ -21,6 +21,28 @@ nothing only when something is wrong.
 3. Return **only** the JSON object — no fences, no commentary, no markdown. Your final message is
    parsed by a script.
 
+## Returning through a structured-output tool
+
+When you are given a tool to return structured output, the profile's own keys go at the **top
+level** of that tool's input — `surfaces`, `commands`, `vcs`, `contract`, and the rest, as real
+JSON values.
+
+Do **not** serialize the profile to a string and nest it under a wrapper field. These are wrong:
+
+```json
+{"output": "{\"surfaces\": [ … ]}"}      ← the profile as text under a wrapper
+{"profile": {"surfaces": [ … ]}}         ← the profile nested one level down
+```
+
+This is right:
+
+```json
+{"surfaces": [ … ], "commands": { … }, "vcs": { … }}
+```
+
+A wrapped return costs the caller everything: the script reads `surfaces` as absent, builds
+nothing, and reports success anyway.
+
 ## Failure shape
 
 If `PIPELINE.md` is missing, or the `yaml pipeline-profile` fence is absent or unparseable, return

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,10 +34,10 @@ 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`,
-   `update-pipeline`, `cycle` — in `.claude/commands/` or `~/.claude/commands/`) carries `model: sonnet` in
+   (`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
    (interactive — they inherit the session model).
@@ -73,7 +73,7 @@ fix only with the human's go-ahead (or hand them the command).
    take and why:
    - **Claude Code version** ≥ 2.1.154 (`claude --version 2>/dev/null | head -1`) — older or no CLI
      on PATH ⇒ conversational only.
-   - **Scripts present:** `<core>/workflows/review.js` + `audit.js` + `refactor.js` + `cycle.js` —
+   - **Scripts present:** `<core>/workflows/review.js` + `audit.js` + `refactor.js` —
      missing on a current core ⇒ half-done install, re-run install/update.
    - **Phase-0 agent present:** `<agents dir>/profile-reader.md` (repo `.claude/agents/` bundled or
      `~/.claude/agents/` global) — the workflows abort without it.
@@ -84,9 +84,11 @@ fix only with the human's go-ahead (or hand them the command).
    End the check with ONE summary line, e.g.
    `workflows: available (opt-in — ask to "run the review workflow")` or
    `workflows: unavailable (<first failing prerequisite>) — conversational commands (the default)`.
-9. **Specs & metrics.** Every `specs/*.md` front-matter `status` is a valid stage; `shipped` specs
+9. **Specs & metrics.** Every `specs/*.md` front-matter `status` is a valid stage — excluding
+   `_`-prefixed files and `specs/refactor-backlog.md`, which `/audit` writes as a backlog, not a
+   spec, and which has no front-matter to check; `shipped` specs
    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>