cohorte 1.3.4 → 1.5.0

package/dashboard/server/doctor.js

@@ -12,12 +12,22 @@ const { versions } = require('./versions');
 // Rendered surface agents live alongside these fixed (non-surface) agents; exclude them
 // from the orphan check so they're never mistaken for a stray surface agent.
 const FIXED_AGENTS = new Set([
-  'review', 'release', 'smoke', 'profile-reader',
+  'review', 'release', 'profile-reader',
+  // retired (1.5.0) — still excluded so a stale install's leftover file isn't
+  // reported as a stray surface agent.
+  'smoke',
   'implementer.template',
 ]);
 
 const VALID_STATUS = ['draft', 'frozen', 'in-review', 'shipped'];
 
+// Artifacts the pipeline itself writes into specs/ that are NOT feature specs and have no
+// front-matter status. `/audit` writes specs/refactor-backlog.md by design, so scanning it
+// as a spec made /doctor warn about a file cohorte had just created — a false positive that
+// fired in every project that had ever run /audit. `_`-prefixed files (e.g. _template.md)
+// are already skipped by the reader below.
+const NON_SPEC_FILES = new Set(['refactor-backlog.md']);
+
 const exists = p => { try { return fs.existsSync(p); } catch { return false; } };
 const readText = p => { try { return fs.readFileSync(p, 'utf8'); } catch { return null; } };
 const readJson = p => { try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return null; } };
