cohorte 2.0.2 → 2.2.0

package/scripts/test-adapter.mjs

@@ -0,0 +1,368 @@
+#!/usr/bin/env node
+// Behavioural tests for the runtime adapter — core/adapter/render.js + core/runtimes/*.json.
+//
+// The adapter is where a single set of source prompts becomes N runtime-specific ones. Its
+// failure mode is silent and expensive: a dropped conditional ships a Claude-only instruction
+// to a runtime that cannot follow it, a leaked marker turns doctrine into visible noise, and a
+// wrong frontmatter key is read by the model as prose. None of that raises an error anywhere —
+// it just makes the pipeline quietly wrong on four runtimes out of five.
+//
+//   node scripts/test-adapter.mjs
+
+import { readFileSync, readdirSync, mkdtempSync, mkdirSync, rmSync, existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+
+const root = fileURLToPath(new URL("..", import.meta.url));
+const require = createRequire(import.meta.url);
+const adapter = require(join(root, "core", "adapter", "render.js"));
+
+let failures = 0;
+const check = (name, cond, detail = "") => {
+  if (cond) console.log(`  ✓ ${name}`);
+  else { failures++; console.error(`  ✗ ${name}${detail ? ` — ${detail}` : ""}`); }
+};
+const group = (name) => console.log(name);
+const throws = (fn) => { try { fn(); return false; } catch { return true; } };
+
+const RUNTIMES = adapter.listRuntimes();
+const tmps = [];
+
+// ---------------------------------------------------------------- registry ---
+group("registry — every runtime declares what the renderer reads");
+
+check("at least the five supported runtimes ship", RUNTIMES.length >= 5, RUNTIMES.join(","));
+for (const id of RUNTIMES) {
+  const rt = adapter.loadRuntime(id);
+  const ok = rt.id === id
+    && typeof rt.label === "string"
+    && rt.scopes && rt.scopes.global && rt.scopes.project
+    && rt.command && ["md", "toml", "skill"].includes(rt.command.format)
+    && Array.isArray(rt.command.frontmatter)
+    && rt.capabilities && typeof rt.capabilities.subagents === "boolean"
+                       && typeof rt.capabilities.hooks === "boolean"
+                       && typeof rt.capabilities.workflows === "boolean"
+                       && typeof rt.capabilities.tool_restriction === "boolean";
+  check(`${id}: complete and well-typed`, ok);
+}
+check("unknown runtime is an error, not a silent default",
+  throws(() => adapter.loadRuntime("nope")));
+
+// A runtime that claims a capability it cannot back is the one mistake the whole design rests
+// on: every `cohorte:if` branch trusts these booleans literally, and an over-claim ships the
+// strict doctrine to a runtime that cannot enforce it. Pinned against the vendor docs — see
+// each runtime's `docs` field; revisit these three lines whenever one of them is re-read.
+const withCap = (c) => RUNTIMES.filter((id) => adapter.loadRuntime(id).capabilities[c]).sort().join();
+check("hooks claimed everywhere but OpenCode (plugins are not a blocking hook)",
+  withCap("hooks") === "claude,codex,cursor,gemini", withCap("hooks"));
+check("only Claude Code claims workflows", withCap("workflows") === "claude");
+// Not a capability to branch on: a HARD requirement. The pipeline's isolation guarantee is the
+// subagent boundary, so a runtime without them cannot be supported — and must be refused loudly
+// rather than rendered into a pipeline whose central promise is silently absent.
+check("every target runtime has real subagents",
+  withCap("subagents") === RUNTIMES.slice().sort().join(), withCap("subagents"));
+check("a runtime declaring no subagents is refused, not degraded",
+  throws(() => adapter.assertSupported({ id: "x", capabilities: { subagents: false } })));
+check("…and one that has them passes the same guard",
+  !throws(() => adapter.assertSupported({ id: "x", capabilities: { subagents: true } })));
+
+// A hook runtime must declare how to talk to it, and a no-ask runtime must be flagged: gate.py
+// escalates ask→deny there, and getting this backwards silently lets a gated command run.
+for (const id of RUNTIMES) {
+  const rt = adapter.loadRuntime(id);
+  if (!rt.capabilities.hooks) { check(`${id}: declares no hook contract`, !rt.hook); continue; }
+  check(`${id}: hook contract is complete`, !!rt.hook && !!rt.hook.event
+    && ["claude", "cursor", "gemini"].includes(rt.hook.format)
+    && typeof rt.hook.supports_ask === "boolean"
+    && !!rt.scopes.project.hooks_config);
+}
+check("the ask tier is claimed only where the runtime honours it",
+  RUNTIMES.filter((id) => (adapter.loadRuntime(id).hook || {}).supports_ask).sort().join()
+    === "claude,cursor");
+
+// ------------------------------------------------------------ conditionals ---
+group("conditionals — the branch that survives is the branch that is true");
+
+// Synthetic capability sets, not real runtimes: the branch logic must stay correct however the
+// vendors' feature matrix moves, and a unit test of the parser should not depend on which
+// runtimes happen to ship today.
+const rich = { id: "rich", capabilities: { subagents: true, hooks: true, workflows: true, tool_restriction: true } };
+const bare = { id: "bare", capabilities: { subagents: false, hooks: false, workflows: false, tool_restriction: false } };
+
+const basic = ["<!-- cohorte:if hooks -->", "H", "<!-- cohorte:else -->", "NOH", "<!-- cohorte:endif -->"].join("\n");
+check("if/else keeps the taken branch", adapter.applyConditionals(basic, rich).trim() === "H");
+check("if/else keeps the else branch", adapter.applyConditionals(basic, bare).trim() === "NOH");
+
+const neg = ["<!-- cohorte:if !hooks -->", "ADVISORY", "<!-- cohorte:endif -->"].join("\n");
+check("negation works", adapter.applyConditionals(neg, bare).trim() === "ADVISORY"
+  && adapter.applyConditionals(neg, rich).trim() === "");
+
+const byId = ["<!-- cohorte:if runtime:claude -->", "CC", "<!-- cohorte:endif -->"].join("\n");
+check("runtime:<id> targets one runtime",
+  adapter.applyConditionals(byId, adapter.loadRuntime("claude")).trim() === "CC"
+  && adapter.applyConditionals(byId, adapter.loadRuntime("cursor")).trim() === "");
+
+const or = ["<!-- cohorte:if hooks workflows -->", "X", "<!-- cohorte:endif -->"].join("\n");
+check("a multi-term condition is an OR", adapter.applyConditionals(or, rich).trim() === "X");
+
+const nested = [
+  "<!-- cohorte:if subagents -->", "A",
+  "<!-- cohorte:if hooks -->", "B", "<!-- cohorte:else -->", "C", "<!-- cohorte:endif -->",
+  "<!-- cohorte:endif -->",
+].join("\n");
+check("nesting resolves inner branches inside a taken outer one",
+  adapter.applyConditionals(nested, rich).trim().split("\n").join() === "A,B");
+check("a dropped outer branch drops its inner branches whole",
+  adapter.applyConditionals(nested, bare).trim() === "");
+
+check("an unknown capability is an error, not a silently-false branch",
+  throws(() => adapter.applyConditionals("<!-- cohorte:if telepathy -->\nx\n<!-- cohorte:endif -->", rich)));
+check("an unclosed if is an error", throws(() => adapter.applyConditionals("<!-- cohorte:if hooks -->\nx", rich)));
+check("a stray endif is an error", throws(() => adapter.applyConditionals("<!-- cohorte:endif -->", rich)));
+check("two elses in one if is an error", throws(() => adapter.applyConditionals(
+  ["<!-- cohorte:if hooks -->", "<!-- cohorte:else -->", "<!-- cohorte:else -->", "<!-- cohorte:endif -->"].join("\n"), rich)));
+
+// Every marker in the real source must be resolvable for EVERY runtime — an unknown term in
+// a command nobody rendered yet would surface as an install-time crash for one runtime only.
+group("source prompts — every marker resolves for every runtime");
+const sources = [
+  ...readdirSync(join(root, "core", "commands")).map((f) => ["commands", f]),
+  ...readdirSync(join(root, "core", "agents")).map((f) => ["agents", f]),
+].filter(([, f]) => f.endsWith(".md"));
+for (const id of RUNTIMES) {
+  const rt = adapter.loadRuntime(id);
+  let bad = null;
+  for (const [dir, f] of sources) {
+    const src = readFileSync(join(root, "core", dir, f), "utf8");
+    try { adapter.applyConditionals(adapter.parseFrontmatter(src).body, rt); }
+    catch (e) { bad = `${dir}/${f}: ${e.message}`; break; }
+  }
+  check(`${id}: all ${sources.length} source files render`, !bad, bad || "");
+}
+
+// ------------------------------------------------------------ full install ---
+group("install — what each runtime actually gets on disk");
+
+const home = mkdtempSync(join(tmpdir(), "cohorte-home-"));
+const proj = mkdtempSync(join(tmpdir(), "cohorte-proj-"));
+tmps.push(home, proj);
+spawnSync("git", ["init", "-q", "."], { cwd: proj });
+const run = spawnSync(process.execPath, [join(root, "bin", "cli.js"), "install",
+  `--runtime=${RUNTIMES.join(",")}`], {
+  cwd: proj, env: { ...process.env, HOME: home, CLAUDE_CONFIG_DIR: "" }, encoding: "utf8",
+});
+check("the installer exits clean for every runtime at once", run.status === 0,
+  (run.stderr || "").slice(0, 400));
+
+for (const id of RUNTIMES) {
+  const rt = adapter.loadRuntime(id);
+  // resolvePaths reads ~ from the real homedir, so re-point it at the sandbox.
+  const p = adapter.resolvePaths(rt, "project", proj);
+  const fix = (s) => s && s.replace(process.env.HOME, home);
+  const cmdDir = fix(p.commands);
+  const buildFile = join(cmdDir, `cohorte-build${rt.command.ext}`);
+  check(`${id}: commands landed in ${rt.scopes.project.commands}`, existsSync(buildFile));
+  if (!existsSync(buildFile)) continue;
+  const build = readFileSync(buildFile, "utf8");
+
+  check(`${id}: no unresolved marker leaked into the output`, !/cohorte:(if|else|endif)/.test(build));
+  check(`${id}: the runtime preamble is present`, build.includes(`**Runtime: ${rt.label}.**`));
+
+  // Parallel dispatch is the doctrine on every runtime now; the sequential-persona fallback was
+  // removed in 2.2.0 along with any suggestion that a lead can simulate the boundary by hand.
+  check(`${id}: dispatches surfaces in parallel`, build.includes("IN PARALLEL"));
+  check(`${id}: no trace of the removed persona fallback`,
+    !build.includes("ONE PERSONA AT A TIME") && !build.includes("adopt it verbatim"));
+
+  // A path the runtime does not have is a path the model will fail to read, silently.
+  if (id !== "claude") {
+    check(`${id}: no hardcoded .claude path left in the prose`,
+      !/(?<![\w/.-])~?\/?\.claude\//.test(build), (build.match(/.{0,60}\.claude\/.{0,40}/) || [""])[0]);
+  }
+
+  // The preamble must describe the gate the way it actually works here — a blocking hook that
+  // fires regardless, or an advisory check the agent has to call. Getting this backwards is the
+  // worst single error the adapter can make: it tells the model a safety property holds when it
+  // does not.
+  if (rt.capabilities.hooks) {
+    check(`${id}: the gate is described as a blocking ${rt.hook.event} hook`,
+      build.includes("is registered as a blocking") && build.includes(rt.hook.event));
+    check(`${id}: the missing confirmation tier is stated`,
+      build.includes("no confirmation tier") === !rt.hook.supports_ask);
+  } else {
+    check(`${id}: the gate is described as an explicit check`, build.includes("gate.py --check"));
+  }
+
+  // Frontmatter the runtime does not understand is prose the model reads as instruction.
+  if (rt.command.format === "md" || rt.command.format === "skill") {
+    const fm = adapter.parseFrontmatter(build).keys.map(([k]) => k);
+    check(`${id}: only supported frontmatter keys survive`,
+      fm.every((k) => rt.command.frontmatter.includes(k)), fm.join(","));
+    if (rt.command.format === "skill") {
+      // A skill is matched on its frontmatter `name`, both for explicit invocation and for
+      // implicit selection. Without it the file installs and is simply never reachable.
+      check(`${id}: the skill carries the name it is invoked by`,
+        fm.includes("name") && /^name: cohorte-build$/m.test(build));
+      check(`${id}: skills are repo-scoped, so a clone gets the commands`,
+        rt.scopes.project.commands.startsWith(".agents/"));
+    }
+  } else {
+    check(`${id}: emitted as ${rt.command.format}, not markdown frontmatter`,
+      !build.startsWith("---\n") && /^description = "/m.test(build) && /^prompt = '''/m.test(build));
+  }
+
+  // Placeholder substitution: a token the runtime never expands must be explained, not left
+  // to look like it works.
+  if (rt.command.args && rt.command.args !== "$ARGUMENTS") {
+    check(`${id}: $ARGUMENTS rewritten to ${rt.command.args}`,
+      build.includes(rt.command.args) && !build.includes("$ARGUMENTS"));
+  } else if (!rt.command.args) {
+    check(`${id}: the unsubstituted placeholder is explained in the preamble`,
+      build.includes("does not substitute placeholders"));
+  }
+
+  for (const excluded of rt.exclude_commands || []) {
+    check(`${id}: ${excluded} is not installed (it cannot run here)`,
+      !existsSync(join(cmdDir, `${excluded}${rt.command.ext}`)));
+  }
+
+  const agentsDir = fix(p.agents) || join(fix(p.core), "agents");
+  const reviewFile = join(agentsDir, `review${rt.agent.ext || ".md"}`);
+  check(`${id}: the review agent exists as ${rt.agent.format}`, existsSync(reviewFile));
+  if (existsSync(reviewFile)) {
+    const review = readFileSync(reviewFile, "utf8");
+    // The reviewer must never be able to fix what it reports. Where the runtime can enforce
+    // that, the rendered file must carry the restriction; where it cannot, the body must say
+    // so — a reviewer that silently gains write access destroys the fix loop's evidence.
+    if (rt.agent.readonly_key) {
+      check(`${id}: the reviewer is pinned read-only (${rt.agent.readonly_key})`,
+        review.includes(rt.agent.readonly_key) && review.includes(rt.agent.readonly_value));
+    } else if (rt.capabilities.tool_restriction) {
+      // Claude expresses it as the absence of write tools in the `tools:` list.
+      check(`${id}: the reviewer's tool list carries no write tool`,
+        /^tools:.*$/m.test(review) && !/^tools:.*(Write|Edit|Bash)/m.test(review));
+    } else {
+      check(`${id}: the reviewer is told read-only is on it`,
+        review.includes("read-only **by discipline**") || review.includes("read-only by discipline"));
+    }
+    // An Anthropic model alias in another vendor's agent file either errors or is ignored.
+    check(`${id}: no Anthropic model alias leaked into the agent file`,
+      id === "claude" || !/^\s*model\s*[:=]/m.test(review), (review.match(/^.*model.*$/m) || [""])[0]);
+  }
+  // Every non-Claude runtime shares one `.cohorte` core, so this registry must ACCUMULATE.
+  // A single-record file let each install erase the previous runtime's entry.
+  const rtJson = join(fix(p.core), "pipeline", "runtimes.json");
+  check(`${id}: survives in runtimes.json after the other installs`, existsSync(rtJson)
+    && !!JSON.parse(readFileSync(rtJson, "utf8"))[id]);
+  check(`${id}: the gate script ships with the core`, existsSync(join(fix(p.core), "hooks", "gate.py")));
+  check(`${id}: workflows ship only where a workflow engine exists`,
+    existsSync(join(fix(p.core), "workflows")) === rt.capabilities.workflows);
+
+  // Templates are resolved in place at install time, so a shared core would let the LAST
+  // runtime installed decide what every other one reads. Each core is its own directory
+  // precisely to prevent that; assert the resolution actually matches this runtime.
+  const step = join(fix(p.core), "templates", "steps", "init-pipeline", "04-write-render.md");
+  if (existsSync(step)) {
+    const text = readFileSync(step, "utf8");
+    check(`${id}: templates carry no unresolved marker`, !/cohorte:(if|else|endif)/.test(text));
+    check(`${id}: the settings/hook step matches this runtime`,
+      text.includes("Write `.claude/settings.json`") === rt.capabilities.hooks);
+  }
+}
+
+// The project state — gate config, preflight stamp, metrics — describes the repo, not the
+// agent driving it, and must NOT fork per runtime.
+group("state — one project, one gate config");
+const stateDirs = new Set(RUNTIMES.map((id) => adapter.stateDir(adapter.loadRuntime(id))));
+check("every non-Claude runtime shares one state dir", stateDirs.size === 2
+  && stateDirs.has(".claude") && stateDirs.has(".cohorte"));
+check("but each keeps its own rendered core",
+  new Set(RUNTIMES.map((id) => adapter.loadRuntime(id).scopes.project.core)).size === RUNTIMES.length);
+
+// A config dir with a space in it is not exotic: a desktop host puts CLAUDE_CONFIG_DIR under
+// `~/Library/Application Support/…`. An unquoted path there splits in the shell, python reports
+// `can't open file '/Users/x/Library/Application'`, and EVERY tool call in the session fails —
+// including the ones the human would need to undo it. Assert the registration is quoted, per
+// runtime, and that the installer still recognises its own entry (or a re-install duplicates it).
+group("hook registration — paths with spaces");
+{
+  const spacedHome = mkdtempSync(join(tmpdir(), "cohorte home-"));
+  const spacedProj = mkdtempSync(join(tmpdir(), "cohorte proj-"));
+  tmps.push(spacedHome, spacedProj);
+  spawnSync("git", ["init", "-q", "."], { cwd: spacedProj });
+  const env = { ...process.env, HOME: spacedHome, CLAUDE_CONFIG_DIR: join(spacedHome, ".claude") };
+  const args = [join(root, "bin", "cli.js"), "install", `--runtime=${RUNTIMES.join(",")}`];
+  const first = spawnSync(process.execPath, args, { cwd: spacedProj, env, encoding: "utf8" });
+  check("installs into a path containing a space", first.status === 0,
+    (first.stderr || "").slice(0, 300));
+  // Claude registers its hook only on a GLOBAL install — project-scope settings.json is
+  // /cohorte-init-pipeline's job — so exercise that scope too.
+  const gargs = [join(root, "bin", "cli.js"), "install", "--global", "--runtime=claude"];
+  spawnSync(process.execPath, gargs, { cwd: spacedProj, env, encoding: "utf8" });
+  // Re-install BOTH: the reconcile must match its own quoted entry, or every run stacks another.
+  spawnSync(process.execPath, args, { cwd: spacedProj, env, encoding: "utf8" });
+  spawnSync(process.execPath, gargs, { cwd: spacedProj, env, encoding: "utf8" });
+
+  for (const id of RUNTIMES) {
+    const rt = adapter.loadRuntime(id);
+    if (!rt.capabilities.hooks) continue;
+    const cfgSpec = (id === "claude" ? rt.scopes.global : rt.scopes.project).hooks_config;
+    const cfgPath = cfgSpec.startsWith("~/")
+      ? join(spacedHome, cfgSpec.slice(2)) : join(spacedProj, cfgSpec);
+    if (!existsSync(cfgPath)) { check(`${id}: hook config written`, false, cfgPath); continue; }
+    const hooks = JSON.parse(readFileSync(cfgPath, "utf8")).hooks || {};
+    const entries = hooks[rt.hook.event] || [];
+    const cmds = entries.flatMap(e => e.command ? [e.command] : (e.hooks || []).map(h => h.command));
+    const ours = cmds.filter(c => /gate\.py/.test(c));
+    check(`${id}: the gate path is quoted`, ours.length > 0 && ours.every(c => /"[^"]*gate\.py"/.test(c)),
+      ours.join(" | "));
+    check(`${id}: re-installing does not stack a second registration`, ours.length === 1,
+      `${ours.length} entries`);
+  }
+}
+
+// CLAUDE_CONFIG_DIR moves Claude Code's whole tree — a desktop host points it at
+// `~/Library/Application Support/…`. The registry declares those paths as `~/.claude`, and
+// resolving them from the homedir instead of the override split the install in half: the core
+// went to the REAL `~/.claude` while the hook was registered in the override. A scratch install
+// therefore wrote into the user's actual global core, silently.
+group("CLAUDE_CONFIG_DIR is honoured, not half-honoured");
+{
+  const home = mkdtempSync(join(tmpdir(), "cohorte-home-"));
+  const cfg = mkdtempSync(join(tmpdir(), "cohorte-cfg-"));   // deliberately NOT under home
+  const proj = mkdtempSync(join(tmpdir(), "cohorte-proj-"));
+  tmps.push(home, cfg, proj);
+  spawnSync("git", ["init", "-q", "."], { cwd: proj });
+  const r = spawnSync(process.execPath,
+    [join(root, "bin", "cli.js"), "install", "--global", "--runtime=claude"],
+    { cwd: proj, env: { ...process.env, HOME: home, CLAUDE_CONFIG_DIR: cfg }, encoding: "utf8" });
+
+  check("the global install succeeds under an overridden config dir", r.status === 0,
+    (r.stderr || "").slice(0, 300));
+  check("the core lands in the override", existsSync(join(cfg, "pipeline", "VERSION")));
+  check("the commands land in the override", existsSync(join(cfg, "commands", "cohorte-build.md")));
+  check("the hook is registered in the override", existsSync(join(cfg, "settings.json")));
+  check("nothing is written to the home default",
+    !existsSync(join(home, ".claude", "pipeline", "VERSION")));
+}
+
+// Claude Code must not regress: it is the runtime everyone is already on.
+group("no regression — the Claude install keeps its shape");
+check("commands still in .claude/commands", existsSync(join(proj, ".claude", "commands", "cohorte-build.md")));
+check("agents still in .claude/agents", existsSync(join(proj, ".claude", "agents", "review.md")));
+check("the model pin survives the render",
+  /^model: sonnet$/m.test(readFileSync(join(proj, ".claude", "commands", "cohorte-build.md"), "utf8")));
+check("the subagent name survives the render",
+  /^name: review$/m.test(readFileSync(join(proj, ".claude", "agents", "review.md"), "utf8")));
+// 2.2.0 retired /cohorte-loop. Copy-over never deletes, so the scrub is the only thing standing
+// between an upgrade and a decoy command the model can still fire — assert it on the layout that
+// actually had one installed.
+check("the retired /cohorte-loop is not installed",
+  !existsSync(join(proj, ".claude", "commands", "cohorte-loop.md")));
+
+for (const d of tmps) rmSync(d, { recursive: true, force: true });
+console.log(failures ? `\ntest-adapter: ${failures} FAILED` : "\ntest-adapter: OK");
+process.exit(failures ? 1 : 0);

package/scripts/test-dashboard.mjs

@@ -402,6 +402,76 @@ console.log("index.js — HTTP guards");
   eq("an unknown API route 404s", (await fetch(`${base}/api/nope`)).status, 404);
 }
 
+// ── runtime.js + a non-Claude layout ────────────────────────────────────────
+// Every path-dependent check used to assume `.claude/`. On a repo driven from Cursor that
+// reported a healthy install as three ❌ and a ⚠️ — no core, no rendered agent, artifacts not
+// ignored, hook not registered — and every one was wrong. A false red is worse than no check:
+// it sends a human fixing something that is not broken.
+console.log("doctor.js — a non-Claude runtime layout");
+{
+  const d = scratch();
+  const g = join(d, "global-claude");
+  mkdirSync(g, { recursive: true });
+
+  const core = join(d, ".cohorte", "cursor");
+  mkdirSync(join(core, "pipeline"), { recursive: true });
+  writeFileSync(join(core, "pipeline", "VERSION"), "9.9.9\n");
+  writeFileSync(join(core, "pipeline", "runtimes.json"), JSON.stringify({
+    cursor: {
+      label: "Cursor", scope: "project", core_version: "9.9.9",
+      capabilities: { subagents: true, hooks: true, workflows: false, tool_restriction: true },
+      paths: {
+        core, commands: join(d, ".cursor", "commands"), agents: join(d, ".cursor", "agents"),
+        hooks_config: join(d, ".cursor", "hooks.json"), state: ".cohorte",
+      },
+    },
+  }));
+  mkdirSync(join(d, ".cursor", "agents"), { recursive: true });
+  writeFileSync(join(d, ".cursor", "agents", "api.md"), "---\nname: api\n---\n");
+  writeFileSync(join(d, ".cursor", "hooks.json"), JSON.stringify({
+    version: 1,
+    hooks: { beforeShellExecution: [{ command: `python3 ${core}/hooks/gate.py --runtime cursor` }] },
+  }));
+  mkdirSync(join(d, ".cohorte"), { recursive: true });
+  const gate = { deny: ["rm -rf /"], ask: [], ask_on_default_branch: [], default_branch: "main" };
+  writeFileSync(join(d, ".cohorte", "gate-config.json"),
+    JSON.stringify({ ...gate, preflight: { enabled: false } }));
+  writeFileSync(join(d, ".gitignore"),
+    ".cohorte/preflight.ok\n.cohorte/pipeline-metrics.jsonl\nspecs/reports/\n");
+  writeFileSync(join(d, "PIPELINE.md"), [
+    "```yaml pipeline-profile", "name: demo",
+    "surfaces:", "  - key: api", "    path: src/api", "    agent: api",
+    "gate:", "  deny:", "    - rm -rf /", "  default_branch: main",
+    "  preflight:", "    enabled: false", "```",
+  ].join("\n"));
+
+  const s = await state({ projectRoot: d, globalDir: g, cliVersion: "9.9.9" });
+  const pick = id => s.checks.find(c => c.id === id) || {};
+  const st = id => pick(id).status;
+  const dt = id => pick(id).detail;
+
+  eq("the runtime is discovered from runtimes.json", s.runtimes.map(r => r.id), ["cursor"]);
+  check("the core in .cohorte/<id>/ counts as installed", st("core") === "ok", dt("core"));
+  check("agents are looked for in .cursor/agents", st("agents") === "ok", dt("agents"));
+  check("gate-config is read from .cohorte, not .claude", st("gate") === "ok", dt("gate"));
+  check("artifact paths are named against the right state dir",
+    st("artifacts") === "ok" && !/\.claude/.test(dt("artifacts")), dt("artifacts"));
+  // Cursor's registration is a flat {command} under beforeShellExecution — read with Claude's
+  // matcher-group shape it looks absent, which is exactly the false red this guards.
+  check("the Cursor hook envelope is recognised", st("hooks") === "ok", dt("hooks"));
+  check("workflows are skipped, not reported missing",
+    st("workflows") === "skip" && /Cursor/.test(dt("workflows")), dt("workflows"));
+  check("nothing is reported broken on a healthy non-Claude install",
+    s.summary.bad === 0 && s.summary.warn === 0, JSON.stringify(s.summary));
+
+  // The metrics sink follows `<state>` too.
+  writeFileSync(join(d, ".cohorte", "pipeline-metrics.jsonl"),
+    JSON.stringify({ ts: "2026-01-01T00:00:00Z", feature: "f", phase: "build", seconds: 10,
+      surfaces: { api: "ok" } }) + "\n");
+  check("metrics are read from the runtime's state dir",
+    metrics({ projectRoot: d, globalDir: g }).batches === 1);
+}
+
 for (const d of tmps) { try { rmSync(d, { recursive: true, force: true }); } catch { /* best effort */ } }
 console.log("");
 if (failures) { console.error(`test-dashboard: ${failures} failure(s)`); process.exit(1); }

package/scripts/test-gate.mjs

@@ -353,6 +353,68 @@ console.log("gate.py — worktree awareness");
   }
 }
 
