@rafinery/cli 0.8.16 → 0.10.0

package/CHANGELOG.md

@@ -4,6 +4,87 @@ 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.10.0 — wave 6: the capability arc (skill dependencies + agent upgrades)
+
+rafa's agents get materially better at engineering — and the mechanism is the
+owner's design: rafa **declares** third-party skill dependencies and installs
+them **with your consent**, package-manager style, so the agents adopt YOUR
+toolbox instead of hardcoding one.
+
+- **The skill installer.** `rafa update`/`init` offers 7 declared skills (tdd,
+  frontend-design, vercel-composition-patterns, requesting-code-review,
+  improve-codebase-architecture, grill-me, and rafa's own grilling procedure)
+  with one-line reasons; on yes it installs them one at a time into the
+  **harness-neutral `.agents/skills/`** (one convention Claude Code, Codex,
+  and Cursor all read — Codex manifests ride along), verifies each
+  (frontmatter parses · sha256s match the tarball's own manifest · license
+  files present), and stamps `rafa.json`. Declining is remembered — re-offer
+  with `rafa update --skills`; `--yes` for CI; non-TTY without `--yes` skips
+  and stamps nothing. A declined set degrades gracefully, never breaks:
+  vendored cards never reference `.agents/` (pinned by test).
+- **TDD by default** (atlas 4.0.0): eligible code tasks (tdd installed + a
+  harness detected) build red→green — the Done-check IS a failing test
+  authored first at a seam the dev approved at plan time; evidence (red
+  exit≠0 before green exit 0) rides the structured return; prism re-runs
+  green live and verifies red per validation tier. Refactor defers to review.
+- **The design method**: UI tasks invoke frontend-design (token system,
+  signature element, critique-before-code) and consult Vercel's composition
+  rules (React-19-gated) — with the brain's design-system notes as the brief.
+- **The grill gate** (prism 0.9.0): plans get a tier-bounded adversarial
+  interview before approval — grounding, unstated dependencies, VACUOUS
+  Done-checks (tautological tests caught), YAGNI. Devs also get `/grill-me`.
+- **Severity-labeled findings** everywhere prism/review rule: Critical ·
+  Important · Minor — Minor never flips a verdict.
+- **bloom's architecture method** (0.9.0): git-log heat scoping, the deletion
+  test, Confidence-lined candidates, first-slice-or-backlog — never big-bang.
+- **Toolbox surfaces**: conductor 2.2.0 recalls `.agents/skills` in every
+  spawn slice; `rafa leverage --json` carries top-level `agentSkills` +
+  `skillDeps`; `rafa doctor` verifies installed skills against the bundle.
+
+Adopt with `rafa update` — the skills prompt runs first, then the blueprint
+sync. All licenses confirmed and vendored (MIT ×5, Apache-2.0 frontend-design).
+
+## 0.9.0 — wave 5: trust plane + transport economics
+
+The research-canvas QA dogfood session (2026-07-25) produced a P0–P3 bottleneck
+backlog; its root causes converged with sage's first two learnings on the same
+seam. This release lands the whole wave:
+
+- **Strict loop events, no legacy path.** `report_loop_event` requires the
+  actor envelope (`model` · `agent` · `runner ∈ sandbox|ci|session`; mechanical
+  CLI emits stamp `model:"mechanical"`) and `verification {method: static|live,
+  tool?, evidence?}` on verdict/gate categories — the static-vs-executed
+  distinction is structural, so a fabricated "tests passed" can't survive the
+  schema. `dedupeKey` makes every emit idempotent; `tier` records the
+  validation tier the ruling ran at. Pre-0.9.0 emits are rejected server-side
+  (pre-launch: old CLIs discarded). Both sage learnings flipped accepted.
+- **One beat per task boundary.** `patch_plan_item` patches ONE item's fields
+  (structure stays `push_plan`-only); `checkpoint_task` lands the item patch +
+  the prism-verdict loop event + decision records in ONE transaction,
+  idempotent on retry. A task boundary went from ~6 platform calls + a
+  full-tree resend to 2 beats.
+- **Self-healing citations.** `verify-citations --fix` rewrites a drifted cite
+  when its token still lives at exactly ONE grep site (gone/ambiguous stay
+  failing — the checker never guesses), then re-runs clean. `rafa hydrate`
+  re-bases served cites against the local checkout on arrival.
+- **`rafa facts` — the session-facts plane.** Bank a verified fact once (claim
+  + the command/exit that proved it + dependsOn paths, sha-anchored); agents
+  read first and cite `SF-n unchanged`. Staleness is mechanical (dependsOn ∩
+  git diff since the verifying sha, working tree included).
+- **The sage-due bridge.** `rafa checkpoint` caches loop-event shapes locally;
+  the SessionStart digest prints "sage due: N" with zero added platform calls,
+  and the conductor card makes honoring it a MUST — sage's trigger is
+  mechanical instead of discretionary.
+- **`validation_tier` on plan tasks** (light|standard|full): bounds prism's
+  re-derivation depth only — the Done-check gate never relaxes.
+- Cards/SOPs re-vendored: prism 0.8.0 (tool-authenticity rule · structured
+  return · bounded invariant citation) · atlas 3.9.0 (structured return ·
+  facts duty) · sage 0.4.0 (verification/actor/tier analysis dimensions) ·
+  conductor 2.1.0 (mechanical sage trigger). Review summary counts dedupe by
+  note id.
+
+Adopt with `rafa update` (re-vendors hooks, cards, SOPs, contract).
+
 ## 0.8.16 — the session tail never strands (both planes, one beat)
 
 Live-catch (2026-07-24, research-canvas): brain notes authored AFTER the last code

package/bin/rafa.mjs

@@ -46,6 +46,7 @@ const COMMANDS = [
   "hydrate",
   "dirty",
   "reflex",
+  "facts",
   "status",
   "doctor",
   "fold",
@@ -73,6 +74,8 @@ Commands:
   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)
+                        --skills     re-offer declared skill dependencies (incl. declined)
+                        --yes        install all skill dependencies unprompted (CI)
   compile              Validate the brain against the contract → .rafa/manifest.json.
   manifest             The BRANCH manifest (lenient snapshot — WIP files land under
                        drafts, never fail). You never need to run this: the post-commit
@@ -113,6 +116,14 @@ Commands:
                        detected. List/--json; --consume <id> [verdict] AFTER banking it
                        through the gates (or judging it session-only). Corrections are
                        the highest-value knowledge signal — they must never evaporate.
+  facts                The session-facts plane (wave 5.4 — memoized verification): bank a
+                       VERIFIED fact once (claim + the command/exit that proved it +
+                       dependsOn paths, sha-anchored); agents read first and cite
+                       "SF-n unchanged" instead of re-deriving. Staleness is mechanical
+                       (dependsOn ∩ git diff since the verifying sha) and NOT transitive —
+                       declare the enclosing directory for subsystem-spanning facts
+                       (breadth is the conservative move). add · invalidate ·
+                       prune --stale · --json.
   status               Where the loop stands, from local state only: active plan +
                        task progress · stale count · corrections · conflicts.
                        --line = the one-line ambient form (statuslines/prompts) ·

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

@@ -1,6 +1,6 @@
 ---
 name: atlas
-version: 3.8.1
+version: 4.0.0
 model: opus   # authoring is correctness-critical — a hallucinated note poisons the brain; best model, never cheap
 groundTruth: code-at-sha
 description: >-
@@ -16,7 +16,7 @@ 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"
+  - "build-execution :: .claude/skills/rafa-build/SKILL.md :: implement per recalled knowledge · TDD-DEFAULT when the tdd skill + a harness are present (the Done-check is a failing test FIRST at the plan-named seam; red→green evidence in the return) · UI tasks run the installed design skills per SOP (brain conventions win) · read session-facts FIRST and bank new expensive verifications (rafa facts add) · never hand-edit brain files around the gate · return what changed, cited"
   - "scoped-refresh :: .claude/skills/rafa-scan/SKILL.md :: re-derive ONLY the dirty-cited notes against current code (input: rafa dirty --json) · same gates as scan (verify-citations exit 0) · on main: compile+push; on a branch: working-set edit + checkpoint · queue consumed only after the refresh ships"
   - "okf-surface :: .claude/skills/rafa-okf/SKILL.md :: authored files pass rafa okf check as written — body links are markdown (never wikilinks); emit-owned sections untouched"
 ---
@@ -62,6 +62,22 @@ whole-codebase read happens in *your* window, not the conductor's, so the main s
 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.
 
+**Structured return (wave 5).** A build-execution report ends with the machine
+block the conductor assembles Logs from — never re-paraphrased prose:
+
+```json
+{ "filesChanged": ["path", "…"], "commitSha": "…",
+  "notes": "one-paragraph what/why",
+  "factsDiscovered": ["SF-n banked: <claim>", "…"] }
+```
+
+**Session facts (wave 5 — read first, bank once).** Before re-deriving any
+environment/tooling fact, read `.rafa/session-facts.json` (`rafa facts`) and
+cite `SF-<n> unchanged` when it holds. When YOU verify something expensive
+(a harness exists, an install works, an env constraint), bank it once:
+`rafa facts add --claim="…" --command="…" --exit=N [--depends=a,b]` — the next
+spawn inherits it instead of re-learning it.
+
 ## The brain is your index, once it exists
 Generic at provision-time, repo-aware after the scan: **if a brain exists at
 `.rafa/brain/`, consult it as your index before re-reading code** — route via its cited
@@ -91,7 +107,9 @@ Never act cold; never over-load.
   *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 [the scan skill](../skills/rafa-scan/SKILL.md) step 4.)
 - **Toolbox-first execution (automatic — never an offer).** Before implementing any
