ruvnet-brain 4.3.9 → 4.3.11

package/scripts/doc-currency.mjs

@@ -175,7 +175,8 @@ const sha256 = (s) => crypto.createHash('sha256').update(s).digest('hex');
 
 // ── the governed set ────────────────────────────────────────────────────────────────────────────
 
-// Resolve every declared entry to a concrete blob at HEAD. Globs expand through the index; a
+// Resolve tracked declarations against actual working bytes. HEAD establishes membership,
+// not the content currently being verified. Globs expand through the index; a
 // literal entry is looked up with `git cat-file --batch-check`, which distinguishes blob / tree /
 // missing in ONE process and — unlike `git rev-parse HEAD:<p>` — never prints the requested path
 // back as if it were an answer.
@@ -220,8 +221,30 @@ export function resolveGoverned(root, entries) {
       continue;
     }
     const hit = byPath.get(e.path) || { sha: null, type: onDisk ? 'untracked' : 'missing' };
-    const type = hit.type === 'missing' && onDisk ? 'untracked' : hit.type;
-    results.push({ ...e, type, sha: hit.sha, onDisk, resolved: type === 'blob' });
+    let type = hit.type === 'missing' && onDisk ? 'untracked' : hit.type;
+    let sha = hit.sha;
+    if (type === 'blob') {
+      try {
+        const relative = path.relative(path.resolve(root), path.resolve(abs));
+        if (!relative || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+          throw new Error('governed path escapes project');
+        }
+        let current = path.resolve(root);
+        for (const part of relative.split(path.sep)) {
+          current = path.join(current, part);
+          if (fs.lstatSync(current).isSymbolicLink()) throw new Error('governed path contains a symlink');
+        }
+        if (!fs.lstatSync(abs).isFile()) throw new Error('governed blob is not a regular file');
+        const bytes = fs.readFileSync(abs);
+        // Git blob identity without writing objects or invoking one process per file.
+        // Unchanged bytes retain the existing recipe; staged and unstaged edits both expire it.
+        sha = crypto.createHash('sha1').update(`blob ${bytes.length}\0`).update(bytes).digest('hex');
+      } catch {
+        type = onDisk ? 'unsafe-working-source' : 'missing';
+        sha = null;
+      }
+    }
+    results.push({ ...e, type, sha, onDisk, resolved: type === 'blob' });
   }
   return results;
 }
