@rafinery/cli 0.5.0 → 0.7.0

package/lib/benchmark.mjs

@@ -0,0 +1,573 @@
+// rafa benchmark — the brain-vs-cold token-efficiency proof, productized.
+//
+// Reproduces the 2026-06-03 audit method
+// (examples/sample-brain/audits/2026-06-03-brain-vs-cold-execution.md) as a
+// repeatable harness anyone can point at THEIR scanned repo:
+//
+//   1. Cut TWO isolated git worktrees from the current sha —
+//        A = cold  (agent forbidden from reading .rafa/)
+//        B = brain (reads .rafa/brain/ first as its index)
+//   2. Run the SAME pre-clarified task fixture in each (ship a default modeled on
+//      the audit's "Saved Investigations"; override with --task <file>).
+//   3. Count tokens from the HARNESS counters — never self-reports (audit rule,
+//      :29) — per phase (scope · build · correction) and total, for A and B.
+//   4. Audit the two diffs (which conventions each obeyed/breached).
+//   5. Emit a machine-readable benchmark.json (schema below; consumed by the
+//      benchmark-ingest task / dashboard widget).
+//
+// Honesty — TWO axes, both stamped in the emitted JSON so a consumer can never
+// mistake one class of number for another:
+//   • measured-vs-estimated: a real run's ratio is a MEASURED result of THIS run
+//     on THIS repo — never the dashboard's ESTIMATED baseline.
+//   • real-vs-fixture: `--dry-run` writes the AUDIT's fixture numbers to exercise
+//     the scaffold — those are demo data, NOT a measurement of anything.
+// So the writer stamps `measured` (true only for a real `--counts` run, false for
+// `--dry-run`), `kind` ("measured" | "fixture"), and a matching caveat. And
+// `--dry-run` NEVER writes the consumer path (.rafa/benchmark.json) — it defaults
+// to .rafa/benchmark.demo.json — so fixture data can't be ingested as real.
+// A small repo is close to the worst case for amortization (audit :90) — the gap
+// widens on larger codebases.
+//
+// Automation boundary — SCOPE OF THIS SCAFFOLD:
+//   • worktree cut + seed + cleanup, the default task fixture, per-phase token
+//     INTAKE, the diff-audit step, and the benchmark.json writer are automated.
+//   • `--dry-run` exercises worktree isolation + the writer end-to-end from
+//     built-in fixture counts (the audit's numbers) with NO live agent.
+//   • Full unattended two-agent orchestration is OUT of scope — the two agents
+//     are driven by a human/agent loop (the audit was reviewer-driven). The run
+//     procedure is DOCUMENTED (RUN_PROCEDURE below + `--help`); a measurement is
+//     NEVER faked — real numbers only ever arrive through `--counts <file>`.
+//
+// benchmark.json schema (schemaVersion 1):
+//   {
+//     schemaVersion: 1,
+//     measured,                           // true = real --counts run; false = --dry-run fixture
+//     kind,                               // "measured" (real) | "fixture" (demo). Both ≠ the
+//                                         //   dashboard's ESTIMATED baseline.
+//     repo, codeSha, task, at,            // task = the fixture id
+//     cold:  { phases: {scope,build,correction}, totalTokens },
+//     brain: { phases: {scope,build,correction}, totalTokens },
+//     ratio,                              // coldTotal / brainTotal ("N×")
+//     improvement: { kind, breach?, prevented? },
+//     caveat
+//   }
+
+import { execSync } from "node:child_process";
+import {
+  cpSync,
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+import { callTool } from "./mcp-client.mjs";
+
+const die = (m) => {
+  console.error(`✗ ${m}`);
+  process.exit(1);
+};
+
+// `--name <value>` reader (the lib idiom — see fold.mjs).
+const flag = (args, name) => {
+  const i = args.indexOf(name);
+  return i !== -1 && args[i + 1] && !args[i + 1].startsWith("--")
+    ? args[i + 1]
+    : null;
+};
+
+const sh = (cmd, cwd) =>
+  execSync(cmd, {
+    cwd,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  }).trim();
+
+const SCHEMA_VERSION = 1;
+
+// ── the default task fixture (audit's "Saved Investigations") ────────────────
+// Pre-clarified so the load-bearing design fork is already answered — this
+// isolates EXECUTION cost, exactly as the audit did (both agents got the same
+// open-ended "list the contracts your change depends on"; neither was told
+// which to watch).
+const DEFAULT_TASK = {
+  id: "saved-investigations",
+  title: "Saved Investigations",
+  prompt:
+    "Authenticated /app/investigations: a user creates an investigation, chats with the " +
+    "LangGraph agent; a server tool `recordFinding` appends to CopilotKit shared CoAgent " +
+    "state; investigation + findings persist in Convex scoped to the Clerk user; listed on " +
+    "return visits.",
+  preClarified: [
+    "Persist in Convex, scoped to ctx.auth.getUserIdentity().subject (the Clerk user).",
+    "recordFinding is a SERVER tool that appends to shared CoAgent state.",
+    "Reuse the existing starterAgent graph — do not add a new graph.",
+    "Keep the frontend/backend AgentState shape aligned.",
+  ],
+  // Not handed to the agents (they get the open-ended prompt) — used by the
+  // diff-audit step as ground truth for which conventions to check.
+  conventionsToWatch: [
+    'RSC boundary: "use client" only at the leaf, never route-level (silent breach).',
+    "Convex queries/mutations scoped to the Clerk subject.",
+    "AgentState shape aligned frontend↔backend.",
+    "No new LangGraph graph — reuse starterAgent.",
+  ],
+};
+
+// ── the fixture counts (--dry-run) — the audit's measured numbers ────────────
+// Used ONLY to exercise the writer + isolation without a live agent. NOT a
+// substitute for a real run; a genuine measurement arrives via --counts.
+const FIXTURE_COUNTS = {
+  cold: { scope: 32300, build: 94500, correction: 104700 },
+  brain: { scope: 35200, build: 77300, correction: 0 },
+};
+const FIXTURE_IMPROVEMENT = {
+  kind: "silent-convention",
+  breach:
+    'cold tagged the route "use client", silently disabling RSC down the subtree',
+  prevented: true,
+};
+const MEASURED_CAVEAT =
+  "MEASURED on this repo — not the estimated baseline. A small repo is near the worst " +
+  "case for amortization; the gap widens on larger codebases (audit 2026-06-03, :90).";
+const FIXTURE_CAVEAT =
+  "FIXTURE/DEMO data (the audit's numbers) — NOT a measurement of this repo. Emitted by " +
+  "`rafa benchmark --dry-run` to exercise the scaffold. Run a real agent measurement and " +
+  "emit via `--counts` for a `measured: true` result.";
+
+// ── the diff-audit step ──────────────────────────────────────────────────────
+// Scaffold: given the two worktrees + the fixture's conventionsToWatch, this is
+// where a reviewer (or agent) records which conventions each diff obeyed or
+// breached — the audit's method of judging diffs against ground truth, NOT the
+// agents' self-reports. Without a live run there are no diffs to judge, so the
+// improvement summary is carried in the counts intake (`improvement` field) or
+// the fixture. Kept as a named seam so the real run has one place to fill in.
+function auditDiff({ coldPath, brainPath, task, improvement }) {
+  return {
+    conventionsWatched: task.conventionsToWatch,
+    // A real run populates per-worktree obeyed/breached from the audited diffs.
+    coldWorktree: coldPath,
+    brainWorktree: brainPath,
+    improvement: improvement ?? null,
+  };
+}
+
+// ── the writer ───────────────────────────────────────────────────────────────
+// Assembles benchmark.json from per-phase token counts. Total = sum of the
+// phases (matches the audit arithmetic exactly). ratio = coldTotal / brainTotal.
+//
+// `measured` is LOAD-BEARING and REQUIRED — it is the honesty stamp the a4 ingest
+// keys on. true = a real `--counts` run (kind "measured"); false = `--dry-run`
+// fixture/demo data (kind "fixture"). The caveat matches. A caller that omits it
+// is a bug, so we don't default it — fixture data must never silently inherit the
+// "measured" stamp.
+export function buildResult({
+  repo,
+  codeSha,
+  task,
+  coldPhases,
+  brainPhases,
+  improvement,
+  measured,
+  caveat,
+  at,
+}) {
+  if (typeof measured !== "boolean")
+    die(
+      "buildResult: `measured` (boolean) is required — refusing to emit an unlabeled result.",
+    );
+  const sum = (phases) =>
+    Object.values(phases).reduce(
+      (a, b) => a + (Number.isFinite(Number(b)) ? Number(b) : 0),
+      0,
+    );
+  const coldTotal = sum(coldPhases);
+  const brainTotal = sum(brainPhases);
+  const ratio =
+    brainTotal > 0 ? Number((coldTotal / brainTotal).toFixed(2)) : null;
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    measured, // true = real measurement; false = --dry-run fixture — the a4 ingest keys on this
+    kind: measured ? "measured" : "fixture",
+    repo: repo ?? "",
+    codeSha: codeSha ?? "unknown",
+    task: typeof task === "string" ? task : task.id,
+    at: at ?? new Date().toISOString(),
+    cold: { phases: coldPhases, totalTokens: coldTotal },
+    brain: { phases: brainPhases, totalTokens: brainTotal },
+    ratio,
+    improvement: improvement ?? null,
+    caveat: caveat ?? (measured ? MEASURED_CAVEAT : FIXTURE_CAVEAT),
+  };
+}
+
+// ── worktree plumbing (git — the CLI already owns this surface) ──────────────
+function repoIdentity(root) {
+  let codeSha = "unknown";
+  try {
+    codeSha = sh("git rev-parse --short HEAD", root);
+  } catch {
+    /* no commits yet — fine */
+  }
+  let repo = "";
+  try {
+    const origin = sh("git remote get-url origin", root);
+    const m = origin.match(/[/:]([^/:]+)\/([^/]+?)(?:\.git)?\/?$/);
+    if (m) repo = `${m[1]}/${m[2]}`;
+  } catch {
+    /* no origin */
+  }
+  return { codeSha, repo };
+}
+
+// Cut the two isolated worktrees from the current sha. A=cold has NO .rafa/
+// (worktrees only check out TRACKED files, and .rafa/ is gitignored, so cold is
+// naturally brain-blind). B=brain gets a copy of the live .rafa/brain/ seeded in.
+function cutWorktrees(root) {
+  let sha;
+  try {
+    sha = sh("git rev-parse HEAD", root);
+  } catch {
+    die(
+      "cannot resolve HEAD — run `rafa benchmark` from a repo with at least one commit.",
+    );
+  }
+  const dir = mkdtempSync(join(tmpdir(), "rafa-benchmark-"));
+  const coldPath = join(dir, "cold");
+  const brainPath = join(dir, "brain");
+
+  sh(`git worktree add --detach ${JSON.stringify(coldPath)} ${sha}`, root);
+  sh(`git worktree add --detach ${JSON.stringify(brainPath)} ${sha}`, root);
+
+  // Defensive: cold must never carry a brain (it won't, but enforce the contract).
+  const coldRafa = join(coldPath, ".rafa");
+  if (existsSync(coldRafa)) rmSync(coldRafa, { recursive: true, force: true });
+
+  // Seed the brain worktree from the live brain, if a scan has produced one.
+  const srcBrain = join(root, ".rafa", "brain");
+  let brainSeeded = false;
+  if (existsSync(srcBrain)) {
+    cpSync(srcBrain, join(brainPath, ".rafa", "brain"), { recursive: true });
+    brainSeeded = true;
+  }
+  return { dir, coldPath, brainPath, sha, brainSeeded };
+}
+
+function cleanupWorktrees(root, wt) {
+  for (const p of [wt.coldPath, wt.brainPath]) {
+    try {
+      sh(`git worktree remove --force ${JSON.stringify(p)}`, root);
+    } catch {
+      /* already gone */
+    }
+  }
+  try {
+    rmSync(wt.dir, { recursive: true, force: true });
+  } catch {
+    /* best effort */
+  }
+  try {
+    sh("git worktree prune", root);
+  } catch {
+    /* best effort */
+  }
+}
+
+const countWorktrees = (root) => {
+  try {
+    return sh("git worktree list --porcelain", root)
+      .split("\n")
+      .filter((l) => l.startsWith("worktree ")).length;
+  } catch {
+    return 0;
+  }
+};
+
+// ── the documented run procedure (human/agent-driven measurement) ────────────
+const RUN_PROCEDURE = `Run procedure (the real, agent-driven measurement — orchestration is intentionally
+NOT automated: the two agents are driven by a human/agent loop, as the audit was):
+
+  1. rafa benchmark               # cuts + seeds the two worktrees, prints their paths
+                                    #   and the identical task prompt; leaves them in place
+  2. In worktree A (cold): run your agent on the printed task. It is FORBIDDEN from
+     reading .rafa/. Record the HARNESS token counter (not the agent's self-report)
+     for each phase: scope, build, correction.
+  3. In worktree B (brain): run the SAME agent on the SAME task, told to read
+     .rafa/brain/ FIRST as its index. Record the same per-phase harness counts.
+  4. Audit BOTH diffs against ground truth yourself (the conventionsToWatch) — judge
+     the diffs, not the agents' self-reports. Note which conventions each obeyed or
+     silently breached, and the improvement class it produced.
+  5. Write a counts file, e.g. counts.json:
+       { "cold":  { "scope": N, "build": N, "correction": N },
+         "brain": { "scope": N, "build": N, "correction": N },
+         "improvement": { "kind": "...", "breach": "...", "prevented": true } }
+  6. rafa benchmark --counts counts.json --out benchmark.json
+                                    # emits the MEASURED benchmark.json + cleans up
+  7. rafa benchmark --counts counts.json --push
+                                    # same, and reports it to the platform (agent-key MCP)
+                                    #   → the repo's proof page shows "proven on this repo: N×".
+                                    #   Or push a file you already emitted: rafa benchmark --push
+
+Never invent a number. If you did not run an agent, use --dry-run (fixture counts,
+clearly a demo) — real numbers arrive only through --counts.`;
+
+const USAGE = `rafa benchmark — reproduce the brain-vs-cold token proof on THIS repo (measured).
+
+Usage:
+  rafa benchmark                     Cut + seed the two isolated worktrees and print the
+                                     task + run procedure (leaves worktrees for the
+                                     agent-driven run; finish with --counts).
+  rafa benchmark --counts <file>     Emit benchmark.json from a REAL per-phase counts file
+                                     (harness counters), then clean up the worktrees.
+  rafa benchmark --dry-run           Exercise worktree isolation + the writer end-to-end
+                                     from built-in FIXTURE counts (no live agent), then
+                                     clean up. For verifying the scaffold — clearly a demo.
+                                     Emits measured:false / kind:"fixture".
+
+Every result is stamped: "measured" (true only for a real --counts run, false for --dry-run
+fixture data) and "kind" ("measured" | "fixture"). The ingest keys on "measured" — fixture
+data can never be rendered as a real measurement.
+
+Options:
+  --task <file>      Override the task fixture (JSON: {id,title,prompt,conventionsToWatch}
+                     or a plain .md/.txt used as the prompt). Default: "saved-investigations".
+  --counts <file>    JSON of measured per-phase token counts (see run procedure).
+  --push             Report the MEASURED result to the platform over the agent-key MCP
+                     surface (report_benchmark — same key custody as usage metering), so
+                     the repo's proof page shows "proven on this repo: N×". Refused for
+                     fixture/--dry-run data. Standalone ("rafa benchmark --push") pushes an
+                     already-emitted .rafa/benchmark.json.
+  --out <file>       Where to write the result. Default: .rafa/benchmark.json for a real
+                     --counts run; .rafa/benchmark.demo.json for --dry-run (never the
+                     consumer path, so fixture data can't be ingested as real).
+  --keep             Do not remove the worktrees after emitting (for inspection).
+  --dry-run          Fixture mode (above).
+  -h, --help         This help.
+
+${RUN_PROCEDURE}`;
+
+function loadTask(path) {
+  if (!path) return DEFAULT_TASK;
+  if (!existsSync(path)) die(`--task file not found: ${path}`);
+  const raw = readFileSync(path, "utf8");
+  try {
+    const t = JSON.parse(raw);
+    if (!t.id) t.id = basename(path).replace(/\.[^.]+$/, "");
+    if (!t.conventionsToWatch) t.conventionsToWatch = [];
+    return t;
+  } catch {
+    // Not JSON — treat the whole file as the prompt.
+    return {
+      id: basename(path).replace(/\.[^.]+$/, ""),
+      title: "",
+      prompt: raw,
+      conventionsToWatch: [],
+    };
+  }
+}
+
+function loadCounts(path) {
+  if (!existsSync(path)) die(`--counts file not found: ${path}`);
+  let c;
+  try {
+    c = JSON.parse(readFileSync(path, "utf8"));
+  } catch (e) {
+    die(
+      `--counts file is not valid JSON: ${e instanceof Error ? e.message : String(e)}`,
+    );
+  }
+  if (!c.cold || !c.brain)
+    die(
+      '--counts must be { "cold": {scope,build,correction}, "brain": {…} } (see `rafa benchmark --help`).',
+    );
+  return c;
+}
+
+function writeResult(outPath, result) {
+  writeFileSync(outPath, JSON.stringify(result, null, 2) + "\n");
+}
+
+// ── push the MEASURED result to the platform (a4 transport) ──────────────────
+// Reuses the existing agent-key MCP surface (report_benchmark on the platform,
+// same key custody as log_usage) — no new surface. MEASURED-ONLY on this side
+// too: refuse a fixture/dry-run result before it ever leaves the machine, so the
+// server's honesty gate is never the first line of defence. Best-effort by
+// intent, but a rejected/non-measured push is LOUD (the whole point is proof).
+async function pushResult(root, result) {
+  if (result?.measured !== true)
+    die(
+      "refusing to push a non-measured result (measured:false / kind:fixture) — " +
+        "proof is measured only. Emit a real result via `rafa benchmark --counts <file>`.",
+    );
+  if (typeof result.ratio !== "number" || !(result.ratio > 0))
+    die(
+      "refusing to push a degenerate result (ratio is null/≤0 — brain total was 0). Nothing to prove.",
+    );
+  await callTool(root, "report_benchmark", {
+    measured: true,
+    task: result.task,
+    codeSha: result.codeSha,
+    coldTokens: result.cold.totalTokens,
+    brainTokens: result.brain.totalTokens,
+    ratio: result.ratio,
+    at: result.at,
+  });
+  console.log(
+    `✓ pushed MEASURED result to the platform: ${result.ratio}× on task "${result.task}" ` +
+      `(${result.codeSha}) — the proof page will show "proven on this repo".`,
+  );
+}
+
+export default async function benchmark(args = []) {
+  if (args.includes("-h") || args.includes("--help")) {
+    console.log(USAGE);
+    return;
+  }
+
+  const root = process.cwd();
+  const task = loadTask(flag(args, "--task"));
+  const outFlag = flag(args, "--out");
+  const keep = args.includes("--keep");
+  const dryRun = args.includes("--dry-run");
+  const push = args.includes("--push");
+  const countsFile = flag(args, "--counts");
+  const { codeSha, repo } = repoIdentity(root);
+
+  // Fixture data is NEVER pushed as proof — refuse the combination up front so
+  // the intent is unmistakable (the server would refuse too; fail earlier).
+  if (push && dryRun)
+    die("--push cannot be combined with --dry-run — fixture data is never ingested as proof.");
+
+  // --dry-run NEVER defaults to the consumer path (.rafa/benchmark.json) — fixture
+  // data must not be ingestible as a real measurement. It writes .demo.json unless
+  // the operator explicitly redirects it with --out.
+  const out =
+    outFlag ??
+    join(root, ".rafa", dryRun ? "benchmark.demo.json" : "benchmark.json");
+
+  // ── --dry-run: isolation + writer, end-to-end, from fixture counts ──────────
+  if (dryRun) {
+    const before = countWorktrees(root);
+    console.log("• cutting two isolated worktrees (A=cold · B=brain) …");
+    const wt = cutWorktrees(root);
+    const coldBlind = !existsSync(join(wt.coldPath, ".rafa"));
+    const brainHas =
+      wt.brainSeeded && existsSync(join(wt.brainPath, ".rafa", "brain"));
+    console.log(
+      `  cold  : ${wt.coldPath}  [.rafa present: ${!coldBlind} → ${coldBlind ? "brain-blind ✓" : "LEAK ✗"}]`,
+    );
+    console.log(
+      `  brain : ${wt.brainPath}  [.rafa/brain seeded: ${brainHas ? "yes ✓" : wt.brainSeeded ? "no ✗" : "no source brain — run a scan first"}]`,
+    );
+    console.log(`  worktrees now: ${countWorktrees(root)} (was ${before})`);
+
+    const audit = auditDiff({
+      coldPath: wt.coldPath,
+      brainPath: wt.brainPath,
+      task,
+      improvement: FIXTURE_IMPROVEMENT,
+    });
+    const result = buildResult({
+      repo,
+      codeSha,
+      task,
+      coldPhases: FIXTURE_COUNTS.cold,
+      brainPhases: FIXTURE_COUNTS.brain,
+      improvement: audit.improvement,
+      measured: false, // fixture/demo — stamped kind:"fixture", never ingested as real
+    });
+    writeResult(out, result);
+    console.log(
+      `• [DRY-RUN — fixture counts, NOT a real measurement · measured:false kind:fixture] wrote ${out}: ` +
+        `${result.ratio}× (cold ${result.cold.totalTokens} / brain ${result.brain.totalTokens})`,
+    );
+
+    cleanupWorktrees(root, wt);
+    console.log(
+      `✓ worktrees cleaned up: ${countWorktrees(root)} remaining (was ${before})`,
+    );
+    console.log(
+      "  Real numbers only via a live agent run — see `rafa benchmark --help`.",
+    );
+    return;
+  }
+
+  // ── --counts <file>: emit the MEASURED result from real intake ─────────────
+  if (countsFile) {
+    const counts = loadCounts(countsFile);
+    const result = buildResult({
+      repo,
+      codeSha,
+      task,
+      coldPhases: counts.cold,
+      brainPhases: counts.brain,
+      improvement: counts.improvement ?? null,
+      measured: true, // real intake — stamped kind:"measured"
+    });
+    writeResult(out, result);
+    console.log(
+      `✓ wrote MEASURED ${out}: ${result.ratio}× on task "${result.task}" ` +
+        `(cold ${result.cold.totalTokens} / brain ${result.brain.totalTokens} · ${codeSha})`,
+    );
+    // Push it to the platform if asked (reuses the agent-key MCP surface).
+    if (push) await pushResult(root, result);
+    // If worktrees from a prior `rafa benchmark` setup are lingering, prune them
+    // unless the operator asked to keep them.
+    if (!keep) {
+      try {
+        sh("git worktree prune", root);
+      } catch {
+        /* best effort */
+      }
+    }
+    return;
+  }
+
+  // ── --push (standalone): push an already-emitted MEASURED benchmark.json ────
+  // For the two-step flow — `--counts` writes the file, a later `--push` sends
+  // it. Reads the resolved --out (default .rafa/benchmark.json); the measured
+  // gate in pushResult refuses fixture/degenerate data.
+  if (push) {
+    if (!existsSync(out))
+      die(
+        `no ${out} to push — run \`rafa benchmark --counts <file>\` first (or pass --out <file>).`,
+      );
+    let result;
+    try {
+      result = JSON.parse(readFileSync(out, "utf8"));
+    } catch (e) {
+      die(`${out} is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    await pushResult(root, result);
+    return;
+  }
+
+  // ── default: set up the run for the human/agent loop ───────────────────────
+  console.log(
+    "• cutting two isolated worktrees for the agent-driven measurement …",
+  );
+  const wt = cutWorktrees(root);
+  console.log(`  cold  (A, brain-blind): ${wt.coldPath}`);
+  console.log(
+    `  brain (B, reads .rafa/brain): ${wt.brainPath}` +
+      (wt.brainSeeded
+        ? ""
+        : "  ! no .rafa/brain to seed — run `/rafa scan` first, else B runs cold too"),
+  );
+  console.log(
+    `\n  Task "${task.id}"${task.title ? ` — ${task.title}` : ""}:\n    ${task.prompt}`,
+  );
+  if (task.preClarified?.length)
+    console.log(
+      "\n  Pre-clarified (both agents get these):\n" +
+        task.preClarified.map((p) => `    • ${p}`).join("\n"),
+    );
+  console.log("\n" + RUN_PROCEDURE);
+  console.log(
+    `\n  When done: rafa benchmark --counts <file> --out ${out}` +
+      "  (add --push to report it to the platform's proof page)" +
+      "\n  Or discard: git worktree remove --force <path> (both), then git worktree prune.",
+  );
+}

package/lib/blueprint.mjs

@@ -30,6 +30,7 @@ export const BLUEPRINT = {
     ".claude/agents/prism.md",
     ".claude/agents/bloom.md",
     ".claude/agents/compass.md",
+    ".claude/agents/sage.md",
     ".claude/commands/rafa.md",
   ],
   ownedDirs: [
@@ -41,8 +42,13 @@ export const BLUEPRINT = {
     ".claude/skills/rafa-distill",
     ".claude/skills/rafa-insights",
     ".claude/skills/rafa-leverage",
+    ".claude/skills/rafa-sage",
   ],
   lockstep: [".claude/rafa/contract.md"],
+  // The M5 sensor hooks — deterministic protocol machinery (like the contract):
+  // they move with the CLI version, clients don't tune them. NOT knowledge —
+  // the brain (.rafa/) stays executable-free; these live in the code repo.
+  lockstepDirs: [".claude/rafa/hooks"],
 };
 
 const HERE = dirname(fileURLToPath(import.meta.url)); // …/packages/cli/lib
@@ -96,7 +102,11 @@ export function blueprintFiles(from) {
     ...BLUEPRINT.owned,
     ...BLUEPRINT.ownedDirs.flatMap((d) => filesUnder(from, d)),
   ];
-  return { owned, lockstep: [...BLUEPRINT.lockstep] };
+  const lockstep = [
+    ...BLUEPRINT.lockstep,
+    ...(BLUEPRINT.lockstepDirs ?? []).flatMap((d) => filesUnder(from, d)),
+  ];
+  return { owned, lockstep };
 }
 
 function sameBytes(a, b) {

package/lib/brain-repo.mjs

@@ -6,7 +6,7 @@
 // which materializes the skeleton + git wiring from the committed rafa.json so
 // `clone → npx rafa <cmd>` just works with no init step on the machine.
 
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { execSync } from "node:child_process";
 import { join } from "node:path";
 import { readStamp } from "./stamp.mjs";
@@ -73,10 +73,16 @@ export function ensureBrainRepo(cwd, { requireRemote = true } = {}) {
   }
 
   // Session/state debris never rides a brain push: the sidecar, conflict
-  // copies, and distill staging are transport-excluded here (not knowledge).
+  // copies, distill staging, and the M5 dirty queue are transport-excluded here
+  // (not knowledge). MERGED line-by-line so clones ignored under an older CLI
+  // still gain new exclusions.
   const ignore = join(rafaDir, ".gitignore");
-  const IGNORES = "hydration.json\n*.theirs.md\ndistill-incoming/\ndistill-verdicts.json\n";
-  if (!existsSync(ignore)) writeFileSync(ignore, IGNORES);
+  const IGNORES = ["hydration.json", "*.theirs.md", "distill-incoming/", "distill-verdicts.json", "dirty.jsonl", "reflex.jsonl"];
+  const cur = existsSync(ignore) ? readFileSync(ignore, "utf8") : "";
+  const have = new Set(cur.split("\n").map((l) => l.trim()).filter(Boolean));
+  const missing = IGNORES.filter((l) => !have.has(l));
+  if (missing.length)
+    writeFileSync(ignore, cur + (cur === "" || cur.endsWith("\n") ? "" : "\n") + missing.join("\n") + "\n");
 
   return { rafaDir, remote, bootstrapped };
 }

package/lib/ci-setup.mjs

@@ -46,6 +46,7 @@ jobs:
       - name: Mechanical fold (no LLM — rigor lives at main)
         env:
           RAFA_MCP_KEY: \${{ secrets.RAFA_MCP_KEY }}
+          RAFA_HOOKS_DISABLED: "1" # headless — the M5 sensors are session instruments
         run: npx -y @rafinery/cli fold --from "\${{ github.event.pull_request.head.ref }}" --to "\${{ github.event.pull_request.base.ref }}"
 
   distill:
@@ -66,6 +67,7 @@ jobs:
           ANTHROPIC_API_KEY: \${{ secrets.ANTHROPIC_API_KEY }}
           RAFA_MCP_KEY: \${{ secrets.RAFA_MCP_KEY }}
           RAFA_BRAIN_TOKEN: \${{ secrets.RAFA_BRAIN_TOKEN }}
+          RAFA_HOOKS_DISABLED: "1" # headless — the M5 sensors are session instruments
         run: npx -y @rafinery/cli distill --headless "\${{ github.event.pull_request.head.ref }}"
 `;