@rafinery/cli 0.3.0 → 0.4.0

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

@@ -0,0 +1,87 @@
+---
+name: rafa-distill
+description: "rafa SOP — merge-time reconciliation: validate a merged branch's WORKING SET against merged MAIN (prism), author survivors into the org brain through verify-citations + compile + push (atlas), refute loudly with citations; contested items flagged needs-adjudication, never guessed. Loaded on /rafa distill or the merge offer; CI runs the same SOP headlessly (rafa distill --headless)."
+---
+
+# distill — merge-time reconciliation of a branch working set into the org brain
+
+> Status: **active.** Two runners, ONE SOP: the org's CI (`rafa distill
+> --headless`, installed by `rafa ci-setup`, driven by the ORG'S OWN
+> `ANTHROPIC_API_KEY` — never stored on the platform) and the dev session
+> (offer-driven at bootstrap, or explicit `/rafa distill <branch>`) as the
+> fallback when CI isn't wired or failed. Depends on: brain (#1), the branch
+> working set (synced via `rafa checkpoint`).
+
+The rigor gradient this enforces (ratified 2026-07-10): **dev↔dev = CAS + a
+session prompt · branch↔branch = free mechanical fold (no LLM, no prism) ·
+branch→main = full distillation + gates.** Cost tracks consequence. Working-set
+files are candidate-grade — attributed, loose, never served as org truth. The
+merge to main is the one moment rigor fires: what survives validation against
+merged main enters the org brain through the normal gates; what doesn't is
+refuted loudly back to its author; what can't be decided is flagged
+`needs-adjudication` — NEVER guessed. Knowledge propagates exactly like the
+code it describes.
+
+## Trigger
+
+- **CI (normal path):** the reconcile workflow fires on the PR-merged EVENT
+  (squash/rebase-safe — ancestry is never consulted): merge to the default
+  branch → `rafa distill --headless <branch>` · branch→parent merge →
+  `rafa fold --from <branch> --to <parent>` (mechanical, no LLM).
+- **Offer (session fallback):** at bootstrap the conductor checks
+  `get_working_set` for active files on branches whose code reached main —
+  *"branch <x> merged with N working-set files — distill now?"* Part of the
+  ONE bootstrap digest. Boundary consent; accepted offer = invocation.
+- **Explicit:** `/rafa distill <branch>`.
+
+## Procedure (the trio, distillation roles)
+
+1. **Collect** — `get_working_set(repo, branch, status: active)`. Zero files →
+   nothing to do, say so, stop. Rows already `needs-adjudication` are a HUMAN's
+   to resolve — surface them in the digest, never fold them in silently.
+2. **Validate (prism, context-isolated)** — the target is **merged MAIN as of
+   NOW, never the fork point and never a stale checkout**: `git fetch origin`
+   first; judge every claim against the fetched trunk. Confirm every citation
+   resolves (the cited line contains its token — grep it yourself). A claim
+   that can't be confirmed with a `file:line` is REFUTED (cited reason).
+   Contested/low-confidence → `needs-adjudication`, never a guess. Files about
+   code the merge did NOT touch are judged on their own merits, same bar.
+3. **Author (atlas)** — for each survivor: write/update the org-brain file
+   (contract §2) with real cites into main; `anchor:` on contracts (hydrated
+   files lost it — re-declare); fold into an existing note when one covers the
+   topic (supersede, never duplicate).
+4. **Gate + ship** — `rafa verify-citations` AND `rafa compile` to exit 0 →
+   `rafa push`. Only now has anything entered the org brain. A failed gate
+   aborts EVERYTHING: nothing resolved, nothing pushed, working set intact.
+5. **Resolve** — `resolve_working_file(path, distilled)` for survivors —
+   CAS: only a live row resolves; a failure means ANOTHER runner already
+   distilled this branch — STOP and reconcile against what it shipped.
+   `resolve_working_file(path, refuted, note)` for failures — TELL the author
+   which files died and why (cited); refutation is feedback, not silence.
+   `resolve_working_file(path, needs-adjudication, note)` for the undecidable —
+   the next session's digest offers the decision.
+
+## Branch→branch merges (sub-feature → feature): FOLD, don't distill
+
+Distillation targets ONLY the default branch. When a sub-feature merges into
+its parent branch, the working set is **folded forward mechanically** —
+`rafa fold --from <branch> --to <parent>` (or the CI fold job): absent on the
+parent → re-keyed · identical content → merged silently · true same-file
+divergence → `needs-adjudication` on the parent row (incoming preserved,
+attributed). No LLM, no prism — the knowledge keeps riding with the code until
+the code reaches main.
+
+Sub-feature CONTEXT: a branch's working knowledge = org brain (via MCP) + its
+own working set + unmerged ANCESTOR branches' working sets (the conductor
+derives the ancestor chain from git and calls `get_working_set` per ancestor —
+the platform stores no lineage).
+
+## Rules
+
+- Validation target is main at distillation time, never the fork point.
+- An abandoned branch's working set is never distilled — it dies with the
+  branch (propagation mirrors code).
+- No file skips steps 2–4; there is no fast path into the org brain.
+- CI can detect and flag; only a dev session resolves a human's divergence.
+- Dev-level observations found among the files route to `put_dev_insight`
+  (the author's user brain), never to the org brain.

package/blueprint/{.rafa/capabilities/improve.md → .claude/skills/rafa-improve/SKILL.md}

@@ -1,3 +1,8 @@
+---
+name: rafa-improve
+description: "rafa SOP — bloom's continuous-improvement pass: multi-lens, cited, prioritized (P0–P3) ledger of the silent rot no gate catches; leverage-ranked, advisory, never nagging. Loaded on /rafa improve."
+---
+
 # improve — continuous improvement  (capability #2)
 
 rafa's second mission: **drive the codebase worst → well-managed, compounding via work
@@ -42,12 +47,12 @@ Invoke via `/rafa improve`. The brain (#1) must exist — bloom *uses* it as the
 - `improvements/<id>.md` — one file per improvement (cited, prioritized, status-tracked).
 - `ledger.md` — generated index: counts by priority/lens/status + the **health/debt trend**.
   Its **frontmatter carries the machine-read `open` · `debt_score` · `by_priority`** (per
-  [`.rafa/contract.md`](../contract.md) §5) — the platform reads *that*, never the body tables,
+  [`.claude/rafa/contract.md`](../../rafa/contract.md) §5) — the platform reads *that*, never the body tables,
   and `rafa compile` cross-checks `open`/`by_priority` against the actual improvement rows.
 - `manifest.json` — regenerated by `rafa compile`; the JSON the platform ingests. Never hand-edit.
 - `citation-check.md` — generated by the checker (improvement cites resolve).
 
-**Improvement schema.** The **strict contract is [`.rafa/contract.md`](../contract.md) §3** —
+**Improvement schema.** The **strict contract is [`.claude/rafa/contract.md`](../../rafa/contract.md) §3** —
 `rafa compile` rejects violations. `title`, `summary`, `fix` are **required frontmatter** (the
 platform shows them; nothing is scraped from prose). Example *illustrative — from the rafa repo*:
 ```yaml
