@rafinery/cli 0.8.15 → 0.10.0

package/lib/facts.mjs

@@ -0,0 +1,130 @@
+// rafa facts — the session-facts surface (wave 5.4, memoized verification).
+//
+//   rafa facts                        list facts + staleness (the conductor's read)
+//   rafa facts --json                 machine read (spawn-prompt slices)
+//   rafa facts add --claim="…" --command="…" --exit=0 [--depends=a,b] [--tool=…]
+//                                     bank ONE verified fact (stamps HEAD sha)
+//   rafa facts invalidate <SF-n>      drop a fact deliberately
+//   rafa facts prune --stale          drop every mechanically-stale fact
+//
+// A fact is never an assumption: `add` REQUIRES the command + exit code that
+// proved it, and staleness is mechanical (dependsOn ∩ git diff since the
+// verifying sha, working tree included). Subagents read first and cite
+// "SF-<n> unchanged" instead of re-deriving — prism's bounded exception.
+
+import { execSync } from "node:child_process";
+import {
+  factsPath,
+  nextFactId,
+  readFacts,
+  staleFacts,
+  validateFact,
+  writeFacts,
+} from "./session-facts.mjs";
+
+const die = (m) => {
+  console.error(`✗ ${m}`);
+  process.exit(1);
+};
+
+export default async function facts(args = []) {
+  const ROOT = process.cwd();
+  const arg = (k) => {
+    const m = args.find((a) => a.startsWith(`--${k}=`));
+    return m ? m.slice(k.length + 3) : undefined;
+  };
+  const [sub, subArg] = args.filter((a) => !a.startsWith("-"));
+
+  if (sub === "add") {
+    const claim = arg("claim");
+    const command = arg("command");
+    const exit = arg("exit");
+    if (!claim || !command || exit === undefined)
+      die('usage: rafa facts add --claim="…" --command="…" --exit=0 [--depends=a,b]');
+    let sha = "";
+    try {
+      sha = execSync("git rev-parse HEAD", {
+        cwd: ROOT,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      }).trim();
+    } catch {
+      die("not a git repo — session facts anchor to a verifying sha");
+    }
+    const doc = readFacts(ROOT);
+    const fact = {
+      id: nextFactId(doc),
+      claim,
+      evidence: { command, exitCode: Number(exit) },
+      verifiedAtSha: sha,
+      dependsOn: (arg("depends") ?? "").split(",").map((s) => s.trim()).filter(Boolean),
+      at: new Date().toISOString(),
+    };
+    const bad = validateFact(fact);
+    if (bad) die(bad);
+    doc.facts.push(fact);
+    writeFacts(ROOT, doc);
+    console.log(
+      `✓ ${fact.id} banked — "${claim}"\n` +
+        `  evidence: \`${command}\` → exit ${fact.evidence.exitCode} @ ${sha.slice(0, 7)}` +
+        (fact.dependsOn.length
+          ? `\n  citable while untouched: ${fact.dependsOn.join(", ")}` +
+            (fact.dependsOn.every((p) => !p.endsWith("/"))
+              ? "\n  note: invalidation is NOT transitive — if this fact spans a subsystem, declare the" +
+                "\n  enclosing directory (e.g. --depends=src/) so indirect changes stale it. Breadth is the conservative move."
+              : "")
+          : "\n  no dependsOn — environment-shaped; invalidate by hand when the env changes"),
+    );
+    return;
+  }
+
+  if (sub === "invalidate") {
+    if (!subArg) die("usage: rafa facts invalidate <SF-n>");
+    const doc = readFacts(ROOT);
+    const before = doc.facts.length;
+    doc.facts = doc.facts.filter((f) => f.id !== subArg);
+    if (doc.facts.length === before) die(`no fact ${subArg} (see \`rafa facts\`)`);
+    writeFacts(ROOT, doc);
+    console.log(`✓ ${subArg} invalidated`);
+    return;
+  }
+
+  if (sub === "prune") {
+    if (!args.includes("--stale")) die("usage: rafa facts prune --stale");
+    const doc = readFacts(ROOT);
+    const stale = new Set(staleFacts(ROOT, doc).map((s) => s.id));
+    const before = doc.facts.length;
+    doc.facts = doc.facts.filter((f) => !stale.has(f.id));
+    writeFacts(ROOT, doc);
+    console.log(`✓ pruned ${before - doc.facts.length} stale fact(s) · ${doc.facts.length} remain`);
+    return;
+  }
+
+  // Default: list.
+  const doc = readFacts(ROOT);
+  if (args.includes("--json")) {
+    console.log(JSON.stringify({ ...doc, stale: staleFacts(ROOT, doc) }, null, 2));
+    return;
+  }
+  if (doc.facts.length === 0) {
+    console.log(
+      "no session facts banked — `rafa facts add` after verifying something expensive\n" +
+        `  (${factsPath(ROOT).replace(ROOT + "/", "")} · read-first for every spawned agent)`,
+    );
+    return;
+  }
+  const stale = new Map(staleFacts(ROOT, doc).map((s) => [s.id, s.reason]));
+  for (const f of doc.facts) {
+    const s = stale.get(f.id);
+    console.log(
+      `${s ? "!" : "✓"} ${f.id} — ${f.claim}\n` +
+        `    \`${f.evidence.command}\` → exit ${f.evidence.exitCode} @ ${f.verifiedAtSha.slice(0, 7)}` +
+        (s ? `\n    STALE: ${s}` : ""),
+    );
+  }
+  const staleCount = stale.size;
+  console.log(
+    `${doc.facts.length} fact(s)` +
+      (staleCount ? ` · ${staleCount} STALE — re-verify or \`rafa facts prune --stale\`` : " · all fresh"),
+  );
+}

