@rafinery/cli 0.8.16 → 0.11.0

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

@@ -17,7 +17,7 @@ platform MCP (one read path — the same surface any third-party agent uses).
 | 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). Plan-done adds one line to the verdict: **working set reviewed — captured, or clean-with-reason** (a build that learned nothing SAYS so; a build that learned something SHOWS the files) |
+| **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). **TDD tasks (wave 6): green re-run LIVE; red per tier (standard = attested `method:"static"` · full = re-run at the red commit in a throwaway worktree). Findings carry `Critical (Must Fix) · Important (Should Fix) · Minor (Nice to Have)` — ITERATE iff any Critical/Important; Minor NEVER flips the verdict.** Plan-done adds one line to the verdict: **working set reviewed — captured, or clean-with-reason** (a build that learned nothing SAYS so; a build that learned something SHOWS the files) |
 | **Improver** | bloom | **push**: new improvement opportunities spotted during execution → new ledger files. **close**: improvements fixed in passing → `status: fixed` in the ledger file + `report_improvement_status(id, fixed)` so the platform shows it LIVE as pending-reconciliation (the ledger row itself changes only at the next brain push — K1). **nudge**: top-leverage open item in the task's blast radius — opt-in, never blocking |
 | **Coach** | compass | **sitback** (harness-arc): after each task's verdict + sweep, one beat of reflection — did THIS task reveal something about how this DEV works (a preference, a recurring friction, a steering pattern)? Repo knowledge goes to the working set, never here. A genuine dev-level observation becomes its OWN opt-in offer (consent doctrine: insights are NEVER under session consent) → `put_dev_insight` on yes. No observation = no offer — silence is the honest default |
 
