@rafinery/cli 0.8.1 → 0.8.3

package/blueprint/.claude/rafa/hooks/session-start.mjs

@@ -12,6 +12,7 @@
 // (get_code_context batch, ≤ 2s, fail-soft to local counts). Never blocks a
 // session: every path exits 0. Honors RAFA_HOOKS_DISABLED=1.
 
+import { execSync } from "node:child_process";
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -45,6 +46,22 @@ function dirtyEntries(rafaDir) {
   return [...files.keys()];
 }
 
+// OPEN improvements whose cited files are dirty — fixed-in-passing candidates
+// (the ledger lies until each is verified + report_improvement_status'd; this
+// nag is deterministic code, not SOP adherence). null = no local manifest.
+function openFixCandidates(rafaDir, files) {
+  const m = readJson(join(rafaDir, "manifest.json"));
+  if (!m || !Array.isArray(m.improvements)) return null;
+  const want = new Set(files);
+  const out = [];
+  for (const i of m.improvements) {
+    if (i.status !== "open") continue;
+    const hits = [...new Set((i.cites ?? []).filter((c) => want.has(c.file)).map((c) => c.file))];
+    if (hits.length) out.push({ id: i.id, priority: i.priority });
+  }
+  return out;
+}
+
 // file → citing note ids, from the LOCAL manifest (a full pull / prior compile).
 function citersFromManifest(rafaDir, files) {
   const m = readJson(join(rafaDir, "manifest.json"));
@@ -149,6 +166,58 @@ function conflictCopies(rafaDir) {
   return out;
 }
 
+// Capture-machinery self-check (P0, owner ask 2026-07-18): a session that
+// starts — or resumes — on broken sensors must SAY so and hand the dev next
+// steps, not silently lose its knowledge. Wiring + recorded failures only;
+// never a network call inside a hook (doctor does the round-trip on demand).
+function machineryProblems(root, rafaDir) {
+  const problems = [];
+  let settings = null;
+  try {
+    settings = JSON.parse(readFileSync(join(root, ".claude", "settings.json"), "utf8"));
+  } catch {
+    /* handled by the wired() checks below */
+  }
+  const wired = (event, script) =>
+    JSON.stringify(settings?.hooks?.[event] ?? []).includes(`rafa/hooks/${script}`) &&
+    existsSync(join(root, ".claude", "rafa", "hooks", script));
+  if (!wired("PostToolUse", "post-tool.mjs")) problems.push("dirty-marker unwired");
+  if (!wired("UserPromptSubmit", "user-prompt-submit.mjs")) problems.push("steering unwired");
+  let hooksDir = join(root, ".git", "hooks");
+  try {
+    // --git-path resolves worktrees correctly; plain .git/hooks is the fallback.
+    hooksDir = join(
+      root,
+      execSync("git rev-parse --git-path hooks", {
+        cwd: root,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      }).trim(),
+    );
+  } catch {
+    /* plain .git/hooks fallback */
+  }
+  for (const h of ["pre-push", "post-commit", "post-checkout", "post-rewrite"]) {
+    try {
+      if (!readFileSync(join(hooksDir, h), "utf8").includes("rafa"))
+        problems.push(`git ${h} hook is foreign (chain line missing)`);
+    } catch {
+      problems.push(`git ${h} hook missing`);
+    }
+  }
+  try {
+    const rows = readFileSync(join(rafaDir, "sensor-errors.jsonl"), "utf8")
+      .split("\n")
+      .filter(Boolean);
+    const last = rows.length ? JSON.parse(rows[rows.length - 1]) : null;
+    if (last?.t && Date.now() - last.t < 48 * 3600 * 1000)
+      problems.push(`recent swallowed failure: ${last.error ?? last.hook}`);
+  } catch {
+    /* no recorded failures */
+  }
+  return problems;
+}
+
 try {
   if (process.env.RAFA_HOOKS_DISABLED === "1") process.exit(0);
   const root = process.env.CLAUDE_PROJECT_DIR || process.cwd();
@@ -157,6 +226,16 @@ try {
 
   const lines = [];
 
+  const machinery = machineryProblems(root, rafaDir);
+  if (machinery.length)
+    lines.push(
+      `[rafa · doctor] capture machinery is NOT fully live: ` +
+        machinery.slice(0, 4).join(" · ") +
+        (machinery.length > 4 ? ` (+${machinery.length - 4} more)` : "") +
+        ` — run \`npx -y @rafinery/cli doctor\` FIRST and relay its named fixes to the dev as ` +
+        `concrete next steps; until fixed, this session's knowledge may be silently lost.`,
+    );
+
   const dirty = dirtyEntries(rafaDir);
   if (dirty.length) {
     let byNote = citersFromManifest(rafaDir, dirty);
@@ -179,6 +258,20 @@ try {
       );
   }
 
+  if (dirty.length) {
+    const candidates = openFixCandidates(rafaDir, dirty);
+    if (candidates && candidates.length)
+      lines.push(
+        `[rafa · ledger] ${candidates.length} OPEN improvement(s) cite dirty files — possible fixed-in-passing: ` +
+          candidates
+            .slice(0, 6)
+            .map((c) => `${c.priority} ${c.id}`)
+            .join(" · ") +
+          (candidates.length > 6 ? " …" : "") +
+          ` — verify each; fixed → report_improvement_status(id, fixed). An unreported fix leaves the ledger lying.`,
+      );
+  }
+
   const corrections = pendingCorrections(rafaDir);
   if (corrections.length)
     lines.push(

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

@@ -5,6 +5,11 @@ description: "rafa SOP — bloom's continuous-improvement pass: multi-lens, cite
 
 # improve — continuous improvement  (capability #2)
 
+> **First worklist, every pass:** `list_improvements` and treat every `reported`
+> overlay (a live session's fixed-in-passing signal) as a verification candidate —
+> confirm against the code, update the row through the gates. A report stays
+> pending until the ROW catches up; only this pass makes it converge.
+
 rafa's second mission: **drive the codebase worst → well-managed, compounding via work
 the dev is already doing.** A living, prioritized, cited **improvement ledger** — not a throwaway
 report. Kept in `.rafa/improve/`, **never** in `.rafa/brain/` (knowledge and assessment

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

@@ -254,7 +254,7 @@ pipeline; **`--brain-only`** stops after the brain is validated (step 5 PASS)
    spawn `bloom` → `.rafa/improve/`. It reads the *validated* brain as its index, so it only
    runs after PASS.
 7. **Push** — present the full summary (brain verdict/score + top improvements). **On the
-   dev's explicit approval**, `npx @rafinery/cli push` — commits `.rafa/` and pushes to the
+   dev's explicit approval**, `npx @rafinery/cli push --verb=scan` — commits `.rafa/` and pushes to the
    brain remote using the dev's own git auth, stamped `brain-for: <code sha>`. Never without approval.
 8. **The coach offer (founding scan only)** — if this was the repo's FIRST scan and the dev's
    user brain is empty (`list_dev_insights` → none), offer ONCE: *"the code side is mapped —

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

@@ -31,6 +31,12 @@ agent. So:
 
 ## Procedure (run in order; ground everything in code)
 
+0. **Prove the machinery first** — `npx -y @rafinery/cli doctor` (capture-engine P0). A
+   brain can only stay valid if capture is alive: sensors wired, hook scripts parse, the
+   heartbeat lands. Doctor failing is NOT a brain blocker (the brain may still be
+   faithful) — record it as a named finding in the checklist's health notes with
+   doctor's own fixes as the next steps; the dev must see a dead capture chain in the
+   report card, not discover it at the next empty distill.
 1. **Re-run the checker yourself** — `npx @rafinery/cli verify-citations`. Record exit
    code + counts (resolution / completeness / policy / **absence / inventory** — checker
    v2 mechanizes the 2026-06-08 ratchet: declared `absent:` tokens re-grepped, coverage

package/lib/checkpoint.mjs

@@ -40,6 +40,16 @@ export default async function checkpoint() {
   } catch {
     die("not a git repo — run from your code repo root");
   }
+  // P0 heartbeat — sensor liveness must reach the PLATFORM, not just a dev who
+  // thinks to ask (`rafa status`). Fires on every checkpoint, every branch,
+  // BEFORE the trunk guard; best-effort — telemetry never blocks the job.
+  try {
+    const { collectSensorHealth } = await import("./sensor-health.mjs");
+    await callTool(ROOT, "report_sensor_health", collectSensorHealth(ROOT));
+  } catch {
+    /* unprovisioned repo or platform unreachable — the checkpoint continues */
+  }
+
   // The working set is BRANCH state. On the trunk, knowledge changes go
   // through scan → compile → rafa push (the org brain's one writer surface).
   if (branch === "main" || branch === "master") {
@@ -49,6 +59,21 @@ export default async function checkpoint() {
     return;
   }
 
+  // The commit this capture is grounded against (contract: capturedAtSha —
+  // absent = unknown grounding). One HEAD per checkpoint push; the merge-time
+  // ancestry sweep keys on it, so a missing sha only narrows that sweep,
+  // never blocks the checkpoint.
+  let capturedAtSha = "";
+  try {
+    capturedAtSha = execSync("git rev-parse HEAD", {
+      cwd: ROOT,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    /* unborn HEAD (fresh repo) — sync without grounding */
+  }
+
   const sidecar = readSidecar(ROOT);
   const syncBranch = (sidecar.sync[branch] = sidecar.sync[branch] ?? {});
 
@@ -76,6 +101,22 @@ export default async function checkpoint() {
 
   if (candidates.length === 0) {
     console.log(`✓ working set clean on ${branch} — nothing to checkpoint`);
+    // 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
+    // branch. Non-blocking, one line — the human decides if it's a real gap.
+    try {
+      const { readDirty } = await import("./dirty.mjs");
+      const dirtyCount = readDirty(ROOT).files.length;
+      if (dirtyCount > 0)
+        console.log(
+          `⚑ ${dirtyCount} code edit(s) recorded this cycle, ZERO brain files captured on ${branch} — ` +
+            `if decisions/gotchas/contracts were learned, they die with the session. ` +
+            `Worth a note? (notes, improvement files, and intent records all ride \`rafa checkpoint\`)`,
+        );
+    } catch {
+      /* nudge is best-effort — never block a checkpoint */
+    }
     return;
   }
 
@@ -84,6 +125,7 @@ export default async function checkpoint() {
   try {
     payload = await callTool(ROOT, "checkpoint_sync", {
       branch,
+      ...(capturedAtSha ? { capturedAtSha } : {}),
       // WHO/WHAT executed — the CLI knows itself; the MODEL is the session's to
       // report (RAFA_ACTOR_MODEL env, set by the conductor) — never guessed.
       actorMeta: {

package/lib/ci-setup.mjs

@@ -23,9 +23,13 @@ const WORKFLOW = `# rafa reconcile — knowledge propagates exactly like the cod
 #   RAFA_BRAIN_TOKEN    a token with push access to the BRAIN repo (distill only)
 #
 # Fires on the merge EVENT itself (PR closed+merged), so squash/rebase merges are
-# detected correctly — git ancestry is never consulted. If distillation cannot run
-# (missing secret, failed gate) it fails LOUD and the branch's working set stays
-# intact — the next dev session gets the standard distill offer (fallback chain).
+# detected correctly. The distill job ALSO runs an ancestry sweep: any still-active
+# working-set row (any branch) whose capturedAtSha is reachable from merged main is
+# provably-merged backlog — an earlier merge whose distill never ran, or a direct
+# push — and folds into the same run. The sweep needs full history (fetch-depth: 0).
+# If distillation cannot run (missing secret, failed gate) it fails LOUD and the
+# branch's working set stays intact — the next dev session gets the standard
+# distill offer (fallback chain).
 
 name: rafa reconcile
 
@@ -58,6 +62,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           ref: \${{ github.event.repository.default_branch }} # merged main = the validation target
+          fetch-depth: 0 # full history — the ancestry sweep proves prior merges
       - uses: actions/setup-node@v4
         with:
           node-version: 20
@@ -76,13 +81,52 @@ jobs:
           RAFA_BRAIN_TOKEN: \${{ secrets.RAFA_BRAIN_TOKEN }}
           RAFA_AGENT_SDK_DIR: \${{ runner.temp }}/rafa-sdk
           RAFA_HOOKS_DISABLED: "1" # headless — the M5 sensors are session instruments
+          RAFA_MERGE_SHA: \${{ github.event.pull_request.merge_commit_sha }} # keys the run record
+          RAFA_TARGET_BRANCH: \${{ github.event.pull_request.base.ref }}
         run: npx -y @rafinery/cli distill --headless "\${{ github.event.pull_request.head.ref }}"
 `;
 
+// Pristine-detection for upgrades: a byte-diff alone cannot tell "user tuned
+// this" from "our template moved on" — and mislabeling a stale pristine
+// install as tuned strands it on old behavior forever (the ancestry sweep is
+// inert without fetch-depth: 0). Comparison ignores comments/blank lines;
+// PREVIOUS_NORMALIZED holds every historical pristine body, so a file that
+// matches one is upgraded in place and only a genuinely tuned file is left
+// alone. (Comment-only tuning is knowingly not preserved.)
+const normalize = (s) =>
+  s
+    .split("\n")
+    .map((l) => l.trimEnd())
+    .filter((l) => {
+      const t = l.trim();
+      return t !== "" && !t.startsWith("#");
+    })
+    .join("\n");
+const PREVIOUS_NORMALIZED = [
+  // v1 (pre ancestry-sweep, pre run-record): identical body minus the lines
+  // those two features added. Derived, not duplicated — v1 never shipped a
+  // byte that differs otherwise.
+  normalize(WORKFLOW)
+    .split("\n")
+    .filter(
+      (l) =>
+        !l.includes("fetch-depth: 0") &&
+        !l.includes("RAFA_MERGE_SHA") &&
+        !l.includes("RAFA_TARGET_BRANCH"),
+    )
+    .join("\n"),
+];
+
 export default async function ciSetup(args = []) {
   const ROOT = process.cwd();
   const target = join(ROOT, WORKFLOW_PATH);
 
+  console.log(
+    "OPTIONAL — the platform reconciles merges automatically (no CI, no repo secrets).\n" +
+      "This wires the org-CI ADAPTER instead: reconciliation compute runs in YOUR\n" +
+      "GitHub Actions on YOUR secrets. Most teams should skip this.\n",
+  );
+
   if (existsSync(target)) {
     const current = readFileSync(target, "utf8");
     if (current === WORKFLOW) {
@@ -90,6 +134,11 @@ export default async function ciSetup(args = []) {
     } else if (args.includes("--overwrite")) {
       writeFileSync(target, WORKFLOW);
       console.log(`✓ ${WORKFLOW_PATH} updated (--overwrite)`);
+    } else if (PREVIOUS_NORMALIZED.includes(normalize(current))) {
+      writeFileSync(target, WORKFLOW);
+      console.log(
+        `✓ ${WORKFLOW_PATH} upgraded from an older pristine template (no local tuning detected)`,
+      );
     } else {
       console.log(
         `! ${WORKFLOW_PATH} exists and differs — left untouched (yours may be tuned).\n` +
@@ -113,6 +162,8 @@ Next steps (repo Settings → Secrets and variables → Actions):
   4. RAFA_BRAIN_TOKEN   — a token with push access to the BRAIN repo (the distill
                           job pushes validated knowledge there).
   5. Commit the workflow via your normal MR flow.
+  6. Verify the whole capture chain:  npx @rafinery/cli doctor  (sensors, scripts,
+     platform round-trip — exit 1 names any fix).
 
 The rigor gradient this wires: dev↔dev = CAS + session prompt · branch↔branch =
 free mechanical fold · branch→main = full distillation + gates. Cost tracks

package/lib/dirty.mjs

@@ -34,6 +34,31 @@ export function readDirty(root = process.cwd()) {
   return { file, files: [...files.entries()].map(([f, t]) => ({ f, t })) };
 }
 
+// OPEN improvements whose cited files are dirty — the fixed-in-passing detector
+// (live-catch 2026-07-17: a session hand-fixed five P2s and the ledger kept
+// saying "open"; SOP text alone is the proven weak link, so the nag is CODE).
+// A dirty file cited by an open improvement is a strong signal the fix may
+// already exist — the session verifies and reports; the queue never guesses.
+// null = no local manifest here (honest unknown, not zero).
+export function resolveOpenFixCandidates(root, dirtyFiles) {
+  const path = join(root, ".rafa", "manifest.json");
+  if (!existsSync(path)) return null;
+  let m;
+  try {
+    m = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+  const want = new Set(dirtyFiles);
+  const out = [];
+  for (const i of m.improvements ?? []) {
+    if (i.status !== "open") continue;
+    const files = [...new Set((i.cites ?? []).filter((c) => want.has(c.file)).map((c) => c.file))];
+    if (files.length) out.push({ id: i.id, priority: i.priority, title: i.title, files });
+  }
+  return out;
+}
+
 // file → citing notes from the local manifest; null = no manifest here (lazy .rafa).
 export function resolveCiters(root, dirtyFiles) {
   const path = join(root, ".rafa", "manifest.json");
@@ -72,6 +97,7 @@ export default async function dirty(args = []) {
   }
 
   const notes = resolveCiters(ROOT, files.map((e) => e.f));
+  const fixCandidates = resolveOpenFixCandidates(ROOT, files.map((e) => e.f));
   const alarm =
     files.length >= DIRTY_FILES_ALARM || (notes !== null && notes.length >= CITED_NOTES_ALARM);
 
@@ -81,6 +107,7 @@ export default async function dirty(args = []) {
         {
           files: files.map((e) => e.f),
           notes, // null = unresolved here (no local manifest) — an honest unknown, not zero
+          openImprovements: fixCandidates, // dirty ∩ open-improvement cites — verify & report_improvement_status
           thresholds: { files: DIRTY_FILES_ALARM, notes: CITED_NOTES_ALARM },
           alarm,
         },
@@ -106,6 +133,16 @@ export default async function dirty(args = []) {
     console.log(`${notes.length} brain note(s) cite them:`);
     for (const n of notes) console.log(`  · ${n.id}  ←  ${n.files.join(", ")}`);
   }
+  if (fixCandidates && fixCandidates.length) {
+    console.log(
+      `⚑ ${fixCandidates.length} OPEN improvement(s) cite files you changed — possible fixed-in-passing:`,
+    );
+    for (const c of fixCandidates)
+      console.log(`  · ${c.priority} ${c.id}  ←  ${c.files.join(", ")}`);
+    console.log(
+      "  verify each: fixed → `report_improvement_status(id, fixed)` (bloom updates the row at its next pass); still open → leave it. An unreported fix leaves the ledger lying.",
+    );
+  }
   console.log(
     alarm
       ? `⚠ drift past threshold — recommend a brain refresh from main (/rafa scan --brain-only), then \`rafa dirty --consume\`.`