@rafinery/cli 0.4.1 → 0.6.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,8 +17,8 @@ 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 |
-| **Improver** | bloom | **push**: new improvement opportunities spotted during execution → new ledger files. **close**: improvements fixed in passing → `status: fixed`. **nudge**: top-leverage open item in the task's blast radius — opt-in, never blocking |
+| **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
 
@@ -40,11 +40,19 @@ platform MCP (one read path — the same surface any third-party agent uses).
    parsed; the plan files at `.rafa/plans/<plan>/` ARE the local cache) → at the
    task-done CHECKPOINT (under the session consent): `push_plan` /
    `update_plan_status` (the plans channel — statuses + Log journals) +
+   **`log_decision` for each deliberation since the last checkpoint** — what
+   came up, what was considered, what the DEV chose, why (actor = the dev for
+   steering, the agent for its own proposals; PARAPHRASE + short verbatim
+   quotes only where the wording carries the decision — transcripts never land
+   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
@@ -61,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-insights/SKILL.md

@@ -58,9 +58,20 @@ code-level → the branch working set (not yours — rafa.md §capture routes it
 existing insight (`put_dev_insight` with its id) rather than accreting near-
 copies.
 
+### 2b. Personal tooling (ratified 2026-07-12 — the user-plane toolbox)
+Under the dev's STANDING insights consent, inventory the tooling they carry
+across repos — `~/.claude/skills` + user-level MCPs — and bank each as a
+`kind: tooling` insight (NAME + DESCRIPTION only, never file contents). Update
+beats duplicate; tombstones honored. This is what lets rafa orchestrate a
+dev's personal migration skill in a repo that has never seen it. The REPO
+toolbox is atlas's plane (scan's toolbox domain), never yours.
+
 ### 3. Steering (the payoff — propose, the dev disposes)
-At natural boundaries only, at most one nudge: surface the insight that changes
-what the dev does next — "you've corrected X three times: want it banked as a
+At natural boundaries only, at most one nudge — and ALWAYS have a candidate
+ready (leverage-coaching: cross the repo's toolbox inventory with the dev's
+patterns + tooling insights — "you've hand-run this migration three times; the
+repo ships a skill for it"). Availability is always; frequency never rises.
+Surface the insight that changes what the dev does next — "you've corrected X three times: want it banked as a
 rule?" · "this decomposition worked before, reuse it?" · "you never use plan
 mode on big changes; it would have caught this." Dismissal is final for the
 session. Never rank, never compare devs, never nag.

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

@@ -37,9 +37,17 @@ Planning is a choreography, not one agent (spec: knowledge-mcp-build-agent):
 1. **Staleness check** — compare the platform envelope's `brainForSha` against the
    local brain stamp; if the platform is behind, surface "run `rafa push`" (never
    proceed silently on knowledge you know is stale — never block either).
-2. **Recall** (atlas, via MCP) → **decompose** ADR-style: decision + rationale +
-   alternatives + risk surface + non-goals; tasks bound to domains with a
-   `## Done-check` each.
+2. **Recall** (atlas, via MCP) → **decompose** into the WORK-ITEM TREE (contract
+   §7 v2): one epic → tasks → subtasks (three ranks, never deeper). Every item
+   carries the glimpse fields — `title` (what) · `description` (why) ·
+   `approach` (how, one line) · `assignee` when known · `blocked_by` for
+   intra-plan dependencies (a dependency IS a blocker; blocked is DERIVED,
+   never a status) · optional `priority` 0–4 / `estimate`. Every LEAF carries a
+   `## Done-check`. The blast radius goes on the EPIC's `domains:` — it rides
+   `push_plan` and the platform renders the plan's brain slice beside it.
+   ADR material (alternatives, risks, non-goals) lives in the epic body AND
+   the pivotal choices are logged as DECISIONS at approval (`log_decision`:
+   context · options · decision · rationale; actor = the dev for their calls).
 3. **Ledger pull** (bloom) → optional leverage tasks in the blast radius.
 4. **Leverage-match** — recommend existing skills/tools/MCP that fit the tasks;
    never plan to hand-roll what a capability already does.
@@ -59,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
@@ -138,6 +149,15 @@ retrieval index. Bodies read like a senior engineer explaining that one concept
    the internal node/relationship model the next steps reason over. (Not emitted as a
    file; it feeds the notes.)
 
+3b. **Toolbox inventory** [deterministic] — ratified 2026-07-12: the REPO toolbox is a
+   first-class brain domain (`toolbox`). Run `npx @rafinery/cli leverage --json` (the
+   deterministic extractor) and author cited notes for the committed toolbox — skills
+   (`.claude/skills/*/SKILL.md` name+description), commands, `.mcp.json` servers,
+   granted permissions — cites into the config files themselves (contract §2; they are
+   citable file:line). This makes the toolbox recallable through the SAME MCP surface
+   as all knowledge and refreshable like any note. Personal `~/.claude/` is NEVER
+   inventoried here (user-profile plane, compass's job, standing consent).
+
 4. **Convention detection** [deterministic + light LLM] — for **each** domain, the local
    idiom (design tokens, component export pattern + any server/client split such as RSC,
    data-op shape, naming).

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/checkpoint.mjs

@@ -84,6 +84,13 @@ export default async function checkpoint() {
   try {
     payload = await callTool(ROOT, "checkpoint_sync", {
       branch,
+      // WHO/WHAT executed — the CLI knows itself; the MODEL is the session's to
+      // report (RAFA_ACTOR_MODEL env, set by the conductor) — never guessed.
+      actorMeta: {
+        agent: "rafa-cli@" + (process.env.npm_package_version ?? "0.5.0"),
+        runner: process.env.CI ? "ci" : "session",
+        model: process.env.RAFA_ACTOR_MODEL ?? "unreported",
+      },
       files: candidates.map(({ path, content, baseVersion, baseBrainSha }) => ({
         path,
         content,

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 }}"
 `;
 

package/lib/claude-config.mjs

@@ -13,6 +13,119 @@ 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).
+// Owned-file edit, idempotent, reviewable in git diff; blueprint stays generic.
+export function mergeRepoMcpsIntoCards(targetDir) {
+  const mcp = readClaudeSettingsFile(join(targetDir, ".mcp.json"));
+  const servers = Object.keys(mcp?.mcpServers ?? {}).filter((n) => n !== "rafinery");
+  if (servers.length === 0) return { updated: [] };
+  const updated = [];
+  const dir = join(targetDir, ".claude", "agents");
+  if (!existsSync(dir)) return { updated };
+  for (const card of ["atlas.md", "bloom.md", "prism.md", "compass.md"]) {
+    const file = join(dir, card);
+    if (!existsSync(file)) continue;
+    let text = readFileSync(file, "utf8");
+    const m = text.match(/^tools: (.+)$/m);
+    if (!m) continue;
+    const have = m[1].split(",").map((t) => t.trim());
+    const missing = servers.map((s2) => `mcp__${s2}`).filter((t) => !have.includes(t));
+    if (missing.length === 0) continue;
+    text = text.replace(/^tools: .+$/m, `tools: ${[...have, ...missing].join(", ")}`);
+    writeFileSync(file, text);
+    updated.push(`${card} (+${missing.join(", ")})`);
+  }
+  return { updated };
+}
+
+function readClaudeSettingsFile(file) {
+  if (!existsSync(file)) return null;
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
 export function settingsPath(targetDir) {
   return join(targetDir, ".claude", "settings.json");
 }