@rafinery/cli 0.3.0 → 0.4.1

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

@@ -1,10 +1,75 @@
 ---
-description: rafa — init · scan · improve · plan · build · push · leverage · migrate · update · help. Usage: /rafa <init|scan|improve|plan|build|push|leverage|migrate|update|help> [--brain-only]
+version: 1.3.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`
 
+## Intent routing — implicit by default, explicit as override
+
+Work verbs dispatch on **prompt intent**; the dev never needs to remember a command.
+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) |
+| 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. |
+| "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 |
+
+**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.
+
+**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.
+
+## Offers — ask at the boundary, never nag
+
+Three interaction modes by the weight of the action:
+1. **Just do** (session-local, reversible): recall · drafting · local journaling ·
+   status updates. Announce-and-proceed.
+2. **Ask once per session, then remember**: recurring cadences — *"keep plans
+   updated + pushed as I work (progress, notes, staged insights)?"* at build start.
+   One answer covers the session.
+3. **Offer at the boundary** (creates a durable artifact, leaves the machine, or
+   spends real money): a short, well-timed question at a NATURAL boundary —
+   - intent is getting big mid-conversation → *"want me to turn this into a plan?"*
+   - work/task complete → *"push the brain so the platform (and your team) see it?"*
+   - plan drafted but the dev drifted → *"push this plan to the platform?"*
+   - 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?"*
+
+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.
+
+**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
@@ -20,11 +85,11 @@ codebase in *its* window — you hold only summaries + the on-disk artifacts (`.
 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 `.rafa/capabilities/scan.md`:
+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 `node .rafa/bin/verify-citations.mjs` until it **exits 0**. Return a
+   `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 `node .rafa/bin/verify-citations.mjs`
+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
@@ -37,7 +102,7 @@ improve + push — a cheap knowledge refresh).
 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: `node .rafa/bin/rafa-push.mjs` — commits `.rafa/` and
+   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.
 
@@ -53,39 +118,93 @@ cite-check them (`--root=.rafa/improve --dirs=improvements`, drop unresolved), r
 high-leverage P0/P1s — don't nag; the dev triages.**
 
 ## `plan <intent>` — brain-grounded, prism-validated decomposition
-Per [`.rafa/capabilities/plan.md`](../../.rafa/capabilities/plan.md). The trio at plan time —
+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
-   `.rafa/capabilities/plan.md`: RECALL the brain slice for the touched domains (coverage →
+   `.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
-   `.rafa/capabilities/plan.md`: every task grounded (not hallucinated), every child has a
+   `.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 `node .rafa/bin/rafa-compile.mjs` to exit 0, offer
-   `rafa push` (the plan becomes resumable from any session/machine via the platform).
+   `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 [`.rafa/capabilities/build.md`](../../.rafa/capabilities/build.md). Resume from `active.md`
-(or the platform's `get_active_plan` when connected) — never re-derive context.
+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 task: **atlas** recalls + implements → **prism** validates against the child'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 child file's `status` → periodically compile + push so the platform
-reflects live progress. If execution invalidates/creates brain knowledge, run a **full
-`## scan`** (v1 rule — never hand-edit brain files around the gate). When all children are
-done: prism-style final verify, set `active.md` = `# No active plan`, compile + push.
+nudge max) → update the child file's `status` + `## Log` → at CHECKPOINTS (task done ·
+cadence under session consent): `push_plan`/`update_plan_status` (plans channel) +
+`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).
+
+## 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
-`node .rafa/bin/rafa-push.mjs` — commit `.rafa/` and push to `origin` (the brain repo) with the
+`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)
@@ -94,7 +213,7 @@ Detection is cheap and deterministic; **acting needs intelligence — that's why
 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 [`.rafa/capabilities/leverage.md`](../../.rafa/capabilities/leverage.md): what's
+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
@@ -105,11 +224,11 @@ Detection is cheap and deterministic; **acting needs intelligence — that's why
 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 [`.rafa/contract.md`](../../.rafa/contract.md) (§6/§7 for plans) and
