@rafinery/cli 0.5.0 → 0.6.0

package/blueprint/.claude/rafa/hooks/session-start.mjs

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+// rafa hook · SessionStart (startup|resume|clear) — the state digest.
+//
+// M5 capture engine, sensor #2: the session starts KNOWING instead of assuming —
+// staleness (dirty code files → the brain notes citing them, via the local manifest
+// or the platform's get_code_context), pending checkpoint conflicts (*.theirs.md),
+// and the active plan. State, never activity (no-gossip principle: nothing here
+// narrates what other devs did — only what THIS working copy's brain plane looks like).
+//
+// Everything printed to stdout lands in Claude's context. Silence = nothing to
+// report (the honest digest). Budget: local reads + ONE optional platform call
+// (get_code_context batch, ≤ 2s, fail-soft to local counts). Never blocks a
+// session: every path exits 0. Honors RAFA_HOOKS_DISABLED=1.
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const DIRTY_FILES_ALARM = 15; // ≥ → recommend /rafa scan --brain-only (the fire-alarm rung)
+const CITED_NOTES_ALARM = 10;
+const MCP_BUDGET_MS = 2000;
+const MCP_MAX_FILES = 6;
+
+function readJson(file) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function dirtyEntries(rafaDir) {
+  const f = join(rafaDir, "dirty.jsonl");
+  if (!existsSync(f)) return [];
+  const files = new Map(); // path → latest touch
+  for (const line of readFileSync(f, "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 {
+      /* a torn line never breaks the digest */
+    }
+  }
+  return [...files.keys()];
+}
+
+// file → citing note ids, from the LOCAL manifest (a full pull / prior compile).
+function citersFromManifest(rafaDir, files) {
+  const m = readJson(join(rafaDir, "manifest.json"));
+  if (!m || !Array.isArray(m.notes)) return null;
+  const want = new Set(files);
+  const byNote = new Map();
+  for (const group of [m.notes, Array.isArray(m.improvements) ? m.improvements : []]) {
+    for (const n of group) {
+      const hits = (n.cites ?? []).filter((c) => want.has(c.file)).map((c) => c.file);
+      if (hits.length) byNote.set(n.id, [...new Set(hits)]);
+    }
+  }
+  return byNote;
+}
+
+// Fallback: the platform's inverted cite graph (get_code_context), fail-soft.
+async function citersFromPlatform(root, files) {
+  const stamp = readJson(join(root, "rafa.json"));
+  const repoId = stamp?.repoId;
+  if (!repoId) return null;
+  let key = process.env.RAFA_MCP_KEY || null;
+  let url = null;
+  const local = readJson(join(root, ".claude", "settings.local.json"));
+  if (!key && local?.env?.RAFA_MCP_KEY) key = local.env.RAFA_MCP_KEY;
+  const creds = readJson(join(homedir(), ".config", "rafinery", "credentials.json"));
+  const entry = creds?.repos?.[repoId];
+  if (!key && entry?.key) key = entry.key;
+  if (entry?.mcpUrl) url = entry.mcpUrl;
+  if (!key || !url || typeof fetch !== "function") return null;
+
+  const byNote = new Map();
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), MCP_BUDGET_MS);
+  try {
+    await Promise.all(
+      files.slice(0, MCP_MAX_FILES).map(async (path, i) => {
+        const res = await fetch(url, {
+          method: "POST",
+          signal: ctrl.signal,
+          headers: { "content-type": "application/json", authorization: `Bearer ${key}` },
+          body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: i + 1,
+            method: "tools/call",
+            params: { name: "get_code_context", arguments: { path } },
+          }),
+        });
+        if (!res.ok) return;
+        const rpc = await res.json();
+        const text = rpc?.result?.content?.[0]?.text;
+        const env = typeof text === "string" ? JSON.parse(text) : text;
+        for (const ref of [...(env?.notes ?? []), ...(env?.improvements ?? [])]) {
+          const id = ref?.id;
+          if (!id) continue;
+          if (!byNote.has(id)) byNote.set(id, []);
+          byNote.get(id).push(path);
+        }
+      }),
+    );
+  } catch {
+    return null; // offline / slow / shape drift → local counts still serve
+  } finally {
+    clearTimeout(timer);
+  }
+  return byNote.size ? byNote : null;
+}
+
+// Unprocessed corrections (the reflex queue) — monotonic; an abandoned session
+// loses nothing because the next session starts by seeing these.
+function pendingCorrections(rafaDir) {
+  const f = join(rafaDir, "reflex.jsonl");
+  if (!existsSync(f)) return [];
+  const out = [];
+  for (const line of readFileSync(f, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const e = JSON.parse(line);
+      if (e && e.id && !e.done) out.push(e);
+    } catch {
+      /* torn line never breaks the digest */
+    }
+  }
+  return out;
+}
+
+function conflictCopies(rafaDir) {
+  const out = [];
+  const walk = (dir, depth) => {
+    if (depth > 4 || !existsSync(dir)) return;
+    for (const e of readdirSync(dir)) {
+      if (e === ".git") continue;
+      const p = join(dir, e);
+      try {
+        if (statSync(p).isDirectory()) walk(p, depth + 1);
+        else if (e.endsWith(".theirs.md")) out.push(p.slice(rafaDir.length + 1));
+      } catch {
+        /* races are fine */
+      }
+    }
+  };
+  walk(rafaDir, 0);
+  return out;
+}
+
+try {
+  if (process.env.RAFA_HOOKS_DISABLED === "1") process.exit(0);
+  const root = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  if (!existsSync(join(root, "rafa.json"))) process.exit(0);
+  const rafaDir = join(root, ".rafa");
+
+  const lines = [];
+
+  const dirty = dirtyEntries(rafaDir);
+  if (dirty.length) {
+    let byNote = citersFromManifest(rafaDir, dirty);
+    if (byNote === null || byNote.size === 0) byNote = (await citersFromPlatform(root, dirty)) ?? byNote;
+    const noteIds = byNote ? [...byNote.keys()] : [];
+    const shown = noteIds.slice(0, 8).join(", ") + (noteIds.length > 8 ? ` (+${noteIds.length - 8} more)` : "");
+    lines.push(
+      `[rafa · staleness] ${dirty.length} code file(s) edited since the last brain reconcile` +
+        (noteIds.length
+          ? ` → ${noteIds.length} brain note(s) cite them: ${shown}.`
+          : byNote === null
+            ? " (citing notes unresolved here — run `rafa dirty` for the mapping)."
+            : " — no brain note cites them (nothing to refresh)."),
+    );
+    if (noteIds.length || byNote === null)
+      lines.push(
+        dirty.length >= DIRTY_FILES_ALARM || noteIds.length >= CITED_NOTES_ALARM
+          ? `[rafa · staleness] drift is past the threshold (${dirty.length} files / ${noteIds.length} notes) — recommend a brain refresh from main (\`/rafa scan --brain-only\`) at the next natural boundary.`
+          : `[rafa · staleness] at the next natural boundary, OFFER a scoped refresh of just the citing notes (atlas re-derives them, gates run as usual, then checkpoint). After the refresh: \`rafa dirty --consume\`.`,
+      );
+  }
+
+  const corrections = pendingCorrections(rafaDir);
+  if (corrections.length)
+    lines.push(
+      `[rafa · reflex] ${corrections.length} unprocessed correction(s) from earlier sessions: ` +
+        corrections
+          .slice(0, 3)
+          .map((c) => `${c.id} ("${c.p.slice(0, 60)}${c.p.length > 60 ? "…" : ""}")`)
+          .join(" · ") +
+        (corrections.length > 3 ? " …" : "") +
+        ` — fold into the bootstrap digest: bank the durable ones through the gates (see \`rafa reflex\`), consume each with its verdict.`,
+    );
+
+  const conflicts = conflictCopies(rafaDir);
+  if (conflicts.length)
+    lines.push(
+      `[rafa · conflicts] ${conflicts.length} checkpoint conflict cop${conflicts.length === 1 ? "y" : "ies"} await a decision (never auto-resolved): ${conflicts.slice(0, 5).join(", ")}${conflicts.length > 5 ? " …" : ""} — read each .theirs.md, merge/adopt/keep, re-run \`rafa checkpoint\`.`,
+    );
+
+  let activePlanId = null;
+  const activePath = join(rafaDir, "active.md");
+  if (existsSync(activePath)) {
+    const first = readFileSync(activePath, "utf8").split("\n")[0].trim();
+    if (first.startsWith("#") && first !== "# No active plan") {
+      activePlanId = first.replace(/^#\s*/, "");
+      lines.push(`[rafa · plan] active: ${activePlanId} (materialized under .rafa/plans/).`);
+    }
+  }
+
+  // Suggested next — ONE deterministic recommendation, ranked by consequence:
+  // a teammate blocked by a conflict > an unbanked correction > resuming the
+  // active plan > staleness repair. Guidance is front-loaded here (and ambient
+  // in the statusline) — never interleaved mid-flow (offer etiquette).
+  {
+    let next = null;
+    if (conflicts.length)
+      next = `resolve the checkpoint conflict${conflicts.length > 1 ? "s" : ""} (${conflicts.length} .theirs.md) — a teammate's copy is waiting on your decision`;
+    else if (corrections.length)
+      next = `work the ${corrections.length} unprocessed correction${corrections.length > 1 ? "s" : ""} (bank the durable ones — \`rafa reflex\`)`;
+    else if (activePlanId) next = `resume plan ${activePlanId}`;
+    else if (dirty.length) next = `refresh the notes your edits staled (offer the scoped refresh)`;
+    if (next) lines.push(`[rafa · next] suggested next: ${next}. Fold into the bootstrap digest — one question, never serial.`);
+  }
+
+  if (lines.length) process.stdout.write(lines.join("\n") + "\n");
+} catch {
+  /* the digest is a courtesy — never a crash */
+}
+process.exit(0);

package/blueprint/.claude/rafa/hooks/statusline.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+// rafa · statusline — the CLAUDE CODE ADAPTER for the loop-state line.
+//
+// HARNESS ADAPTER, deliberately thin (portability directive 2026-07-13: built
+// for Claude Code now, Cursor/Codex later). The semantics are owned by the
+// harness-neutral core — `rafa status` (packages/cli/lib/status.mjs); this
+// script mirrors that computation as a self-contained, dependency-free file
+// because statuslines re-render often (an npx call here would lag the UI).
+// Any drift between this and `rafa status --line` is a bug against the core.
+//
+// Claude Code invokes it with session JSON on stdin; whatever one line it
+// prints becomes the statusline. Ambient guidance, zero keystrokes, zero nags:
+//   rafa ▸ plan auth-rate-limit 2/5 → add limiter to route · 3 stale · 1 correction
+//   rafa ▸ in sync
+// Outside a rafa repo it prints nothing (silent — never hijacks the statusline).
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+function readJsonl(file) {
+  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 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;
+}
+
+function fmField(path, key) {
+  try {
+    let fence = 0;
+    for (const line of readFileSync(path, "utf8").split("\n")) {
+      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;
+}
+
+try {
+  let root = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  try {
+    const evt = JSON.parse(readFileSync(0, "utf8"));
+    root = evt?.workspace?.current_dir || evt?.workspace?.project_dir || evt?.cwd || root;
+  } catch {
+    /* no/bad stdin — fall back to env/cwd */
+  }
+  if (!existsSync(join(root, "rafa.json"))) process.exit(0); // silent outside rafa repos
+
+  const rafaDir = join(root, ".rafa");
+  const dirty = new Set(
+    readJsonl(join(rafaDir, "dirty.jsonl")).filter((e) => typeof e.f === "string").map((e) => e.f),
+  ).size;
+  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;
+  const conflicts = walk(rafaDir, 4, (n) => n.endsWith(".theirs.md")).length;
+
+  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, total = 0, 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 };
+    }
+  }
+
+  const parts = [];
+  if (plan) parts.push(`plan ${plan.id} ${plan.done}/${plan.total}` + (plan.current ? ` → ${plan.current}` : ""));
+  if (dirty) parts.push(`${dirty} stale`);
+  if (reflex) parts.push(`${reflex} correction${reflex === 1 ? "" : "s"}`);
+  if (conflicts) parts.push(`${conflicts} conflict${conflicts === 1 ? "" : "s"}`);
+  process.stdout.write(parts.length ? `rafa ▸ ${parts.join(" · ")}` : "rafa ▸ in sync");
+} catch {
+  /* a statusline must never error the UI */
+}
+process.exit(0);

