@rafinery/cli 0.8.12 → 0.8.14

package/bin/rafa.mjs

@@ -53,6 +53,8 @@ const COMMANDS = [
   "ci-setup",
   "leverage",
   "benchmark",
+  "manifest",
+  "review",
   "migrate",
 ];
 const [cmd, ...rest] = process.argv.slice(2);
@@ -72,6 +74,10 @@ Commands:
                         --keep       keep all changed owned files without asking
                         (default: ask per file; in a non-TTY it keeps them)
   compile              Validate the brain against the contract → .rafa/manifest.json.
+  manifest             The BRANCH manifest (lenient snapshot — WIP files land under
+                       drafts, never fail). You never need to run this: the post-commit
+                       brain hook regenerates it on every mirrored commit (zero-command
+                       rule). The standalone form exists for debugging a snapshot.
   verify-citations     Deterministic citation checker (v2): every cite resolves (B1),
                        every contract anchor's code occurrences are cited (B2), policy
                        holds, declared absences re-grepped (B3), coverage inventories
@@ -128,6 +134,11 @@ Commands:
                        count harness tokens, emit a MEASURED benchmark.json. --dry-run
                        exercises the scaffold from fixture counts; --help documents the
                        agent-driven run procedure. Measured — never the estimated baseline.
+  review               Brain-grounded review pre-pass (deterministic, zero LLM): the
+                       diff's changed lines ∩ the brain's cite graph → the exact rules/
+                       improvements the change touches (.rafa/review.json + summary).
+                       The rafa-review SOP's judge then rules on precisely that list —
+                       generic "review this PR" never happens. Advisory; never blocks.
   migrate              Bring this repo's structured files (plans, config) up to the schema
                        the installed CLI ships. Idempotent; review the diff after.
 

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

@@ -105,6 +105,19 @@ try {
     /* not a merge / rev-list unavailable — normal 1-1 path */
   }
 
+  // The BRANCH MANIFEST (harness-arc wave 1, manifest-as-handoff): every brain
+  // commit carries a lenient snapshot of the branch's knowledge state, so the
+  // reconciler (or any agent) reads "what this branch believes" at any ref.
+  // Delegated to the CLI (`rafa manifest` — okf-parsed, never a second parser);
+  // best-effort + bounded: a missing/slow CLI must never block a code commit.
+  try {
+    const localRafa = join(ROOT, "node_modules", ".bin", "rafa");
+    const runner = existsSync(localRafa) ? `"${localRafa}"` : "npx -y @rafinery/cli";
+    sh(`${runner} manifest`, ROOT, 30000);
+  } catch {
+    /* snapshot skipped — the reconciler treats a stale/absent branch manifest as null */
+  }
+
   // The intent record — the commit's end-to-end intent, mechanically joined.
   // Minimal here (sha · subject · files); the P3 capture worker enriches.
   const fullSha = sh("git rev-parse HEAD");
@@ -129,6 +142,33 @@ try {
       `\n`,
   );
 
+  // Local-state exclusion (owner 2026-07-24): the hydration sidecar + sensor
+  // queues are MACHINE state, never knowledge — ensure the ignore entries and
+  // UNTRACK anything an earlier CLI's window let git track (a .gitignore entry
+  // alone never untracks; `git add -A` would keep committing it forever).
+  // Best-effort: exclusion must never block a code commit.
+  try {
+    const LOCAL_STATE = [
+      "hydration.json",
+      "dirty.jsonl",
+      "reflex.jsonl",
+      "sensor-errors.jsonl",
+      "distill-verdicts.json",
+      "benchmark.demo.json",
+    ];
+    const gi = join(rafa, ".gitignore");
+    const cur = existsSync(gi) ? readFileSync(gi, "utf8") : "";
+    const have = new Set(cur.split("\n").map((l) => l.trim()).filter(Boolean));
+    const missing = [...LOCAL_STATE, "*.theirs.md", "distill-incoming/"].filter((l) => !have.has(l));
+    if (missing.length)
+      writeFileSync(gi, cur + (cur === "" || cur.endsWith("\n") ? "" : "\n") + missing.join("\n") + "\n");
+    for (const p of LOCAL_STATE) shR(`git rm -q --cached --ignore-unmatch "${p}"`);
+    shR('git rm -q -r --cached --ignore-unmatch distill-incoming');
+    shR('git rm -q --cached --ignore-unmatch "*.theirs.md"');
+  } catch {
+    /* exclusion is best-effort */
+  }
+
   shR("git add -A");
   disposeHydrations(branch);
   shR(

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

@@ -300,6 +300,16 @@ try {
     }
   }
 
+  // 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.
+  const hasBrain = existsSync(join(rafaDir, "brain", "rules"));
+  const measuredBenchmark = readJson(join(rafaDir, "benchmark.json"))?.measured === true;
+  if (hasBrain && !measuredBenchmark)
+    lines.push(
+      `[rafa · benchmark] no measured token-proof for this repo yet — the next /rafa scan runs the Prove-it step (brain-vs-cold, harness-counted) automatically.`,
+    );
+
   // Suggested next — ONE deterministic recommendation, ranked by consequence:
   // a teammate blocked by a conflict > an unbanked correction > resuming the
   // active plan > staleness repair. Guidance is front-loaded here (and ambient

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

@@ -19,6 +19,7 @@ platform MCP (one read path — the same surface any third-party agent uses).
 | **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) |
 | **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 |
 
 ## Procedure
 
@@ -26,6 +27,11 @@ platform MCP (one read path — the same surface any third-party agent uses).
    (envelope `brainForSha` vs local stamp → prompt `rafa push` if behind). MCP
    recall is automatic throughout — SOP-driven, never dev-invoked; a repo without
    the `rafinery` MCP connected falls back to local `.rafa/` file reads.
+   **On a feature branch, pass `branch: <current git branch>` to
+   search_knowledge/get_rule/get_playbook/get_improvement** — recall then
+   overlays the branch's live working set on canon, every non-canonical result
+   tier-labeled (the alert rule: a `source: {tier: "candidate"}` or
+   `branchOverlay` is branch state, not org truth — say so when you rely on it).
    **Session consent (asked ONCE, verbs ENUMERATED):** *"keep the platform
    updated as I work? That means exactly: (1) plan status + Log pushes on
    cadence, (2) checkpointing this branch's working set (edited/new brain