+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 `node .rafa/bin/rafa-compile.mjs` until it **exits 0** (validate-and-correct loop), surface
+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)
@@ -121,13 +240,13 @@ understood to be rewritten correctly — need intelligence, and that's this comm
   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 `.rafa/contract.md`. That gap is exactly what the CLI update flagged. (If the CLI
+   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 `node .rafa/bin/rafa-compile.mjs` to exit 0, then advance the data
+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.
@@ -140,8 +259,10 @@ Print this reference verbatim and stop.
 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, wires the brain remote, registers the knowledge MCP in `.mcp.json`
-   (secret-free) + puts the key in `.claude/settings.local.json` (gitignored).
+   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
@@ -166,6 +287,8 @@ names exist on both — the CLI does the mechanical half, `/rafa` the intelligen
 | `/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). |
@@ -173,10 +296,12 @@ names exist on both — the CLI does the mechanical half, `/rafa` the intelligen
 **`rafa` — in the terminal (`npx @rafinery/cli@latest <cmd>`; deterministic):**
 | Command | What it does |
 |---|---|
-| `init [<setup-url>]` | Vendor the blueprint into the repo (+ wire the brain remote from a platform setup URL). |
+| `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`. |
-| `push` | Compile, then push `.rafa/` to the brain remote. |
+| `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`. |
 | `migrate` | Run the mechanical (deterministic) migrations. |
 

package/blueprint/{.rafa → .claude/rafa}/contract.md

@@ -6,6 +6,12 @@ prism) and the reader (the platform ingest). If a file violates this, the compil
 step **fails loudly** and the authoring agent must correct it — the platform never
 guesses, never assumes a value.
 
+**Canonical home: `.claude/rafa/contract.md` in the CODE repo** (blueprint split,
+0.4.0) — the contract versions with the CLI that implements it (`rafa compile` ships
+inside `@rafinery/cli`, never vendored). A **stamped copy** rides every brain push as
+`contract.md` in the brain repo, so any reader of the brain repo knows which contract
+version that brain conforms to.
+
 Pipeline:
 
 ```
@@ -39,9 +45,18 @@ doesn't validate, compile fails.
 | ledger | `improve/ledger.md` | **structured** | §5 | bloom |
 | plan | `plans/**/*.md` | **structured** | §7 | plan/build |
 | log | `brain/log.md` | **verbatim** | — (prose trail) | conductor |
-| citation-check | `**/citation-check.md` | **generated** | — (by `verify-citations`) | tool |
+| citation-check | `**/citation-check.md` | **generated** | — (by `rafa verify-citations`) | tool |
 | active pointer | `active.md` | **generated** | — (`# <plan-id>` or "No active plan"; compile emits it as `activePlanId`, §7) | conductor |
-| blueprint | `capabilities/*`, `bin/*`, `contract.md` | **verbatim** | — (shipped SOPs/tools) | rafa |
+| contract copy | `contract.md` | **generated** | — (stamped copy of `.claude/rafa/contract.md`, written by `rafa push`) | tool |
+| agent | `.claude/agents/*.md` (code repo) | **structured** (local gate — NOT in manifest) | §10 | rafa |
+
+The `agent` type is the one structured type outside `.rafa/`: the shipped agent cards
+in the code repo. Compile validates them (§10) so a malformed card fails the gate like
+any other contract violation, but they are never emitted into `manifest.json` — the
+platform doesn't ingest agents (yet); the gate exists so the agents themselves are
+never un-schema'd. The SOPs the cards point at are committed skills in the code repo
+(`.claude/skills/rafa-*/SKILL.md`); the gate tools are `@rafinery/cli` commands —
+neither lives under `.rafa/`, which holds purely knowledge + state.
 
 `structured` types are compiled into `manifest.json` (§1) — that JSON is the ONLY thing the
 platform ingests. `verbatim`/`generated` files are shown as-is in the file browser (fetched
@@ -77,9 +92,14 @@ key: { a: x, b: y }               # flow map of scalars
 key:                              # block list …
   - item
   - item
+key: >-                           # folded scalar: continuation lines joined with one space
+  first part
+  second part
 ```
 
-No nested block maps, no multiline scalars, no anchors. Deterministic to parse.
+No nested block maps, no anchors, no literal (`|`) blocks. The folded scalar (`>-`/`>`)
+is the ONLY multiline form, added for agent cards (§10) whose descriptions fold.
+Deterministic to parse: indented non-empty lines after `>-` join with a single space.
 
 ### cites DSL
 
@@ -155,25 +175,15 @@ JSON. This is the exact shape the platform binds to.
       "cites": [{ "file": "…", "line": "25", "token": "…" }],
       "path": "improve/improvements/dead-model-options-google-crewai.md"
     }
-  ],
-
-  "activePlanId": null,                     // from active.md: plan id, or null
-  "plans": [
-    {
-      "id": "multitenant",                  // == filename stem, globally unique
-      "plan": "multitenant",                // the parent plan id
-      "parent": null,                       // parent plan id, or null for the root
-      "kind": "parent",                     // "parent" | "child"
-      "title": "…",
-      "status": "in-progress",              // omitted when absent (parent may omit)
-      "branch": "feat/mt-c1",               // omitted when absent
-      "baseSha": "abc123",                  // omitted when absent
-      "path": "plans/multitenant/multitenant.md"   // prose body (lazy fetch)
-    }
   ]
 }
 ```
 
+**The manifest carries KNOWLEDGE only.** Plans and the active pointer left it
+(0.4.0 — the plans channel, §7): they are pushed on approval via `push_plan` /
+`set_active_plan` and never ride the brain repo. Legacy manifests carrying
+`plans[]`/`activePlanId` are tolerated and IGNORED by ingest (never written).
+
 Ingest is `JSON.parse` + a shape-check against this schema. Any mismatch (missing
 key, wrong enum, wrong type, unknown `schemaVersion`) → a **surfaced ingest error**
 on the platform, never a guessed value.
@@ -278,7 +288,7 @@ domains: { design-system: mapped, components: mapped, api: thin, external-integr
 
 ---
 
-## 7. Plan files — `plans/**/*.md`
+## 7. Plan files — `plans/**/*.md` (+ the plans channel)
 
 Each child owns exactly one file (so merges never conflict; parent progress is
 derived by counting).
@@ -291,7 +301,7 @@ plan: multitenant                # required · the parent plan id
 parent: multitenant              # required · parent plan id (child), or null (root)
 kind: parent | child             # required
 title: …                         # required
-status: todo | in-progress | done | blocked   # required (child); parent may omit
+status: todo | in-progress | done | blocked | superseded | abandoned   # required (child); parent may omit
 branch: feat/mt-c1               # optional · the branch this executes on
 baseSha: abc123                  # optional · commit it was cut from
 ---
@@ -312,10 +322,29 @@ Rules (all compile-enforced unless noted):
 - **Progress is never stored.** A `progress` key in plan frontmatter is a compile
   error. Parent progress is `count(children where status == done) / count(children)`
   — derived at read time, everywhere (compile, platform, MCP).
+- **Statuses.** `done` exists only on prism PASS (the execution gate). The two
+  TERMINAL statuses close work honestly without pretending `done`:
+  `superseded` (a newer plan replaces it) · `abandoned` (deliberately dropped).
+  `blocked` is waiting, not terminal. Statuses are set in sessions; the platform
+  board renders them read-only.
 - **`active.md` → `activePlanId`.** Compile reads the generated pointer: a first line
   `# <plan-id>` must resolve to a `kind: parent` plan (else compile error);
   `# No active plan` or a missing `active.md` → `activePlanId: null` (documented
   default — the pointer is generated, absence means "none", never a guess of one).
+  The PLATFORM pointer is set separately through `set_active_plan` (below).
+
+**Transport — the plans channel (0.4.0; plans never ride the brain manifest):**
+
+- **Authoring**: plans are drafted as the files above (compile-validated —
+  determinism holds; `.rafa/plans/` is the working copy).
+- **Push on approval**: the dev's approval IS the trigger — `push_plan` sends the
+  whole plan (parent + children + bodies) to the platform; `set_active_plan`
+  points the repo's active pointer at it. Build cadence re-pushes statuses +
+  `## Log` journals (`push_plan` upsert / `update_plan_status`).
+- **Pull-based work**: `list_plans` returns NAMES ONLY (id · title · status ·
+  progress); **"load plan X"** = `get_plan` (bodies included) materialized back
+  into `.rafa/plans/` by the session. Nothing plan-shaped is hydrated until
+  explicitly loaded.
 
 ---
 
@@ -366,8 +395,8 @@ match.
 | `search_knowledge` | `q`, `types?`, `domain?`, `limit?` | ranked candidates (fields per type below) |
 | `get_rule` / `get_playbook` / `get_improvement` | `repo`, `id` | full frontmatter + lazy-fetched body + cites as objects |
 | `list_improvements` | `repo`, `status?`, `priority?`, `domain?` | ledger rows |
-| `get_plan` | `repo`, `id` (parent or child) | parent + all children + **derived** progress; a child id resolves the whole plan with `requestedChild` set |
-| `get_active_plan` | `repo` | resolves manifest `activePlanId` → `get_plan`, or "no active plan" |
+| `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
 instances land in Slice 2 — third-party clients default to the production brain,
@@ -393,4 +422,61 @@ minted at setup generation and delivered consume-once through the setup fetch;
 `.claude/settings.local.json` `env` (gitignored) and `~/.config/rafinery/credentials.json`
 (0600). Teammates mint their own key on the platform (repo → Agent access).
 
+### §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
+state**, marked by `envelope.plane: "state"`:
+
+| Tool | Store | Notes |
+|---|---|---|
+| `list_dev_insights` / `put_dev_insight` / `remove_dev_insight` | **user brain** — account-scoped, cross-repo, PRIVATE | consent-gated by the conductor; never logged to repo activity; nothing person-scoped is ever served to another user |
+| `checkpoint_sync` | **branch working set** — (repo, branch, file path) rows | pushes edited/new brain files from the lazy `.rafa/` instance at CHECKPOINTS (task done · plan approved · explicit ask · cadence · git push/pull — never session-end) under **base-version CAS**: each file carries the row `version` last seen (null = create); a stale base returns the newer copy as a per-file conflict for the HUMAN in that session to resolve |
+| `get_working_set` | branch working set | hydration (a session starts with its branch's working set), the branch view, distillation collect; `needs-adjudication` rows carry the incoming copy in `pending` |
+| `resolve_working_file` | branch working set | `distilled` / `refuted` (+ cited note) at merge-to-main distillation; `keep-current` for adjudication decisions; CAS on status — a racing distill fails loudly |
+| `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` | **plans** — (repo) work objects | the dedicated push-on-approval channel (§7): approval pushes the whole plan (bodies stored); `list_plans` = names only; statuses push back from sessions; the active pointer is explicit, never inferred |
+
+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
+snapshot/ingestError gates. `get_plan`/`get_active_plan` share this exemption
+(plans are work objects, not snapshot-derived knowledge). The retired
+bucket-note tools (`stage/list/resolve_bucket_note`, pre-0.4.0) are superseded
+by the working-set tools.
+
+## 10. Agent cards — `../.claude/agents/*.md` (local gate)
+
+The shipped agents are contract-governed artifacts: every card is validated by
+`rafa compile` (a malformed agent fails the gate) but never enters `manifest.json`.
+No assumed values — applied to the agents themselves.
+
+```yaml
+---
+name: prism                 # required · MUST equal filename stem
+version: 0.4.0              # required · semver (MAJOR.MINOR.PATCH)
+model: opus                 # required · non-empty (trailing # comment = the why)
+groundTruth: code-vs-claim  # required · code-at-sha | code-vs-claim | code-trend | sessions-over-time
+description: >-             # required · non-empty (folded scalar allowed, §0)
+  …
+tools: Read, Grep, …        # required · non-empty
+color: orange               # optional
+duties:                     # required · block list, ≥ 1 · each a duty DSL string
+  - <duty> :: <sop-path> :: <bar>
+---
+```
+
+**Duty DSL** (one string per duty, split on ` :: `, exactly three parts):
+- `duty` — kebab-case name of the responsibility.
+- `sop-path` — path relative to the CODE repo root (e.g.
+  `.claude/skills/rafa-validate/SKILL.md`); the file MUST exist at compile time (a
+  duty without a procedure is a claim, not a contract). Legacy `.rafa/`-relative
+  paths (pre-0.4.0 `capabilities/*.md`) still resolve during the migration window.
+- `bar` — the explicit pass/fail sentence for this duty. Never empty: a duty whose
+  bar can't be stated can't be validated, so it doesn't ship.
+
+Versioning: bump `version:` with any card change; record the *why* outside the card
+(cards ship to end users and stay clean of build-log clutter).
+
+---
+
 This contract is the thing to test against.

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

@@ -0,0 +1,76 @@
+---
+name: rafa-build
+description: "rafa SOP — execute the active plan task by task: atlas implements from recalled knowledge, prism gates done on each Done-check, bloom sweeps the ledger; progress + journals sync at checkpoints. Loaded on /rafa build."
+---
+
+# build — execute the plan, trio-choreographed, compounding  (capability #4)
+
+> Status: **active.** The work-time loop where recall + validation + improvement all
+> fire — the mission payoff. Depends on: plan (#3), brain (#1), ledger (#2).
+> Invoke via `/rafa build`.
+
+Execute the approved plan with all three agents in the loop, knowledge served by the
+platform MCP (one read path — the same surface any third-party agent uses).
+
+## The trio at build time
+
+| Role | Agent | Job per task |
+|---|---|---|
+| **Executor** | atlas | RECALL the task's brain slice via MCP (`search_knowledge` + `get_rule`/`get_playbook`; honor non-exemplars) → implement, convention-adherent |
+| **Validator** | prism | validate the execution against the child's `## Done-check` — strict, unbiased, against code + brain, never against atlas's claims. **`status: done` only on prism PASS**; FAIL → atlas corrects (validate-and-correct at work time). This gate is conductor-flow SOP — deterministic enforcement is the deferred capture-engine's job |
+| **Improver** | bloom | **push**: new improvement opportunities spotted during execution → new ledger files. **close**: improvements fixed in passing → `status: fixed`. **nudge**: top-leverage open item in the task's blast radius — opt-in, never blocking |
+
+## Procedure
+
+1. **Resume** — `get_active_plan` (platform) or local `active.md`; staleness check
+   (envelope `brainForSha` vs local stamp → prompt `rafa push` if behind). MCP
+   recall is automatic throughout — SOP-driven, never dev-invoked; a repo without
+   the `rafinery` MCP connected falls back to local `.rafa/` file reads.
+   **Session consent (asked ONCE, verbs ENUMERATED):** *"keep the platform
+   updated as I work? That means exactly: (1) plan status + Log pushes on
+   cadence, (2) checkpointing this branch's working set (edited/new brain
+   files) — announced per file as it happens, (3) nothing else."* Revocable
+   anytime ("stop pushing"). On "no": journal locally only, push at the end on
+   approval. Dev-level insights are NEVER under this consent — each is its own
+   offer.
+2. **Per task:** atlas recalls → implements → prism validates vs `## Done-check` →
+   bloom sweeps (push new / close fixed / nudge) → update the child file's `status`
+   **and append a dated entry to the child's `## Log`** — what was done, what was
+   decided, what surprised (body prose: displayed verbatim on the platform, never
+   parsed; the plan files at `.rafa/plans/<plan>/` ARE the local cache) → at the
+   task-done CHECKPOINT (under the session consent): `push_plan` /
+   `update_plan_status` (the plans channel — statuses + Log journals) +
+   `rafa checkpoint` (the branch working set), so the platform and every MCP
+   consumer reflect live progress. Checkpoint moments: task done · plan
+   approved · explicit ask · cadence · git push/pull — never session-end. A
+   checkpoint CONFLICT (a teammate's newer copy of the same file) is decided
+   IN THIS SESSION: read the `.theirs.md` copy, merge/adopt/keep, re-checkpoint.
+3. **Brain changes mid-build — WHERE you are decides WHERE it goes.**
+   - **On the default branch (main):** run a full `/rafa scan` (regenerate →
+     prism → compile → push); the brain re-stamps at the new sha, so
+     `brain = f(code@sha)` stays exact.
+   - **On any other branch:** the org brain is NEVER written from a branch —
+     it describes main, and a branch-state scan would poison it for everyone.
+     Invalidated/learned knowledge → the branch **working set**: hydrate the
+     affected note (`rafa hydrate <rule|playbook> <id>`) and edit it, or author
+     a new note file under `.rafa/brain/**` — `rafa checkpoint` syncs it. It
+     enters the org brain at merge-to-main, through distillation. This is the
+     knowledge-propagates-like-code rule, enforced.
+   The working-set files ARE the sanctioned branch authoring surface — what is
+   never allowed is editing main's brain around the scan/compile/push gates.
+4. **Verify** (prism-style) before declaring the plan done; final `push_plan` +
+   `set_active_plan` (clear) + `rafa checkpoint`. A plan that stops being worth
+   finishing closes honestly: `superseded` or `abandoned`, never fake-`done`.
+
+**Lite plans** (single-child, from plan-lite) run the same per-task loop — the
+Done-check gate never relaxes; only the ceremony around it shrinks (no bloom nudge,
+single checkpoint + plan push at the end).
+
+## Deferred / open
+- **The capture engine** — `Stop`/`PostToolUse` hooks making the gates + capture
+  automatic rather than conductor-driven SOP (deterministic-enforcement lesson).
+- **Incremental re-scan** — cite-graph invalidation (diff → invalidate notes citing
+  changed files → re-verify/regenerate only those). Needs: partial-brain cache-key
+  semantics + the seam-neighbor scope rule. Designed (see
+  .fable/sessions/2026-07-07-brain-versioning-and-incremental.md); first post-loop item.
+- Show-thinking + pivot protocol from the atlas character.