cohorte 1.3.4 → 1.4.0

package/scripts/test-metrics.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+// test-metrics.mjs — end-to-end checks for scripts/metrics/collect.mjs.
+//
+// Builds a throwaway repo plus a synthetic ~/.claude/projects transcript, runs the real
+// collector against it via --json, and asserts the numbers. The cases are the ones that
+// silently produce plausible-but-wrong output rather than crashing:
+//
+//   1. one API response written as several transcript lines, each repeating `usage`
+//   2. a <task-notification> arriving mid-command (must not split the run)
+//   3. subagent spend, which lives in a separate file tree
+//   4. <synthetic> harness messages, which carry usage but cost nothing
+//   5. the cache-tier pricing arithmetic itself
+//
+// Run: node scripts/test-metrics.mjs
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const COLLECT = path.join(HERE, 'metrics', 'collect.mjs');
+
+let failures = 0;
+const ok = (label) => console.log(`  ✓ ${label}`);
+function check(label, actual, expected) {
+  const a = JSON.stringify(actual), e = JSON.stringify(expected);
+  if (a === e) return ok(label);
+  failures += 1;
+  console.log(`  ✗ ${label}\n      expected ${e}\n      actual   ${a}`);
+}
+
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'cohorte-metrics-'));
+const repo = path.join(tmp, 'repo');
+const cfg = path.join(tmp, 'claude');
+const SESSION = 'sess-test-0001';
+const projectDir = path.join(cfg, 'projects', 'test-slug');
+fs.mkdirSync(path.join(projectDir, SESSION, 'subagents'), { recursive: true });
+fs.mkdirSync(repo, { recursive: true });
+execFileSync('git', ['init', '-q'], { cwd: repo, stdio: 'ignore' });
+
+const T0 = Date.parse('2026-07-30T10:00:00.000Z');
+const at = (s) => new Date(T0 + s * 1000).toISOString();
+
+const assistant = (id, tsS, model, usage, content = [{ type: 'text', text: 'x' }]) => ({
+  type: 'assistant', timestamp: at(tsS), cwd: repo, sessionId: SESSION,
+  message: { id, model, content, usage },
+});
+const user = (tsS, text) => ({
+  type: 'user', timestamp: at(tsS), cwd: repo, sessionId: SESSION,
+  message: { role: 'user', content: text },
+});
+
+const usageOpus = {
+  input_tokens: 100, output_tokens: 1000,
+  cache_creation_input_tokens: 1000, cache_read_input_tokens: 10000,
+  cache_creation: { ephemeral_5m_input_tokens: 1000, ephemeral_1h_input_tokens: 0 },
+};
+
+const lines = [
+  user(0, '<command-message>build</command-message>\n<command-name>/build</command-name>'),
+  // Case 1: one response, three lines, identical usage on each. Only one should be billed.
+  assistant('m1', 5, 'claude-opus-5', usageOpus, [{ type: 'thinking', thinking: '...' }]),
+  assistant('m1', 5, 'claude-opus-5', usageOpus, [{ type: 'text', text: 'hello' }]),
+  assistant('m1', 6, 'claude-opus-5', usageOpus, [{ type: 'tool_use', id: 'toolu_A', name: 'Task', input: {} }]),
+  // Case 2: a background agent finished mid-run. This is not the human starting anything.
+  user(10, '<task-notification>\n<task-id>a1</task-id>\n</task-notification>'),
+  // Case 4: harness-authored message, has usage, costs nothing.
+  assistant('m2', 12, '<synthetic>', { input_tokens: 0, output_tokens: 999999 }),
+  assistant('m3', 20, 'claude-opus-5', { input_tokens: 0, output_tokens: 500 }),
+  // A second, genuinely separate run — long enough not to read as a steering turn.
+  user(600, 'unrelated question about the repository layout and its conventions'),
+  assistant('m4', 605, 'claude-opus-5', { input_tokens: 0, output_tokens: 40 }),
+  // Case 6: a command named inside ordinary prose. The harness emits no <command-name>
+  // for this, but it is the way commands actually get invoked in practice.
+  user(1200, 'move on branding-ramp and /review'),
+  assistant('m5', 1205, 'claude-opus-5', { input_tokens: 0, output_tokens: 60 }),
+  // Case 7: a short steer continues the /review rather than opening an anonymous run.
+  user(1260, 'continue'),
+  assistant('m6', 1265, 'claude-opus-5', { input_tokens: 0, output_tokens: 70 }),
+  // 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 }),
+];
+fs.writeFileSync(path.join(projectDir, `${SESSION}.jsonl`),
+  lines.map((l) => JSON.stringify(l)).join('\n') + '\n');
+
+// Case 3: subagent spend, linked back to /build by the Task tool_use id.
+const agentDir = path.join(projectDir, SESSION, 'subagents');
+fs.writeFileSync(path.join(agentDir, 'agent-a1.meta.json'),
+  JSON.stringify({ agentType: 'core', description: 'Build core surface', toolUseId: 'toolu_A', spawnDepth: 1 }));
+fs.writeFileSync(path.join(agentDir, 'agent-a1.jsonl'),
+  JSON.stringify(assistant('s1', 8, 'claude-sonnet-5', { input_tokens: 0, output_tokens: 2000 })) + '\n');
+
+const run = spawnSync(process.execPath, [COLLECT, repo, '--json', '--runs'], {
+  encoding: 'utf8',
+  env: { ...process.env, CLAUDE_CONFIG_DIR: cfg },
+});
+if (run.status !== 0) {
+  console.error('collector failed:\n' + (run.stderr || run.stdout));
+  process.exit(1);
+}
+const out = JSON.parse(run.stdout);
+const build = out.commands.find((c) => c.command === '/build');
+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('/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('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);
+
+// 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
+//   m3  500*25                                   = 12500
+//   s1  sonnet-5 2000*15                         = 30000   (subagent)
+check('cost sums the cache tiers at their own rates', Number(build.cost.total.toFixed(6)), 0.07925);
+check('the unpriced list stays empty for known models', build.unpriced, []);
+
+const detail = out.runs.find((r) => r.command === '/build');
+check('per-run detail carries the subagent', detail.agents.map((a) => a.type), ['core']);
+
+fs.rmSync(tmp, { recursive: true, force: true });
+console.log(failures ? `\ntest-metrics: ${failures} FAILED` : '\ntest-metrics: OK');
+process.exit(failures ? 1 : 0);