package/lib/gate/compile.mjs

@@ -579,6 +579,15 @@ export function runCompile(argv = []) {
         !(Number.isInteger(data.estimate) && data.estimate >= 0)
       )
         fail(path, "estimate", "optional · non-negative int (points)");
+      if (
+        data.validation_tier !== undefined &&
+        !["light", "standard", "full"].includes(data.validation_tier)
+      )
+        fail(
+          path,
+          "validation_tier",
+          "optional · light|standard|full — bounds prism re-derivation depth ONLY (the Done-check gate never relaxes)",
+        );
       if (data.external !== undefined) {
         const ex = data.external;
         if (
@@ -618,6 +627,9 @@ export function runCompile(argv = []) {
           : {}),
         ...(Number.isInteger(data.priority) ? { priority: data.priority } : {}),
         ...(Number.isInteger(data.estimate) ? { estimate: data.estimate } : {}),
+        ...(["light", "standard", "full"].includes(data.validation_tier)
+          ? { validationTier: data.validation_tier }
+          : {}),
         ...(typeof data.branch === "string" && data.branch !== ""
           ? { branch: data.branch }
           : {}),

package/lib/gate/verify-citations.mjs

@@ -119,6 +119,31 @@ function gitLsGlob(glob, cwd = process.cwd()) {
   }
 }
 
+// EXPORTED — moved here from distiller/doctrine.mjs (wave 5.3; doctrine
+// re-exports it) so the gate's `--fix` can use it without an import cycle
+// (doctrine imports citeResolves/gitGrep FROM this file). Rewrites frontmatter
+// `cites:` DSL locators so a re-grounded citation points at where the token
+// NOW lives. Token-anchored when the cite carries one — two cites sharing
+// file:line with different tokens must not clobber each other; falls back to
+// the locator-only match for callers that pass no token.
+export function rewriteCites(content, regroundings) {
+  let out = content;
+  for (const r of regroundings ?? []) {
+    const fromLoc = r.cite.loc; // file:line[-end]
+    const toLoc = r.to.loc; // file:line
+    const esc = fromLoc.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    if (r.cite.token !== undefined) {
+      const escTok = String(r.cite.token).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      const re = new RegExp(`(-\\s+)${esc}(\\s*::\\s*${escTok}\\s*)$`, "gm");
+      out = out.replace(re, `$1${toLoc}$2`);
+    } else {
+      const re = new RegExp(`(-\\s+)${esc}(\\s*::\\s*)`, "g");
+      out = out.replace(re, `$1${toLoc}$2`);
+    }
+  }
+  return out;
+}
+
 // EXPORTED (refinery-arc-p1-distiller): the doctrine validates a candidate's
 // citations against merged main through the exact same predicate the gate uses,
 // so "resolves for the checker" and "resolves for arbitration" can never drift.
@@ -160,6 +185,14 @@ export function runVerifyCitations(argv = []) {
   const arg = (k, d) => { const m = argv.find((a) => a.startsWith(`--${k}=`)); return m ? m.slice(k.length + 3) : d; };
   const ROOT = arg("root", ".rafa/brain");                                      // --root=.rafa/improve for the improve ledger
   const NOTE_DIRS = arg("dirs", "rules,playbooks").split(",").filter(Boolean);  // --dirs=improvements
+  // --fix (wave 5.3): heal DRIFTED line-cites in place — a failing cite whose
+  // token still lives at exactly ONE grep site gets its locator rewritten, then
+  // the whole verification re-runs clean. gone (0 hits) and ambiguous (>1)
+  // stay untouched and keep failing — the checker never guesses.
+  const FIX = argv.includes("--fix");
+  const fixDrifted = []; // { notePath, cite: {loc, token}, to: {loc} }
+  const fixGone = []; // { note, loc, token }
+  const fixAmbiguous = []; // { note, loc, token, hits }
 
   // --selftest: prove each gate's logic on throwaway fixtures (no brain/repo pollution).
   // prism runs this as its mutation probe — re-running the checker is not proof it still
@@ -264,7 +297,22 @@ export function runVerifyCitations(argv = []) {
     // RESOLUTION
     for (const ct of cites) {
       const { ok, reason } = citeResolves(ct.file, ct.start, ct.end, ct.token);
-      resolution.push({ note: rel, loc: `${ct.file}:${ct.start}${ct.end !== ct.start ? "-" + ct.end : ""}`, token: ct.token, ok, reason });
+      const loc = `${ct.file}:${ct.start}${ct.end !== ct.start ? "-" + ct.end : ""}`;
+      resolution.push({ note: rel, loc, token: ct.token, ok, reason });
+      if (!ok && FIX) {
+        // Classify with the gate's OWN primitives — deliberately NOT
+        // arbitrateCite, which takes hits[0] blindly; the gate never guesses.
+        const hits = gitGrep(ct.token);
+        if (hits.length === 1)
+          fixDrifted.push({
+            notePath: note,
+            cite: { loc, token: ct.token },
+            to: { loc: `${hits[0].file}:${hits[0].line}` },
+            ranged: ct.end !== ct.start,
+          });
+        else if (hits.length === 0) fixGone.push({ note: rel, loc, token: ct.token });
+        else fixAmbiguous.push({ note: rel, loc, token: ct.token, hits: hits.length });
+      }
     }
 
     // COMPLETENESS
@@ -355,6 +403,35 @@ export function runVerifyCitations(argv = []) {
     }
   }
 
+  // ── --fix apply + re-run (wave 5.3) ────────────────────────────────────────
+  if (FIX && (fixDrifted.length || fixGone.length || fixAmbiguous.length)) {
+    const byNote = new Map();
+    for (const f of fixDrifted) {
+      if (!byNote.has(f.notePath)) byNote.set(f.notePath, []);
+      byNote.get(f.notePath).push(f);
+    }
+    for (const [notePath, fixes] of byNote) {
+      const before = readFileSync(notePath, "utf8");
+      const after = rewriteCites(before, fixes);
+      if (after !== before) writeFileSync(notePath, after);
+    }
+    for (const f of fixDrifted)
+      console.log(
+        `  ✓ fixed drifted ${f.cite.loc} → ${f.to.loc} :: ${f.cite.token}` +
+          (f.ranged ? "  (range collapsed to the found line)" : ""),
+      );
+    for (const g of fixGone)
+      console.log(`  ✗ gone ${g.loc} :: ${g.token} — token nowhere in the tree, not fixable [${g.note}]`);
+    for (const a2 of fixAmbiguous)
+      console.log(`  · ambiguous ${a2.loc} :: ${a2.token} — ${a2.hits} grep sites, never guessed [${a2.note}]`);
+    console.log(
+      `--fix: ${fixDrifted.length} drifted healed · ${fixGone.length} gone · ${fixAmbiguous.length} ambiguous (untouched)`,
+    );
+    // Re-run WITHOUT --fix so the report + exit code reflect the healed state
+    // (gone/ambiguous cites still fail — honestly).
+    return runVerifyCitations(argv.filter((a2) => a2 !== "--fix"));
+  }
+
   const rFail = resolution.filter((r) => !r.ok);
   const cFail = completeness.filter((r) => !r.ok);
   const pFail = policy.filter((r) => !r.ok);

package/lib/hydrate.mjs

@@ -22,6 +22,7 @@ import { execSync } from "node:child_process";
 import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { callTool } from "./mcp-client.mjs";
+import { citeResolves, gitGrep } from "./gate/verify-citations.mjs";
 import {
   hashOf,
   materializeImprovement,
@@ -35,6 +36,42 @@ const die = (m) => {
   process.exit(1);
 };
 
+// Wave 5.3 — hydrate-time citation re-basing. Served cites were authored
+// against the brain's base sha; the LOCAL checkout may be newer. Before
+// materializing, re-ground each {file, line, token} with the gate's own
+// primitives: resolves → keep; exactly ONE grep hit → re-cite there;
+// gone/ambiguous → keep the original + a ⚠ (the push gate still catches it).
+// Fail-soft by construction: any error (not a git repo, missing file) keeps
+// the served original untouched. Exported for tests.
+export function rebaseCites(cites, cwd = process.cwd()) {
+  const out = [];
+  const notes = [];
+  for (const c of cites ?? []) {
+    try {
+      const [startRaw, endRaw] = String(c.line).split("-");
+      const start = Number(startRaw);
+      const end = Number(endRaw ?? startRaw);
+      if (!Number.isFinite(start) || citeResolves(join(cwd, c.file), start, end, c.token).ok) {
+        out.push(c);
+        continue;
+      }
+      const hits = gitGrep(c.token, cwd);
+      if (hits.length === 1) {
+        out.push({ ...c, file: hits[0].file, line: hits[0].line });
+        notes.push(`✓ re-based ${c.file}:${c.line} → ${hits[0].file}:${hits[0].line} :: ${c.token}`);
+      } else {
+        out.push(c);
+        notes.push(
+          `⚠ ${c.file}:${c.line} did not re-base (${hits.length === 0 ? "gone" : `ambiguous — ${hits.length} sites`}) — served line may be stale`,
+        );
+      }
+    } catch {
+      out.push(c);
+    }
+  }
+  return { cites: out, notes };
+}
+
 export default async function hydrate(args = []) {
   const ROOT = process.cwd();
 
@@ -94,6 +131,14 @@ export default async function hydrate(args = []) {
     die(e instanceof Error ? e.message : String(e));
   }
   const brainForSha = payload.envelope?.brainForSha ?? null;
+  // Wave 5.3 — arrive pre-healed: re-base served cites against THIS checkout
+  // before the file is written (drifted-but-unique tokens re-cite; gone/
+  // ambiguous keep the original + a ⚠ so nothing is ever guessed).
+  if (Array.isArray(payload.cites) && payload.cites.length > 0) {
+    const { cites, notes } = rebaseCites(payload.cites, ROOT);
+    payload.cites = cites;
+    for (const n of notes) console.log(`  ${n}`);
+  }
   const rel =
     kind === "improvement"
       ? materializeImprovement(ROOT, payload, brainForSha)

package/lib/init.mjs

@@ -131,6 +131,13 @@ export default async function init(args) {
     for (const u of r.updated) console.log(`  ✓ repo MCPs → ${u}`);
   }
 
+  // Wave 6 — offer the declared skill dependencies (consent-gated, verified,
+  // stamped; declined remembered). .agents/skills is COMMITTED dev toolbox.
+  {
+    const { installSkillDeps } = await import("./skill-deps.mjs");
+    await installSkillDeps(TARGET, { args });
+  }
+
   // Keep the brain out of the code repo's diffs; keep the per-dev MCP key out of git.
   const ensureIgnored = (line, label) => {
     const gi = join(TARGET, ".gitignore");
@@ -200,7 +207,8 @@ export default async function init(args) {
 
   console.log(
     `\n✓ Provisioned.\n\nNext steps:\n` +
-      "  1. Commit the vendored files (agents, /rafa command, skills, contract, rafa.json)\n" +
+      "  1. Commit the vendored files (agents, /rafa command, skills, contract, rafa.json,\n" +
+      "     and .agents/skills/ if you installed the skill dependencies)\n" +
       "     — protected-main teams: via a normal MR. The brain remote lives in rafa.json,\n" +
       "     so any teammate's clone bootstraps with  npx rafa pull  (no init needed).\n" +
       "  2. Restart Claude Code in this repo (reload the /rafa command + agents + skills" +

package/lib/leverage/engine.mjs

@@ -6,6 +6,7 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { adapters } from "./adapters/index.mjs";
+import { listAgentSkills, neededSkills, skillsStamp } from "../skill-deps.mjs";
 
 // Merge dependencies from the cwd package.json and any apps/*/package.json (monorepo).
 function readDeps(cwd) {
@@ -66,17 +67,45 @@ export function repoContext(cwd) {
     envFiles,
     envGitignored: envFiles.length === 0 || envIgnored(cwd),
     mcp: readMcp(cwd),
+    // The cross-harness toolbox (wave 6): `.agents/skills/` is harness-NEUTRAL
+    // (Claude Code · Codex · Cursor read the same SKILL.md convention; the
+    // vendored deps ship Codex manifests alongside). Every adapter sees the
+    // same inventory — never a per-toolchain re-read.
+    agentSkills: listAgentSkills(cwd),
+    skillDeps: {
+      needed: neededSkills(cwd).map((d) => ({ name: d.name, why: d.why })),
+      ...skillsStamp(cwd),
+    },
   };
 }
 
 const RANK = { P1: 0, P2: 1, P3: 2 };
 
+// Engine-level tips — rafa's OWN dependency system, harness-neutral by
+// definition (the fix is a rafa command, whatever the host toolchain).
+function engineTips(ctx) {
+  const tips = [];
+  const missing = ctx.skillDeps?.needed ?? [];
+  if (missing.length) {
+    tips.push({
+      id: "skill-deps-missing",
+      priority: "P2",
+      title: `${missing.length} declared skill dependenc${missing.length === 1 ? "y" : "ies"} not installed`,
+      detail: missing.map((d) => `${d.name} — ${d.why}`).join(" · "),
+      fix: "run `rafa update --skills` (consent-gated; declined is remembered)",
+      tool: "rafa",
+    });
+  }
+  return tips;
+}
+
 // Run every detected adapter, tag tips with their tool, and rank by priority.
 export function advise(cwd) {
   const ctx = repoContext(cwd);
   const active = adapters.filter((a) => a.detect(cwd));
-  const tips = active
-    .flatMap((a) => a.recommend(cwd, ctx).map((t) => ({ ...t, tool: a.name })))
-    .sort((x, y) => (RANK[x.priority] ?? 9) - (RANK[y.priority] ?? 9));
+  const tips = [
+    ...engineTips(ctx),
+    ...active.flatMap((a) => a.recommend(cwd, ctx).map((t) => ({ ...t, tool: a.name }))),
+  ].sort((x, y) => (RANK[x.priority] ?? 9) - (RANK[y.priority] ?? 9));
   return { ctx, detected: active.map((a) => a.name), tips };
 }

package/lib/leverage.mjs

@@ -7,16 +7,25 @@ import { adapters, PLANNED } from "./leverage/adapters/index.mjs";
 
 export default async function leverage(args = []) {
   const cwd = process.cwd();
-  const { detected, tips } = advise(cwd);
+  const { ctx, detected, tips } = advise(cwd);
 
   // --json: the DETERMINISTIC toolbox inventory (ratified 2026-07-12) — what
   // the conductor loads at bootstrap and atlas consults during scan's toolbox
   // pass. Machine truth: only what is actually installed, never inferred.
+  // `agentSkills` (wave 6) is the HARNESS-NEUTRAL `.agents/skills/` inventory
+  // — top-level, not under any one toolchain: Claude Code, Codex, and Cursor
+  // all read the same skill convention.
   if (args.includes("--json")) {
     const inventory = {};
     for (const a of adapters)
       if (a.detect(cwd)) inventory[a.id] = a.inspect(cwd);
-    console.log(JSON.stringify({ detected, inventory, tips }, null, 2));
+    console.log(
+      JSON.stringify(
+        { detected, agentSkills: ctx.agentSkills, skillDeps: ctx.skillDeps, inventory, tips },
+        null,
+        2,
+      ),
+    );
     return;
   }
 

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,18 @@ 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.
+export function cliActorMeta() {
+  return {
+    model: "mechanical",
+    agent: `cli@${CLI_VERSION}`,
+    runner: 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 */

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 */