-  task step, CHECK the repo's installed toolbox — committed `.claude/skills/`,
+  task step, CHECK the repo's installed toolbox — committed `.claude/skills/`, the
+  **harness-neutral `.agents/skills/`** (consent-installed skill dependencies —
+  tdd, frontend-design, vercel-composition-patterns are yours to INVOKE),
   `.mcp.json` servers, commands — for a capability that already does it, and INVOKE
   it (Skill tool / MCP) instead of hand-rolling. The conductor passes the matching
   inventory slice in your spawn prompt; consult it first. Only what is actually

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

@@ -1,6 +1,6 @@
 ---
 name: bloom
-version: 0.8.1
+version: 0.9.0
 model: opus   # a false flag mutes the whole ledger — best model, never cheap
 groundTruth: code-trend
 description: >-
@@ -13,7 +13,7 @@ description: >-
 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"
+  - "improve-pass :: .claude/skills/rafa-improve/SKILL.md :: cited · prioritized P0–P3 · the architecture lens applies the deletion-test/depth method with its vocabulary (Confidence-lined candidates, first-slice-or-backlog, never big-bang) · 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"

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

@@ -1,6 +1,6 @@
 ---
 name: prism
-version: 0.7.1
+version: 0.9.0
 model: opus   # the trust anchor — a hallucinated verdict/finding is the worst failure; best model, never cheap
 groundTruth: code-vs-claim
 description: >-
