@rafinery/cli 0.8.15 → 0.8.16

package/CHANGELOG.md

@@ -4,6 +4,29 @@ 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.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
+commit sat uncommitted in `.rafa` while `rafa checkpoint` reported clean — the
+capture plane (platform working set) was synced, the git plane (brain mirror
+branch) was dirty. The hooks only fire on code commit/push, so a session tail
+(verify flips · late-authored notes · regenerated manifest) had nothing to ride.
+
+- `rafa checkpoint` now owns BOTH planes: after the working-set sync (including
+  the "clean" path) it fires the vendored `brain-commit.mjs` worker whenever the
+  brain tree is dirty — the tail commits and pushes at the same beat that
+  creates it, and "clean" finally means capture AND mirror.
+- The worker is tail-aware: when HEAD already has its 1-1 mirror, the extra run
+  commits with a distinct `brain(<branch>): session tail · N file(s)` subject on
+  the SAME `code-commit` trailer (join intact, log legible) — and an empty tail
+  is a no-op, never an `--allow-empty` duplicate.
+- `review.json` (the review gate's scored-ranges artifact) joins the local-state
+  exclusion list — machine state like `distill-verdicts.json`, never knowledge.
+- Fixed: the `RELEASES` ledger tail was out of ascending order (0.8.13/0.8.14
+  after 0.8.15), so `CURRENT` reported 0.8.13 from a 0.8.15 build.
+
+Adopt with `rafa update` (re-vendors the hook worker).
+
 ## 0.8.2 — MCP scope: derived from the key, never guessed
 
 First real client MCP call surfaced it: agents GUESSED the `repo` arg (folder name)

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

@@ -1,6 +1,6 @@
 ---
 name: sage
-version: 0.2.1
+version: 0.3.0
 model: opus   # a wrong learning re-shapes an agent for every repo — best model, never cheap
 groundTruth: sessions-over-time
 description: >-
@@ -19,6 +19,7 @@ duties:
   - "scrub :: .claude/skills/rafa-sage/SKILL.md :: every entry passes the SCRUB STEP before write — anything asset-shaped (code content, snippets, repo-specific facts, repo-identifying detail) abstracted to the pattern or DROPPED; the ledger entry schema has NO code-content-capable field"
   - "route-person-shaped :: .claude/skills/rafa-sage/SKILL.md :: a person-shaped observation is NEVER a learning — it routes to compass's consent path (rafa-insights, user brain), never sage's ledger"
   - "propose-only :: .claude/skills/rafa-sage/SKILL.md :: output is PROPOSED diffs to agent cards/SOPs — applying a change is a separate human/MR-reviewed act; sage never self-applies and never edits an agent card or SOP"
+  - "mirror-summary :: .claude/skills/rafa-sage/SKILL.md :: after scrub + file write, each entry's SUMMARY row is mirrored via report_learning for the platform card — a projection, never a second truth; the committed .md stays the ledger"
   - "okf-surface :: .claude/skills/rafa-okf/SKILL.md :: learnings pass the compile learning gate (id · type · title · description) — the same protocol outside the bundle"
 ---
 

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

@@ -128,19 +128,42 @@ try {
     .split("\n")
     .filter(Boolean)
     .slice(0, 100);
+
+  // TAIL RUN detection (0.8.16, live-catch 2026-07-24): if HEAD already has its
+  // 1-1 mirror commit (its code-commit trailer is in the brain log), THIS
+  // invocation carries the SESSION TAIL — brain deltas written AFTER the last
+  // code commit (verify flips · late-authored notes · regenerated manifest)
+  // that would otherwise strand uncommitted until the next code commit. The
+  // checkpoint beat fires this worker for exactly that case. A tail commit is
+  // additive provenance on the SAME join key (trailer unchanged); its subject
+  // is distinct so the log never shows two look-alike mirrors, and an empty
+  // tail is a NO-OP — never an --allow-empty duplicate.
+  let isTail = false;
+  try {
+    isTail = shR(`git log --grep "code-commit: ${fullSha}" --format=%H -n 1`) !== "";
+  } catch {
+    /* fresh mirror / unborn HEAD — normal 1-1 path */
+  }
+
   mkdirSync(join(rafa, "intent"), { recursive: true });
-  writeFileSync(
-    join(rafa, "intent", `${short}.md`),
-    `---\n` +
-      `type: IntentRecord\n` +
-      `description: "per-commit intent trail (capture-engine P2) — provenance, consumed at merge, never org-brain truth"\n` +
-      `code-commit: ${fullSha}\n` +
-      `code-branch: ${branch}\n` +
-      `timestamp: ${new Date().toISOString()}\n` +
-      `---\n\n# ${subject}\n\n## Files\n` +
-      files.map((f) => `- ${f}`).join("\n") +
-      `\n`,
-  );
+  // A tail run never rewrites an existing intent record — the 1-1 mirror wrote
+  // it, and a fresh `timestamp:` would make every tail beat a phantom delta
+  // (the no-op contract would never hold).
+  const intentPath = join(rafa, "intent", `${short}.md`);
+  if (!isTail || !existsSync(intentPath)) {
+    writeFileSync(
+      intentPath,
+      `---\n` +
+        `type: IntentRecord\n` +
+        `description: "per-commit intent trail (capture-engine P2) — provenance, consumed at merge, never org-brain truth"\n` +
+        `code-commit: ${fullSha}\n` +
+        `code-branch: ${branch}\n` +
+        `timestamp: ${new Date().toISOString()}\n` +
+        `---\n\n# ${subject}\n\n## Files\n` +
+        files.map((f) => `- ${f}`).join("\n") +
+        `\n`,
+    );
+  }
 
   // Local-state exclusion (owner 2026-07-24): the hydration sidecar + sensor
   // queues are MACHINE state, never knowledge — ensure the ignore entries and
@@ -155,6 +178,9 @@ try {
       "sensor-errors.jsonl",
       "distill-verdicts.json",
       "benchmark.demo.json",
+      // rafa review's scored-ranges artifact (wave 2.3) — regenerated per
+      // review, machine state like distill-verdicts; never brain knowledge.
+      "review.json",
     ];
     const gi = join(rafa, ".gitignore");
     const cur = existsSync(gi) ? readFileSync(gi, "utf8") : "";
@@ -171,10 +197,26 @@ try {
 
   shR("git add -A");
   disposeHydrations(branch);
-  shR(
-    `git commit --allow-empty -q -m "brain(${branch}): ${subject}" ` +
-      `-m "code-commit: ${fullSha}" -m "code-branch: ${branch}"`,
-  );
+  if (isTail) {
+    // Session tail: commit only when something REAL is staged (disposal may
+    // have unstaged everything). The 1-1 join stays mechanical — same trailer.
+    let staged = [];
+    try {
+      staged = shR("git diff --cached --name-only").split("\n").filter(Boolean);
+    } catch {
+      /* nothing staged */
+    }
+    if (staged.length > 0)
+      shR(
+        `git commit -q -m "brain(${branch}): session tail · ${staged.length} file(s)" ` +
+          `-m "code-commit: ${fullSha}" -m "code-branch: ${branch}"`,
+      );
+  } else {
+    shR(
+      `git commit --allow-empty -q -m "brain(${branch}): ${subject}" ` +
+        `-m "code-commit: ${fullSha}" -m "code-branch: ${branch}"`,
+    );
+  }
   // Keep the REMOTE mirror branch current (owner 2026-07-23: the branch is visible
   // in the brain repo) — best-effort, bounded; a failed push retries on the next
   // commit. Never the trunk (single writer = the reconciler).

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

@@ -101,7 +101,9 @@ human.
 The ledger is a **committed, human-reviewed governance artifact** — diffs for MR review. It is
 **NOT** a Convex table and **NOT** inside any customer `.rafa/brain/` (asset-free: learnings are
 about OUR agents; they never mix with customer knowledge). It lives beside the contract at
-`.claude/rafa/learnings/` (governance, versioned with the blueprint, MR-reviewed):
+`.claude/rafa/learnings/` (governance, versioned with the blueprint, MR-reviewed). The platform's
+"agent learnings" card renders a **projection** of it (summary rows via `report_learning`, wave
+4.1, owner-ratified 2026-07-24) — a display overlay, never a second truth and never the store:
 
 - `learnings/<id>.md` — one file per learning (one proposed card/SOP diff, cited to event shapes).
 - `ledger.md` — generated index: counts by category / target / status, and the top-leverage few.
@@ -169,7 +171,16 @@ enforced by sage and by MR review.
 7. **Ledger + leverage.** Regenerate `ledger.md`: counts by category / target / status, and the
    **top-leverage few** (impact × ease) — the single card/SOP change that would cover the widest
    class of misses, first.
-8. **Present, don't nag, don't apply.** Surface the top few high-leverage learnings succinctly as
+8. **Mirror the summary rows (wave 4.1 — the platform "agent learnings" card).** For each entry
+   written or status-changed in step 6, call `report_learning` with the entry's SUMMARY fields
+   (`id · pattern · categories · evidence_shape · proposed_diff_target · proposed_change ·
+   status · leverage`) — AFTER the scrub step and the file write, never before. This is a
+   **projection, not a second truth** (owner 2026-07-24): the committed `.md` stays the single
+   truth; the rows only render the Activity card. Upsert by id — re-runs refresh `status`,
+   never duplicate. The server re-screens every field (enum checks, `.claude/`-only target,
+   length caps, code-fence/secret rejection) — a rejection means the entry failed the asset-free
+   gate: fix the ENTRY, don't re-word past the screen.
+9. **Present, don't nag, don't apply.** Surface the top few high-leverage learnings succinctly as
    PROPOSALS. sage never applies a diff; a human reviews the ledger, and any accepted change lands
    as a versioned, MR-reviewed card/SOP edit (bump `version:`, record the why). Silent otherwise.
 

package/lib/checkpoint.mjs

@@ -27,6 +27,62 @@ const die = (m) => {
   process.exit(1);
 };
 
+// The GIT-PLANE tail beat (0.8.16, live-catch 2026-07-24): brain deltas written
+// AFTER the last code commit (verify flips · late-authored notes · regenerated
+// manifest) have no post-commit mirror to ride, and the pre-push ceremony may
+// already have run — they strand uncommitted until the next code commit. The
+// checkpoint beat is the boundary that CREATES that tail, so it fires the SAME
+// vendored worker the git hooks run (single implementation, tail-aware since
+// 0.8.16) whenever the brain tree is dirty. One beat, both planes: "clean"
+// from this command means capture AND mirror. Best-effort — a mirror problem
+// never fails a checkpoint.
+function mirrorTail(ROOT, branch) {
+  const rafa = join(ROOT, ".rafa");
+  const worker = join(ROOT, ".claude", "rafa", "hooks", "brain-commit.mjs");
+  if (!existsSync(join(rafa, ".git")) || !existsSync(worker)) return;
+  const shR = (cmd) =>
+    execSync(cmd, { cwd: rafa, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  let dirty = "";
+  try {
+    dirty = shR("git status --porcelain");
+  } catch {
+    return; // unreadable brain repo — the hooks' own paths will surface it
+  }
+  if (dirty === "") return; // git plane already clean — nothing stranded
+  let before = "";
+  try {
+    before = shR("git rev-parse HEAD");
+  } catch {
+    /* unborn HEAD — the worker handles it */
+  }
+  try {
+    execSync(`node "${worker}"`, { cwd: ROOT, stdio: ["ignore", "ignore", "ignore"], timeout: 60000 });
+  } catch {
+    /* worker is silent + non-blocking by design; fall through to the report */
+  }
+  try {
+    const after = shR("git rev-parse HEAD");
+    if (after !== before) {
+      let pushed = false;
+      try {
+        pushed = shR(`git rev-parse "origin/${branch}"`) === after;
+      } catch {
+        /* no remote tracking yet */
+      }
+      console.log(
+        `✓ brain mirror: session tail committed (${after.slice(0, 12)})` +
+          (pushed ? " + pushed" : " — push rides the next pre-push ceremony"),
+      );
+    } else {
+      console.log(
+        "• brain tree dirt is disposable hydration cache — nothing real to mirror",
+      );
+    }
+  } catch {
+    /* report is best-effort */
+  }
+}
+
 export default async function checkpoint() {
   const ROOT = process.cwd();
 
@@ -101,6 +157,9 @@ export default async function checkpoint() {
 
   if (candidates.length === 0) {
     console.log(`✓ working set clean on ${branch} — nothing to checkpoint`);
+    // A clean CAPTURE plane can still hide a dirty GIT plane (the live catch:
+    // "checkpoint said clean" while the session tail sat uncommitted).
+    mirrorTail(ROOT, branch);
     // Knowledge-absence nudge (live-catch 2026-07-17: a session can do real
     // work and bank ZERO knowledge, silently — no sensor fires on absence).
     // Deterministic signal only: code edits recorded, no brain delta on this
@@ -184,6 +243,11 @@ export default async function checkpoint() {
       (conflicts ? ` · ${conflicts} conflict(s) need YOUR decision (see above)` : ""),
   );
 
+  // Both planes, one beat: the capture sync above, the brain mirror here.
+  // (Runs before the conflict exit — a contested working set is still worth a
+  // durable mirror of the dev's current copies; .theirs.md files are ignored.)
+  mirrorTail(ROOT, branch);
+
   // prism-verdict backstop (harness-arc wave 0): gate-result/reflex-outcome are
   // emitted mechanically by the CLI, but prism verdicts are LLM judgments only
   // the session can report. The checkpoint beat — the SOP's own emit moment —

package/lib/releases.mjs

@@ -265,23 +265,18 @@ export const RELEASES = [
       "`rafa update` re-vendors the post-checkout hook.",
   },
   {
-    version: "0.8.15",
+    version: "0.8.13",
     contract: 1,
     plans: 2,
     requires: "update",
     summary:
-      "THE REVIEW GATE + ZERO-LEAK MIRRORS. `rafa review`: deterministic brain-" +
-      "grounded review pre-pass — diff's changed lines ∩ the cite graph → rules AND " +
-      "playbooks + open improvements + stale-cite risk + open gaps, each note " +
-      "relevance-scored (OKF type-aware: contract class weighs heavier) into " +
-      "deep/triage/skip engage tiers so the judge's tokens scale with the DIFF, " +
-      "never the brain (rafa-review SOP: local-first + frontmatter-first reads, " +
-      "10-note deep cap, skips listed never judged). LOCAL-STATE EXCLUSION: the " +
-      "post-commit hook now ensures .rafa/.gitignore AND untracks previously " +
-      "tracked machine state (hydration.json · sensor queues · demo benchmark · " +
-      "distill staging · *.theirs.md) — the next mirror commit cleans the branch. " +
-      "Plus wave-2 SOPs: delta briefing + decision recall at plan time, branch-" +
-      "aware recall (tier-labeled), compass sitback, gap lifecycle beats.",
+      "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.",
   },
   {
     version: "0.8.14",
@@ -300,18 +295,41 @@ export const RELEASES = [
       "session-start absence sensor) — never a dev-typed command.",
   },
   {
-    version: "0.8.13",
+    version: "0.8.15",
     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 REVIEW GATE + ZERO-LEAK MIRRORS. `rafa review`: deterministic brain-" +
+      "grounded review pre-pass — diff's changed lines ∩ the cite graph → rules AND " +
+      "playbooks + open improvements + stale-cite risk + open gaps, each note " +
+      "relevance-scored (OKF type-aware: contract class weighs heavier) into " +
+      "deep/triage/skip engage tiers so the judge's tokens scale with the DIFF, " +
+      "never the brain (rafa-review SOP: local-first + frontmatter-first reads, " +
+      "10-note deep cap, skips listed never judged). LOCAL-STATE EXCLUSION: the " +
+      "post-commit hook now ensures .rafa/.gitignore AND untracks previously " +
+      "tracked machine state (hydration.json · sensor queues · demo benchmark · " +
+      "distill staging · *.theirs.md) — the next mirror commit cleans the branch. " +
+      "Plus wave-2 SOPs: delta briefing + decision recall at plan time, branch-" +
+      "aware recall (tier-labeled), compass sitback, gap lifecycle beats.",
+  },
+  {
+    version: "0.8.16",
+    contract: 1,
+    plans: 2,
+    requires: "update",
+    summary:
+      "THE SESSION TAIL NEVER STRANDS (live-catch 2026-07-24: brain notes " +
+      "authored AFTER the last code commit sat uncommitted while `rafa " +
+      "checkpoint` said clean — capture plane synced, git plane dirty). " +
+      "`rafa checkpoint` now owns BOTH planes: after the working-set sync it " +
+      "fires the vendored brain-commit worker whenever the brain tree is " +
+      "dirty, so the tail commits + pushes at the same beat that creates it. " +
+      "The worker is tail-aware: HEAD already mirrored ⇒ a distinct " +
+      "`session tail · N file(s)` subject on the same code-commit trailer " +
+      "(never a look-alike duplicate), and an empty tail is a no-op. " +
+      "review.json (the review gate's scored-ranges artifact) joins the " +
+      "local-state exclusion — machine state, never brain knowledge.",
   },
 ];
 

package/package.json

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