@rafinery/cli 0.8.14 → 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/bin/rafa.mjs

@@ -135,10 +135,12 @@ Commands:
                        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.
+                       diff's changed lines ∩ the brain's cite graph → everything the
+                       change touches — rules AND playbooks (flow-still-true), open
+                       improvements, stale-cite risk flags, open knowledge gaps,
+                       related plans (.rafa/review.json + summary). The rafa-review
+                       SOP's judge 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/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-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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."
+description: "rafa SOP — the brain-grounded review gate: `rafa review` computes exactly what a diff touches (cite-intersection, zero LLM): rules AND playbooks, open improvements, stale-cite risk, open gaps, related plans' decisions; 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)
@@ -16,34 +16,97 @@ 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):
+ranges ∩ the brain's cite graph (`get_code_context` per file), BOTH note kinds:
 
-- **◆ 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
+- **◆ direct** — a changed line falls inside a note's cited anchor range: the
+  code the note 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.
+- **· file** — the file changed elsewhere but the note governs it.
+- **⚠ stale cites** — the freshness sweep already flagged this note's anchors
+  as drifted: a RISK marker (verify the note against code before relying on
+  it in judgment — it may describe a world that no longer exists).
 - **! 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)?
+- **open knowledge gaps** (top-missed queries) — live demand near the change.
 
 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.
 
+## Token economy — BINDING (the gate must cost less than the bugs it catches)
+
+The judge's spend is proportional to the DIFF, never to the brain. Owner rule
+(2026-07-24): review checks only the diff; hydrated fields serve the judgment;
+querying files wholesale is a waste. Concretely:
+
+1. **The pre-pass is free AND selective** — zero LLM; every note carries a
+   deterministic RELEVANCE score (direct-hit +3 · failure:silent +2 · cite
+   anchor token appears in the diff's added lines +2 · title/summary keyword
+   overlap +1 each, capped) and an **`engage` tier**:
+   - `deep` — body-worthy: hydrate/fetch and judge fully;
+   - `triage` — summary-only: rule in/out from metadata + diff, fetch a body
+     ONLY if that makes a violation plausible;
+   - `skip` — governs the file but nothing in the change relates: NEVER
+     judged, never fetched — listed in review.json so nothing drops silently.
+   (Semantic relevance stays contract-reserved via `matchKind` — keywords +
+   citations are the v1 scorer; vectors arrive on evidence, never blindly.)
+2. **Honor the tiers.** The judge never upgrades a `skip`, and upgrades a
+   `triage` to a body fetch only with a stated reason (the finding cites it).
+3. **Local-first, never re-serve.** A note already hydrated under
+   `.rafa/brain/**` (plan/build recall put it there) is read FROM DISK —
+   no MCP round-trip, no double-serving. Fetch via `get_rule`/`get_playbook`
+   only for shortlist notes absent locally; `rafa hydrate <kind> <id>` them
+   so a re-judge after atlas's fix re-reads the disk copy (disposable-cache
+   semantics keep them out of commits).
+   **Frontmatter-first (the OKF leverage):** every file type has a strict
+   format (contract §11), so the MACHINE fields — `cites` · `anchor` ·
+   `failure` · `links` · `type` — parse without touching the prose body.
+   Judge from frontmatter + diff first; read the body only when they can't
+   settle it. A `contract` note's check is half-mechanical before any prose:
+   does the diff touch its `anchor` token anywhere without updating every
+   cited site (the B2 completeness question)?
+4. **Deep-judge cap: 10 notes**, leverage-ranked (◆ direct > failure:silent >
+   ⚠ stale-and-direct > · file). Anything beyond the cap is ruled on metadata
+   only and the verdict SAYS SO ("N notes judged shallow") — an honest bound,
+   never a silent one.
+5. **Metadata-only lanes stay metadata-only**: gaps, decisions, relatedPlans,
+   improvements are judged from what the pre-pass/`get_plan` already carries —
+   no body fetches, no extra searches. NEVER load the whole brain, never
+   fetch a note the pre-pass didn't flag.
+
 ## Pass 2 — the judge (prism-style, scoped)
 
-For the work list ONLY — never the whole diff, never taste:
+For the work list ONLY — never the whole diff, never taste. Each data kind has
+its OWN question:
 
