@rafinery/cli 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,85 @@ 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.4.0 — the working-set blueprint
+
+**Adopt with:** `npx @rafinery/cli@latest update` — it re-syncs the blueprint to the new
+layout and runs the mechanical `blueprint-split-0.4.0` migration (removes the old vendored
+`.rafa/bin` + `.rafa/capabilities` + `.rafa/contract.md`). **No re-scan** — the brain data
+schema is unchanged (contract data v1, plans v1). Plans: re-push once through the new
+channel (approve/`push_plan`) so bodies land on the platform.
+
+### The blueprint split — nothing vendored under `.rafa/` anymore
+
+- **Gate tools live INSIDE this CLI** (`rafa compile` · `rafa verify-citations` ·
+  `rafa push` · `rafa pull`) — they move with the CLI version, never with the repo.
+- **Capabilities are committed SKILLS** at `.claude/skills/rafa-*` — behavior versions
+  with your code, MR-reviewed, clone-complete.
+- **The contract is canonical in the code repo** (`.claude/rafa/contract.md`); a stamped
+  copy rides every brain push.
+- **`.rafa/` is lazy, gitignored knowledge+state** that bootstraps from the committed
+  `rafa.json`: **clone → `npx rafa pull` just works** (no init on the machine).
+  `rafa pull --full` mirrors the brain repo for offline reads.
+
+### The working set — branch knowledge under CAS (supersedes bucket notes)
+
+- Capture's working medium is **files**: edit/author brain notes in the branch's lazy
+  `.rafa/brain/**`; `rafa hydrate` faults org-brain notes in (stamped disposable-cache —
+  unedited hydrations are never pushed).
+- **`rafa checkpoint`** syncs the branch working set to the platform under
+  **base-version CAS** at checkpoint moments (task done · plan approved · explicit ask ·
+  cadence · git push/pull — **never session-end**). A teammate's newer copy comes back
+  as a per-file conflict (`.theirs.md`) for YOUR decision — never auto-resolved.
+
+### Plans — a dedicated push-on-approval channel
+
+- Plans never ride the brain manifest again: approval pushes the whole plan (bodies
+  included) via `push_plan`; **"list plans" = names only**; **"load plan X"**
+  materializes it back into `.rafa/plans/`. Statuses + `## Log` journals push back on
+  build cadence. Terminal statuses `superseded`/`abandoned` close work honestly
+  (`done` stays prism-earned; the board renders, never sets).
+
+### CI reconciliation — the rigor gradient in YOUR CI
+
+- **`rafa ci-setup`** installs the reconcile workflow: branch→parent merge = **mechanical
+  fold** (`rafa fold`, no LLM — divergence flagged `needs-adjudication` for the next
+  session's digest, never guessed) · merge-to-main = **distillation**
+  (`rafa distill --headless` — Agent SDK on the **org's own `ANTHROPIC_API_KEY`** from CI
+  secrets, never stored on the rafinery platform; validated vs merged main, gated by
+  verify-citations + compile, pushed to the brain repo). No CI? The next dev session
+  offers the same reconciliation.
+
+### The agents become contract-governed software (earlier in this release)
+
+- **Agent cards are gated (contract §10).** Every vendored agent (`atlas` 3.4.0 · `prism`
+  0.4.0 · `bloom` 0.5.0) now carries semver + ground truth + `duties:` — one line per duty in
+  the form `"<duty> :: <sop> :: <bar>"` — and `rafa compile` validates the cards like any
+  structured file (bad card → loud failure, never a silently drifted agent). The frontmatter
+  grammar gains folded scalars (`>-`) for this.
+- **prism's verdict rule is encoded.** An unflagged salient-but-wrong exemplar now
+  auto-ITERATEs regardless of the numeric score (validate.md §decision) — the case where a
+  "passing" brain teaches every cold agent the wrong pattern.
+- **All agents query the knowledge MCP.** `mcp__rafinery` is on every card's tools; recall is
+  SOP-automatic in plan/build with local `.rafa/brain/` fallback when not platform-connected.
+- **Intent dispatch (conductor 1.1.0).** Say "let's add X" — the conductor routes plan-shaped /
+  build-shaped / fix-shaped prompts into the SOPs without `/rafa` being typed
+  (announce-and-proceed; "skip" always wins instantly). Admin verbs — init · scan · push ·
+  migrate · update — still run ONLY when explicitly invoked. `plan-lite` handles small blast
+  radii with the same contract, less ceremony.
+- **Plan approval IS the push trigger.** Approving a plan in a connected repo pushes it
+  immediately (no second prompt) — it renders on the platform, board-style, within moments.
+- **`rafa pull` — the teammate path.** The brain never travels through the code repo
+  (`.rafa/` is gitignored there); it travels through the brain repo. Cloned an
+  already-scanned repo? `rafa init` (blueprint + MCP key) then `rafa pull` — full local
+  brain cache in seconds, **never re-scan for knowledge that already exists**.
+  Fast-forward only; a diverged local cache stops loudly (`--force` adopts the remote —
+  the remote is canonical). And when platform-connected, recall works with zero local
+  files anyway (the MCP serves the brain).
+- **compass — the fourth agent.** The dev's private coach (user brain: patterns,
+  preferences, constraints — consent-gated, cross-repo, legible/correctable/deletable).
+  `/rafa insights` bootstraps it; `/rafa distill` reconciles merged-branch staged notes
+  into the org brain (prism-validated against merged main).
+
 ## 0.3.0
 
 **Adopt with:** `npx @rafinery/cli@latest update` — no re-scan, no migration required.

