cohorte 1.4.0 → 1.6.0

package/scripts/test-loop.mjs

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+// Behavioural tests for scripts/loop.sh — the autonomous /review ⇄ /fix driver.
+//
+// The driver is pure shell around two JSON files it does not write, so it is
+// testable end-to-end by putting a FAKE `claude` on PATH that produces those files
+// per phase. What is pinned here cannot be seen by any structural check:
+//
+//   · exit 4 — /build's readiness gate said NOT-READY, so no pass count helps
+//   · exit 0/3 leave the right TERMINAL status in the spec's front-matter, which is
+//     what makes an interrupted loop resumable (SCHEMA.md §Spec status)
+//   · the front-matter stamps are written with awk on every platform — a `sed -i`
+//     would pass on GNU and corrupt every spec on BSD/macOS
+//   · --resume continues at the recorded pass instead of re-paying passes 1..n-1
+//   · a spec with no front-matter still runs (the stamps are a silent no-op)
+//
+//   node scripts/test-loop.mjs
+
+import { mkdtempSync, writeFileSync, readFileSync, mkdirSync, chmodSync, existsSync } from "node:fs";
+import { execFileSync, spawnSync } from "node:child_process";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+const root = fileURLToPath(new URL("..", import.meta.url));
+const LOOP = join(root, "scripts/loop.sh");
+
+let failures = 0;
+const check = (name, cond, detail = "") => {
+  if (cond) console.log(`  ✓ ${name}`);
+  else { failures++; console.error(`  ✗ ${name}${detail ? ` — ${detail}` : ""}`); }
+};
+
+const FM = `---
+feature_id: feat-x
+title: Feat X
+status: frozen # draft → frozen → in-progress → in-review → shipped · blocked
+branch: feature/feat-x
+---
+
+# Feat X
+`;
+
+// A fake `claude`: reads the phase out of the `-p "/<cmd> <id>"` argument and
+// writes whatever the scenario says that phase produces. `$PHASES` is a
+// newline-separated script of `<cmd>:<what to write>` steps, consumed in order,
+// so a scenario can make pass 1 and pass 2 differ.
+const FAKE_CLAUDE = `#!/usr/bin/env bash
+set -u
+prompt=""
+while [ $# -gt 0 ]; do
+  case "$1" in -p) prompt="$2"; shift 2 ;; *) shift ;; esac
+done
+cmd="\${prompt%% *}"; cmd="\${cmd#/}"
+n=0; [ -f "$SCEN_DIR/count" ] && n=$(cat "$SCEN_DIR/count")
+n=$((n + 1)); echo "$n" >"$SCEN_DIR/count"
+step=$(sed -n "\${n}p" "$SCEN_DIR/phases")
+echo "fake claude: phase=$cmd step=$step"
+want="\${step%%:*}"; do_what="\${step#*:}"
+[ "$want" = "$cmd" ] || { echo "fake claude: expected /$want, got /$cmd" >&2; exit 9; }
+mkdir -p specs/reports
+case "$do_what" in
+  notready)
+    printf '{"id":"feat-x","phase":"readiness","ts":"t","verdict":"NOT-READY","gaps":["contract|POST /o|no success shape"],"surfaces":["backend"]}' \\
+      >specs/reports/feat-x.readiness.json ;;
+  ready)
+    printf '{"id":"feat-x","phase":"readiness","ts":"t","verdict":"READY","gaps":[],"surfaces":["backend"]}' \\
+      >specs/reports/feat-x.readiness.json ;;
+  clean)
+    printf '{"id":"feat-x","phase":"review","ts":"t","verdict":"SHIP","findings":2,"blocking":0,"deferred":2,"unreviewed":[],"fingerprint":""}' \\
+      >specs/reports/feat-x.verdict.json ;;
+  deadreviewer)
+    printf '{"id":"feat-x","phase":"review","ts":"t","verdict":"REVISE","findings":0,"blocking":0,"deferred":0,"unreviewed":["backend"],"fingerprint":""}' \\
+      >specs/reports/feat-x.verdict.json ;;
+  deadimplementer)
+    printf '{"id":"feat-x","phase":"readiness","ts":"t","verdict":"READY","gaps":[],"surfaces":["backend"]}' \\
+      >specs/reports/feat-x.readiness.json
+    printf '{"id":"feat-x","phase":"build","ts":"t","surfaces":{"backend":"dead","frontend":"ok"},"dead":["backend"]}' \\
+      >specs/reports/feat-x.build.json ;;
+  blocking)
+    printf '{"id":"feat-x","phase":"review","ts":"t","verdict":"REVISE","findings":3,"blocking":2,"deferred":1,"fingerprint":"aaaa1111bbbb2222"}' \\
+      >specs/reports/feat-x.verdict.json ;;
+  noop) : ;;
+esac
+exit 0
+`;
+
+// One scratch repo per scenario: a git checkout (loop.sh cds to its toplevel), a
+// spec, the fake claude on PATH, and the phase script it plays out.
+function scenario(phases, { frontmatter = FM } = {}) {
+  const dir = mkdtempSync(join(tmpdir(), "cohorte-loop-"));
+  const git = (...a) => execFileSync("git", ["-C", dir, ...a], { stdio: "ignore" });
+  git("init", "-q");
+  git("config", "user.email", "t@t.t");
+  git("config", "user.name", "t");
+  mkdirSync(join(dir, "specs/reports"), { recursive: true });
+  writeFileSync(join(dir, "specs/feat-x.md"), frontmatter);
+  git("add", "-A");
+  git("commit", "-qm", "init");
+
+  const bin = join(dir, "bin");
+  mkdirSync(bin);
+  writeFileSync(join(dir, "phases"), phases.join("\n") + "\n");
+  writeFileSync(join(bin, "claude"), FAKE_CLAUDE);
+  chmodSync(join(bin, "claude"), 0o755);
+  return { dir, bin };
+}
+
+function runLoop({ dir, bin }, args) {
+  const r = spawnSync("bash", [LOOP, ...args], {
+    cwd: dir,
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      PATH: `${bin}:${process.env.PATH}`,
+      SCEN_DIR: dir,
+      CLAUDE_FLAGS: "--permission-mode acceptEdits",
+      GIT_AUTHOR_NAME: "t", GIT_AUTHOR_EMAIL: "t@t.t",
+      GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "t@t.t",
+    },
+  });
+  const spec = readFileSync(join(dir, "specs/feat-x.md"), "utf8");
+  const fm = k => {
+    const m = spec.match(new RegExp(`^${k}:\\s*([^#\\n]*)`, "m"));
+    return m ? m[1].trim() : null;
+  };
+  return { code: r.status, out: `${r.stdout}${r.stderr}`, spec, fm };
+}
+
+console.log("loop.sh — readiness gate");
+{
+  const s = scenario(["build:notready"]);
+  const r = runLoop(s, ["feat-x"]);
+  check("NOT-READY ⇒ exit 4, not 2", r.code === 4, `got ${r.code}: ${r.out.trim().split("\n").pop()}`);
+  check("NOT-READY ⇒ says the spec is not implementable",
+    /not implementable/i.test(r.out), r.out.trim().split("\n").pop());
+  check("NOT-READY ⇒ points at /spec", /\/spec feat-x/.test(r.out));
+  check("NOT-READY ⇒ spec left blocked", r.fm("status") === "blocked", r.fm("status"));
+  check("NOT-READY ⇒ no review ran (the gate is the point)", !/phase=review/.test(r.out));
+  check("NOT-READY ⇒ the build stamp is NOT written",
+    !existsSync(join(s.dir, "specs/reports/feat-x.built")));
+}
+
+console.log("loop.sh — clean run");
+{
+  const s = scenario(["build:ready", "review:clean"]);
+  const r = runLoop(s, ["feat-x"]);
+  check("clean ⇒ exit 0", r.code === 0, `got ${r.code}: ${r.out}`);
+  check("clean ⇒ status in-review (ready to /ship)", r.fm("status") === "in-review", r.fm("status"));
+  check("clean ⇒ loop state cleared", r.fm("loop_pass") === "0" && r.fm("loop_phase") === "done",
+    `${r.fm("loop_pass")}/${r.fm("loop_phase")}`);
+  check("clean ⇒ the deferred count is named, not dropped",
+    /2 deferred finding\(s\) parked/.test(r.out), r.out.trim().split("\n").pop());
+  check("clean ⇒ the status comment survives the awk rewrite",
+    /^status: in-review # draft/m.test(r.spec), r.spec.split("\n")[3]);
+}
+
+console.log("loop.sh — a dead subagent is never a clean result");
+{
+  // A dead implementer: /build finishes fine having built one surface of two. Reviewing
+  // that would spend N reviewers auditing a half-built feature and report its holes as
+  // findings to fix — the wrong diagnosis at the wrong price.
+  const s = scenario(["build:deadimplementer"]);
+  const r = runLoop(s, ["feat-x"]);
+  check("dead implementer ⇒ exit 2, not a review pass", r.code === 2, `got ${r.code}: ${r.out}`);
+  check("dead implementer ⇒ no reviewer was spawned", !/phase=review/.test(r.out));
+  check("dead implementer ⇒ names the cause", /implementer died/.test(r.out),
+    r.out.trim().split("\n").pop());
+  check("dead implementer ⇒ spec left blocked", r.fm("status") === "blocked", r.fm("status"));
+}
+{
+  // THE dangerous one: blocking == 0 because the only reviewer that could have found
+  // something never answered. Exiting 0 here would report "clean" about unread code and
+  // send the human to /ship.
+  const s = scenario(["build:ready", "review:deadreviewer"]);
+  const r = runLoop(s, ["feat-x"]);
+  check("dead reviewer + blocking 0 ⇒ NOT exit 0", r.code !== 0, `got ${r.code}: ${r.out}`);
+  check("dead reviewer ⇒ exit 2 (no usable verdict)", r.code === 2, `got ${r.code}`);
+  check("dead reviewer ⇒ names the unreviewed surface", /reviewer died/.test(r.out),
+    r.out.trim().split("\n").pop());
+  check("dead reviewer ⇒ never says clean", !/✓ clean/.test(r.out));
+  check("dead reviewer ⇒ spec is NOT left in-review", r.fm("status") === "blocked", r.fm("status"));
+}
+
+console.log("loop.sh — non-convergent + resume");
+{
+  const s = scenario(["build:ready", "review:blocking", "fix:noop", "review:blocking"]);
+  const r = runLoop(s, ["feat-x", "--max=4"]);
+  check("same fingerprint twice ⇒ exit 3", r.code === 3, `got ${r.code}: ${r.out}`);
+  check("non-convergent ⇒ status blocked", r.fm("status") === "blocked", r.fm("status"));
+  check("non-convergent ⇒ the pass it reached is recorded (resume anchor)",
+    r.fm("loop_pass") === "2", r.fm("loop_pass"));
+  check("non-convergent ⇒ the phase is recorded", r.fm("loop_phase") === "review", r.fm("loop_phase"));
+
+  // Resume: the recorded pass is where it picks up — passes 1..n-1 are not re-paid.
+  writeFileSync(join(s.dir, "count"), "0");
+  writeFileSync(join(s.dir, "phases"), "review:clean\n");
+  const r2 = runLoop(s, ["feat-x", "--max=4", "--resume"]);
+  check("--resume ⇒ announces the pass it continues from",
+    /resuming at review pass 2/.test(r2.out), r2.out.trim().split("\n")[0]);
+  check("--resume ⇒ skips the build (the stamp is there)", !/phase=build/.test(r2.out));
+  check("--resume ⇒ finishes clean from there", r2.code === 0, `got ${r2.code}: ${r2.out}`);
+  check("--resume ⇒ reports the resumed pass count, not 1",
+    /after 2 review pass\(es\)/.test(r2.out), r2.out.trim().split("\n").pop());
+}
+{
+  const s = scenario(["review:clean"]);
+  // A resume anchor past the ceiling is a usage error, not a silent restart at 1.
+  writeFileSync(join(s.dir, "specs/feat-x.md"), FM.replace("branch:", "loop_pass: 9\nbranch:"));
+  const r = runLoop(s, ["feat-x", "--max=3", "--resume"]);
+  check("--resume past --max ⇒ exit 64 with the reason", r.code === 64 && /raise --max/.test(r.out),
+    `${r.code}: ${r.out.trim()}`);
+}
+
+console.log("loop.sh — a spec with no front-matter still runs");
+{
+  const s = scenario(["build:ready", "review:clean"], { frontmatter: "# Feat X\n\nno front-matter\n" });
+  const r = runLoop(s, ["feat-x"]);
+  check("no front-matter ⇒ still exits 0 (stamps are a silent no-op)", r.code === 0,
+    `got ${r.code}: ${r.out}`);
+  check("no front-matter ⇒ the spec is left untouched",
+    r.spec === "# Feat X\n\nno front-matter\n", JSON.stringify(r.spec));
+  check("no front-matter ⇒ no stray temp file",
+    !existsSync(join(s.dir, "specs/feat-x.md.loop.tmp")));
+}
+
+if (failures) { console.error(`\ntest-loop: ${failures} failure(s)`); process.exit(1); }
+console.log("\ntest-loop: OK");

package/scripts/test-metrics.mjs

@@ -82,6 +82,13 @@ const lines = [
   // Case 8: a slash token that is not a command must not invent one.
   user(1800, 'look at the /usr/local/share directory and report what you find there'),
   assistant('m7', 1805, 'claude-opus-5', { input_tokens: 0, output_tokens: 10 }),
+  // Case 9: a long prompt that merely DISCUSSES a command is not an invocation of it.
+  // Without the length gate, writing about /review bills the conversation to /review —
+  // which is what happened in cohorte's own repo while the pipeline was being designed.
+  user(2400, 'I want to talk through how /review behaves when a surface has no findings at '
+    + 'all, because the verdict logic there is what produced the false green we saw last week '
+    + 'and I am not convinced the fix covers the case where every reviewer dies at once.'),
+  assistant('m8', 2405, 'claude-opus-5', { input_tokens: 0, output_tokens: 20 }),
 ];
 fs.writeFileSync(path.join(projectDir, `${SESSION}.jsonl`),
   lines.map((l) => JSON.stringify(l)).join('\n') + '\n');
@@ -107,18 +114,20 @@ const chat = out.commands.find((c) => c.command === '(chat)');
 const review = out.commands.find((c) => c.command === '/review');
 
 console.log('test-metrics');
-check('the mid-command task-notification did not split the run', out.totals.runs, 4);
+check('the mid-command task-notification did not split the run', out.totals.runs, 5);
 check('/build is one run, not three', build.runs, 1);
 check('duplicate lines of one response are billed once', build.tokens.output, 1000 + 500 + 2000);
 check('the <synthetic> message contributed no tokens', build.tokens.output < 999999, true);
 check('cache-write tokens are kept on their own tier', build.tokens.cacheWrite5m, 1000);
 check('cache-read tokens are kept on their own tier', build.tokens.cacheRead, 10000);
 check('the subagent was attributed to the command that spawned it', build.agents.total, 1);
-check('the second prompt is a separate (chat) run', chat.runs, 2);
+check('the second prompt is a separate (chat) run', chat.runs, 3);
 check('a command named inside prose is attributed to that command', review && review.runs, 1);
 check('a short steer continues the run instead of opening a new one', review.continuations, 1);
 check('the continued turn counts toward the command it continued', review.tokens.output, 60 + 70);
-check('a non-command slash token does not invent a command', chat.tokens.output, 40 + 10);
+check('a non-command slash token does not invent a command', chat.tokens.output, 40 + 10 + 20);
+check('a long prompt that discusses a command is not counted as running it',
+  review.runs, 1);
 
 // opus-5 $5 in / $25 out per MTok; 5m cache write 1.25x input, cache read 0.1x input.
 //   m1  100*5 + 1000*25 + 1000*6.25 + 10000*0.5 = 36750

package/scripts/test-workflows.mjs

@@ -146,6 +146,34 @@ console.log("review.js");
   ]));
   check("SHIP + only LOW ⇒ next is /ship", String(result.next).startsWith("/ship"), result.next);
 }