package/scripts/test-workflows.mjs

@@ -8,9 +8,8 @@
 //
 // This exists because of one specific failure mode: agent() resolves to `null`
 // when a subagent dies, and a dead reviewer produces zero findings — which is
-// byte-identical to a clean surface. Both review.js and cycle.js scored that as
-// SHIP, and cycle.js went on to tick the DoD and stamp the freshness gate over
-// code no reviewer had read. A unit test is the only thing that catches it: the
+// byte-identical to a clean surface. review.js scored that as SHIP over code no
+// reviewer had read. A unit test is the only thing that catches it: the
 // structural checks in validate-core.mjs cannot see verdict logic.
 //
 //   node scripts/test-workflows.mjs
@@ -99,17 +98,6 @@ const BASE_REVIEW = [
   ["stage-report", "done"],
 ];
 
-const BASE_CYCLE = [
-  ["profile", PROFILE],
-  ["ready", { frozen: true, gaps: [], designLinks: "none" }],
-  ["preflight", { pass: true }],
-  ["stage-diff", { surfaces: TOUCHED }],
-  ["build:", "handoff ok"],
-  ["fix:", "handoff ok"],
-  ["close", "done"],
-];
-
-// ── review.js ────────────────────────────────────────────────────────────────
 console.log("review.js");
 {
   const { result } = await run("review.js", replier([
@@ -172,165 +160,74 @@ console.log("review.js");
     !calls.some(c => c.startsWith("review:")), calls.join(","));
 }
 
-// ── cycle.js ─────────────────────────────────────────────────────────────────
-console.log("cycle.js");
-{
-  const { result } = await run("cycle.js", replier([
-    ["review:", { verdict: "SHIP", findings: [] }], ...BASE_CYCLE,
-  ]));
-  check("clean run, smoke off ⇒ SHIP-READY", result.outcome === "SHIP-READY", `got ${result.outcome}`);
-  check("smoke off ⇒ smoke: SKIPPED", result.smoke === "SKIPPED", result.smoke);
-  check("smoke off ⇒ next warns nobody ran the code",
-    /\/smoke/.test(result.next), result.next);
-  check("clean run ⇒ no questions", (result.questions || []).length === 0, JSON.stringify(result.questions));
-}
-{
-  const { result } = await run("cycle.js", replier([
-    ["smoke", { pass: true, failures: [] }],
-    ["review:", { verdict: "SHIP", findings: [] }], ...BASE_CYCLE,
-  ]), { feature: "feat-x", smoke: true });
-  check("clean run, smoke on ⇒ SHIP-READY", result.outcome === "SHIP-READY", `got ${result.outcome}`);
-  check("smoke on ⇒ smoke: PASS", result.smoke === "PASS", result.smoke);
-  check("smoke on + clean ⇒ next is a straight /ship",
-    /straight shot/.test(result.next), result.next);
-}
+// ── args normalisation ───────────────────────────────────────────────────────
+// The runtime passes `args` through verbatim, so a caller that JSON-encodes it
+// hands the script a string. That string used to become the feature id itself —
+// which is how a report was written to `specs/reports/{"feature": "x"}.md`.
+console.log("args");
 {
-  // THE regression, cycle-side: dead reviewers used to exit SHIP-READY, which
-  // ticks the DoD and stamps the freshness gate.
-  const { result } = await run("cycle.js", replier([
-    ["review:", null], ...BASE_CYCLE,
-  ]), { feature: "feat-x", maxRounds: 2 });
-  check("all reviewers dead ⇒ not SHIP-READY", result.outcome !== "SHIP-READY", `got ${result.outcome}`);
-  check("all reviewers dead ⇒ verdict not SHIP", result.verdict !== "SHIP", result.verdict);
-  check("all reviewers dead ⇒ surfaces reported",
-    (result.unreviewedSurfaces || []).length === 2, JSON.stringify(result.unreviewedSurfaces));
-  check("all reviewers dead ⇒ a question names them",
-    (result.questions || []).some(q => /not reviewed/i.test(q)), JSON.stringify(result.questions));
-}
-{
-  // …and it must retry the review round rather than dispatching an empty fix round.
-  const { calls } = await run("cycle.js", replier([
-    ["review:", null], ...BASE_CYCLE,
-  ]), { feature: "feat-x", maxRounds: 3 });
-  check("dead reviewers ⇒ review retried across rounds",
-    calls.filter(c => c.startsWith("review:")).length > 2,
-    `review calls: ${calls.filter(c => c.startsWith("review:")).length}`);
-  check("dead reviewers ⇒ no empty fix round dispatched",
-    !calls.some(c => c.startsWith("fix:")), calls.join(","));
-}
-{
-  const { result } = await run("cycle.js", replier([
-    ["ready", { frozen: false, gaps: ["status is draft"], designLinks: "none" }], ...BASE_CYCLE,
-  ]));
-  check("unfrozen spec ⇒ NOT-READY", result.outcome === "NOT-READY", `got ${result.outcome}`);
-  check("unfrozen spec ⇒ the gap is in questions",
-    (result.questions || []).some(q => /draft/.test(q)), JSON.stringify(result.questions));
-}
-{
-  const { result } = await run("cycle.js", replier([
-    ["smoke", { pass: false, failures: ["❌ POST /x · expected 201 got 500 · apps/api/a.ts"] }],
-    ["review:", { verdict: "SHIP", findings: [] }], ...BASE_CYCLE,
-  ]), { feature: "feat-x", smoke: true, maxRounds: 1 });
-  check("smoke on + FAIL ⇒ not SHIP-READY", result.outcome !== "SHIP-READY", `got ${result.outcome}`);
-  check("smoke on + FAIL ⇒ smoke: FAIL", result.smoke === "FAIL", result.smoke);
-}
-{
-  // A finding in round 1 that the fix clears must let round 2 exit clean.
-  let round = 0;
-  const { result } = await run("cycle.js", (prompt, opts) => {
-    const l = opts.label || "";
-    if (l.startsWith("review:")) {
-      round++;
-      return round <= 2 ? { verdict: "REVISE", findings: [finding({ severity: "CRITICAL" })] }
-        : { verdict: "SHIP", findings: [] };
-    }
-    if (l.startsWith("verify:")) return { refuted: false, reason: "holds" };
-    return replier(BASE_CYCLE)(prompt, opts);
-  }, { feature: "feat-x", maxRounds: 4 });
-  check("findings then clean ⇒ SHIP-READY", result.outcome === "SHIP-READY", `got ${result.outcome}`);
-  check("findings then clean ⇒ took >1 round", result.rounds > 1, `rounds ${result.rounds}`);
+  const { result } = await run("review.js", replier([
+    ["review:", { verdict: "SHIP", findings: [] }], ...BASE_REVIEW,
+  ]), JSON.stringify({ feature: "feat-x" }));
+  check("review: a JSON-encoded args string is parsed, not used as the id",
+    result.verdict === "SHIP", `got ${result.verdict}`);
 }
 {
-  // A refuted CRITICAL must not force a fix round.
-  const { result, calls } = await run("cycle.js", (prompt, opts) => {
-    const l = opts.label || "";
-    if (l.startsWith("review:")) return { verdict: "REVISE", findings: [finding({ severity: "CRITICAL" })] };
-    if (l.startsWith("verify:")) return { refuted: true, reason: "guarded upstream" };
-    return replier(BASE_CYCLE)(prompt, opts);
-  }, { feature: "feat-x", maxRounds: 2 });
-  check("cross-check refutes the only CRITICAL ⇒ SHIP-READY",
-    result.outcome === "SHIP-READY", `got ${result.outcome}`);
-  check("refuted finding ⇒ no fix round", !calls.some(c => c.startsWith("fix:")), calls.join(","));
+  let threw = "";
+  try {
+    await run("review.js", replier([...BASE_REVIEW]), { feature: '{"feature": "feat-x"}' });
+  } catch (e) { threw = e.message; }
+  check("review: a non-slug feature id throws before anything is written",
+    /not a slug/.test(threw), threw || "(did not throw)");
 }
 {
-  const { result } = await run("cycle.js", replier([
-    ["build:", null], ["review:", { verdict: "SHIP", findings: [] }], ...BASE_CYCLE,
-  ]));
-  check("dead implementers ⇒ a question names them",
-    (result.questions || []).some(q => /implementer\(s\) died/.test(q)), JSON.stringify(result.questions));
+  let threw = "";
+  try {
+    await run("review.js", replier([...BASE_REVIEW]), { feature: "../../etc/passwd" });
+  } catch (e) { threw = e.message; }
+  check("review: a path-shaped feature id is rejected",
+    /not a slug/.test(threw), threw || "(did not throw)");
 }
+
+// ── Phase 0 profile handling ─────────────────────────────────────────────────
+// A haiku profile-reader intermittently returns the profile as a JSON *string*
+// under a wrapper field instead of at the top level. The old schema accepted that
+// wrapper, so `surfaces` read as undefined ⇒ [] ⇒ parallel([]) ⇒ zero agents
+// dispatched — and because every later guard compares against `surfaces`, an
+// empty list made them all vacuously pass: a run reported a verdict having done
+// nothing, indistinguishable from a clean run with an empty diff. Two properties
+// are pinned per workflow: a wrapped return is recovered, an empty one aborts.
+console.log("profile phase");
+const WRAPPED = { output: JSON.stringify(PROFILE) };
+const EMPTY_PROFILE = { ...PROFILE, surfaces: [] };
 {
-  const { result } = await run("cycle.js", replier([
-    ["profile", { error: "PIPELINE.md not found" }], ...BASE_CYCLE,
+  const { result } = await run("review.js", replier([
+    ["profile", WRAPPED],
+    ["review:", { verdict: "SHIP", findings: [] }], ...BASE_REVIEW,
   ]));
-  check("unreadable profile ⇒ ABORTED", result.outcome === "ABORTED", `got ${result.outcome}`);
+  check("review: a string-wrapped profile is unwrapped, not silently empty",
+    result.verdict === "SHIP", `got ${result.verdict}`);
 }
 {
-  // A DEAD contract agent must not be reported as a successful re-authoring, and
-  // must not hand every surface a "the contract was RE-AUTHORED, realign" item
-  // pointing at a file nobody touched.
-  const CONTRACT_PROFILE = {
-    ...PROFILE,
-    contract: { enabled: true, path: "packages/shared/src", ext: "ts", mechanism: "shared-types-zod", index: "" },
-  };
-  const contractFinding = finding({ severity: "CRITICAL", file: "packages/shared/src/feat-x.ts" });
-  const { result, calls } = await run("cycle.js", (prompt, opts) => {
-    const l = opts.label || "";
-    if (l === "profile") return CONTRACT_PROFILE;
-    if (l === "contract-fix") return null;              // the agent dies
-    if (l.startsWith("review:")) return { verdict: "REVISE", findings: [contractFinding] };
-    if (l.startsWith("verify:")) return { refuted: false, reason: "holds" };
-    return replier(BASE_CYCLE)(prompt, opts);
-    // maxRounds ≥ 2: the loop breaks at the cap BEFORE the fix block, so a
-    // 1-round run never reaches the contract path at all (a vacuous test).
-  }, { feature: "feat-x", maxRounds: 2 });
-  check("dead contract agent ⇒ no fabricated contractChanges entry",
-    (result.contractChanges || []).length === 0, JSON.stringify(result.contractChanges));
-  check("dead contract agent ⇒ a question says the contract is UNCHANGED",
-    (result.questions || []).some(q => /contract agent died/.test(q)), JSON.stringify(result.questions));
-  check("dead contract agent ⇒ no surface told to realign against it",
-    !calls.some(c => c.startsWith("fix:")), calls.join(","));
+  const { result, calls } = await run("review.js", replier([["profile", EMPTY_PROFILE], ...BASE_REVIEW]));
+  check("review: no surfaces ⇒ ABORTED, not a verdict",
+    result.verdict === "ABORTED", `got ${result.verdict}`);
+  check("review: no surfaces ⇒ zero reviewers spawned",
+    !calls.some(c => c.startsWith("review:")), calls.join(","));
 }
 {
-  // Preflight red with no owning surface used to spin the loop doing nothing
-  // until the round cap, then report a stale verdict.
-  const { result, calls } = await run("cycle.js", replier([
-    ["preflight", { pass: false, tail: "error in vendor/thing.go: boom" }],
-    ["build:", null],                                   // no implementer survives
-    ...BASE_CYCLE,
-  ]), { feature: "feat-x", maxRounds: 5 });
-  check("red preflight with no owning surface ⇒ stops instead of spinning",
-    result.rounds === 1, `burned ${result.rounds} round(s)`);
-  check("…and dispatches no fix agent", !calls.some(c => c.startsWith("fix:")), calls.join(","));
-  check("…and the question carries the failure tail",
-    (result.questions || []).some(q => /no surface owns the failure/.test(q)),
-    JSON.stringify(result.questions));
+  const { result } = await run("audit.js", replier([
+    ["profile", EMPTY_PROFILE], ["gates", { failures: [] }], ["write-backlog", "done"],
+  ]), {});
+  check("audit: no surfaces ⇒ error, not an empty backlog",
+    /no surfaces/.test(result.error || ""), JSON.stringify(result));
 }
 {
-  // A finding under no surface path has no owner: it keeps the loop from exiting
-  // clean while nobody is ever dispatched to fix it. Reachable because `touched`
-  // is agent-supplied — the stage-diff agent can name a key the profile lacks.
-  const orphan = finding({ severity: "CRITICAL", file: "tools/thing.sh", line: 9 });
-  const { result } = await run("cycle.js", (prompt, opts) => {
-    const l = opts.label || "";
-    if (l === "stage-diff") return { surfaces: [{ key: "tools", diff: "d", files: ["tools/thing.sh"] }] };
-    if (l.startsWith("review:")) return { verdict: "REVISE", findings: [orphan] };
-    if (l.startsWith("verify:")) return { refuted: false, reason: "holds" };
-    return replier(BASE_CYCLE)(prompt, opts);
-  }, { feature: "feat-x", maxRounds: 3 });
-  check("a finding owned by no surface names the file, not just 'run /fix manually'",
-    (result.questions || []).some(q => /never dispatched/.test(q) && /tools\/thing\.sh:9/.test(q)),
-    JSON.stringify(result.questions));
+  const { result } = await run("refactor.js", replier([
+    ["profile", EMPTY_PROFILE], ["read-backlog", { domains: [] }],
+  ]), { domains: "all" });
+  check("refactor: no surfaces ⇒ error, not a no-op success",
+    /no surfaces/.test(result.error || ""), JSON.stringify(result));
 }
 
 // ── the dead-agent family, swept across every terminal/staging agent ─────────
@@ -356,25 +253,6 @@ console.log("dead-agent sweep");
   check("review: dead report-stager ⇒ next says nothing was written",
     /NEVER written/.test(result.next), result.next);
 }
-{
-  const { result } = await run("cycle.js", replier([
-    ["stage-diff", null], ["review:", { verdict: "SHIP", findings: [] }], ...BASE_CYCLE,
-  ]));
-  check("cycle: dead diff-stager ⇒ diagnosed as such, not 'wrong branch'",
-    (result.questions || []).some(q => /diff-staging agent died/.test(q)),
-    JSON.stringify(result.questions));
-}
-{
-  const { result } = await run("cycle.js", replier([
-    ["close", null], ["review:", { verdict: "SHIP", findings: [] }], ...BASE_CYCLE,
-  ]));
-  check("cycle: dead close agent ⇒ NOT SHIP-READY",
-    result.outcome !== "SHIP-READY", `got ${result.outcome}`);
-  check("cycle: dead close agent ⇒ a question says nothing was written",
-    (result.questions || []).some(q => /NEVER written/.test(q)), JSON.stringify(result.questions));
-  check("cycle: dead close agent ⇒ report path not claimed",
-    !/^specs\//.test(String(result.report)), result.report);
-}
 {
   const { result } = await run("audit.js", replier([
     ["profile", PROFILE], ["gates", { failures: [] }],

package/scripts/validate-core.mjs

@@ -23,7 +23,7 @@ const frontmatter = (text) => {
 // 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", "cycle"];
+  "refactor", "doctor", "align-ds", "update-pipeline"];
 const UNPINNED = ["brainstorm", "spec", "init-pipeline"];
 
 for (const f of readdirSync(join(root, "core/commands"))) {
@@ -188,8 +188,9 @@ if (!installPs1.includes("core\\workflows"))
   fail("install.ps1", "does not copy core\\workflows (Copy-Core)");
 
 // A new workflow script must also be KNOWN to the things that check for it, or it
-// ships and nothing notices when an installer stops copying it. cycle.js shipped in
-// 1.3.0 while three call sites still said "review/audit/refactor".
+// ships and nothing notices when an installer stops copying it. This check exists
+// because a workflow once shipped while three call sites still named only the
+// three that preceded it.
 const workflowNames = existsSync(workflowsDir)
   ? readdirSync(workflowsDir).filter((f) => f.endsWith(".js"))
   : [];
@@ -204,7 +205,7 @@ for (const f of workflowNames) {
 
 // ── dashboard: the metrics phase list is duplicated server/client ────────────
 // A phase present in one and not the other parses fine and renders in no column —
-// silently invisible data, which is how the cycle batch went unnoticed.
+// silently invisible data, which is how a phase batch once went unnoticed.
 const phaseList = (text, file) => {
   const m = text.match(/const PHASES = \[([^\]]*)\]/);
   if (!m) { fail(file, "no `const PHASES = [...]` found"); return null; }

package/core/commands/cycle.md

@@ -1,61 +0,0 @@
----
-model: sonnet
-description: Launch the full dev-cycle workflow (contract → build → review → fix, until zero findings; add `smoke` to also run the app each round) for a frozen spec; relay its verdict + deferred questions.
-argument-hint: <feature_id> [max_rounds] [smoke]
----
-
-You are the **lead**. Launch the full dev-cycle **workflow** for feature **$ARGUMENTS** — the
-deterministic script does the orchestration (SCHEMA.md §Workflows, `cycle.js`); your job is only to
-start it and relay its result. Do NOT run the phases yourself here — that's the conversational path
-(`/build` → `/smoke` → `/review` → `/fix`), which remains the fallback below.
-
-> **Kanban** (SCHEMA.md §Kanban): move card `#<feature_id>` → **Building** at launch. No-op silently
-> if no board.
-
-## 1. Resolve & check (fail fast, before spending anything)
-
-- Parse `$ARGUMENTS`: the first token is `<feature_id>`, an optional numeric token is
-  `<max_rounds>` (the workflow defaults to 5), and an optional literal token `smoke` opts the
-  smoke agent INTO the verify rounds (default: review-only — smoke is expensive, it boots the
-  app every round; skipping it is the human's explicit risk, `/smoke <feature_id>` stays
-  available standalone before `/ship`).
-- Resolve the script: `.claude/workflows/cycle.js` if it exists, else `~/.claude/workflows/cycle.js`
-  (`test -f`). **Missing both** ⇒ the core predates 1.3.0 or is half-copied: tell the human to run
-  `/update-pipeline`, and stop.
-- **Workflow runtime available?** If the `Workflow` tool is not in your toolset (Claude Code
-  < 2.1.154 or workflows disabled), say so and hand over the conversational path instead:
-  `/build <feature_id>` → `/smoke` → `/review` → `/fix` — same phases, interactive. Stop.
-- Quick spec sanity (the workflow re-checks properly — this just saves a doomed launch):
-  `grep '^status:' specs/<feature_id>.md` must say `frozen` or `in-review`; otherwise tell the human
-  to run `/spec` first, and stop.
-
-## 2. Launch
-
-Call the `Workflow` tool: `scriptPath: <resolved cycle.js path>`,
-`args: {"feature": "<feature_id>", "maxRounds": <max_rounds, omit if not given>, "smoke": <true
-only if the smoke token was given — omit otherwise>}`.
-It runs in the background — tell the human it's off and what it will do (build, then review → fix
-rounds until zero findings, with smoke alongside each round if opted in; no questions mid-run), and
-that `/workflows` shows live progress. Then END YOUR TURN — never poll, never sleep; the completion
-notification re-wakes you.
-
-## 3. Relay the result (when the task notification arrives)
-
-The workflow returns only a verdict object — the bulk is already on disk
-(`specs/reports/<feature_id>.md`, spec `## Remediation`). Print, without re-reading any of it into
-context:
-
-- `outcome` · rounds used · review verdict · smoke result.
-- `contractChanges` if any — flag them explicitly: the loop re-authored the frozen contract
-  lead-style; the human should eyeball those hunks in the diff.
-- `unreviewedSurfaces` if non-empty — **say it plainly**: a reviewer died, so those surfaces
-  carry NO verdict. The run's verdict covers the others only; the code there was never read.
-- **The `questions` array, verbatim** — this is the human's inbox from the run (empty when the spec
-  pre-answered everything). Each one is a decision to make, usually by sharpening the spec.
-- The `next` line: **SHIP-READY** ⇒ `/ship <feature_id>` (DoD ticked + freshness stamped — ship is a
-  straight shot, its human confirmation stays). **STOPPED** ⇒ answer the questions, then rerun
-  `/cycle <feature_id>` (it picks up from the spec's Remediation) or finish conversationally with
-  `/fix <feature_id>` + `/review <feature_id>`.
-- **Kanban:** outcome SHIP-READY ⇒ move card → **Review** (the cycle's last verdict is a review);
-  otherwise → **Fix**. No-op silently if no board.
-- **Recommend a `/clear`** — everything the next command needs is on disk.