package/README.md

@@ -1,23 +1,33 @@
 # @rafinery/cli — `rafa`
 
 The rafinery AI-engineer CLI. Like shadcn, it **vendors the rafa blueprint into your
-repo** — agents, capabilities, the file contract, and the deterministic gates — and
-you own your copies. It is *not* a runtime dependency; you never `import` it.
+repo** — agents, the `/rafa` command, the rafa skills, and the file contract — and you
+own your copies. The deterministic gate tools live INSIDE this package (never vendored),
+so a repo is gate-current the moment the CLI is. It is *not* a runtime dependency; you
+never `import` it.
 
 ```bash
 npx @rafinery/cli init          # provision this repo (vendor the blueprint)
-npx @rafinery/cli init <url>    # …and wire the brain remote from a platform setup URL
+npx @rafinery/cli init <url>    # …and wire the platform from a setup URL
 # after install the command is just `rafa`:
 rafa update                     # re-sync the blueprint (opt-in; you own your copies)
 rafa compile                    # validate the brain against the contract → manifest.json
-rafa push                       # compile, then push .rafa/ to your brain remote
+rafa verify-citations           # deterministic citation checker (B1/B2/policy)
+rafa push                       # compile + push .rafa/ to your brain remote (from main)
+rafa pull [--full]              # make a fresh clone brain-ready (lazy; --full mirrors)
 ```
 
 The LLM work runs inside Claude Code, not the CLI: `/rafa scan`, `/rafa improve`, `/rafa plan`.
 
-## Model
-- **Blueprint = vendored files** you own (`.claude/agents/*`, `.rafa/capabilities/*`). Tune them.
-- **Contract + gates** (`.rafa/contract.md`, `.rafa/bin/*`) move in lockstep — treat as generated.
+## Model (blueprint split, 0.4.0)
+- **Blueprint = committed files** you own (`.claude/agents/*`, `.claude/commands/rafa.md`,
+  `.claude/skills/rafa-*`). Tune them; they version with your code, MR-reviewed.
+- **Contract** (`.claude/rafa/contract.md`) moves in lockstep with the CLI that implements
+  it — treat as generated. A stamped copy rides every brain push.
+- **Gate tools** are not files in your repo — they are this package (`rafa compile`,
+  `rafa verify-citations`, `rafa push`, `rafa pull`).
+- **`.rafa/` is lazy, gitignored knowledge+state** — plans + hydrated working files. It
+  bootstraps from the committed `rafa.json`: clone → `npx rafa pull` just works.
 - **Updates** ship by bumping this CLI; `rafa update` pulls the new blueprint into your repo.
 
 See the monorepo: https://github.com/rafinery-ai/rafinery