-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 →
+1. Per **rule hit** — the OKF `type` names the violation shape:
+   - `convention` → does the new code FOLLOW the local pattern the rule names?
+   - `contract` → the cross-file class: does the diff change any occurrence of
+     the rule's `anchor` without updating EVERY cited site (B2 completeness —
+     half-mechanical from frontmatter, see the economy rules)? `failure:
+     silent` contracts get the deepest scrutiny — that class never announces
+     itself.
+   Judge against code + rule, never against the author's claims.
+2. Per **playbook hit** (`flow` / `how-to` types): is the documented
+   FLOW/how-to still TRUE after this change (steps, ordering, file routes)?
+   A diff that silently invalidates a playbook ships a lie to the next dev —
+   that's an ITERATE finding (or a working-set edit updating the playbook,
+   authored the branch way).
+3. Per **⚠ stale-cite note**: verify the note against current code BEFORE
+   using it in judgment; if the diff is the thing that staled it further,
+   surface the scoped-refresh offer.
+4. 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
+5. **Related plans' decisions** (`get_plan` for each `relatedPlans` entry):
+   does the diff contradict a recorded decision? Contradicting one is the
+   owner's call to reopen — an ITERATE finding, never silently overridden.
+6. **Open gaps**: does this change ANSWER one (author the note, close the
+   gap) — or deepen it?
+7. **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 +
+8. Verdict: **PASS** or **ITERATE** with per-finding citations (note 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:
+9. 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.
 

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

@@ -264,20 +264,6 @@ 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,
@@ -292,6 +278,59 @@ export const RELEASES = [
       "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",
+    contract: 1,
+    plans: 2,
+    requires: "update",
+    summary:
+      "THE PROVENANCE SPINE (published 2026-07-24). Branch manifest: `rafa manifest` " +
+      "(zero-command — the post-commit brain hook regenerates it per mirrored commit): " +
+      "lenient snapshot with mode:branch · base.brainSha · per-note provenance " +
+      "{baseBrainSha, commits[], tasks[]} — the reconciler's three-way handoff doc. " +
+      "rafa-commit skill: subjects carry the active task id ([task-id] type: subject) " +
+      "and the manifest lifts it into per-note task lineage. Deterministic loop " +
+      "events: push gates emit gate-result from real exit codes; reflex --consume " +
+      "emits reflex-outcome. Benchmark is workflow-woven (scan's Prove-it step + " +
+      "session-start absence sensor) — never a dev-typed command.",
+  },
+  {
+    version: "0.8.15",
+    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.",
+  },
+  {
+    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.",
+  },
 ];
 
 // The release this CLI build ships (last entry).

package/lib/review.mjs

@@ -1,10 +1,12 @@
 // 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.
+// RULES *and* PLAYBOOKS and 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 notes
+// against THESE lines. Also surfaced: per-note stale-cite RISK flags (the
+// freshness sweep's signal) and the repo's open knowledge gaps — the judge
+// weighs whether this change answers or worsens one.
 //
 //   rafa review [--base <ref>] [--json]
 //
@@ -71,6 +73,50 @@ export function citeHits(citeLine, ranges) {
   return ranges.some((r) => a <= r.end && b >= r.start);
 }
 
+// Identifier tokens from the diff's ADDED lines, per file — the relevance
+// vocabulary a note must intersect to earn the judge's attention.
+export function addedTokens(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, new Set());
+      continue;
+    }
+    if (current && line.startsWith("+") && !line.startsWith("+++"))
+      for (const t of line.slice(1).toLowerCase().match(/[a-z_][a-z0-9_-]{2,}/g) ?? [])
+        byFile.get(current).add(t);
+  }
+  return byFile;
+}
+
+// Deterministic relevance (owner 2026-07-24: never hydrate/judge blindly —
+// keywords + citations decide whether a note ADDS VALUE to this diff; the OKF
+// type registry is leveraged: every type has a format, so every type has a
+// DEFINED violation shape and a deterministic weight):
+//   direct anchor hit        +3   (the cited code itself moved)
+//   type: contract           +2   (the cross-file class — breaks span files)
+//   failure: silent          +2   (the class that never announces itself)
+//   cite anchor token in diff +2  (the rule's own token appears in new code)
+//   title/summary keyword     +1 each, capped at +3
+// → engage: "deep" (≥3: body-worthy) · "triage" (1–2: summary-only) ·
+//   "skip" (0: governs the file but nothing relates — listed, never judged).
+export function relevanceOf(note, diffTokens) {
+  let score = 0;
+  if (note.hit === "direct") score += 3;
+  if (note.type === "contract") score += 2;
+  if (note.failure === "silent") score += 2;
+  const anchor = String(note.token ?? "").toLowerCase();
+  if (anchor && [...diffTokens].some((t) => anchor.includes(t) || t.includes(anchor))) score += 2;
+  let kw = 0;
+  const text = `${note.title ?? ""} ${note.summary ?? ""}`.toLowerCase();
+  for (const t of diffTokens) if (text.includes(t)) kw += 1;
+  score += Math.min(kw, 3);
+  return { score, engage: score >= 3 ? "deep" : score >= 1 ? "triage" : "skip" };
+}
+
 export default async function review(args = []) {
   const ROOT = process.cwd();
   if (!existsSync(join(ROOT, "rafa.json"))) {
@@ -88,6 +134,7 @@ export default async function review(args = []) {
 
   const diff = sh(`git diff -U0 ${base}`, ROOT);
   const ranges = changedRanges(diff);
+  const tokensByFile = addedTokens(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",
@@ -106,18 +153,43 @@ export default async function review(args = []) {
       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",
-    }));
+    // BOTH note kinds engage: a rule hit asks "does the diff still honor the
+    // convention/contract"; a playbook hit asks "is the documented flow/how-to
+    // still true after this change". staleCites = freshness RISK (the note may
+    // already describe drifted code — verify before relying on it).
+    const fileTokens = tokensByFile.get(path) ?? new Set();
+    const notes = (ctx.notes ?? []).map((n) => {
+      const base = {
+        id: n.id,
+        kind: n.kind,
+        ...(n.type ? { type: n.type } : {}),
+        title: n.title,
+        domain: n.domain,
+        line: n.line,
+        token: n.token,
+        ...(n.failure ? { failure: n.failure } : {}),
+        // The one-line summary IS the triage surface — the judge rules most
+        // notes in/out from this alone, fetching bodies only for the shortlist.
+        ...(n.summary ? { summary: n.summary } : {}),
+        ...(n.staleCites ? { staleCites: n.staleCites } : {}),
+        hit: citeHits(n.line, fileRanges) ? "direct" : "file",
+      };
+      const { score, engage } = relevanceOf(base, fileTokens);
+      return { ...base, relevance: score, engage };
+    });
     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 ?? [] });
