@rafinery/cli 0.8.16 → 0.11.0

package/CHANGELOG.md

@@ -4,6 +4,136 @@ 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.11.0 — schema-aware reconciliation (the 4-case ladder)
+
+Distillation is where knowledge from two lineages meets — so it is now also
+where brain SCHEMA VERSIONS meet. Before any claim-level judging, the
+reconciler resolves target (the org brain) vs source (the branch's candidates)
+vs the runner's own latest schema:
+
+1. **target < source** → full target-brain rewrite onto the newer schema,
+   riding the same run's gates + push (one migration+reconcile commit).
+2. **target > source** → incoming old-schema candidates lift into the
+   target's schema before judging.
+3. **target == source, both < latest** → the merged target rewrites onto the
+   runner's latest.
+4. **target == source == latest** → plain diff reconcile — the happy flow,
+   exactly as before.
+
+Either side NEWER than the runner aborts loudly — 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 version line; derived/generated files regenerate
+at the new schema, they never migrate); a missing step or class fails
+loudly — the ladder never guesses a schema. v1 is the only schema in existence, so today
+every reconcile is case 4; this ships the SEAM (fully tested) that turns a
+future v2 into a one-entry registry change instead of a migration crisis.
+
+**Descriptive commits (owner 2026-07-26).** Reconciliation commits now SAY
+what the run did: the headless distiller composes
+`reconcile(<branch>): N banked · M refuted · K adjudication — <ids…>` and
+passes it via the new `rafa push --message=` override (the brain-for trailer
+is untouched — provenance consumers keep their key); the session SOP carries
+the same rule. And the commit contract (rafa-commit) now REQUIRES an
+agent-readable body on dev commits: what concretely changed, the why the diff
+can't show, brain-note join keys, no session deixis — the next reader of a
+commit is usually an agent.
+
+**The configurable prod branch reaches the CLI.** `trunkBranchOf` resolves
+the stamped `rafa.json → prodBranch` → git's origin/HEAD → "main"; the
+checkpoint trunk guard and the CI distill target use it (with prodBranch set,
+"main" can be a plain feature-carrying branch). The platform side shipped the
+`repos.prodBranch` setting + repo-page card in the same arc.
+
+Also in this release (landed after 0.10.0's publish): distill-refutation loop
+events carry the required actor envelope + a dedupeKey (a retried distill
+counts each resolution once); `cliActorMeta` honors `RAFA_ACTOR_RUNNER` for
+sandbox/CI attribution; and dependsOn invalidation is documented as NOT
+transitive, with breadth-of-declaration taught as the conservative pattern at
+`rafa facts add`, the CLI help, and prism's citation rule (pinned by test).
+
+## 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
@@ -454,6 +455,23 @@ imported comments are never scraped into decisions.
   fields do NOT bump it** — e.g. the note size stamps (`bodyTokens`,
   `cites[].targetTokens`, §1): ingest tolerates their absence, so a legacy manifest
   without them stays valid at the same `schemaVersion`.
+- **The reconciliation schema ladder (0.11.0 — owner's 4-case doctrine).** When a
+  version bump DOES ship, distillation is the upgrade moment — the reconciler
+  resolves target-vs-source-vs-runner before judging: target below source → full
+  target rewrite onto the newer schema; source below target → incoming candidates
+  lift before judging; both equal-but-old → the merged target rewrites onto the
+  runner's latest; both current → plain diff (today). Either side newer than the
+  runner → **abort loudly** (update the runner; knowledge is never downgraded).
+  Transforms are registered per step AND per OKF type in the CLI
+  (`lib/distiller/schema-ladder.mjs`): each step declares rule · playbook · improvement
+  explicitly — a function, or the EXPLICIT `"unchanged"` (still re-stamps the note's
+  `schemaVersion:`); an unregistered step or class fails loudly — the ladder never
+  guesses a schema. Class resolves by CHAIN: the governed directory first (inside the
+  transport the path IS identity — the CAS row key), then the portable filename suffix
+  (`.rule.md` · `.playbook.md` · `.improvement.md`) for files travelling outside the
+  canonical tree; a contradiction between the two is a loud error. Only durable
+  knowledge migrates; derived/generated files
+  (coverage · checklist · ledger · reports · the manifest) regenerate at the new schema.
 - **Validate-and-correct:** `rafa compile` validates every file. On failure it emits
   a structured error — `path · field · rule` — to the **authoring agent** (atlas for
   notes, bloom for improvements/ledger, prism for checklist). The agent edits the
@@ -573,12 +591,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.