@rafinery/cli 0.5.0 → 0.7.0

package/lib/claude-config.mjs

@@ -13,6 +13,83 @@ export const RAFA_PERMISSIONS = [
   "Bash(rafa:*)",
 ];
 
+// The M5 sensor hooks (capture engine): SessionStart injects the state digest
+// (staleness · conflicts · active plan), PostToolUse dirty-marks edited code
+// files into .rafa/dirty.jsonl. Both scripts are vendored LOCKSTEP at
+// .claude/rafa/hooks/ and are no-ops outside a rafa-provisioned repo.
+export const RAFA_HOOKS = {
+  SessionStart: {
+    matcher: "startup|resume|clear",
+    command: 'node "$CLAUDE_PROJECT_DIR/.claude/rafa/hooks/session-start.mjs"',
+  },
+  PostToolUse: {
+    matcher: "Edit|Write|MultiEdit|NotebookEdit",
+    command: 'node "$CLAUDE_PROJECT_DIR/.claude/rafa/hooks/post-tool.mjs"',
+  },
+  // The correction reflex (M5 sensor #4): detect correction-shaped prompts,
+  // queue them, and inject the bank-it-now steering at exactly that moment.
+  UserPromptSubmit: {
+    matcher: "*",
+    command: 'node "$CLAUDE_PROJECT_DIR/.claude/rafa/hooks/user-prompt-submit.mjs"',
+  },
+};
+
+// The ambient loop-state statusline (frictionless loop, 2026-07-13). Set ONLY
+// when the dev has no statusline of their own, or theirs is already ours —
+// a configured statusline is the dev's turf, never replaced (merge, don't own).
+export const RAFA_STATUSLINE = {
+  type: "command",
+  command: 'node "$CLAUDE_PROJECT_DIR/.claude/rafa/hooks/statusline.mjs"',
+};
+
+export function mergeStatusLine(targetDir) {
+  const file = settingsPath(targetDir);
+  const existing = readClaudeSettings(targetDir);
+  if (existing && existing.error) {
+    return { skipped: `.claude/settings.json is not valid JSON (${existing.error})` };
+  }
+  const settings = existing ?? {};
+  const cur = settings.statusLine;
+  const ours = typeof cur?.command === "string" && cur.command.includes(".claude/rafa/hooks/statusline.mjs");
+  if (cur && !ours) return { skipped: "you already have a statusline — keeping yours (rafa's shows via `rafa status --line`)" };
+  if (ours && cur.command === RAFA_STATUSLINE.command) return { added: [] };
+  const next = { ...settings, statusLine: { ...RAFA_STATUSLINE } };
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify(next, null, 2) + "\n");
+  return { added: ["statusLine"] };
+}
+
+// Merge rafa's sensor hooks into .claude/settings.json WITHOUT clobbering the
+// dev's own hook config: a rafa hook is recognized by its script path — if any
+// handler for that event already points at .claude/rafa/hooks/<script>, the
+// event is left untouched (matcher/command tuning survives updates). Returns
+// { added: [eventNames] } or { skipped: "reason" }.
+export function mergeClaudeHooks(targetDir, defs = RAFA_HOOKS) {
+  const file = settingsPath(targetDir);
+  const existing = readClaudeSettings(targetDir);
+  if (existing && existing.error) {
+    return { skipped: `.claude/settings.json is not valid JSON (${existing.error})` };
+  }
+  const settings = existing ?? {};
+  const hooks = { ...(settings.hooks ?? {}) };
+  const added = [];
+  for (const [event, def] of Object.entries(defs)) {
+    const groups = Array.isArray(hooks[event]) ? hooks[event] : [];
+    const marker = def.command.match(/\.claude\/rafa\/hooks\/[\w.-]+/)?.[0] ?? def.command;
+    const present = groups.some((g) =>
+      (g?.hooks ?? []).some((h) => typeof h?.command === "string" && h.command.includes(marker)),
+    );
+    if (present) continue;
+    hooks[event] = [...groups, { matcher: def.matcher, hooks: [{ type: "command", command: def.command }] }];
+    added.push(event);
+  }
+  if (added.length === 0 && existing) return { added: [] };
+  const next = { ...settings, hooks };
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify(next, null, 2) + "\n");
+  return { added };
+}
+
 // Merge the repo's .mcp.json server names into the OWNED agent cards' tools
 // lines (ratified 2026-07-12: subagents must be able to reach the repo's MCPs
 // — a Convex repo's mcp__convex tools were structurally invisible to atlas).

package/lib/dirty.mjs

