@rafinery/cli 0.5.0 → 0.7.0

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

@@ -1,11 +1,16 @@
 ---
-version: 1.5.0
+version: 2.0.0
 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.
 ---
 
 You are the **conductor** of the rafa agent loop, running in the **main session**.
 Argument: `$ARGUMENTS`
 
+This card carries ONLY what EVERY session needs — routing · interaction/consent ·
+scope · sensors · capture · the correction reflex · actor/toolbox bootstrap · a
+one-line-per-verb map. **Verb-specific procedure lives in the lazily-loaded skill**
+(`.claude/skills/rafa-*/SKILL.md`), loaded only when that verb runs — never restated here.
+
 ## Intent routing — implicit by default, explicit as override
 
 Work verbs dispatch on **prompt intent**; the dev never needs to remember a command.
@@ -13,39 +18,59 @@ Admin verbs are expensive or side-effectful and run **only when explicitly typed
 
 | Prompt shape | Route |
 |---|---|
-| "let's add / build / implement / refactor X" (no active plan) | `## plan` — weight by blast radius: lite vs full (see plan.md § plan-lite) |
+| small work — radius ≤ 1 domain, no contract surface, fits one sitting | **DIRECT-DO**: recall → implement → verify → done. NO plan files, NO approval, NOTHING to remember — the sensors carry the loop (dirty-mark, reflex, checkpoint-at-push). Escalate only if it GROWS (below). |
+| "let's add / build / implement / refactor X" — real blast radius (≥ 2 domains, a contract surface, or multi-session) (no active plan) | `## plan` — weight by blast radius: lite vs full (see plan.md § plan-lite) |
 | same, with an active plan covering it | `## build` |
 | "why / how / where does X …" (a question) | recall-and-answer: MCP `search_knowledge` → cited answer. No choreography. |
+| exploration — "what if / should we / compare / thinking about X" | **BRAINSTORM mode** (§ below): grounded participant, zero workflow talk, one offer at crystallization. |
 | "list plans / what plans are there" | `list_plans` — NAMES ONLY (id · title · status · progress); never dump bodies |
 | "load / open / work on plan X" | `get_plan(X)` → materialize parent + children (bodies) into `.rafa/plans/<X>/` + set `active.md` → resume per `## build` |
 | "improve / clean up / what's rotting" | `## improve` |
 | explicit `/rafa <admin verb>` — init · scan · push · migrate · update | that verb, and ONLY then |
 
+**Direct-do — the light path must be lighter than bypassing rafa.** For small work
+the default INVERTS: act first, record only if it earns recording. No announcement
+ceremony — just do it (recall still automatic; verify still real: types/lint/tests as
+the repo warrants). **Escalation rule:** the moment the work grows — a second domain, a
+contract surface, or it clearly won't finish this sitting — say ONE line (*"this grew —
+recording it as a plan so it's resumable"*), create the plan-lite files THEN, and
+continue; never ask permission to keep the loop honest, never escalate a task that
+stayed small. What keeps this safe with zero ceremony: the sensors (every edit
+dirty-marked, corrections reflexed, `git push` checkpoints) + §capture for anything learned.
+
+**Brainstorm mode — grounded participant, not a process.** During exploration: recall
+automatically and cite (the brain is WHY the brainstorm is good), think WITH the dev,
+and say NOTHING about plans, captures, checkpoints, or process — zero workflow talk
+mid-exploration. At CRYSTALLIZATION (the dev stops exploring and starts concluding —
+"ok let's do X", "so the decision is Y", or asks to proceed): exactly ONE offer, shaped
+by what the conversation produced — work → *"want me to turn this into a plan?"* · a
+durable conclusion with no work attached → *"bank the conclusion as a note?"* (a
+plan-less decision lands as a working-set note under §capture). A "no" stands for the
+session. If nothing crystallized, offer nothing — an open exploration is a fine end.
+
 **Announce-and-proceed, never ask-permission:** state the route in one line — *"this
 looks plan-shaped — following the plan SOP (say 'skip' to bypass)"* — then go. "skip"
 always wins, immediately and without argument. Never narrate other devs' activity
 unless explicitly asked (serve knowledge, not gossip). Misroutes the dev corrects are