package/blueprint/.claude/rafa/hooks/user-prompt-submit.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+// rafa hook · UserPromptSubmit — the correction reflex, detect half (M5 sensor #4).
+//
+// A dev correcting the agent is the highest-value knowledge signal the system
+// sees. This hook makes the MOMENT deterministic: a correction-shaped prompt is
+// (a) queued to .rafa/reflex.jsonl (monotonic — an abandoned session loses
+// nothing; the SessionStart digest resurfaces unprocessed corrections), and
+// (b) answered with a steering injection so THIS session validates and banks it
+// through the normal gates right now — same session, not next scan.
+//
+// The hook only detects CANDIDATES (narrow patterns, cheap, no LLM); judging
+// whether it's durable repo knowledge is model work downstream (capture is
+// cheap, distillation is rigorous). False positive cost: one injected line.
+// Privacy: the queue stores a short prompt snippet + a LOCAL transcript path —
+// nothing here ever ships; only a distilled, cited note passes the gates.
+//
+// Hard rules: never block (exit 0 everywhere), no network, no LLM.
+// Honors RAFA_HOOKS_DISABLED=1 (headless/CI recursion guard).
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+// Narrow, strong correction shapes — leading negation/contradiction, or an
+// explicit never/don't-use instruction. Deliberately NOT matching every "no"
+// mid-sentence; missed captures still have the dev's "bank that" as a path.
+const CORRECTION = [
+  /^(no\b|nope\b|wrong\b|incorrect\b|that'?s (wrong|incorrect|not right)|not (quite|right)\b|actually[,\s])/i,
+  /\b(never|don'?t|do not|stop) (use|do|call|import|write|put|add|touch)\b/i,
+  /\buse\s+\S[^.!?]{0,60}\binstead\b/i,
+  /\binstead of\b[^.!?]{0,60}\buse\b/i,
+];
+
+try {
+  if (process.env.RAFA_HOOKS_DISABLED === "1") process.exit(0);
+
+  let evt = null;
+  try {
+    evt = JSON.parse(readFileSync(0, "utf8"));
+  } catch {
+    process.exit(0);
+  }
+  const root = process.env.CLAUDE_PROJECT_DIR || evt?.cwd || process.cwd();
+  if (!existsSync(join(root, "rafa.json"))) process.exit(0);
+
+  const prompt = typeof evt?.prompt === "string" ? evt.prompt.trim() : "";
+  if (!prompt || prompt.startsWith("/")) process.exit(0); // commands are not corrections
+  if (!CORRECTION.some((re) => re.test(prompt))) process.exit(0);
+
+  const rafaDir = join(root, ".rafa");
+  mkdirSync(rafaDir, { recursive: true });
+  // Transport exclusion (same belt-and-braces as the dirty queue).
+  const gi = join(rafaDir, ".gitignore");
+  const body = existsSync(gi) ? readFileSync(gi, "utf8") : "";
+  if (!/^reflex\.jsonl$/m.test(body))
+    writeFileSync(gi, body + (body === "" || body.endsWith("\n") ? "" : "\n") + "reflex.jsonl\n");
+
+  const id = `rx_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`;
+  appendFileSync(
+    join(rafaDir, "reflex.jsonl"),
+    JSON.stringify({
+      id,
+      p: prompt.slice(0, 300),
+      t: new Date().toISOString(),
+      tp: typeof evt?.transcript_path === "string" ? evt.transcript_path : null, // LOCAL pointer, never ships
+    }) + "\n",
+  );
+
+  // The steering injection — arrives WITH the correction itself, so the session
+  // handles it at exactly the right moment (no SOP memory involved).
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "UserPromptSubmit",
+        additionalContext:
+          `[rafa · reflex ${id}] This prompt reads as a CORRECTION of prior agent output. ` +
+          `After addressing it: judge whether it encodes DURABLE repo knowledge (code-groundable — a convention, contract, or fact a future session would need). ` +
+          `If yes: bank it NOW through the gates — on a branch: author/edit the note under .rafa/brain/** with ≥1 resolving cite + \`rafa checkpoint\`; on main: full gates (verify-citations · compile · push). ` +
+          `Then confirm to the dev in ONE line (note id + where it landed) and run \`rafa reflex --consume ${id}\`. ` +
+          `If it is NOT durable repo knowledge (one-off steer, preference, out-of-code claim): say it stays session-only, and still \`rafa reflex --consume ${id}\` with reason "session-only". ` +
+          `Never bank an ungroundable claim; never quote the transcript into any shared store.`,
+      },
+    }),
+  );
+} catch {
+  /* a sensor must never take down the session */
+}
+process.exit(0);

