@rafinery/cli 0.8.16 → 0.11.0

package/lib/loop-cache.mjs

@@ -0,0 +1,67 @@
+// The checkpoint-written loop-event cache + the sage-due comparator (wave 5.5).
+//
+// Sage's trigger never fired organically: it was a discretionary end-of-session
+// SOP step (the same disease the capture engine cured — "capture never fired,
+// authoring was discretionary SOP"). The bridge makes DETECTION mechanical:
+// `rafa checkpoint` already makes one best-effort get_loop_events call — it now
+// caches recent event SHAPES here (.rafa/loop-events-tail.json — category/at
+// only, subjects excluded: the smallest honest cache), and the SessionStart
+// digest compares the cache against the learnings ledger LOCALLY, printing
+// "sage due" with ZERO added platform calls. Front-of-session, where reminders
+// get obeyed — only the spawn stays with the conductor.
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const LOOP_CACHE_REL = "loop-events-tail.json";
+export const loopCachePath = (cwd) => join(cwd, ".rafa", LOOP_CACHE_REL);
+
+export function readLoopCache(cwd = process.cwd()) {
+  try {
+    const doc = JSON.parse(readFileSync(loopCachePath(cwd), "utf8"));
+    if (doc?.schemaVersion !== 1 || !Array.isArray(doc.events)) return null;
+    return doc;
+  } catch {
+    return null;
+  }
+}
+
+export function writeLoopCache(cwd, { fetchedAt, events }) {
+  const rows = (events ?? [])
+    .map((e) => ({ category: e.category, at: e.at }))
+    .filter((e) => typeof e.category === "string" && Number.isFinite(e.at));
+  const categories = {};
+  for (const e of rows) categories[e.category] = (categories[e.category] ?? 0) + 1;
+  const doc = {
+    schemaVersion: 1,
+    fetchedAt,
+    newestAt: rows.reduce((m, e) => Math.max(m, e.at), 0) || null,
+    count: rows.length,
+    categories,
+    events: rows,
+  };
+  mkdirSync(join(cwd, ".rafa"), { recursive: true });
+  writeFileSync(loopCachePath(cwd), JSON.stringify(doc, null, 2) + "\n");
+  return doc;
+}
+
+// The deterministic trigger condition from the rafa-sage SOP: fire only when
+// the count of loop events NEWER than the learnings ledger's newest entry
+// reaches the threshold (≥10 — under that is noise, not a pattern). No ledger
+// yet (ledgerNewestAt == null) = sage never ran → every cached event counts.
+export function sageDue({ events, ledgerNewestAt, threshold = 10 }) {
+  const rows = events ?? [];
+  const fresh =
+    ledgerNewestAt == null ? rows : rows.filter((e) => e.at > ledgerNewestAt);
+  return { due: fresh.length >= threshold, count: fresh.length, threshold };
+}
+
+// Newest learnings-pass timestamp, parsed LOCALLY from the committed ledger
+// (`- Generated: YYYY-MM-DD …`). Returns epoch ms or null (no ledger = never ran).
+export function ledgerNewestAt(ledgerContent) {
+  if (typeof ledgerContent !== "string") return null;
+  const m = ledgerContent.match(/^-\s*Generated:\s*([0-9]{4}-[0-9]{2}-[0-9]{2}(?:[T ][0-9:.Z+-]+)?)/m);
+  if (!m) return null;
+  const t = Date.parse(m[1]);
+  return Number.isFinite(t) ? t : null;
+}

package/lib/mcp-client.mjs

@@ -14,6 +14,25 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { credentialsPath } from "./mcp-config.mjs";
 import { readStamp } from "./stamp.mjs";