+// ---------------------------------------------------------------------------
+// Runtime dialects. Four runtimes host this hook and none of them agree on the
+// envelope. A verdict emitted in the wrong shape is read as "allow" by every one of
+// them — the gate would look installed, print JSON, and block nothing. Two of them
+// also have no confirmation tier, where an honest `ask` must become a `deny` rather
+// than fall through.
+console.log("gate.py — runtime dialects");
+{
+  const d = scratch();
+  gitRepo(d, "main");
+  writeConfig(d, {
+    deny: ["rm -rf /"], ask: ["git push"], ask_on_default_branch: [],
+    default_branch: "main", preflight: { enabled: true, agents: ["review"] },
+  });
+  const raw = (payload, ...args) => {
+    const r = spawnSync(python, [GATE, ...args], {
+      input: JSON.stringify(payload), encoding: "utf8",
+      env: { ...process.env, CLAUDE_PROJECT_DIR: d },
+    });
+    let json = null;
+    try { json = JSON.parse((r.stdout || "").trim()); } catch { /* no verdict */ }
+    return { json, status: r.status };
+  };
+  const push = { tool_name: "Bash", tool_input: { command: "git push" }, cwd: d };
+
+  const cc = raw(push, "--runtime", "claude");
+  check("claude: ask stays an ask, in the PreToolUse envelope",
+    cc.json?.hookSpecificOutput?.permissionDecision === "ask");
+  check("no --runtime flag behaves exactly as claude (pre-adapter registrations)",
+    raw(push).json?.hookSpecificOutput?.permissionDecision === "ask");
+
+  const cx = raw(push, "--runtime", "codex");
+  check("codex: ask escalates to deny (its `ask` is parsed but never honoured)",
+    cx.json?.hookSpecificOutput?.permissionDecision === "deny");
+  check("…and the reason says why it was refused rather than queried",
+    /no confirmation tier/.test(cx.json?.hookSpecificOutput?.permissionDecisionReason || ""));
+
+  // Cursor sends the command at the top level and names no tool.
+  const cu = raw({ hook_event_name: "beforeShellExecution", command: "git push", cwd: d },
+    "--runtime", "cursor");
+  check("cursor: its own envelope, and the top-level command is found",
+    cu.json?.permission === "ask" && typeof cu.json?.user_message === "string");
+  const cuDeny = raw({ hook_event_name: "beforeShellExecution", command: "rm -rf /", cwd: d },
+    "--runtime", "cursor");
+  check("cursor: a deny also exits 2 (its documented blocking code)",
+    cuDeny.json?.permission === "deny" && cuDeny.status === 2);
+
+  const ge = raw({ tool_name: "run_shell_command", tool_input: { command: "rm -rf /" }, cwd: d },
+    "--runtime", "gemini");
+  check("gemini: BeforeTool envelope, and run_shell_command is recognised as the shell",
+    ge.json?.decision === "deny" && typeof ge.json?.reason === "string");
+
+  // Gemini exposes each subagent as a tool of its own name, so the phase gate has to fire
+  // on `tool_name: review` — not only on Claude's `Task` + subagent_type shape.
+  const geDispatch = raw({ tool_name: "review", tool_input: {}, cwd: d }, "--runtime", "gemini");
+  check("gemini: a subagent-as-tool dispatch still hits the preflight phase gate",
+    geDispatch.json?.decision === "deny"
+      && /preflight/i.test(geDispatch.json?.reason || ""));
+  check("an unrelated tool is never gated on any runtime",
+    raw({ tool_name: "read_file", tool_input: {}, cwd: d }, "--runtime", "gemini").json === null);
+}
+
 for (const d of tmps) { try { rmSync(d, { recursive: true, force: true }); } catch { /* best effort */ } }
 
 console.log("");

