@rafinery/cli 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,32 @@ The machine-readable version of this lives in [`lib/releases.mjs`](lib/releases.
 CLI reads it to tell a client, on `rafa update`, exactly what an upgrade requires (nothing,
 a re-scan, or a `rafa migrate`).
 
+## 0.3.0
+
+**Adopt with:** `npx @rafinery/cli@latest update` — no re-scan, no migration required.
+Recommended: re-run `/rafa scan` (or a `rafa push`) so your manifest picks up the new `plans[]`.
+
+The read side lands — your brain is now queryable by any MCP client.
+
+- **`init` wires the knowledge MCP (secret-free where committed).** With a platform setup URL,
+  `init` now registers the platform's read-only knowledge MCP:
+  - `.mcp.json` (committed) — a `rafinery` HTTP server with `Authorization: Bearer ${RAFA_MCP_KEY}`
+    env expansion, so **no secret is committed**.
+  - `.claude/settings.local.json` `env` (gitignored) + `~/.config/rafinery/credentials.json` (0600) —
+    where the raw per-dev key lives. The key is minted at setup generation and delivered
+    **consume-once** through the setup fetch; a re-fetched (keyless) setup is reported loudly, with
+    instructions to mint one on the platform (repo → Agent access).
+  - Merge, never clobber: unparseable files are left alone and reported; other servers/env keys are
+    preserved; only the `rafinery` entry is ours.
+- **Contract §9 — the read-side twin.** Documents the platform-served knowledge MCP: the mandatory
+  response envelope (`source`/`brainForSha`/`ingestedAt`), loud error semantics (no assumed values),
+  and the read-only tool set (`get_brain_status`, `search_knowledge`, `get_rule/playbook/improvement`,
+  `list_improvements`, `get_plan`, `get_active_plan`, `get_coverage`).
+- **§7 plans wired; compile emits `plans[]` + `activePlanId`.** Plan files are no longer "Slice 4" —
+  compile now parses `plans/**/*.md`, enforces global-id uniqueness, parent/child integrity, and
+  the no-stored-progress rule, resolves `active.md` → `activePlanId`, and emits them into
+  `manifest.json`. Progress stays **derived**, never stored.
+
 ## 0.2.2
 
 **Adopt with:** `npx @rafinery/cli@latest update` — no re-scan, no migration.

package/bin/rafa.mjs

@@ -40,7 +40,29 @@ Commands:
   migrate              Bring this repo's structured files (plans, config) up to the schema
                        the installed CLI ships. Idempotent; review the diff after.
 
-Then, inside Claude Code:  /rafa scan · /rafa improve · /rafa plan
+End to end — from zero to a queryable, working brain:
+
+  1. PLATFORM   Sign in → add a GitHub token → add your brain repo + code repo →
+                connect them → "Generate setup command" (URL expires in 15 min;
+                it carries a one-time MCP agent key).
+  2. INSTALL    In your code repo:  npx @rafinery/cli init '<setup-url>'
+                → vendors the blueprint (.rafa/ + .claude/), wires the brain remote,
+                  registers the knowledge MCP in .mcp.json (secret-free) and puts the
+                  key in .claude/settings.local.json + ~/.config/rafinery/credentials.json.
+  3. SCAN       Restart Claude Code, run  /rafa scan  — atlas maps the codebase into
+                cited rules/playbooks, prism validates, bloom writes the improvement
+                ledger. Then  rafa push  → webhook → the platform ingests it.
+  4. SEE IT     Open the repo on the platform: Overview (health), Brain (files),
+                Improvements (kanban), Plans. "Agent access" mints keys for more
+                clients (Slack, incident.io, CI — anything that speaks MCP).
+  5. WORK       /rafa plan "<intent>"  — a prism-validated plan, grounded in the brain.
+                /rafa build            — execute it; progress syncs on every push, so
+                any teammate or session resumes where you stopped.
+  6. QUERY      Any MCP client with a key can read 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.
+
+Then, inside Claude Code:  /rafa scan · /rafa improve · /rafa plan · /rafa build
 
 Docs: ${pkg.homepage ?? "https://github.com/rafinery-ai/rafinery"}`);
 }

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

@@ -1,5 +1,5 @@
 ---
-description: rafa — init · scan · improve · push · leverage · migrate · update · help. Usage: /rafa <init|scan|improve|push|leverage|migrate|update|help> [--brain-only]
+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]
 ---
 
 You are the **conductor** of the rafa agent loop, running in the **main session**.
@@ -52,6 +52,38 @@ cite-check them (`--root=.rafa/improve --dirs=improvements`, drop unresolved), r
 `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 [`.rafa/capabilities/plan.md`](../../.rafa/capabilities/plan.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 →
+   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
+   `## 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).
+
+## `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 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.
+
 ## `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
 dev's own git auth. Use after a scan, or to re-sync a brain that changed.
@@ -103,6 +135,24 @@ 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, wires the brain remote, 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.
@@ -113,6 +163,8 @@ names exist on both — the CLI does the mechanical half, `/rafa` the intelligen
 | `/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 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. |

package/blueprint/.rafa/bin/rafa-compile.mjs

@@ -324,6 +324,90 @@ function compileCoverage() {
   return { domains };
 }
 
+// Plans (contract §7): parent+child files under plans/**. Global id uniqueness,
+// parent/child cross-checks, progress never stored, active.md → activePlanId.
+function compilePlans() {
+  const plans = [];
+  const seen = new Map(); // id → path (global uniqueness across plans/**)
+  for (const path of walk(join(ROOT, "plans"))) {
+    const name = path.split("/").pop();
+    const { data, error } = parseFrontmatter(read(path));
+    if (error) {
+      fail(path, "frontmatter", error);
+      continue;
+    }
+    checkVersion(data, path);
+    const id = checkId(data, path, name);
+    if (seen.has(id))
+      fail(path, "id", `duplicate plan id "${id}" (also ${seen.get(id)}) · ids are globally unique across plans/**`);
+    seen.set(id, path);
+    if ("progress" in data)
+      fail(path, "progress", "never stored · parent progress is derived by counting children");
+    const kind = reqEnum(data, "kind", ["parent", "child"], path);
+    const plan = reqStr(data, "plan", path);
+    const status = data.status;
+    if (kind === "child") {
+      if (!isEnum(status, ["todo", "in-progress", "done", "blocked"]))
+        fail(path, "status", "required (child) · todo|in-progress|done|blocked");
+      if (data.parent !== plan)
+        fail(path, "parent", `must equal plan "${plan}" for a child (flat v1)`);
+    } else {
+      if (data.parent !== null && data.parent !== "null")
+        fail(path, "parent", "must be null for kind: parent");
+      if (plan !== id) fail(path, "plan", `must equal id "${id}" for kind: parent`);
+      if (
+        status !== undefined &&
+        !isEnum(status, ["todo", "in-progress", "done", "blocked"])
+      )
+        fail(path, "status", "optional (parent) · todo|in-progress|done|blocked");
+    }
+    plans.push({
+      id,
+      plan,
+      parent: kind === "parent" ? null : plan,
+      kind,
+      title: reqStr(data, "title", path),
+      ...(isEnum(status, ["todo", "in-progress", "done", "blocked"])
+        ? { status }
+        : {}),
+      ...(typeof data.branch === "string" && data.branch !== ""
+        ? { branch: data.branch }
+        : {}),
+      ...(typeof data.baseSha === "string" && data.baseSha !== ""
+        ? { baseSha: String(data.baseSha) }
+        : {}),
+      path: rel(path),
+    });
+  }
+  // Cross-check: every child's plan resolves to a kind:parent in this compile.
+  const parents = new Set(plans.filter((p) => p.kind === "parent").map((p) => p.id));
+  for (const p of plans)
+    if (p.kind === "child" && !parents.has(p.plan))
+      fail(p.path, "plan", `no parent plan "${p.plan}" in this compile (dangling child)`);
+  return plans;
+}
+
+// active.md (generated pointer) → activePlanId. First line `# <plan-id>` must
+// resolve to a kind:parent plan; `# No active plan` or a missing file → null
+// (documented default: the pointer is generated, absence means "none").
+function compileActivePlanId(plans) {
+  const path = join(ROOT, "active.md");
+  if (!existsSync(path)) return null;
+  const first = read(path).split("\n")[0].trim();
+  const m = first.match(/^#\s+(.+)$/);
+  if (!m) {
+    fail(path, "pointer", 'first line must be "# <plan-id>" or "# No active plan"');
+    return null;
+  }
+  const val = m[1].trim();
+  if (/^no active plan$/i.test(val)) return null;
+  if (!plans.some((p) => p.kind === "parent" && p.id === val)) {
+    fail(path, "pointer", `active plan "${val}" is not a kind:parent plan in this compile`);
+    return null;
+  }
+  return val;
+}
+
 // ── assemble ─────────────────────────────────────────────────────────────────
 const gitOpts = { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }; // no stderr leak
 function gitSha() {
@@ -349,6 +433,8 @@ const improvements = compileImprovements(join(ROOT, "improve", "improvements"));
 const health = compileHealth();
 const ledger = compileLedger();
 const coverage = compileCoverage();
+const plans = compilePlans();
+const activePlanId = compileActivePlanId(plans);
 
 // Cross-check: ledger.open / by_priority must match the actual open improvements.
 if (ledger) {
@@ -380,11 +466,13 @@ const manifest = {
   coverage,
   notes,
   improvements,
-  plans: [],
+  activePlanId,
+  plans,
 };
 writeFileSync(join(ROOT, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
 console.log(
   `✓ rafa compile: ${notes.length} notes · ${improvements.length} improvements · ` +
+    `${plans.length} plans${activePlanId ? ` (active: ${activePlanId})` : ""} · ` +
     `health ${health ? "ok" : "—"} · ledger ${ledger ? "ok" : "—"} · ` +
     `coverage ${coverage ? `${coverage.domains.length} domains` : "—"} → .rafa/manifest.json`,
 );

package/blueprint/.rafa/capabilities/build.md

@@ -1,38 +1,39 @@
-# build — execute, brain-aware, compounding  (DRAFT · capability #4)
+# build — execute the plan, trio-choreographed, compounding  (capability #4)
 
-> Status: **draft / spec.** The work-time loop where **recall + nudge + capture-back** all
-> fire — the mission payoff. Depends on: plan (#3), brain (#1), ledger (#2). Built last.
+> 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 both stores in the loop. Invoke via `/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).
 
-## Why build fits the mission (the flywheel closes here)
+## The trio at build time
 
-Each task both **spends** the stores and **feeds** them — the compounding made real:
+| 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 |
 
-- **RECALL** — per task, load the brain slice for the touched domains: follow
-  conventions/contracts; honor **non-exemplars** (don't pattern-match the salient-but-wrong
-  example — the audit showed a cold agent paying a 100K-token correction loop for exactly this).
-- **NUDGE** — surface the top-leverage open improvement in the task's blast radius: *"10-min fix
-  while you're here?"* Dismissible, never blocking. (bloom's deferred nudge, finally firing.)
-- **LEVERAGE (orchestrate, don't bury)** — before hand-rolling a task, surface the best-fit
-  existing capability (skill/tool/MCP — committed or the dev's personal) to the host, and any
-  config that would help it fire. Recommend; the host orchestrates. Never reinvent what's present.
-- **CAPTURE-BACK** — as work lands:
-  - decisions / scars → propose brain notes (**prism-validated** before they enter the brain),
-    **tool-agnostic** — capture *what + why + cited code*, never which (possibly personal) skill produced it,
-  - improvements fixed in passing → improve ledger **auto-close** (`status: fixed`),
-  - touched code → **incremental re-scan** of that domain so the brain stays fresh.
+## Procedure
 
-## Procedure (draft)
-1. Resume from `active.md` (plan + active task).
-2. Per task: **recall** brain slice → implement (convention-adherent) → **nudge** a
-   blast-radius fix (opt-in) → done-check.
-3. **Capture-back**: distill decisions/scars (prism-validated); auto-close fixed improvements;
-   re-scan the touched domain.
-4. Verify (prism-style) before declaring done. Update `active.md`.
+1. **Resume** — `get_active_plan` (platform) or local `active.md`; staleness check
+   (envelope `brainForSha` vs local stamp → prompt `rafa push` if behind).
+2. **Per task:** atlas recalls → implements → prism validates vs `## Done-check` →
+   bloom sweeps (push new / close fixed / nudge) → update the child file's `status`
+   → periodic `rafa compile` + `rafa push` so the platform (and every MCP consumer)
+   reflects live progress.
+3. **Brain changes mid-build** — execution may invalidate rules or teach new ones.
+   v1: run a full `/rafa scan` (regenerate → prism → compile → push); the whole
+   brain re-stamps at the new sha, so `brain = f(code@sha)` stays exact. NEVER
+   hand-edit brain files around the gate.
+4. **Verify** (prism-style) before declaring the plan done; final compile + push.
 
 ## Deferred / open
-- **The capture engine** — `Stop`/`PostToolUse` hooks to make capture-back *automatic*, not
-  model-discretion (the deterministic-enforcement lesson, applied to capture).
-- **Incremental re-scan** — changed files + seam-neighbors only (keep it cheap).
+- **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.

package/blueprint/.rafa/capabilities/plan.md

@@ -1,38 +1,47 @@
-# plan — brain-grounded ADR decomposition  (DRAFT · capability #3)
-
-> Status: **draft / spec.** The first *consumer* of the stores — where the brain starts to pay
-> off. Depends on: brain (#1), ledger (#2). Built after the stores are proven in real use.
-
-Turn an intent into an approval-gated **ADR plan**, *grounded* in the brain (don't re-derive)
-and *aware* of the ledger (fold improvement into the work). Invoke via `/plan <intent>`.
-
-## Why plan fits the mission (the integration)
-
-plan is the first place knowledge + improvement meet real work, all keyed on **domain**:
-
-- **RECALL** — load the brain slice for the domains the intent touches: conventions,
-  contracts, flows, and **non-exemplars** (don't copy the grandfathered demo — the audit's
-  exact lesson). The plan starts from known ground, not a cold read. *This is the 100×.*
-- **BLAST RADIUS** — name the domains/nodes the change touches (from the brain's map), so risk
-  is known up front and `build` can recall/nudge per task.
-- **NUDGE** — query the improve ledger for open improvements in that blast radius; surface the
-  **top-leverage** ones as optional *"while-you're-here"* tasks (leverage-ranked, dismissible).
-- **LEVERAGE (orchestrate, don't bury)** — match the intent against available capabilities
-  (committed skills/agents/MCP **+** the dev's personal ones, discovered live) and recommend the
-  best-fit to the host: *"there's a `tdd-workflow` skill for this — use it."* Never plan to
-  hand-roll what a capability already does; flag config that would help. Recommend; the host
-  orchestrates (a hook can't auto-invoke).
-
-## Procedure (draft)
-1. **Recall** the brain slice for the intent's domains (notes + contracts + non-exemplars).
-2. **Decompose** ADR: decision + rationale + alternatives + tradeoffs + risk surface + non-goals.
-3. **Tasks** — each bound to domains/nodes (so `build` can recall + nudge per task) with a done-check.
-4. **Ledger nudge** — surface open improvements in the blast radius as optional, leverage-ranked tasks.
-4b. **Leverage-match** — recommend the existing skills/tools/MCP that fit the tasks; flag tooling-fit
-    improvements. Don't plan to reinvent a present capability.
-5. **Approval gate** (ExitPlanMode). Materialize `.rafa/plans/<id>.md` + `active.md → {plan, task:1}`.
+# plan — brain-grounded, prism-validated decomposition  (capability #3)
+
+> Status: **active.** The first *consumer* of the stores — where the brain starts to
+> pay off. Depends on: brain (#1), ledger (#2). Invoke via `/rafa plan <intent>`.
+
+Turn an intent into an approval-gated plan (contract §7 files), *grounded* in the
+brain (don't re-derive), *aware* of the ledger (fold improvement into the work), and
+**validated by prism before the owner ever sees it**.
+
+## The trio at plan time
+
+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.
+- **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).
+- **prism validates the plan itself** — before the approval gate: is every task
+  grounded in real brain/code (not hallucinated ground)? does every child carry a
+  `## Done-check` (the expected outcome prism will validate execution against)?
+  A plan whose children lack Done-checks is REJECTED here — compile never parses
+  bodies (invariant #3); this gate is prism's.
+
+## Procedure
+
+1. **Staleness check** — compare the platform envelope's `brainForSha` against the
+   local brain stamp; if the platform is behind, surface "run `rafa push`" (never
+   proceed silently on knowledge you know is stale — never block either).
+2. **Recall** (atlas, via MCP) → **decompose** ADR-style: decision + rationale +
+   alternatives + risk surface + non-goals; tasks bound to domains with a
+   `## Done-check` each.
+3. **Ledger pull** (bloom) → optional leverage tasks in the blast radius.
+4. **Leverage-match** — recommend existing skills/tools/MCP that fit the tasks;
+   never plan to hand-roll what a capability already does.
+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`).
 
 ## Deferred / open
-- Capture-back of plan-time decisions → brain (prism-validated) — needs the capture engine (hooks).
-- Pivot detection (conversation-as-steering; mark superseded, the path is data).
-- Plan lifecycle + tiering (cap, archive→remote, restore) — designed in `.arohi/architecture.md`.
+- Capture-back of plan-time decisions → brain (needs the capture engine).
+- Pivot detection (mark superseded; the path is data).
+- Plan lifecycle + tiering (cap, archive→remote, restore).

package/blueprint/.rafa/contract.md

@@ -37,10 +37,10 @@ doesn't validate, compile fails.
 | coverage | `brain/coverage.md` | **structured** | §6 | atlas |
 | improvement | `improve/improvements/*.md` | **structured** | §3 | bloom |
 | ledger | `improve/ledger.md` | **structured** | §5 | bloom |
-| plan | `plans/**/*.md` | **structured** | §7 *(wired: Slice 4)* | plan/build |
+| 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 |
-| active pointer | `active.md` | **generated** | — (`# <plan-id>` or "No active plan") | conductor |
+| 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 |
 
 `structured` types are compiled into `manifest.json` (§1) — that JSON is the ONLY thing the
@@ -157,7 +157,20 @@ JSON. This is the exact shape the platform binds to.
     }
   ],
 