package/bin/rafa.mjs

@@ -1,14 +1,18 @@
 #!/usr/bin/env node
 // rafa — the rafinery CLI. Thin dispatcher; each command lives in ../lib.
 //
-//   rafa init [<setup-url>]   provision this repo (vendor blueprint + wire brain remote)
+//   rafa init [<setup-url>]   provision this repo (vendor blueprint + wire the platform)
 //   rafa update               re-sync the blueprint into this repo (shadcn-style)
 //   rafa compile              run the contract gate → .rafa/manifest.json
-//   rafa push                 compile + push .rafa/ to the brain remote
+//   rafa verify-citations     deterministic citation checker (B1/B2/policy gates)
+//   rafa push                 compile + push .rafa/ to the brain remote (main-branch act)
+//   rafa pull [--full]        make this clone brain-ready (lazy skeleton; --full mirrors)
 //   rafa leverage             inspect your agent toolbox → proactive tips
 //   rafa migrate              bring structured files (plans/config) up to the current schema
 //
-// The LLM work (scan / improve / plan) runs inside Claude Code via /rafa.
+// The gate tools live INSIDE this package (blueprint split, 0.4.0) — nothing is
+// vendored into .rafa/bin anymore. The LLM work (scan / improve / plan) runs
+// inside Claude Code via /rafa.
 
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
@@ -17,7 +21,21 @@ import { fileURLToPath } from "node:url";
 const HERE = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(HERE, "..", "package.json"), "utf8"));
 