@@ -33,7 +39,10 @@ platform MCP (one read path — the same surface any third-party agent uses).
    anytime ("stop pushing"). On "no": journal locally only, push at the end on
    approval. Dev-level insights are NEVER under this consent — each is its own
    offer.
-2. **Per task:** atlas recalls → implements → prism validates vs `## Done-check` →
+2. **Per task:** atlas recalls → implements → **commits use the
+   [rafa-commit](../rafa-commit/SKILL.md) format — `[<task-id>] <type>:
+   <subject>` (the id join-key; intent records + the branch manifest lift it
+   into per-note provenance)** → prism validates vs `## Done-check` →
    bloom sweeps (push new / close fixed / nudge) → update the child file's `status`
    **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
@@ -69,14 +78,28 @@ platform MCP (one read path — the same surface any third-party agent uses).
    - **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
-     affected note (`rafa hydrate <rule|playbook> <id>`) and edit it, or author
-     a new note file under `.rafa/brain/**` — `rafa checkpoint` syncs it. It
+     affected note (`rafa hydrate <rule|playbook|improvement> <id>`) and edit
+     it, or author a new note file under `.rafa/brain/**` — `rafa checkpoint`
+     syncs it. Ledger status edits (bloom's `fixed`) ALWAYS hydrate first. It
      enters the org brain at merge-to-main, through distillation. This is the
      knowledge-propagates-like-code rule, enforced.
    The working-set files ARE the sanctioned branch authoring surface — what is
    never allowed is editing main's brain around the scan/compile/push gates.
-4. **Verify** (prism-style) before declaring the plan done; final `push_plan` +
-   `set_active_plan` (clear) + `rafa checkpoint`. A plan that stops being worth
+   **Gap close-out:** authored knowledge that answers an in-scope knowledge
+   gap (adopted at plan time via `get_knowledge_gaps`) closes the loop —
+   `set_gap_status(q, "closed")` at the same beat the note is authored.
+4. **Verify** (prism-style) before declaring the plan done — including the
+   [rafa-review](../rafa-review/SKILL.md) gate: `rafa review` scopes the exact
+   rules/improvements the branch's diff touches; the judge rules on that list
+   + each Done-check, emits `review-verdict`; final `push_plan` +
+   `set_active_plan` (clear) + `rafa checkpoint`. **Dual status (single/double
+   tick):** `status: done` is the dev ✓ — prism-earned, session-set, for
+   leaves AND the epic (the epic's ✓ = every leaf verified done). DELIVERY is
+   the separate ✓✓: the platform stamps `merged` per item when the branch
+   merges to main (the reconciliation is the receipt; sessions can never
+   write it; intermediate merges re-point the plan to the target branch so
+   stacked branches converge). The board shows "awaiting merge" between ✓ and
+   ✓✓. A plan that stops being worth
    finishing closes honestly: `superseded` or `abandoned`, never fake-`done`.
    Plan-done is also a **staleness boundary**: read `rafa dirty --json` — if the
    build's edits dirtied notes this session didn't already refresh, surface the

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

@@ -0,0 +1,45 @@
+---
+name: rafa-commit
+description: "rafa SOP — generate the commit message with the id join-key: the active task id rides the subject ([task-id] type: subject), making commit → task → plan → brain-delta lineage mechanical. Loaded at commit moments during /rafa build or on request."
+---
+
+# commit — the id join-key  (the commit contract)
+
+> Status: **active.** The commit message is a JOIN KEY, not prose: the task id
+> in the subject is what lets the platform walk rule ← commit ← task ← plan
+> mechanically (intent records capture the subject per commit; the branch
+> manifest lifts task ids into per-note `provenance.tasks`). Invoked at commit
+> moments in /rafa build, or explicitly.
+
+## The format
+
+```
+[<task-id>] <type>: <subject>
+
+<body — what and why, wrapped>
+```
+
+- `<task-id>` — the ACTIVE plan item this commit advances (the in-progress
+  leaf from `get_active_plan` / local `active.md`). Exactly one; the deepest
+  in-progress leaf wins when nested. Work outside any plan (direct-do) omits
+  the bracket entirely — `<type>: <subject>` — never a fake id.
+- `<type>` — conventional: feat | fix | refactor | perf | test | docs | chore.
+- `<subject>` — imperative, ≤ 72 chars including the bracket.
+
+## Procedure
+
+1. Resolve the active task: `get_active_plan` (platform) or `active.md` +
+   child statuses (local). No active plan / no in-progress leaf → no bracket.
+2. Compose from the STAGED DIFF (never from memory of the session): what
+   changed, why, in the repo's own voice.
+3. On task completion commits, the body's last paragraph notes the Done-check
+   outcome one-line ("Done-check: prism PASS") — the receipt travels with the
+   code.
+
+## Why this exists (don't skip the bracket)
+
+The brain-commit hook captures every subject into `intent/<sha>.md`;
+`rafa manifest` parses `[task-id]` back out into each note's
+`provenance.tasks`. Skip the bracket and the lineage chain (rule ← commit ←
+task ← plan) breaks at its first link — the platform can still join
+plan ↔ merge via the branch, but per-task attribution is lost for that commit.

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

@@ -25,7 +25,16 @@ Planning is a choreography, not one agent (spec: knowledge-mcp-build-agent):
   knowledge, just unserved.*
 - **bloom pulls** — `list_improvements` in the blast radius; surface the
   top-leverage open items as optional *"while-you're-here"* child tasks
-  (leverage-ranked, dismissible, never blocking).
+  (leverage-ranked, dismissible, never blocking). **Any improvement the plan
+  ADOPTS (as a task or the plan's very subject) is hydrated NOW** —
+  `rafa hydrate improvement <id>` — so the canonical ledger file is in the
+  branch working set from the start and the eventual `status: fixed` edit lands
+  on that same file, never a path-drifted twin authored at build's end.
+  **Also pull `get_knowledge_gaps`** (the open backlog — what devs asked that
+  the brain couldn't serve): a top-missed gap inside the blast radius is live
+  demand — offer it as a while-you're-here task; on adoption call
+  `set_gap_status(q, "in-scope")` (and `out-of-scope` with a one-line note is
+  an honest dismissal — silence is not).
 - **prism validates the plan itself** — before the approval gate: is every task
   grounded in real brain/code (not hallucinated ground)? does every child carry a
   `## Done-check` (the expected outcome prism will validate execution against)?
@@ -37,7 +46,14 @@ Planning is a choreography, not one agent (spec: knowledge-mcp-build-agent):
 1. **Staleness check** — compare the platform envelope's `brainForSha` against the
    local brain stamp; if the platform is behind, surface "run `rafa push`" (never
    proceed silently on knowledge you know is stale — never block either).
-2. **Recall** (atlas, via MCP) → **decompose** into the WORK-ITEM TREE (contract
+2. **Recall** (atlas, via MCP) — `get_coverage` now carries **`recentDeltas`**
+   (the last trunk merges' knowledge changes + which plan delivered each):
+   open the plan draft with a TWO-LINE BRIEFING of what changed in the blast
+   radius since it was last touched — planning starts from the deltas, never a
+   stale mental model. `search_knowledge` may return a **`decisions`** block
+   (prior recorded calls matching the query): read it BEFORE re-litigating a
+   settled decision — reopening one is the owner's move, not the plan's.
+   Then **decompose** into the WORK-ITEM TREE (contract
    §7 v2): one epic → tasks → subtasks (three ranks, never deeper). Every item
    carries the glimpse fields — `title` (what) · `description` (why) ·
    `approach` (how, one line) · `assignee` when known · `blocked_by` for
@@ -54,7 +70,11 @@ Planning is a choreography, not one agent (spec: knowledge-mcp-build-agent):
 5. **prism plan-validation** → REJECT/fix loop until clean.
 6. **Approval gate** (owner). Then materialize `plans/<plan>/*.md` per contract §7
    (plan files ride the OKF surface — markdown links in bodies; see [rafa-okf](../rafa-okf/SKILL.md))
-   (parent + child-owned files, globally-unique prefixed ids) + `active.md` pointer
+   (parent + child-owned files, globally-unique prefixed ids; **the EPIC's
+   frontmatter stamps `branch:` = the current git branch** — the platform
+   joins merge events on this field to stamp the delivery ✓✓ (`merged`) per
+   item, and re-points it through intermediate merges)
+   + `active.md` pointer
    → `rafa compile` (validate the files) → **`push_plan` + `set_active_plan`
    immediately, no second prompt — plan approval IS the push trigger** (the
    dedicated plans channel; plans never ride the brain manifest). The dev just

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

@@ -0,0 +1,63 @@
+---
+name: rafa-review
+description: "rafa SOP — the brain-grounded review gate: `rafa review` computes the exact rules/improvements a diff touches (cite-intersection, zero LLM); a prism-style judge rules ONLY on that list + the active task's Done-check; findings feed atlas; the verdict emits a review-verdict loop event. Loaded before push/merge or on request."
+---
+
+# review — the brain-grounded gate  (harness-arc wave 2)
+
+> Status: **active.** The at-the-gate moment: defects caught BEFORE merge, by
+> the repo's own rules — not generic review taste. Depends on: brain (#1),
+> plans (#3, for the Done-check). Runs at the pre-push beat (offer, never
+> block) and on demand.
+
+Generic "review this PR" is banned here. The gate is two passes with a hard
+split:
+
+## Pass 1 — mechanical (the CLI, zero LLM)
+
+`rafa review [--json]` — diff vs merge-base(origin default) → changed line
+ranges ∩ the brain's cite graph (`get_code_context` per file):
+
+- **◆ direct** — a changed line falls inside a rule's cited anchor range: the
+  code the rule stands on MOVED. Highest priority; also a staleness signal
+  (the note may need a scoped refresh — the dirty queue already tracks it).
+- **· file** — the file changed elsewhere but the rule governs it.
+- **! open improvements** citing a touched file — is this change making the
+  debt better, worse, or is it the fix itself (then bloom's close flow)?
+
+Output: `.rafa/review.json` + summary. A bounded pass SAYS what it dropped
+(never a silent cap); a mid-pass transport failure marks the list PARTIAL.
+
+## Pass 2 — the judge (prism-style, scoped)
+
+For the work list ONLY — never the whole diff, never taste:
+
+1. Per **rule hit**: fetch the rule (`get_rule`, with `branch:` for the
+   working-set overlay) → does the diff still honor it? Judge against code +
+   rule, never against the author's claims. A `failure: silent` rule gets
+   extra scrutiny — that class never announces itself.
+2. Per **open improvement**: touched for better or worse? Fixed-in-passing →
+   bloom's close flow (hydrate first, `status: fixed`, report).
+3. **The active task's Done-check** (from `get_active_plan`): does the diff
+   satisfy what the plan said done means?
+4. Verdict: **PASS** or **ITERATE** with per-finding citations (rule id +
+   file:line). Findings feed atlas (validate-and-correct — atlas fixes, the
+   judge re-checks; the reviewer never edits).
+5. 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.
+
+## When it runs
+
+- **The pre-push beat** — before `git push`, offer the gate ("review the
+  branch against the brain? <n> rules touched"). Opt-in, advisory, never
+  blocks a push (a declined offer is honored, not re-asked this session).
+- **Plan-done verify** — rafa-build's final verify runs it as part of
+  declaring the build complete.
+- **On demand** — `/rafa review` any time.
+
+## Anti-patterns
+- Judging files the pre-pass didn't flag (scope creep = generic review).
+- 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.

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

@@ -253,7 +253,19 @@ pipeline; **`--brain-only`** stops after the brain is validated (step 5 PASS)
 6. **Improve** *(skip if `--brain-only`)* — run the improve pass ([rafa-improve](../rafa-improve/SKILL.md)):
    spawn `bloom` → `.rafa/improve/`. It reads the *validated* brain as its index, so it only
    runs after PASS.
-7. **Land it** — present the full summary (brain verdict/score + top improvements). **On the
+7. **Prove it — the measured benchmark** *(skip if `--brain-only`; skip if
+   `.rafa/benchmark.json` already carries `measured: true` for this repo)* —
+   the proof engine is WORKFLOW-WOVEN, never a dev-typed command (owner
+   2026-07-24): the conductor drives `rafa benchmark` itself right after the
+   brain PASSes — cut the two worktrees (cold vs brain; the scaffold does
+   this), run the task fixture in EACH (the conductor IS the driving loop the
+   scaffold documents), collect the harness token counts, then
+   `rafa benchmark --counts <file> --push` so the Efficiency page's
+   "measured on this repo: N×" widget carries a real row. Announce-and-proceed
+   ("measuring the brain-vs-cold token proof — say stop to skip"); a decline
+   is honored and not re-asked this session. `--dry-run` fixture numbers are
+   demo-only and can never land as proof (the handler refuses them).
+8. **Land it** — present the full summary (brain verdict/score + top improvements). **On the
    dev's explicit approval**, land the brain the way EVERY brain change lands — through the
    commit hooks, **never a direct trunk push** (the reconciler is the org brain's only writer).
    The dev MUST be on a feature branch (the post-commit hook no-ops on `main`). Then:
@@ -263,7 +275,7 @@ pipeline; **`--brain-only`** stops after the brain is validated (step 5 PASS)
    `git merge` + push — both work) → detection enqueues and the **reconciler** authors the org
    brain at the merge sha, minting the node (brain ↔ code). Do **not** run `rafa push` (retired:
    it wrote the trunk directly, bypassing the reconciler). Never land without approval.
-8. **The coach offer (founding scan only)** — if this was the repo's FIRST scan and the dev's
+9. **The coach offer (founding scan only)** — if this was the repo's FIRST scan and the dev's
    user brain is empty (`list_dev_insights` → none), offer ONCE: *"the code side is mapped —
    want me to bootstrap YOUR insights from your usage report?"* Accepted = run `## insights`
    (compass; every candidate offered, banked only on yes). The offer rung of the consent

package/lib/blueprint.mjs

@@ -38,6 +38,8 @@ export const BLUEPRINT = {
     ".claude/skills/rafa-validate",
     ".claude/skills/rafa-plan",
     ".claude/skills/rafa-build",
+    ".claude/skills/rafa-commit",
+    ".claude/skills/rafa-review",
     ".claude/skills/rafa-improve",
     ".claude/skills/rafa-distill",
     ".claude/skills/rafa-insights",

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"];
+  const IGNORES = ["hydration.json", "*.theirs.md", "distill-incoming/", "distill-verdicts.json", "dirty.jsonl", "reflex.jsonl", "sensor-errors.jsonl", "benchmark.demo.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

@@ -183,5 +183,23 @@ export default async function checkpoint() {
     `${conflicts ? "!" : "✓"} checkpoint: ${accepted}/${results.length} synced on ${branch}` +
       (conflicts ? ` · ${conflicts} conflict(s) need YOUR decision (see above)` : ""),
   );
+
+  // 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.
+  try {
+    const evts = await callTool(ROOT, "get_loop_events", {
+      category: "prism-verdict",
+      limit: 1,
+    });
+    if ((evts.events ?? []).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 */
+  }
   if (conflicts) process.exit(2);
 }

package/lib/hydrate.mjs

@@ -1,8 +1,11 @@
 // rafa hydrate — fault knowledge INTO the lazy .rafa/ instance (working-set
 // architecture, ratified 2026-07-10). Two sources, one bookkeeping rule:
 //
-//   rafa hydrate rule <id>        one org-brain note → .rafa/brain/rules/<id>.md
-//   rafa hydrate playbook <id>    one org-brain note → .rafa/brain/playbooks/<id>.md
+//   rafa hydrate rule <id>          one org-brain note → .rafa/brain/rules/<id>.md
+//   rafa hydrate playbook <id>      one org-brain note → .rafa/brain/playbooks/<id>.md
+//   rafa hydrate improvement <id>   one ledger item → .rafa/improve/improvements/<id>.md
+//       (the CANONICAL ledger path — a status edit lands on the same file the org
+//       brain carries; bloom hydrates BEFORE editing, never authors a path twin)
 //       Stamped in the sidecar with its main-brain base version (envelope
 //       brainForSha) + content hash — an UNEDITED hydration is a disposable
 //       cache `rafa checkpoint` will never push; editing it makes it working set.
@@ -21,6 +24,7 @@ import { dirname, join } from "node:path";
 import { callTool } from "./mcp-client.mjs";
 import {
   hashOf,
+  materializeImprovement,
   materializeNote,
   readSidecar,
   writeSidecar,
@@ -76,17 +80,24 @@ export default async function hydrate(args = []) {
   }
 
   const [kind, id] = args.filter((a) => !a.startsWith("-"));
-  if ((kind !== "rule" && kind !== "playbook") || !id)
-    die("usage: rafa hydrate <rule|playbook> <id>   ·   rafa hydrate --working-set");
+  if ((kind !== "rule" && kind !== "playbook" && kind !== "improvement") || !id)
+    die("usage: rafa hydrate <rule|playbook|improvement> <id>   ·   rafa hydrate --working-set");
 
   let payload;
   try {
-    payload = await callTool(ROOT, kind === "rule" ? "get_rule" : "get_playbook", { id });
+    payload = await callTool(
+      ROOT,
+      kind === "rule" ? "get_rule" : kind === "playbook" ? "get_playbook" : "get_improvement",
+      { id },
+    );
   } catch (e) {
     die(e instanceof Error ? e.message : String(e));
   }
   const brainForSha = payload.envelope?.brainForSha ?? null;
-  const rel = materializeNote(ROOT, kind, payload, brainForSha);
+  const rel =
+    kind === "improvement"
+      ? materializeImprovement(ROOT, payload, brainForSha)
+      : materializeNote(ROOT, kind, payload, brainForSha);
   console.log(
     `✓ hydrated ${kind} "${id}" → .rafa/${rel}` +
       (brainForSha ? `  (base: ${String(brainForSha).slice(0, 7)})` : "") +

package/lib/manifest.mjs

@@ -0,0 +1,208 @@
+// rafa manifest — the BRANCH manifest, lenient snapshot mode (harness-arc wave 1,
+// manifest-as-handoff, owner 2026-07-23). The trunk manifest is compile's (strict,
+// gate-fed); every mirrored BRANCH commit carries this snapshot instead so any
+// agent reading the brain repo at a ref knows exactly what that branch's knowledge
+// state is — parseable entries index normally, WIP files land under `drafts`
+// (never fail a dev's commit; strictness stays at the reconcile gate).
+//
+// ZERO-COMMAND (owner 2026-07-24): devs never run this — the post-commit brain
+// hook (brain-commit.mjs) regenerates it on every mirrored commit, exactly like
+// okf emit rides `rafa push`. The standalone form exists for debugging only.
+//
+//   rafa manifest            write .rafa/manifest.json for the current branch
+//
+// Additive contract-§1 fields (schemaVersion stays 1):
+//   mode: "branch"                       trunk manifests never carry these
+//   base: { brainSha } | null            the org-brain version most hydrations
+//                                        diverged from (hydration sidecar)
+//   drafts: [{ path, error }]            unparseable WIP files, listed not fatal
+//   per-entry provenance: { baseBrainSha?, commits[] }
+//                                        commits = CODE shas that touched the
+//                                        note (brain-commit trailers, 1-1 law)
+//
+// Parsing goes through @rafinery/okf + the distiller doctrine — never a second
+// frontmatter parser. The manifest describes what IS at a commit; the knowledge
+// node describes what HAPPENED between commits (that split is doctrine).
+
+import { execSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { parseFrontmatter } from "@rafinery/okf/frontmatter";
+import { citesOf } from "./distiller/doctrine.mjs";
+
+const SCHEMA_VERSION = 1;
+const PRIORITIES = new Set(["P0", "P1", "P2", "P3"]);
+const IMP_STATUSES = new Set(["open", "backlog", "fixed", "wontfix"]);
+
+const str = (v, fallback = "") => (typeof v === "string" ? v : fallback);
+const strArr = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === "string") : []);
+const idOfPath = (p) => (p.split("/").pop() ?? p).replace(/\.md$/, "");
+
+const toCites = (content) =>
+  citesOf(content).map((c) => ({
+    file: c.file,
+    line: c.start === c.end ? String(c.start) : `${c.start}-${c.end}`,
+    token: c.token,
+  }));
+
+function mdFilesUnder(dir) {
+  if (!existsSync(dir)) return [];
+  const out = [];
+  for (const entry of readdirSync(dir, { recursive: true })) {
+    const p = join(dir, String(entry));
+    if (p.endsWith(".md") && statSync(p).isFile()) out.push(p);
+  }
+  return out.sort();
+}
+
+export default async function manifest() {
+  const ROOT = process.cwd();
+  const rafa = join(ROOT, ".rafa");
+  if (!existsSync(join(rafa, ".git"))) {
+    console.error("✗ no .rafa brain instance here — run `rafa pull` first");
+    process.exit(1);
+  }
+  const sh = (cmd, cwd = ROOT) => {
+    try {
+      return execSync(cmd, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    } catch {
+      return "";
+    }
+  };
+  const branch = sh("git rev-parse --abbrev-ref HEAD");
+  if (branch === "main" || branch === "master") {
+    // The trunk manifest is compile's (strict) — this command is branch-only.
+    console.log("• on the trunk — the strict compile gate owns main's manifest; nothing to do");
+    return;
+  }
+  const codeSha = sh("git rev-parse HEAD");
+
+  // Hydration sidecar → per-path divergence base + the branch-level base
+  // (the most common hydration base across files; null when nothing hydrated).
+  let sidecarFiles = {};
+  try {
+    sidecarFiles = JSON.parse(readFileSync(join(rafa, "hydration.json"), "utf8")).files ?? {};
+  } catch {
+    /* no sidecar — branch-new everything */
+  }
+  const baseCounts = new Map();
+  for (const rec of Object.values(sidecarFiles))
+    if (rec?.baseBrainSha) baseCounts.set(rec.baseBrainSha, (baseCounts.get(rec.baseBrainSha) ?? 0) + 1);
+  const baseBrainSha =
+    [...baseCounts.entries()].sort((a, b) => b[1] - a[1])[0]?.[0] ?? null;
+
+  // provenance.commits — the CODE shas that touched a brain path, read off the
+  // 1-1 brain commits' `code-commit:` trailers (bounded; oldest dropped).
+  const commitsFor = (relPath) =>
+    sh(`git log -n 10 --format="%(trailers:key=code-commit,valueonly)" -- "${relPath}"`, rafa)
+      .split("\n")
+      .map((s) => s.trim())
+      .filter((s) => /^[0-9a-f]{7,64}$/i.test(s));
+
+  // The commit contract's task lift: intent/<shortsha>.md captures each code
+  // commit's subject; a `[task-id]` bracket there joins the note to the plan
+  // item that produced it (rule ← commit ← task ← plan, mechanical).
+  const taskOfCommit = (sha) => {
+    try {
+      const subject = readFileSync(join(rafa, "intent", `${sha.slice(0, 12)}.md`), "utf8")
+        .split("\n")
+        .find((l) => l.startsWith("# "));
+      return subject?.match(/^# \[([A-Za-z0-9][\w.-]*)\]/)?.[1] ?? null;
+    } catch {
+      return null;
+    }
+  };
+
+  const drafts = [];
+  const provenanceOf = (relPath) => {
+    const commits = commitsFor(relPath);
+    const base = sidecarFiles[relPath]?.baseBrainSha;
+    const tasks = [...new Set(commits.map(taskOfCommit).filter(Boolean))];
+    return {
+      ...(base ? { baseBrainSha: base } : {}),
+      ...(commits.length > 0 ? { commits } : {}),
+      ...(tasks.length > 0 ? { tasks } : {}),
+    };
+  };
+
+  const noteEntry = (abs) => {
+    const relPath = relative(rafa, abs);
+    const content = readFileSync(abs, "utf8");
+    const parsed = parseFrontmatter(content);
+    if (parsed.error || !parsed.data) {
+      drafts.push({ path: relPath, error: parsed.error ?? "unparseable frontmatter" });
+      return null;
+    }
+    const d = parsed.data;
+    const id = str(d.id, idOfPath(relPath));
+    const prov = provenanceOf(relPath);
+    return {
+      id,
+      kind: relPath.includes("playbooks/") ? "playbook" : "rule",
+      type: str(d.type, "note"),
+      domain: str(d.domain, "general"),
+      title: str(d.title, id),
+      summary: str(d.summary),
+      links: strArr(d.links),
+      cites: toCites(content),
+      path: relPath,
+      ...(Object.keys(prov).length > 0 ? { provenance: prov } : {}),
+    };
+  };
+
+  const improvementEntry = (abs) => {
+    const relPath = relative(rafa, abs);
+    const content = readFileSync(abs, "utf8");
+    const parsed = parseFrontmatter(content);
+    if (parsed.error || !parsed.data) {
+      drafts.push({ path: relPath, error: parsed.error ?? "unparseable frontmatter" });
+      return null;
+    }
+    const d = parsed.data;
+    const id = str(d.id, idOfPath(relPath));
+    const leverage = typeof d.leverage === "object" && d.leverage !== null ? d.leverage : {};
+    const prov = provenanceOf(relPath);
+    return {
+      id,
+      priority: PRIORITIES.has(d.priority) ? d.priority : "P2",
+      lens: str(d.lens, "general"),
+      status: IMP_STATUSES.has(d.status) ? d.status : "open",
+      title: str(d.title, id),
+      summary: str(d.summary),
+      fix: str(d.fix),
+      leverage: { impact: str(leverage.impact), effort: str(leverage.effort) },
+      blastRadius: strArr(d.blastRadius),
+      cites: toCites(content),
+      path: relPath,
+      ...(Object.keys(prov).length > 0 ? { provenance: prov } : {}),
+    };
+  };
+
+  const notes = [
+    ...mdFilesUnder(join(rafa, "brain", "rules")),
+    ...mdFilesUnder(join(rafa, "brain", "playbooks")),
+  ]
+    .map(noteEntry)
+    .filter(Boolean);
+  const improvements = mdFilesUnder(join(rafa, "improve", "improvements"))
+    .map(improvementEntry)
+    .filter(Boolean);
+
+  const byPath = (a, b) => a.path.localeCompare(b.path);
+  const out = {
+    schemaVersion: SCHEMA_VERSION,
+    mode: "branch",
+    codeSha,
+    branch,
+    base: baseBrainSha ? { brainSha: baseBrainSha } : null,
+    notes: notes.sort(byPath),
+    improvements: improvements.sort(byPath),
+    ...(drafts.length > 0 ? { drafts: drafts.sort(byPath) } : {}),
+  };
+  writeFileSync(join(rafa, "manifest.json"), JSON.stringify(out, null, 2) + "\n");
+  console.log(
+    `✓ branch manifest: ${notes.length} note(s) · ${improvements.length} improvement(s)` +
+      (drafts.length ? ` · ${drafts.length} draft(s)` : "") +
+      (baseBrainSha ? ` · base ${baseBrainSha.slice(0, 7)}` : " · no hydration base"),
+  );
+}

package/lib/push.mjs

@@ -122,30 +122,55 @@ export default async function push(args = []) {
   // THIS push — a stale/hand-stamped citation-check.json can never ship
   // (mechanized 2026-07-13 from prism's live-run recommendation: the stale-record
   // class dies at the transport layer, not in review).
+  // Deterministic gate-result loop events (harness-arc wave 0): the push
+  // boundary is where the gates ACTUALLY run, so the event rides the real exit
+  // code — never the SOP's memory of it. Best-effort: telemetry never blocks
+  // a push; an unprovisioned repo just skips.
+  const emitGate = async (subject, ok) => {
+    try {
+      const { callTool } = await import("./mcp-client.mjs");
+      await callTool(ROOT, "report_loop_event", {
+        category: "gate-result",
+        outcome: ok ? "exit0" : "failed",
+        subject,
+      });
+    } catch {
+      /* platform unreachable / unprovisioned — the local exit code is still the truth */
+    }
+  };
+
   console.log("• rafa verify-citations — re-grounding every cite/absence/inventory …");
-  if (runVerifyCitations([]) !== 0)
+  if (runVerifyCitations([]) !== 0) {
+    await emitGate("verify-citations", false);
     die(
       "citations failed the checker (see report above). Fix the notes against the " +
         "code (or have atlas repair them), then re-push.",
     );
+  }
   if (
     existsSync(join(ROOT, ".rafa", "improve", "improvements")) &&
     runVerifyCitations(["--root=.rafa/improve", "--dirs=improvements"]) !== 0
-  )
+  ) {
+    await emitGate("verify-citations", false);
     die(
       "improvement citations failed the checker (see report above). Fix the ledger " +
         "files against the code (or have bloom correct them), then re-push.",
     );
+  }
+  await emitGate("verify-citations", true);
 
   // ── contract gate (in-process) ──
   // Compile + validate the brain. A schema-invalid brain NEVER leaves the machine —
   // the platform ingests JSON, so what we push must already conform to the contract.
   console.log("• rafa compile — validating against the contract …");
-  if (runCompile([`--repo=${repoFull}`]) !== 0)
+  if (runCompile([`--repo=${repoFull}`]) !== 0) {
+    await emitGate("compile", false);
     die(
       "brain failed the contract (see errors above). Fix the files, or have the " +
         "authoring agent (atlas/bloom/prism) correct them, then re-push.",
     );
+  }
+  await emitGate("compile", true);
 
   inRafa("git add -A");
   // Descriptive commit (owner catch 2026-07-17: the history was a wall of

package/lib/reflex.mjs

@@ -56,6 +56,21 @@ export default async function reflex(args = []) {
       JSON.stringify({ id, done: true, verdict, at: new Date().toISOString() }) + "\n",
     );
     console.log(`✓ correction ${id} consumed (${verdict})`);
+    // Deterministic reflex-outcome loop event (harness-arc wave 0): the consume
+    // IS the outcome moment, so the event rides it mechanically — shape only
+    // (the correction id, never its text). Best-effort, never blocks.
+    try {
+      const { callTool } = await import("./mcp-client.mjs");
+      const outcome =
+        verdict === "banked" ? "durable" : verdict === "refuted" ? "refuted" : "session-only";
+      await callTool(process.cwd(), "report_loop_event", {
+        category: "reflex-outcome",
+        outcome,
+        subject: id,
+      });
+    } catch {
+      /* unprovisioned repo / platform unreachable — the queue marker is the local truth */
+    }
     return;
   }
 

package/lib/releases.mjs

@@ -264,6 +264,34 @@ export const RELEASES = [
       "first branch checkout (bounded; a failure never breaks the checkout). " +
       "`rafa update` re-vendors the post-checkout hook.",
   },
+  {
+    version: "0.8.14",
+    contract: 1,
+    plans: 2,
+    requires: "update",
+    summary:
+      "LOCAL-STATE EXCLUSION (zero-leak mirrors): the hydration sidecar + sensor " +
+      "queues (hydration.json · dirty/reflex/sensor-errors.jsonl · benchmark.demo.json " +
+      "· distill staging · *.theirs.md) are machine state, never knowledge — the " +
+      "post-commit brain hook now ENSURES the .rafa/.gitignore entries AND untracks " +
+      "anything an earlier window let git track (gitignore alone never untracks), so " +
+      "the next mirror commit cleans the branch. ensureBrainRepo's ignore list gains " +
+      "sensor-errors.jsonl + benchmark.demo.json. `rafa update` re-vendors the hook.",
+  },
+  {
+    version: "0.8.13",
+    contract: 1,
+    plans: 2,
+    requires: "update",
+    summary:
+      "LEDGER HYDRATION: `rafa hydrate improvement <id>` faults a ledger item into " +
+      ".rafa/improve/improvements/<id>.md — the CANONICAL path — so bloom edits the " +
+      "same file the org brain carries (never a path twin). SOPs updated: an " +
+      "improvement the plan ADOPTS is hydrated AT PLAN TIME (bloom engages from the " +
+      "start, not only at build end); ledger status edits always hydrate first. " +
+      "Platform fixes ride server-side: set_active_plan now resolves v2 epics " +
+      "(was v1 parent-only — the not_found bug), get_improvement serves summary.",
+  },
 ];
 
 // The release this CLI build ships (last entry).

package/lib/review.mjs

@@ -0,0 +1,160 @@
+// rafa review — the brain-grounded review gate's DETERMINISTIC pre-pass
+// (harness-arc wave 2). Zero LLM here: the diff's changed line ranges are
+// intersected with the brain's cite graph (get_code_context — file → the
+// rules/playbooks/improvements that know about it), producing the exact,
+// scoped work list the rafa-review SOP's judge then rules on. Generic
+// "review this PR" never happens — the judge only ever sees THESE rules
+// against THESE lines.
+//
+//   rafa review [--base <ref>] [--json]
+//
+// Base defaults to merge-base(HEAD, origin/<default>) — the review covers
+// everything this branch changed (committed + working tree). Advisory always:
+// exit 0, never blocks. Output: .rafa/review.json + a human summary.
+//
+//   hit: "direct"  — a changed line falls INSIDE a cite's line range (the rule's
+//                    anchor itself moved — highest review priority)
+//   hit: "file"    — the file changed elsewhere; the rule still governs it
+//
+// Open improvements citing a touched file + stale-risk flags ride along. The
+// SOP (rafa-review) judges the work list, feeds findings to atlas, and emits
+// report_loop_event(review-verdict, PASS|ITERATE).
+
+import { execSync } from "node:child_process";
+import { existsSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { callTool } from "./mcp-client.mjs";
+
+const MAX_FILES = 50; // bounded fan-out — anything dropped is SAID, never silent
+
+const flag = (args, name) => {
+  const i = args.indexOf(name);
+  return i !== -1 && args[i + 1] && !args[i + 1].startsWith("--") ? args[i + 1] : null;
+};
+
+const sh = (cmd, cwd) => {
+  try {
+    return execSync(cmd, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return "";
+  }
+};
+
+// Parse `git diff -U0` → path → changed NEW-side line ranges [{start, end}].
+export function changedRanges(diffText) {
+  const byFile = new Map();
+  let current = null;
+  for (const line of diffText.split("\n")) {
+    const f = line.match(/^\+\+\+ b\/(.+)$/);
+    if (f) {
+      current = f[1];
+      if (!byFile.has(current)) byFile.set(current, []);
+      continue;
+    }
+    const h = current && line.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/);
+    if (h) {
+      const start = Number(h[1]);
+      const count = h[2] !== undefined ? Number(h[2]) : 1;
+      if (count > 0) byFile.get(current).push({ start, end: start + count - 1 });
+      else byFile.get(current).push({ start, end: start }); // pure deletion → the seam line
+    }
+  }
+  return byFile;
+}
+
+// A cite line ("12" | "10-14") vs the changed ranges → direct hit?
+export function citeHits(citeLine, ranges) {
+  const m = String(citeLine ?? "").match(/^(\d+)(?:-(\d+))?$/);
+  if (!m) return false;
+  const a = Number(m[1]);
+  const b = m[2] !== undefined ? Number(m[2]) : a;
+  return ranges.some((r) => a <= r.end && b >= r.start);
+}
+
+export default async function review(args = []) {
+  const ROOT = process.cwd();
+  if (!existsSync(join(ROOT, "rafa.json"))) {
+    console.error("✗ not a rafa repo (no rafa.json)");
+    process.exit(1);
+  }
+  const defaultBranch =
+    sh("git symbolic-ref --short refs/remotes/origin/HEAD", ROOT).replace(/^origin\//, "") || "main";
+  const base =
+    flag(args, "--base") ?? sh(`git merge-base HEAD "origin/${defaultBranch}"`, ROOT) ?? "";
+  if (!base) {
+    console.error(`✗ cannot resolve a review base (no origin/${defaultBranch}?) — pass --base <ref>`);
+    process.exit(1);
+  }
+
+  const diff = sh(`git diff -U0 ${base}`, ROOT);
+  const ranges = changedRanges(diff);
+  // Code files only — the brain plane reviews itself at reconcile, not here.
+  const files = [...ranges.keys()].filter(
+    (p) => !p.startsWith(".rafa/") && !p.startsWith(".claude/") && p !== "rafa.json",
+  );
+  const reviewed = files.slice(0, MAX_FILES);
+  const dropped = files.length - reviewed.length;
+
+  const out = [];
+  let unreachable = null;
+  for (const path of reviewed) {
+    let ctx;
+    try {
+      ctx = await callTool(ROOT, "get_code_context", { path });
+    } catch (e) {
+      unreachable = e instanceof Error ? e.message : String(e);
+      break; // one transport failure fails them all — say so, don't half-report
+    }
+    const fileRanges = ranges.get(path) ?? [];
+    const rules = (ctx.notes ?? []).map((n) => ({
+      id: n.id,
+      kind: n.kind,
+      title: n.title,
+      domain: n.domain,
+      line: n.line,
+      ...(n.failure ? { failure: n.failure } : {}),
+      hit: citeHits(n.line, fileRanges) ? "direct" : "file",
+    }));
+    const improvements = (ctx.improvements ?? []).filter((i) => i.status === "open");
+    if (rules.length > 0 || improvements.length > 0)
+      out.push({ path, ranges: fileRanges, rules, improvements, relatedPlans: ctx.relatedPlans ?? [] });
+  }
+
+  const report = {
+    schemaVersion: 1,
+    base,
+    filesChanged: files.length,
+    filesReviewed: reviewed.length,
+    ...(dropped > 0 ? { dropped } : {}),
+    ...(unreachable ? { unreachable } : {}),
+    files: out,
+  };
+  writeFileSync(join(ROOT, ".rafa", "review.json"), JSON.stringify(report, null, 2) + "\n");
+
+  if (args.includes("--json")) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+  const direct = out.flatMap((f) => f.rules.filter((r) => r.hit === "direct"));
+  const fileHits = out.flatMap((f) => f.rules.filter((r) => r.hit === "file"));
+  const imps = out.flatMap((f) => f.improvements);
+  console.log(
+    `✓ review pre-pass vs ${base.slice(0, 7)}: ${files.length} changed file(s)` +
+      (dropped > 0 ? ` (${dropped} beyond the ${MAX_FILES}-file bound NOT reviewed)` : ""),
+  );
+  if (unreachable) console.log(`  ! platform unreachable mid-pass — the work list is PARTIAL: ${unreachable}`);
+  if (out.length === 0) {
+    console.log("  no governed lines touched — nothing for the judge (the brain has no rules citing these files)");
+    return;
+  }
+  for (const f of out) {
+    console.log(`  ${f.path}`);
+    for (const r of f.rules)
+      console.log(`    ${r.hit === "direct" ? "◆" : "·"} ${r.id} [${r.domain}] ${r.title}${r.failure ? ` (failure: ${r.failure})` : ""}`);
+    for (const i of f.improvements) console.log(`    ! open ${i.priority}: ${i.id} ${i.title}`);
+  }
+  console.log(
+    `→ ${direct.length} direct anchor hit(s) · ${fileHits.length} same-file rule(s) · ${imps.length} open improvement(s)` +
+      `\n  The judge rules on exactly these (rafa-review SOP): does the diff still honor each rule; does it satisfy the active task's Done-check.`,
+  );
+}

package/lib/working-set.mjs

@@ -139,3 +139,46 @@ export function renderNote(d) {
   ];
   return lines.join("\n") + (d.body ?? "") + "\n";
 }
+
+// The improvement-ledger twin of materializeNote — faults ONE improvement into
+// `.rafa/improve/improvements/<id>.md` (the CANONICAL ledger path, so a status
+// edit lands on the same file the org brain carries — never a path-drifted twin).
+// Same sidecar rule: unedited hydration = disposable cache.
+export function materializeImprovement(cwd, data, brainForSha) {
+  const rel = `improve/improvements/${data.id}.md`;
+  const abs = join(cwd, ".rafa", rel);
+  const content = renderImprovement(data);
+  mkdirSync(dirname(abs), { recursive: true });
+  writeFileSync(abs, content);
+  const sidecar = readSidecar(cwd);
+  sidecar.files[rel] = {
+    ...(brainForSha ? { baseBrainSha: brainForSha } : {}),
+    hash: hashOf(content),
+  };
+  writeSidecar(cwd, sidecar);
+  return rel;
+}
+
+// Deterministic ledger-file writer for hydrated improvements — mirrors the shape
+// bloom authors (see any improve/improvements/*.md): priority · lens · status ·
+// fix · leverage · blast_radius · cites, then the prose body.
+export function renderImprovement(d) {
+  const lines = [
+    "---",
+    "schemaVersion: 1",
+    `id: ${d.id}`,
+    `priority: ${d.priority}`,
+    ...(d.lens ? [`lens: ${d.lens}`] : []),
+    `status: ${d.status}`,
+    `title: ${q(d.title)}`,
+    ...(d.summary ? [`summary: ${q(d.summary)}`] : []),
+    ...(d.fix ? [`fix: ${q(d.fix)}`] : []),
+    ...(d.leverage ? [`leverage: { impact: ${d.leverage.impact}, effort: ${d.leverage.effort} }`] : []),
+    `blast_radius: [${(d.blastRadius ?? []).join(", ")}]`,
+    "cites:",
+    ...(d.cites ?? []).map((c) => `  - ${c.file}:${c.line} :: ${c.token}`),
+    "---",
+    "",
+  ];
+  return lines.join("\n") + (d.body ?? "") + "\n";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rafinery/cli",
-  "version": "0.8.12",
+  "version": "0.8.14",
   "description": "rafa — the AI engineer CLI. Vendors the rafa blueprint into your repo (shadcn-style) and runs the deterministic contract gates.",
   "type": "module",
   "bin": {