+{
+  // Deferred findings are real but out of the feature's scope: they must be
+  // counted and routed to the backlog, yet move NEITHER the verdict nor `clean`.
+  // Both halves matter — a deferred item that blocks costs a fix loop it was
+  // deferred out of, and one that is dropped is the leak the section exists to close.
+  const deferred = [{
+    severity: "HIGH", file: "apps/api/legacy.ts", line: 9, kind: "quality",
+    problem: "p", fix: "f", outOfScope: "predates this feature; diff never touched it",
+  }];
+  let stagePrompt = "";
+  const { result } = await run("review.js", (prompt, opts) => {
+    const label = opts.label || "";
+    if (label.startsWith("review:")) return { verdict: "SHIP", findings: [], deferred };
+    if (label === "stage-report") { stagePrompt = prompt; return "done"; }
+    return replier(BASE_REVIEW)(prompt, opts);
+  });
+  check("deferred-only ⇒ verdict still SHIP", result.verdict === "SHIP", `got ${result.verdict}`);
+  check("deferred-only ⇒ next is /ship (not a fix loop)",
+    String(result.next).startsWith("/ship"), result.next);
+  check("deferred are counted (both surfaces)", result.deferred === 2, `got ${result.deferred}`);
+  check("deferred stay out of the severity counts",
+    Object.values(result.counts).every(n => n === 0), JSON.stringify(result.counts));
+  check("deferred are routed to the refactor backlog",
+    /refactor-backlog\.md/.test(stagePrompt) && /deferred:feat-x/.test(stagePrompt),
+    stagePrompt.slice(0, 200));
+  check("deferred are never cross-checked (no verify agent spawned)",
+    !/verify:/.test(String(result.criticals)) && result.refutedByCrossCheck === 0);
+}
 {
   const { result } = await run("review.js", replier([
     ["preflight", { pass: false, tail: "boom" }], ...BASE_REVIEW,

package/scripts/validate-core.mjs

@@ -22,12 +22,27 @@ const frontmatter = (text) => {
 // Mechanical commands must pin model: sonnet (otherwise the lead's
 // orchestration turn silently bills at the session model — Opus/Fable).
 // Interactive commands must stay unpinned (they inherit on purpose).
-const PINNED = ["build", "review", "fix", "smoke", "ship", "audit",
-  "refactor", "doctor", "align-ds", "update-pipeline"];
+const PINNED = ["build", "review", "fix", "ship", "audit",
+  "refactor", "doctor", "align-ds", "update-pipeline", "drive"];
 const UNPINNED = ["brainstorm", "spec", "init-pipeline"];
 
+// Names Claude Code itself claims. A core command that collides is not overridden —
+// it is SHADOWED: the built-in answers the slash, our command file is never read, and
+// the session confidently reports on a run that never happened. That is what `/loop`
+// did (Claude Code's own `/loop` runs a prompt on an interval), invisible until a user
+// noticed the driver had never started. `/loop` is here so the 1.6.0 rename to
+// `/drive` can never be quietly reverted.
+// Watchlist, not yet enforced because the collision is unproven: `doctor` (Claude Code
+// has its own `/doctor`) — if a typed `/doctor` ever stops reaching the pipeline's, add
+// it here and rename.
+const RESERVED = ["loop", "clear", "compact", "cost", "help", "config",
+  "init", "run", "schedule", "simplify", "review-pr"];
+
 for (const f of readdirSync(join(root, "core/commands"))) {
   const path = `core/commands/${f}`;
+  if (RESERVED.includes(f.replace(/\.md$/, "")))
+    fail(path, `command name collides with a Claude Code built-in — it would be SHADOWED ` +
+      `(the built-in answers the slash and this file is never read); rename it`);
   const fm = frontmatter(read(path));
   if (!fm) { fail(path, "missing or malformed YAML frontmatter"); continue; }
   if (!/^description:\s*\S/m.test(fm)) fail(path, "frontmatter lacks a description");
@@ -43,7 +58,7 @@ for (const f of readdirSync(join(root, "core/commands"))) {
 // Every non-template agent needs name/tools/model, and must be shipped by
 // both installers (a new agent that install.sh doesn't copy never reaches
 // a global install — the exact bug that motivated this check).
-const AGENT_MODEL = { review: "sonnet", release: "haiku", smoke: "sonnet",
+const AGENT_MODEL = { review: "sonnet", release: "haiku",
   "profile-reader": "haiku" };
 const installSh = read("install.sh");
 const installPs1 = read("install.ps1");
@@ -90,7 +105,7 @@ for (const path of allDocs) {
   }
   for (const m of text.matchAll(/subagent_type:\s*(?:`|)([a-z-]+)(?:`|)/g)) {
     const t = m[1];
-    if (["review", "release", "smoke", "profile-reader"].includes(t)) continue;
+    if (["review", "release", "profile-reader"].includes(t)) continue;
     if (t.startsWith("<")) continue; // <surface.agent> placeholder
     if (!existsSync(join(root, "core/agents", `${t}.md`)))
       fail(path, `dispatches subagent_type ${t} with no core/agents/${t}.md`);
@@ -115,9 +130,9 @@ if (!existsSync(steps) || readdirSync(steps).length === 0)
 
 // ── telemetry coverage ──────────────────────────────────────────────────────
 // The funnel is only readable if every one of its stages pings — a single missing
-// one silently truncates it (that is how /smoke, /review and /fix went unreported
+// one silently truncates it (that is how /review and /fix went unreported
 // until 1.2.3). The phase list here must match SCHEMA.md §Telemetry's table.
-const FUNNEL = ["brainstorm", "spec", "build", "smoke", "review", "fix", "ship"];
+const FUNNEL = ["brainstorm", "spec", "build", "review", "fix", "ship"];
 for (const c of FUNNEL)
   if (!/usage ping/i.test(read(`core/commands/${c}.md`)))
     fail(`core/commands/${c}.md`, "funnel command with no usage ping — breaks the telemetry funnel");

package/core/agents/smoke.md

@@ -1,63 +0,0 @@
----
-name: smoke
-description: Executes the end-to-end smoke run for one feature in its worktree — infra up, migrations, contract endpoints, key UI flows, visual check vs design — then stages the SMOKE REPORT. Dispatched by /smoke. Observes honestly, never fixes anything.
-tools: Read, Write, Grep, Glob, Bash, DesignSync
-model: sonnet
----
-
-You are the **smoke** agent for one feature. You actually run the built feature — `/review` audits
-code read-only; nobody has executed it yet. You verify it *works*; you never fix it (failures go
-through `/fix`). Observe honestly: report what happened, not what should have happened.
-
-> **First action, always:** read `PIPELINE.md` §`pipeline-profile`: `commands` (migrate/dev),
-> `isolation` (worktree, slot ports, db), `contract`, `design`, `surfaces` — then the spec
-> `specs/<id>.md` (§5 contract, §8 flows, §9 acceptance).
-
-## Your inputs (supplied at dispatch — you have no memory)
-
-1. The feature id and spec path `specs/<id>.md`.
-2. The contract path `<contract.path>/<id>.<ext>`.
-3. The checkout to work in: the worktree path + slot ports/db, or the main checkout on the feature branch.
-
-## Keep your own context lean
-
-Redirect every bulky output to a file and inspect it with `grep`/`jq` — never print full curl bodies,
-server logs, or poll loops into your transcript. `curl -s … -o /tmp/resp.json -w '%{http_code}'` then
-assert on the pieces you need.
-
-## 1. Bring the feature up
-
-- Work in the checkout your dispatch names. Infra as needed: the compose stack if one is declared
-  (the gate will ask — that's expected), then `commands.migrate`, then `commands.dev` **in the
-  background**. Wait for ready (poll the ports), don't assume.
-
-## 2. Exercise the contract (the real server, not the tests)
-
-- Hit a representative set of spec §5 endpoints with `curl`: every route domain, every auth level,
-  at least one error case per class (validation `422`, unauthenticated `401`, wrong-role `403`,
-  conflict `409`). Compare status + response envelope against the contract.
-- If `rbac.enabled`: verify at least one denial per role boundary the spec declares.
-- A mismatch is a FAIL entry with the exact command, expected, and actual — precise enough for a
-  stateless `/fix` agent.
-
-## 3. Exercise the UI (only if a touched surface has `uses_design`)
-
-- Drive the spec §8 flows against the running app, **mobile viewport first** (375px), then desktop.
-- If a browser/screenshot tool is available (a project driver, playwright, an agent browser), capture
-  each §8 screen and compare against the feature's design pages: each `design_files` entry is a full
-  `https://claude.ai/design/p/<projectId>?file=<file>` link — extract its `<projectId>` (the `/p/…`
-  segment) + `<file>` (the `?file=` query) and fetch read-only via `DesignSync get_file(<projectId>,
-  <file>)`. Compare layout, states (empty/loading/error/suppressed…), copy language. Note deviations.
-- No browser tooling available ⇒ **say so and skip the visual diff** — never claim a visual check
-  you didn't perform.
-
-## 4. Stage the SMOKE REPORT, tear down, return
-
-- One line per check: ✅/❌ · what was exercised · (on ❌) command → expected vs actual.
-- **Write the full report to `specs/reports/<id>.md`** (overwrite) — the same gitignored buffer
-  `/review` uses, so a `/fix` after a `/clear` still has the failures.
-- Tear down what you started (kill the dev server); leave shared infra as you found it.
-- **Your return to the lead is ONLY:** the verdict line (`PASS` / `FAIL:<n>`), **at most 10 ❌
-  lines** — one line each (`❌ <flow/endpoint> · expected <x> got <y>`), no command output, no code
-  or body excerpts; more than 10 ⇒ keep the 10 most severe and add `+<n> more — see the report` —
-  and `Full report: specs/reports/<id>.md`. No logs, no bodies, no screenshots.

package/core/commands/smoke.md

@@ -1,55 +0,0 @@
----
-model: sonnet
-description: Exercise the built feature end-to-end in its worktree — infra up, migrations, contract endpoints, key UI flows, visual check vs design — before /review.
-argument-hint: <feature_id>
----
-
-You are the **lead**. Dispatch the smoke run for feature **$ARGUMENTS** — the `smoke` agent actually
-runs it so the bulky output (curl bodies, server logs, screenshots, design payloads) never enters
-your own context, which is re-sent every turn.
-
-> Read `PIPELINE.md` §`pipeline-profile`: `isolation` (worktree, slot ports, db), `contract.path`
-> and `commands`. _Skip the re-read if it's already in your context this session and unmodified since._
->
-> **Kanban:** none here — `/review` owns the → **Review** move (running both duplicated it).
-
-## 0. Deterministic pre-flight — no agents while red
-
-Same gate as `/review` §0, run **in the feature's checkout** (§1 resolves it — resolve first, then
-preflight): `<core>/pipeline/scripts/preflight.sh specs/reports/$ARGUMENTS.preflight.txt
-"<commands.typecheck>" "<commands.lint_quiet, else lint>" "<commands.test_quiet, else test>"`.
-Non-zero exit ⇒ the raw last-40 lines were already printed — **STOP, relay them verbatim, spawn NO
-agent**: booting infra to smoke-test code that doesn't compile wastes the whole run. Zero exit ⇒
-the `.claude/preflight.ok` stamp lets the gate hook pass your `smoke` dispatch. Script absent
-(older core) ⇒ run the commands yourself redirected to the same file, aborting on the first failure.
-Note the epoch (`date +%s`) in the same call — §3's metrics line needs it.
-
-## 1. Resolve the checkout
-
-With `isolation.enabled`: the sibling worktree (`../<slug>-$ARGUMENTS`, its slot's ports + db from
-`.worktrees/slots.tsv`); otherwise the main checkout on the feature branch.
-
-## 2. Dispatch ONE `smoke` agent
-
-Keep the prompt byte-identical across features except the variable block at the END (prompt-cache
-prefix):
-
-> `subagent_type: smoke` — "Smoke-test one feature. Read `PIPELINE.md` first. Bring it up, exercise
-> the contract and the §8 UI flows, stage the full SMOKE REPORT to the report buffer, tear down, and
-> return only the capped verdict your agent instructions define (verdict + ❌ lines, no logs). —
-> Variable slots: feature `$ARGUMENTS` · spec: `specs/$ARGUMENTS.md` · contract:
-> `<contract.path>/$ARGUMENTS.<ext>` · report: `specs/reports/$ARGUMENTS.md` · checkout: `<worktree
-> path or main checkout>` · ports/db: `<slot info, or defaults>`."
-
-The gate hooks fire on the agent's Bash calls too — compose/migrate confirmations still reach the
-human; that's expected.
-
-## 3. Relay the verdict
-
-- Print the agent's return as-is (verdict + ❌ lines + report path) — it is already minimal.
-- Append ONE metrics line to `pipeline-metrics.jsonl` (main-checkout path + rules in `/build` §4,
-  `phase: "smoke"`), chaining the opt-in usage ping in the same Bash call (results = `PASS` or
-  `FAIL:<n>` failing flows).
-- **PASS** → tell the human to run `/review $ARGUMENTS`. **FAIL** → the failures are findings: feed
-  them to `/fix $ARGUMENTS`, re-run `/smoke` after. Either way the report is on disk —
-  **recommend a `/clear`** before the next command.