package/blueprint/.claude/skills/rafa-build/SKILL.md

@@ -17,7 +17,7 @@ platform MCP (one read path — the same surface any third-party agent uses).
 | Role | Agent | Job per task |
 |---|---|---|
 | **Executor** | atlas | RECALL the task's brain slice via MCP (`search_knowledge` + `get_rule`/`get_playbook`; honor non-exemplars) → implement, convention-adherent |
-| **Validator** | prism | validate the execution against the child's `## Done-check` — strict, unbiased, against code + brain, never against atlas's claims. **`status: done` only on prism PASS**; FAIL → atlas corrects (validate-and-correct at work time). This gate is conductor-flow SOP — deterministic enforcement is the deferred capture-engine's job |
+| **Validator** | prism | validate the execution against the child's `## Done-check` — strict, unbiased, against code + brain, never against atlas's claims. **`status: done` only on prism PASS**; FAIL → atlas corrects (validate-and-correct at work time). Plan-done adds one line to the verdict: **working set reviewed — captured, or clean-with-reason** (a build that learned nothing SAYS so; a build that learned something SHOWS the files) |
 | **Improver** | bloom | **push**: new improvement opportunities spotted during execution → new ledger files. **close**: improvements fixed in passing → `status: fixed` in the ledger file + `report_improvement_status(id, fixed)` so the platform shows it LIVE as pending-reconciliation (the ledger row itself changes only at the next brain push — K1). **nudge**: top-leverage open item in the task's blast radius — opt-in, never blocking |
 
 ## Procedure