@@ -47,22 +47,33 @@ platform MCP (one read path — the same surface any third-party agent uses).
    **and append a dated entry to the child's `## Log`** (body links: markdown,
    per [rafa-okf](../rafa-okf/SKILL.md)) — what was done, what was
    decided, what surprised (body prose: displayed verbatim on the platform, never
-   parsed; the plan files at `.rafa/plans/<plan>/` ARE the local cache) → at the
-   task-done CHECKPOINT (under the session consent): `push_plan` /
-   `update_plan_status` (the plans channel — statuses + Log journals) +
-   **`log_decision` for each deliberation since the last checkpoint** — what
-   came up, what was considered, what the DEV chose, why (actor = the dev for
-   steering, the agent for its own proposals; PARAPHRASE + short verbatim
-   quotes only where the wording carries the decision — transcripts never land
-   in shared stores; mirror each into the item's `## Decisions` section) +
-   **`report_loop_event(category: "prism-verdict", outcome: PASS|ITERATE,
-   subject: <task id>)`** at the moment prism rules on the Done-check (sage's
-   evidence — shapes only: the verdict + the task id, never code) +
-   `rafa checkpoint` (the branch working set), so the platform and every MCP
-   consumer reflect live progress. Checkpoint moments: task done · plan
+   parsed; the plan files at `.rafa/plans/<plan>/` ARE the local cache) → the
+   task-done CHECKPOINT is **ONE beat (wave 5), two calls total**, under the
+   session consent:
+   **(a) `checkpoint_task`** — the atomic boundary write (all-or-nothing,
+   idempotent on retry) carrying together: `patch: {status, body}` (the item's
+   new status + its full body with the fresh `## Log` entry — never a
+   whole-tree `push_plan` for one task); `loopEvent: {category:
+   "prism-verdict", outcome: PASS|ITERATE, subject: <task id>, tier: <the
+   task's validation_tier>, verification: <prism's evidence entry — method
+   static|live + tool + exit code, straight from its structured return>,
+   actorMeta: {model: <ruling model>, agent: "prism@<card ver>", runner:
+   "session"}, dedupeKey: "<task-id>·v<attempt>"}` (the emit rides the ruling's
+   OWN moment, never a session-end sweep; the dedupeKey makes a retried beat
+   count ONCE — the non-idempotent-emit learning, closed); and `decisions:
+   [...]` — each deliberation since the last beat with a CLIENT-STABLE id
+   (`<task-id>·d1`, `·d2` …): what came up, what was considered, what the DEV
+   chose, why (actor = the dev for steering, the agent for its own proposals;
+   PARAPHRASE + short verbatim quotes only where the wording carries the
+   decision — transcripts never land in shared stores; mirror each into the
+   item's `## Decisions` section).
+   **(b) `rafa checkpoint`** — the branch working set + sensor heartbeat +
+   brain mirror (the CLI beat; it also refreshes the loop-event cache the
+   sage-due digest reads).
+   `push_plan` remains for CREATION and structure changes only;
+   `update_plan_status`/`log_decision` stay valid but the one-beat call
+   replaces them at task boundaries. Checkpoint moments: task done · plan
    approved · explicit ask · cadence · git push/pull — never session-end. The
-   loop-event emits ride the SAME checkpoint beats — one per outcome as it
-   occurs, monotonic, NEVER a session-end sweep. The
    git-push boundary is MECHANICAL (M5): the pre-push hook runs `rafa checkpoint`
    itself, non-blocking — the session still owns the task-done/plan-approved
    moments. A checkpoint CONFLICT (a teammate's newer copy of the same file) is
@@ -71,10 +82,11 @@ platform MCP (one read path — the same surface any third-party agent uses).
 3. **Brain changes mid-build — WHERE you are decides WHERE it goes.**
    - **On the default branch (main):** run a full `/rafa scan` (regenerate →
      prism → compile → push); the brain re-stamps at the new sha, so
-     `brain = f(code@sha)` stays exact. When the gate runs, emit
-     **`report_loop_event(category: "gate-result", outcome: exit0|failed,
-     subject: <compile|verify-citations>)`** at that checkpoint beat — the gate's
-     own moment, never deferred to session-end.
+     `brain = f(code@sha)` stays exact. gate-result loop events are
+     **MECHANICAL** (wave 5): the push gates emit them CLI-stamped — actor
+     envelope, `method: "live"` verification with the real exit code, and a
+     `(gate·sha·outcome)` dedupeKey. The session never hand-emits gate-result;
+     the double-emit class died with the non-idempotent-emit learning.
    - **On any other branch:** the org brain is NEVER written from a branch —
      it describes main, and a branch-state scan would poison it for everyone.
      Invalidated/learned knowledge → the branch **working set**: hydrate the
@@ -106,6 +118,85 @@ platform MCP (one read path — the same surface any third-party agent uses).
    scoped-refresh offer NOW (on main: refresh → gates → push; on a branch:
    working-set edit → checkpoint), and `rafa dirty --consume` only after it ships.
 
+## TDD-default (wave 6 — code tasks build red → green)
+
+**Eligibility gate (deterministic, decided once per session):** the `tdd` skill
+is installed (`.agents/skills/tdd/` — the toolbox slice says so) AND the repo
+has a test harness — checklist, first hit wins: `package.json` `test` script ·
+`vitest.config.*`/`jest.config.*` · `pytest.ini`/`pyproject [tool.pytest]` ·
+`go.mod` with `*_test.go` · `Cargo.toml`. Bank the answer as a session fact
+(`rafa facts add --claim="test harness: <runner>" --command="<detect>" --exit=0
+--depends=package.json`) so no later spawn re-derives it. Not eligible → the
+pre-wave path below, unchanged, plus a `factsDiscovered: ["tdd unavailable:
+<reason>"]` note in atlas's return — bloom may later surface a tooling-fit
+improvement; NEVER a mid-build nag.
+
+**The loop (per the installed tdd skill — atlas INVOKES it; its anti-patterns
+are prism's criteria):**
+1. **Red** — atlas authors the failing test FIRST, at the seam the plan's
+   Done-check names (the seam was dev-confirmed at approval — never invented
+   here). Run it; it must FAIL for the right reason. Commit
+   `[<task-id>] test: red — <seam>` (full tier prefers the split commit; at
+   standard tier the evidence object below is the durable proof and red+green
+   may land as one commit).
+2. **Green** — implement the minimal slice to exit 0. One seam, one test, one
+   vertical slice per cycle — never all-tests-then-all-code.
+3. **Refactor is NOT part of the loop** — it belongs to the review stage
+   (tdd SKILL.md's own rule + the [rafa-review](../rafa-review/SKILL.md) gate;
+   bloom's no-big-bang directive is the same law).
+Evidence rides atlas's structured return —
+`evidence: [{claim: "red", tool: "<runner>", exitCode: 1}, {claim: "green",
+tool: "<runner>", exitCode: 0}]` + `skillsUsed: ["tdd"]` — and
+`how: via the tdd skill` lands in the item's `approach`.
+
+**prism's verification, tier-scaled:** green is ALWAYS re-run live (tool
+authenticity: binary + real exit code). Red at **standard** = attested from
+atlas's evidence, labeled `method: "static"`; at **full** = re-run at the red
+commit in a throwaway worktree (`git worktree add`), labeled `method: "live"`.
+Mock discipline is a finding class: mocks only at system boundaries, never the
+repo's own collaborators (the tdd skill's mocking reference is the criteria).
+
+## UI tasks — the design method (wave 6)
+
+**Trigger:** the task's epic `domains:` include a UI domain, or its target
+files land in the app's component/route surfaces — the BRAIN's domain map
+decides, never a hardcoded path list.
+
+**Method (when the skills are installed — the toolbox slice says):** atlas
+**INVOKES** `frontend-design` (Skill tool) for the two-pass plan — token
+system (Color 4–6 named values · Type roles · Layout · the ONE signature
+element), then self-critique against the brief before any code — and CONSULTS
+`vercel-composition-patterns` for component structure (no boolean-prop
+sprawl · compound components · state/actions/meta context · children over
+render props), gating the `react19-*` rules on the repo's actual React version
+(a React ≤18 repo skips them, stated in the return).
+
+**Adherence vs distinctive — the brain decides:** when the brain documents a
+design system (theme tokens, component conventions), those notes ARE the
+brief and the skill's own "the brief's own words always win" rule applies —
+adherence mode, distinctiveness spent within the system. No design-system
+notes (greenfield/marketing surface) → distinctive mode, full method. Record
+`how: via the frontend-design skill` (+ vercel-composition-patterns when
+consulted). Skills declined → the pre-wave path + a `factsDiscovered` note.
+
+## Spawn-prompt discipline (wave 5 — pay once, cite after)
+
+- **Session facts first.** Every atlas/prism spawn prompt begins by pointing at
+  `.rafa/session-facts.json` (read first; cite `SF-n unchanged` where it holds;
+  bank new expensive verifications via `rafa facts add`). Six agents
+  re-deriving one environment fact was the QA session's headline waste.
+- **Never restate card doctrine.** The card already binds the agent's creed
+  (prism's skepticism, atlas's toolbox-first) — a spawn prompt carries ONLY the
+  task-specific grounding: the task file, the exact target files/patterns, the
+  `validation_tier`, the facts pointer. Re-explaining the card in every prompt
+  is conductor inefficiency, not rigor.
+- **Compact agent-to-agent register.** A subagent's primary reader is the
+  CONDUCTOR: terse-with-citations by default, ending in the structured return
+  (prism: `{verdict, evidence[], residualRisk}` · atlas: `{filesChanged,
+  commitSha, notes, factsDiscovered}`) — Logs and loop events assemble from
+  FIELDS, never re-paraphrased prose. Expand to full prose only on ITERATE or
+  when the human will read it directly.
+
 **Lite plans** (single-child, from plan-lite) run the same per-task loop — the
 Done-check gate never relaxes; only the ceremony around it shrinks (no bloom nudge,
 single checkpoint + plan push at the end).

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

@@ -36,6 +36,28 @@ description: "rafa SOP — generate the commit message with the id join-key: the
    outcome one-line ("Done-check: prism PASS") — the receipt travels with the
    code.
 
+## The body is REQUIRED and written for an AGENT reader (owner 2026-07-26)
+
+A subject-only commit is a broken contract here. The next reader of this
+message is most often an AGENT — ours (atlas recalling why a line exists, the
+distiller judging a claim against this change, sage reading shapes) or a
+foreign one — so the body must be SELF-CONTAINED and joinable:
+
+- **What, concretely** — the surfaces/behaviors that changed, named (not
+  "various fixes"); a reader must know the blast radius without the diff.
+- **Why — the intent** — the one thing the diff cannot show. State the
+  problem/decision that made this change necessary; paraphrase the pivotal
+  choice if one was made (it should also be a `log_decision`).
+- **Join keys** — mention the brain notes this change follows or invalidates
+  (`per rule <id>` / `staleness: touches <id>`), so the cite-graph and the
+  dirty queue read straight out of the log.
+- **No session deixis** — never "as discussed", "per the above", "the same
+  fix as before": the message must stand alone in `git log` a year later,
+  with zero conversation context.
+
+TDD-default red commits keep their fixed form (`[<task-id>] test: red —
+<seam>`) — the seam IS the body's content there.
+
 ## Why this exists (don't skip the bracket)
 
 The brain-commit hook captures every subject into `intent/<sha>.md`;

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

@@ -39,6 +39,28 @@ code it describes.
 1. **Collect** — `get_working_set(repo, branch, status: active)`. Zero files →
    nothing to do, say so, stop. Rows already `needs-adjudication` are a HUMAN's
    to resolve — surface them in the digest, never fold them in silently.
+1b. **Schema ladder (0.11.0 — the owner's 4-case doctrine).** Before ANY
+   claim-level judging, resolve the version lattice: **target** = the org
+   brain's `manifest.json → schemaVersion` (else max over its notes; a
+   pre-manifest brain is the founding v1) · **source** = max over the
+   collected candidates' own `schemaVersion` · **latest** = the running CLI's
+   `SCHEMA_VERSION`. Then: **target < source → REWRITE-TARGET** (every org-
+   brain note lifts to the newer schema and rides THIS run's gates + push —
+   one migration+reconcile commit) · **target > source → UPGRADE-SOURCE**
+   (incoming candidates lift into the target's schema before judging) ·
+   **equal but < latest → REWRITE-MERGED** (both lift; the merged target is a
+   full rewrite onto latest) · **equal and == latest → DIFF** (the happy flow,
+   steps 2–6 exactly as written). **Either side > latest → ABORT LOUDLY** — a
+   newer CLI authored it; update the runner, knowledge is never downgraded.
+   Transforms are REGISTERED per step AND per OKF type
+   (`lib/distiller/schema-ladder.mjs` — each step declares rule · playbook ·
+   improvement explicitly: a function, or the EXPLICIT "unchanged", which
+   still re-stamps the note's schemaVersion line); a missing step OR class is
+   a loud error, never a guess. Only durable knowledge ladders — derived/
+   generated files (coverage · checklist · ledger · reports · manifest)
+   REGENERATE at the new schema; intent records pass through untouched. The
+   headless CLI runs this mechanically; the session path applies the same
+   lattice by hand.
 2. **Validate (prism, context-isolated)** — the target is **merged MAIN as of
    NOW, never the fork point and never a stale checkout**: `git fetch origin`
    first; judge every claim against the fetched trunk. Confirm every citation
@@ -51,7 +73,13 @@ code it describes.
    files lost it — re-declare); fold into an existing note when one covers the
    topic (supersede, never duplicate).
 4. **Gate + ship** — `rafa verify-citations` AND `rafa compile` to exit 0 →
-   `rafa push`. Only now has anything entered the org brain. A failed gate
+   `rafa push --verb=distill --message="reconcile(<branch>): <N> banked ·
+   <M> refuted · <K> adjudication — <banked ids…>"`. The reconciliation
+   commit is DESCRIPTIVE (owner 2026-07-26): its subject states what THIS run
+   did — branch, per-verdict counts, the banked note ids — so any agent
+   walking the brain log understands the commit without opening it (the
+   headless CLI composes this automatically; the session path passes it
+   explicitly). Only now has anything entered the org brain. A failed gate
    aborts EVERYTHING: nothing resolved, nothing pushed, working set intact.
 5. **Resolve** — `resolve_working_file(path, distilled)` for survivors — authored
    per the OKF surface ([rafa-okf](../rafa-okf/SKILL.md); push emits the rest) —
@@ -61,9 +89,14 @@ code it describes.
    which files died and why (cited); refutation is feedback, not silence. At
    that same resolve beat emit **`report_loop_event(category:
    "distill-refutation", outcome: refuted|distilled, subject: <path or note
-   id>)`** — sage's evidence that a claim met the gates or was refuted (shapes
-   only: the outcome + a file/note reference, never the refuted content, never
-   the cited code). Checkpoint-adjacent, monotonic, never a session-end sweep.
+   id>, actorMeta: {model: <the judging model>, agent: "distiller@<ver>" (or
+   "prism@<ver>" on the session path), runner: session|ci|sandbox — the tier
+   this distill runs in}, dedupeKey: "<branch>·<path>·<outcome>")`** — sage's
+   evidence that a claim met the gates or was refuted (shapes only: the
+   outcome + a file/note reference, never the refuted content, never the
+   cited code). Wave 5 is STRICT: an emit without the actor envelope is
+   rejected loudly; the dedupeKey makes a re-run of the same distillation
+   count ONCE. Checkpoint-adjacent, monotonic, never a session-end sweep.
    `resolve_working_file(path, needs-adjudication, note)` for the undecidable —
    the next session's digest offers the decision.
 

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

@@ -91,6 +91,24 @@ convention — see [RSC client boundary](/brain/rules/rsc-client-boundary.md)).
    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."
+
+   **The architecture lens has a METHOD (wave 6)** — criteria adapted from the installed
+   `improve-codebase-architecture` skill (READ as criteria, never invoked — it is
+   `disable-model-invocation`; the method below stands whether or not the skill is installed):
+   - **Scope by heat, not by sweep** (YAGNI): unless the dev named a direction, walk
+     `git log --oneline` for the hot spots — churn is where depth pays; cold code waits.
+   - **Deep vs shallow judgment**: a module earns its interface when the interface is smaller
+     than what it hides. Bouncing between many small modules to follow one behavior, pure
+     functions extracted only for testability, and leaky seams are the friction signals.
+   - **The deletion test**: would deleting this module CONCENTRATE complexity somewhere honest,
+     or just smear it around? "Concentrates" marks a candidate.
+   - **Candidates are normal §3 improvement files** (zero schema change): before/after as body
+     prose + a `Confidence: Strong | Worth exploring | Speculative` body line; inside these
+     notes use the depth vocabulary — module · interface · implementation · seam · adapter ·
+     depth · leverage · locality — and keep it INSIDE the architecture lens (the rest of the
+     ledger speaks the repo's own language).
+   - **The big-bang guard is sovereign** (directive 1): a `Strong` candidate lands as its first
+     10-minute slice or a P2 backlog item — never a grand refactor plan.
 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.
@@ -166,3 +184,7 @@ the ledger the nudge will read.
   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).
+- A visual before/after artifact for architecture candidates (the
+  improve-codebase-architecture skill's HTML report) — deliberately SKIPPED for now: its
+  CDN-loaded Tailwind/Mermaid + temp-file-and-open mechanics violate the deterministic,
+  no-network posture; the ledger IS the report.

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

@@ -44,7 +44,12 @@ at the fix. This is platform DNA: **leverage what's present; never reinvent it.*
 
 The engine ([`lib/leverage/engine.mjs`](../../../packages/cli/lib/leverage/engine.mjs)) gathers
 light, tool-agnostic repo signals (`repoContext`: stack deps, `.env` files + whether they're
-ignored, declared MCP servers), then runs every **detected** adapter and ranks the tips.
+ignored, declared MCP servers, **and the harness-neutral `.agents/skills/` inventory +
+skill-dependency status (wave 6)** — `.agents/` is ONE convention Claude Code · Codex ·
+Cursor all read, so it lives in the engine, never inside a per-toolchain adapter), then runs
+every **detected** adapter and ranks the tips. The engine emits its own rafa-level tip —
+`skill-deps-missing` (`P2`, fix = `rafa update --skills`) — because rafa's declared skill
+dependencies are harness-neutral by definition.
 
 Each adapter implements one contract ([`lib/leverage/adapters/index.mjs`](../../../packages/cli/lib/leverage/adapters/index.mjs)):
 

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

@@ -41,6 +41,34 @@ Planning is a choreography, not one agent (spec: knowledge-mcp-build-agent):
   A plan whose children lack Done-checks is REJECTED here — compile never parses
   bodies (invariant #3); this gate is prism's.
 
+  **The grill pass (wave 6 — tier-bounded adversarial interview).** On top of
+  the two invariants, prism GRILLS the draft — the same procedure the installed
+  `grilling` skill carries (`.agents/skills/grilling/SKILL.md`; prism READS it
+  as criteria when installed, and this SOP carries the method regardless —
+  never invoked mid-validation, per its card). Per task, up the probe ladder:
+  **grounding** (which claims rest on assumption? name it, demand its
+  evidence — a session-fact id counts, vibes don't) · **unstated dependencies**
+  (what must exist for this task that no `blocked_by` declares?) · **vacuous
+  Done-check** (can it pass while the feature is broken? a check that
+  recomputes its expectation the way the code will, or that a no-op satisfies,
+  is TAUTOLOGICAL — criteria per the tdd skill's anti-patterns when installed)
+  · **YAGNI** (does the INTENT need this task, or did thoroughness invent it?).
+  Budget scales with the task's `validation_tier`: **light** = the two
+  invariants only (exactly today) · **standard** = ≤2 probes per task, ≤10 per
+  plan · **full** = the complete grilling procedure (one probe at a time,
+  survives-three-consecutive ends it). Every probe finding cites the plan line
+  it hits — an uncited probe is dropped, and findings feed the existing
+  REJECT-with-cited-reasons loop. Plan-lite drafts grill at light.
+
+  **The seam ritual (wave 6 — TDD's consent moment, no new prompt).** For code
+  tasks in TDD-eligible repos (the tdd skill installed + a test harness
+  detected — the build SOP's gate), every LEAF's `## Done-check` NAMES the seam
+  under test: *"`<runner>` on `<test-file>` at seam `<the public interface>`
+  exits 0"*. Seams come from recall (the brain's contracts/flows) — never
+  invented at build time. The plan-approval summary lists the seams as their
+  own line, so **the dev approving the plan IS the tdd skill's "confirm seams
+  with the user" step** — consent rides the existing approval gate.
+
 ## Procedure
 
 1. **Staleness check** — compare the platform envelope's `brainForSha` against the
@@ -58,7 +86,14 @@ Planning is a choreography, not one agent (spec: knowledge-mcp-build-agent):
    carries the glimpse fields — `title` (what) · `description` (why) ·
    `approach` (how, one line) · `assignee` when known · `blocked_by` for
    intra-plan dependencies (a dependency IS a blocker; blocked is DERIVED,
-   never a status) · optional `priority` 0–4 / `estimate`. Every LEAF carries a
+   never a status) · optional `priority` 0–4 / `estimate` ·
+   **`validation_tier` (wave 5 — rigor scales with blast radius, not with
+   process): assign per LEAF from what the task touches — contract/state-shape/
+   graph surface → `full` · pure types/docs/leaf-UI → `light` · everything else
+   → `standard` (the default when omitted). The tier bounds prism's
+   RE-DERIVATION DEPTH only; the Done-check gate itself never relaxes, and the
+   tier rides the task's loop events so sage can audit the tiering against
+   escaped-bug reality instead of anyone guessing.** Every LEAF carries a
    `## Done-check`. The blast radius goes on the EPIC's `domains:` — it rides
    `push_plan` and the platform renders the plan's brain slice beside it.
    ADR material (alternatives, risks, non-goals) lives in the epic body AND

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