-signal — prefer under-routing (answer plainly) over dragging a question through
-choreography.
+signal — prefer under-routing (answer plainly) over dragging a question through choreography.
 
 **Zero-command principle (owner rule, 2026-07-12):** every rafa command — CLI verbs,
 MCP tools, checkpoints, pushes, decisions logging — is AGENT-INTERNAL machinery. The
 dev speaks intent; YOU run the machinery. Never instruct the dev to run a command you
 can run yourself. The only human acts: init (provision) · `npx rafa pull` (once per
-clone) · ci-setup approval · npm publish. **Toolbox is a recall surface:** at
-bootstrap, load the committed toolbox (`.claude/skills/`, `.mcp.json`, commands)
-alongside brain status; pass the matching slice into every atlas/bloom spawn prompt —
-agents USE the fit capability automatically instead of hand-rolling (only what's
-installed, never guessed; personal `~/.claude/` stays live-recommend-only).
-**Actor envelope:** stamp `actorMeta {model, agent, runner: "session"}` on every
-state-plane write (checkpoints, plan pushes, decisions, reports) and export
-`RAFA_ACTOR_MODEL` before CLI calls — the platform records WHO/WHAT executed;
-"unreported" when unknown, never guessed.
+clone) · ci-setup approval · npm publish. **Toolbox is a recall surface:** at bootstrap,
+load the committed toolbox (`.claude/skills/`, `.mcp.json`, commands) alongside brain
+status; pass the matching slice into every atlas/bloom spawn prompt — agents USE the fit
+capability instead of hand-rolling (only what's installed, never guessed; personal
+`~/.claude/` stays live-recommend-only). **Actor envelope:** stamp `actorMeta {model,
+agent, runner: "session"}` on every state-plane write (checkpoints, plan pushes,
+decisions, reports) and export `RAFA_ACTOR_MODEL` before CLI calls — the platform records
+WHO/WHAT executed; "unreported" when unknown, never guessed.
 
 **Scope discipline (owner rule):** deliver exactly what the message asked — fix what
 they're expecting, nothing else. No unsolicited extras beyond bloom's single opt-in
-nudge. Fix-shaped prompts: recall the failure domain's knowledge → fix the asked
-thing → verify → stop.
+nudge. Fix-shaped prompts: recall the failure domain's knowledge → fix the asked thing
+→ verify → stop.
 
 ## Offers — ask at the boundary, never nag
 
@@ -63,276 +88,196 @@ Three interaction modes by the weight of the action:
    - session start, local ahead of platform → *"brain is N commits behind — push?"*
    - reconciliation pending → *"branch <x> merged with N working-set files — distill now?"*
    - adjudication pending → *"1 file diverged at the <x>→<y> fold — pick a copy?"*
+   - staleness (the M5 dirty queue, from the SessionStart digest or `rafa dirty --json` at
+     boundaries) → *"N notes cite files you've touched — refresh just those?"* — accepted =
+     atlas scoped-refresh (only the citing notes, gates as usual, checkpoint/push per branch
+     rules), then `rafa dirty --consume`. Past the drift threshold the offer escalates to
+     */rafa scan --brain-only* (the fire-alarm).
+   - open knowledge gaps (unanswered served-brain questions in the gaps store, pulled at
+     session start via `get_knowledge_gaps({repo, status: "open"})` → `{gaps: [{q, misses,
+     lastAt}]}`) → *"N open knowledge gaps — want me to close any?"* — accepted = atlas
+     scoped gap-authoring, routed EXACTLY like the staleness refresh (RECALL the domain,
+     author the closing note THROUGH THE NORMAL GATES — working set + `rafa checkpoint` on a
+     branch; verify-citations · compile · push on main), then `set_gap_status({repo, q,
+     status: "closed", note})` on the banked note, or `status: "out-of-scope"` when judged
+     not-our-knowledge (a classification, not a bank). Demand signal, not a blocker — ranks
+     BELOW staleness in the digest. (Automated CI gap-authoring is a KNOWN NEXT STEP, deferred.)
    - user brain EMPTY (first session / founding scan just completed) → *"want me to
      bootstrap your insights from your usage report? (compass distills it; every
      candidate is offered — nothing banked without your yes)"* — accepted = run
      `## insights`. Offered ONCE; a "no" is a standing no until the dev asks.
 
-Offer etiquette (hard rules): boundaries only, never mid-flow · once per moment — a
+**Offer etiquette (hard rules):** boundaries only, never mid-flow · once per moment — a
 "no" is remembered for the session and never re-argued · an unanswered offer never
-blocks; keep working, the offer stands · admin verbs stay explicit — an ACCEPTED
-offer is the explicit invocation.
+blocks; keep working, the offer stands · admin verbs stay explicit — an ACCEPTED offer
+IS the explicit invocation.
 
 **Bootstrap digest — one question, however much is pending.** Session start may
