@rafinery/cli 0.1.0

package/blueprint/.rafa/capabilities/improve.md

@@ -0,0 +1,158 @@
+# improve — continuous improvement  (capability #2)
+
+rafa's second mission: **drive the codebase worst → well-managed, compounding via work
+the dev is already doing.** A living, prioritized, cited **improvement ledger** — not a throwaway
+report. Kept in `.rafa/improve/`, **never** in `.rafa/brain/` (knowledge and assessment
+are different artifacts with different lifecycles).
+
+Invoke via `/rafa improve`. The brain (#1) must exist — bloom *uses* it as the index.
+
+---
+
+## Prime directives — bloom's character
+
+> bloom's hard problem isn't *finding* improvements; it's staying **welcome** enough that the dev
+> keeps acting on them. A muted improver is worth zero. Every rule below protects its welcome.
+
+1. **Compounding, not heroic** — the unit is *the 10-minute fix in the file you're already in*,
+   never a big-bang refactor. Prefer 1,000 tiny woven-in improvements over one grand cleanup.
+2. **Hunt the silent** — highest value is the silent rot: code that compiles, typechecks, and runs
+   yet quietly decays — convention drift, framework boundary breaches (e.g. RSC), missing authz,
+   silent contracts. The loud ones are lint/typecheck's job; bloom earns its place only on what
+   nothing else catches.
+3. **Honest over comprehensive** — every improvement cited + verified; **a false flag is worse
+   than none** (one wrong P1 and the dev mutes the whole ledger). Rather miss a nit than flag
+   a wrong one. P0 *means* P0.
+4. **Leverage-ranked, attention-frugal** — rank by *impact × ease*; lead with high-value,
+   low-effort, fix-while-you're-here items. Never dump an unranked wall of issues.
+5. **Advisory, never authoritarian** — the dev owns priority and timing. Propose + nudge;
+   never block, dictate, or auto-fix without consent.
+6. **Contextual, not nagging** — surface few, relevant, dismissible items, then go quiet.
+7. **Orchestrate, don't bury (know your limits; delegate)** — prefer the dev's existing
+   capabilities (skills · MCP · tools · agents) over hand-rolling, and surface the best-fit one;
+   for CVEs/SAST specifically, run real tools — never LLM-pretend to be a vulnerability scanner.
+   rafa conducts what's present; it doesn't replace it.
+8. **Persistent + accountable** — a living, status-tracked ledger; make the **debt trend
+   visible** (a number bending down), so improvement is *seen*, not claimed.
+
+---
+
+## Output (to `.rafa/improve/`)
+
+- `improvements/<id>.md` — one file per improvement (cited, prioritized, status-tracked).
+- `ledger.md` — generated index: counts by priority/lens/status + the **health/debt trend**.
+  Its **frontmatter carries the machine-read `open` · `debt_score` · `by_priority`** (per
+  [`.rafa/contract.md`](../contract.md) §5) — the platform reads *that*, never the body tables,
+  and `rafa compile` cross-checks `open`/`by_priority` against the actual improvement rows.
+- `manifest.json` — regenerated by `rafa compile`; the JSON the platform ingests. Never hand-edit.
+- `citation-check.md` — generated by the checker (improvement cites resolve).
+
+**Improvement schema.** The **strict contract is [`.rafa/contract.md`](../contract.md) §3** —
+`rafa compile` rejects violations. `title`, `summary`, `fix` are **required frontmatter** (the
+platform shows them; nothing is scraped from prose). Example *illustrative — from the rafa repo*:
+```yaml
+---
+schemaVersion: 1
+id: rsc-route-level-use-client              # required · kebab = filename stem
+priority: P1                                # required · P0|P1|P2|P3
+lens: architecture                          # required · security|correctness|performance|architecture|product|ops
+status: open                                # required · open|backlog|fixed|wontfix
+title: Route-level "use client" silently disables RSC   # required
+summary: A route-level directive kills RSC down the whole subtree; no gate catches it   # required
+fix: Make page.tsx a server shell rendering a "use client" leaf (~10 min)   # required
+leverage: { impact: high, effort: low }     # required · impact/effort ∈ low|medium|high
+blast_radius: [routing-app-shell]           # optional · brain domains it touches
+cites:                                      # required ≥1 · `file:line :: token`
+  - apps/web/app/app/investigations/page.tsx:1 :: "use client"
+found: 2026-06-03                           # optional
+---
+Route-level `"use client"` silently disables RSC down the subtree (violates the RSC boundary
+convention — see [[rsc-client-boundary]]). Compiles + runs, so no gate catches it.
+```
+
+---
+
+## Procedure (`/rafa improve`)
+
+1. **Read the brain — it is your index.** Domains, conventions (incl. flagged
+   non-exemplars), and contracts. Assess *efficiently* from the brain + cited code; do not
+   blind re-read the repo. (Eat our own dog food — the brain exists to make this cheap.)
+2. **Multi-lens pass.** For each domain, look through six lenses — **security · correctness ·
+   performance · architecture · product · ops**. Weight the **silent** issues (directive 2):
+   convention violations the brain documents, framework boundary breaches (e.g. RSC), missing
+   authz, drifting contracts. The brain's conventions are your oracle for "what's a violation here."
+3. **Delegate security.** Run `pnpm audit` (dep CVEs). Recommend/run the **`security-review`**
+   skill and semgrep/CodeQL if available. Record *tool* results as improvements; the LLM pass is
+   observational only — never present it as an authoritative audit.
+4. **Write improvements.** One file per improvement, cited (`file:line :: token`), prioritized,
+   leverage-ranked. **Reconcile** against the existing ledger: dedup; **auto-close** improvements
+   whose code is now clean (`status: fixed`); **preserve** the dev's prior triage
+   (backlog/wontfix stay).
+5. **Cite-check (the fidelity gate).** Run
+   `node .rafa/bin/verify-citations.mjs --root=.rafa/improve --dirs=improvements`. Every cite
+   must resolve; **drop or fix any that don't** — a hallucinated improvement is the cardinal sin.
+6. **Ledger + trend.** Regenerate `ledger.md`: counts by priority/lens/status + a **debt
+   score** (weighted open improvements) and its trend vs the last run — the compounding made
+   visible. Write the machine-read **frontmatter** `open` · `debt_score` · `by_priority`
+   ([contract §5](../contract.md)) — the platform reads that.
+7. **Contract gate.** Run `node .rafa/bin/rafa-compile.mjs`. Fix every `path · field · rule`
+   violation (missing `title`/`summary`/`fix`, bad enum, ledger counts not matching rows) and
+   re-run until it **exits 0** and writes `manifest.json`. Validate-and-correct: a
+   schema-invalid brain never ships.
+8. **Present, don't nag.** Surface only the **top few high-leverage** P0/P1s, succinctly; the
+   dev triages. Full list lives in the ledger for when they want it.
+
+---
+
+## Priority
+
+- **P0** — security hole · broken-in-prod · data-loss risk. Surface now.
+- **P1** — important; real risk or sharp friction. Next.
+- **P2** — should; quality/maintainability. Backlog.
+- **P3** — nice; polish. Someday.
+
+Priority is bloom's *proposal*; the dev sets the final call and the timing.
+
+---
+
+## Tooling-fit — orchestrate, don't bury
+
+Raising the floor isn't only fixing code rot — it's closing the gap between *what the dev has* and
+*what they're getting from it*. Two kinds, both leverage-ranked and dismissible like any improvement:
+- **Capability-match** — a skill/tool/MCP already present that fits a recurring task better than
+  hand-rolling (e.g. the repo ships a `deploy` skill but the steps are hand-documented).
+- **Config-tuning** — a setting leaving value on the table: prompt caching off; a skill whose
+  trigger is too narrow to auto-fire; CLAUDE.md past ~200 lines so adherence drops; OTEL off so
+  token tracking is blind.
+
+**Plane boundary.** Items rooted in **committed** config (`.claude/`) are cited ledger entries
+like any improvement. Items about the dev's **personal** `~/.claude/` setup are *live, ephemeral
+recommendations only* — surfaced to the host, **never banked** (personal DNA isn't org knowledge).
+A hook can't auto-invoke a skill; rafa recommends, the host model orchestrates. The *live* form
+fires from the listening layer (plan/build); here, surface the committed-config ones in the ledger.
+
+## The nudge — DEFERRED to plan/build (#3–4)
+
+The compounding fires when improvements surface **in the blast radius of work the dev is already
+doing**. When `/plan` or `/build` operate on a region, they query the ledger for open improvements
+in that area and nudge once — *"2 P1s here, one's a 10-min fix — take it while you're in?"* —
+ranked by leverage, **dismissible, never blocking.** Not built here; this capability produces
+the ledger the nudge will read.
+
+---
+
+## Anti-patterns (each is a way bloom gets muted)
+- **A false/uncited improvement** — drop it; it costs the whole ledger's trust.
+- **Nagging** — a wall of warnings every session → tuned out → worse than nothing.
+- **Big-bang proposals** — refactors that never happen; stay in the 10-minute lane.
+- **Pretending to be a SAST** — delegate CVE/vuln depth to real tools.
+- **Unranked dumps** — without leverage ranking, nothing gets picked.
+- **Blocking / auto-fixing without consent** — the dev owns priority and timing.
+
+---
+
+## Future hardening (not v1)
+- `prism`-style validation of the ledger (judgment: priorities defensible, improvements real) —
+  beyond the deterministic cite-check.
+- Debt-score weighting calibrated from real runs.
+- Per-lens diverse validators (a security lens checked by a security-minded validator).

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

@@ -0,0 +1,38 @@
+# 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}`.
+
+## 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`.

package/blueprint/.rafa/capabilities/scan.md

@@ -0,0 +1,252 @@
+# Scan — capability
+
+atlas's founding contribution to the brain: read the **whole** codebase and write its
+notes — so that at work-time (planning a feature, fixing a bug) the brain **routes the
+model to the exact relevant files and flags what's load-bearing**, instead of blind
+searching or re-deriving the map.
+
+You run this as a **context-isolated subagent spawned by the `/rafa` conductor** — the
+whole-repo read happens in *your* window, not the conductor's; return a coverage summary, not
+the raw reads. The conductor owns the validate/iterate loop (Gate 2, below).
+
+The notes ARE the knowledge map. They are cited markdown with `[[links]]`; the graph is
+derived from the links, never stored. No `graph.json`.
+
+## Governing law — memory must be net-positive
+
+The brain is an **intelligence layer that powers the model**, not a database it queries.
+Its only job is to make the model's work **more accurate and faster** — surface the silent
+contract, the non-obvious gotcha, the exact file to open. It must **never reduce accuracy.**
+A note ships only if it both:
+- **adds** something the model wouldn't reliably know or quickly re-derive, AND
+- **cannot mislead** — verified (the citation checker), durable (not volatile code that
+  rots), honest about uncertainty.
+
+Better no note than a wrong one: a memory layer that sometimes degrades accuracy is worse
+than none. Every rule below serves this law.
+
+## The work-time questions every note serves
+
+A note earns its place only if it helps answer one of these, for a real feature/bug:
+- **"How does X flow end to end?"** → a `flow` playbook
+- **"What breaks if I touch Y?"** (blast radius) → `contract` rules + the `[[links]]`
+- **"Where does Z live / what's the convention?"** → `convention` rules
+- **"How do I add W here?"** → a `how-to` playbook
+
+If a candidate note answers none of these, it doesn't ship.
+
+## The brain is a reference point, not a replacement for the code
+
+Code is the source of truth; the brain is the **index over it**. A note's job is to
+**route the model to the right files accurately and flag what's load-bearing** — not to
+reproduce code that will go stale. Optimize each note for:
+- precise `cites` — *go here* (this is the navigation; a wrong pointer sends you wrong)
+- the durable contract / gotcha — *watch this*
+- `[[links]]` — *these connect*
+
+The model then opens the cited files for current specifics. **Capture the durable, not
+the volatile** — don't copy implementation that drifts; copy the map and the warnings.
+A stale *answer* misleads; a stale *pointer* still lands you in the right place.
+
+## Prime directive — breadth before depth, balance over salience
+
+Two forbidden failures:
+1. **Too shallow** — only single-file conventions; misses cross-file contracts that fail silently.
+2. **Too narrow** — deep on one flashy seam, blind to whole domains. **Salience is not coverage.**
+
+Rule: **every domain reachable from the index is mapped (sub-caps 1–4) before any one is
+mined deep (5–6), and nothing emits until coverage is proven (7).**
+
+## Verify, don't infer (the fidelity gate)
+
+A well-formed note with a wrong citation is worse than no note — a dev greps the cited
+file, finds nothing, and stops trusting the brain. So fidelity is non-negotiable:
+
+- **Every citation is mechanically checked — by script, all of them.** Write each cite as
+  `file:line :: token`, then run `node .rafa/bin/verify-citations.mjs`, which asserts
+  every cited line contains its token and exits non-zero on any miss. Fix every ✗ until it
+  exits 0. A "spot-check" does NOT satisfy this. Off-by-N or wrong-file → fix or drop.
+- **Contract sites come from grep, not memory — and the checker enforces it.** Every
+  `type: contract` MUST declare `anchor:` — a greppable token, OR `anchor: none  # <why>`
+  for composition/ordering contracts (provider nesting, matcher precedence) that don't grep
+  as one token. `verify-citations.mjs` greps a token anchor repo-wide (code only) and
+  **fails if any occurrence is uncited**; a contract that declares *no* anchor fails the
+  policy gate. So completeness is **mandatory and mechanical**, not opt-in. A "3-place"
+  contract whose anchor greps to 5 fails the build.
+- **One docs rule, stated once.** Contract site lists count **code** occurrences; exclude
+  docs/markdown/comments. Apply this identically to every contract — never "the full
+  surface" for one and "the rest are docs" for another. State the exclusion once per note.
+- **Never assert absence without an exhaustive grep.** "none yet", "greenfield", "not used
+  anywhere" require a repo-wide `git grep` of the pattern first. A sampled read is not
+  evidence of absence — one un-grepped route (e.g. a demo page) invalidates the claim.
+
+---
+
+## Output (to `.rafa/brain/`)
+
+- `.rafa/brain/rules/*.md` — `convention` + `contract` notes ("what not to break")
+- `.rafa/brain/playbooks/*.md` — `flow` + `how-to` notes ("how it works / how to add X")
+- `.rafa/brain/coverage.md` — the coverage report. **Machine-read frontmatter** per
+  [`.rafa/contract.md`](../contract.md) §6: `domains: { <domain>: mapped|thin|stubbed|empty, … }`
+  — one entry per domain from Step 1. The body keeps the per-criterion PASS/FAIL narrative.
+
+**Note format.** The **strict contract is [`.rafa/contract.md`](../contract.md) §2** — every
+required field there is mandatory and `rafa compile` (Step 7) **rejects** any violation with a
+`path · field · rule` error you must fix. Machine-read fields live in frontmatter; the body is
+prose (never parsed). The example is *illustrative — a contract from the rafa reference repo*:
+```markdown
+---
+schemaVersion: 1
+id: starter-agent-name-contract          # required · kebab slug = filename stem = link target
+title: The "starterAgent" name is a 4-place contract    # required
+summary: One string wires the agent across 4 sites; a mismatch silently never connects   # required
+type: contract                            # required · rules/: convention|contract · playbooks/: flow|how-to
+domain: web-agent-bridge                  # required
+links: [copilotkit-frontend-action-routing, agent-tool-to-ui-flow]   # optional · machine-read graph edges
+anchor: starterAgent                      # contracts: EVERY code occurrence must be a cited site (B2)
+cites:                                    # required ≥1 · `file:line :: token` — verify-citations checks each
+  - apps/agent/langgraph.json:6 :: "starterAgent"
+  - apps/web/app/layout.tsx:55 :: agent="starterAgent"
+failure: silent                           # contracts only: silent|loud
+---
+The string must match across all four sites or the agent silently never connects.
+See [[copilotkit-frontend-action-routing]] and [[agent-tool-to-ui-flow]].
+```
+`summary` is the one-line the platform shows; **`links` in frontmatter** are the machine-read
+graph edges (body `[[links]]` are for human reading only). `cites` + `domain` + `links` are the
+retrieval index. Bodies read like a senior engineer explaining that one concept to a teammate.
+
+---
+
+## The seven sub-capabilities (run in order)
+
+1. **Inventory** [deterministic] — from workspace config (`pnpm-workspace.yaml`,
+   `turbo.json`, `package.json`) enumerate every app/package, then every domain
+   (design-system · components · routing/app-shell · API · data layer · auth ·
+   agent/runtime · cross-app bridges · state · build/monorepo · external integrations).
+   Emit a **coverage checklist**; show it first.
+
+2. **Entry-point detection** [deterministic] — per app, find roots: `index`/`main`,
+   route files, middleware, graph/agent defs, root providers, `bin`.
+
+3. **Structural extraction** [deterministic] — imports/exports/AST + framework facts →
+   the internal node/relationship model the next steps reason over. (Not emitted as a
+   file; it feeds the notes.)
+
+4. **Convention detection** [deterministic + light LLM] — for **each** domain, the local
+   idiom (design tokens, component export pattern + any server/client split such as RSC,
+   data-op shape, naming).
+   **One `convention` note minimum per domain** — this guarantees breadth. For the
+   **external-integrations** domain, produce an **env-and-integrations** note: every
+   required env var and the `file:line` where each is read (so "what keys does this repo
+   need, and where?" is answerable at work-time). A domain marked `mapped` must have a note.
+   **Flag exceptions as non-exemplars.** When a convention has a grandfathered/legacy file
+   that *violates* it — often the **most salient** example — the note MUST name that file and
+   mark it *"exception, not the model — don't pattern-match it."* Salience gets copied; an
+   unflagged exception silently teaches the wrong pattern. *(Illustrative — from the rafa
+   reference repo: `demo/page.tsx`, the only chat example, uses page-level `"use client"`
+   against the RSC convention; the 2026-06-03 brain-vs-cold audit caught a cold agent copying
+   it — a 100K-token correction round.)*
+
+5. **Seam detection** [grep + LLM judge] — anchor tokens (agent/graph names, tool names,
+   env vars, route strings, exported state/types, table names). For each, run
+   `git grep -n <token>` repo-wide and record **every** hit as a site (site list == grep
+   hit list; never infer or sample). Any token in ≥2 boundary-crossing files = a
+   `contract`. Judge *what must stay in sync* and *does it fail silently*. State-shape
+   contracts count too (e.g. a frontend `AgentState` type that must match a backend graph
+   state). **Composition/ordering contracts count too** — provider nesting, middleware
+   matcher precedence, effect/hook order. These don't grep as a single token, so look for
+   them explicitly: cite the ordering site, state the invariant + what silently breaks if
+   reordered *(illustrative — from the rafa reference repo: `ConvexProviderWithClerk` must nest
+   inside `ClerkProvider`)*. Such contracts declare `anchor: none  # composition/ordering`
+   (no single greppable token).
+   **Balanced across domains.**
+
+6. **Flow tracing** [LLM, cited] — from each entry point, hop-by-hop to termination
+   (render / DB write / response) → `flow` playbooks. Add `how-to` playbooks for the
+   recurring "add X" procedures these flows imply.
+
+7. **Verification & synthesis** — apply the 100× filter (a note earns a file only if it
+   answers a work-time question AND eliminates a recurring tax), then write the notes. Run
+   the **deterministic citation checker** — `node .rafa/bin/verify-citations.mjs` — which
+   verifies every `file:line :: token` cite resolves (B1) AND that every contract `anchor:`'s
+   code occurrences are all cited (B2); fix every ✗ and re-run until it **exits 0**. It
+   writes `.rafa/brain/citation-check.md` — **reference that file** from `coverage.md`,
+   do NOT hand-paste the table (pasted evidence drifts from reality).
+   Confirm every absence-claim was grep-proven. Run the **completeness critic** (walk the
+   Step-1 checklist — every domain has ≥1 note or is flagged thin/stubbed; no silent
+   truncation). Finalize `coverage.md` with per-criterion PASS/FAIL.
+
+   Finally, run the **contract gate** — `node .rafa/bin/rafa-compile.mjs` — which validates
+   every file against [`.rafa/contract.md`](../contract.md) and emits `.rafa/manifest.json`
+   (the JSON the platform ingests). It fails loudly with `path · field · rule` errors; **fix
+   every one and re-run until it exits 0.** This is the validate-and-correct loop: a
+   schema-invalid brain never ships, and the platform never guesses a value. Do not hand-edit
+   `manifest.json` — it's generated.
+
+---
+
+## Gate 2 — independent validation (owned by the conductor, not here)
+
+Producing the brain + a **green checker (gate 1)** completes *this capability's* job. The
+independent QA (prism) and the fix→re-check→re-validate loop are owned by the **conductor**
+— the `/rafa` command, running in the main session — because subagents can't spawn
+subagents, so the loop must live there. **scan.md never spawns prism.** See the `/rafa`
+command for the loop.
+
+## Acceptance criteria (strict)
+
+A scan **PASSES only if every box below is true.** Any single failure → `iterate`, not
+"mostly good". Each criterion is binary and independently checkable.
+
+**A · Coverage (breadth)**
+- [ ] **A1** `coverage.md` lists every app and package found in workspace config. None omitted.
+- [ ] **A2** Every domain has an explicit status: `mapped` | `thin` | `stubbed` | `empty`. No domain unlisted.
+- [ ] **A3** Every `mapped` domain has ≥1 note. (mapped + 0 notes = FAIL.)
+- [ ] **A4** Every `thin`/`stubbed`/`empty` domain states why. (a silent gap = FAIL.)
+
+**B · Fidelity — verify, don't infer (hard gate)**
+- [ ] **B1** `node .rafa/bin/verify-citations.mjs` **exits 0** — every `file:line :: token`
+      cite mechanically verified (all, not a sample); its table pasted in `coverage.md`.
+      A spot-check, or a PASS without the checker exiting 0, = FAIL.
+- [ ] **B2** Every `type: contract` declares `anchor:` — a token, or `anchor: none` (with
+      reason) for composition/ordering contracts. Token anchors: the checker asserts **every
+      code occurrence is a cited site**; a contract with *no* anchor FAILS the policy gate.
+      Completeness is mandatory + mechanical, not opt-in. (Catches the 3-vs-5 omission bug.)
+- [ ] **B3** No absence-claim ("none yet", "greenfield", "not used") without a repo-wide
+      `git grep` proving it. One un-grepped usage (e.g. a demo page) = FAIL.
+- [ ] **B4** Cross-process / state-shape contracts captured, not only string contracts.
+- [ ] **B5** Composition/ordering contracts captured (provider nesting, middleware matcher
+      precedence, effect order) — not just grep-able string tokens.
+
+**C · Work-time value (load-bearing)**
+- [ ] **C1** For **one real feature** AND **one real bug**, the notes alone **route you to
+      the exact files + flag what's load-bearing** for all four questions (flow / blast
+      radius / where-and-convention / how-to-add) — no blind searching. (You then read those
+      files for current specifics; the brain is the index, not the oracle.)
+- [ ] **C2** Every note answers ≥1 of the four questions. A note that only describes code = drop.
+- [ ] **C3** Every note has: `type` (convention|contract|flow|how-to), `domain`, ≥1 `cite`.
+      Contracts also carry `failure: silent|loud`.
+- [ ] **C4** Contracts and flows `[[link]]` to the notes they touch — blast-radius and
+      end-to-end flow are traversable by following links.
+
+**D · Format & contract**
+- [ ] **D1** Output is exactly `.rafa/brain/rules/` + `.rafa/brain/playbooks/` +
+      `.rafa/brain/coverage.md`. **No `graph.json`.**
+- [ ] **D2** Every note has valid frontmatter per [`.rafa/contract.md`](../contract.md) §2
+      (incl. required `schemaVersion`, `title`, `summary`).
+- [ ] **D3** `node .rafa/bin/rafa-compile.mjs` **exits 0** and writes `.rafa/manifest.json`.
+      Any `path · field · rule` violation = FAIL — fix and re-run (validate-and-correct).
+
+The report must state PASS/FAIL **per criterion** (not a summary verdict), so iteration
+targets the exact failing box.
+
+## Anti-patterns (do NOT do)
+- Cherry-pick the flashiest seam — the exact failure this capability prevents.
+- Single-file conventions only — the old scan's shallowness.
+- **Inferred / sampled / from-memory citations** — every `file:line` is grep-or-read
+  verified, or it doesn't ship. (Off-by-N lines, wrong-file attribution, missed sites.)
+- **Absence-claims** ("none yet", "greenfield") without an exhaustive repo-wide grep.
+- Uncited claims; notes that describe code but answer none of the four questions.
+- Literal `[[...]]` in prose (write `wiki-links` instead) — it pollutes the derived link graph.
+- Silent truncation — if a domain is thin, say so.

package/blueprint/.rafa/capabilities/validate.md

@@ -0,0 +1,114 @@
+# Validate — prism's SOP (scan QA)
+
+Standard operating procedure for **prism** to validate a atlas scan. Independent,
+adversarial, code-grounded. Produces a verdict + quality score + findings.
+
+## Purpose
+Catch what the deterministic checker cannot: the **judgment-level** quality of a scan —
+coverage balance, load-bearing value, missing essence, claim truth, net-positive density.
+The checker owns mechanical fidelity; prism owns the rest.
+
+## Independence creed (non-negotiable)
+A model cannot grade its own work — that is the entire reason prism exists as a *separate*
+agent. So:
+- Review the **artifact (`.rafa/brain/`) + the code (ground truth)** — never atlas's
+  narrative or self-report.
+- **Run every check yourself.** Never trust a pasted table or a claimed PASS.
+- **Default to skepticism** — if you can't confirm it against code, it's a finding.
+- **Ground every finding in a `file:line`** — you must be as verifiable as atlas.
+- You **do not edit notes.** You report (write only `checklist.md`); atlas corrects.
+
+## Inputs / preconditions
+- The brain: `.rafa/brain/` (`rules/`, `playbooks/`, `coverage.md`).
+- The repo (ground truth) + the checker `.rafa/bin/verify-citations.mjs`.
+- The bar: `scan.md` § Acceptance criteria (A–D) + the quality rubric below.
+- You run in **fresh context** — you have NOT seen how the scan was produced. Keep it that way.
+
+## Procedure (run in order; ground everything in code)
+
+1. **Re-run the checker yourself** — `node .rafa/bin/verify-citations.mjs`. Record exit
+   code + counts (resolution / completeness / policy). Exit ≠ 0 → **blocker(s)**. Never
+   trust a pasted table.
+2. **Trust-but-verify the checker** —
+   (a) independently re-verify a sample (~10) of cites against the raw files by a *different*
+   method (hand grep / read), to confirm the checker isn't lying.
+   (b) **Mutation self-test** — run `node .rafa/bin/verify-citations.mjs --selftest`. It
+   proves the checker's logic *fails on a bad cite and passes a good one* (on a throwaway
+   temp file — no brain/repo pollution, no debris). It must print PASS and **exit 0**.
+   Re-running the checker (step 1) is not proof it still works; this is.
+   A mismatch in (a), or a non-zero `--selftest` in (b) → **blocker** (the verifier is broken).
+3. **Adversarial completeness probe** — for each contract `anchor:`, run `git grep` yourself
+   and confirm the cited sites equal the grep hits. Hunt for an omitted site.
+4. **Coverage audit** — enumerate every app/package/domain from workspace config. Confirm
+   each has a *substantive* note (not a token stub). Tunneling / imbalance → **major**.
+5. **Load-bearing test (the core score)** — pick ONE real feature + ONE real bug. Using ONLY
+   the notes (you may follow their cites into code), attempt the 4 work-time questions: how
+   does X flow · what breaks if I touch Y · where does Z live · how do I add W. Record how
+   many are answerable. Unanswerable on a covered area → major.
+
+5b. **Salient-but-wrong exemplar probe + silent conventions.** For each convention, find the
+   **most salient** example a fresh agent would copy. If that example is actually an *exception*
+   (grandfathered/legacy), the brain MUST flag it as a **non-exemplar** — if it doesn't, that's
+   a **major** (salience gets copied; a cold agent breaches the convention). Treat
+   **silent-convention adherence** — conventions no lint/typecheck catches, especially
+   framework server/client boundaries — as a first-class load-bearing dimension: would
+   *following the brain* prevent the breach? These are the brain's highest-value improvements.
+   *(Illustrative — from the rafa reference repo: a silent RSC server/client breach cost a
+   100K-token correction loop in the 2026-06-03 audit; the brain prevented the repeat.)*
+6. **Missing-essence hunt** — actively search the code for a high-leverage contract / flow /
+   gotcha that is NOT captured. Each genuine miss → major (the cherry-pick guard).
+7. **Claim-truth check** — for a sample of notes, verify the note's *claim* matches the code
+   (the checker only proved the cite *resolves*). A false/misleading claim → **blocker**
+   (it violates the net-positive law: a wrong note is worse than none).
+8. **Connectivity** — orphan notes, dangling `[[links]]`, literal `[[...]]` in prose → minor.
+
+## Severity + decision
+- **Blocker** — hard-gate failure, broken checker, or a wrong/misleading note. Must be **0**.
+- **Major** — a real gap: missing essence, under-covered domain, unanswerable question.
+- **Minor** — nits (orphan, cosmetic). Logged, not looped on.
+- **PASS** = hard gates pass · quality score ≥ 85 · 0 blockers · majors ≤ 2. Else **ITERATE**.
+
+## Quality score (0–100) — only meaningful once hard gates (fidelity + coverage) pass
+| Weight | Dimension | Measure |
+|---|---|---|
+| 35 | Load-bearing | questions answerable / questions asked (step 5) |
+| 25 | Coverage balance | notes spread across domains; tunneling penalty (step 4) |
+| 25 | Net-positive density | notes adding non-obvious intelligence / total |
+| 15 | Connectivity | 1 − (orphan + dangling) rate (step 8) |
+
+**Non-obvious** (for net-positive density) = a competent dev *couldn't derive it from a
+single file* — it's a cross-file contract, a flow, a scar, or a *why*. A note that restates
+one file's content is obvious and doesn't count. Apply this test literally so two runs on
+the same brain score it the same.
+
+## Output → `.rafa/brain/checklist.md` (the report card)
+
+A frontmatter **header** the conductor branches on, then a **checklist** of every criterion
+with two columns — atlas's self-check (read from `coverage.md`) and your independent
+verdict (a `✓/✗` split on a row is itself a finding) — then the scorecard, then findings.
+
+```yaml
+---
+schemaVersion: 1          # required · contract §4 — the platform ingests this header
+verdict: ITERATE          # PASS | ITERATE   ← the conductor reads this
+round: 1
+score: 78                 # 0–100 (required int; a hard-gate fail is score 0 + verdict ITERATE)
+gates: { fidelity: pass, coverage: pass }        # each pass | fail
+counts: { blockers: 1, majors: 2, minors: 3 }    # non-negative ints
+---
+```
+`checklist.md`'s frontmatter is machine-read by the platform (contract §4) and validated by
+`rafa compile` — `schemaVersion`, `verdict`, `score`, `gates`, `counts` are all required. On a
+hard-gate fail write `score: 0` (not `null` — the contract requires an int).
+- **Checklist** — one row per criterion (A1, A3, B1, B2, policy, C1, C2, D1…): `checked-by`
+  (checker | atlas | prism) · atlas (self) · prism (verify) · evidence (`file:line` / artifact).
+- **Scorecard** — the 4 graded dimensions + composite.
+- **Findings ledger** — blocker / major / minor, each cited (`file:line`) + a suggested fix.
+
+You write **`checklist.md` only**. The **conductor** owns `log.md` (the round-by-round trail).
+PASS = hard gates pass · score ≥ 85 · 0 blockers · majors ≤ 2.
+
+## The ratchet
+Any judgment finding you raise repeatedly that *could* be mechanized → recommend it become a
+deterministic check in `verify-citations.mjs` (as B2 did). Push checks down into the machine;
+keep prism for what only judgment can catch.