+import { CLI_VERSION } from "./releases.mjs";
+
+// The CLI's own actor envelope for state-plane writes (wave 5: REQUIRED on every
+// loop event — strict, no legacy path). model is the explicit "mechanical"
+// sentinel: no LLM ruled here, and the split stays grep-able for sage. The
+// runner honors RAFA_ACTOR_RUNNER first (the platform's sandbox distiller and
+// other tiers export it — sandbox|ci|session), else CI env, else session.
+export function cliActorMeta() {
+  const declared = process.env.RAFA_ACTOR_RUNNER;
+  return {
+    model: "mechanical",
+    agent: `cli@${CLI_VERSION}`,
+    runner: ["sandbox", "ci", "session"].includes(declared)
+      ? declared
+      : process.env.CI
+        ? "ci"
+        : "session",
+  };
+}
 
 const readJson = (file) => {
   try {

package/lib/push.mjs

@@ -128,11 +128,19 @@ export default async function push(args = []) {
   // a push; an unprovisioned repo just skips.
   const emitGate = async (subject, ok) => {
     try {
-      const { callTool } = await import("./mcp-client.mjs");
+      const { callTool, cliActorMeta } = await import("./mcp-client.mjs");
       await callTool(ROOT, "report_loop_event", {
         category: "gate-result",
         outcome: ok ? "exit0" : "failed",
         subject,
+        // Wave 5 trust plane: the gate ACTUALLY ran here, so the event carries
+        // method:"live" + the real exit code, stamped by the mechanical actor.
+        actorMeta: cliActorMeta(),
+        verification: { method: "live", tool: subject, evidence: ok ? "exit 0" : "exit 1" },
+        // Idempotent per (gate, code sha, outcome): re-pushing an identical tree
+        // re-emits the same key and the platform dedupes; a fail→pass transition
+        // at the same sha is two distinct facts and both land.
+        dedupeKey: `${subject}·${codeSha}·${ok ? "exit0" : "failed"}`,
       });
     } catch {
       /* platform unreachable / unprovisioned — the local exit code is still the truth */
@@ -181,6 +189,11 @@ export default async function push(args = []) {
   // on it.
   const verbArg = args.find((a) => a.startsWith("--verb="));
   const verb = verbArg ? verbArg.slice("--verb=".length) : "update";
+  // Custom subject (owner 2026-07-26: reconciliation commits are DESCRIPTIVE):
+  // --message="…" replaces the generic manifest-derived subject; the brain-for
+  // trailer machinery below is untouched — provenance consumers keep their key.
+  const msgArg = args.find((a) => a.startsWith("--message="));
+  const customSubject = msgArg ? msgArg.slice("--message=".length).trim().replace(/"/g, "'") : null;
   const subjectParts = [];
   try {
     const m = JSON.parse(readFileSync(join(rafaDir, "manifest.json"), "utf8"));
@@ -206,9 +219,10 @@ export default async function push(args = []) {
   } catch {
     /* stat is garnish */
   }
-  const subject = `brain(${verb}): ${
-    subjectParts.length ? subjectParts.join(" · ") : "state sync"
-  } · brain-for: ${codeSha}`.replace(/"/g, "'");
+  const subject = (
+    customSubject ??
+    `brain(${verb}): ${subjectParts.length ? subjectParts.join(" · ") : "state sync"} · brain-for: ${codeSha}`
+  ).replace(/"/g, "'");
   try {
     inRafa(
       `git commit -m "${subject}" -m "brain-for: ${codeSha}${stagedStat ? ` · ${stagedStat}` : ""} · cli: ${CLI_VERSION}"`,

package/lib/reflex.mjs

@@ -60,13 +60,17 @@ export default async function reflex(args = []) {
     // 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 { callTool, cliActorMeta } = 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,
+        // Wave 5: actor envelope required on every emit; a consume is mechanical.
+        // One consume per correction id — dedupeKey makes the emit idempotent.
+        actorMeta: cliActorMeta(),
+        dedupeKey: `reflex·${id}`,
       });
     } catch {
       /* unprovisioned repo / platform unreachable — the queue marker is the local truth */

package/lib/releases.mjs

@@ -331,6 +331,84 @@ export const RELEASES = [
       "review.json (the review gate's scored-ranges artifact) joins the " +
       "local-state exclusion — machine state, never brain knowledge.",
   },
+  {
+    version: "0.9.0",
+    contract: 1,
+    plans: 2,
+    requires: "update",
+    summary:
+      "WAVE 5 — trust plane + transport economics (the QA-dogfood fixes). " +
+      "Loop events are STRICT (no legacy path): required actor envelope " +
+      "{model, agent, runner} + required verification {method: static|live, " +
+      "tool, evidence} on verdict/gate categories + idempotent dedupeKey + " +
+      "tier — pre-0.9.0 emits reject loudly (owner: old CLIs discarded). " +
+      "One beat per task boundary: patch_plan_item (field-level item patch) " +
+      "+ checkpoint_task (patch + loop event + decisions, ONE transaction). " +
+      "verify-citations --fix heals drifted cites (unique-grep only — never " +
+      "guesses) and hydrate re-bases served cites on arrival. NEW `rafa " +
+      "facts`: the session-facts plane (memoized verification, sha-anchored " +
+      "invalidation). The SessionStart digest computes 'sage due' from a " +
+      "checkpoint-written loop-event cache — sage's trigger is mechanical. " +
+      "Plan tasks gain validation_tier (light|standard|full — prism depth " +
+      "only; the Done-check never relaxes). Cards/SOPs re-vendored: prism " +
+      "0.8.0 (tool authenticity · structured return · bounded invariant " +
+      "citation) · atlas 3.9.0 · sage 0.4.0 · conductor 2.1.0.",
+  },
+  {
+    version: "0.10.0",
+    contract: 1,
+    plans: 2,
+    requires: "update",
+    summary:
+      "WAVE 6 — the capability arc. NEW: consent-gated SKILL DEPENDENCIES — " +
+      "this release declares 7 third-party skills (tdd · frontend-design · " +
+      "vercel-composition-patterns · requesting-code-review · " +
+      "improve-codebase-architecture · grill-me · grilling), and `rafa " +
+      "update`/`init` offers them ONCE with per-skill reasons, installs " +
+      "package-manager style into the HARNESS-NEUTRAL .agents/skills/ " +
+      "(Claude Code · Codex · Cursor read the same convention), verifies " +
+      "(frontmatter · hashes · licenses), and stamps rafa.json. Declined is " +
+      "remembered (re-offer: --skills); --yes for CI; a declined set NEVER " +
+      "breaks anything (F1: cards never point at .agents). Agent upgrades " +
+      "riding it: TDD-DEFAULT builds (atlas 4.0.0 — the Done-check is a " +
+      "failing test first at a dev-approved seam; red→green evidence; prism " +
+      "verifies tier-scaled), the UI design method (frontend-design invoked, " +
+      "brain conventions win), the plan-gate GRILL pass (tier-bounded " +
+      "adversarial interview; vacuous Done-checks caught), severity-labeled " +
+      "findings (Critical/Important/Minor — Minor never flips a verdict; " +
+      "prism 0.9.0), and bloom's architecture method (deletion test · " +
+      "Confidence-lined candidates; bloom 0.9.0). Conductor 2.2.0: the " +
+      "toolbox recall surface includes .agents/skills; `rafa leverage " +
+      "--json` carries the harness-neutral agentSkills + skillDeps blocks; " +
+      "doctor gains a capabilities section.",
+  },
+  {
+    version: "0.11.0",
+    contract: 1,
+    plans: 2,
+    requires: "update",
+    summary:
+      "SCHEMA-AWARE RECONCILIATION (owner's 4-case doctrine): distillation " +
+      "resolves the version lattice BEFORE judging — target below source → " +
+      "full target rewrite onto the newer schema (rides the run's gates + " +
+      "push); source below target → incoming candidates lift before judging; " +
+      "equal-but-old → the merged target rewrites onto the runner's latest; " +
+      "equal-and-current → plain diff (today). Either side newer than the " +
+      "runner aborts LOUDLY (update the runner; knowledge is never " +
+      "downgraded); transforms are registered per step and a missing step " +
+      "fails loudly — the ladder never guesses a schema. Also in this " +
+      "release (missed 0.10.0's publish): distill-refutation emits carry the " +
+      "required actor envelope + dedupeKey (a re-run counts once); " +
+      "cliActorMeta honors RAFA_ACTOR_RUNNER (sandbox|ci|session); dependsOn " +
+      "invalidation documented NOT transitive with breadth-as-conservative " +
+      "taught at facts add/help/prism's card (pinned by test). DESCRIPTIVE " +
+      "COMMITS: reconciliation pushes compose reconcile(<branch>): N banked " +
+      "· M refuted · K adjudication (rafa push --message= override); the " +
+      "commit contract requires an agent-readable body on dev commits. The " +
+      "configurable prod branch reaches the CLI: trunkBranchOf (stamp → " +
+      "origin/HEAD → main) drives the checkpoint trunk guard + CI distill " +
+      "target.",
+  },
 ];
 
 // The release this CLI build ships (last entry).

package/lib/review.mjs

@@ -117,6 +117,37 @@ export function relevanceOf(note, diffTokens) {
   return { score, engage: score >= 3 ? "deep" : score >= 1 ? "triage" : "skip" };
 }
 
+// Summary counters, deduped by id (wave 5 T7): get_code_context runs per
+// changed file, so a note citing N changed files lands in N per-file rows —
+// counting it N times inflated every summary number. Dedupe is DISPLAY-COUNT
+// only: the per-file sections (and review.json's files[]) stay per-file — a
+// note governing two files still prints under both. A note keeps its STRONGEST
+// classification: direct beats file-hit, engage beats skip.
+export function summarizeReview(out) {
+  const dedupe = (rows) => {
+    const seen = new Map();
+    for (const r of rows) if (!seen.has(r.id)) seen.set(r.id, r);
+    return [...seen.values()];
+  };
+  const allNotes = out.flatMap((f) => f.notes);
+  const direct = dedupe(allNotes.filter((r) => r.hit === "direct"));
+  const directIds = new Set(direct.map((r) => r.id));
+  const fileHits = dedupe(allNotes.filter((r) => r.hit === "file")).filter(
+    (r) => !directIds.has(r.id),
+  );
+  const engaged = dedupe(allNotes.filter((r) => r.engage !== "skip"));
+  const engagedIds = new Set(engaged.map((r) => r.id));
+  const skipped = dedupe(allNotes).filter((r) => !engagedIds.has(r.id));
+  return {
+    direct,
+    fileHits,
+    imps: dedupe(out.flatMap((f) => f.improvements)),
+    stale: dedupe(allNotes.filter((r) => r.staleCites)),
+    engaged,
+    skipped,
+  };
+}
+
 export default async function review(args = []) {
   const ROOT = process.cwd();
   if (!existsSync(join(ROOT, "rafa.json"))) {
@@ -208,12 +239,7 @@ export default async function review(args = []) {
     console.log(JSON.stringify(report, null, 2));
     return;
   }
-  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"));
+  const { direct, fileHits, imps, stale, engaged, skipped } = summarizeReview(out);
   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)` : ""),

package/lib/session-facts.mjs

@@ -0,0 +1,108 @@
+// The session-facts plane (wave 5.4 — memoized verification).
+//
+// QA-session finding: six subagents independently re-derived the same
+// environment facts ("no node_modules, workspace:* deps") in one build. The fix
+// is NOT a trust-me cache — that would be the assumed-values disease. Every
+// fact carries its VERIFICATION EVIDENCE (the command + exit code that proved
+// it) and a MECHANICAL invalidation rule: the fact is citable only while
+// `git diff <verifiedAtSha>` (against the working tree, uncommitted edits
+// count) leaves its `dependsOn` paths untouched. Memoization with
+// invalidation — the same move as brain = f(code@sha), at session scale.
+//
+// File: .rafa/session-facts.json — machine/session state, excluded from brain
+// pushes (LOCAL_STATE in brain-commit.mjs + IGNORES in brain-repo.mjs; a
+// defensive self-ignore rides every write). Conductor writes via `rafa facts`;
+// subagents READ FIRST and cite "SF-<n> unchanged" instead of re-deriving.
+
+import { execSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const FACTS_REL = "session-facts.json";
+export const factsPath = (cwd) => join(cwd, ".rafa", FACTS_REL);
+
+const EMPTY = () => ({ schemaVersion: 1, facts: [] });
+
+export function readFacts(cwd = process.cwd()) {
+  try {
+    const doc = JSON.parse(readFileSync(factsPath(cwd), "utf8"));
+    if (doc?.schemaVersion !== 1 || !Array.isArray(doc.facts)) return EMPTY();
+    return doc;
+  } catch {
+    return EMPTY();
+  }
+}
+
+// A malformed fact is rejected loudly at write time — never stored, never
+// silently dropped at read time. Returns an error string or null.
+export function validateFact(f) {
+  if (!f || typeof f !== "object") return "fact must be an object";
+  if (typeof f.id !== "string" || !/^SF-\d+$/.test(f.id)) return "id must be SF-<n>";
+  if (typeof f.claim !== "string" || f.claim.trim() === "") return "claim is required";
+  if (!f.evidence || typeof f.evidence.command !== "string" || f.evidence.command.trim() === "")
+    return "evidence.command is required — a fact without the command that proved it is an assumed value";
+  if (!Number.isInteger(f.evidence.exitCode)) return "evidence.exitCode must be an integer";
+  if (typeof f.verifiedAtSha !== "string" || f.verifiedAtSha.trim() === "")
+    return "verifiedAtSha is required";
+  if (!Array.isArray(f.dependsOn)) return "dependsOn must be an array of paths (may be empty)";
+  return null;
+}
+
+export function writeFacts(cwd, doc) {
+  const dir = join(cwd, ".rafa");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(factsPath(cwd), JSON.stringify(doc, null, 2) + "\n");
+  // Defensive self-ignore (post-tool.mjs pattern): the facts file must never
+  // ride a brain push even if this repo predates the wave-5 ignore lists.
+  try {
+    const gi = join(dir, ".gitignore");
+    const cur = existsSync(gi) ? readFileSync(gi, "utf8") : "";
+    const have = new Set(cur.split("\n").map((l) => l.trim()).filter(Boolean));
+    if (!have.has(FACTS_REL))
+      writeFileSync(gi, cur + (cur === "" || cur.endsWith("\n") ? "" : "\n") + FACTS_REL + "\n");
+  } catch {
+    /* ignore-file hygiene is best-effort — the canonical lists also carry it */
+  }
+}
+
+const short = (sha) => String(sha).slice(0, 7);
+
+// The mechanical invalidation rule. A fact goes stale when:
+//   - any dependsOn path changed since verifiedAtSha (working tree INCLUDED —
+//     an uncommitted edit invalidates just as hard), or
+//   - verifiedAtSha is unknown to this checkout (rebase/gc) → fail-honest.
+// Empty dependsOn = environment-shaped fact, never auto-stale (invalidate by hand).
+export function staleFacts(cwd = process.cwd(), doc = null) {
+  const d = doc ?? readFacts(cwd);
+  const out = [];
+  for (const f of d.facts) {
+    try {
+      const changed = execSync(`git diff --name-only ${f.verifiedAtSha}`, {
+        cwd,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      })
+        .split("\n")
+        .filter(Boolean);
+      const hit = (f.dependsOn ?? []).filter((p) =>
+        changed.some((c) => c === p || c.startsWith(p.endsWith("/") ? p : p + "/")),
+      );
+      if (hit.length)
+        out.push({ id: f.id, reason: `dependsOn touched since ${short(f.verifiedAtSha)}: ${hit.join(", ")}` });
+    } catch {
+      out.push({
+        id: f.id,
+        reason: `verifiedAtSha ${short(f.verifiedAtSha)} unknown to this checkout — re-verify or drop`,
+      });
+    }
+  }
+  return out;
+}
+
+export function nextFactId(doc) {
+  const max = doc.facts.reduce((m, f) => {
+    const n = Number(String(f.id).replace(/^SF-/, ""));
+    return Number.isFinite(n) && n > m ? n : m;
+  }, 0);
+  return `SF-${max + 1}`;
+}