@@ -104,8 +104,16 @@ its OWN question:
 7. **The active task's Done-check** (from `get_active_plan`): does the diff
    satisfy what the plan said done means?
 8. Verdict: **PASS** or **ITERATE** with per-finding citations (note id +
-   file:line). Findings feed atlas (validate-and-correct — atlas fixes, the
-   judge re-checks; the reviewer never edits).
+   file:line). **Severity rides every finding (wave 6 — the
+   requesting-code-review taxonomy): `Critical (Must Fix)` · `Important
+   (Should Fix)` · `Minor (Nice to Have)`. ITERATE iff ≥1 Critical or
+   Important; Minor NEVER flips the verdict** (advisory noise must not
+   masquerade as a gate — and "not everything is Critical" is the taxonomy's
+   own first rule). Findings feed atlas (validate-and-correct — atlas fixes,
+   the judge re-checks; the reviewer never edits). The fresh-context reviewer
+   discipline the installed requesting-code-review skill prescribes
+   (precisely-crafted context, never the session's history) IS rafa's spawn
+   model already — confirmation, not new machinery.
 9. Emit **`report_loop_event(category: "review-verdict", outcome:
    PASS|ITERATE, subject: <task id or branch>)`** at the ruling — sage's
    evidence, monotonic, never a session-end sweep.
@@ -124,3 +132,9 @@ its OWN question:
 - Trusting the diff author's summary — judge code against rules.
 - Blocking on the gate — it is advisory; the merge reconciler is the hard gate.
 - Findings without citations (rule id + file:line) — uncited = unactionable.
+- **Mutating anything while judging** (wave 6, from the code-reviewer's
+  read-only rule): the review never touches the working tree, the index, HEAD,
+  or branch state — inspect another revision via `git show`/a throwaway
+  worktree, never a checkout on this one.
+- **Severity inflation** — a verdict where everything is Critical has stopped
+  discriminating; that is itself a review failure.

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

@@ -58,8 +58,14 @@ boundary; its product is a ledger reviewed *later*, never a live nudge. No mid-f
 ### 2. evidence-cited — SHAPES only, via `get_loop_events`
 Every learning cites its evidence, and evidence is **loop-event shapes and categories only**:
 verdict TYPES, gap CLASSES, miss TAXONOMIES, and the aggregate counts/rates over them — read via
-`get_loop_events` (category ∈ `prism-verdict | gate-result | reflex-outcome | distill-refutation`;
-outcome enum per category; `subject` is a shape reference, never content). A learning with no
+`get_loop_events` (category ∈ `prism-verdict | gate-result | reflex-outcome | distill-refutation |
+review-verdict`; outcome enum per category; `subject` is a shape reference, never content). Wave 5
+enriched every event with THREE new analysis dimensions — split every rate by them: **verification
+method** (`static` vs `live` — a PASS-rate that holds only on static rulings is a coverage gap, not
+health), **actor envelope** (model · agent@version · runner — attribute a miss class to the agent
+structure that produced it), and **tier** (`light|standard|full` — audit the tiering itself: a
+light-tier task class that later produced escaped bugs is evidence the planner's tier rule needs a
+diff; a full-tier class whose findings-density is ~zero is evidence of ceremony). A learning with no
 event-shape evidence is a hunch — drop it. sage never cites a customer artifact (no `file:line`
 into customer code; that field does not exist in the schema below).
 

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

@@ -155,7 +155,10 @@ retrieval index. Bodies read like a senior engineer explaining that one concept
 3b. **Toolbox inventory** [deterministic] — ratified 2026-07-12: the REPO toolbox is a
    first-class brain domain (`toolbox`). Run `npx @rafinery/cli leverage --json` (the
    deterministic extractor) and author cited notes for the committed toolbox — skills
-   (`.claude/skills/*/SKILL.md` name+description), commands, `.mcp.json` servers,
+   (`.claude/skills/*/SKILL.md` name+description), **the harness-neutral
+   `.agents/skills/*/SKILL.md` (wave 6 — the `agentSkills` block in the JSON: one
+   convention Claude Code · Codex · Cursor all read; consent-installed by
+   `rafa update`)**, commands, `.mcp.json` servers,
    granted permissions — cites into the config files themselves (contract §2; they are
    citable file:line). This makes the toolbox recallable through the SAME MCP surface
    as all knowledge and refreshable like any note. Personal `~/.claude/` is NEVER

package/lib/brain-repo.mjs

@@ -77,7 +77,7 @@ export function ensureBrainRepo(cwd, { requireRemote = true } = {}) {
   // (not knowledge). MERGED line-by-line so clones ignored under an older CLI
   // still gain new exclusions.
   const ignore = join(rafaDir, ".gitignore");
-  const IGNORES = ["hydration.json", "*.theirs.md", "distill-incoming/", "distill-verdicts.json", "dirty.jsonl", "reflex.jsonl", "sensor-errors.jsonl", "benchmark.demo.json"];
+  const IGNORES = ["hydration.json", "*.theirs.md", "distill-incoming/", "distill-verdicts.json", "dirty.jsonl", "reflex.jsonl", "sensor-errors.jsonl", "benchmark.demo.json", "session-facts.json", "loop-events-tail.json"];
   const cur = existsSync(ignore) ? readFileSync(ignore, "utf8") : "";
   const have = new Set(cur.split("\n").map((l) => l.trim()).filter(Boolean));
   const missing = IGNORES.filter((l) => !have.has(l));

package/lib/checkpoint.mjs

@@ -108,11 +108,20 @@ export default async function checkpoint() {
 
   // The working set is BRANCH state. On the trunk, knowledge changes go
   // through scan → compile → rafa push (the org brain's one writer surface).
-  if (branch === "main" || branch === "master") {
-    console.log(
-      `• on ${branch} — the working set is branch-scoped; org-brain changes on the trunk go through /rafa scan + rafa push. Nothing to checkpoint.`,
-    );
-    return;
+  // The trunk is RESOLVED, never hardcoded (owner 2026-07-26): the stamped
+  // prodBranch → origin/HEAD → "main"; the main|master pair stays as a belt
+  // ONLY for unconfigured repos (with prodBranch set, "main" can be a plain
+  // feature-carrying branch and its working set checkpoints normally).
+  {
+    const { trunkBranchOf, readStamp } = await import("./stamp.mjs");
+    const trunk = trunkBranchOf(ROOT);
+    const configured = typeof readStamp(ROOT).prodBranch === "string";
+    if (branch === trunk || (!configured && (branch === "main" || branch === "master"))) {
+      console.log(
+        `• on ${branch} (the trunk) — the working set is branch-scoped; org-brain changes on the trunk go through /rafa scan + rafa push. Nothing to checkpoint.`,
+      );
+      return;
+    }
   }
 
   // The commit this capture is grounded against (contract: capturedAtSha —
@@ -248,22 +257,24 @@ export default async function checkpoint() {
   // durable mirror of the dev's current copies; .theirs.md files are ignored.)
   mirrorTail(ROOT, branch);
 
-  // prism-verdict backstop (harness-arc wave 0): gate-result/reflex-outcome are
-  // emitted mechanically by the CLI, but prism verdicts are LLM judgments only
-  // the session can report. The checkpoint beat — the SOP's own emit moment —
-  // checks the store and reminds while it's still empty. Best-effort, one line.
+  // prism-verdict backstop (harness-arc wave 0) + the sage-due cache (wave
+  // 5.5): the SAME single best-effort call, enriched. It now fetches recent
+  // events (no category filter) and caches their SHAPES locally
+  // (.rafa/loop-events-tail.json — category/at only, subjects excluded) so the
+  // SessionStart digest computes "sage due" with ZERO added platform calls.
+  // The old prism-verdict reminder derives from the same response.
   try {
-    const evts = await callTool(ROOT, "get_loop_events", {
-      category: "prism-verdict",
-      limit: 1,
-    });
-    if ((evts.events ?? []).length === 0)
+    const { writeLoopCache } = await import("./loop-cache.mjs");
+    const evts = await callTool(ROOT, "get_loop_events", { limit: 200 });
+    const events = evts.events ?? [];
+    writeLoopCache(ROOT, { fetchedAt: new Date().toISOString(), events });
+    if (events.filter((e) => e.category === "prism-verdict").length === 0)
       console.log(
         "  ℹ no prism-verdict loop events recorded yet — the build SOP emits " +
           "report_loop_event(prism-verdict, PASS|ITERATE, <task id>) at each Done-check ruling.",
       );
   } catch {
-    /* unprovisioned/unreachable — the reminder is best-effort */
+    /* unprovisioned/unreachable — the reminder + cache are best-effort */
   }
   if (conflicts) process.exit(2);
 }

package/lib/distill.mjs

@@ -40,8 +40,17 @@ import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { callTool } from "./mcp-client.mjs";
-import { runCompile } from "./gate/compile.mjs";
+import { trunkBranchOf } from "./stamp.mjs";
+import { runCompile, SCHEMA_VERSION } from "./gate/compile.mjs";
 import { runVerifyCitations } from "./gate/verify-citations.mjs";
+import {
+  applyLadder,
+  brainSchemaVersion,
+  classOf,
+  resolveSchemaPlan,
+  sourceSchemaVersion,
+  walkBrainNotes,
+} from "./distiller/schema-ladder.mjs";
 import pull from "./pull.mjs";
 import push from "./push.mjs";
 
@@ -192,7 +201,7 @@ export default async function distill(args = []) {
     try {
       await callTool(ROOT, "report_distill_run", {
         branch,
-        toBranch: process.env.RAFA_TARGET_BRANCH || "main",
+        toBranch: process.env.RAFA_TARGET_BRANCH || trunkBranchOf(ROOT),
         mergeCommitSha: mergeSha,
         status,
         note: summary,
@@ -371,6 +380,35 @@ export default async function distill(args = []) {
   await pull(["--full"]);
   console.log(`  ⏱ brain mirror: ${secs(tPull)}s`);
 
+  // 2b · SCHEMA LADDER (0.11.0 — the owner's 4-case doctrine): resolve the
+  // version lattice BEFORE any claim-level judging, so knowledge from two
+  // lineages always meets on ONE schema — the newest this runner understands.
+  // Lifted target notes ride THIS run's gates + push (one migration+reconcile
+  // commit); an unknown future schema aborts loudly, never downgrades.
+  {
+    const target = brainSchemaVersion(join(ROOT, ".rafa"));
+    const source = sourceSchemaVersion(active.map((f) => f.content));
+    const plan = resolveSchemaPlan({ target, source, latest: SCHEMA_VERSION });
+    console.log(
+      `• schema ladder: target v${target} · source v${source} · runner v${SCHEMA_VERSION} → ${plan.mode}`,
+    );
+    if (plan.mode === "abort-newer-than-runner") die(plan.reason);
+    if (plan.mode !== "diff") console.log(`  ${plan.reason}`);
+    // Per-OKF-type lifts (class derives from the PATH — typed-candidates
+    // doctrine); non-laddered paths (intent records …) pass through untouched.
+    if (plan.upgradeSource)
+      for (const f of active) {
+        const cls = classOf(f.path);
+        if (cls) f.content = applyLadder(f.content, plan.toVersion, cls);
+      }
+    if (plan.rewriteTarget)
+      for (const noteFile of walkBrainNotes(join(ROOT, ".rafa"))) {
+        const cls = classOf(noteFile);
+        if (cls)
+          writeFileSync(noteFile, applyLadder(readFileSync(noteFile, "utf8"), plan.toVersion, cls));
+      }
+  }
+
   // 3 · stage the incoming working set for the agent (gitignored inside .rafa).
   const stagingRoot = join(ROOT, ".rafa", "distill-incoming");
   rmSync(stagingRoot, { recursive: true, force: true });
@@ -554,7 +592,22 @@ ${fileList}`;
     (f) => byPath.get(f.path).verdict === "distilled",
   ).length;
   if (distilledCount > 0) {
-    await push(["--verb=distill"]);
+    // Descriptive reconciliation commit (owner 2026-07-26): the subject says
+    // WHAT this run did — branch, per-verdict counts, the banked ids — so any
+    // agent (ours or a foreign OKF reader) walking the brain log understands
+    // the commit without opening it. brain-for trailer untouched (push owns it).
+    {
+      const counts = { distilled: 0, refuted: 0, "needs-adjudication": 0 };
+      for (const v of verdicts) counts[v.verdict] = (counts[v.verdict] ?? 0) + 1;
+      const banked = verdicts
+        .filter((v) => v.verdict === "distilled")
+        .map((v) => String(v.path).split("/").pop().replace(/\.md$/, ""));
+      const idList = banked.slice(0, 4).join(", ") + (banked.length > 4 ? " …" : "");
+      await push([
+        "--verb=distill",
+        `--message=reconcile(${branch}): ${counts.distilled} banked · ${counts.refuted} refuted · ${counts["needs-adjudication"]} adjudication${banked.length ? ` — ${idList}` : ""}`,
+      ]);
+    }
   } else {
     console.log("• no survivors — nothing to push to the brain repo");
   }

package/lib/distiller/doctrine.mjs

@@ -164,22 +164,11 @@ export function citesGround(content, cwd = process.cwd()) {
 }
 
 // Rewrite a survivor's frontmatter `cites:` DSL so a re-grounded citation points
-// at where the token NOW lives on main — otherwise banking it as authored would
-// fail the checker (the stale line no longer resolves). Mechanical string
-// substitution on the exact `file:line :: token` locator; untouched lines pass
-// through. Returns the rewritten content.
-export function rewriteCites(content, regroundings) {
-  let out = content;
-  for (const r of regroundings ?? []) {
-    const fromLoc = r.cite.loc; // file:line[-end]
-    const toLoc = r.to.loc; // file:line
-    // Match the DSL line `  - <fromLoc> :: <token>` and swap the locator only.
-    const esc = fromLoc.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    const re = new RegExp(`(-\\s+)${esc}(\\s*::\\s*)`, "g");
-    out = out.replace(re, `$1${toLoc}$2`);
-  }
-  return out;
-}
+// at where the token NOW lives on main. MOVED to the gate (wave 5.3) so
+// `verify-citations --fix` can use it without an import cycle (this module
+// imports the gate's primitives, never the reverse); re-exported here so the
+// doctrine's callers keep their import path.
+export { rewriteCites } from "../gate/verify-citations.mjs";
 
 // ── folding N branch working sets into ONE run (case 1 · case 5) ────────────────
 // Input: [{ branch, capturedAtSha, mergedAt, files: [{ path, content }] }].