@@ -47,9 +47,12 @@ platform MCP (one read path — the same surface any third-party agent uses).
    in shared stores; mirror each into the item's `## Decisions` section) +
    `rafa checkpoint` (the branch working set), so the platform and every MCP
    consumer reflect live progress. Checkpoint moments: task done · plan
-   approved · explicit ask · cadence · git push/pull — never session-end. A
-   checkpoint CONFLICT (a teammate's newer copy of the same file) is decided
-   IN THIS SESSION: read the `.theirs.md` copy, merge/adopt/keep, re-checkpoint.
+   approved · explicit ask · cadence · git push/pull — never session-end. The
+   git-push boundary is MECHANICAL (M5): the pre-push hook runs `rafa checkpoint`
+   itself, non-blocking — the session still owns the task-done/plan-approved
+   moments. A checkpoint CONFLICT (a teammate's newer copy of the same file) is
+   decided IN THIS SESSION: read the `.theirs.md` copy, merge/adopt/keep,
+   re-checkpoint.
 3. **Brain changes mid-build — WHERE you are decides WHERE it goes.**
    - **On the default branch (main):** run a full `/rafa scan` (regenerate →
      prism → compile → push); the brain re-stamps at the new sha, so
@@ -66,6 +69,10 @@ platform MCP (one read path — the same surface any third-party agent uses).
 4. **Verify** (prism-style) before declaring the plan done; final `push_plan` +
    `set_active_plan` (clear) + `rafa checkpoint`. A plan that stops being worth
    finishing closes honestly: `superseded` or `abandoned`, never fake-`done`.
+   Plan-done is also a **staleness boundary**: read `rafa dirty --json` — if the
+   build's edits dirtied notes this session didn't already refresh, surface the
+   scoped-refresh offer NOW (on main: refresh → gates → push; on a branch:
+   working-set edit → checkpoint), and `rafa dirty --consume` only after it ships.
 
 **Lite plans** (single-child, from plan-lite) run the same per-task loop — the
 Done-check gate never relaxes; only the ceremony around it shrinks (no bloom nudge,

package/blueprint/.claude/skills/rafa-plan/SKILL.md

@@ -67,6 +67,13 @@ The full choreography earns its weight on cross-cutting work; a one-file change
 through five steps teaches devs to route around rafa — and a route-around is a product
 failure. So the conductor weighs the **blast radius** (from coverage at recall time):
 
+- **Below planning entirely — DIRECT-DO (conductor 1.8.0):** radius ≤ 1 domain, no
+  contract surface, fits one sitting → NO plan files are created at all. The
+  conductor acts (recall → implement → verify) and the sensors carry the loop
+  (dirty-mark · reflex · checkpoint-at-push · capture if knowledge emerged). Plans
+  begin where RESUMABILITY or COORDINATION begins — not before. If direct-do work
+  GROWS (2nd domain, contract surface, multi-session), the conductor escalates to
+  lite with one announce line and creates the files THEN.
 - **Lite** (radius ≤ 2 domains and no contract/schema surface touched): ONE parent +
   ONE child file, recall scoped to the touched domains, bloom pull skipped, prism gate
   collapses to the two invariants that never relax — every task grounded, the child

package/blueprint/.claude/skills/rafa-scan/SKILL.md

@@ -81,9 +81,14 @@ file, finds nothing, and stops trusting the brain. So fidelity is non-negotiable
 - **One docs rule, stated once.** Contract site lists count **code** occurrences; exclude
   docs/markdown/comments. Apply this identically to every contract — never "the full
   surface" for one and "the rest are docs" for another. State the exclusion once per note.
-- **Never assert absence without an exhaustive grep.** "none yet", "greenfield", "not used
-  anywhere" require a repo-wide `git grep` of the pattern first. A sampled read is not
-  evidence of absence — one un-grepped route (e.g. a demo page) invalidates the claim.
+- **Never assert absence without an exhaustive grep — and DECLARE it so the gate re-greps
+  it forever.** "none yet", "greenfield", "not used anywhere" require a repo-wide
+  `git grep` of the pattern first; a sampled read is not evidence of absence. Then declare
+  the token in frontmatter — `absent: <token>` (repeatable, one per line) — so
+  `verify-citations` gate **B3** re-greps it on every run and the claim can never silently
+  go stale (the 2026-06-08 blocker class: code grew the thing the note said was missing).
+  An absence-shaped title/summary with no `absent:` declared is flagged as a checker WARN —
+  resolve every WARN before hand-off (declare the token, or reword the claim).
 
 ---
 
@@ -94,6 +99,12 @@ file, finds nothing, and stops trusting the brain. So fidelity is non-negotiable
 - `.rafa/brain/coverage.md` — the coverage report. **Machine-read frontmatter** per
   [`.claude/rafa/contract.md`](../../rafa/contract.md) §6: `domains: { <domain>: mapped|thin|stubbed|empty, … }`
   — one entry per domain from Step 1. The body keeps the per-criterion PASS/FAIL narrative.
+  **Declare `inventory:` entries** (`- <name> :: <glob> :: <count>`) for each framework
+  surface the scan counted — route pages, API routes, agent graphs, whatever is
+  load-bearing in THIS repo. The checker recomputes each via `git ls-files ':(glob)…'`
+  every run and fails on drift, so coverage can never silently claim an inventory the
+  repo has outgrown. Compute the count FROM the same `git ls-files` command — never from
+  memory of the tree.
 
 **Note format.** The **strict contract is [`.claude/rafa/contract.md`](../../rafa/contract.md) §2** — every
 required field there is mandatory and `rafa compile` (Step 7) **rejects** any violation with a

package/blueprint/.claude/skills/rafa-validate/SKILL.md

@@ -32,8 +32,11 @@ agent. So:
 ## Procedure (run in order; ground everything in code)
 
 1. **Re-run the checker yourself** — `npx @rafinery/cli verify-citations`. Record exit
-   code + counts (resolution / completeness / policy). Exit ≠ 0 → **blocker(s)**. Never
-   trust a pasted table.
+   code + counts (resolution / completeness / policy / **absence / inventory** — checker
+   v2 mechanizes the 2026-06-08 ratchet: declared `absent:` tokens re-grepped, coverage
+   `inventory:` counts re-computed). Exit ≠ 0 → **blocker(s)**. Never trust a pasted
+   table; confirm `citation-check.json` (checkerVersion · pass · at) matches the run you
+   just made — a stale record riding a push is itself a **blocker**.
 2. **Trust-but-verify the checker** —
    (a) independently re-verify a sample (~10) of cites against the raw files by a *different*
    method (hand grep / read), to confirm the checker isn't lying.
@@ -44,6 +47,16 @@ agent. So:
    A mismatch in (a), or a non-zero `--selftest` in (b) → **blocker** (the verifier is broken).
 3. **Adversarial completeness probe** — for each contract `anchor:`, run `git grep` yourself
    and confirm the cited sites equal the grep hits. Hunt for an omitted site.
+
+3b. **Absence audit — work the WARN list.** The checker's report ends with heuristic WARNs
+   (absence-shaped title/summary with no `absent:` declared). For each: decide whether the
+   claim is truly existence-dependent → if yes, it MUST declare `absent: <token>` (finding:
+   major — an undeclared absence claim is exactly the class that went stale in 2026-06-08);
+   if the wording is just loose, note it as minor. Then hunt for absence claims the
+   heuristic missed: any note whose truth depends on something NOT existing, with no
+   `absent:` gate behind it. The mechanized gate only covers what is declared — YOUR job
+   is the undeclared remainder (the ratchet's disposition protocol: every catch here
+   should end as a new declaration, an eval case, or a recorded judgment).
 4. **Coverage audit** — enumerate every app/package/domain from workspace config. Confirm
    each has a *substantive* note (not a token stub). Tunneling / imbalance → **major**.
 5. **Load-bearing test (the core score)** — pick ONE real feature + ONE real bug. Using ONLY

package/lib/blueprint.mjs

@@ -43,6 +43,10 @@ export const BLUEPRINT = {
     ".claude/skills/rafa-leverage",
   ],
   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 +100,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 }}"
 `;