package/scripts/validate-core.mjs

@@ -24,7 +24,7 @@ const frontmatter = (text) => {
 // Interactive commands must stay unpinned (they inherit on purpose).
 const PINNED = ["cohorte-build", "cohorte-review", "cohorte-fix", "cohorte-ship",
   "cohorte-audit", "cohorte-refactor", "cohorte-doctor", "cohorte-align-ds",
-  "cohorte-update-pipeline", "cohorte-loop"];
+  "cohorte-update-pipeline"];
 const UNPINNED = ["cohorte-brainstorm", "cohorte-spec", "cohorte-init-pipeline"];
 
 // Every command must carry the `cohorte-` prefix. This replaces the old RESERVED

package/core/commands/cohorte-loop.md

@@ -1,110 +0,0 @@
----
-model: sonnet
-description: Autonomous /cohorte-build → /cohorte-review → /cohorte-fix → /cohorte-review loop for one feature, until no blocking finding remains.
-argument-hint: <feature_id> [--max=N] [--no-build] [--rebuild] [--resume]
-allowed-tools: Bash(bash ~/.claude/pipeline/scripts/loop-detach.sh:*), Bash(bash .claude/pipeline/scripts/loop-detach.sh:*), Bash(test:*), Read(specs/reports/**)
-disable-model-invocation: true
----
-
-You are the **launcher**, not the loop. Run the driver for **$ARGUMENTS** and relay three lines.
-
-> **The driver's name has moved twice.** It was `/loop`, which Claude Code's own built-in `/loop`
-> (run a prompt on a recurring interval) silently **shadowed** — typing `/loop <id>` started the
-> interval runner with the feature id as its prompt, so the driver never ran and the session
-> reported a loop that did not exist. 1.6.0 renamed it `/drive` to escape that. 2.0.0 prefixed
-> every command with `cohorte-`, which makes shadowing impossible by construction, so the accurate
-> name is back: **`/cohorte-loop`**. The shipped script keeps its `loop.sh` name throughout.
->
-> This command exists because a slash command cannot `/clear` itself. Every phase of the loop runs
-> as a **separate `claude -p` child session** with its own fresh context, driven by a bash script —
-> so the diff, the N review reports and the N contracts never accumulate in YOUR history, which is
-> re-sent at input price on every turn. Running the loop conversationally here would cost more than
-> the loop saves.
-
-## 1. Launch — detached, then poll
-
-The driver runs for **hours**, which rules out running it as one foreground Bash call: a single
-call is capped at 600 s, and a backgrounded one is not detached — the child stays in this session's
-process group, so a Claude Code restart, crash or laptop sleep kills `loop.sh` and every `claude -p`
-child with it, mid-write. `loop-detach.sh` puts the driver in its own `screen` session so it
-survives all of that, and `loop.sh` re-execs itself under `caffeinate` so idle sleep cannot abort
-its in-flight requests either.
-
-Launch — returns immediately:
-
-```
-test -f .claude/pipeline/scripts/loop-detach.sh \
-  && bash .claude/pipeline/scripts/loop-detach.sh start $ARGUMENTS \
-  || bash ~/.claude/pipeline/scripts/loop-detach.sh start $ARGUMENTS
-```
-
-Then poll. Each call blocks up to ~9 min (inside the tool ceiling) and prints the **status file** —
-one line per phase, plus `__EXIT__ <code>` when the run is over:
-
-```
-bash ~/.claude/pipeline/scripts/loop-detach.sh wait <feature_id>
-```
-
-**Repeat `wait` until you see `__EXIT__ <code>`.** A `__RUNNING__` line means the driver is still
-working and nothing is wrong — call `wait` again. Never conclude anything from a `__RUNNING__`;
-the run has not finished and you have no verdict to report. If the human says to stop waiting,
-tell them the run continues detached and how to follow it (`screen -r cohorte-<id>`) — do not
-kill it unless they ask.
-
-Pass `$ARGUMENTS` through untouched — `loop.sh` owns its own flag parsing (`--max=N`,
-`--no-build`, `--rebuild`, `--resume`) and exits 64 on anything it doesn't know. Don't validate flags
-yourself, don't rewrite them, don't add any.
-
-**One lid-close caveat to pass on** if the human is walking away from a laptop: `caffeinate` holds
-off *idle* sleep, but no userspace assertion can prevent lid-close sleep. Lid open, or clamshell
-mode (AC + external display + external input).
-
-**Resume is the human's call, not yours.** The loop records its position in the spec's front-matter
-(`status: in-progress` · `loop_pass` · `loop_phase` — SCHEMA.md §Spec status), so a run killed by a
-dead session, a ceiling or a `blocked` exit can continue with `--resume` instead of re-paying the
-passes it already made. If the human types `/cohorte-loop <id>` on a spec whose front-matter says
-`status: in-progress` or `blocked` with `loop_pass` > 1, say so in one line and ask whether to resume
-or restart — never silently add the flag, and never silently restart from pass 1.
-
-**Never read `specs/reports/<id>.loop.log`.** It holds the full transcript of every child session —
-the entire diff, every review report, every fix handoff. Pulling it into this session re-imports
-exactly the context the loop was built to keep out, and it is the one mistake that turns this
-command into the most expensive one in the pipeline. Point the human at the path instead; they can
-open it in an editor for free. The same goes for the per-surface `.diff` and `.preflight.txt` files.
-
-`<id>.loop.status` is the **other** file and is safe: it is the driver's stdout, one line per phase.
-`wait` already prints it, so you never need to Read it yourself. Two files, one letter apart —
-`.log` is the expensive one.
-
-## 2. Report — three lines, from the exit code
-
-`wait` prints one line per phase, one closing line, and `__EXIT__ <code>`; that is your raw
-material, and that code is the exit code the table below is keyed on. For exit
-**1** or **3** only, also Read `specs/reports/<id>.verdict.json` (small, structured, safe) to name
-the remaining findings — never the markdown report, which is the findings body in full. For exit
-**4**, Read `specs/reports/<id>.readiness.json` instead (also small) and relay its `gaps`. On any
-other exit the closing line already carries the deferred count, so read nothing.
-
-| exit | meaning | what to say |
-| ---- | ------- | ----------- |
-| `0` | clean | no blocking findings left; the human can `/cohorte-ship <id>` |
-| `1` | ceiling hit | the fix was progressing but ran out of passes ⇒ re-run with a higher `--max` |
-| `2` | no usable verdict | `/cohorte-review` produced nothing, or aborted on a red preflight — the closing line says which; point at `specs/reports/<id>.preflight.txt` |
-| `3` | non-convergent | the same blocking findings survived a fix pass; a higher `--max` will NOT help — the human needs to look at them (list them from the verdict) |
-| `4` | not implementable | `/cohorte-build`'s readiness gate returned `NOT-READY` — the frozen spec cannot be built and **no agent ran**; Read `specs/reports/<id>.readiness.json` (small, structured) and relay its `gaps`, then point at `/cohorte-spec <id>`. More passes cannot fix this |
-| `64` | usage | relay the script's own message verbatim |
-
-Then print exactly three lines and nothing else — plus a fourth **only when the verdict carries
-`deferred` > 0** (findings that were real but out of this feature's scope, parked in the backlog by
-`/cohorte-review` §3.5; they are not blocking and never cost a pass, but they are not nothing either):
-
-```
-outcome:    <one clause — clean / ceiling / no verdict / non-convergent / not implementable / usage>
-iterations: <n> review pass(es)<, m fix pass(es) committed>
-remaining:  <blocking count + one short phrase per blocking item, or "none">
-deferred:   <n> parked in specs/refactor-backlog.md — /cohorte-refactor <domain> when you want them
-```
-
-Add at most one follow-up sentence: the next command to run. Never restate a finding's fix, never
-summarize the log, never open the diff. Each fix pass is already committed
-(`loop(<id>): fix pass <i>`) — say so on a non-zero exit, since those commits are the way back.