@@ -89,13 +94,13 @@ convention — see [[rsc-client-boundary]]). Compiles + runs, so no gate catches
    whose code is now clean (`status: fixed`); **preserve** the dev's prior triage
    (backlog/wontfix stay).
 5. **Cite-check (the fidelity gate).** Run
-   `node .rafa/bin/verify-citations.mjs --root=.rafa/improve --dirs=improvements`. Every cite
+   `npx @rafinery/cli verify-citations --root=.rafa/improve --dirs=improvements`. Every cite
    must resolve; **drop or fix any that don't** — a hallucinated improvement is the cardinal sin.
 6. **Ledger + trend.** Regenerate `ledger.md`: counts by priority/lens/status + a **debt
    score** (weighted open improvements) and its trend vs the last run — the compounding made
    visible. Write the machine-read **frontmatter** `open` · `debt_score` · `by_priority`
-   ([contract §5](../contract.md)) — the platform reads that.
-7. **Contract gate.** Run `node .rafa/bin/rafa-compile.mjs`. Fix every `path · field · rule`
+   ([contract §5](../../rafa/contract.md)) — the platform reads that.
+7. **Contract gate.** Run `npx @rafinery/cli compile`. Fix every `path · field · rule`
    violation (missing `title`/`summary`/`fix`, bad enum, ledger counts not matching rows) and
    re-run until it **exits 0** and writes `manifest.json`. Validate-and-correct: a
    schema-invalid brain never ships.

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

