@rafinery/cli 0.8.1 → 0.8.3

package/CHANGELOG.md

@@ -4,6 +4,15 @@ The machine-readable version of this lives in [`lib/releases.mjs`](lib/releases.
 CLI reads it to tell a client, on `rafa update`, exactly what an upgrade requires (nothing,
 a re-scan, or a `rafa migrate`).
 
+## 0.8.2 — MCP scope: derived from the key, never guessed
+
+First real client MCP call surfaced it: agents GUESSED the `repo` arg (folder name)
+because nothing told them where the id lives. Server-side, `repo` is now optional on
+every tool — the per-repo key IS the scope and the platform derives it (explicit
+mismatch still fails loudly, teaching both exits). Fleet-side, every agent card +
+the conductor carry the convention: omit `repo`; where a value is explicitly needed
+it is the committed `rafa.json → repoId`, never a guess. Adopt with `rafa update`.
+
 ## 0.8.1 — honest empty: absence is never conformance
 
 `rafa okf check` over a root with zero `.md` files used to print a green "conforms" —

package/bin/rafa-distiller.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// rafa-distiller — the distiller loop's binary (reconciliation orchestrator, spec
+// §2.6). boot.sh's DISTILLER_ENTRY seam: the sandbox image's boot.sh wins the claim
+// (claim-on-start, exports RAFA_ATTEMPT) and `exec rafa-distiller`. From here the
+// metered loop owns the run: heartbeat + arbitrate against merged main + author
+// survivors through the gates + push (never force) + reconcile_report.
+//
+// Thin entry only — the loop lives in ../lib/distiller.mjs so it stays importable +
+// unit-testable (runDistiller) without a sandbox.
+
+import distiller from "../lib/distiller.mjs";
+
+await distiller(process.argv.slice(2));

package/bin/rafa.mjs

@@ -12,6 +12,8 @@
 //   rafa checkpoint           sync this branch's working set (CAS; conflicts → .theirs.md)
 //   rafa hydrate              fault knowledge into the lazy .rafa/
 //   rafa dirty [--json]       staleness queue → citing notes; --consume after a refresh
+//   rafa doctor               prove the capture machinery end to end (sensors ·
+//                             scripts · heartbeat round-trip); runs inside init too
 //   rafa fold                 branch→parent mechanical fold of the working set (no LLM)
 //   rafa distill --headless   CI merge-to-main distillation (org's own LLM key)
 //   rafa ci-setup             write the reconcile workflow (fold + distill on PR merge)
@@ -45,8 +47,10 @@ const COMMANDS = [
   "dirty",
   "reflex",
   "status",
+  "doctor",
   "fold",
   "distill",
+  "distiller",
   "ci-setup",
   "leverage",
   "benchmark",
@@ -144,18 +148,15 @@ End to end — from zero to a queryable, working brain:
                 validates, bloom writes the improvement ledger. Then  rafa push
                 → webhook → the platform ingests it (the brain repo only).
   4. SEE IT     Open the repo on the platform: Overview (health), Brain (files),
-                Improvements (kanban), Plans, Activity (branch changes). "Agent
-                access" mints keys for more MCP clients (Slack, CI, incident.io).
+                Improvements (kanban), Plans, Reconciliations (merge runs).
   5. WORK       /rafa plan "<intent>" — prism-validated, brain-grounded; approval
                 pushes it to the platform (the plans channel). /rafa build —
                 execute it; statuses/journals + the branch WORKING SET sync at
                 checkpoints, so any teammate or session resumes where you stopped.
-  6. RECONCILE  rafa ci-setup (once) — your CI folds branch→branch merges
-                mechanically and DISTILLS merge-to-main into the org brain with
-                YOUR OWN LLM key. No CI? The next session offers the same.
-  7. QUERY      Any MCP client with a key can read the brain at <platform>/api/mcp:
-                get_brain_status · search_knowledge · get_rule/playbook/improvement ·
-                list_plans · get_plan · get_active_plan. Read-only, cited, per-repo.
+  6. MERGE      Just merge PRs — the platform detects the merge and distills the
+                branch's knowledge into the org brain automatically (watch the
+                Reconciliations tab). Teams that want the compute in their own
+                CI instead: rafa ci-setup (optional, org-CI adapter).
 
 Then, inside Claude Code:  /rafa scan · /rafa improve · /rafa plan · /rafa build
 

package/blueprint/.claude/agents/atlas.md

@@ -1,6 +1,6 @@
 ---
 name: atlas
-version: 3.8.0
+version: 3.8.1
 model: opus   # authoring is correctness-critical — a hallucinated note poisons the brain; best model, never cheap
 groundTruth: code-at-sha
 description: >-
@@ -23,6 +23,10 @@ duties:
 
 # atlas — senior design engineer
 
+**MCP scope — every `mcp__rafinery` call:** OMIT `repo`; your key IS the repo
+scope and the server derives it. Where a value is explicitly needed, it is the
+committed `rafa.json → repoId` — NEVER a folder name or repo-name guess.
+
 You are **atlas**, a senior design engineer for the rafa platform. A peer who
 reasons about systems, not a code-completion assistant.
 

package/blueprint/.claude/agents/bloom.md

@@ -1,6 +1,6 @@
 ---
 name: bloom
-version: 0.8.0
+version: 0.8.1
 model: opus   # a false flag mutes the whole ledger — best model, never cheap
 groundTruth: code-trend
 description: >-
@@ -22,6 +22,10 @@ duties:
 
 # bloom — continuous improvement
 
+**MCP scope — every `mcp__rafinery` call:** OMIT `repo`; your key IS the repo
+scope and the server derives it. Where a value is explicitly needed, it is the
+committed `rafa.json → repoId` — NEVER a folder name or repo-name guess.
+
 You are **bloom**, rafa's improvement engine — a patient staff engineer who raises the bar
 a little every interaction, relentless but gentle. atlas **knows** the codebase; **prism**
 doubts it; **you raise its floor.**

package/blueprint/.claude/agents/compass.md

@@ -1,6 +1,6 @@
 ---
 name: compass
-version: 0.4.0
+version: 0.4.1
 model: opus   # a false note about a PERSON is worse than one about code — best model, never cheap
 groundTruth: sessions-over-time
 description: >-
@@ -23,6 +23,10 @@ duties:
 
 # compass — the dev's coach
 
+**MCP scope — every `mcp__rafinery` call:** OMIT `repo`; your key IS the repo
+scope and the server derives it. Where a value is explicitly needed, it is the
+committed `rafa.json → repoId` — NEVER a folder name or repo-name guess.
+
 You are **compass**, the fourth agent: where atlas knows the code, prism doubts
 the claims, and bloom raises the floor, you know — and refine — **how this
 developer works**. Your store is the user brain: account-scoped, cross-repo,

package/blueprint/.claude/agents/prism.md

@@ -1,6 +1,6 @@
 ---
 name: prism
-version: 0.7.0
+version: 0.7.1
 model: opus   # the trust anchor — a hallucinated verdict/finding is the worst failure; best model, never cheap
 groundTruth: code-vs-claim
 description: >-
@@ -22,6 +22,10 @@ duties:
 
 # prism — the validator
 
+**MCP scope — every `mcp__rafinery` call:** OMIT `repo`; your key IS the repo
+scope and the server derives it. Where a value is explicitly needed, it is the
+committed `rafa.json → repoId` — NEVER a folder name or repo-name guess.
+
 You are **prism**, an independent QA engineer and the trust anchor of every rafa
 gate. Adversarial by mandate: your job is to find what's wrong, not to bless what's
 there. You review the **artifact + the ground truth, never the producer's claims**;

package/blueprint/.claude/agents/sage.md

@@ -1,6 +1,6 @@
 ---
 name: sage
-version: 0.2.0
+version: 0.2.1
 model: opus   # a wrong learning re-shapes an agent for every repo — best model, never cheap
 groundTruth: sessions-over-time
 description: >-
@@ -24,6 +24,10 @@ duties:
 
 # sage — the silent L5 observer
 
+**MCP scope — every `mcp__rafinery` call:** OMIT `repo`; your key IS the repo
+scope and the server derives it. Where a value is explicitly needed, it is the
+committed `rafa.json → repoId` — NEVER a folder name or repo-name guess.
+
 You are **sage**, rafa's fifth agent and its **self-improvement loop (L5: system → itself)**.
 Where **atlas** knows the code, **prism** doubts the claims, **bloom** raises the code floor,
 and **compass** coaches the dev — **you raise the floor of the agents themselves.** Your subject

package/blueprint/.claude/commands/rafa.md

@@ -1,5 +1,5 @@
 ---
-version: 2.0.0
+version: 2.0.2
 description: rafa — the repo's engineering SOP. Use whenever the dev wants to plan a feature or change, build/execute against the active plan, improve code health, or ground work in the repo's brain — intent counts, the dev does NOT need to type /rafa. Also explicit: /rafa <init|scan|improve|plan|build|push|leverage|migrate|update|help> [--brain-only]. Admin verbs (init/scan/push/migrate/update) run ONLY when explicitly invoked.
 ---
 
@@ -123,6 +123,13 @@ Dismissible as a unit; offer fatigue trains reflexive yes, which corrodes every
 rung above it. Open gaps are one more line in this ONE digest — a pullable source, never
 a serial prompt and never mid-flow.
 
+**Exception — a `[rafa · doctor]` digest line is NOT dismissible-later.** It means the
+capture machinery itself is broken (unwired sensor, missing/foreign git hook, a recent
+swallowed failure): run `npx -y @rafinery/cli doctor` FIRST and present its named fixes
+to the dev as concrete next steps before knowledge work — every task done on dead
+sensors is knowledge silently lost. This fires on new sessions AND resumes (the
+SessionStart hook covers both).
+
 **The M5 sensors feed you — you never poll.** Four deterministic instruments run outside
 the model (blueprint hooks + the git boundary): the SessionStart digest injects
 staleness/conflicts/corrections/active-plan at session start · every Edit/Write is
@@ -199,6 +206,17 @@ Two destinations, one rule — route by what the observation is ABOUT:
 > **Every verb that writes `.md` is under the OKF surface** (contract §11): files
 > self-describe, body links are bundle-relative markdown, `rafa push` materializes
 > the rest — protocol + the two declared exceptions live in [rafa-okf](../skills/rafa-okf/SKILL.md).
+>
+> **MCP scope — every `mcp__rafinery` call:** omit `repo` (the key IS the scope;
+> the server derives it); where explicitly needed it is `rafa.json → repoId`,
+> never a folder-name guess. Mid-session 401 after a key rotation = this session
+> holds the OLD connect-time key — have the dev reconnect the rafinery MCP (or
+> restart); CLI tools reload credentials per call and keep working.
+>
+> **Fixed-in-passing is REPORTED, always:** any ledger improvement fixed during
+> ANY work — inside or outside a /rafa verb — gets `report_improvement_status`
+> at the fix boundary. Hand-edits never flip ledger status; an unreported fix
+> leaves bloom's ledger lying until the next full pass.
 
 Each work/admin verb dispatches to its SOP. Read the skill only when the verb runs; it is
 self-contained and ADR-shaped. **You orchestrate + push on approval; the subagent follows
@@ -216,7 +234,7 @@ explicitly typed; an ACCEPTED boundary offer counts as the explicit invocation.
 | `insights` | spawn compass → bootstrap/refresh the dev's private user brain from their native `/insights` report + recent work; every candidate OFFERED, banked only on yes (`put_dev_insight`). Capture during normal work is §capture's job, not this command. | [rafa-insights](../skills/rafa-insights/SKILL.md) |
 | `leverage` | reason over the committed toolbox (`.claude/settings.json`, `.mcp.json`, `skills/`, `commands/`, the stack) — what's missing/misconfigured/unused; on approval apply the fix EXACTLY (merge permissions, wire an MCP, scaffold a skill). Merge, never clobber; show the diff. The CLI reports, you fix. | [rafa-leverage](../skills/rafa-leverage/SKILL.md) |
 | `sage` | explicit OVERRIDE of the implicit observer pass (below) | [rafa-sage](../skills/rafa-sage/SKILL.md) |
-| `push` | `npx @rafinery/cli push` — commit `.rafa/` and push to the brain remote (the dev's own git auth), stamped `brain-for: <code sha>`. After a scan, or to re-sync a changed brain. Never without approval. | — |
+| `push` | `npx @rafinery/cli push --verb=<scan\|improve\|build\|update>` — commit `.rafa/` and push to the brain remote (the dev's own git auth), stamped `brain-for: <code sha>`. Pass the verb of the work that produced this push (P4 descriptive commits — the brain history should say `brain(scan): …`, never a wall of `update`). After a scan, or to re-sync a changed brain. Never without approval. | — |
 | `migrate` · `update` | brain-side schema migration — see below | — |
 | `help` (also no arg / unrecognized) | print this reference verbatim, then stop | — |
 

package/blueprint/.claude/rafa/contract.md

@@ -47,6 +47,7 @@ doesn't validate, compile fails.
 | improvement           | `improve/improvements/*.md`       | **structured**                                                                                                                     | §3                                                                                                                                                            | bloom      |
 | ledger                | `improve/ledger.md`               | **structured**                                                                                                                     | §5                                                                                                                                                            | bloom      |
 | plan                  | `plans/**/*.md`                   | **structured**                                                                                                                     | §7                                                                                                                                                            | plan/build |
+| reconciliation report | `brain/reconciliations/*.md`      | **structured** (validated, NOT in the manifest — travels on the brain-repo transport, like plans)                                  | `run` (merge sha) · `outcome` ∈ `succeeded`\|`needs-attention`\|`superseded` · `tier` ∈ `canonical`\|`provisional`; refutation/deletion records ride INSIDE (body sections — one class); minted via `rafa okf new reconciliation-report` | distiller  |
 | log                   | `brain/log.md`                    | **verbatim**                                                                                                                       | — (prose trail; OKF-reserved name, §11)                                                                                                                       | conductor  |
 | index                 | `**/index.md`                     | **generated**                                                                                                                      | — (OKF §6 listings, by `rafa okf`; the ROOT index alone carries frontmatter: `okf_version` + provenance)                                                      | tool       |
 | citation-check        | `**/citation-check.md`            | **generated**                                                                                                                      | — (by `rafa verify-citations`; self-describing frontmatter, §11)                                                                                              | tool       |
@@ -500,7 +501,11 @@ match.
 | `get_plan`                                      | `repo`, `id` (parent or child)            | parent + all children **with stored bodies** + **derived** progress; a child id resolves the whole plan with `requestedChild` set — this is what "load plan X" materializes into `.rafa/plans/` |
 | `get_active_plan`                               | `repo`                                    | resolves the channel pointer (`set_active_plan`) → `get_plan`, or "no active plan"                                                                                                              |
 
-`repo` must match the key's scope exactly; `branch` is reserved (branch-keyed
+`repo` is OPTIONAL on every tool — the scope is DERIVED from the per-repo key
+(the key IS the repo identity; a derivation from an authenticated fact, never an
+assumed value). When provided it must match the registered id exactly — loud
+mismatch, never a fallback. Sessions that pass it read the id from the committed
+`rafa.json` `repoId`, never a folder name. `branch` is reserved (branch-keyed
 instances land in Slice 2 — third-party clients default to the production brain,
 i.e. the default branch's instance).
 
@@ -538,7 +543,13 @@ intent degrades to search; a wrong intent would answer the wrong thing.
    silent throttle.
 
 **Auth:** per-repo machine keys, minted on the platform, sent as
-`Authorization: Bearer`. Keys are stored hashed platform-side and live client-side in
+`Authorization: Bearer`. **Rotation is zero-downtime by design:** keys COEXIST —
+mint the replacement, update the configs (settings.local.json · credentials.json ·
+CI secrets), then revoke the old at leisure; revoke stays an immediate kill (a
+security act, never graced). A live session holds its connect-time key — reconnect
+the rafinery MCP server (or restart the session) after swapping; the CLI tools
+(checkpoint · hydrate · distill) resolve credentials fresh per invocation and are
+never stale. Keys are stored hashed platform-side and live client-side in
 `~/.config/rafinery/credentials.json` — never inside the code repo or this brain repo.
 
 **Client wiring (written by `rafa init`, secret-free where committed):** a key is
@@ -551,7 +562,7 @@ minted at setup generation and delivered consume-once through the setup fetch;
 ### §9 addendum — state-plane tools (three-store model, working-set architecture)
 
 The knowledge plane stays strictly read-only (org-brain writes go ONLY through
-files → compile → push → ingest). Seven additional tools write **collaboration
+files → compile → push → ingest). Additional tools write **collaboration
 state**, marked by `envelope.plane: "state"`:
 
 | Tool                                                                                   | Store                                                   | Notes                                                                                                                                                                                                                                                                                                                                                                |
@@ -563,6 +574,11 @@ state**, marked by `envelope.plane: "state"`:
 | `fold_working_set`                                                                     | branch working set                                      | branch→parent-branch MECHANICAL fold (no LLM, no prism — rigor only at main): absent → re-keyed · identical → merged · divergent → `needs-adjudication` on the parent row                                                                                                                                                                                            |
 | `push_plan` / `list_plans` / `update_plan_status` / `set_active_plan` / `log_decision` | **plans** — (repo) work objects                         | the push-on-approval channel (§7 v2): approval pushes the whole work-item TREE (items[], bodies stored); `list_plans` = names only; statuses push back (5-value enum — blocked is derived); `log_decision` records the deliberation trail (paraphrase + pivotal quotes); the active pointer is explicit, never inferred                                              |
 | `report_improvement_status`                                                            | **events only** — no store                              | a LIVE session signal (bloom's fixed-in-passing during build). The improvement ledger row is untouched — it has ONE writer, the ingest (K1); the platform overlays the report as pending-reconciliation until the next brain push confirms it                                                                                                                        |
+| `reconcile_claim`                                                                      | **reconciliations queue** — (repo) run rows            | executor claim (`plane:"state"`): ACID no-running-sibling assert → returns the attempt token; delegates to `reconciliations.claim`; stamps the actor envelope `{model, agent, runner}` (runner ∈ `sandbox`\|`ci`\|`session`, enum-checked at the boundary) on the row                                                                                          |
+| `reconcile_heartbeat`                                                                   | reconciliations queue                                   | extends the wall-clock lease + sets the phase; **attempt-fenced** (a non-current attempt is rejected, nothing written); actor envelope re-stamped                                                                                                                                                                                                                    |
+| `reconcile_log_append`                                                                  | **reconciliationLogs** — the run log tail               | batched chunks, **secret-screened PER LINE** (the same `looksLikeSecret` screen — a credential chunk is rejected by chunk/line index, nothing stored or echoed) + **attempt-fenced**; `seq`-ordered; UNLOGGED (emits its own `reconcile.log` event, counts only)                                                                                                       |
+| `reconcile_report`                                                                      | reconciliations queue (+ knowledge node on success)     | terminal outcome + node delta + meter; **attempt-fenced**; success COMPOSES the pointer advance atomically (insert node + move pointer, one mutation); refutation/deletion ride the success outcomes; actor envelope stamped                                                                                                                                          |
+| `list_working_sets`                                                                     | branch working set (**READ**)                           | enumerates branches with LIVE candidate rows + counts only (no bodies) — closes the 07-14 sensor gap (`get_working_set` needs a branch arg; nothing listed them); feeds the SessionStart digest pending line                                                                                                                                                         |
 
 State tools work with or without an ingested brain (a working set can exist —
 and a plan can be pushed — before the first scan) and are exempt from the
@@ -571,6 +587,18 @@ snapshot/ingestError gates. `get_plan`/`get_active_plan` share this exemption
 bucket-note tools (`stage/list/resolve_bucket_note`, pre-0.4.0) are superseded
 by the working-set tools.
 
+**Typed candidates (capture-engine P2, additive).** A working-set row's KIND
+derives from its path — never from a parallel field that could drift:
+`brain/rules|playbooks/**` = **note** (§2, judged on "does the claim hold?");
+`improve/improvements/**` = **improvement** (§3, judged on the LIFECYCLE —
+"is the defect actually gone / does it actually exist on merged main?"; the
+row resolution stays the standard enum, the verdict note carries
+`confirmed-fixed` / `still-open` / `opened`); `intent/**` = **intent record**
+(the post-commit hook's per-commit provenance — consumed at merge, never
+judged, never authored into the org brain). `improve/ledger.md` is DERIVED
+and never a candidate. schemaVersion stays 1 — this section is purely
+additive (§8).
+
 ## 10. Agent cards — `../.claude/agents/*.md` (local gate)
 
 The shipped agents are contract-governed artifacts: every card is validated by

package/blueprint/.claude/rafa/hooks/brain-commit.mjs

@@ -0,0 +1,81 @@
+// rafa brain-commit — the post-commit worker (capture-engine P1, spec r2 §2.2).
+// ONE brain commit per code commit, strict 1-1 (--allow-empty), on the MIRRORED
+// brain branch — never the brain default branch (the distiller's, single
+// writer). Carries whatever changed under .rafa/ plus the commit's INTENT
+// RECORD (intent/<shortsha>.md); trailers code-commit/code-branch are the join
+// keys. Standalone by design (node built-ins only, like every M5 sensor);
+// non-blocking always — a brain problem must never block a code commit.
+
+import { execSync } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const ROOT = process.cwd();
+try {
+  if (process.env.RAFA_HOOKS_DISABLED === "1") process.exit(0);
+  if (!existsSync(join(ROOT, "rafa.json"))) process.exit(0);
+  if (!existsSync(join(ROOT, ".rafa", ".git"))) process.exit(0);
+
+  const sh = (cmd, cwd = ROOT) =>
+    execSync(cmd, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  const rafa = join(ROOT, ".rafa");
+  const shR = (cmd) => sh(cmd, rafa);
+
+  const branch = sh("git rev-parse --abbrev-ref HEAD");
+  // Trunk commits never mirror — the brain default branch has one writer, the
+  // distiller. Conservative charset guard: a refname git allows but a shell
+  // might mangle is skipped, never quoted-and-hoped.
+  if (branch === "main" || branch === "master" || branch === "HEAD") process.exit(0);
+  if (!/^[A-Za-z0-9._/-]+$/.test(branch)) process.exit(0);
+
+  // Lockstep ensure (post-checkout's job, repeated here belt-and-braces): dirty
+  // surfaces carry to the OLD branch first — deterministic, nothing lost.
+  const cur = shR("git rev-parse --abbrev-ref HEAD");
+  if (cur !== branch) {
+    try {
+      shR("git add -A");
+      shR(`git commit -q -m "brain(switch-carryover)" -m "switch-carryover-from: ${cur}"`);
+    } catch {
+      /* nothing dirty */
+    }
+    try {
+      shR(`git rev-parse --verify -q "refs/heads/${branch}"`);
+      shR(`git checkout -q "${branch}"`);
+    } catch {
+      shR(`git checkout -q -b "${branch}"`);
+    }
+  }
+
+  // The intent record — the commit's end-to-end intent, mechanically joined.
+  // Minimal here (sha · subject · files); the P3 capture worker enriches.
+  const fullSha = sh("git rev-parse HEAD");
+  const short = fullSha.slice(0, 12);
+  const clean = (s) => s.replace(/[`"$\\]/g, "'");
+  const subject = clean(sh("git log -1 --pretty=%s")).slice(0, 100);
+  const files = sh("git diff-tree --no-commit-id --name-only -r HEAD")
+    .split("\n")
+    .filter(Boolean)
+    .slice(0, 100);
+  mkdirSync(join(rafa, "intent"), { recursive: true });
+  writeFileSync(
+    join(rafa, "intent", `${short}.md`),
+    `---\n` +
+      `type: IntentRecord\n` +
+      `description: "per-commit intent trail (capture-engine P2) — provenance, consumed at merge, never org-brain truth"\n` +
+      `code-commit: ${fullSha}\n` +
+      `code-branch: ${branch}\n` +
+      `timestamp: ${new Date().toISOString()}\n` +
+      `---\n\n# ${subject}\n\n## Files\n` +
+      files.map((f) => `- ${f}`).join("\n") +
+      `\n`,
+  );
+
+  shR("git add -A");
+  shR(
+    `git commit --allow-empty -q -m "brain(${branch}): ${subject}" ` +
+      `-m "code-commit: ${fullSha}" -m "code-branch: ${branch}"`,
+  );
+} catch {
+  /* silent by design — the heartbeat carries sensor health */
+}
+process.exit(0);

package/blueprint/.claude/rafa/hooks/brain-map.mjs

@@ -0,0 +1,64 @@
+// rafa brain-map — the post-rewrite worker (capture-engine P1, spec r2 §2.2).
+// Rebase/amend rewrite the CODE shas; git hands the old→new map on stdin. We
+// APPEND it to the mirrored brain branch (maps/rewrite-<ts>.json) — brain
+// history is never rewritten. Collection keys on the merge event's branch
+// name; the map chain restores per-commit grounding through code-commit
+// trailers. argv[2]: "amend" | "rebase" (git's post-rewrite kind).
+
+import { execSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const ROOT = process.cwd();
+try {
+  if (process.env.RAFA_HOOKS_DISABLED === "1") process.exit(0);
+  if (!existsSync(join(ROOT, "rafa.json"))) process.exit(0);
+  if (!existsSync(join(ROOT, ".rafa", ".git"))) process.exit(0);
+
+  const map = readFileSync(0, "utf8")
+    .split("\n")
+    .filter(Boolean)
+    .map((l) => {
+      const [oldSha, newSha] = l.trim().split(/\s+/);
+      return { old: oldSha, new: newSha };
+    })
+    .filter((m) => /^[0-9a-f]{40,64}$/i.test(m.old ?? "") && /^[0-9a-f]{40,64}$/i.test(m.new ?? ""));
+  if (map.length === 0) process.exit(0);
+
+  const sh = (cmd, cwd = ROOT) =>
+    execSync(cmd, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  const rafa = join(ROOT, ".rafa");
+  const shR = (cmd) => sh(cmd, rafa);
+
+  const branch = sh("git rev-parse --abbrev-ref HEAD");
+  if (branch === "main" || branch === "master" || branch === "HEAD") process.exit(0);
+  if (!/^[A-Za-z0-9._/-]+$/.test(branch)) process.exit(0);
+
+  const cur = shR("git rev-parse --abbrev-ref HEAD");
+  if (cur !== branch) {
+    try {
+      shR("git add -A");
+      shR(`git commit -q -m "brain(switch-carryover)" -m "switch-carryover-from: ${cur}"`);
+    } catch {
+      /* nothing dirty */
+    }
+    try {
+      shR(`git rev-parse --verify -q "refs/heads/${branch}"`);
+      shR(`git checkout -q "${branch}"`);
+    } catch {
+      shR(`git checkout -q -b "${branch}"`);
+    }
+  }
+
+  const kind = process.argv[2] === "amend" ? "amend" : "rebase";
+  mkdirSync(join(rafa, "maps"), { recursive: true });
+  writeFileSync(
+    join(rafa, "maps", `rewrite-${Date.now()}.json`),
+    JSON.stringify({ kind, at: new Date().toISOString(), branch, map }, null, 2) + "\n",
+  );
+  shR("git add -A");
+  shR(`git commit -q -m "brain(rewrite-map): ${kind} · ${map.length} commit(s)" -m "code-branch: ${branch}"`);
+} catch {
+  /* silent by design */
+}
+process.exit(0);

package/blueprint/.claude/rafa/hooks/brain-switch.mjs

@@ -0,0 +1,48 @@
+// rafa brain-switch — the post-checkout worker (capture-engine P1, spec r2
+// §2.2). Keeps the nested .rafa/ repo's branch in LOCKSTEP with the code
+// branch: code branch cut/switch ⇒ brain branch cut/switch (created lazily
+// from the current local state). Dirty brain surfaces are committed to the OLD
+// branch first (switch-carryover) — deterministic, nothing lost, nothing
+// blocks. argv: <prevHEAD> <newHEAD> <flag> (git's post-checkout contract;
+// flag "1" = branch checkout, "0" = file checkout → no-op).
+
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+const ROOT = process.cwd();
+try {
+  if (process.env.RAFA_HOOKS_DISABLED === "1") process.exit(0);
+  if (process.argv[4] !== "1") process.exit(0);
+  if (!existsSync(join(ROOT, "rafa.json"))) process.exit(0);
+  if (!existsSync(join(ROOT, ".rafa", ".git"))) process.exit(0);
+
+  const sh = (cmd, cwd = ROOT) =>
+    execSync(cmd, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  const shR = (cmd) => sh(cmd, join(ROOT, ".rafa"));
+
+  const branch = sh("git rev-parse --abbrev-ref HEAD");
+  if (branch === "HEAD") process.exit(0); // detached — no mirror
+  if (!/^[A-Za-z0-9._/-]+$/.test(branch)) process.exit(0);
+
+  const cur = shR("git rev-parse --abbrev-ref HEAD");
+  if (cur === branch) process.exit(0);
+  try {
+    shR("git add -A");
+    shR(`git commit -q -m "brain(switch-carryover)" -m "switch-carryover-from: ${cur}"`);
+  } catch {
+    /* nothing dirty */
+  }
+  // Trunk mirrors to the brain repo's SAME-NAMED branch when it exists — the
+  // default branch stays the distiller's write target; the session only ever
+  // reads there. A missing trunk-named brain branch is left alone.
+  try {
+    shR(`git rev-parse --verify -q "refs/heads/${branch}"`);
+    shR(`git checkout -q "${branch}"`);
+  } catch {
+    if (branch !== "main" && branch !== "master") shR(`git checkout -q -b "${branch}"`);
+  }
+} catch {
+  /* silent by design */
+}
+process.exit(0);

package/blueprint/.claude/rafa/hooks/post-checkout

@@ -0,0 +1,10 @@
+#!/bin/sh
+# rafa post-checkout hook v1 (installed by @rafinery/cli init/pull/update).
+#
+# Capture-engine P1: brain-branch LOCKSTEP — code branch cut/switch mirrors in
+# the nested .rafa/ repo; dirty brain surfaces carry to the old branch first.
+# Non-blocking and silent on every path.
+[ "$RAFA_HOOKS_DISABLED" = "1" ] && exit 0
+[ -f "rafa.json" ] || exit 0
+node ".claude/rafa/hooks/brain-switch.mjs" "$1" "$2" "$3" >/dev/null 2>&1 || true
+exit 0

package/blueprint/.claude/rafa/hooks/post-commit

@@ -0,0 +1,11 @@
+#!/bin/sh
+# rafa post-commit hook v1 (installed by @rafinery/cli init/pull/update — safe
+# to delete; offered again, never forced over a foreign hook).
+#
+# Capture-engine P1: ONE brain commit per code commit (strict 1-1) on the
+# MIRRORED brain branch, with the commit's intent record inside. Hook-owned —
+# the dev never maintains the brain. Non-blocking and silent on every path.
+[ "$RAFA_HOOKS_DISABLED" = "1" ] && exit 0
+[ -f "rafa.json" ] || exit 0
+node ".claude/rafa/hooks/brain-commit.mjs" >/dev/null 2>&1 || true
+exit 0

package/blueprint/.claude/rafa/hooks/post-rewrite

@@ -0,0 +1,10 @@
+#!/bin/sh
+# rafa post-rewrite hook v1 (installed by @rafinery/cli init/pull/update).
+#
+# Capture-engine P1: rebase/amend safety — git's old→new sha map is APPENDED to
+# the mirrored brain branch (never rewritten); CI resolves code-commit trailers
+# through the chain. Non-blocking and silent on every path.
+[ "$RAFA_HOOKS_DISABLED" = "1" ] && exit 0
+[ -f "rafa.json" ] || exit 0
+node ".claude/rafa/hooks/brain-map.mjs" "$1" >/dev/null 2>&1 || true
+exit 0

package/blueprint/.claude/rafa/hooks/pre-push

@@ -19,6 +19,28 @@ npx -y @rafinery/cli checkpoint || {
     echo "rafa · checkpoint CONFLICT — a teammate's newer copy landed as *.theirs.md; decide in your next session (merge/adopt/keep, re-run rafa checkpoint). Push continues."
   else
     echo "rafa · checkpoint skipped (exit $code) — push continues; run 'rafa checkpoint' manually when convenient."
+    # P0: a swallowed failure must still reach the heartbeat — record it so the
+    # next checkpoint's report_sensor_health carries it (best-effort, silent).
+    mkdir -p .rafa 2>/dev/null && printf '{"t":%s000,"hook":"pre-push","error":"checkpoint exit %s"}\n' "$(date +%s)" "$code" >> .rafa/sensor-errors.jsonl 2>/dev/null || true
   fi
 }
+
+# Capture-engine P1 ceremony: durably push the MIRRORED brain branch so capture
+# survives a dead laptop, a closed PR, an abandoned branch. Trunk pushes skip —
+# the brain default branch is the distiller's; sessions never push it. A
+# diverged remote (two clones on one branch) takes a mechanical transport
+# replay; a real conflict is left intact for the next session, never forced.
+BR="$(git rev-parse --abbrev-ref HEAD 2>/dev/null)"
+if [ -n "$BR" ] && [ "$BR" != "main" ] && [ "$BR" != "master" ] && [ -d ".rafa/.git" ]; then
+  if git -C .rafa rev-parse --verify -q "refs/heads/$BR" >/dev/null 2>&1; then
+    echo "rafa · brain branch push ($BR) …"
+    git -C .rafa push -q -u origin "$BR" 2>/dev/null || {
+      git -C .rafa pull -q --rebase origin "$BR" 2>/dev/null && git -C .rafa push -q -u origin "$BR" 2>/dev/null || {
+        git -C .rafa rebase --abort >/dev/null 2>&1
+        echo "rafa · brain branch push skipped (remote diverged on the same file) — the next session reconciles; code push continues."
+        printf '{"t":%s000,"hook":"pre-push","error":"brain branch push diverged"}\n' "$(date +%s)" >> .rafa/sensor-errors.jsonl 2>/dev/null || true
+      }
+    }
+  fi
+fi
 exit 0