@rafinery/cli 0.8.12 → 0.8.13

package/bin/rafa.mjs

@@ -53,6 +53,7 @@ const COMMANDS = [
   "ci-setup",
   "leverage",
   "benchmark",
+  "manifest",
   "migrate",
 ];
 const [cmd, ...rest] = process.argv.slice(2);
@@ -72,6 +73,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

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");

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

@@ -33,7 +33,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 +72,25 @@ 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.
+   **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; final `push_plan` +
-   `set_active_plan` (clear) + `rafa checkpoint`. A plan that stops being worth
+   `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)?
@@ -54,7 +63,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-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,7 @@ export const BLUEPRINT = {
     ".claude/skills/rafa-validate",
     ".claude/skills/rafa-plan",
     ".claude/skills/rafa-build",
+    ".claude/skills/rafa-commit",
     ".claude/skills/rafa-improve",
     ".claude/skills/rafa-distill",
     ".claude/skills/rafa-insights",

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,20 @@ export const RELEASES = [
       "first branch checkout (bounded; a failure never breaks the checkout). " +
       "`rafa update` re-vendors the post-checkout 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/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.13",
   "description": "rafa — the AI engineer CLI. Vendors the rafa blueprint into your repo (shadcn-style) and runs the deterministic contract gates.",
   "type": "module",
   "bin": {