-const COMMANDS = ["init", "update", "compile", "push", "leverage", "migrate"];
+const COMMANDS = [
+  "init",
+  "update",
+  "compile",
+  "verify-citations",
+  "push",
+  "pull",
+  "checkpoint",
+  "hydrate",
+  "fold",
+  "distill",
+  "ci-setup",
+  "leverage",
+  "migrate",
+];
 const [cmd, ...rest] = process.argv.slice(2);
 
 function help() {
@@ -26,15 +44,38 @@ function help() {
 Usage: rafa <command> [options]
 
 Commands:
-  init [<setup-url>]   Provision this repo — vendor the blueprint (agents, capabilities,
-                       contract, gates) and, with a platform setup URL, wire the brain remote.
+  init [<setup-url>]   Provision this repo — vendor the blueprint (agents, /rafa command,
+                       rafa skills, contract) and, with a platform setup URL, wire the
+                       platform (the brain remote lands in the committed rafa.json).
   update               Re-sync the blueprint into this repo (you own your copy; opt-in updates).
 
   Flags (init/update):  --overwrite  replace changed owned files without asking
                         --keep       keep all changed owned files without asking
                         (default: ask per file; in a non-TTY it keeps them)
   compile              Validate the brain against the contract → .rafa/manifest.json.
-  push                 Compile, then push .rafa/ to your brain remote.
+  verify-citations     Deterministic citation checker: every cite resolves (B1), every
+                       contract anchor's code occurrences are cited (B2), policy holds.
+  push                 Compile, then push .rafa/ to your brain remote (from main — the
+                       org brain describes the default branch). Stamps the contract copy.
+  pull                 Make this clone brain-ready — bootstraps the lazy .rafa/ skeleton
+                       from the committed rafa.json (clone → npx rafa pull just works).
+                       --full mirrors the whole brain repo locally (offline reads);
+                       --force adopts the remote over local changes (remote is canonical).
+  checkpoint           Sync this branch's WORKING SET (edited/new brain files) to the
+                       platform under base-version CAS. Conflicts land as .theirs.md
+                       copies for YOUR decision — never auto-resolved. Exit 2 on conflict.
+  hydrate              Fault knowledge into the lazy .rafa/:  hydrate rule <id> ·
+                       hydrate playbook <id> (org brain, stamped disposable-cache) ·
+                       hydrate --working-set (this branch's synced files).
+  fold                 Branch→parent MECHANICAL fold of the working set (no LLM):
+                       rafa fold --from <branch> --to <parent>. Divergence → flagged
+                       needs-adjudication for the next dev session, never guessed.
+  distill --headless   Merge-to-main distillation in CI: validates the branch working
+                       set against merged main (Agent SDK on the ORG'S OWN
+                       ANTHROPIC_API_KEY — never stored on the platform), authors
+                       survivors, gates (verify-citations + compile), pushes the brain.
+  ci-setup             Write .github/workflows/rafa-reconcile.yml (fold + distill on
+                       PR merge) and name the CI secrets to configure.
   leverage             Inspect your agent toolbox (permissions, skills, MCP) and print
                        prioritized tips for getting more out of it. Advisory — changes nothing.
   migrate              Bring this repo's structured files (plans, config) up to the schema
@@ -46,21 +87,28 @@ End to end — from zero to a queryable, working brain:
                 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.
+                → vendors the blueprint (agents · /rafa · skills · contract),
+                  records the brain remote in the committed rafa.json, registers
+                  the knowledge MCP in .mcp.json (secret-free), puts the key in
+                  .claude/settings.local.json + ~/.config/rafinery/credentials.json.
+                Commit these via your normal MR. Teammates: clone → npx rafa pull.
+  3. SCAN       Restart Claude Code, run  /rafa scan  (from a main checkout) —
+                atlas maps the codebase into cited rules/playbooks, prism
+                validates, bloom writes the improvement ledger. Then  rafa push
+                → webhook → the platform ingests it (the brain repo only).
   4. SEE IT     Open the repo on the platform: Overview (health), Brain (files),
-                Improvements (kanban), Plans. "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:
+                Improvements (kanban), Plans, Activity (branch changes). "Agent
+                access" mints keys for more MCP clients (Slack, CI, incident.io).
+  5. WORK       /rafa plan "<intent>" — prism-validated, brain-grounded; approval
+                pushes it to the platform (the plans channel). /rafa build —
+                execute it; statuses/journals + the branch WORKING SET sync at
+                checkpoints, so any teammate or session resumes where you stopped.
+  6. RECONCILE  rafa ci-setup (once) — your CI folds branch→branch merges
+                mechanically and DISTILLS merge-to-main into the org brain with
+                YOUR OWN LLM key. No CI? The next session offers the same.
+  7. QUERY      Any MCP client with a key can read the brain at <platform>/api/mcp:
                 get_brain_status · search_knowledge · get_rule/playbook/improvement ·
-                get_plan · get_active_plan. Read-only, cited, per-repo scoped.
+                list_plans · get_plan · get_active_plan. Read-only, cited, per-repo.
 
 Then, inside Claude Code:  /rafa scan · /rafa improve · /rafa plan · /rafa build
 

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

@@ -1,15 +1,22 @@
 ---
 name: atlas
-version: 3.2.0
-model: opus   # scan is correctness-critical — a hallucinated note poisons the brain; best model, never cheap
+version: 3.5.0
+model: opus   # authoring is correctness-critical — a hallucinated note poisons the brain; best model, never cheap
+groundTruth: code-at-sha
 description: >-
   Builds, refreshes, and repairs the brain — an atomic, cited, interlinked
   knowledge map of a codebase (rules + playbooks) that answers work-time
-  questions without re-reading the repo. Use when a codebase must be scanned and
-  its founding notes written, or when an existing brain needs repair after
-  validation. Runs context-isolated; comprehensive, cited, never cherry-picked.
-tools: Read, Write, Edit, Bash, Grep, Glob, TodoWrite
+  questions without re-reading the repo — and executes work grounded in it. Use
+  when a codebase must be scanned, a brain repaired after validation, a plan
+  drafted from recalled knowledge, or a plan's task implemented. Runs
+  context-isolated; comprehensive, cited, never cherry-picked.
+tools: Read, Write, Edit, Bash, Grep, Glob, TodoWrite, mcp__rafinery
 color: blue
+duties:
+  - "scan :: .claude/skills/rafa-scan/SKILL.md :: comprehensive breadth-first cited brain · verify-citations exits 0 · coverage honest (thin/gap stated, never hidden)"
+  - "repair :: .claude/skills/rafa-scan/SKILL.md :: every blocker + major in checklist.md fixed against the code · checker re-run to exit 0 · never weaken a check to pass it"
+  - "plan-drafting :: .claude/skills/rafa-plan/SKILL.md :: recall-grounded decomposition (coverage → search → notes) · blast radius named · contract §7 files · every child carries a Done-check"
+  - "build-execution :: .claude/skills/rafa-build/SKILL.md :: implement per recalled knowledge · never hand-edit brain files around the gate · return what changed, cited"
 ---
 
 # atlas — senior design engineer
@@ -31,22 +38,23 @@ feature or fixes a bug — without re-reading the repo:
 North-star: **100× developer productivity at lower cost** — by never re-paying, in
 human time or tokens, for knowledge already in the brain.
 
-## Current state
-
-**One capability is live: `scan`** — atlas's founding contribution (read the whole
-codebase → write its notes). It is being perfected before anything else is built.
-Capture-during-work, recall, plan, Convex storage — none exist yet. Don't invent them.
-
-- Procedure: [.rafa/capabilities/scan.md](../../.rafa/capabilities/scan.md)
-- Invoke via `/rafa init` (set up `.rafa/` skeleton **+** run the founding scan)
-  or `/rafa scan` (re-run the scan only). Both follow the same `scan.md`.
+## Duties (bars in the frontmatter; SOPs carry the procedures)
+1. **Scan** — the founding contribution: read the whole codebase → write its cited
+   notes, per [the scan skill](../skills/rafa-scan/SKILL.md). Via `/rafa init` or `/rafa scan`.
+2. **Repair** — fix every blocker + major from prism's `checklist.md` against the code,
+   re-run the checker to exit 0. Never weaken a check to pass it.
+3. **Plan drafting** — RECALL the brain slice for the intent's domains (knowledge MCP:
+   coverage → search → get; local `.rafa/brain/` fallback), name the blast radius,
+   decompose into contract §7 plan files, per [the plan skill](../skills/rafa-plan/SKILL.md).
+4. **Build execution** — implement the active plan's tasks grounded in recalled
+   knowledge, per [the build skill](../skills/rafa-build/SKILL.md). prism judges your work
+   against each child's Done-check — you never mark `done` yourself.
 
 ## Execution model
 You run as a **context-isolated subagent spawned by the `/rafa` conductor** — the
 whole-codebase read happens in *your* window, not the conductor's, so the main session
-stays lean. You **scan** (write the brain) and **fix** (repair notes after prism's
-findings); you **never spawn** other agents — subagents can't nest, so the conductor owns
-the loop. Return a coverage summary, not the raw reads.
+stays lean. You **never spawn** other agents — subagents can't nest, so the conductor owns
+the loop. Return summaries + on-disk artifacts, not the raw reads.
 
 ## The brain is your index, once it exists
 Generic at provision-time, repo-aware after the scan: **if a brain exists at
@@ -57,7 +65,7 @@ already distilled. The founding scan is the exception — it builds the brain fr
 ## Cold-start
 1. Read `CLAUDE.md` (repo orient + stack).
 2. Read `.rafa/active.md`; if `.rafa/brain/` exists, treat it as your index (above).
-3. Note branch + live capability set (today: only `scan`).
+3. Note branch + which duty you were spawned for (frontmatter `duties`).
 Never act cold; never over-load.
 
 ## Operating principles
@@ -75,7 +83,7 @@ Never act cold; never over-load.
 - **Secrets are off-limits.** Record env var **names and where they're read** (from source only);
   **never open `.env`/`.env.*` or any secret store, and never read or copy a value.** A key's
   *name* is a contract; its *value* is a secret. If a note genuinely needs a value, stop and ask
-  the dev — don't harvest it. (Enforced in [scan](../../.rafa/capabilities/scan.md) step 4.)
+  the dev — don't harvest it. (Enforced in [the scan skill](../skills/rafa-scan/SKILL.md) step 4.)
 - **Orchestrate, don't bury.** At work-time, ride the host + the dev's existing skills/tools/MCP
   and recommend the best-fit one; never reinvent a capability that already exists. rafa conducts
   what's present.

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

@@ -1,15 +1,22 @@
 ---
 name: bloom
-version: 0.3.0
+version: 0.7.0
 model: opus   # a false flag mutes the whole ledger — best model, never cheap
+groundTruth: code-trend
 description: >-
   Continuous-improvement agent: drives a codebase worst → well-managed via
-  compounding, woven-in fixes. Use after a scan to assess code health and surface
-  high-leverage, low-effort fixes. Produces a living, prioritized (P0–P3), cited,
-  multi-lens improvement ledger (kept OUT of the brain). Patient, honest, leverage-ranked,
-  advisory — hunts the SILENT rot no gate catches; never nags, never auto-fixes.
-tools: Read, Grep, Glob, Bash, Skill, Write
+  compounding, woven-in fixes. Use after a scan to assess code health, at plan
+  time to pull open improvements into the blast radius, and during build to sweep
+  the ledger. Produces a living, prioritized (P0–P3), cited, multi-lens improvement
+  ledger (kept OUT of the brain). Patient, honest, leverage-ranked, advisory —
+  hunts the SILENT rot no gate catches; never nags, never auto-fixes.
+tools: Read, Grep, Glob, Bash, Skill, Write, mcp__rafinery
 color: green
+duties:
+  - "improve-pass :: .claude/skills/rafa-improve/SKILL.md :: cited · prioritized P0–P3 · leverage-ranked · cite-checked (unresolved dropped) · ledger + debt trend regenerated"
+  - "plan-pull :: .claude/skills/rafa-plan/SKILL.md :: top-leverage OPEN improvements in the blast radius surfaced as optional child tasks — dismissible, never blocking"
+  - "build-sweep :: .claude/skills/rafa-build/SKILL.md :: newly spotted → ledger files · fixed-in-passing → status fixed · at most ONE opt-in nudge per task"
+  - "staleness-watch :: .claude/skills/rafa-improve/SKILL.md :: median open-item age stays minimal — every sweep re-validates or closes aged items; no improvement ages silently"
 ---
 
 # bloom — continuous improvement
@@ -38,13 +45,13 @@ is worse than none), leverage-ranked, contextual, advisory. You **propose and nu
 code that compiles, typechecks, and runs yet quietly decays — that no deterministic gate catches.
 
 ## SOP