-  "plans": []                               // v1: may be empty; shape in §6
+  "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)
+    }
+  ]
 }
 ```
 
@@ -265,7 +278,7 @@ domains: { design-system: mapped, components: mapped, api: thin, external-integr
 
 ---
 
-## 7. Plan files — `plans/**/*.md` (Slice 4)
+## 7. Plan files — `plans/**/*.md`
 
 Each child owns exactly one file (so merges never conflict; parent progress is
 derived by counting).
@@ -273,19 +286,36 @@ derived by counting).
 ```yaml
 ---
 schemaVersion: 1
-id: c1-schema                    # required · == filename stem
+id: multitenant-c1-schema        # required · == filename stem · GLOBALLY unique across plans/**
 plan: multitenant                # required · the parent plan id
-parent: null                     # required · parent plan id, or null for the root
+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
 branch: feat/mt-c1               # optional · the branch this executes on
 baseSha: abc123                  # optional · commit it was cut from
 ---
+（prose body — for a child it MUST contain a `## Done-check` section: the expected
+outcome prism validates execution against. Compile never parses bodies; a missing
+Done-check is rejected by prism's PLAN validation, not by compile.）
 ```
 
-Parent progress is `count(children where status == done) / count(children)` —
-derived, never stored.
+Rules (all compile-enforced unless noted):
+
+- **Global id uniqueness.** `plans/**` is nested, so stems could collide; a duplicate
+  plan id anywhere under `plans/` is a compile error. Convention: prefix children
+  with the plan id (`<plan>-c1-….md`).
+- **`kind: parent`** → `parent` MUST be `null` and `plan` MUST equal `id`.
+- **`kind: child`** → `plan` MUST resolve to a `kind: parent` file in the same
+  compile, and `parent` MUST equal `plan` (flat parent→children in v1). A dangling
+  child is a loud error; a parent with zero children is valid (a plan just created).
+- **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).
+- **`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).
 
 ---
 
@@ -300,4 +330,67 @@ derived, never stored.
   blocks the push (better than a silently-wrong brain).
 - The validator **reports, never auto-fills** a required value.
 
+---
+
+## 9. The read side — knowledge MCP (platform-served)
+
+The platform serves the **ingested** brain to any MCP client (the build agent, a
+teammate's session, Slack/incident.io agents) — the read-side twin of this contract.
+One backend: the platform. Local files are the *authoring* surface; the platform is
+the *serving* surface, and it serves only what passed compile + ingest.
+
+**Envelope — mandatory on every tool response:**
+
+```jsonc
+{
+  "source": "platform",
+  "brainForSha": "<snapshot codeSha>",   // the ingested manifest's codeSha — one source
+  "ingestedAt": "<ISO time of ingest>",
+  "schemaVersion": 1,
+  "synthesized": false                   // raw tools: always false
+}
+```
+
+**Error semantics (no assumed values, outward):** snapshot has an `ingestError` →
+every tool returns that error loudly, never partial data. Repo connected but never
+pushed (no snapshot) → `"no brain ingested — run rafa push"`. Invalid/mismatched key
+→ loud auth error, never a fallback. Empty search → empty result, never a stretched
+match.
+
+**Tools (read-only — ALL writes flow files → compile → push → ingest):**
+
+| Tool | Args | Returns |
+|---|---|---|
+| `get_brain_status` | `repo` | envelope + per-type counts, health, coverage summary, `activePlanId`, `ingestError?` |
+| `get_coverage` | `repo` | coverage rows (the domain map — how an agent navigates) |
+| `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" |
+
+`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,
+i.e. the default branch's instance).
+
+**Search = deterministic lexical retrieval; the server retrieves, the agent decides.**
+Fields searched per type — rule/playbook: `title, summary, domain, type` ·
+improvement: `title, summary, lens, blast_radius` · plan: `title, plan, parent`.
+Score = Σ over matched case-folded query tokens of field weight (`title` 3 ·
+`domain`/`lens`/`blast_radius`/`type`/`plan`/`parent` 2 · `summary` 1); tie-break
+score desc then id asc; fields a type lacks are omitted, never defaulted. Candidates
+carry `matchKind: "lexical"` (`"semantic"` reserved). `ask_knowledge` is a reserved
+tool id for the synthesis layer (responses will carry `synthesized: true`).
+
+**Auth:** per-repo machine keys, minted on the platform, sent as
+`Authorization: Bearer`. Keys are stored hashed platform-side and live client-side in
+`~/.config/rafinery/credentials.json` — never inside the code repo or this brain repo.
+
+**Client wiring (written by `rafa init`, secret-free where committed):** a key is
+minted at setup generation and delivered consume-once through the setup fetch;
+`.mcp.json` (committed) registers the `rafinery` server with
+`Authorization: Bearer ${RAFA_MCP_KEY}` env expansion; the raw key lands in
+`.claude/settings.local.json` `env` (gitignored) and `~/.config/rafinery/credentials.json`
+(0600). Teammates mint their own key on the platform (repo → Agent access).
+
 This contract is the thing to test against.

package/lib/init.mjs

@@ -11,6 +11,12 @@ import { execSync } from "node:child_process";
 import { join } from "node:path";
 import { blueprintSource, copyBlueprint } from "./blueprint.mjs";
 import { mergeClaudeSettings } from "./claude-config.mjs";
+import {
+  credentialsPath,
+  mergeLocalEnv,
+  mergeMcpJson,
+  saveCredentials,
+} from "./mcp-config.mjs";
 import { stampCurrent } from "./stamp.mjs";
 import { notifyIfBehind } from "./version-check.mjs";
 import { isInteractive, ask } from "./prompt.mjs";
@@ -108,12 +114,49 @@ export default async function init(args) {
   // Grant rafa's vendored tools their permissions (merge, never overwrite).
   reportSettings(TARGET);
 
-  // Keep the brain out of the code repo's diffs.
-  const gi = join(TARGET, ".gitignore");
-  const body = existsSync(gi) ? readFileSync(gi, "utf8") : "";
-  if (!/^\.rafa\/?\s*$/m.test(body)) {
-    appendFileSync(gi, `${body.endsWith("\n") || body === "" ? "" : "\n"}.rafa/\n`);
-    console.log("  ✓ .rafa/ → .gitignore");
+  // Keep the brain out of the code repo's diffs; keep the per-dev MCP key out of git.
+  const ensureIgnored = (line, label) => {
+    const gi = join(TARGET, ".gitignore");
+    const body = existsSync(gi) ? readFileSync(gi, "utf8") : "";
+    const re = new RegExp(`^${line.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\/?\\s*$`, "m");
+    if (!re.test(body)) {
+      appendFileSync(gi, `${body.endsWith("\n") || body === "" ? "" : "\n"}${line}\n`);
+      console.log(`  ✓ ${label} → .gitignore`);
+    }
+  };
+  ensureIgnored(".rafa/", ".rafa/");
+
+  // Wire the platform's knowledge MCP (contract §9): committed .mcp.json entry
+  // (secret-free, ${RAFA_MCP_KEY} expansion) + the key in gitignored local config
+  // + the per-machine canonical copy. The key was minted at setup generation and
+  // is consume-once: a re-fetched setup arrives keyless and we say so loudly.
+  if (p?.mcpUrl) {
+    if (p.agentKey) {
+      const cred = saveCredentials(p.repoId, p.agentKey, p.mcpUrl);
+      console.log(
+        cred.skipped
+          ? `  ! MCP key NOT saved to ${credentialsPath()} — ${cred.skipped}`
+          : `  ✓ MCP key → ${cred.file} (0600)`,
+      );
+      const env = mergeLocalEnv(TARGET, p.agentKey);
+      console.log(
+        env.skipped
+          ? `  ! ${env.skipped} — export RAFA_MCP_KEY yourself (key is in ${credentialsPath()})`
+          : "  ✓ RAFA_MCP_KEY → .claude/settings.local.json (gitignored)",
+      );
+      ensureIgnored(".claude/settings.local.json", ".claude/settings.local.json");
+    } else {
+      console.log(
+        `  ! this setup's MCP key was already consumed${p.agentKeyConsumed ? "" : " or absent"} — ` +
+          "mint one on the platform (repo → Agent access) and set RAFA_MCP_KEY in .claude/settings.local.json",
+      );
+    }
+    const mcp = mergeMcpJson(TARGET, p.mcpUrl);
+    console.log(
+      mcp.skipped
+        ? `  ! ${mcp.skipped} — add the "rafinery" server pointing at ${p.mcpUrl} yourself`
+        : `  ✓ knowledge MCP → .mcp.json (rafinery · ${p.mcpUrl})`,
+    );
   }
 
   // Stamp the versions this repo was provisioned at — the compat anchor `update`/`migrate`
@@ -145,9 +188,15 @@ export default async function init(args) {
 
   console.log(
     `\n✓ Provisioned.\n\nNext steps:\n` +
-      "  1. Restart Claude Code in this repo (reload the /rafa command + agents).\n" +
+      "  1. Restart Claude Code in this repo (reload the /rafa command + agents" +
+      (p?.mcpUrl ? " + the rafinery MCP server" : "") +
+      ").\n" +
       "  2. Run  /rafa scan  — build + validate the brain, then  rafa push  to sync it.\n" +
-      "  3. Open the repo on the rafinery platform — its Overview shows the brain once pushed.",
+      "  3. Open the repo on the rafinery platform — its Overview shows the brain once pushed." +
+      (p?.mcpUrl
+        ? "\n  4. After the first push, any MCP client with a key can query this repo's knowledge\n" +
+          `     (endpoint: ${p.mcpUrl} · keys: repo → Agent access on the platform).`
+        : ""),
   );
 
   await notifyIfBehind();

package/lib/mcp-config.mjs

@@ -0,0 +1,93 @@
+// MCP wiring for `rafa init` — connect the client repo to the platform's
+// knowledge MCP (.rafa/contract.md §9) with zero secrets in committed files:
+//
+//   .mcp.json                     committed · server entry, key via ${RAFA_MCP_KEY}
+//   .claude/settings.local.json   gitignored · env.RAFA_MCP_KEY = the raw key
+//   ~/.config/rafinery/credentials.json   per-machine canonical copy (0600)
+//
+// Merge, never clobber: unparseable files are left alone (reported), other
+// servers/env keys are preserved; only the `rafinery` entry is ours to replace.
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  chmodSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+
+const readJson = (file) => {
+  if (!existsSync(file)) return null;
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch (e) {
+    return { error: e instanceof Error ? e.message : String(e) };
+  }
+};
+const writeJson = (file, data) => {
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify(data, null, 2) + "\n");
+};
+
+export function credentialsPath() {
+  return join(homedir(), ".config", "rafinery", "credentials.json");
+}
+
+// Canonical per-machine store: { repos: { <repoId>: { key, mcpUrl, savedAt } } }.
+// Never inside the code repo or the brain repo — nothing to gitignore, nothing
+// for `rafa push` to publish.
+export function saveCredentials(repoId, key, mcpUrl) {
+  const file = credentialsPath();
+  const existing = readJson(file);
+  if (existing?.error)
+    return { skipped: `credentials.json is not valid JSON (${existing.error})` };
+  const data = existing ?? {};
+  data.repos = { ...(data.repos ?? {}) };
+  data.repos[repoId] = { key, mcpUrl, savedAt: new Date().toISOString() };
+  writeJson(file, data);
+  try {
+    chmodSync(file, 0o600);
+  } catch {
+    /* best-effort on non-POSIX */
+  }
+  return { file };
+}
+
+// .mcp.json — the committed, shareable server registration. The Authorization
+// header uses ${RAFA_MCP_KEY} env expansion, so the file carries NO secret; each
+// teammate's key comes from their own settings.local.json / shell env.
+export function mergeMcpJson(targetDir, mcpUrl) {
+  const file = join(targetDir, ".mcp.json");
+  const existing = readJson(file);
+  if (existing?.error)
+    return { skipped: `.mcp.json is not valid JSON (${existing.error})` };
+  const data = existing ?? {};
+  data.mcpServers = { ...(data.mcpServers ?? {}) };
+  const entry = {
+    type: "http",
+    url: mcpUrl,
+    headers: { Authorization: "Bearer ${RAFA_MCP_KEY}" },
+  };
+  const same = JSON.stringify(data.mcpServers.rafinery) === JSON.stringify(entry);
+  data.mcpServers.rafinery = entry;
+  if (!same) writeJson(file, data);
+  return { file, changed: !same };
+}
+
+// .claude/settings.local.json — Claude Code's gitignored per-checkout settings;
+// its `env` map is applied to the session, which is exactly where a per-dev
+// secret belongs. Everything else in the file is preserved.
+export function mergeLocalEnv(targetDir, key) {
+  const file = join(targetDir, ".claude", "settings.local.json");
+  const existing = readJson(file);
+  if (existing?.error)
+    return {
+      skipped: `.claude/settings.local.json is not valid JSON (${existing.error})`,
+    };
+  const data = existing ?? {};
+  data.env = { ...(data.env ?? {}), RAFA_MCP_KEY: key };
+  writeJson(file, data);
+  return { file };
+}

