@rafinery/cli 0.5.0 → 0.6.0

package/lib/githook.mjs

@@ -0,0 +1,54 @@
+// The git pre-push hook installer — M5 sensor #3 (the deterministic checkpoint
+// boundary). `git push` of the code branch is a ratified natural checkpoint
+// moment; this hook makes it MECHANICAL instead of SOP-remembered.
+//
+// .git/hooks is per-clone (git never versions it), so this runs at init AND
+// pull (the teammate path) AND update — every working copy gets the sensor.
+// Never clobbers a foreign hook: ours is recognized by its marker line; anything
+// else is respected and the chain-line printed for the dev to add themselves.
+
+import { chmodSync, copyFileSync, existsSync, readFileSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { join } from "node:path";
+
+const MARKER = "rafa pre-push hook";
+const CHAIN_LINE = "npx -y @rafinery/cli checkpoint || true";
+
+export function installPrePush(targetDir) {
+  const src = join(targetDir, ".claude", "rafa", "hooks", "pre-push");
+  if (!existsSync(src)) return { skipped: "no vendored hook template (run `rafa update`)" };
+
+  let hooksDir;
+  try {
+    // --git-path resolves worktrees/submodules correctly; never assume .git is a dir.
+    hooksDir = execSync("git rev-parse --git-path hooks", { cwd: targetDir, encoding: "utf8" }).trim();
+    hooksDir = join(targetDir, hooksDir);
+  } catch {
+    return { skipped: "not a git repo" };
+  }
+
+  const dst = join(hooksDir, "pre-push");
+  if (existsSync(dst)) {
+    const body = readFileSync(dst, "utf8");
+    if (!body.includes(MARKER)) {
+      return {
+        skipped:
+          "a pre-push hook already exists (not rafa's) — to chain the checkpoint boundary, " +
+          `add this line to it yourself:  ${CHAIN_LINE}`,
+      };
+    }
+    // ours → refresh in place (idempotent update)
+    copyFileSync(src, dst);
+    chmodSync(dst, 0o755);
+    return { updated: true };
+  }
+  copyFileSync(src, dst);
+  chmodSync(dst, 0o755);
+  return { installed: true };
+}
+
+export function reportGitHook(r) {
+  if (r.installed) console.log("  ✓ git pre-push hook → checkpoint runs at every code push (non-blocking)");
+  else if (r.updated) console.log("  ✓ git pre-push hook refreshed");
+  else if (r.skipped) console.log(`  ! git pre-push hook not installed — ${r.skipped}`);
+}

package/lib/init.mjs

@@ -105,6 +105,24 @@ export default async function init(args) {
   );
   // Grant rafa's tools their permissions (merge, never overwrite).
   reportSettings(TARGET);
+  // Wire the M5 sensor hooks (SessionStart digest + PostToolUse dirty-marker)
+  // into .claude/settings.json — merge, never clobber the dev's own hooks.
+  {
+    const { mergeClaudeHooks, mergeStatusLine } = await import("./claude-config.mjs");
+    const h = mergeClaudeHooks(TARGET);
+    if (h.skipped) console.log(`  ! hooks untouched — ${h.skipped}`);
+    else if (h.added?.length) console.log(`  ✓ sensor hooks → .claude/settings.json (${h.added.join(", ")})`);
+    else console.log("  ✓ sensor hooks already wired");
+    const sl = mergeStatusLine(TARGET);
+    if (sl.skipped) console.log(`  ! statusline untouched — ${sl.skipped}`);
+    else if (sl.added?.length) console.log("  ✓ loop-state statusline → .claude/settings.json");
+    else console.log("  ✓ loop-state statusline already wired");
+  }
+  // The pre-push checkpoint boundary is per-clone (.git/hooks is never committed).
+  {
+    const { installPrePush, reportGitHook } = await import("./githook.mjs");
+    reportGitHook(installPrePush(TARGET));
+  }
   // Wire the repo's own MCP servers into the (owned) agent cards so subagents
   // can actually reach them (zero-command orchestration, 2026-07-12).
   {

package/lib/pull.mjs

@@ -32,6 +32,13 @@ export default async function pull(args = []) {
   const inRafa = inDir(rafaDir);
   if (bootstrapped) console.log(`• bootstrapped lazy .rafa/ from rafa.json (remote: ${remote})`);
 
+  // Every working copy gets the M5 checkpoint boundary (.git/hooks is per-clone —
+  // pull IS the teammate path, so this is where a fresh clone gains the sensor).
+  {
+    const { installPrePush, reportGitHook } = await import("./githook.mjs");
+    reportGitHook(installPrePush(ROOT));
+  }
+
   // Reachability + default branch — loud if the remote can't be reached.
   let branch = "main";
   try {

package/lib/push.mjs

@@ -13,6 +13,7 @@ import { execSync } from "node:child_process";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { runCompile } from "./gate/compile.mjs";
+import { runVerifyCitations } from "./gate/verify-citations.mjs";
 import { ensureBrainRepo, remoteDefaultBranch, inDir, die } from "./brain-repo.mjs";
 import { CLI_VERSION } from "./releases.mjs";
 
@@ -39,6 +40,26 @@ export default async function push(args = []) {
     /* no origin — manifest.repo stays "" */
   }
 
+  // ── citation gate (in-process) ──
+  // Re-run the checker HERE so the record that rides the push is the record of
+  // THIS push — a stale/hand-stamped citation-check.json can never ship
+  // (mechanized 2026-07-13 from prism's live-run recommendation: the stale-record
+  // class dies at the transport layer, not in review).
+  console.log("• rafa verify-citations — re-grounding every cite/absence/inventory …");
+  if (runVerifyCitations([]) !== 0)
+    die(
+      "citations failed the checker (see report above). Fix the notes against the " +
+        "code (or have atlas repair them), then re-push.",
+    );
+  if (
+    existsSync(join(ROOT, ".rafa", "improve", "improvements")) &&
+    runVerifyCitations(["--root=.rafa/improve", "--dirs=improvements"]) !== 0
+  )
+    die(
+      "improvement citations failed the checker (see report above). Fix the ledger " +
+        "files against the code (or have bloom correct them), then re-push.",
+    );
+
   // ── contract gate (in-process) ──
   // Compile + validate the brain. A schema-invalid brain NEVER leaves the machine —
   // the platform ingests JSON, so what we push must already conform to the contract.

package/lib/reflex.mjs

@@ -0,0 +1,76 @@
+// rafa reflex — the correction queue's query/consume surface (M5, agent-internal;
+// the UserPromptSubmit sensor writes the queue, the conductor works it).
+//
+//   rafa reflex                    list unprocessed corrections
+//   rafa reflex --json             machine shape (bootstrap digest / spawn prompts)
+//   rafa reflex --consume <id> [reason]   mark one processed — AFTER it was banked
+//                                  through the gates, or judged session-only
+//
+// Consume APPENDS a done-marker line ({id, done:true, verdict, at}) — the queue
+// is append-only like every M5 sensor stream (monotonic, torn-line tolerant);
+// readers treat the latest line per id as truth. Nothing here ever ships: the
+// queue is transport-excluded; only distilled cited notes pass the gates.
+
+import { appendFileSync, existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export function readReflex(root = process.cwd()) {
+  const file = join(root, ".rafa", "reflex.jsonl");
+  const byId = new Map(); // id → latest entry (done-markers override)
+  if (!existsSync(file)) return { file, pending: [], done: 0 };
+  for (const line of readFileSync(file, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const e = JSON.parse(line);
+      if (e?.id) byId.set(e.id, { ...(byId.get(e.id) ?? {}), ...e });
+    } catch {
+      /* torn line — skip */
+    }
+  }
+  const all = [...byId.values()];
+  return {
+    file,
+    pending: all.filter((e) => !e.done),
+    done: all.filter((e) => e.done).length,
+  };
+}
+
+export default async function reflex(args = []) {
+  const ROOT = process.cwd();
+  const { file, pending, done } = readReflex(ROOT);
+
+  const ci = args.indexOf("--consume");
+  if (ci !== -1) {
+    const id = args[ci + 1];
+    if (!id || id.startsWith("-")) {
+      console.error("✗ usage: rafa reflex --consume <id> [banked|session-only|refuted]");
+      process.exit(1);
+    }
+    if (!pending.some((e) => e.id === id)) {
+      console.error(`✗ no unprocessed correction with id ${id} (see \`rafa reflex\`)`);
+      process.exit(1);
+    }
+    const verdict = args[ci + 2] && !args[ci + 2].startsWith("-") ? args[ci + 2] : "banked";
+    appendFileSync(
+      file,
+      JSON.stringify({ id, done: true, verdict, at: new Date().toISOString() }) + "\n",
+    );
+    console.log(`✓ correction ${id} consumed (${verdict})`);
+    return;
+  }
+
+  if (args.includes("--json")) {
+    console.log(JSON.stringify({ pending, done }, null, 2));
+    return;
+  }
+
+  if (pending.length === 0) {
+    console.log(`✓ reflex queue clean${done ? ` (${done} processed)` : ""} — no unbanked corrections`);
+    return;
+  }
+  console.log(`${pending.length} unprocessed correction(s):`);
+  for (const e of pending) console.log(`  · ${e.id} [${e.t}] "${e.p}"`);
+  console.log(
+    "→ for each: bank it through the gates if it's durable repo knowledge (branch: note + checkpoint · main: full gates), then `rafa reflex --consume <id>` — or consume with `session-only` if it isn't.",
+  );
+}

package/lib/releases.mjs

@@ -133,6 +133,41 @@ export const RELEASES = [
       "files mechanically (parent→epic, child→task, blocked→todo+blocked_reason). Brain data " +
       "schema unchanged; no re-scan.",
   },
+  {
+    version: "0.6.0",
+    contract: 1,
+    plans: 2,
+    requires: "update",
+    summary:
+      "The core-solidity release — checker v2 + the M5 capture engine. RATCHET: " +
+      "verify-citations gains the two 2026-06-08 catches as gates — ABSENCE (declared " +
+      "`absent:` tokens re-grepped every run; a stale absence claim fails at gate 1) and " +
+      "INVENTORY (coverage `inventory: <name> :: <glob> :: <count>` recomputed via git " +
+      "ls-files; surface drift fails) — plus a non-failing WARN heuristic for undeclared " +
+      "absence-shaped claims (prism's worklist). The checker records its run " +
+      "(citation-check.json) and compile folds it into manifest.citations {checkerVersion, " +
+      "pass, at} — the platform learns which gate level a brain passed. M5 SENSORS " +
+      "(deterministic capture moments — no more SOP-only checkpoints): SessionStart state " +
+      "digest (staleness · conflicts · active plan), PostToolUse dirty-marking " +
+      "(.rafa/dirty.jsonl, monotonic, no session-end dependency), git pre-push runs " +
+      "`rafa checkpoint` (non-blocking; installed per-clone at init/pull/update). New " +
+      "`rafa dirty [--json|--consume]` — the cite-graph invalidator's query surface: dirty " +
+      "files → citing notes → scoped refresh offer at boundaries; drift threshold → " +
+      "fire-alarm (/rafa scan --brain-only). Hooks vendor LOCKSTEP at .claude/rafa/hooks/ " +
+      "and are disabled in headless/CI runs (RAFA_HOOKS_DISABLED=1 — the recursion guard). " +
+      "THE CORRECTION REFLEX: correction-shaped prompts are queued (.rafa/reflex.jsonl) and " +
+      "steer the session to validate + bank them through the gates SAME-SESSION (rafa reflex " +
+      "--consume closes each with a verdict; ungroundable claims never bank). " +
+      "THE FRICTIONLESS LOOP: loop-state statusline (rafa ▸ plan 2/5 · 3 stale · 1 correction; " +
+      "never replaces a dev's own statusline; `rafa status --line|--json` is the harness-" +
+      "neutral core — Claude Code today, Cursor/Codex adapters later) · a deterministic " +
+      "'suggested next' line in the session digest · DIRECT-DO routing (small work = no plan " +
+      "files, no approval; escalates only when it grows) · brainstorm mode (grounded " +
+      "participant, one crystallization offer). " +
+      "`rafa push` now re-runs the checker itself (stale/hand-stamped check records can " +
+      "never ship). Brain data schema unchanged; no re-scan; adopt with `rafa update` " +
+      "(re-vendors hooks, merges settings + statusline, installs the pre-push boundary).",
+  },
 ];
 
 // The release this CLI build ships (last entry).

package/lib/status.mjs

@@ -0,0 +1,152 @@
+// rafa status — the loop-state read, HARNESS-NEUTRAL CORE (portability
+// directive, 2026-07-13: built for Claude Code now, ships for Cursor/Codex
+// later — the logic lives HERE; harness adapters stay thin mirrors).
+//
+//   rafa status           human view of where the loop stands
+//   rafa status --line    the one-line ambient form (statuslines, prompts, TUIs)
+//   rafa status --json    machine shape (adapters, conductors, other harnesses)
+//
+// Reads ONLY local state (the queues + plans + active pointer) — fast, offline,
+// no network. The Claude Code statusline adapter (.claude/rafa/hooks/
+// statusline.mjs) mirrors this computation as a self-contained script; any
+// drift between the two is a bug against THIS file's semantics.
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+function readJsonl(file, pick) {
+  if (!existsSync(file)) return [];
+  const out = [];
+  for (const line of readFileSync(file, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const e = JSON.parse(line);
+      if (e) out.push(e);
+    } catch {
+      /* torn line */
+    }
+  }
+  return pick ? pick(out) : out;
+}
+
+function walk(dir, depth, hit, out = []) {
+  if (depth < 0 || !existsSync(dir)) return out;
+  for (const e of readdirSync(dir)) {
+    if (e === ".git") continue;
+    const p = join(dir, e);
+    try {
+      if (statSync(p).isDirectory()) walk(p, depth - 1, hit, out);
+      else if (hit(e)) out.push(p);
+    } catch {
+      /* races are fine */
+    }
+  }
+  return out;
+}
+
+// Frontmatter line-scan (the hooks' shared idiom — never a YAML parser).
+function fmField(path, key) {
+  try {
+    const lines = readFileSync(path, "utf8").split("\n");
+    let fence = 0;
+    for (const line of lines) {
+      if (line.trim() === "---") { fence++; if (fence >= 2) break; continue; }
+      if (fence !== 1) continue;
+      const m = line.match(new RegExp(`^${key}:\\s*(.+?)\\s*$`));
+      if (m) return m[1].replace(/\s+#.*$/, "").replace(/^["']|["']$/g, "").trim();
+    }
+  } catch {
+    /* unreadable = absent */
+  }
+  return null;
+}
+
+// The whole loop state, from local files only.
+export function computeStatus(root = process.cwd()) {
+  const rafaDir = join(root, ".rafa");
+  const provisioned = existsSync(join(root, "rafa.json"));
+
+  // dirty: unique files
+  const dirty = new Set(
+    readJsonl(join(rafaDir, "dirty.jsonl")).filter((e) => typeof e.f === "string").map((e) => e.f),
+  ).size;
+
+  // reflex: pending = latest-per-id without a done marker
+  const byId = new Map();
+  for (const e of readJsonl(join(rafaDir, "reflex.jsonl"))) {
+    if (e.id) byId.set(e.id, { ...(byId.get(e.id) ?? {}), ...e });
+  }
+  const reflex = [...byId.values()].filter((e) => !e.done).length;
+
+  // checkpoint conflicts awaiting a human
+  const conflicts = walk(rafaDir, 4, (n) => n.endsWith(".theirs.md")).length;
+
+  // active plan + task progress (plans v2: kind task|subtask, status done|…)
+  let plan = null;
+  const activePath = join(rafaDir, "active.md");
+  if (existsSync(activePath)) {
+    const first = readFileSync(activePath, "utf8").split("\n")[0].trim();
+    const id = first.startsWith("# ") && first !== "# No active plan" ? first.slice(2).trim() : null;
+    if (id) {
+      let done = 0;
+      let total = 0;
+      let current = null;
+      for (const f of walk(join(rafaDir, "plans"), 3, (n) => n.endsWith(".md") && !n.startsWith("_"))) {
+        if (fmField(f, "plan") !== id) continue;
+        const kind = fmField(f, "kind");
+        if (kind !== "task" && kind !== "subtask") continue;
+        total++;
+        const status = fmField(f, "status");
+        if (status === "done") done++;
+        else if (status === "in-progress" && !current)
+          current = fmField(f, "title") ?? fmField(f, "id");
+      }
+      plan = { id, done, total, current };
+    }
+  }
+
+  return { provisioned, plan, dirty, reflex, conflicts };
+}
+
+// The ambient one-liner — identical semantics wherever it renders.
+export function formatLine(s) {
+  if (!s.provisioned) return "";
+  const parts = [];
+  if (s.plan)
+    parts.push(
+      `plan ${s.plan.id} ${s.plan.done}/${s.plan.total}` +
+        (s.plan.current ? ` → ${s.plan.current}` : ""),
+    );
+  if (s.dirty) parts.push(`${s.dirty} stale`);
+  if (s.reflex) parts.push(`${s.reflex} correction${s.reflex === 1 ? "" : "s"}`);
+  if (s.conflicts) parts.push(`${s.conflicts} conflict${s.conflicts === 1 ? "" : "s"}`);
+  return parts.length ? `rafa ▸ ${parts.join(" · ")}` : "rafa ▸ in sync";
+}
+
+export default async function status(args = []) {
+  const s = computeStatus(process.cwd());
+  if (args.includes("--json")) {
+    console.log(JSON.stringify(s, null, 2));
+    return;
+  }
+  if (args.includes("--line")) {
+    const line = formatLine(s);
+    if (line) console.log(line);
+    return;
+  }
+  if (!s.provisioned) {
+    console.log("not a rafa repo (no rafa.json) — `npx @rafinery/cli init` to provision");
+    return;
+  }
+  console.log(formatLine(s));
+  if (s.plan)
+    console.log(
+      `  plan: ${s.plan.id} — ${s.plan.done}/${s.plan.total} tasks done` +
+        (s.plan.current ? ` · in progress: ${s.plan.current}` : ""),
+    );
+  if (s.dirty) console.log(`  stale: ${s.dirty} code file(s) touched since last reconcile (rafa dirty)`);
+  if (s.reflex) console.log(`  corrections: ${s.reflex} unprocessed (rafa reflex)`);
+  if (s.conflicts) console.log(`  conflicts: ${s.conflicts} .theirs.md awaiting your decision`);
+  if (!s.plan && !s.dirty && !s.reflex && !s.conflicts)
+    console.log("  nothing pending — the loop is closed.");
+}

package/lib/update.mjs

@@ -38,6 +38,19 @@ export default async function update(args = []) {
     const r = mergeRepoMcpsIntoCards(TARGET);
     for (const u of r.updated) console.log(`  ✓ repo MCPs → ${u}`);
   }
+  // M5 sensors: hooks config (merge, never clobber) + the per-clone pre-push
+  // boundary + the ambient loop-state statusline.
+  {
+    const { mergeClaudeHooks, mergeStatusLine } = await import("./claude-config.mjs");
+    const h = mergeClaudeHooks(TARGET);
+    if (h.skipped) console.log(`  ! hooks untouched — ${h.skipped}`);
+    else if (h.added?.length) console.log(`  ✓ sensor hooks → .claude/settings.json (${h.added.join(", ")})`);
+    const sl = mergeStatusLine(TARGET);
+    if (sl.skipped) console.log(`  ! statusline untouched — ${sl.skipped}`);
+    else if (sl.added?.length) console.log("  ✓ loop-state statusline → .claude/settings.json");
+    const { installPrePush, reportGitHook } = await import("./githook.mjs");
+    reportGitHook(installPrePush(TARGET));
+  }
 
   // ── Blueprint-side migrations: mechanical/deterministic, run here in the CLI. ──
   // (Anything needing intelligence is left for the brain-side pass — /rafa update.)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rafinery/cli",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "rafa — the AI engineer CLI. Vendors the rafa blueprint into your repo (shadcn-style) and runs the deterministic contract gates.",
   "type": "module",
   "bin": {