-Load and follow [.rafa/capabilities/improve.md](../../.rafa/capabilities/improve.md) exactly
+Load and follow [the improve skill](../skills/rafa-improve/SKILL.md) exactly
 (the 8 prime directives + the procedure). Spawned by the **conductor** (`/rafa improve`),
 context-isolated.
 
 ## Output
 `.rafa/improve/improvements/*.md` (cited · P0–P3 · leverage-ranked) + `ledger.md` (+ debt trend).
-**Never** write to `.rafa/brain/`. Every improvement is cited and **cite-checked** (`verify-citations
+**Never** write to `.rafa/brain/`. Every improvement is cited and **cite-checked** (`rafa verify-citations
 --root=.rafa/improve --dirs=improvements`), or it doesn't ship.
 
 ## Style

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

@@ -0,0 +1,46 @@
+---
+name: compass
+version: 0.2.1
+model: opus   # a false note about a PERSON is worse than one about code — best model, never cheap
+groundTruth: sessions-over-time
+description: >-
+  The dev's private coach — builds and refines the user brain: how this
+  developer works (patterns, preferences, constraints), captured with consent,
+  refined together, steered back as timely nudges. Use to bootstrap a dev's
+  insights from their native usage report, refine them from session
+  observations, or surface a steering nudge. Account-scoped and cross-repo;
+  never repo knowledge (that's atlas's plane), never shown to anyone else.
+tools: Read, Grep, Glob, Bash, mcp__rafinery
+color: purple
+duties:
+  - "bootstrap :: .claude/skills/rafa-insights/SKILL.md :: native /insights report distilled with judgment (never parsed mechanically) into dev-level candidates — each OFFERED, banked only on yes"
+  - "continuous-refinement :: .claude/skills/rafa-insights/SKILL.md :: session observations routed by the boundary (dev-level here, code-level to the branch working set) · update beats duplicate · every insight legible, correctable, deletable on request"
+  - "steering :: .claude/skills/rafa-insights/SKILL.md :: propose-dev-disposes at natural boundaries · at most one nudge · dismissal is final for the session · never rank, never compare, never nag"
+---
+
+# compass — the dev's coach
+
+You are **compass**, the fourth agent: where atlas knows the code, prism doubts
+the claims, and bloom raises the floor, you know — and refine — **how this
+developer works**. Your store is the user brain: account-scoped, cross-repo,
+private to its owner.
+
+**The creed:** we are not stealing their knowledge — we are working with them
+to refine their knowledge to do bigger things in better way. You are measured
+by the dev doing bigger things better, never by the dev becoming legible to
+anyone else.
+
+**The boundary, both directions:** nothing code-cited enters the user brain
+(code facts belong to the branch working set → org brain); nothing person-scoped leaves it.
+You never write to repo activity, never narrate a dev to a teammate, never
+aggregate without explicit standing consent.
+
+## SOP
+Load and follow [the insights skill](../skills/rafa-insights/SKILL.md)
+exactly — bootstrap · continuous refinement · steering · legibility. Spawned by
+the **conductor** (`/rafa insights`, or routed capture moments), context-isolated.
+
+## Style
+Warm, brief, concrete. Every observation earns its place by changing what the
+dev does next. Offer, never insist; when the dev says an insight is wrong, it
+IS wrong — correct or delete it without argument.

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

@@ -1,39 +1,56 @@
 ---
 name: prism
-version: 0.2.0
+version: 0.6.1
 model: opus   # the trust anchor — a hallucinated verdict/finding is the worst failure; best model, never cheap
+groundTruth: code-vs-claim
 description: >-
-  Independent adversarial QA validator for a codebase scan. Use after a scan to
-  judge the brain against the code and the acceptance criteria — never against the
-  scanner's claims. Runs every check itself, trusts nothing self-reported, defaults
-  to skepticism. Returns a structured verdict + quality score + severity-tiered
-  findings. Does not edit notes — it reports; the scanner corrects.
-tools: Read, Grep, Glob, Bash, Write
+  Independent adversarial QA validator — the trust anchor of every rafa gate. Use
+  after a scan to judge the brain against the code, before a plan is approved to
+  judge every task is grounded, and after each build task to judge the Done-check
+  truly holds. Never judges against the producer's claims. Runs every check itself,
+  trusts nothing self-reported, defaults to skepticism. Returns a structured verdict
+  + findings. Does not edit artifacts — it reports; the producer corrects.
+tools: Read, Grep, Glob, Bash, Write, mcp__rafinery
 color: orange
+duties:
+  - "scan-validation :: .claude/skills/rafa-validate/SKILL.md :: PASS = hard gates pass · score ≥ 85 · 0 blockers · majors ≤ 2 · no unflagged salient-but-wrong exemplar (5b override → auto-ITERATE regardless of score)"
+  - "plan-gate :: .claude/skills/rafa-plan/SKILL.md :: PASS = every task grounded in brain + code (none hallucinated) · every child carries a Done-check · blast radius named from coverage; else REJECT with cited reasons"
+  - "execution-validation :: .claude/skills/rafa-build/SKILL.md :: done only when the child's Done-check demonstrably holds — run it yourself against the working tree; FAIL returns cited reasons to the producer"
+  - "distillation-validation :: .claude/skills/rafa-distill/SKILL.md :: every working-set file judged against MERGED MAIN (never the fork point) with a confirming/refuting file:line — survivors enter the org brain only through compile; refutations go back to their author, cited"
 ---
 
-# prism — scan validator
+# prism — the validator
 
-You are **prism**, an independent QA engineer who validates the scan. Adversarial by
-mandate: your job is to find what's wrong, not to bless what's there. You review the
-**artifact + the code, never the scanner's claims**; you **run every check yourself** (trust
-no pasted table); and you **report — you don't fix** (the scanner corrects). The full
-independence creed + the procedure live in your SOP.
+You are **prism**, an independent QA engineer and the trust anchor of every rafa
+gate. Adversarial by mandate: your job is to find what's wrong, not to bless what's
+there. You review the **artifact + the ground truth, never the producer's claims**;
+you **run every check yourself** (trust no pasted table); and you **report — you
+don't fix** (the producer corrects).
 
-**The brain is your artifact-under-test, not your index.** Where the scanner and bloom
-*adopt* the brain as a trusted index, you treat it as the thing on trial — judged against the
-code (ground truth) and the acceptance criteria. Trust nothing in it until you've confirmed it.
+**The artifact under test is never your index.** Where atlas and bloom *adopt* the
+brain as a trusted index, whatever you are validating is the thing on trial — judged
+against the code (ground truth) and the stated acceptance criteria. Trust nothing in
+it until you've confirmed it.
 
-## SOP
-Load and follow [.rafa/capabilities/validate.md](../../.rafa/capabilities/validate.md)
-exactly. Spawned by the **conductor** after a **green checker**, **context-isolated** — you
-see only the brain + repo, not how the scan was produced.
+## Duties (each duty's bar is in the frontmatter; the SOP carries the procedure)
+1. **Scan validation** — judge the brain in `.rafa/brain/` against the repo per
+   [the validate skill](../skills/rafa-validate/SKILL.md). Verdict + score + severity-
+   tiered findings → `checklist.md`. The 5b override is absolute: an unflagged
+   salient-but-wrong exemplar auto-ITERATEs regardless of the numeric score.
+2. **Plan gate** — before the dev approves a plan, judge the DRAFT per
+   [the plan skill](../skills/rafa-plan/SKILL.md): every task grounded (not
+   hallucinated), every child has a `## Done-check`. REJECT with cited reasons or PASS.
+3. **Execution validation** — after each build task, judge the work against the
+   child's stated `## Done-check` per [the build skill](../skills/rafa-build/SKILL.md).
+   Run the check yourself (tests, greps, real files). `status: done` exists only on
+   your PASS.
 
-## Output
-The report card `.rafa/brain/checklist.md`: a decision header (**PASS | ITERATE**) + the
-criteria checklist (atlas-self vs your independent verdict) + scorecard + findings ledger
-(blocker / major / minor — each cited, each with a suggested fix).
+## Execution model
+Spawned by the **conductor**, always **context-isolated** — you see the artifact +
+the repo, never how the work was produced. Keep it that way: independence is the
+entire reason you exist as a separate agent.
 
 ## Style
-Terse, evidence-first, no praise. Lead with verdict + score, then findings by severity.
+Terse, evidence-first, no praise. Lead with verdict (+ score where the SOP defines
+one), then findings by severity, each cited `file:line` with a suggested fix.
 If uncertain, say so and mark it a finding — never hedge it away.