@@ -14,8 +14,8 @@ 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"
+  - "plan-gate :: .claude/skills/rafa-plan/SKILL.md :: PASS = every task grounded in brain + code (none hallucinated) · every child's Done-check present AND non-vacuous (grilled per validation_tier — light = invariants only · standard = bounded probes · full = the whole interview) · TDD-eligible code tasks name their seam in the 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 · TDD tasks: green re-run live, red per tier (static-attested at standard, worktree re-run at full) · findings labeled Critical/Important/Minor — ITERATE iff any Critical or Important, Minor never flips the verdict; 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"
   - "okf-surface :: .claude/skills/rafa-okf/SKILL.md :: every checker LINKS warn judged (unwritten knowledge vs typo) — never ignored, never auto-failed"
 ---
@@ -37,6 +37,45 @@ brain as a trusted index, whatever you are validating is the thing on trial —
 against the code (ground truth) and the stated acceptance criteria. Trust nothing in
 it until you've confirmed it.
 
+**Tool authenticity (wave 5 — the npx-placeholder trap).** A tool result is
+evidence ONLY if the tool actually ran: name the binary (path or resolved
+command) and the REAL exit code. `npx <name>` can silently resolve a joke/
+placeholder package and "pass" — a class that already produced one fabricated
+verdict in the field. If you cannot execute the check (no keys, no deps, no
+env), the claim is `method: "static"` — say so in the same breath, never
+smooth it into an unqualified PASS. Fabricating a `live` result is the one
+unforgivable failure: the whole trust model prices from it.
+
+**Structured return (wave 5).** Your report ends with the machine block the
+conductor assembles Logs and loop events from — never re-paraphrased prose:
+
+```json
+{ "verdict": "PASS|ITERATE",
+  "evidence": [{ "claim": "…", "method": "static|live", "tool": "…", "exitCode": 0 }],
+  "residualRisk": "what was NOT proven, named — or the explicit empty string" }
+```
+
+The `evidence` entries feed `report_loop_event.verification` verbatim; the
+static-vs-live split is structural, not prose discipline.
+
+**Bounded invariant citation (wave 5 — no-redundant-reverification).** An
+invariant YOU (or a prior prism pass this plan) verified once is citable as
+`SF-<n> unchanged` **iff** `.rafa/session-facts.json` shows its `dependsOn`
+untouched since its verifying sha (the session-start digest surfaces staleness;
+`rafa facts` lists it). Re-deriving an unchanged, evidence-backed fact is waste,
+not rigor. The bound is hard: anything NOT in the facts file — and everything
+about the artifact under test itself — stays trust-nothing. **Invalidation is
+NOT transitive** (dependsOn is intersected with the diff, imports are never
+walked — pinned by test): trust a fact only as far as its declared breadth, and
+when a fact you rely on spans a subsystem whose dependsOn names single files,
+treat it as under-declared — re-verify instead of citing it.
+
+**Validation tier (wave 5).** A task's `validation_tier` (plan §7) bounds your
+RE-DERIVATION DEPTH — how much surrounding context you re-read and re-prove:
+light = the Done-check itself + direct evidence · standard = + the touched
+files' immediate seams · full = unbounded re-derivation. The Done-check gate
+NEVER relaxes at any tier, and your emitted loop event carries the tier it ran at.
+
 ## 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-