package/lib/releases.mjs

@@ -56,6 +56,19 @@ export const RELEASES = [
       "(no more `.new` clutter; stale `.new` cleaned up; --overwrite/--keep flags). New `/rafa help` " +
       "with a full command reference for both surfaces. (Completes 0.2.1, published before these landed.)",
   },
+  {
+    version: "0.3.0",
+    contract: 1,
+    plans: 1,
+    requires: "update",
+    summary:
+      "Knowledge MCP — the read side. `init` now wires the platform's read-only knowledge MCP: " +
+      "a secret-free `.mcp.json` entry (Bearer ${RAFA_MCP_KEY}), the per-dev key into gitignored " +
+      "`.claude/settings.local.json` + `~/.config/rafinery/credentials.json` (0600), delivered " +
+      "consume-once via the setup URL. Contract §9 (read-side tools + envelope) and §7 plans are " +
+      "wired: compile now emits `plans[]` + `activePlanId` with global-id/parent/progress rules. " +
+      "Re-run `/rafa scan` (or push) to surface plans in your manifest; no re-scan required to adopt.",
+  },
 ];
 
 // The release this CLI build ships (last entry).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rafinery/cli",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "rafa — the AI engineer CLI. Vendors the rafa blueprint into your repo (shadcn-style) and runs the deterministic contract gates.",
   "type": "module",
   "bin": {