@@ -119,7 +129,7 @@ function checkGate(profile, projectRoot) {
   const wantPf = gate.preflight || {};
   const havePf = (cfg.preflight && typeof cfg.preflight === 'object') ? cfg.preflight : {};
   if (!!wantPf.enabled !== !!havePf.enabled
-      || !sameSet(wantPf.agents || ['review', 'smoke'], havePf.agents || ['review', 'smoke'])
+      || !sameSet(wantPf.agents || ['review'], havePf.agents || ['review'])
       || Number(wantPf.max_age_minutes || 30) !== Number(havePf.max_age_minutes || 30)) {
     drifted.push('preflight');
   }
@@ -226,7 +236,7 @@ function checkIsolation(profile, projectRoot) {
   return mk('isolation', 'Isolation', 'ok', 'feature scripts rendered (worktree state not checked here)');
 }
 
-// Workflow variants (cycle/review/audit/refactor as deterministic multi-agent runs) are opt-in;
+// Workflow variants (review/audit/refactor as deterministic multi-agent runs) are opt-in;
 // the conversational commands stay the default path, so nothing here is ever 'bad'.
 // Whether the session has workflows ENABLED needs a live Claude session — /doctor
 // in-session checks that; here we only check what's on disk.
@@ -238,7 +248,7 @@ function checkWorkflows(projectRoot, globalDir, installMode) {
   const agentsDir = installMode === 'bundled'
     ? path.join(projectRoot, '.claude', 'agents')
     : path.join(globalDir, 'agents');
-  const scripts = ['review.js', 'audit.js', 'refactor.js', 'cycle.js'];
+  const scripts = ['review.js', 'audit.js', 'refactor.js'];
   const missing = scripts.filter(s => !exists(path.join(dir, s)));
   if (missing.length === scripts.length) {
     return mk('workflows', 'Workflows', 'warn',
@@ -263,7 +273,7 @@ function scanSpecs(projectRoot) {
   const dir = path.join(projectRoot, 'specs');
   const specs = [];
   let files = [];
-  try { files = fs.readdirSync(dir).filter(f => f.endsWith('.md') && !f.startsWith('_')); }
+  try { files = fs.readdirSync(dir).filter(f => f.endsWith('.md') && !f.startsWith('_') && !NON_SPEC_FILES.has(f)); }
   catch { return specs; }
   for (const f of files) {
     const txt = readText(path.join(dir, f)) || '';

package/dashboard/server/index.js

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

package/dashboard/server/metrics.js

@@ -1,6 +1,6 @@
 'use strict';
 // Read a project's `.claude/pipeline-metrics.jsonl` (one line per phase batch, appended by
-// /build, /review, /fix and /smoke) and aggregate it per feature: wall-clock per phase, fix
+// /build, /review and /fix) and aggregate it per feature: wall-clock per phase, fix
 // rounds, and per-surface results. Dependency-free; a missing file is simply "no data yet".
 //
 // Two line formats coexist in the file:
@@ -11,9 +11,9 @@
 const fs = require('fs');
 const path = require('path');
 
-// `cycle` is the workflow variant's own batch (cycle.js §Close). Without it in this
-// list its per-surface results parse fine but render in no column — the surface table
-// showed rows with every cell empty.
+// `smoke` and `cycle` are RETIRED phases, kept so metrics files written before their removal
+// still render. Without them in this list their per-surface results parse fine but land in no
+// column — the surface table showed rows with every cell empty.
 const PHASES = ['build', 'review', 'fix', 'smoke', 'cycle'];
 
 // Parse the raw JSONL into normalized batches ({ts, feature, phase, seconds, surfaces}),
@@ -74,7 +74,8 @@ function aggregate(batches) {
       };
       byFeature.set(b.feature, f);
     }
-    // cycle.js reports its round count outside `surfaces` (that map is for surfaces).
+    // The retired cycle phase reported its round count outside `surfaces` (that map is for
+    // surfaces); historical files still carry it.
     if (b.phase === 'cycle' && Number(b.rounds) > 0) f.cycleRounds = Number(b.rounds);
     if (b.ts && (!f.firstTs || b.ts < f.firstTs)) f.firstTs = b.ts;
     if (b.ts && b.ts > f.lastTs) f.lastTs = b.ts;

package/dashboard/server/usage.js

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

package/install.ps1

@@ -151,6 +151,7 @@ try {
         Copy-Item (Join-Path $src 'scripts\kanban-move.sh')       (Join-Path $dest 'pipeline\scripts') -Force
         Copy-Item (Join-Path $src 'scripts\telemetry-send.sh')    (Join-Path $dest 'pipeline\scripts') -Force
         Copy-Item (Join-Path $src 'scripts\preflight.sh')         (Join-Path $dest 'pipeline\scripts') -Force
+        Copy-Item (Join-Path $src 'scripts\loop.sh')              (Join-Path $dest 'pipeline\scripts') -Force
         Copy-Item (Join-Path $src 'core\agents\implementer.template.md') (Join-Path $dest 'pipeline') -Force
         if (Test-Path (Join-Path $src 'CHANGELOG.md')) { Copy-Item (Join-Path $src 'CHANGELOG.md') (Join-Path $dest 'pipeline') -Force }
         [System.IO.File]::WriteAllText((Join-Path $dest 'pipeline\VERSION'), "$ver`n", [System.Text.UTF8Encoding]::new($false))
@@ -188,8 +189,10 @@ try {
         New-Item -ItemType Directory -Force -Path (Join-Path $dest 'agents') | Out-Null
         Copy-Item (Join-Path $src 'core\agents\review.md'),
                   (Join-Path $src 'core\agents\release.md'),
-                  (Join-Path $src 'core\agents\smoke.md'),
                   (Join-Path $src 'core\agents\profile-reader.md') (Join-Path $dest 'agents') -Force
+        # 1.5.0 removed the /smoke phase; copy-over never deletes, so scrub the orphan agent.
+        Remove-Item -LiteralPath (Join-Path $dest 'agents\smoke.md') -Force -ErrorAction SilentlyContinue
+        Remove-Item -LiteralPath (Join-Path $dest 'commands\smoke.md') -Force -ErrorAction SilentlyContinue
         # 0.1.19 split the bi-mode questionnaire-researcher into research-agent + questionnaire-architect;
         # copy-over never deletes, so scrub the retired agent lest a dead subagent_type linger.
         Remove-Item -LiteralPath (Join-Path $dest 'agents\questionnaire-researcher.md') -Force -ErrorAction SilentlyContinue

package/install.sh

@@ -107,8 +107,9 @@ copy_core() {
   cp "$src/scripts/kanban-move.sh"       "$dest/pipeline/scripts/"
   cp "$src/scripts/telemetry-send.sh"    "$dest/pipeline/scripts/"
   cp "$src/scripts/preflight.sh"         "$dest/pipeline/scripts/"
+  cp "$src/scripts/loop.sh"              "$dest/pipeline/scripts/"
   chmod +x "$dest/pipeline/scripts/kanban-move.sh" "$dest/pipeline/scripts/telemetry-send.sh" \
-           "$dest/pipeline/scripts/preflight.sh" 2>/dev/null || true
+           "$dest/pipeline/scripts/preflight.sh" "$dest/pipeline/scripts/loop.sh" 2>/dev/null || true
   cp "$src/core/agents/implementer.template.md" "$dest/pipeline/"
   [ -f "$src/CHANGELOG.md" ] && cp "$src/CHANGELOG.md" "$dest/pipeline/"
   printf '%s\n' "$ver" > "$dest/pipeline/VERSION"
@@ -149,8 +150,10 @@ PY
 copy_fixed_agents() {
   mkdir -p "$dest/agents"
   cp "$src/core/agents/review.md" "$src/core/agents/release.md" \
-     "$src/core/agents/smoke.md" "$src/core/agents/profile-reader.md" \
+     "$src/core/agents/profile-reader.md" \
      "$dest/agents/"
+  # 1.5.0 removed the /smoke phase; copy-over never deletes, so scrub the orphan agent.
+  rm -f "$dest/agents/smoke.md" "$dest/commands/smoke.md"
   # 0.1.19 split the bi-mode questionnaire-researcher into research-agent + questionnaire-architect;
   # copy-over never deletes, so scrub the retired agent lest a dead subagent_type linger.
   rm -f "$dest/agents/questionnaire-researcher.md"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cohorte",
-  "version": "1.3.4",
+  "version": "1.5.0",
   "description": "Portable, stack-agnostic multi-agent development pipeline for Claude Code — install the core, run /init-pipeline, and it adapts to your project's stack.",
   "bin": {
     "cohorte": "bin/cli.js"

package/profile/PIPELINE.template.md

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

package/profile/SCHEMA.md

@@ -34,7 +34,7 @@ generic pipeline uses it, so a stateless agent can read/regenerate the profile c
 | `contract.path` `.ext` `.index`      | string       | build                             | Where `<feature_id>` contract is authored + barrel.           |
 | `contract.authored_by`               | const `lead` | build                             | Implementers import it read-only, never edit.                 |
 | `commands.*`                         | string       | all                               | Repo-wide install/dev/lint/format/typecheck/test + migrate.   |
-| `commands.test_quiet` `.lint_quiet`  | string       | review, smoke, audit, workflows   | Repo-wide bridled variants — what the `/review`·`/smoke` pre-flight runs. Same fallback as the per-surface ones. |
+| `commands.test_quiet` `.lint_quiet`  | string       | review, audit, workflows          | Repo-wide bridled variants — what the `/review` pre-flight runs. Same fallback as the per-surface ones. |
 | `rbac.enabled`                       | bool         | brainstorm, review                | Toggle RBAC personas + authz audit.                           |
 | `rbac.hierarchy`                     | list         | review                            | Highest→lowest role list.                                     |
 | `design.enabled`                     | bool         | build, frontend, align-ds         | `false` ⇒ design steps are no-ops.                            |
@@ -52,8 +52,8 @@ generic pipeline uses it, so a stateless agent can read/regenerate the profile c
 | `gate.ask[]`                         | list         | hooks/gate.py, settings           | Command substrings that require confirm, on any branch.       |
 | `gate.ask_on_default_branch[]`       | list         | hooks/gate.py                     | Confirm ONLY on `default_branch`; free on feature branches.   |
 | `gate.default_branch`                | string       | hooks/gate.py                     | Protected branch (default `main`); gate resolves via git.     |
-| `gate.preflight.enabled`             | bool         | hooks/gate.py, review, smoke      | Phase gate: review/smoke dispatches need a fresh preflight stamp. See §Preflight. |
-| `gate.preflight.agents[]`            | list         | hooks/gate.py                     | `subagent_type`s the stamp gates (default `[review, smoke]`). |
+| `gate.preflight.enabled`             | bool         | hooks/gate.py, review             | Phase gate: review dispatches need a fresh preflight stamp. See §Preflight. |
+| `gate.preflight.agents[]`            | list         | hooks/gate.py                     | `subagent_type`s the stamp gates (default `[review]`).        |
 | `gate.preflight.max_age_minutes`     | number       | hooks/gate.py                     | Stamp freshness window (default 30).                          |
 
 ## Prose sections
@@ -161,10 +161,10 @@ the frozen contract as the only cross-surface channel**. So specialization means
 Coarse first, specialize on evidence: start with one `frontend` / `backend` surface each; split only a
 surface that's proven slow and cleanly separable. The evidence lives in
 the **main checkout's** `.claude/pipeline-metrics.jsonl` (gitignored) — one JSONL line per phase batch
-(`ts`/`feature`/`phase`/`seconds`/`surfaces:{key: result}`), appended by `/build`, `/review`, `/fix`
-and `/smoke`, plus a `phase: "cycle"` line from the cycle workflow.
+(`ts`/`feature`/`phase`/`seconds`/`surfaces:{key: result}`), appended by `/build`, `/review`
+and `/fix`.
 **`surfaces` keys are surface keys, nothing else** — run-level facts go in their own top-level
-fields (the cycle line carries `rounds` and `smoke` there). Anything put inside `surfaces` is read
+fields. Anything put inside `surfaces` is read
 as a surface: the dashboard renders it as a row in the per-surface table and scores a non-`ok`
 value as that surface failing. Always the main checkout, never the feature worktree (which dies at teardown while
 metrics must accumulate across features) — resolve from anywhere with
@@ -188,7 +188,7 @@ to log it. For what's EXPENSIVE, use Claude Code's own accounting:
   per-subagent attribution needs traces (`CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`, beta).
 
 **Lead context discipline — the silent bill.** The lead session's conversation history is re-sent as
-input on EVERY turn; a session that spans spec→build→smoke→review→fix without clearing re-pays the
+input on EVERY turn; a session that spans spec→build→review→fix without clearing re-pays the
 accumulated spec walk-through, handoffs, and reports on each turn. The pipeline is built so this is
 never necessary: every phase handoff (spec, contract, diff, staged reports) lives on disk, so `/clear`
 at each phase boundary is always safe — each command's closing line recommends it. Corollaries the
@@ -219,7 +219,7 @@ storing a bare `pnpm test` as the thing agents execute; `/update-pipeline` tops
 
 ## Preflight — the deterministic phase gate
 
-`/review` and `/smoke` start by running `pipeline/scripts/preflight.sh` — a plain shell script (no
+`/review` starts by running `pipeline/scripts/preflight.sh` — a plain shell script (no
 agent) that executes the profile's mechanical checks in order (typecheck → lint → tests, quiet
 variants) with all output redirected to `specs/reports/<id>.preflight.txt`:
 
@@ -231,7 +231,7 @@ variants) with all output redirected to `specs/reports/<id>.preflight.txt`:
 
 `hooks/gate.py` enforces the stamp as a **phase gate** (the `preflight` block of `gate-config.json`,
 generated from `gate.preflight`): a Task dispatch of a listed `subagent_type` (default
-`review`/`smoke`) with a missing/stale stamp — older than `max_age_minutes`, or HEAD moved — gets an
+`review`) with a missing/stale stamp — older than `max_age_minutes`, or HEAD moved — gets an
 "ask", so a lead can't accidentally skip the gate but a human can consciously override it. The gate
 hook fires for **every** agent in the session, including subagents spawned by the Workflow runtime
 (they run in `acceptEdits` whatever the session mode — Write/Edit auto-approved — but Bash and Task
@@ -319,13 +319,12 @@ itself changes in ways `/build` §1.5 can't auto-grow (e.g. package manager or c
 
 ## Workflows — deterministic multi-agent runs (opt-in)
 
-Four phases have a **workflow variant** — a deterministic orchestration script the Claude Code
+Three phases have a **workflow variant** — a deterministic orchestration script the Claude Code
 Workflow runtime executes instead of the lead reasoning out the fan-out turn by turn:
-`<core>/workflows/review.js`, `audit.js`, `refactor.js`, `cycle.js` (installed to `.claude/workflows/` bundled or
+`<core>/workflows/review.js`, `audit.js`, `refactor.js` (installed to `.claude/workflows/` bundled or
 `~/.claude/workflows/` global). The conversational commands (`/review`, `/audit`, `/refactor`)
 **remain the default path and the fallback** — a workflow runs only when the human explicitly asks
-for it ("run the review workflow", or via the `/cycle <id>` launcher command, which resolves
-`cycle.js` and invokes the runtime for them), and requires Claude Code ≥ **2.1.154** with workflows
+for it ("run the review workflow"), and requires Claude Code ≥ **2.1.154** with workflows
 enabled.
 `/doctor` reports which path a session will take. The interactive commands (`/init-pipeline`,
 `/brainstorm`, `/spec`) and the dispatch-only ones (`/build`, `/ship`) have **no** workflow variant on
@@ -345,8 +344,8 @@ Shared design, all four scripts:
 - **A dead agent is never a clean result.** `agent()` resolves to `null` when a subagent dies, and a
   dead *reviewer* returns zero findings — byte-identical to a surface that is genuinely clean. Any
   script that derives a verdict from "how many findings came back" must first subtract the agents
-  that never answered: `review.js` and `cycle.js` name them in `unreviewedSurfaces`, refuse to score
-  `SHIP`, and (in the cycle) never tick the DoD or stamp the freshness gate. `scripts/test-workflows.mjs`
+  that never answered: `review.js` names them in `unreviewedSurfaces` and refuses to score
+  `SHIP`. `scripts/test-workflows.mjs`
   pins this — it is the one invariant the structural checks in `validate-core.mjs` cannot see.
 - **`review.js`** — preflight gate (aborts red, zero agents), one `git diff --stat` staged per
   touched surface, one reviewer per surface in parallel, then an **adversarial cross-check** phase
@@ -356,28 +355,9 @@ Shared design, all four scripts:
 - **`refactor.js`** — big domains only (it skips domains with a handful of open items — the
   conversational `/refactor` is cheaper there): `shared` first and alone, then the other domains'
   implementers in parallel, each verified per-domain.
-- **`cycle.js`** — the **full dev cycle** on a frozen spec: contract → parallel build → rounds of
-  [preflight → review(+cross-check) (∥ smoke if opted in) → fix on the surfaces with findings], looping until
-  **zero open findings (+ a PASS smoke when opted in)** (`maxRounds`, default 5, and the token budget are runaway
-  protection, not targets). Since a workflow can't ask anything mid-run, the decisions move to the
-  edges: a **readiness gate** aborts up front if the spec isn't frozen (other gaps ride along as
-  deferred questions), and everything genuinely human comes back at the END in the result's
-  `questions` array — empty when `/brainstorm` + `/spec` did their job. Even a finding that implies
-  a **contract change stays inside the loop**: a lead-equivalent agent re-authors spec §5 + the
-  contract file (exactly what conversational `/fix` §1 does — implementers still never touch it),
-  the consuming surfaces re-dispatch, and the loop continues; the re-authorings are reported in the
-  result's `contractChanges` for the human to review in the diff. A clean exit ticks the DoD and
-  stamps the freshness gate (when smoke was skipped — the default — the runtime-flows DoD box stays
-  unticked and `/ship` flags it); a stopped run appends its open
-  findings to the spec's `## Remediation` so a rerun of the cycle — or a conversational `/fix` —
-  continues seamlessly. `/ship` itself stays outside on purpose — outward-facing and irreversible,
-  it keeps its human confirmation.
-  **Corollary — harden the spec:** the more `/brainstorm` + `/spec` pre-answer (edge cases, error
-  envelopes, role matrix, design links), the further the cycle runs and the emptier `questions`
-  comes back; a vague spec just converts into deferred questions.
 - **No input mid-run.** A workflow runs to completion without questions; anything interactive
-  (contract changes, human decisions) belongs to the conversational path — or, for `cycle.js`, to
-  the `questions` array of its result. The gate hook still fires on workflow subagents (see
+  (contract changes, human decisions) belongs to the conversational path. The gate hook still
+  fires on workflow subagents (see
   §Preflight) — in unattended runs its asks become denies.
 - **Permissions:** `/init-pipeline` and `/update-pipeline` extend the generated `settings.json`
   `allow` list with what workflow agents need (the quiet commands, the shipped
@@ -429,7 +409,7 @@ card created in the target column if missing.
 | `/spec` opens (draft)                   | `spec`          |
 | `/spec` freezes (`status: frozen`)      | `ready`         |
 | `/build`                                | `building`      |
-| `/review` (owns the move — `/smoke` never moves the card) | `review`        |
+| `/review`                               | `review`        |
 | `/fix`                                  | `fix`           |
 | `/ship` starts                          | `ship`          |
 | PR opened (`status: shipped`)           | `shipped` (+ `PR #<num>` on the card) |
@@ -457,7 +437,7 @@ pre-telemetry installs) ask ONE question, once per machine, default **No**, and
 `|| true`, so a **missing** script is equally silent: `/doctor` check 1 verifies `pipeline/scripts/`
 is fully populated.
 
-**Which commands ping** — the seven that make up the feature funnel, and only those. The point is to
+**Which commands ping** — the six that make up the feature funnel, and only those. The point is to
 see where features stall, so every stage of `idea → PR` reports and nothing else does:
 
 | phase | fired when | `seconds` | `results` |
@@ -465,16 +445,13 @@ see where features stall, so every stage of `idea → PR` reports and nothing el
 | `brainstorm` | the return is staged | `0` | — |
 | `spec` | a freeze lands (Mode A only) | `0` | `frozen` |
 | `build` | after the batch metrics line | wall-clock | `ok,ok` / `error` |
-| `smoke` | after the verdict | wall-clock | `PASS` / `FAIL:<n>` |
 | `review` | after the merged verdict | wall-clock | `<verdict>:<count>` |
 | `fix` | after the batch metrics line | wall-clock | `<fixed>/<found>` |
 | `ship` | the release agent succeeded | `0` | `pr` / `compare` |
 
-> Workflow-variant runs (`review.js`, `cycle.js`) report `seconds: 0` for their phases — only the
-> conversational commands measure wall-clock. `cycle.js` also reports `fix` as `rounds:<n>` (the
-> number of fix dispatches it made) rather than `<fixed>/<found>`: it never counts items the way a
-> conversational `/fix` does. `results` is a free-text summary field, so both forms are valid — but
-> read the `fix` column knowing which path produced it.
+> Workflow-variant runs (`review.js`) report `seconds: 0` for their phases — only the
+> conversational commands measure wall-clock. `results` is a free-text summary field, so both
+> forms are valid — but read the `fix` column knowing which path produced it.
 
 `seconds: 0` marks a phase whose duration is human thinking time, not pipeline wall-clock — the
 funnel signal there is the event, not how long it took. `/doctor`, `/audit`, `/refactor`,

package/scripts/loop.sh

@@ -0,0 +1,189 @@
+#!/usr/bin/env bash
+#
+# loop.sh — autonomous /build → /review → /fix → /review … loop for ONE feature.
+#
+#   loop.sh <feature-id> [--max=N] [--no-build] [--rebuild]
+#
+# THE POINT: every phase runs as a SEPARATE `claude -p` child with its own fresh
+# context. The session that typed /loop never sees the diff, the N review reports
+# or the N contracts — it reads only this script's one-line-per-phase stdout and,
+# at the end, the verdict JSON. Running the loop inside the calling session would
+# accumulate all of it in a history that is re-sent at input price on every turn,
+# which is the exact cost the pipeline's /clear discipline exists to avoid.
+#
+# Contract with the pipeline: /review writes specs/reports/<id>.verdict.json on
+# every run. That file — `blocking` and `fingerprint` — is the ONLY channel
+# between cohorte and this driver. No prose is parsed.
+#
+# Exit codes (three distinct diagnostics, do not collapse them):
+#   0   clean — a review returned blocking == 0
+#   1   ceiling — --max passes used, still blocking (the fix was progressing;
+#       re-run with a higher --max)
+#   2   no usable verdict — /review produced nothing, or aborted on a red
+#       preflight (typecheck/lint/tests broken; the message says which)
+#   3   non-convergent — two consecutive reviews returned the SAME blocking
+#       fingerprint: the fix is treading water, a higher --max will not help
+#   64  usage — bad flag, bad id, missing spec, no `claude` on PATH
+#
+# No /fix runs on the last pass: fixing without a review behind it ships
+# unaudited code. Each fix pass is committed — that commit is the only way back
+# after N autonomous passes.
+
+set -uo pipefail
+
+usage() {
+  cat >&2 <<'EOF'
+usage: loop.sh <feature-id> [--max=N] [--no-build] [--rebuild]
+
+  --max=N      stop after N review passes (default 5)
+  --no-build   never build — re-run the /review ⇄ /fix loop on a feature that
+               is already built (the common case; the build stamp is ignored)
+  --rebuild    force a /build even if the stamp says it was already built
+
+  env CLAUDE_FLAGS   flags for every child session
+                     (default: --permission-mode acceptEdits)
+EOF
+  exit 64
+}
+
+id=""
+max=5
+build_mode="auto"          # auto | never | force
+
+for arg in "$@"; do
+  case "$arg" in
+    --max=*)
+      max="${arg#--max=}"
+      case "$max" in
+        ''|*[!0-9]*) echo "loop: --max must be a positive integer (got '${arg#--max=}')" >&2; exit 64 ;;
+      esac
+      [ "$max" -ge 1 ] || { echo "loop: --max must be >= 1" >&2; exit 64; }
+      ;;
+    --no-build) build_mode="never" ;;
+    --rebuild)  build_mode="force" ;;
+    -h|--help)  usage ;;
+    -*)         echo "loop: unknown flag: $arg" >&2; usage ;;
+    *)
+      [ -z "$id" ] || { echo "loop: unexpected argument: $arg" >&2; usage; }
+      id="$arg"
+      ;;
+  esac
+done
+
+[ -n "$id" ] || usage
+# --no-build --rebuild together is a contradiction, not a precedence puzzle.
+case " $* " in
+  *" --no-build "*) case " $* " in *" --rebuild "*)
+    echo "loop: --no-build and --rebuild are mutually exclusive" >&2; exit 64 ;; esac ;;
+esac
+
+command -v claude >/dev/null 2>&1 || {
+  echo "loop: no 'claude' on PATH — the loop drives child claude -p sessions" >&2
+  exit 64
+}
+
+root="$(git rev-parse --show-toplevel 2>/dev/null)" || {
+  echo "loop: not inside a git checkout" >&2; exit 64; }
+cd "$root" || exit 64
+
+spec="specs/$id.md"
+[ -f "$spec" ] || {
+  echo "loop: no spec at $spec — run /spec $id first" >&2; exit 64; }
+
+reports="specs/reports"
+mkdir -p "$reports"
+verdict="$reports/$id.verdict.json"
+stamp="$reports/$id.built"
+log="$reports/$id.loop.log"
+
+: "${CLAUDE_FLAGS:=--permission-mode acceptEdits}"
+
+: >"$log"
+{
+  printf '# loop %s — max=%s build=%s\n' "$id" "$max" "$build_mode"
+  printf '# flags: %s\n' "$CLAUDE_FLAGS"
+} >>"$log"
+
+# --- one phase = one throwaway child session ---------------------------------
+# ALL child output is redirected into $log and never surfaces here: if the
+# parent re-imports the children's transcripts, the whole point is lost.
+# $CLAUDE_FLAGS is intentionally unquoted — it is a flag list, not one word.
+run_phase() {
+  cmd="$1"
+  printf '▶ /%-6s %-24s ' "$cmd" "$id"
+  printf '\n\n===== /%s %s =====\n' "$cmd" "$id" >>"$log"
+  # shellcheck disable=SC2086
+  if claude -p "/$cmd $id" $CLAUDE_FLAGS >>"$log" 2>&1; then
+    echo "ok"
+    return 0
+  fi
+  echo "fail"
+  return 1
+}
+
+# Scalar reads on a flat JSON object — no jq dependency (the pipeline ships no
+# runtime deps). Only `blocking` and `fingerprint` are ever read; both are
+# top-level scalars by construction of the verdict contract.
+json_num() { sed -n 's/.*"'"$2"'"[[:space:]]*:[[:space:]]*\([0-9][0-9]*\).*/\1/p' "$1" | head -n1; }
+json_str() { sed -n 's/.*"'"$2"'"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$1" | head -n1; }
+
+finish() { echo "$2"; exit "$1"; }
+
+# --- build -------------------------------------------------------------------
+# The stamp is the driver's own bookkeeping — /build knows nothing about it.
+case "$build_mode" in
+  force) do_build=1 ;;
+  never) do_build=0 ;;
+  auto)  [ -f "$stamp" ] && do_build=0 || do_build=1 ;;
+esac
+
+if [ "$do_build" -eq 1 ]; then
+  run_phase build || finish 2 "✗ /build failed — see $log"
+  date -u +%Y-%m-%dT%H:%M:%SZ >"$stamp"
+fi
+
+# --- review ⇄ fix ------------------------------------------------------------
+prev_fp=""
+pass=1
+while [ "$pass" -le "$max" ]; do
+  # Delete first: a stale verdict from the previous pass read as this pass's
+  # answer would end the loop on someone else's numbers.
+  rm -f "$verdict"
+  run_phase review || true          # exit status of the child is not the verdict
+
+  [ -f "$verdict" ] || finish 2 \
+    "✗ /review wrote no verdict (pass $pass) — see $log"
+
+  if grep -q '"aborted"' "$verdict"; then
+    finish 2 "✗ /review aborted on a red preflight — typecheck/lint/tests are broken, see $reports/$id.preflight.txt"
+  fi
+
+  blocking="$(json_num "$verdict" blocking)"
+  [ -n "$blocking" ] || finish 2 \
+    "✗ verdict has no usable 'blocking' count (pass $pass) — see $verdict"
+
+  [ "$blocking" -eq 0 ] && finish 0 \
+    "✓ clean after $pass review pass(es) — no blocking findings"
+
+  fp="$(json_str "$verdict" fingerprint)"
+  if [ -n "$fp" ] && [ "$fp" = "$prev_fp" ]; then
+    finish 3 "✗ non-convergent — the same $blocking blocking finding(s) survived a fix pass; see $verdict"
+  fi
+  prev_fp="$fp"
+
+  # Last pass: report and stop. A /fix here would leave unreviewed code behind.
+  [ "$pass" -eq "$max" ] && finish 1 \
+    "✗ ceiling — $blocking blocking finding(s) after $max pass(es); re-run with a higher --max"
+
+  run_phase fix || true
+
+  # Non-fatal by design: nothing to commit is a legitimate outcome (an agent
+  # that decided a finding needed no code change). The commit itself is the
+  # rollback point for the pass that just ran.
+  git add -A >>"$log" 2>&1
+  git commit -m "loop($id): fix pass $pass" >>"$log" 2>&1 || true
+
+  pass=$((pass + 1))
+done
+
+finish 1 "✗ ceiling — $max pass(es) exhausted"