package/blueprint/.claude/agents/sage.md

@@ -1,6 +1,6 @@
 ---
 name: sage
-version: 0.3.0
+version: 0.4.0
 model: opus   # a wrong learning re-shapes an agent for every repo — best model, never cheap
 groundTruth: sessions-over-time
 description: >-

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

@@ -1,5 +1,5 @@
 ---
-version: 2.0.2
+version: 2.2.0
 description: rafa — the repo's engineering SOP. Use whenever the dev wants to plan a feature or change, build/execute against the active plan, improve code health, or ground work in the repo's brain — intent counts, the dev does NOT need to type /rafa. Also explicit: /rafa <init|scan|improve|plan|build|push|leverage|migrate|update|help> [--brain-only]. Admin verbs (init/scan/push/migrate/update) run ONLY when explicitly invoked.
 ---
 
@@ -59,10 +59,15 @@ MCP tools, checkpoints, pushes, decisions logging — is AGENT-INTERNAL machiner
 dev speaks intent; YOU run the machinery. Never instruct the dev to run a command you
 can run yourself. The only human acts: init (provision) · `npx rafa pull` (once per
 clone) · ci-setup approval · npm publish. **Toolbox is a recall surface:** at bootstrap,
-load the committed toolbox (`.claude/skills/`, `.mcp.json`, commands) alongside brain
-status; pass the matching slice into every atlas/bloom spawn prompt — agents USE the fit
-capability instead of hand-rolling (only what's installed, never guessed; personal
-`~/.claude/` stays live-recommend-only). **Actor envelope:** stamp `actorMeta {model,
+load the committed toolbox — `.claude/skills/` (this harness) **and
+`.agents/skills/` (the HARNESS-NEUTRAL third-party skills — one convention
+Claude Code · Codex · Cursor all read; installed by `rafa update` with
+consent, wave 6)** — plus `.mcp.json` and commands, alongside brain status
+(`rafa leverage --json` is the deterministic read); pass the matching slice
+into every atlas/bloom spawn prompt — agents USE the fit capability instead of
+hand-rolling (only what's installed, never guessed; a DECLINED skill dep means
+the SOP's fallback path, never a nag; personal `~/.claude/` stays
+live-recommend-only). **Actor envelope:** stamp `actorMeta {model,
 agent, runner: "session"}` on every state-plane write (checkpoints, plan pushes,
 decisions, reports) and export `RAFA_ACTOR_MODEL` before CLI calls — the platform records
 WHO/WHAT executed; "unreported" when unknown, never guessed.
@@ -240,14 +245,20 @@ explicitly typed; an ACCEPTED boundary offer counts as the explicit invocation.
 
 ## sage — the silent L5 observer (runs IMPLICITLY, zero-command; owner 2026-07-13)
 
-Devs never type `/rafa sage`. **Trigger:** at completion boundaries — build final-verify ·
-distill close · bootstrap — when new loop events exist since the learnings ledger's newest
-entry, spawn sage per [rafa-sage](../skills/rafa-sage/SKILL.md); announce ONE line, proceed;
-its proposals ride the NEXT bootstrap digest. Writing proposals is the just-do rung; the
-consent moment is ACCEPTING one (accepted = a versioned, MR-reviewed card/SOP edit — proposals
-never self-apply). `/rafa sage` is the explicit override. Full mechanics (≥10-event threshold,
-`get_loop_events` shape read, scrub step, ledger schema, the person-free/asset-free creed) live
-in the skill.
+Devs never type `/rafa sage`. **Trigger — MECHANICAL as of wave 5 (owner
+2026-07-25):** the SessionStart digest computes it — a `[rafa · sage] sage due:
+N loop events…` line (the checkpoint-written loop-event cache vs the learnings
+ledger, compared locally). **When that line is present, spawning sage at the
+next completion boundary — build final-verify · distill close · bootstrap — is
+a MUST, not a judgment call**: the line IS the trigger condition already
+evaluated; a discretionary trigger is how sage never fired organically. Spawn
+per [rafa-sage](../skills/rafa-sage/SKILL.md); announce ONE line, proceed; its
+proposals ride the NEXT bootstrap digest. No digest line = not due (skip
+silently). Writing proposals is the just-do rung; the consent moment is
+ACCEPTING one (accepted = a versioned, MR-reviewed card/SOP edit — proposals
+never self-apply). `/rafa sage` is the explicit override. Full mechanics
+(≥10-event threshold, `get_loop_events` shape read, scrub step, ledger schema,
+the person-free/asset-free creed) live in the skill.
 
 ## migrate · update — brain-side schema migration (no skill; the intelligence-only half)
 

package/blueprint/.claude/rafa/contract.md

@@ -382,6 +382,7 @@ blocked_by: [payments-c2] # optional · item ids this waits on — a dependency
 blocked_reason: "vendor sandbox access" # optional · external blocks (no dependency id to point at)
 priority: 2 # optional · 0 none · 1 urgent · 2 high · 3 medium · 4 low (Linear scale)
 estimate: 3 # optional · points (Linear estimate / Jira story points)
+validation_tier: standard # optional · light|standard|full — bounds prism's re-derivation DEPTH only (wave 5); the Done-check gate itself never relaxes. Planner assigns from blast radius: contract/state/graph surface → full · types/docs/leaf-UI → light · default standard
 branch: feat/webhooks # optional · ↔ Linear branchName
 baseSha: abc123 # optional · commit it was cut from
 domains: [payments] # optional · EPIC only · the blast radius — the brain link
@@ -573,12 +574,17 @@ state**, marked by `envelope.plane: "state"`:
 | `resolve_working_file`                                                                 | branch working set                                      | `distilled` / `refuted` (+ cited note) at merge-to-main distillation; `keep-current` for adjudication decisions; CAS on status — a racing distill fails loudly                                                                                                                                                                                                       |
 | `fold_working_set`                                                                     | branch working set                                      | branch→parent-branch MECHANICAL fold (no LLM, no prism — rigor only at main): absent → re-keyed · identical → merged · divergent → `needs-adjudication` on the parent row                                                                                                                                                                                            |
 | `push_plan` / `list_plans` / `update_plan_status` / `set_active_plan` / `log_decision` | **plans** — (repo) work objects                         | the push-on-approval channel (§7 v2): approval pushes the whole work-item TREE (items[], bodies stored); `list_plans` = names only; statuses push back (5-value enum — blocked is derived); `log_decision` records the deliberation trail (paraphrase + pivotal quotes); the active pointer is explicit, never inferred                                              |
+| `patch_plan_item`                                                                       | plans (one item)                                        | wave 5.2 — field-level patch on ONE item (no full-tree resend): provided fields replace, absent stay; CLEARING a field and any STRUCTURE change (kind/parent/add/remove/domains/external/merged) remain `push_plan`-only, so "a vanished optional field must not survive" keeps holding at tree granularity; snapshot-before-change rides noteRevisions like a re-push |
+| `checkpoint_task`                                                                       | plans + loopEvents + planDecisions (**ONE transaction**) | wave 5.2 — the ONE-beat boundary write: optional item patch + the loop-event ruling + decision records land atomically (all-or-nothing; `mcp.call` is an action, so composing the separate tools can never be atomic — this is one internalMutation). Idempotent end-to-end (patch no-ops on same values · loop event dedupes on `dedupeKey` · decisions dedupe on client-stable ids). The embedded loopEvent obeys `report_loop_event`'s exact rules — one rulebook, no side door. `checkpoint_sync` stays separate: per-file CAS partial-accept is a different failure model than an atomic beat |
 | `report_improvement_status`                                                            | **events only** — no store                              | a LIVE session signal (bloom's fixed-in-passing during build). The improvement ledger row is untouched — it has ONE writer, the ingest (K1); the platform overlays the report as pending-reconciliation until the next brain push confirms it                                                                                                                        |
 | `reconcile_claim`                                                                      | **reconciliations queue** — (repo) run rows            | executor claim (`plane:"state"`): ACID no-running-sibling assert → returns the attempt token; delegates to `reconciliations.claim`; stamps the actor envelope `{model, agent, runner}` (runner ∈ `sandbox`\|`ci`\|`session`, enum-checked at the boundary) on the row                                                                                          |
 | `reconcile_heartbeat`                                                                   | reconciliations queue                                   | extends the wall-clock lease + sets the phase; **attempt-fenced** (a non-current attempt is rejected, nothing written); actor envelope re-stamped                                                                                                                                                                                                                    |
 | `reconcile_log_append`                                                                  | **reconciliationLogs** — the run log tail               | batched chunks, **secret-screened PER LINE** (the same `looksLikeSecret` screen — a credential chunk is rejected by chunk/line index, nothing stored or echoed) + **attempt-fenced**; `seq`-ordered; UNLOGGED (emits its own `reconcile.log` event, counts only)                                                                                                       |
 | `reconcile_report`                                                                      | reconciliations queue (+ knowledge node on success)     | terminal outcome + node delta + meter; **attempt-fenced**; success COMPOSES the pointer advance atomically (insert node + move pointer, one mutation); refutation/deletion ride the success outcomes; actor envelope stamped                                                                                                                                          |
 | `list_working_sets`                                                                     | branch working set (**READ**)                           | enumerates branches with LIVE candidate rows + counts only (no bodies) — closes the 07-14 sensor gap (`get_working_set` needs a branch arg; nothing listed them); feeds the SessionStart digest pending line                                                                                                                                                         |
+| `report_loop_event`                                                                     | **loopEvents** — the loop-outcome ledger (sage's evidence) | ONE structured outcome per ruling, shapes only (enum category + per-category enum outcome + `subject` shape ref, secret-screened). Wave 5 trust plane, STRICT (no legacy path): **required actor envelope** `{model, agent, runner ∈ sandbox\|ci\|session}` (mechanical CLI emits use `model:"mechanical"`); **required `verification {method: static\|live, tool?, evidence?}`** on `prism-verdict`/`gate-result`/`review-verdict` — the static-vs-executed distinction is structural, never prose; optional `dedupeKey` (≤120) makes the emit **idempotent** (same `(repo, key)` never lands twice — response says `deduped`) and `tier ∈ light\|standard\|full` records the §7 `validation_tier` the ruling ran at |
+| `get_loop_events`                                                                       | loopEvents (**READ**)                                   | newest-first shape read (optional category filter, limit ≤500): category/outcome/subject + actorMeta/verification/dedupeKey/tier + at — no bodies, no code; sage splits miss patterns by verification method, actor, and tier                                                                                                                                          |
+| `report_learning`                                                                       | **agentLearnings** — sage's summary-row mirror          | sage ONLY (wave 4.1): mirrors the SUMMARY ROW of one committed ledger entry (`.claude/rafa/learnings/<id>.md` stays the single truth, MR-gated, never self-applied). Asset-free ENFORCED server-side: enum status/leverage/categories, `.claude/`-only diff target, length caps, code-fence + secret screens; upsert by id                                                                                                          |
 
 State tools work with or without an ingested brain (a working set can exist —
 and a plan can be pushed — before the first scan) and are exempt from the

package/blueprint/.claude/rafa/hooks/brain-commit.mjs

@@ -181,6 +181,10 @@ try {
       // rafa review's scored-ranges artifact (wave 2.3) — regenerated per
       // review, machine state like distill-verdicts; never brain knowledge.
       "review.json",
+      // wave 5: session-scoped machine state — memoized verification + the
+      // checkpoint-written loop-event cache the sage-due digest reads.
+      "session-facts.json",
+      "loop-events-tail.json",
     ];
     const gi = join(rafa, ".gitignore");
     const cur = existsSync(gi) ? readFileSync(gi, "utf8") : "";

package/blueprint/.claude/rafa/hooks/session-start.mjs

@@ -300,6 +300,72 @@ try {
     }
   }
 
+  // Session facts (wave 5.4 — memoized verification): banked verified facts +
+  // mechanical staleness (dependsOn ∩ git diff since the verifying sha, working
+  // tree included). Spawned agents read the file FIRST and cite "SF-n unchanged"
+  // instead of re-deriving. Local reads only — no platform call.
+  {
+    const doc = readJson(join(rafaDir, "session-facts.json"));
+    if (doc?.schemaVersion === 1 && Array.isArray(doc.facts) && doc.facts.length) {
+      let stale = 0;
+      for (const f of doc.facts) {
+        try {
+          const changed = execSync(`git diff --name-only ${f.verifiedAtSha}`, {
+            cwd: root,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+          })
+            .split("\n")
+            .filter(Boolean);
+          if (
+            (f.dependsOn ?? []).some((p) =>
+              changed.some((c) => c === p || c.startsWith(p.endsWith("/") ? p : p + "/")),
+            )
+          )
+            stale++;
+        } catch {
+          stale++; // unknown sha — fail-honest, count it stale
+        }
+      }
+      lines.push(
+        `[rafa · facts] ${doc.facts.length} session fact(s) banked (.rafa/session-facts.json — spawned agents read it FIRST and cite "SF-n unchanged" instead of re-deriving)` +
+          (stale ? ` · ${stale} STALE — re-verify or \`rafa facts prune --stale\`` : ""),
+      );
+    }
+  }
+
+  // Sage-due bridge (wave 5.5 — mechanical detection): the checkpoint-written
+  // loop-event cache vs the learnings ledger, compared LOCALLY (zero platform
+  // calls). Sage's trigger was a discretionary end-of-session SOP step and
+  // never fired organically — detection now lands front-of-session where
+  // reminders get obeyed; only the SPAWN stays with the conductor.
+  {
+    const cache = readJson(join(rafaDir, "loop-events-tail.json"));
+    if (cache?.schemaVersion === 1 && Array.isArray(cache.events)) {
+      let ledgerAt = null;
+      const ledgerPath = join(root, ".claude", "rafa", "learnings", "ledger.md");
+      if (existsSync(ledgerPath)) {
+        const m = readFileSync(ledgerPath, "utf8").match(
+          /^-\s*Generated:\s*([0-9]{4}-[0-9]{2}-[0-9]{2}(?:[T ][0-9:.Z+-]+)?)/m,
+        );
+        if (m) {
+          const t = Date.parse(m[1]);
+          if (Number.isFinite(t)) ledgerAt = t;
+        }
+      }
+      const fresh =
+        ledgerAt == null
+          ? cache.events
+          : cache.events.filter((e) => Number.isFinite(e.at) && e.at > ledgerAt);
+      if (fresh.length >= 10)
+        lines.push(
+          `[rafa · sage] sage due: ${fresh.length} loop events since the last learnings pass` +
+            (ledgerAt == null ? " (no ledger yet — sage has never run here)" : "") +
+            ` — spawn sage at the next completion boundary (zero-command; this line is the trigger, not a suggestion).`,
+        );
+    }
+  }
+
   // Benchmark liveness (harness-arc: the proof engine is workflow-woven, never a
   // dev-typed command) — a scanned brain with no MEASURED benchmark is a gap the
   // scan SOP's Prove-it step closes. Absence sensor only; never a nag mid-flow.

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).