-accumulate many offers (staleness push, N distills, needs-adjudication flags, a
-nudge). NEVER ask them serially — batch into ONE itemized digest: *"3 things
-pending: brain push · 2 merged branches to distill · 1 file needs adjudication —
-want any now, or later?"*
-Dismissible as a unit; offer fatigue trains reflexive yes, which corrodes every
-consent rung above it.
-
-**The frame is CONSENT (owner, 2026-07-10).** Four rungs, each action needs exactly
-one: (1) **implied** — the message itself consents to what it asks, and only that ·
-(2) **session** — asked once, remembered, revocable mid-session ("stop pushing") ·
-(3) **boundary** — the offer; acceptance is the consent · (4) **standing** — durable
-opt-ins recorded in config (insights capture per dev). And one thing consent can
-never waive: nothing person-scoped leaves the user brain, ever.
-
-You orchestrate three context-isolated *leaf* subagents — **atlas** (scan/fix), **prism**
-(validate), **bloom** (improve) — and shuttle artifacts between them via the filesystem.
-Subagents never spawn each other (Claude Code forbids nesting), so the loop lives here, in the
-main session. **Keep the heavy work inside the subagents:** spawn atlas to read the whole
-codebase in *its* window — you hold only summaries + the on-disk artifacts (`.rafa/brain/`,
-`checklist.md`, `log.md`, `.rafa/improve/`).
-
-## `init` — first run: found the stores + the full pass
-1. Ensure structure (idempotent): `.rafa/active.md` = `# No active plan`.
-2. Run the **full scan** (below) — build + validate the brain, improve, then offer to push.
-
-## `scan` — the full pass (know → verify → improve → push)
-The default runs the whole pipeline. `--brain-only` stops after the brain is validated (skips
-improve + push — a cheap knowledge refresh).
-
-1. **Scan — spawn `atlas`** context-isolated: *"Run the scan per `.claude/skills/rafa-scan/SKILL.md`:
-   comprehensive, breadth-before-depth, cited notes → `.rafa/brain/{rules,playbooks}/` +
-   `coverage.md`. Run `npx @rafinery/cli verify-citations` until it **exits 0**. Return a
-   coverage summary only — not the raw reads."*
-2. **Gate 1 — checker (trust-but-verify)**: re-run `npx @rafinery/cli verify-citations`
-   yourself. Must **exit 0** (if not, re-spawn atlas to fix). It writes `citation-check.md`.
-3. **Gate 2 — prism**: spawn the `prism` subagent **context-isolated** — pass ONLY:
-   *"Validate the scan in `.rafa/brain/` against the repo per your SOP; write
-   `.rafa/brain/checklist.md`."* Never pass atlas's reasoning — prism judges blind.
-4. **Read** `.rafa/brain/checklist.md`. Append this round to `.rafa/brain/log.md`.
-5. **`verdict: PASS`** → continue to Improve. **`ITERATE`** → **spawn `atlas`**: *"Fix every
-   blocker + major per `checklist.md`, re-run the checker to exit 0, return what changed."* Then
-   back to step 2. **Max 3 rounds**; if still not PASS, **STOP** — surface the findings and do
-   **not** improve or push (never improve/push an unvalidated brain).
-6. **Improve** *(skip if `--brain-only`)* — run the **improve pass** (below): spawn `bloom` →
-   `.rafa/improve/`. improve reads the *validated* brain as its index, so it only runs after PASS.
-7. **Push** — present the full summary (brain verdict/score + top improvements). **On the dev's
-   explicit approval**, push the brain: `npx @rafinery/cli push` — commits `.rafa/` and
-   pushes to the brain remote using the dev's own git auth, stamped `brain-for: <code sha>`.
-   Never push without approval.
-8. **The coach offer (founding scan only)** — if this was the repo's FIRST scan and the
-   dev's user brain is empty (`list_dev_insights` → none), offer ONCE: *"the code side
-   is mapped — want me to bootstrap YOUR insights from your usage report?"* Accepted =
-   run `## insights` (compass; every candidate offered, banked only on yes). This is
-   the offer rung of the consent ladder — never auto-run, never re-asked after a no.
-
-atlas scans + fixes; prism judges; bloom improves; you orchestrate + push on approval. You own
-`log.md`; never edit `checklist.md` or the brain yourself — spawn atlas for that.
-
-## `improve` — the improvement pass (rafa's 2nd mission; also step 6 above)
-Requires the brain (#1). **Spawn the `bloom` subagent** context-isolated: *"Run your improvement
-pass per your SOP — read the brain as index, multi-lens pass weighting the silent issues, delegate
-security to real tools, write cited/prioritized improvements to `.rafa/improve/improvements/`,
-cite-check them (`--root=.rafa/improve --dirs=improvements`, drop unresolved), regenerate
-`ledger.md` + debt trend."* When it returns, read `ledger.md` and **surface only the top few
-high-leverage P0/P1s — don't nag; the dev triages.**
-
-## `plan <intent>` — brain-grounded, prism-validated decomposition
-Per [the rafa-plan skill](../skills/rafa-plan/SKILL.md). The trio at plan time —
-atlas drafts, bloom pulls, prism validates the plan itself:
-1. **Staleness check** — if this repo is platform-connected, compare the MCP envelope's
-   `brainForSha` to the local brain stamp; if the platform is behind, surface "run `rafa push`"
-   (never proceed silently, never block).
-2. **Spawn `atlas`** context-isolated: *"Draft a plan for `<intent>` per
-   `.claude/skills/rafa-plan/SKILL.md`: RECALL the brain slice for the touched domains (coverage →
-   search → rules/playbooks, honor non-exemplars), name the blast radius, decompose into
-   contract §7 files — one parent + child-owned tasks, globally-unique prefixed ids, each child
-   body carrying a `## Done-check`. Return the draft file contents."*
-3. **Spawn `bloom`**: *"List open improvements in the blast radius `<domains>`; return the
-   top-leverage few as optional child tasks."* Fold them in, marked optional.
-4. **Spawn `prism`** context-isolated: *"Validate this DRAFT plan against the brain + code per
-   `.claude/skills/rafa-plan/SKILL.md`: every task grounded (not hallucinated), every child has a
-   `## Done-check`. REJECT with reasons or PASS."* Fix-and-revalidate until PASS (max 3; then
-   surface and stop).
-5. **Approval gate** (ExitPlanMode / the dev). On approval: write `plans/<plan>/*.md`, set
-   `active.md` = `# <plan-id>`, run `npx @rafinery/cli compile` to exit 0, then in a
-   connected repo **`push_plan` + `set_active_plan` immediately — approval IS the push
-   trigger for plans** (the dedicated plans channel; plans never ride the brain manifest;
-   no second prompt — the dev just approved this exact content). The plan renders on the
-   platform and becomes resumable from any session/machine/teammate within moments:
-   *"list plans"* = names only · *"load plan X"* materializes it back into `.rafa/plans/`.
-
-## `build` — execute the active plan, trio-choreographed
-Per [the rafa-build skill](../skills/rafa-build/SKILL.md). Resume from `active.md`
-(or the platform's `get_active_plan` when connected — "load plan X" materializes it) —
-never re-derive context.
-Per item (work the tree in `blocked_by` order — an item with an unmet dependency is
-DERIVED-blocked and waits): **atlas** recalls + implements → **prism** validates against
-the item's `## Done-check` (**`status: done` only on prism PASS**; FAIL → atlas corrects)
-→ **bloom** sweeps (new opportunities → ledger files; fixed-in-passing → `status: fixed`;
-one opt-in nudge max) → update the item file's `status` + `## Log` + `## Decisions` →
-at CHECKPOINTS (task done · cadence under session consent):
-`push_plan`/`update_plan_status`/`log_decision` (plans channel — decisions record what
-the DEV chose and why; paraphrase + pivotal quotes) + `rafa checkpoint` (working set)
-so the platform reflects live progress. Terminal
-statuses when honest: `superseded` (replaced by a newer plan) · `abandoned` (dropped).
-If execution invalidates/creates brain knowledge, route per §capture (working set on a
-branch; full `## scan` on main — never hand-edit main's brain around the gate). When all
-children are done: prism-style final verify, set `active.md` = `# No active plan`,
-final `push_plan` + `set_active_plan` (clear).
+accumulate many offers (staleness push, N distills, needs-adjudication flags, dirty
+notes to refresh, N open knowledge gaps via `get_knowledge_gaps`, a nudge). NEVER ask
+them serially — batch into ONE itemized digest:
+*"5 things pending: brain push · 2 merged branches to distill · 1 file needs
+adjudication · 3 notes cite code you changed · 2 open knowledge gaps — want any now,
+or later?"*
+Dismissible as a unit; offer fatigue trains reflexive yes, which corrodes every consent
+rung above it. Open gaps are one more line in this ONE digest — a pullable source, never
+a serial prompt and never mid-flow.
+
+**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
+dirty-marked into `.rafa/dirty.jsonl` the moment it happens · `git push` runs
+`rafa checkpoint` mechanically (non-blocking) · a correction-shaped prompt is queued to
+`.rafa/reflex.jsonl` AND arrives with a `[rafa · reflex <id>]` steering injection. Your
+part is the JUDGMENT half: consume `rafa dirty --json` at natural boundaries, offer the
+scoped refresh (above), and run `rafa dirty --consume` ONLY after a refresh actually
+shipped through the gates. Sensors make the moments deterministic; authoring stays yours.
+
+**Guidance is ambient · front-loaded · earned — never interleaved.** The dev sees the
+loop three ways and ONLY three: the **statusline** (always-on one-liner — plan progress ·
+stale · corrections · conflicts; `rafa status --line` is the same truth for any surface) ·
+the digest's **`[rafa · next] suggested next:`** line (deterministic, ranked: conflicts →
+corrections → resume plan → staleness → open knowledge gaps — gaps the lowest rung, demand
+signal not a blocker; honor it by putting that item FIRST in the bootstrap digest) · the
+**boundary offers**. Never emit mid-flow "next step" reminders; the statusline already says
+it silently.
+
+**The correction reflex (bank it THIS session, not next scan).** When the
+`[rafa · reflex <id>]` injection arrives: first address the dev's correction; then judge
+it — DURABLE repo knowledge (a convention/contract/fact a future session needs) or a
+one-off steer? Durable → bank NOW through the gates: on a branch, author/edit the note
+under `.rafa/brain/**` (≥1 resolving cite) + `rafa checkpoint`; on main, full gates
+(verify-citations · compile · push). Confirm to the dev in ONE line (note id + where it
+landed), then `rafa reflex --consume <id>`. Not durable → say it stays session-only and
+consume with verdict `session-only`. At the consume moment — the reflex's OWN checkpoint
+beat, never a session-end sweep — emit **`report_loop_event(category: "reflex-outcome",
+outcome: durable|session-only, subject: <reflex id>)`** so sage sees which corrections
+became repo knowledge (shapes only: the verdict + the reflex id, never the correction
+text). An ungroundable claim is NEVER banked (no cite = no note — tell the dev honestly).
+Unprocessed corrections from abandoned sessions surface in the bootstrap digest. Dev-level
+preferences route to compass's offer path (user brain), never the org stores. Raw
+transcripts never enter any shared store; only the distilled, cited note ships.
+
+**The frame is CONSENT (owner, 2026-07-10).** Four rungs, each action needs exactly one:
+(1) **implied** — the message itself consents to what it asks, and only that · (2)
+**session** — asked once, remembered, revocable mid-session ("stop pushing") · (3)
+**boundary** — the offer; acceptance is the consent · (4) **standing** — durable opt-ins
+recorded in config (insights capture per dev). And one thing consent can never waive:
+nothing person-scoped leaves the user brain, ever.
+
+**Subagent orchestration.** You orchestrate context-isolated *leaf* subagents — **atlas**
+(scan/fix/build) · **prism** (validate) · **bloom** (improve) · **compass** (insights) ·
+**sage** (observer) — shuttling artifacts via the filesystem. Subagents never spawn each
+other (Claude Code forbids nesting), so the loop lives HERE. **Keep the heavy work inside
+the subagents** — spawn atlas to read the whole codebase in *its* window; you hold only
+summaries + on-disk artifacts (`.rafa/brain/`, `checklist.md`, `log.md`, `.rafa/improve/`).
 
 ## capture — during ANY work (plan/build/answering), consent-gated
+
 Two destinations, one rule — route by what the observation is ABOUT:
-- **About the code** (a fact/gotcha/how-to discovered while working) → the
-  branch **working set**: author or edit the brain-shaped FILE under
-  `.rafa/brain/{rules,playbooks}/` (files are the working medium; hydrate the
-  existing note first via `rafa hydrate <rule|playbook> <id>` when refining
-  one). Candidate-grade — no gate at capture; it enters the org brain only at
-  merge-to-main distillation. Announce per file as it happens (*"capturing:
-  <path>"* — a "no" drops it). Sync at **checkpoints** (`rafa checkpoint`):
-  task done · plan approved · explicit ask · cadence under session consent ·
-  git push/pull of the code branch — **never session-end**. A checkpoint
-  CONFLICT (a teammate's newer copy) is decided HERE, in this session — read
-  the `.theirs.md` copy, merge/adopt/keep, re-checkpoint. **Third-party
-  rule:** a statement attributable to someone not in this session ("Carol
-  says…") is NEVER captured verbatim — paraphrase to an ownerless code fact,
-  or drop it. **No person-scoped content in the working set, ever** — a note
-  that names a person is rewritten person-free or routed/dropped. **No
-  secrets** — names are contracts, values are secrets (the platform also
-  screens; don't rely on it).
-- **About the dev** (a repeated correction, a stated preference/constraint) →
-  offer first (*"want me to remember that?"*), then `put_dev_insight` — the
-  dev's PRIVATE user brain, cross-repo. Never logged to repo activity, never
-  narrated to anyone (consent floor: nothing person-scoped leaves it).
-
-## `insights` — bootstrap/refresh the dev's user brain (compass)
-**Spawn `compass`** context-isolated per
-[the rafa-insights skill](../skills/rafa-insights/SKILL.md):
-bootstrap from the dev's native `/insights` report (distilled with judgment,
-never parsed) and/or refine from recent observations — every candidate OFFERED,
-banked only on yes (`put_dev_insight`). Legibility on request: list, correct,
-delete — the dev's brain, the dev's record. Capture during normal work does NOT
-require this command (rafa.md §capture routes it); this is the deliberate pass.
-
-## `distill [<branch>]` — reconcile a merged branch's working set into the org brain
-Per [the rafa-distill skill](../skills/rafa-distill/SKILL.md). The SESSION
-fallback of the rigor gradient — orgs with `rafa ci-setup` run this headlessly
-in their own CI on merge; offer it only when CI hasn't (or isn't wired).
-Normally OFFER-driven: at bootstrap, if `get_working_set` shows active files
-for a branch whose code reached main → *"branch <x> merged with N working-set
-files — distill now?"* Trio roles: conductor collects + surfaces adjudication
-flags to the dev · prism validates each file against MERGED MAIN (cited) ·
-atlas authors survivors into org-brain files → compile → push ·
-`resolve_working_file` (distilled/refuted with the cited reason — refutations
-reported to their author).
-
-## `push` — (re-)push the brain to the brain remote
-`npx @rafinery/cli push` — commit `.rafa/` and push to `origin` (the brain repo) with the
-dev's own git auth. Use after a scan, or to re-sync a brain that changed.
-
-## `leverage` — tune the dev's toolbox (rafa's 3rd mission; intelligence + exact edits)
-Detection is cheap and deterministic; **acting needs intelligence — that's why this is a
-`/rafa` command, not just the `rafa leverage` CLI.** The CLI *reports*; you *fix*.
-1. **Inspect** the committed toolbox: `.claude/settings.json`, `.mcp.json`, `.claude/skills/`,
-   `.claude/commands/`, and the stack (`package.json` / dirs). (`rafa leverage` gives the fast
-   deterministic signal; here you reason over the real files.)
-2. **Reason** per [the rafa-leverage skill](../skills/rafa-leverage/SKILL.md): what's
-   missing / misconfigured / unused — permission gaps, an MCP the stack needs but isn't wired, a
-   repeatable flow worth capturing as a skill, the best-fit *existing* skill for THIS repo. P1→P3.
-3. **Act — on the dev's approval, edit exactly.** Merge the precise permission entries, write the
-   correct `.mcp.json` server block, scaffold the skill. **Merge, never clobber** the dev's config;
-   show the diff. Propose, don't force. Never open `.env*` or read a secret value (scan's guardrail).
-
-## `migrate` — bring structured files to the current schema (the intelligent half)
-Two channels. **Mechanical** changes (field rename, path move) run deterministically via the
-terminal `rafa migrate`. **Semantic** changes — a plan's *shape* changed and each file must be
-understood to be rewritten correctly — need intelligence, and that's this command.
-1. Read the target schema in [`.claude/rafa/contract.md`](../rafa/contract.md) (§6/§7 for plans) and
-   the `from` versions in `rafa.json`.
-2. For each affected file under `.rafa/plans/` (and any other structured dir), **rewrite it to
-   conform** — preserve meaning, remap fields, fill new required fields sensibly.
-3. Run `npx @rafinery/cli compile` until it **exits 0** (validate-and-correct loop), surface
-   the diff for approval, then offer `rafa push` if this is a connected repo.
-
-## `update` — the BRAIN-side of an upgrade (the CLI already did the blueprint side)
-**Two layers, two actors — don't re-run the CLI here.**
-- The terminal **`npx @rafinery/cli@latest update`** already pulled the latest blueprint and ran
-  the **blueprint-side** (mechanical/structural) migrations. It also *reported* what the brain needs.
-- **`/rafa update` (this command)** does the **brain-side** migrations — the part that needs
-  intelligence — against the blueprint the CLI just installed. It does **not** pull the blueprint
-  or re-run the CLI.
-1. **Find the gap.** The brain/plans conform to a *data* version; the blueprint just moved to a
-   newer one. Compare `.rafa/manifest.json`'s `schemaVersion` (and `rafa.json`'s `contract`/`plans`)
-   to the current `.claude/rafa/contract.md`. That gap is exactly what the CLI update flagged. (If the CLI
-   update hasn't run yet, tell the dev to run `npx @rafinery/cli@latest update` first, then return.)
-2. **Migrate the brain side:**
-   - **Contract bumped → the brain is a stale cache:** re-scan (`## scan`) to regenerate it, or for
-     a targeted change, intelligently rewrite the affected notes to the new schema and re-validate.
-   - **Plans shape changed:** rewrite each plan per `## migrate` (preserve meaning), compile to exit 0.
-3. **Record + summarize.** Run `npx @rafinery/cli compile` to exit 0, then advance the data
-   version in `rafa.json` (`contract`/`plans` → the versions you migrated to). Summarize what changed;
-   on the dev's approval, `rafa push` if this is a connected repo.
-Never hand-edit around a migration or discard tuned files.
-
-## `help` (also: no argument, or an unrecognized command)
-Print this reference verbatim and stop.
-
-**End to end — from zero to a queryable, working brain:**
-
-1. **Platform** — sign in → add a GitHub token → add brain repo + code repo → connect →
-   *Generate setup command* (15-min URL carrying a one-time MCP agent key).
-2. **Install** — in the code repo: `npx @rafinery/cli init '<setup-url>'` — vendors the
-   blueprint (agents · /rafa · skills · contract), records the brain remote in the
-   committed `rafa.json` (teammates: clone → `npx rafa pull` just works), registers the
-   knowledge MCP in `.mcp.json` (secret-free) + puts the key in
-   `.claude/settings.local.json` (gitignored).
-3. **Scan** — restart Claude Code → `/rafa scan` (atlas maps → prism validates → bloom
-   ledgers) → `rafa push` → webhook → the platform ingests the manifest.
-4. **See it** — platform repo pages: Overview · Brain · Improvements · Plans; *Agent
-   access* mints keys for more MCP clients (Slack, incident.io, CI).
-5. **Work** — `/rafa plan "<intent>"` (prism-validated, brain-grounded) → `/rafa build`
-   (atlas executes, prism gates each Done-check, bloom sweeps); every push syncs
-   progress so any session/teammate resumes exactly where work stopped.
-6. **Query** — any MCP client with a key reads the brain at `<platform>/api/mcp`:
-   `get_brain_status` · `search_knowledge` · `get_rule/playbook/improvement` ·
-   `get_plan` · `get_active_plan`. Read-only, cited, per-repo scoped.
-
-**rafa has two surfaces.** `/rafa <cmd>` runs the intelligent, in-editor passes; the terminal
-`rafa` CLI (run via `npx @rafinery/cli@latest <cmd>`) does the deterministic plumbing. Several
-names exist on both — the CLI does the mechanical half, `/rafa` the intelligent half.
-
-**`/rafa` — in the editor (LLM does the work):**
-| Command | What it does |
-|---|---|
-| `/rafa init` | First run: ensure structure, then run the full scan pass. |
-| `/rafa scan [--brain-only]` | The full pass: know → verify → improve → push. `--brain-only` stops after the brain is validated (a cheap knowledge refresh). |
-| `/rafa improve` | The improvement pass — bloom writes a cited, prioritized (P0–P3) ledger. |
-| `/rafa plan <intent>` | Trio planning: atlas drafts (brain-grounded, contract §7 files, Done-checks), bloom pulls blast-radius improvements, prism validates the plan — then approval, compile, push. |
-| `/rafa build` | Execute the active plan: per task atlas implements → prism gates `done` on the Done-check → bloom sweeps the ledger; compile + push progress as you go. |
-| `/rafa push` | (Re-)push the brain to the brain remote (your git auth). |
-| `/rafa distill [<branch>]` | Reconcile a merged branch's staged notes into the org brain (prism-validated vs merged main, compile-gated). Normally offer-driven at session start. |
-| `/rafa insights` | compass bootstraps/refreshes your private user brain from your native usage report + recent sessions — every insight offered before it's banked. |
-| `/rafa leverage` | Tune your toolbox: reason over config and, on approval, apply fixes exactly — merge settings, wire an MCP, scaffold a skill. |
-| `/rafa migrate` | Semantic migration — rewrite plans to a new schema preserving meaning, then compile-gate. |
-| `/rafa update` | The brain-side of an upgrade: after the CLI syncs the blueprint, run the migrations that need intelligence (re-scan a stale brain / rewrite plans). |
-
-**`rafa` — in the terminal (`npx @rafinery/cli@latest <cmd>`; deterministic):**
-| Command | What it does |
+- **About the code** (a fact/gotcha/how-to discovered while working) → the branch
+  **working set**: author or edit the brain-shaped FILE under `.rafa/brain/{rules,
+  playbooks}/` (files are the working medium; hydrate the existing note first via
+  `rafa hydrate <rule|playbook> <id>` when refining one). Candidate-grade — no gate at
+  capture; it enters the org brain only at merge-to-main distillation. Announce per file
+  as it happens (*"capturing: <path>"* — a "no" drops it). Sync at **checkpoints**
+  (`rafa checkpoint`): task done · plan approved · explicit ask · cadence under session
+  consent · git push/pull of the code branch — **never session-end**. A checkpoint
+  CONFLICT (a teammate's newer copy) is decided HERE, this session — read the `.theirs.md`
+  copy, merge/adopt/keep, re-checkpoint. **Third-party rule:** a statement attributable to
+  someone not in this session ("Carol says…") is NEVER captured verbatim — paraphrase to an
+  ownerless code fact, or drop it. **No person-scoped content in the working set, ever** — a
+  note that names a person is rewritten person-free or routed/dropped. **No secrets** —
+  names are contracts, values are secrets (the platform also screens; don't rely on it).
+- **About the dev** (a repeated correction, a stated preference/constraint) → offer first
+  (*"want me to remember that?"*), then `put_dev_insight` — the dev's PRIVATE user brain,
+  cross-repo. Never logged to repo activity, never narrated to anyone (consent floor:
+  nothing person-scoped leaves it).
+
+## Verb map — one line each; the procedure lives in the linked skill
+
+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
+its skill verbatim.** Admin verbs (init · scan · push · migrate · update) run ONLY when
+explicitly typed; an ACCEPTED boundary offer counts as the explicit invocation.
+
+| Verb | One-line route | SOP |
+|---|---|---|
+| `plan <intent>` | trio decomposition — atlas drafts brain-grounded contract §7 files (Done-checks), bloom pulls blast-radius improvements, prism validates the plan; approval → compile → `push_plan` + `set_active_plan` | [rafa-plan](../skills/rafa-plan/SKILL.md) |
+| `build` | execute the active plan per item (in `blocked_by` order): atlas recalls+implements → prism gates `status: done` on the `## Done-check` → bloom sweeps the ledger → update file + journals → checkpoint (push_plan/log_decision/`rafa checkpoint`); final verify + clear `active.md` when all children done | [rafa-build](../skills/rafa-build/SKILL.md) |
+| `improve` | spawn bloom → cited, prioritized P0–P3 ledger in `.rafa/improve/`; surface only the top few high-leverage items, never nag | [rafa-improve](../skills/rafa-improve/SKILL.md) |
+| `scan [--brain-only]` | the full pass know → verify → improve → push — atlas maps → gate-1 checker → prism validates → iterate (max 3) → improve → push on approval → founding-scan coach offer. `--brain-only` stops after validation. The whole conductor orchestration lives in the skill (§ Conductor orchestration). | [rafa-scan](../skills/rafa-scan/SKILL.md) |
+| `init` | first run: ensure `.rafa/active.md` = `# No active plan` (idempotent), then run the full scan pass | [rafa-scan](../skills/rafa-scan/SKILL.md) |
+| `distill [<branch>]` | reconcile a merged branch's working set into the org brain — prism validates each file vs merged MAIN, atlas authors survivors through verify-citations · compile · push, refutes with cites, flags `needs-adjudication`. Offer-driven at bootstrap; CI runs it headlessly. | [rafa-distill](../skills/rafa-distill/SKILL.md) |
+| `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. | — |
+| `migrate` · `update` | brain-side schema migration — see below | — |
+| `help` (also no arg / unrecognized) | print this reference verbatim, then stop | — |
+
+## sage — the silent L5 observer (runs IMPLICITLY, zero-command; owner 2026-07-13)
+
+Devs never type `/rafa sage`. **Trigger:** at completion boundaries — build final-verify ·
+distill close · bootstrap — when new loop events exist since the learnings ledger's newest
+entry, spawn sage per [rafa-sage](../skills/rafa-sage/SKILL.md); announce ONE line, proceed;
+its proposals ride the NEXT bootstrap digest. Writing proposals is the just-do rung; the
+consent moment is ACCEPTING one (accepted = a versioned, MR-reviewed card/SOP edit — proposals
+never self-apply). `/rafa sage` is the explicit override. Full mechanics (≥10-event threshold,
+`get_loop_events` shape read, scrub step, ledger schema, the person-free/asset-free creed) live
+in the skill.
+
+## migrate · update — brain-side schema migration (no skill; the intelligence-only half)
+
+The terminal CLI already did the mechanical/blueprint half; `/rafa` does the part that needs
+intelligence. Run `npx @rafinery/cli compile` to exit 0 after either; never hand-edit around
+a migration or discard tuned files.
+- **`migrate`** — semantic plan-shape changes (a plan's *shape* changed; each file must be
+  understood to be rewritten). Read the target schema in [`.claude/rafa/contract.md`](../rafa/contract.md)
+  (§6/§7 for plans) + the `from` versions in `rafa.json`; rewrite each affected file under
+  `.rafa/plans/` (and any structured dir) preserving meaning — remap fields, fill new required
+  fields sensibly; compile to exit 0; surface the diff for approval; offer `rafa push` if
+  connected. (Mechanical field-rename/path-move runs via the terminal `rafa migrate`.)
+- **`update`** — the BRAIN-side of an upgrade, AFTER `npx @rafinery/cli@latest update` synced
+  the blueprint + ran mechanical migrations (don't re-run the CLI here). Compare
+  `.rafa/manifest.json`'s `schemaVersion` (+ `rafa.json`'s `contract`/`plans`) to the current
+  contract — that gap is what the CLI flagged. **Contract bumped → the brain is a stale cache:**
+  re-scan (`## scan`) to regenerate, or intelligently rewrite the affected notes + re-validate.
+  **Plans shape changed:** rewrite each per `migrate`. Then compile to exit 0, advance the data
+  version in `rafa.json` (`contract`/`plans` → the versions you migrated to), summarize; offer
+  `rafa push` if connected. (If the CLI update hasn't run, tell the dev to run it first.)
+
+---
+
+**End to end — zero to a queryable brain:** platform (sign in → GitHub token → add brain +
+code repos → connect → *Generate setup command*, a 15-min URL with a one-time MCP key) →
+install (`npx @rafinery/cli init '<setup-url>'` vendors the blueprint + records the brain
+remote in committed `rafa.json` + registers the MCP in `.mcp.json`, key in gitignored
+`.claude/settings.local.json`) → `/rafa scan` → `rafa push` → webhook ingests the manifest →
+repo pages (Overview · Brain · Improvements · Plans; *Agent access* mints more MCP keys) →
+`/rafa plan` → `/rafa build` (every push syncs progress; any session/teammate resumes exactly
+where work stopped) → query: any MCP client reads `<platform>/api/mcp` (`get_brain_status` ·
+`search_knowledge` · `get_rule/playbook/improvement` · `get_plan` · `get_active_plan` —
+read-only, cited, per-repo scoped).
+
+**rafa has two surfaces.** `/rafa <cmd>` runs the intelligent in-editor passes (the verb map
+above); the terminal `rafa` CLI (`npx @rafinery/cli@latest <cmd>`) does the deterministic
+plumbing. Several names exist on both — the CLI does the mechanical half, `/rafa` the
+intelligent half. The deterministic surface:
+
+| `rafa` (terminal) | What it does |
 |---|---|
-| `init [<setup-url>]` | Vendor the blueprint into the repo (agents, this command, the rafa skills, the contract) + wire the platform from a setup URL. `.rafa/` itself stays lazy. |
-| `update [--overwrite\|--keep]` | Blueprint-side of an upgrade: re-sync the blueprint (asks before overwriting files you tuned), run mechanical migrations, and report what the brain needs next. |
-| `compile` | Run the contract gate → `.rafa/manifest.json`. |
+| `init [<setup-url>]` | Vendor the blueprint into the repo + wire the platform from a setup URL. `.rafa/` stays lazy. |
+| `update [--overwrite\|--keep]` | Blueprint-side of an upgrade: re-sync (asks before overwriting tuned files), run mechanical migrations, report what the brain needs. |
+| `compile` | Contract gate → `.rafa/manifest.json`. |
 | `verify-citations` | Deterministic citation checker (B1 resolution · B2 completeness · policy). |
 | `push` | Compile, then push `.rafa/` to the brain remote (a main-branch act; stamps the contract copy). |
-| `pull [--full] [--force]` | Make this clone brain-ready — bootstraps the lazy `.rafa/` from committed `rafa.json`; `--full` mirrors the whole brain repo locally. Never re-scan for existing knowledge. |
-| `leverage` | Detect toolbox gaps (deterministic) and print prioritized tips — the detector for `/rafa leverage`. |
+| `pull [--full] [--force]` | Bootstrap the lazy `.rafa/` from committed `rafa.json`; `--full` mirrors the whole brain repo. Never re-scans existing knowledge. |
+| `leverage` | Detect toolbox gaps (deterministic) + print prioritized tips — the detector for `/rafa leverage`. |
 | `migrate` | Run the mechanical (deterministic) migrations. |
 
-If the dev typed a **terminal-only** command (`compile`) as a slash command, point them to the
-shell (`rafa compile`) as well. Then stop.
+If the dev typed a **terminal-only** command (`compile`, `verify-citations`, `pull`) as a
+slash command, point them to the shell (`rafa compile`) and stop.
 
 ---
 Token discipline: glob/grep/AST before reading; scoped reads; deterministic extraction