@@ -290,7 +313,7 @@ export function deriveImpl(root, governed, { checkWiring = true } = {}) {
 export const DRIFT_COMMITS_STALE = 2;
 export const DRIFT_DAYS_STALE = 7;
 
-export function deriveDrift(root, docRel, governed) {
+export function deriveDrift(root, docRel, governed, { floorSha = null } = {}) {
   const paths = governed.filter((g) => g.resolved).map((g) => g.path);
   if (!paths.length) return { state: 'not-applicable', commits: 0, days: 0, reason: 'no resolvable governed paths' };
   const doc = lastCommit(root, docRel);
@@ -310,8 +333,16 @@ export function deriveDrift(root, docRel, governed) {
   // paths is version-identifier lines cannot have changed any decision, so it does not count. Any
   // commit touching one substantive line still counts in full — this narrows the trigger, never the
   // verdict.
+  const floor = floorSha && git(root, ['rev-parse', '--verify', `${floorSha}^{commit}`]);
+  const resolvedFloor = floor?.ok ? floor.out : null;
   const shas = (() => {
-    const r = git(root, ['rev-list', `${doc.sha}..HEAD`, '--', ...paths]);
+    // With --changed, only movement introduced after the candidate merge-base can consume the
+    // candidate's drift budget. Historical debt remains visible in an unscoped report, but cannot
+    // turn one new governed edit into a threshold breach merely because the ADR was already stale.
+    const range = resolvedFloor
+      ? ['HEAD', `^${doc.sha}`, `^${resolvedFloor}`]
+      : [`${doc.sha}..HEAD`];
+    const r = git(root, ['rev-list', ...range, '--', ...paths]);
     return r.ok && r.out ? r.out.split('\n').filter(Boolean) : [];
   })();
   const VERSION_FIELD = /^[+-]\s*"?(version|releaseTag|brainVersion|softwareVersion|tag)"?\s*[:=]/i;
@@ -327,12 +358,20 @@ export function deriveDrift(root, docRel, governed) {
   const substantive = shas.filter((s) => !isVersionOnly(s));
   const commits = substantive.length;
 
-  const codeR = git(root, ['log', '-1', '--format=%ad', '--date=short', `${doc.sha}..HEAD`, '--', ...paths]);
-  const codeDate = codeR.ok && codeR.out ? codeR.out.split('\n')[0] : null;
+  const codeR = substantive.length
+    ? git(root, ['show', '-s', '--format=%ad', '--date=short', substantive[0]])
+    : null;
+  const codeDate = codeR?.ok && codeR.out ? codeR.out.split('\n')[0] : null;
+
+  let anchorDate = doc.date;
+  if (resolvedFloor && git(root, ['merge-base', '--is-ancestor', doc.sha, resolvedFloor]).ok) {
+    const floorR = git(root, ['show', '-s', '--format=%ad', '--date=short', resolvedFloor]);
+    if (floorR.ok && floorR.out) anchorDate = floorR.out.split('\n')[0];
+  }
 
   let days = 0;
   if (codeDate) {
-    const d0 = Date.parse(`${doc.date}T00:00:00Z`);
+    const d0 = Date.parse(`${anchorDate}T00:00:00Z`);
     const d1 = Date.parse(`${codeDate}T00:00:00Z`);
     if (Number.isFinite(d0) && Number.isFinite(d1)) days = Math.max(0, Math.round((d1 - d0) / 86400000));
   }
@@ -412,7 +451,7 @@ export function evaluateDoc(root, rel, opts = {}) {
   const fm = parseFrontmatter(text);
   const k = fm.keys;
 
-  const CONVENTION_KEYS = ['status', 'date', 'updated', 'impl', 'governs', 'verified', 'verified_digest'];
+  const CONVENTION_KEYS = ['status', 'date', 'updated', 'impl', 'governs', 'verified', 'verified_digest', 'reviewed_digest'];
   const declared = CONVENTION_KEYS.filter((key) => k[key] !== undefined);
   // A document predating the convention carries NONE of its keys. That is a derived property of the
   // file, not a hardcoded list of filenames — a new doc written to the convention can never be
@@ -586,7 +625,28 @@ export function evaluateDoc(root, rel, opts = {}) {
   }
 
   // ── drift ─────────────────────────────────────────────────────────────────────────────────────
-  const drift = deriveDrift(root, rel, governed);
+  // A review records examination and findings, NOT normative agreement, acceptance, or verified
+  // implementation. Use the existing digest: frontmatter and the Currency log already exclude
+  // their own metadata, while every governed byte and normative claim remains covered unchanged.
+  // Require an explicit review row naming this digest and a governed-source referent. This checks
+  // evidence structure, never sincerity; changing a date or merely dirtying a doc proves no review.
+  const log = parseCurrencyLog(root, text);
+  const reviewedDigest = k.reviewed_digest || null;
+  const reviewMatch = Boolean(reviewedDigest && digest.digest && reviewedDigest === digest.digest);
+  const reviewRow = reviewedDigest && log.rows.find((row) => /^\d{4}-\d{2}-\d{2}$/.test(row.date)
+    && /\breview(?:ed)?\b/i.test(row.what)
+    && `${row.what} ${row.why}`.split(/[^a-f0-9]+/i).includes(reviewedDigest)
+    && row.referents.some((ref) => ref.kind === 'path'
+      && governed.some((g) => g.resolved && g.path === ref.value)));
+  const reviewed = reviewMatch && Boolean(reviewRow);
+  doc.review = { stored: reviewedDigest, computed: digest.digest, match: reviewMatch,
+    recorded: Boolean(reviewRow), current: reviewed };
+  if (reviewedDigest && !reviewed) {
+    add(WARN, 'review-unsubstantiated', !reviewMatch
+      ? 'reviewed_digest does not bind the current document and governed bytes — no current review is established'
+      : 'reviewed_digest requires a dated Currency log review row naming this digest and a governed-source path — no current review is established');
+  }
+  const drift = deriveDrift(root, rel, governed, { floorSha: opts.driftFloor });
   doc.drift = drift;
   // A DECISION THAT IS NOT IN FORCE CANNOT DRIFT (ADR-056, 2026-07-27). Rejected / Superseded /
   // Deprecated documents describe a path NOT taken, or one another document has since taken over.
@@ -600,15 +660,16 @@ export function evaluateDoc(root, rel, opts = {}) {
   // day someone un-rejects it the finding returns to BLOCK on its own.
   const notInForce = /^(rejected|superseded|deprecated)$/i.test(statusWord || '');
   if (drift.state === 'presumed-stale') {
-    add(notInForce ? WARN : BLOCK, 'presumed-stale',
-      `governed code moved ${drift.commits} commit(s) (${drift.days}d) after the document's own last commit (${drift.docDate}) — nobody has checked since it moved. Paths: ${drift.paths.join(', ')}`
-      + (notInForce ? ` — reported, NOT blocked: status "${statusWord}" means this decision is not in force, so it cannot drift from code it never governed` : ''));
+    add(notInForce || reviewed ? WARN : BLOCK, 'presumed-stale',
+      `governed code moved ${drift.commits} commit(s) (${drift.days}d) after the document's own last commit (${drift.docDate}). Paths: ${drift.paths.join(', ')}`
+      + (reviewed ? ' — exact current bytes have a recorded review; historical drift remains visible, but does not establish missing review. This is NOT normative agreement or verification.'
+        : notInForce ? ` — reported, NOT blocked: status "${statusWord}" means this decision is not in force, so it cannot drift from code it never governed`
+          : ' — no source-bound review is recorded since it moved.'));
   } else if (drift.state === 'lagging') {
     add(WARN, 'lagging', `governed code moved ${drift.commits} commit(s) after the document — normal within a session; reported, not blocked`);
   }
 
   // ── currency log ──────────────────────────────────────────────────────────────────────────────
-  const log = parseCurrencyLog(root, text);
   doc.currencyLog = log;
   if (!doc.legacy && !log.present) {
     add(WARN, 'no-currency-log', 'no `## Currency log` section — the *why* of each change is unrecorded');
@@ -784,12 +845,23 @@ export function main(argv = process.argv.slice(2)) {
   }
 
   const dirs = a.dirs ?? DEFAULT_DIRS;
-  const result = evaluate(a.root, { dirs, checkWiring: !a.noWiring });
+  let touched = null;
+  let driftFloor = null;
+  if (a.changed) {
+    const diff = git(a.root, ['diff', '--name-only', `${a.changed}...HEAD`]);
+    if (!diff.ok) {
+      process.stderr.write('[doc-currency] candidate base cannot be resolved.\n');
+      return 1;
+    }
+    touched = new Set(diff.ok ? diff.out.split('\n').filter(Boolean) : []);
+    const base = git(a.root, ['merge-base', a.changed, 'HEAD']);
+    if (!base.ok || !base.out) return 1;
+    if (base.ok && base.out) driftFloor = base.out.split('\n')[0];
+  }
+  const result = evaluate(a.root, { dirs, checkWiring: !a.noWiring, driftFloor });
 
   let scope = null;
-  if (a.changed) {
-    const r = git(a.root, ['diff', '--name-only', `${a.changed}...HEAD`]);
-    const touched = new Set(r.ok ? r.out.split('\n').filter(Boolean) : []);
+  if (touched) {
     scope = changedDocumentScope(result.docs, touched);
   }
 
@@ -816,7 +888,7 @@ export function main(argv = process.argv.slice(2)) {
       recipe: DIGEST_RECIPE,
       docs: result.docs.map((d) => ({
         file: d.file, id: d.id, legacy: d.legacy, status: d.status, date: d.date, updated: d.updated,
-        implStored: d.implStored, impl: d.impl, digest: d.digest, drift: d.drift,
+        implStored: d.implStored, impl: d.impl, digest: d.digest, review: d.review, drift: d.drift,
         governs: d.governsDeclared, findings: d.findings,
       })),
     }, null, 2) + '\n');

package/scripts/git-hooks/pre-push

@@ -1,163 +1,5 @@
 #!/bin/sh
-# RuvNet Brain — pre-push gate. NON-OPTIONAL. Runs on every `git push`.
-#
-# WHY (2026-07-17): a real client (Jan) hit npx ruvnet-brain@latest with a stale package whose
-# self-update manifest 404'd. The root cause wasn't the bug — it was that the CHECK was optional
-# and I skipped it. This hook removes the discretion: it refuses the push if the version surfaces
-# disagree or the self-update manifest 404s. It does not care whether I remembered, or was in a
-# hurry, or "was pretty sure it was fine." Pass or the push does not happen.
-#
-# It blocks ONLY on what is knowable before a push. npm-latest and the live explainer are verified
-# post-publish by `node scripts/release.mjs --publish` (the only sanctioned ship path).
-#
-# Escape hatch is `git push --no-verify` — but if you use it, you are consciously overriding a gate
-# that exists because of a specific failure that cost real user trust. Own that out loud.
-#
-# SECRET SCAN (2026-07-21): a buggy diagnostic echoed live OPENAI and OPENROUTER keys into a
-# terminal, and AgentDB's session autocapture wrote them to .swarm/. Nothing reached git — but the
-# only thing that stopped it was a GLOBAL gitignore that does not travel to a clone or another
-# machine. Relying on "the file happened to be ignored" is not a control. This is: a real key
-# pattern in anything being pushed refuses the push. Placeholders (your-key, abc123, xxxx,
-# deadbeef, example) are excluded, because rUv's own docs are full of them and a gate that cries
-# wolf on documentation is a gate people learn to bypass.
-#
-# SCOPE FIX (2026-07-22): this scanned `git diff --cached HEAD` — the STAGED INDEX. But a push ships
-# COMMITS, and at push time the index is normally clean, so the scan read nothing. Proven both ways
-# in a scratch repo: a key COMMITTED then pushed sailed through, while the same key merely STAGED was
-# blocked. The gate could only catch the one case that never happens. It is the same defect class the
-# 7e715bb commit fixed in the *test* — a check that cannot fail in the situation it was written for —
-# which survived here in the *scan*. Now it reads the actual push range from the hook's stdin.
-RANGE_DIFF=""
-CURRENCY_BASE=""
-while read -r _local_ref local_sha _remote_ref remote_sha; do
-  [ -z "$local_sha" ] && continue
-  case "$local_sha" in *[!0]*) ;; *) continue ;; esac        # all-zeros = branch deletion, nothing to scan
-  case "$remote_sha" in
-    ""|*[!0-9a-f]*|0000000000000000000000000000000000000000)  # new branch: scan its whole history vs other refs
-      RANGE_DIFF="$RANGE_DIFF$(git diff --no-color -U0 "$(git merge-base HEAD origin/main 2>/dev/null || echo '')" "$local_sha" 2>/dev/null)"
-      # ADR-056 §5: a new branch has no remote counterpart, so the merge-base with main is the only
-      # honest base. If even that cannot resolve, CURRENCY_BASE stays empty and the currency check is
-      # SKIPPED rather than run against a guess — never a scope invented from nothing.
-      [ -z "$CURRENCY_BASE" ] && CURRENCY_BASE="$(git merge-base HEAD origin/main 2>/dev/null || true)" ;;
-    *)
-      RANGE_DIFF="$RANGE_DIFF$(git diff --no-color -U0 "$remote_sha" "$local_sha" 2>/dev/null)"
-      # ADR-056: the remote tip is only a valid "what did I change" base when it is an ANCESTOR of
-      # what we are pushing. After a rebase or squash it is NOT — the range then spans the entire
-      # rewrite and drags in every document the upstream branch already carried, red ones included.
-      # Measured 2026-07-27: a force-push after rebasing onto main was refused for ADR-054 and
-      # ADR-055 — two documents on main that this branch never touched. GPT-5.6 predicted exactly
-      # this in the ADR-056 duel ("rebase or squash changes the touched-file set without changing
-      # whether a violation is genuinely new"). So: ancestor => use it; otherwise fall back to the
-      # merge-base with main, which is the honest answer to "what is mine".
-      if [ -z "$CURRENCY_BASE" ]; then
-        if git merge-base --is-ancestor "$remote_sha" "$local_sha" 2>/dev/null; then
-          CURRENCY_BASE="$remote_sha"
-        else
-          CURRENCY_BASE="$(git merge-base "$local_sha" origin/main 2>/dev/null || true)"
-        fi
-      fi ;;
-  esac
-done
-# Fall back to the staged index too, so a pre-commit-style invocation still gets covered.
-RANGE_DIFF="$RANGE_DIFF
-$(git diff --cached --no-color -U0 HEAD 2>/dev/null)"
-
-SECRET_HITS=$(printf '%s' "$RANGE_DIFF" | grep -E "^\+" \
-  | grep -oE "sk-(proj|ant|or-v1)-[A-Za-z0-9_-]{20,}" \
-  | grep -vEi "your-key|abc123|xxxx+|deadbeef|example|placeholder|REDACTED" | head -3)
-if [ -n "$SECRET_HITS" ]; then
-  echo ""
-  echo "  ⛔ PUSH BLOCKED — what looks like a REAL API key is in this push."
-  echo "     matched (prefix only): $(echo "$SECRET_HITS" | cut -c1-14 | tr '\n' ' ')"
-  echo "     Remove it, rotate the key, and push again. Never --no-verify past this one:"
-  echo "     a key that reaches a remote is compromised the moment it lands."
-  echo ""
-  exit 1
-fi
-
-# Hooks may be shared by several git worktrees. Resolving from this script's own path is wrong when
-# core.hooksPath names another checkout: the hook then validates that checkout while pushing the
-# current one (measured 2026-07-28: announced 3.9.128, pushed 3.9.129). Git already knows the
-# worktree whose refs are being pushed, so derive the shipping root from that live repository.
-ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
-if [ -z "$ROOT" ] || [ ! -f "$ROOT/scripts/verify-channels.mjs" ]; then
-  echo "  ⛔ pre-push gate cannot resolve the worktree being pushed."
-  exit 1
-fi
-node "$ROOT/scripts/verify-channels.mjs" --pre-push
-status=$?
-if [ "$status" -ne 0 ]; then
-  echo ""
-  echo "  ⛔ pre-push gate refused this push. A user on some path would get a broken build."
-  echo "     Fix the channel(s) above, then push again. Do not route around this."
-  exit 1
-fi
-
-# Generated public census and command aliases have one source of truth each. Both writers have a
-# `--check` mode specifically for CI/pre-push; until 2026-08-22 nothing invoked either check, so the
-# writers were built and tested but their promised gate did not exist.
-node "$ROOT/scripts/sync-census.mjs" --check
-census_status=$?
-if [ "$census_status" -ne 0 ]; then
-  echo ""
-  echo "  ⛔ pre-push gate refused this push — public census claims have drifted."
-  echo "     Run: node scripts/sync-census.mjs"
-  exit 1
-fi
-
-node "$ROOT/scripts/sync-commands.mjs" --check
-commands_status=$?
-if [ "$commands_status" -ne 0 ]; then
-  echo ""
-  echo "  ⛔ pre-push gate refused this push — command aliases no longer share one body."
-  echo "     Run: node scripts/sync-commands.mjs"
-  exit 1
-fi
-
-# The convergence manifest is the exact source/version/ADR identity consumed by hosted QA.
-# Check it here so a push cannot publish a commit whose generated identity was produced before
-# the final source edit (the failure mode that repeatedly escaped local pre-push validation).
-if [ -f "$ROOT/scripts/convergence-manifest.mjs" ]; then
-  node "$ROOT/scripts/convergence-manifest.mjs"
-  convergence_status=$?
-else
-  convergence_status=0
-fi
-if [ "$convergence_status" -ne 0 ]; then
-  echo ""
-  echo "  ⛔ pre-push gate refused this push — convergence identity is stale."
-  echo "     Run: npm run convergence:write"
-  exit 1
-fi
-
-# ── DOCUMENT CURRENCY (ADR-056 §5) ─────────────────────────────────────────────────────────────────
-# The tool was written and tested on 2026-07-22 and then invoked by NOTHING for five days — absent
-# from this hook, gate.sh, gates.mjs and every workflow, while `wired-check` reported it "wired"
-# because package.json DEFINED an npm alias for it. This line is the whole fix.
-#
-# NO RATCHET, DELIBERATELY. The first draft of ADR-056 proposed a stateful new-vs-pre-existing
-# violation tracker so this gate could coexist with 32 pre-existing BLOCKs forever. Two independent
-# adversarial reviews killed it: a committed baseline is gamed by the same commit that adds the
-# violation, re-deriving at the remote SHA needs a second worktree, and "report the rest forever"
-# is the wolf-cry doc-currency.mjs's own header names as its designed failure mode. The debt was
-# PAID instead (32 BLOCKs -> 4, all four genuine re-reads), which makes the plain gate safe.
-#
-# SCOPED to what this push touches. A pre-existing red document must not block someone who merely
-# walked past it — that teaches people never to touch the red documents, preserving exactly the drift
-# this exists to end. Scope is empty => nothing to check => pass; never a scope invented from nothing.
-if [ -n "$CURRENCY_BASE" ]; then
-  node "$ROOT/scripts/doc-currency.mjs" --check --changed "$CURRENCY_BASE"
-  dc_status=$?
-  if [ "$dc_status" -ne 0 ]; then
-    echo ""
-    echo "  ⛔ pre-push gate refused this push — a document you touched disagrees with its code."
-    echo "     An ADR that describes a world the code left is worse than no ADR."
-    echo "     \`node scripts/doc-currency.mjs --fix\` backfills every date git can prove;"
-    echo "     everything else is a claim only you can make."
-    exit 1
-  fi
-fi
-echo ""
-echo "  ✓ pre-push gate passed — version, channels, secrets, and document currency are clean."
-echo ""
-exit 0
+# Select the active checkout's development check. Qualification is explicit and hosted once.
+set -eu
+ROOT="$(git rev-parse --show-toplevel)"
+exec node "$ROOT/scripts/development-push-check.mjs"

package/scripts/health-repair.mjs

@@ -26,6 +26,7 @@ import { execFileSync, spawnSync } from 'node:child_process';
 import { findStores, diagnose } from './memory-doctor.mjs';
 import { learnerCwd, loadRuntimePreferences } from '../plugin/scripts/runtime-preferences.mjs';
 import { projectDirectory } from '../plugin/scripts/project-identity.mjs';
+import { newestSnapshot, snapshotInventory, MTIME_GRACE_MS } from './snapshot-freshness.mjs';
 
 const HOME = os.homedir();
 // The SAME project root learn-flush.mjs computes, by the same rule — the two halves of the flush
@@ -263,22 +264,39 @@ function distillFleet() {
   const receiptPath = argv.includes('--receipt') ? argv[argv.indexOf('--receipt') + 1] : null;
   const receipt = [];
   const writeReceipt = () => {
-    if (!receiptPath) return;
+    if (!receiptPath) return true;
     try {
       fs.mkdirSync(path.dirname(receiptPath), { recursive: true });
       fs.writeFileSync(receiptPath, JSON.stringify({ at: new Date().toISOString(), stores: receipt }, null, 2));
-    } catch { /* the receipt is for undo; failing to write it must not fail the repair itself */ }
+      return true;
+    } catch { return false; }
   };
 
   for (const t of targets) {
     const dir = path.join(path.dirname(t.db), 'backups');
+    const backupStartedAt = Date.now();
+    let priorSnapshots;
+    try { priorSnapshots = snapshotInventory(dir); }
+    catch (error) { failed.push(`${t.name}: refused to distill — ${error.message}`); continue; }
     try { execFileSync(RUFLO, ['memory', 'backup', '--db', t.db, '--dir', dir], { env: RUFLO_ENV, stdio: 'ignore', timeout: 300_000 }); }
     catch (e) { failed.push(`${t.name}: refused to distill — snapshot failed (${String(e.message).slice(0, 80)})`); continue; }
+    // `memory backup` exiting 0 is not proof a NEW file landed in `dir` — a stale snapshot from a
+    // prior fleet run sitting there already would otherwise be silently accepted as this run's undo
+    // (the exact gap `distill-project.mjs` was fixed for in PR #192, applied here to fleet's own,
+    // separate call site — see the 2026-08-29 Dream Cycle report, "Next steps #1").
+    const snapshot = newestSnapshot(dir, backupStartedAt, MTIME_GRACE_MS, priorSnapshots);
+    if (!snapshot) {
+      failed.push(`${t.name}: refused to distill — snapshot reported success but no fresh file landed in ${dir}`);
+      continue;
+    }
     // Record the snapshot BEFORE distilling, and flush after every store. If the process is killed
     // mid-fleet, the receipt still names every store already modified — a partial receipt is
     // recoverable, a missing one is not.
-    receipt.push({ db: t.db, name: t.name, backupDir: dir });
-    writeReceipt();
+    receipt.push({ db: t.db, name: t.name, backupDir: dir, snapshot });
+    if (!writeReceipt()) {
+      failed.push(`${t.name}: refused to distill — requested undo receipt could not be written`);
+      continue;
+    }
 
     try {
       execFileSync(RUFLO, ['memory', 'distill', 'run', '--db', t.db, '--judge', 'structural', '--budget-usd', '0'],

package/scripts/hook-retirement-check.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { automaticHookRetirementStatus } from '../bin/install.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+export function main() {
+  const result = automaticHookRetirementStatus(ROOT);
+  if (!result.ok) {
+    console.error(`hook-retirement-check: FAIL — ${result.registrations.length} automatic registration(s), ${result.errors.length} manifest error(s)`);
+    for (const error of result.errors) console.error(`  ${error}`);
+    for (const item of result.registrations) console.error(`  ${item.file} ${item.event}: ${item.command || '(empty command)'}`);
+    return 1;
+  }
+  console.log(`hook-retirement-check: PASS — zero automatic Brain registrations across ${result.files.length} source, contract, and host-pointer surfaces`);
+  return 0;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  process.exitCode = main();
+}