cohorte 1.3.3 → 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

@@ -0,0 +1,321 @@
+#!/usr/bin/env node
+// Behavioural tests for core/workflows/*.js.
+//
+// The workflow runtime hands a script an async function body with agent() /
+// parallel() / pipeline() / phase() / log() / args / budget injected. Nothing in
+// a script touches the filesystem, so the whole orchestration is testable by
+// injecting stub agents and asserting the returned verdict object.
+//
+// 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. 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
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = fileURLToPath(new URL("..", import.meta.url));
+const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor;
+
+let failures = 0;
+const check = (name, cond, detail = "") => {
+  if (cond) console.log(`  ✓ ${name}`);
+  else { failures++; console.error(`  ✗ ${name}${detail ? ` — ${detail}` : ""}`); }
+};
+
+const PROFILE = {
+  name: "testproj",
+  vcs: { default_branch: "main" },
+  contract: { enabled: false, path: "packages/shared/src", ext: "ts", mechanism: "none" },
+  commands: { typecheck: "tsc --noEmit", lint_quiet: "lint -q", test_quiet: "test --dot" },
+  surfaces: [
+    { key: "backend", path: "apps/api", agent: "backend", uses_design: false },
+    { key: "frontend", path: "apps/web", agent: "frontend", uses_design: true },
+  ],
+};
+
+const TOUCHED = [
+  { key: "backend", diff: "specs/reports/f.backend.diff", files: ["apps/api/a.ts"] },
+  { key: "frontend", diff: "specs/reports/f.frontend.diff", files: ["apps/web/b.tsx"] },
+];
+
+const finding = (over = {}) => ({
+  severity: "HIGH", file: "apps/api/a.ts", line: 3, kind: "quality",
+  problem: "p", fix: "f", ...over,
+});
+
+// Run one workflow script with a `reply(prompt, opts) => value` stub in place of
+// every agent call. Returns { result, calls }.
+async function run(script, reply, args = { feature: "feat-x" }) {
+  const text = readFileSync(join(root, "core/workflows", script), "utf8")
+    .replace(/^export const meta/m, "const meta");
+  const calls = [];
+  const agent = async (prompt, opts = {}) => {
+    calls.push(opts.label || "(unlabelled)");
+    return reply(prompt, opts, calls);
+  };
+  // Mirrors the runtime's contract: a thunk that throws resolves to null, the
+  // call itself never rejects.
+  const parallel = thunks =>
+    Promise.all(thunks.map(t => Promise.resolve().then(t).catch(() => null)));
+  // Each item runs through every stage independently; a throwing stage drops
+  // that item to null and skips its remaining stages.
+  const pipeline = (items, ...stages) =>
+    Promise.all(items.map(async (item, i) => {
+      let v = item;
+      for (const s of stages) {
+        try { v = await s(v, item, i); } catch { return null; }
+      }
+      return v;
+    }));
+  const fn = new AsyncFunction(
+    "agent", "parallel", "pipeline", "phase", "log", "args", "budget", "workflow", text);
+  const result = await fn(
+    agent, parallel, pipeline, () => {}, () => {}, args,
+    { total: null, spent: () => 0, remaining: () => Infinity }, async () => {});
+  return { result, calls };
+}
+
+// A reply table keyed by label prefix; the first matching prefix wins.
+const replier = table => (prompt, opts) => {
+  const label = opts.label || "";
+  for (const [prefix, value] of table) {
+    if (label === prefix || label.startsWith(prefix)) {
+      return typeof value === "function" ? value(label) : value;
+    }
+  }
+  return "ok";
+};
+
+const BASE_REVIEW = [
+  ["profile", PROFILE],
+  ["preflight", { pass: true }],
+  ["stage-diff", { surfaces: TOUCHED }],
+  ["stage-report", "done"],
+];
+
+console.log("review.js");
+{
+  const { result } = await run("review.js", replier([
+    ["review:", { verdict: "SHIP", findings: [] }], ...BASE_REVIEW,
+  ]));
+  check("clean run ⇒ SHIP", result.verdict === "SHIP", `got ${result.verdict}`);
+  check("clean run ⇒ no unreviewed surfaces", (result.unreviewedSurfaces || []).length === 0);
+  check("clean run ⇒ next is /ship", String(result.next).startsWith("/ship"), result.next);
+}
+{
+  // THE regression: every reviewer dies ⇒ zero findings ⇒ must NOT read as SHIP.
+  const { result } = await run("review.js", replier([
+    ["review:", null], ...BASE_REVIEW,
+  ]));
+  check("all reviewers dead ⇒ not SHIP", result.verdict !== "SHIP", `got ${result.verdict}`);
+  check("all reviewers dead ⇒ both surfaces reported unreviewed",
+    (result.unreviewedSurfaces || []).join(",") === "backend,frontend",
+    JSON.stringify(result.unreviewedSurfaces));
+  check("all reviewers dead ⇒ next says re-run",
+    /re-run the review/.test(result.next), result.next);
+}
+{
+  // One dead reviewer must not be masked by the other surface coming back clean.
+  const { result } = await run("review.js", replier([
+    ["review:backend", null],
+    ["review:", { verdict: "SHIP", findings: [] }],
+    ...BASE_REVIEW,
+  ]));
+  check("one reviewer dead ⇒ not SHIP", result.verdict !== "SHIP", `got ${result.verdict}`);
+  check("one reviewer dead ⇒ names only that surface",
+    (result.unreviewedSurfaces || []).join(",") === "backend", JSON.stringify(result.unreviewedSurfaces));
+}
+{
+  // A SHIP carrying HIGH findings is a real verdict, but it is not "go ship it":
+  // the conversational /review routes any surviving HIGH to /fix.
+  const { result } = await run("review.js", replier([
+    ["review:", { verdict: "SHIP", findings: [finding()] }], ...BASE_REVIEW,
+  ]));
+  check("SHIP + HIGH findings ⇒ verdict still SHIP", result.verdict === "SHIP");
+  check("SHIP + HIGH findings ⇒ next routes to /fix, not /ship",
+    String(result.next).startsWith("/fix"), result.next);
+}
+{
+  const { result } = await run("review.js", replier([
+    ["review:", { verdict: "SHIP", findings: [finding({ severity: "LOW" })] }], ...BASE_REVIEW,
+  ]));
+  check("SHIP + only LOW ⇒ next is /ship", String(result.next).startsWith("/ship"), result.next);
+}
+{
+  const { result } = await run("review.js", replier([
+    ["preflight", { pass: false, tail: "boom" }], ...BASE_REVIEW,
+  ]));
+  check("red preflight ⇒ ABORTED", result.verdict === "ABORTED", `got ${result.verdict}`);
+}
+{
+  const { calls } = await run("review.js", replier([
+    ["preflight", { pass: false, tail: "boom" }], ...BASE_REVIEW,
+  ]));
+  check("red preflight ⇒ zero reviewers spawned",
+    !calls.some(c => c.startsWith("review:")), calls.join(","));
+}
+
+// ── 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");
+{
+  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}`);
+}
+{
+  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)");
+}
+{
+  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("review.js", replier([
+    ["profile", WRAPPED],
+    ["review:", { verdict: "SHIP", findings: [] }], ...BASE_REVIEW,
+  ]));
+  check("review: a string-wrapped profile is unwrapped, not silently empty",
+    result.verdict === "SHIP", `got ${result.verdict}`);
+}
+{
+  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(","));
+}
+{
+  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));
+}
+{
+  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 ─────────
+// `agent()` returns null when a subagent dies. Any call whose result is turned
+// into a CLAIM (a verdict, a path, "it is on disk") must distinguish "died" from
+// "succeeded with nothing to say". This block is the sweep.
+console.log("dead-agent sweep");
+{
+  const { result } = await run("review.js", replier([
+    ["stage-diff", null], ...BASE_REVIEW,
+  ]));
+  check("review: dead diff-stager ⇒ ABORTED, not 'SHIP — nothing to review'",
+    result.verdict === "ABORTED", `got ${result.verdict}: ${result.reason}`);
+}
+{
+  const { result } = await run("review.js", replier([
+    ["stage-report", null],
+    ["review:", { verdict: "SHIP", findings: [] }], ...BASE_REVIEW,
+  ]));
+  check("review: dead report-stager ⇒ reportStaged false", result.reportStaged === false);
+  check("review: dead report-stager ⇒ report path not claimed",
+    !/^specs\//.test(String(result.report)), result.report);
+  check("review: dead report-stager ⇒ next says nothing was written",
+    /NEVER written/.test(result.next), result.next);
+}
+{
+  const { result } = await run("audit.js", replier([
+    ["profile", PROFILE], ["gates", { failures: [] }],
+    ["audit:backend", null],
+    ["audit:", { items: [] }], ["write-backlog", "done"],
+  ]), {});
+  check("audit: dead auditor ⇒ the domain is listed as NOT audited",
+    (result.notAudited || []).join(",") === "backend", JSON.stringify(result.notAudited));
+  check("audit: dead auditor ⇒ next tells you to re-audit it",
+    /re-audit backend/.test(result.next), result.next);
+}
+{
+  const { result } = await run("audit.js", replier([
+    ["profile", PROFILE], ["gates", { failures: [] }],
+    ["audit:", { items: [] }], ["write-backlog", null],
+  ]), {});
+  check("audit: dead backlog writer ⇒ path not claimed",
+    !/^specs\//.test(String(result.backlog)), result.backlog);
+}
+{
+  const { result } = await run("refactor.js", replier([
+    ["profile", PROFILE], ["read-backlog", null],
+  ]), { domains: "all" });
+  check("refactor: dead backlog reader ⇒ says it died, not 'no open items'",
+    /agent died/.test(String(result.error)), result.error);
+}
+{
+  const items = ["- [ ] a", "- [ ] b", "- [ ] c", "- [ ] d", "- [ ] e"];
+  const { result } = await run("refactor.js", replier([
+    ["profile", PROFILE],
+    ["read-backlog", { domains: [{ key: "backend", items }] }],
+    ["verify:", { cleared: items, remaining: [], gatesGreen: true }],
+    ["reverify:", { cleared: items, remaining: [], gatesGreen: true }],
+    ["tick-backlog", null],
+    ["refactor:", "handoff"],
+  ]), { domains: "all" });
+  check("refactor: dead ticker ⇒ backlogTicked false", result.backlogTicked === false);
+  check("refactor: dead ticker ⇒ next warns the backlog still shows them open",
+    /NOT ticked/.test(result.next), result.next);
+}
+
+// ── audit.js / refactor.js — smoke-level: they must return, not throw ────────
+console.log("audit.js / refactor.js");
+{
+  const { result } = await run("audit.js", replier([
+    ["profile", PROFILE],
+    ["gates", { failures: [] }],
+    ["audit:", { items: [{ severity: "HIGH", file: "apps/api/a.ts", line: 1, kind: "tdd", fix: "add a test" }] }],
+    ["write-backlog", "done"],
+  ]), {});
+  check("audit returns a backlog path", result.backlog === "specs/refactor-backlog.md", JSON.stringify(result));
+  check("audit counts every domain (surfaces + shared)",
+    Object.keys(result.domains || {}).join(",") === "backend,frontend,shared", JSON.stringify(result.domains));
+}
+{
+  const { result } = await run("refactor.js", replier([
+    ["profile", PROFILE],
+    ["read-backlog", { domains: [{ key: "backend", items: ["- [ ] a", "- [ ] b"] }] }],
+  ]), { domains: "all" });
+  check("refactor skips a domain below the item threshold",
+    result.skipped && result.skipped.backend === 2, JSON.stringify(result));
+}
+
+console.log("");
+if (failures) { console.error(`test-workflows: ${failures} failure(s)`); process.exit(1); }
+console.log("test-workflows: OK");

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"))) {
@@ -168,6 +168,11 @@ else for (const f of readdirSync(workflowsDir)) {
     fail(path, "phase 0 must read the profile via the profile-reader agent");
   if (/\bDate\.now\(\)|\bMath\.random\(\)|new Date\(\)/.test(text))
     fail(path, "Date.now()/Math.random()/new Date() are unavailable in workflow scripts");
+  // Prompts hand agents literal `<core>/…` paths; an agent can only resolve that
+  // token if the same script also spells out what <core> means. A bare token +
+  // `|| true` = the command fails silently and the ping/metrics never happen.
+  if (text.includes("<core>/") && !/<core> = /.test(text))
+    fail(path, "uses <core>/ paths in prompts without defining `<core> = …` anywhere");
   try {
     new AsyncFunction("agent", "parallel", "pipeline", "phase", "log", "args",
       "budget", "workflow", text.replace(/^export const meta/m, "const meta"));
@@ -182,6 +187,51 @@ if (!installSh.includes("core/workflows"))
 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. 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"))
+  : [];
+const ci = existsSync(join(root, ".github/workflows/ci.yml")) ? read(".github/workflows/ci.yml") : "";
+const dashDoctor = read("dashboard/server/doctor.js");
+for (const f of workflowNames) {
+  if (!ci.includes(`workflows/${f}`))
+    fail(".github/workflows/ci.yml", `install dry-run never asserts .claude/workflows/${f}`);
+  if (!dashDoctor.includes(`'${f}'`))
+    fail("dashboard/server/doctor.js", `checkWorkflows() does not list ${f}`);
+}
+
+// ── 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 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; }
+  return m[1].split(",").map((s) => s.trim().replace(/^['"]|['"]$/g, "")).filter(Boolean);
+};
+const serverPhases = phaseList(read("dashboard/server/metrics.js"), "dashboard/server/metrics.js");
+const clientPhases = phaseList(read("dashboard/app/src/components/MetricsPanel.jsx"),
+  "dashboard/app/src/components/MetricsPanel.jsx");
+if (serverPhases && clientPhases && serverPhases.join("|") !== clientPhases.join("|"))
+  fail("dashboard/app/src/components/MetricsPanel.jsx",
+    `PHASES drifted from dashboard/server/metrics.js ([${clientPhases}] vs [${serverPhases}])`);
+
+// ── packaging: no build artifacts in the published tarball ──────────────────
+// `.npmignore` is INERT under an explicit package.json `files` allowlist, so its
+// `__pycache__/` rule never fired — a maintainer who had compiled gate.py shipped
+// their machine's bytecode cache. The negations in `files` are what actually work.
+const pkg = JSON.parse(read("package.json"));
+for (const negation of ["!core/hooks/__pycache__", "!**/*.pyc"])
+  if (!(pkg.files || []).includes(negation))
+    fail("package.json", `\`files\` must carry the ${negation} negation (.npmignore cannot do this)`);
+for (const [name, src] of Object.entries(installers))
+  if (!src.includes("__pycache__"))
+    fail(name, "never scrubs hooks/__pycache__ — cp -R would carry it into the user's .claude");
+if (!read("bin/cli.js").includes("__pycache__"))
+  fail("bin/cli.js", "copyCore() never excludes __pycache__ from the hooks copy");
+
 // ── report ──────────────────────────────────────────────────────────────────
 if (errors.length) {
   console.error(`validate-core: ${errors.length} error(s)\n`);

package/core/commands/cycle.md

@@ -1,54 +0,0 @@
----
-model: sonnet
-description: Launch the full dev-cycle workflow (contract → build → smoke ∥ review → fix, until zero findings) for a frozen spec; relay its verdict + deferred questions.
-argument-hint: <feature_id> [max_rounds]
----
-
-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 second numeric token is
-  `<max_rounds>` (the workflow defaults to 5).
-- 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>}`.
-It runs in the background — tell the human it's off and what it will do (build, then smoke ∥ review
-→ fix rounds until zero findings + PASS; 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.
-- **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.