@@ -0,0 +1,114 @@
+// rafa dirty — the cite-graph invalidator's query surface (M5, agent-internal:
+// the conductor runs this at boundaries; devs never need to remember it).
+//
+//   rafa dirty             human view: dirty code files + the brain notes citing them
+//   rafa dirty --json      the same, machine-shaped (conductor bootstrap / spawn prompts)
+//   rafa dirty --consume   clear the queue AFTER a completed scoped refresh — the
+//                          refresh must have shipped (gates + checkpoint/push) first
+//
+// The queue (.rafa/dirty.jsonl) is written by the PostToolUse hook the moment an
+// edit happens (monotonic, no session-end dependency). Citing notes resolve from
+// the LOCAL manifest when one exists (full pull / prior compile); otherwise the
+// mapping is honestly "unresolved here" — counts still serve, and the platform's
+// get_code_context covers work-time recall. Never guesses.
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const DIRTY_FILES_ALARM = 15; // ≥ → recommend /rafa scan --brain-only
+export const CITED_NOTES_ALARM = 10;
+
+export function readDirty(root = process.cwd()) {
+  const file = join(root, ".rafa", "dirty.jsonl");
+  const files = new Map(); // path → last touch
+  if (!existsSync(file)) return { file, files: [] };
+  for (const line of readFileSync(file, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const e = JSON.parse(line);
+      if (e && typeof e.f === "string") files.set(e.f, e.t ?? "");
+    } catch {
+      /* torn line — skip, never fail the query */
+    }
+  }
+  return { file, files: [...files.entries()].map(([f, t]) => ({ f, t })) };
+}
+
+// file → citing notes from the local manifest; null = no manifest here (lazy .rafa).
+export function resolveCiters(root, dirtyFiles) {
+  const path = join(root, ".rafa", "manifest.json");
+  if (!existsSync(path)) return null;
+  let m;
+  try {
+    m = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+  const want = new Set(dirtyFiles);
+  const notes = [];
+  for (const group of [m.notes ?? [], m.improvements ?? []]) {
+    for (const n of group) {
+      const files = [...new Set((n.cites ?? []).filter((c) => want.has(c.file)).map((c) => c.file))];
+      if (files.length) notes.push({ id: n.id, path: n.path, files });
+    }
+  }
+  return notes;
+}
+
+export default async function dirty(args = []) {
+  const ROOT = process.cwd();
+  const { file, files } = readDirty(ROOT);
+
+  if (args.includes("--consume")) {
+    if (files.length === 0) {
+      console.log("✓ dirty queue already clean");
+      return;
+    }
+    writeFileSync(file, "");
+    console.log(
+      `✓ consumed ${files.length} dirty file(s) — do this ONLY after the scoped refresh shipped (gates + checkpoint/push)`,
+    );
+    return;
+  }
+
+  const notes = resolveCiters(ROOT, files.map((e) => e.f));
+  const alarm =
+    files.length >= DIRTY_FILES_ALARM || (notes !== null && notes.length >= CITED_NOTES_ALARM);
+
+  if (args.includes("--json")) {
+    console.log(
+      JSON.stringify(
+        {
+          files: files.map((e) => e.f),
+          notes, // null = unresolved here (no local manifest) — an honest unknown, not zero
+          thresholds: { files: DIRTY_FILES_ALARM, notes: CITED_NOTES_ALARM },
+          alarm,
+        },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  if (files.length === 0) {
+    console.log("✓ dirty queue clean — no code edits recorded since the last brain reconcile");
+    return;
+  }
+  console.log(`${files.length} code file(s) edited since the last brain reconcile:`);
+  for (const e of files) console.log(`  · ${e.f}`);
+  if (notes === null) {
+    console.log("citing notes: unresolved here (lazy .rafa, no local manifest) — recall still");
+    console.log("serves fresh knowledge via the platform; run a scoped refresh from a session.");
+  } else if (notes.length === 0) {
+    console.log("citing notes: none — nothing in the brain cites these files (nothing to refresh).");
+  } else {
+    console.log(`${notes.length} brain note(s) cite them:`);
+    for (const n of notes) console.log(`  · ${n.id}  ←  ${n.files.join(", ")}`);
+  }
+  console.log(
+    alarm
+      ? `⚠ drift past threshold — recommend a brain refresh from main (/rafa scan --brain-only), then \`rafa dirty --consume\`.`
+      : `→ at the next boundary: scoped refresh of the citing notes (atlas re-derives ONLY those → gates → checkpoint), then \`rafa dirty --consume\`.`,
+  );
+}

package/lib/distill.mjs

@@ -61,6 +61,10 @@ async function loadAgentSdk(cwd) {
 const VERDICTS = ["distilled", "refuted", "needs-adjudication"];
 
 export default async function distill(args = []) {
+  // U7 recursion guard, belt-and-braces: the Agent SDK worker must never fire
+  // the M5 session sensors (a worker's own tool calls re-triggering hooks would
+  // loop). The ci-setup workflow sets this too; this covers ad-hoc invocations.
+  process.env.RAFA_HOOKS_DISABLED = "1";
   const branch = args.filter((a) => !a.startsWith("-"))[0];
   if (!args.includes("--headless"))
     die(