+    if (notes.length > 0 || improvements.length > 0)
+      out.push({ path, ranges: fileRanges, notes, improvements, relatedPlans: ctx.relatedPlans ?? [] });
+  }
+
+  // Open knowledge gaps — live demand near this change (queries + counts only).
+  // The judge weighs: does this diff ANSWER one (close it) or deepen it?
+  let gaps = [];
+  try {
+    const g = await callTool(ROOT, "get_knowledge_gaps", { status: "open", limit: 5 });
+    gaps = (g.gaps ?? []).map((x) => ({ q: x.q, misses: x.misses }));
+  } catch {
+    /* gaps are context, not a gate — absence never fails the pass */
   }
 
   const report = {
@@ -128,6 +200,7 @@ export default async function review(args = []) {
     ...(dropped > 0 ? { dropped } : {}),
     ...(unreachable ? { unreachable } : {}),
     files: out,
+    ...(gaps.length > 0 ? { openGaps: gaps } : {}),
   };
   writeFileSync(join(ROOT, ".rafa", "review.json"), JSON.stringify(report, null, 2) + "\n");
 
@@ -135,9 +208,12 @@ export default async function review(args = []) {
     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 direct = out.flatMap((f) => f.notes.filter((r) => r.hit === "direct"));
+  const fileHits = out.flatMap((f) => f.notes.filter((r) => r.hit === "file"));
   const imps = out.flatMap((f) => f.improvements);
+  const stale = out.flatMap((f) => f.notes.filter((r) => r.staleCites));
+  const engaged = out.flatMap((f) => f.notes.filter((r) => r.engage !== "skip"));
+  const skipped = out.flatMap((f) => f.notes.filter((r) => r.engage === "skip"));
   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)` : ""),
@@ -149,12 +225,20 @@ export default async function review(args = []) {
   }
   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 r of f.notes.filter((n) => n.engage !== "skip"))
+      console.log(
+        `    ${r.hit === "direct" ? "◆" : "·"} [${r.engage}] ${r.kind} ${r.id} [${r.domain}] ${r.title}` +
+          `${r.failure ? ` (failure: ${r.failure})` : ""}${r.staleCites ? ` ⚠ ${r.staleCites} stale cite(s)` : ""}`,
+      );
     for (const i of f.improvements) console.log(`    ! open ${i.priority}: ${i.id} ${i.title}`);
   }
+  if (gaps.length)
+    console.log(`  open knowledge gaps (does this change answer one?): ${gaps.map((g) => `"${g.q}"×${g.misses}`).join(" · ")}`);
   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.`,
+    `→ engage ${engaged.length}/${engaged.length + skipped.length} note(s) (${direct.length} direct · ${fileHits.length} same-file` +
+      (skipped.length ? ` · ${skipped.length} governs-the-file-but-unrelated SKIPPED, listed in review.json` : "") +
+      `) · ${imps.length} open improvement(s)` +
+      (stale.length ? ` · ⚠ ${stale.length} stale-cite note(s) — verify before relying` : "") +
+      `\n  The judge rules on exactly the engaged set (rafa-review SOP): deep = body-worthy, triage = summary-only.`,
   );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rafinery/cli",
-  "version": "0.8.14",
+  "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": {