@@ -0,0 +1,71 @@
+---
+name: rafa-insights
+description: "rafa SOP — compass's user brain: bootstrap from the dev's native /insights report, refine with consent, steer back at boundaries; account-scoped, cross-repo, private. Loaded on /rafa insights and routed capture moments."
+---
+
+# insights — the user brain: bootstrap, refine, steer  (compass's SOP)
+
+> Status: **active (v1 — conductor-mediated).** Invoke via `/rafa insights`
+> (bootstrap/refresh) — capture during work is the conductor's job (rafa.md
+> §capture routes dev-level observations here). Store: `put_dev_insight` /
+> `list_dev_insights` / `remove_dev_insight` (account-scoped, cross-repo).
+
+## The creed (owner, verbatim — non-negotiable)
+**"We are not stealing their knowledge; we are working with them to refine
+their knowledge to do bigger things in better way."** Partnership, not
+extraction. The dev is the beneficiary AND co-author of their own refinement.
+The measure of this work is the dev doing bigger things better — never the dev
+becoming legible to anyone else.
+
+## Honesty about tenancy (pre-orgs)
+Until org accounts land, teammates' keys live under the repo owner's platform
+account: MCP scoping keeps one KEY from reading another's insights, but the
+ACCOUNT owner can see data stored under their account on the platform. When
+the key isn't the account owner's, the offer says so: *"banked privately to
+your key — note: stored under this repo owner's account until org accounts
+ship."* Consent means informed.
+
+## The boundary (both directions, no exceptions)
+- Nothing **code-cited** enters the user brain (code facts → the branch working set →
+  org brain via distillation).
+- Nothing **person-scoped** leaves it — not to teammates, not to repo activity
+  feeds, not to aggregates without explicit standing consent. This floor is
+  enforced in the platform dispatch, not just here.
+
+## Procedure
+
+### 1. Bootstrap (first run, or on request)
+Read the dev's native usage report (Claude Code `/insights` — ask the dev to
+run it if absent; its report lands at `~/.claude/usage-data/report.html`).
+**Distill with judgment — never parse the HTML mechanically** (its shape is
+unversioned; the model reads it like a document). Extract dev-level signals
+only: asking/decomposition patterns, repeated instructions (each is a candidate
+preference), friction loops, unused leverage. For each candidate: show the dev,
+**offer** — banked only on yes (`put_dev_insight`, kind pattern|preference|
+constraint).
+
+### 2. Continuous refinement (every session, conductor-routed)
+**Before ANY put: `list_dev_insights` first.** Update the matching existing
+insight (its id) instead of creating a near-copy — and NEVER re-offer an
+insight the dev deleted (deleted rows persist as content-erased tombstones in
+the list precisely so you can honor the refusal: "you removed this before; not
+re-suggesting"). **Never bank a secret**: a stated constraint quoting a
+credential is rephrased value-free before the offer (the platform screens too —
+don't rely on it).
+Capture moments: a correction repeated across sessions · a stated preference ·
+a named constraint · a friction loop. Route: dev-level → offer → bank;
+code-level → the branch working set (not yours — rafa.md §capture routes it). Update beats duplicate: refine the
+existing insight (`put_dev_insight` with its id) rather than accreting near-
+copies.
+
+### 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
+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.
+
+### 4. Legibility (consent's other half)
+On request, show everything (`list_dev_insights`), correct anything, delete
+anything (`remove_dev_insight`) — no residue, no argument. An insight the dev
+says is wrong IS wrong.

package/blueprint/{.rafa/capabilities/leverage.md → .claude/skills/rafa-leverage/SKILL.md}

@@ -1,3 +1,8 @@
+---
+name: rafa-leverage
+description: "rafa SOP — tune the dev's agent toolbox: detect missing/misconfigured/unused permissions, skills, MCP servers; on approval apply exact merges. Loaded on /rafa leverage."
+---
+
 # leverage — get more out of the toolbox you already have  (capability #3)
 
 rafa's third mission: **make the dev's agent toolchain pull its full weight.** rafa already
@@ -37,11 +42,11 @@ at the fix. This is platform DNA: **leverage what's present; never reinvent it.*
 
 ## Architecture — the ToolchainAdapter seam
 
-The engine ([`lib/leverage/engine.mjs`](../../packages/cli/lib/leverage/engine.mjs)) gathers
+The engine ([`lib/leverage/engine.mjs`](../../../packages/cli/lib/leverage/engine.mjs)) gathers
 light, tool-agnostic repo signals (`repoContext`: stack deps, `.env` files + whether they're
 ignored, declared MCP servers), then runs every **detected** adapter and ranks the tips.
 
-Each adapter implements one contract ([`lib/leverage/adapters/index.mjs`](../../packages/cli/lib/leverage/adapters/index.mjs)):
+Each adapter implements one contract ([`lib/leverage/adapters/index.mjs`](../../../packages/cli/lib/leverage/adapters/index.mjs)):
 
 | Member | Shape | Job |
 |---|---|---|
@@ -57,7 +62,7 @@ list) — the seam is real, the adapters are added when a user actually runs on
 
 ### What the Claude Code adapter checks today
 - **Secrets** — `.env*` present but not gitignored → `P1` (protect the keys before a scan or a commit).
-- **Permissions** — `.rafa/bin` vendored but its tools aren't allow-listed / no `settings.json`
+- **Permissions** — rafa provisioned but its CLI commands are not allow-listed / no `settings.json`
   → `P2`, fix = `rafa init`/`update` (which *merge*, never clobber — see the CLI).
 - **MCP** — a stack with no matching server wired (e.g. Convex repo, no `convex` MCP) → `P2`.
 - **Skills** — no project skills captured → `P3`.
@@ -70,7 +75,7 @@ behind the same contract. The engine and the `rafa leverage` command never chang
 ## Boundaries
 
 - **Committed config only.** Read the repo's `.claude/` (org config). The dev's personal
-  `~/.claude/` is private — never inspected. (Mirrors [scan](scan.md)'s privacy line.)
+  `~/.claude/` is private — never inspected. (Mirrors [scan](../rafa-scan/SKILL.md)'s privacy line.)
 - **Secrets are off-limits.** Detect that an `.env` is unprotected; **never open it or read a
   value.** Same hard line as the scan guardrail.
 - **Read-only.** leverage itself mutates nothing. The only writes are `rafa init`/`update`

package/blueprint/{.rafa/capabilities/plan.md → .claude/skills/rafa-plan/SKILL.md}

@@ -1,3 +1,8 @@
+---
+name: rafa-plan
+description: "rafa SOP — brain-grounded, prism-validated decomposition of an intent into contract §7 plan files (each child with a Done-check); plan-lite for small blast radius. Loaded on /rafa plan or plan-shaped intent."
+---
+
 # plan — brain-grounded, prism-validated decomposition  (capability #3)
 
 > Status: **active.** The first *consumer* of the stores — where the brain starts to
@@ -14,7 +19,10 @@ Planning is a choreography, not one agent (spec: knowledge-mcp-build-agent):
 - **atlas drafts** — RECALL the brain slice for the intent's domains through the
   knowledge MCP (`get_coverage` to navigate → `search_knowledge` → `get_rule` /
   `get_playbook`, including non-exemplars), name the BLAST RADIUS from coverage,
-  decompose into parent + child plan files.
+  decompose into parent + child plan files. *Recall is automatic — the SOP calls
+  the tools; the dev never asks for it. Repo not platform-connected (no `rafinery`
+  MCP in the session)? Fall back to reading `.rafa/brain/` files directly — same
+  knowledge, just unserved.*
 - **bloom pulls** — `list_improvements` in the blast radius; surface the
   top-leverage open items as optional *"while-you're-here"* child tasks
   (leverage-ranked, dismissible, never blocking).
@@ -38,8 +46,27 @@ Planning is a choreography, not one agent (spec: knowledge-mcp-build-agent):
 5. **prism plan-validation** → REJECT/fix loop until clean.
 6. **Approval gate** (owner). Then materialize `plans/<plan>/*.md` per contract §7
    (parent + child-owned files, globally-unique prefixed ids) + `active.md` pointer
-   → `rafa compile` → `rafa push` (the plan is now resumable from ANY session,
-   machine, or teammate via `get_active_plan`).
+   → `rafa compile` (validate the files) → **`push_plan` + `set_active_plan`
+   immediately, no second prompt — plan approval IS the push trigger** (the
+   dedicated plans channel; plans never ride the brain manifest). The dev just
+   approved this exact content; a connected repo renders it on the platform
+   within moments, resumable from ANY session, machine, or teammate — *"list
+   plans"* shows names only; *"load plan X"* (`get_plan`) materializes the full
+   plan (bodies included) back into `.rafa/plans/`.
+
+## plan-lite — the light path (a mode of THIS SOP, not a bypass)
+The full choreography earns its weight on cross-cutting work; a one-file change routed
+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):
+
+- **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
+  carries a `## Done-check`. Same contract §7 files, same compile, same approval.
+- **Full** (anything wider): the complete procedure above.
+
+The dev can force either: `/rafa plan` always offers the choice when the radius is
+borderline; "skip" bypasses planning entirely (their call — note it, never police it).
 
 ## Deferred / open
 - Capture-back of plan-time decisions → brain (needs the capture engine).

package/blueprint/{.rafa/capabilities/scan.md → .claude/skills/rafa-scan/SKILL.md}

@@ -1,3 +1,8 @@
+---
+name: rafa-scan
+description: "rafa SOP — atlas's founding scan: map the whole codebase into cited rules/playbooks + coverage, breadth before depth, every citation mechanically verified. Loaded when the /rafa conductor runs scan or init; atlas follows it verbatim."
+---
+
 # Scan — capability
 
 atlas's founding contribution to the brain: read the **whole** codebase and write its
@@ -63,7 +68,7 @@ A well-formed note with a wrong citation is worse than no note — a dev greps t
 file, finds nothing, and stops trusting the brain. So fidelity is non-negotiable:
 
 - **Every citation is mechanically checked — by script, all of them.** Write each cite as
-  `file:line :: token`, then run `node .rafa/bin/verify-citations.mjs`, which asserts
+  `file:line :: token`, then run `npx @rafinery/cli verify-citations`, which asserts
   every cited line contains its token and exits non-zero on any miss. Fix every ✗ until it
   exits 0. A "spot-check" does NOT satisfy this. Off-by-N or wrong-file → fix or drop.
 - **Contract sites come from grep, not memory — and the checker enforces it.** Every
@@ -87,10 +92,10 @@ file, finds nothing, and stops trusting the brain. So fidelity is non-negotiable
 - `.rafa/brain/rules/*.md` — `convention` + `contract` notes ("what not to break")
 - `.rafa/brain/playbooks/*.md` — `flow` + `how-to` notes ("how it works / how to add X")
 - `.rafa/brain/coverage.md` — the coverage report. **Machine-read frontmatter** per
-  [`.rafa/contract.md`](../contract.md) §6: `domains: { <domain>: mapped|thin|stubbed|empty, … }`
+  [`.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.
 
-**Note format.** The **strict contract is [`.rafa/contract.md`](../contract.md) §2** — every
+**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
 `path · field · rule` error you must fix. Machine-read fields live in frontmatter; the body is
 prose (never parsed). The example is *illustrative — a contract from the rafa reference repo*:
@@ -173,7 +178,7 @@ retrieval index. Bodies read like a senior engineer explaining that one concept
 
 7. **Verification & synthesis** — apply the 100× filter (a note earns a file only if it
    answers a work-time question AND eliminates a recurring tax), then write the notes. Run
-   the **deterministic citation checker** — `node .rafa/bin/verify-citations.mjs` — which
+   the **deterministic citation checker** — `npx @rafinery/cli verify-citations` — which
    verifies every `file:line :: token` cite resolves (B1) AND that every contract `anchor:`'s
    code occurrences are all cited (B2); fix every ✗ and re-run until it **exits 0**. It
    writes `.rafa/brain/citation-check.md` — **reference that file** from `coverage.md`,
@@ -182,8 +187,8 @@ retrieval index. Bodies read like a senior engineer explaining that one concept
    Step-1 checklist — every domain has ≥1 note or is flagged thin/stubbed; no silent
    truncation). Finalize `coverage.md` with per-criterion PASS/FAIL.
 
-   Finally, run the **contract gate** — `node .rafa/bin/rafa-compile.mjs` — which validates
-   every file against [`.rafa/contract.md`](../contract.md) and emits `.rafa/manifest.json`
+   Finally, run the **contract gate** — `npx @rafinery/cli compile` — which validates
+   every file against [`.claude/rafa/contract.md`](../../rafa/contract.md) and emits `.rafa/manifest.json`
    (the JSON the platform ingests). It fails loudly with `path · field · rule` errors; **fix
    every one and re-run until it exits 0.** This is the validate-and-correct loop: a
    schema-invalid brain never ships, and the platform never guesses a value. Do not hand-edit
@@ -211,7 +216,7 @@ A scan **PASSES only if every box below is true.** Any single failure → `itera
 - [ ] **A4** Every `thin`/`stubbed`/`empty` domain states why. (a silent gap = FAIL.)
 
 **B · Fidelity — verify, don't infer (hard gate)**
-- [ ] **B1** `node .rafa/bin/verify-citations.mjs` **exits 0** — every `file:line :: token`
+- [ ] **B1** `npx @rafinery/cli verify-citations` **exits 0** — every `file:line :: token`
       cite mechanically verified (all, not a sample); its table pasted in `coverage.md`.
       A spot-check, or a PASS without the checker exiting 0, = FAIL.
 - [ ] **B2** Every `type: contract` declares `anchor:` — a token, or `anchor: none` (with
@@ -238,9 +243,9 @@ A scan **PASSES only if every box below is true.** Any single failure → `itera
 **D · Format & contract**
 - [ ] **D1** Output is exactly `.rafa/brain/rules/` + `.rafa/brain/playbooks/` +
       `.rafa/brain/coverage.md`. **No `graph.json`.**
-- [ ] **D2** Every note has valid frontmatter per [`.rafa/contract.md`](../contract.md) §2
+- [ ] **D2** Every note has valid frontmatter per [`.claude/rafa/contract.md`](../../rafa/contract.md) §2
       (incl. required `schemaVersion`, `title`, `summary`).
-- [ ] **D3** `node .rafa/bin/rafa-compile.mjs` **exits 0** and writes `.rafa/manifest.json`.
+- [ ] **D3** `npx @rafinery/cli compile` **exits 0** and writes `.rafa/manifest.json`.
       Any `path · field · rule` violation = FAIL — fix and re-run (validate-and-correct).
 
 The report must state PASS/FAIL **per criterion** (not a summary verdict), so iteration

package/blueprint/{.rafa/capabilities/validate.md → .claude/skills/rafa-validate/SKILL.md}

@@ -1,3 +1,8 @@
+---
+name: rafa-validate
+description: "rafa SOP — prism's independent scan QA: re-run every check against the code, adversarial probes, verdict + score to checklist.md. Loaded when prism validates a brain; never trusts the producer's claims."
+---
+
 # Validate — prism's SOP (scan QA)
 
 Standard operating procedure for **prism** to validate a atlas scan. Independent,
@@ -20,19 +25,19 @@ agent. So:
 
 ## Inputs / preconditions
 - The brain: `.rafa/brain/` (`rules/`, `playbooks/`, `coverage.md`).
-- The repo (ground truth) + the checker `.rafa/bin/verify-citations.mjs`.
+- The repo (ground truth) + the checker ``rafa verify-citations` (in @rafinery/cli)`.
 - The bar: `scan.md` § Acceptance criteria (A–D) + the quality rubric below.
 - You run in **fresh context** — you have NOT seen how the scan was produced. Keep it that way.
 
 ## Procedure (run in order; ground everything in code)
 
-1. **Re-run the checker yourself** — `node .rafa/bin/verify-citations.mjs`. Record exit
+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.
 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.
-   (b) **Mutation self-test** — run `node .rafa/bin/verify-citations.mjs --selftest`. It
+   (b) **Mutation self-test** — run `npx @rafinery/cli verify-citations --selftest`. It
    proves the checker's logic *fails on a bad cite and passes a good one* (on a throwaway
    temp file — no brain/repo pollution, no debris). It must print PASS and **exit 0**.
    Re-running the checker (step 1) is not proof it still works; this is.
@@ -66,7 +71,10 @@ agent. So:
 - **Blocker** — hard-gate failure, broken checker, or a wrong/misleading note. Must be **0**.
 - **Major** — a real gap: missing essence, under-covered domain, unanswerable question.
 - **Minor** — nits (orphan, cosmetic). Logged, not looped on.
-- **PASS** = hard gates pass · quality score ≥ 85 · 0 blockers · majors ≤ 2. Else **ITERATE**.
+- **PASS** = hard gates pass · quality score ≥ 85 · 0 blockers · majors ≤ 2 · **and no
+  unflagged salient-but-wrong exemplar** (an open 5b finding → **auto-ITERATE regardless
+  of score** — salience gets copied, so one unflagged exception poisons every cold agent;
+  the numeric bar alone must never pass it). Else **ITERATE**.
 
 ## Quality score (0–100) — only meaningful once hard gates (fidelity + coverage) pass
 | Weight | Dimension | Measure |
@@ -106,7 +114,8 @@ hard-gate fail write `score: 0` (not `null` — the contract requires an int).
 - **Findings ledger** — blocker / major / minor, each cited (`file:line`) + a suggested fix.
 
 You write **`checklist.md` only**. The **conductor** owns `log.md` (the round-by-round trail).
-PASS = hard gates pass · score ≥ 85 · 0 blockers · majors ≤ 2.
+PASS = hard gates pass · score ≥ 85 · 0 blockers · majors ≤ 2 · no unflagged salient-but-wrong
+exemplar (5b override — auto-ITERATE).
 
 ## The ratchet
 Any judgment finding you raise repeatedly that *could* be mechanized → recommend it become a

package/lib/blueprint.mjs

@@ -16,33 +16,43 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 // Two classes of blueprint file:
-//  - owned    → the client tunes these (agents, SOPs). We NEVER clobber a modified copy;
-//               a changed file is written alongside as `<file>.new` so the dev merges by hand.
-//  - lockstep → tools + contract. These move with the CLI version, so they overwrite.
+//  - owned    → the client tunes these (agents, commands, skills). We NEVER clobber a
+//               modified copy; a conflict asks (shadcn-style).
+//  - lockstep → the contract. It moves with the CLI version (the CLI implements it),
+//               so it overwrites.
+// Blueprint split (0.4.0): the gate TOOLS are not here — they live inside this
+// package (lib/gate). Capabilities ship as committed SKILLS (.claude/skills/rafa-*)
+// so behavior versions with the code repo, MR-reviewed and clone-complete. `.rafa/`
+// itself is never vendored — it is lazy, gitignored knowledge+state.
 export const BLUEPRINT = {
   owned: [
     ".claude/agents/atlas.md",
     ".claude/agents/prism.md",
     ".claude/agents/bloom.md",
+    ".claude/agents/compass.md",
     ".claude/commands/rafa.md",
   ],
-  ownedDirs: [".rafa/capabilities"],
-  lockstep: [
-    ".rafa/contract.md",
-    ".rafa/bin/verify-citations.mjs",
-    ".rafa/bin/rafa-compile.mjs",
-    ".rafa/bin/rafa-push.mjs",
+  ownedDirs: [
+    ".claude/skills/rafa-scan",
+    ".claude/skills/rafa-validate",
+    ".claude/skills/rafa-plan",
+    ".claude/skills/rafa-build",
+    ".claude/skills/rafa-improve",
+    ".claude/skills/rafa-distill",
+    ".claude/skills/rafa-insights",
+    ".claude/skills/rafa-leverage",
   ],
+  lockstep: [".claude/rafa/contract.md"],
 };
 
 const HERE = dirname(fileURLToPath(import.meta.url)); // …/packages/cli/lib
 
-// Walk up to the monorepo root (the dir that holds the source `.rafa/contract.md`).
+// Walk up to the monorepo root (the dir that holds the canonical contract).
 function findRepoRoot() {
   let d = HERE;
   for (let i = 0; i < 8; i++) {
     d = join(d, "..");
-    if (existsSync(join(d, ".rafa", "contract.md"))) return d;
+    if (existsSync(join(d, ".claude", "rafa", "contract.md"))) return d;
   }
   return null;
 }
@@ -52,7 +62,7 @@ function findRepoRoot() {
 //  - dev in the monorepo → the repo root itself
 export function blueprintSource() {
   const bundled = join(HERE, "..", "blueprint");
-  if (existsSync(join(bundled, ".rafa", "contract.md"))) return bundled;
+  if (existsSync(join(bundled, ".claude", "rafa", "contract.md"))) return bundled;
   const root = findRepoRoot();
   if (root) return root;
   throw new Error(

package/lib/brain-repo.mjs

@@ -0,0 +1,100 @@
+// The lazy `.rafa/` bootstrap — the committed rafa.json is the anchor.
+//
+// Blueprint split (0.4.0): `.rafa/` is created lazily, gitignored, per working
+// copy — it is NEVER vendored and never travels through the code repo. Any
+// command that needs the brain repo (push/pull/distill) calls ensureBrainRepo(),
+// 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 { execSync } from "node:child_process";
+import { join } from "node:path";
+import { readStamp } from "./stamp.mjs";
+
+export const die = (m) => {
+  console.error(`✗ ${m}`);
+  process.exit(1);
+};
+
+export const inDir = (dir) => (cmd) =>
+  execSync(cmd, { cwd: dir, stdio: ["ignore", "pipe", "pipe"], encoding: "utf8" }).trim();
+
+// The brain remote recorded at provision time (committed, secret-free).
+export function brainRemote(cwd) {
+  const stamp = readStamp(cwd);
+  return typeof stamp.brainRepo === "string" && stamp.brainRepo !== ""
+    ? stamp.brainRepo
+    : null;
+}
+
+// Ensure `.rafa/` exists as its own git repo wired to the brain remote.
+// Order of truth: an existing `.rafa/.git` origin wins (a machine wired by an
+// older init keeps working); otherwise bootstrap from the committed rafa.json.
+// Returns { rafaDir, remote, bootstrapped }.
+export function ensureBrainRepo(cwd, { requireRemote = true } = {}) {
+  const rafaDir = join(cwd, ".rafa");
+  const inRafa = inDir(rafaDir);
+  let bootstrapped = false;
+
+  if (!existsSync(rafaDir)) {
+    mkdirSync(rafaDir, { recursive: true });
+    bootstrapped = true;
+  }
+  if (!existsSync(join(rafaDir, ".git"))) {
+    inDir(cwd)(`git -C ${JSON.stringify(rafaDir)} init -b main`);
+    bootstrapped = true;
+  }
+
+  let remote = null;
+  try {
+    remote = inRafa("git remote get-url origin");
+  } catch {
+    const fromStamp = brainRemote(cwd);
+    if (fromStamp) {
+      inRafa(`git remote add origin ${fromStamp}`);
+      remote = fromStamp;
+      bootstrapped = true;
+    }
+  }
+  if (requireRemote && !remote)
+    die(
+      "no brain remote — this repo's rafa.json has no `brainRepo` and `.rafa/` has no origin.\n" +
+        "  Provision via `rafa init <setup-url>` (platform), or add `\"brainRepo\": \"<git url>\"` to rafa.json.",
+    );
+
+  // CI auth (rafa ci-setup): a workflow has no interactive git credentials —
+  // RAFA_BRAIN_TOKEN (repo secret) is injected into the https remote for THIS
+  // working copy only. Never stored on the rafinery platform, never printed.
+  const token = process.env.RAFA_BRAIN_TOKEN;
+  if (token && remote?.startsWith("https://") && !remote.includes("@")) {
+    inRafa(
+      `git remote set-url origin ${remote.replace("https://", `https://x-access-token:${token}@`)}`,
+    );
+  }
+
+  // Session/state debris never rides a brain push: the sidecar, conflict
+  // copies, and distill staging are transport-excluded here (not knowledge).
+  const ignore = join(rafaDir, ".gitignore");
+  const IGNORES = "hydration.json\n*.theirs.md\ndistill-incoming/\ndistill-verdicts.json\n";
+  if (!existsSync(ignore)) writeFileSync(ignore, IGNORES);
+
+  return { rafaDir, remote, bootstrapped };
+}
+
+// The brain repo's default branch (HEAD symref) — never assume "main".
+export function remoteDefaultBranch(rafaDir, fallback = "main") {
+  try {
+    const symref = inDir(rafaDir)("git ls-remote --symref origin HEAD");
+    const m = symref.match(/ref:\s+refs\/heads\/(\S+)\s+HEAD/);
+    if (m) return m[1];
+  } catch {
+    /* unreachable remote — caller decides how loud to be */
+  }
+  return fallback;
+}
+
+// Seed the generated active pointer if absent (state, not knowledge).
+export function ensureActivePointer(rafaDir) {
+  const p = join(rafaDir, "active.md");
+  if (!existsSync(p)) writeFileSync(p, "# No active plan\n");
+}