ruvnet-brain 4.6.2 → 4.6.4

package/plugin/scripts/continuity-events.mjs

@@ -28,13 +28,10 @@
  * detail.status: 'detected-unconfirmed'`, written only to the project's own local store; the brief never
  * presents one as a standing rule. RUVNET_CONTINUITY_LESSON_DETECT=off turns that detector off.
  */
+import { nativeTurnLines } from './native-turn-transcript.mjs';
 import crypto from 'node:crypto';
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { redactProgression } from './project-progression-contract.mjs';
-import { resolveProjectStore } from './project-store-resolver.mjs';
 
 export const CONTINUITY_NAMESPACE = 'continuity-events';
 export const EVENT_SCHEMA = 'ruvnet-brain.continuity-event';
@@ -265,12 +262,12 @@ function exitOutcome(result) {
 }
 
 /**
- * Typed events from one Claude JSONL turn. Codex rollouts are not parsed (project-progression-sources
- * declares that format unknown); Codex gets decisions/lessons from `last_assistant_message` only.
+ * Typed events from the current native turn. Codex JSONL is normalized mechanically; opaque
+ * custom-tool orchestration inputs cannot manufacture a gate outcome or semantic decision.
  */
 export function collectTurnEvents({ lines = null, lastAssistantMessage = '', host, session, project, env = process.env, at = Date.now() }) {
   const events = [];
-  const turn = lines ? currentTurnRecords(lines) : { userMessage: '', records: [] };
+  const turn = lines ? currentTurnRecords(nativeTurnLines(lines, host)) : { userMessage: '', records: [] };
   const uses = new Map();
   const assistantTexts = [];
   for (const rec of turn.records) {
@@ -306,9 +303,9 @@ export function collectTurnEvents({ lines = null, lastAssistantMessage = '', hos
   for (const text of assistantTexts) {
     for (const line of text.split('\n')) {
       if (DECISION_LINE.test(line)) {
-        events.push(makeEvent({ kind: 'decision', at, host, session, project, source: 'assistant-detected', authoritative: false, summary: line.replace(/\*\*/g, '') }));
+        events.push(makeEvent({ kind: 'decision', at, host, session, project, source: 'assistant-detected', authoritative: false, detail: { status: 'detected-unconfirmed' }, summary: line.replace(/\*\*/g, '') }));
       } else if (LESSON_LINE.test(line)) {
-        events.push(makeEvent({ kind: 'lesson', at, host, session, project, source: 'assistant-detected', authoritative: false, summary: line.replace(/\*\*/g, '') }));
+        events.push(makeEvent({ kind: 'lesson', at, host, session, project, source: 'assistant-detected', authoritative: false, detail: { status: 'detected-unconfirmed' }, summary: line.replace(/\*\*/g, '') }));
       }
     }
   }
@@ -325,79 +322,3 @@ export function collectTurnEvents({ lines = null, lastAssistantMessage = '', hos
   return events.filter((e) => (seen.has(`${e.kind}:${e.id}`) ? false : seen.add(`${e.kind}:${e.id}`)));
 }
 
-/**
- * The owner's own user-level AgentDB hooks (~/.claude/settings.json). Read, never modified. Used to
- * DEFER: where one of them already records a thing, the product does not record it a second time.
- */
-export function userLevelAgentdbHooks({ home = os.homedir(), event, projectDir, env = process.env } = {}) {
-  const found = { turnCapture: false, autocapture: false, ensure: false, ownership: 'unknown', collisionCandidate: false,
-    settings: path.join(home, '.claude', 'settings.json') };
-  if (!['Stop', 'PreCompact', 'SessionEnd', 'SessionStart'].includes(event) || !projectDir
-    || String(env.RUVNET_HOOK_HOST || 'claude') !== 'claude') return found;
-  let doc;
-  try { doc = JSON.parse(fs.readFileSync(found.settings, 'utf8')); } catch { return found; }
-  if (!doc || typeof doc !== 'object' || Array.isArray(doc) || doc.disableAllHooks === true || doc.allowManagedHooksOnly === true) return found;
-  let target, executable;
-  try {
-    for (const file of [path.join(projectDir, '.claude', 'settings.json'), path.join(projectDir, '.claude', 'settings.local.json')]) {
-      let local;
-      try { local = JSON.parse(fs.readFileSync(file, 'utf8')); } catch (error) { if (error.code === 'ENOENT') continue; throw error; }
-      if (!local || typeof local !== 'object' || Array.isArray(local) || local.disableAllHooks === true || local.allowManagedHooksOnly === true) return found;
-    }
-    const deadlineAt = Number(env.RUVNET_SESSION_START_DEADLINE_AT) || Infinity;
-    target = resolveProjectStore({ projectDir, gitTimeoutMs: 500, deadlineAt }).canonicalAgentDbPath;
-    // Bind the direct command to the declared entry of the user's one managed GLOBAL Ruflo.
-    // Arbitrary Node handlers, filenames and source comments do not prove their actual target.
-    if (!process.getuid) return found; // Native Windows ACL ownership is not attested by POSIX uid metadata.
-    const root = path.join(home, '.npm-global', 'lib', 'node_modules', 'ruflo');
-    const manifest = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
-    const declared = typeof manifest.bin === 'string' ? manifest.bin : manifest.bin?.ruflo;
-    if (manifest.name !== 'ruflo' || typeof declared !== 'string' || path.isAbsolute(declared) || declared.split(/[\\/]/).includes('..')) return found;
-    executable = fs.realpathSync.native(path.join(home, '.npm-global', 'bin', 'ruflo'));
-    const entry = fs.realpathSync.native(path.join(root, declared));
-    const relative = path.relative(fs.realpathSync.native(root), entry);
-    const stat = fs.statSync(entry);
-    if (executable !== entry || relative.startsWith('..') || path.isAbsolute(relative) || !stat.isFile() || stat.uid !== process.getuid()) return found;
-    fs.accessSync(executable, fs.constants.X_OK);
-  } catch { return found; }
-  const groups = doc?.hooks?.[event];
-  for (const group of Array.isArray(groups) ? groups : []) {
-    if (group?.enabled === false || group?.disabled === true || (group?.matcher && group.matcher !== '*')) continue;
-    for (const hook of Array.isArray(group?.hooks) ? group.hooks : []) {
-      if (hook?.type !== 'command' || hook.enabled === false || hook.disabled === true || typeof hook.command !== 'string') continue;
-      const command = hook.command.trim();
-      if (/[$`;&|<>\r\n]/.test(command)) continue;
-      const tokens = []; const words = /"([^"\\]*)"|'([^']*)'|([^\s"'\\]+)/g;
-      let match, previous = 0, valid = true;
-      while ((match = words.exec(command))) {
-        if (command.slice(previous, match.index).trim()) { valid = false; break; }
-        tokens.push(match[1] ?? match[2] ?? match[3]); previous = words.lastIndex;
-      }
-      if (!valid || command.slice(previous).trim() || tokens[1] !== 'memory') continue;
-      try { if (!path.isAbsolute(tokens[0]) || fs.realpathSync.native(tokens[0]) !== executable) continue; } catch { continue; }
-      const options = tokens[2] === 'store' ? ['--path', '-p', '--namespace', '-n', '--key', '-k', '--value']
-        : tokens[2] === 'retrieve' ? ['--path', '-p', '--namespace', '-n', '--key', '-k']
-          : tokens[2] === 'init' ? ['--path', '-p'] : [];
-      for (let i = 3; i < tokens.length; i += 2) {
-        if (!options.includes(tokens[i]) || !tokens[i + 1] || tokens[i + 1].startsWith('-')) { valid = false; break; }
-      }
-      if (!valid) continue;
-      const flag = names => {
-        const positions = tokens.flatMap((token, i) => names.includes(token) ? [i] : []);
-        return positions.length === 1 ? tokens[positions[0] + 1] : undefined;
-      };
-      const db = flag(['--path', '-p']);
-      if (!db || !path.isAbsolute(db) || db.split(/[\\/]/).includes('..') || path.resolve(db) !== target) continue;
-      const namespace = flag(['--namespace', '-n']);
-      const captureRegistration = tokens[2] === 'store' && flag(['--key', '-k']) && flag(['--value'])
-        && ((event === 'Stop' && namespace === 'turns') || (['PreCompact', 'SessionEnd'].includes(event) && namespace === 'sessions'));
-      const ensureRegistration = event === 'SessionStart' && ['init', 'retrieve'].includes(tokens[2]);
-      if (captureRegistration || ensureRegistration) found.collisionCandidate = true;
-    }
-  }
-  if (found.collisionCandidate) {
-    found.target = target; found.event = event;
-    found.reason = 'canonical registration alone does not prove capture of the current turn/session';
-  }
-  return found;
-}

package/plugin/scripts/continuity-hook-policy.mjs

@@ -122,8 +122,8 @@ const registration = (id, matcher, hosts) => Object.freeze({ id, matcher, hosts:
  */
 export const CONTINUITY_EVENTS = Object.freeze({
   SessionStart: Object.freeze([
+    // learn-flush is no longer its own registration (ADR-106): session-start schedules it detached.
     registration('session-start', 'startup|resume|clear|compact|fork', ['claude', 'codex']),
-    registration('learn-flush', 'startup|resume|clear|compact|fork', ['claude', 'codex']),
   ]),
   UserPromptSubmit: Object.freeze([
     registration('session-snapshot', '*', ['claude', 'codex']),
@@ -154,7 +154,7 @@ export const CONTINUITY_EVENTS = Object.freeze({
   // no change either (proven live: the real MCP tool_response's `content[0].text` carries the exact
   // "Searched N RuvNet repos" banner and query text the script already looks for).
   PostToolUse: Object.freeze([
-    registration('learn-capture', '^(?:Bash|Write|Edit|MultiEdit|exec_command|apply_patch|functions(?:\\.|__)(?:exec_command|apply_patch))$', ['claude', 'codex']),
+    // learn-capture runs in-process inside session-snapshot's PostToolUse boundary (ADR-106).
     registration('session-snapshot', '*', ['claude', 'codex']),
     registration('grounding-stamp', '^(?:.*__)?search_ruvnet$', ['claude', 'codex']),
   ]),
@@ -186,7 +186,7 @@ export const CONTINUITY_EVENTS = Object.freeze({
     registration('session-snapshot', '*', ['claude', 'codex']),
   ]),
   SessionEnd: Object.freeze([
-    registration('learn-flush', '*', ['claude', 'codex']),
+    // learn-flush is scheduled by session-snapshot's SessionEnd boundary (ADR-106).
     registration('session-snapshot', '*', ['claude', 'codex']),
   ]),
 });

package/plugin/scripts/continuity-journal.mjs

@@ -12,6 +12,7 @@
  * RETAIN_COMMITTED_MS, ages quarantine/corrupt notices after QUARANTINE_REPORT_MS, and bounds committed
  * history at MAX_EVENT_RECORDS. Pending events are never dropped; prolonged outages report pressure.
  */
+import { nativeTurnLines } from './native-turn-transcript.mjs';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -137,7 +138,9 @@ export class ContinuityJournal {
   scan() {
     this.requireBudget();
     let text = '';
-    try { text = fs.readFileSync(this.path, 'utf8'); } catch { /* no outbox yet */ }
+    try { text = fs.readFileSync(this.path, 'utf8'); } catch (error) {
+      if (error.code !== 'ENOENT') throw new Error(`continuity outbox unreadable: ${error.code || 'I/O error'}`);
+    }
     const events = new Map();
     const committed = new Map();
     const failures = new Map();
@@ -367,23 +370,23 @@ export function stopNotice({ journal, status, session }) {
 }
 function defaultStore({ ruflo, db, key, value }) {
   const cwd = rufloRunDir(db);
+  const source = JSON.parse(value).source;
+  const provenance = ['assistant-detected', 'owner-correction-detected', 'agent-result'].includes(source) ? 'agent_output' : 'system_observation';
   try {
     const { executable, args } = rufloInvocation(ruflo, ['memory', 'store', '--key', key, '--value', value,
-      '--namespace', CONTINUITY_NAMESPACE, '--no-upsert', '--provenance', 'system_observation', '--path', db]);
+      '--namespace', CONTINUITY_NAMESPACE, '--no-upsert', '--require-native', '--append-only', '--provenance', provenance, '--path', db]);
     const r = spawnSync(executable, args, { cwd, encoding: 'utf8', timeout: 60_000, windowsHide: true,
-      env: { ...process.env, RUFLO_DAEMON_AUTOSTART: '0' } });
+      env: { ...process.env, RUFLO_DAEMON_AUTOSTART: '0', CLAUDE_FLOW_MEMORY_PATH: undefined } });
     return { status: Number.isInteger(r.status) ? r.status : 1, output: `${r.stderr || ''}\n${r.stdout || ''}${r.error ? `\n${r.error.message}` : ''}` };
   } finally { fs.rmSync(cwd, { recursive: true, force: true }); }
 }
 
 function defaultReadBack({ ruflo, db, key }) {
-  const fast = withProgressionReader(db, (reader) => reader.readContent(CONTINUITY_NAMESPACE, key));
-  if (fast.ok) return { key, content: fast.value, readPath: 'node:sqlite' };
   const cwd = rufloRunDir(db);
   try {
     const { executable, args } = rufloInvocation(ruflo, ['memory', 'retrieve', '--key', key, '--namespace', CONTINUITY_NAMESPACE, '--value-only', '--path', db]);
-    const r = spawnSync(executable, args, { cwd, encoding: 'utf8', timeout: 60_000, windowsHide: true, env: { ...process.env, RUFLO_DAEMON_AUTOSTART: '0' } });
-    return { key, content: r.status === 0 ? String(r.stdout || '') : null, readPath: `ruflo-cli (${fast.reason})` };
+    const r = spawnSync(executable, args, { cwd, encoding: 'utf8', timeout: 60_000, windowsHide: true, env: { ...process.env, RUFLO_DAEMON_AUTOSTART: '0', CLAUDE_FLOW_MEMORY_PATH: undefined } });
+    return { key, content: r.status === 0 ? String(r.stdout || '') : null, readPath: 'ruflo-cli' };
   } finally { fs.rmSync(cwd, { recursive: true, force: true }); }
 }
 
@@ -414,15 +417,18 @@ export function drain(journal, {
       if (now() >= deadline) break;
       const value = JSON.stringify(privateContinuityEvent(rec.event, consent.contentPathExcludes, consent.capturePath));
       if (value !== JSON.stringify(rec.event)) return { committed, failed, remaining: journal.pending().length, skipped: 'content exclusions changed; immutable continuity retained' };
-      attempts += 1; const result = store({ ruflo, db: journal.db, key: rec.key, value });
-      const back = readBack({ ruflo, db: journal.db, key: rec.key });
+      attempts += 1;
+      const prior = readBack({ ruflo, db: journal.db, key: rec.key });
+      const alreadyStored = typeof prior.content === 'string' && prior.content.trim() === value && (prior.key === undefined || prior.key === rec.key);
+      const result = alreadyStored ? { status: 0 } : store({ ruflo, db: journal.db, key: rec.key, value });
+      const back = alreadyStored ? prior : readBack({ ruflo, db: journal.db, key: rec.key });
       const content = typeof back.content === 'string' ? back.content.trim() : '';
-      if (content === value && digestCanonical(rec.event) === rec.digest && (back.key === undefined || back.key === rec.key)) {
+      if (result.status === 0 && content === value && digestCanonical(rec.event) === rec.digest && (back.key === undefined || back.key === rec.key)) {
         journal.appendRecords([{ type: 'commit', key: rec.key, digest: rec.digest, committedAt: new Date(now()).toISOString(), readPath: back.readPath,
-          alreadyStored: result.status !== 0 || content !== value, ...(attempts > 1 ? { attempts, lastError: last?.reason } : {}) }]);
+          alreadyStored, ...(attempts > 1 ? { attempts, lastError: last?.reason } : {}) }]);
         committed += 1;
         done = true;
-      } else if (content) {
+      } else if (content && (content !== value || digestCanonical(rec.event) !== rec.digest || (back.key !== undefined && back.key !== rec.key))) {
         // A DIFFERENT row holds our key: never overwritten (--no-upsert), never retried, reported.
         journal.appendRecords([{ type: 'quarantine', key: rec.key, at: new Date(now()).toISOString(), reason: 'a different stored row holds this key' }]);
         failed += 1;
@@ -466,7 +472,7 @@ export function takeLock(journal, { now = Date.now } = {}) {
 export function launchDrain({ projectRoot, spawnFn = spawn, env = process.env } = {}) {
   try {
     const child = spawnFn(process.execPath, [fileURLToPath(import.meta.url), '--drain', projectRoot], {
-      cwd: os.tmpdir(), detached: true, stdio: 'ignore', windowsHide: true, env: { ...env, RUFLO_DAEMON_AUTOSTART: '0' },
+      cwd: os.tmpdir(), detached: true, stdio: 'ignore', windowsHide: true, env: { ...env, RUFLO_DAEMON_AUTOSTART: '0', CLAUDE_FLOW_MEMORY_PATH: undefined },
     });
     child.unref?.();
     return true;
@@ -513,13 +519,13 @@ export function captureContinuityEvents({
     events.push(...collectCommits({ checkoutRoot: resolution.checkoutRoot, sinceMs, host, session, project }));
     events.push(...collectReleases({ checkoutRoot: resolution.checkoutRoot, sinceMs, host, session, project }));
   }
-  if (event === 'Stop') {
+  if (['Stop', 'SessionEnd', 'PreCompact', 'SubagentStop'].includes(event)) {
     let lines = null;
-    if (host === 'claude' && typeof payload.transcript_path === 'string' && payload.transcript_path) {
+    if (typeof payload.transcript_path === 'string' && payload.transcript_path) {
       try { lines = readTranscript(payload.transcript_path); } catch { /* unreadable transcript: git events still count */ }
     }
     const last = typeof payload.last_assistant_message === 'string' ? payload.last_assistant_message : ''; const policy = journal.captureConsent();
-    if (!policy.skipped && !(lines && turnReferencesExcludedResource(claudeTurn(lines), policy.contentPathExcludes, projectDir))) events.push(...collectTurnEvents({ lines, lastAssistantMessage: last, host, session, project, env, at: now() }));
+    if (!policy.skipped && !(lines && turnReferencesExcludedResource(claudeTurn(nativeTurnLines(lines, host)), policy.contentPathExcludes, projectDir))) events.push(...collectTurnEvents({ lines, lastAssistantMessage: last, host, session, project, env, at: now() }));
   }
   try { report.recorded = journal.record(events).length; } catch (error) { return { ...report, skipped: `outbox write failed: ${error.message}` }; }
   try { if (journal.needsCompaction()) journal.compact(); } catch { /* bounded next time */ }

package/plugin/scripts/decision-gate.mjs

@@ -162,7 +162,7 @@ const POLICY = (id, file, interpreter = 'bash') => ({ id, file, interpreter });
 const REFUSAL_POLICIES = [
   POLICY('protect-state', 'protect-brain-state.sh'),
   POLICY('hijack-ruvnet', 'hijack-ruvnet.sh'),
-  POLICY('ground-before-write', 'ground-before-write.sh'),
+  POLICY('ground-before-write', 'ground-before-write.sh'), POLICY('decision-recall', 'decision-recall-gate.mjs', 'node'), // ADR-106
   // adr-currency-gate fires on the EDIT, where the pre-push gate fires on the push. Same rule, same
   // machinery (it calls doc-currency.mjs, never a second copy of the logic) — moved to the earliest
   // moment it has enough information. On 2026-08-13 four ADRs went stale together and were caught
@@ -181,7 +181,7 @@ const SPEECH = { id: 'unprompted-speech', file: 'unprompted-runtime.mjs', interp
 
 /** Which policies apply to which PreToolUse sub-event, mirroring the matchers they replaced. */
 const REGISTRY = {
-  'write': ['protect-state', 'hijack-ruvnet', 'ground-before-write', 'adr-currency', 'duplicate-code'],
+  'write': ['protect-state', 'hijack-ruvnet', 'ground-before-write', 'decision-recall', 'adr-currency', 'duplicate-code'],
 };
 
 export function policiesFor(event, registry = REGISTRY, all = REFUSAL_POLICIES) {

package/plugin/scripts/decision-recall-gate.mjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+/**
+ * decision-recall-gate.mjs — "read AgentDB before deciding" as a FACT check (ADR-105 §8, ADR-106).
+ *
+ * A POLICY OF decision-gate.mjs, NOT A HOOK: exit 0 allow, exit 2 + stderr refuse; composed by the
+ * one PreToolUse refuser (ADR-067) on both hosts, so it adds no registration.
+ *
+ * WHEN IT LOOKS: a write that CREATES an ADR file (Write to a path that does not exist yet, or an
+ * apply_patch `*** Add File:`), or an Edit/MultiEdit that changes an ADR's status line. Ordinary ADR
+ * edits (wording, review stamps) are never checked.
+ *
+ * THE FACT: a `decision-record.mjs --consult` receipt for this project younger than two hours. The
+ * receipt proves the consult RAN; it does not require history to have been available — an AgentDB
+ * outage must not wedge decisions, so an `unavailable` receipt allows and says history was unknown.
+ *
+ * AT MOST ONE REFUSAL PER PATH PER SESSION (the duplicate-gate shape): the retry is allowed and
+ * recorded. Only in an adopted project (canonical `.swarm/memory.db` exists). Opt-outs win
+ * (ADR-105 §7): RUVNET_DECISION_RECALL_GATE=off, RUVNET_AGENTDB_FIRST=off, the brain-off sentinel.
+ * Fails open on its own errors.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { resolveProjectStore } from './project-store-resolver.mjs';
+import { isAdrPath, freshConsultReceipt, brainHomeOf } from './decision-record.mjs';
+
+const ALLOW = 0;
+const REFUSE = 2;
+const STATUS_LINE = /^\s*(?:status:\s*\S.*|\*\*Status\*\*\s*:.*)$/im;
+/** The document's status line, ignoring fenced code (a YAML example is not the ADR's status). */
+const STATUS_LINES = new RegExp(STATUS_LINE.source, 'gim');
+/** Every status line of the document (frontmatter AND body), ignoring fenced code. */
+export const statusOf = (text) => [...String(text || '').replace(/^(```|~~~)[^\n]*\n[\s\S]*?^\1[^\n]*$/gm, '').matchAll(STATUS_LINES)]
+  .map((m) => m[0].trim()).join('\n');
+
+function readText(file) { try { return fs.readFileSync(file, 'utf8'); } catch { return null; } }
+
+/**
+ * Which ADR decision, if any, this tool call makes. A status change is judged on the WHOLE document:
+ * the status of the file now versus the status after this edit is applied, so a whole-file Write over
+ * an existing ADR is seen (review finding 5) and a `status:` line inside a code fence is not (finding 6).
+ */
+export function adrDecisionIn(payload, { read = readText } = {}) {
+  const tool = String(payload?.tool_name || '');
+  const input = payload?.tool_input || {};
+  const cwd = typeof payload?.cwd === 'string' ? payload.cwd : process.cwd();
+  const abs = (p) => (path.isAbsolute(p) ? p : path.resolve(cwd, p));
+  if (['Write', 'Edit', 'MultiEdit'].includes(tool) && isAdrPath(input.file_path)) {
+    const before = read(abs(input.file_path));
+    if (before === null) return tool === 'Write' ? { path: input.file_path, kind: 'new ADR' } : null;
+    let after = before;
+    if (tool === 'Write') after = String(input.content ?? '');
+    else {
+      const edits = tool === 'Edit' ? [input] : (Array.isArray(input.edits) ? input.edits : []);
+      for (const e of edits) {
+        const from = String(e.old_string ?? ''); const to = String(e.new_string ?? '');
+        if (!from) continue;
+        after = e.replace_all ? after.split(from).join(to) : after.replace(from, () => to);
+      }
+    }
+    return statusOf(after) !== statusOf(before) ? { path: input.file_path, kind: 'ADR status change' } : null;
+  }
+  if (tool === 'apply_patch') {
+    const text = typeof input === 'string' ? input : JSON.stringify(input);
+    const patch = typeof input === 'string' ? input : String(input.input ?? input.patch ?? input.command ?? text);
+    const added = [...patch.matchAll(/\*\*\* Add File: ([^\n\\"]+)/g)].map((m) => m[1].trim()).find(isAdrPath);
+    if (added) return { path: added, kind: 'new ADR' };
+    // An Update File hunk on an ADR: compare the status lines it removes with the ones it adds.
+    for (const section of patch.split(/^\*\*\* (?=Update File: )/m).slice(1)) {
+      const file = /^Update File: ([^\n]+)/.exec(section)?.[1]?.trim();
+      if (!isAdrPath(file)) continue;
+      const lines = section.split('\n');
+      const side = (sign) => lines.filter((l) => l.startsWith(sign) && !l.startsWith(sign.repeat(3))).map((l) => l.slice(1)).join('\n');
+      if (statusOf(side('+')) !== statusOf(side('-'))) return { path: file, kind: 'ADR status change' };
+    }
+  }
+  return null;
+}
+
+function brainOff(env) {
+  const dir = env.RUVNET_BRAIN_STATE_DIR || path.join(env.HOME || os.homedir(), '.config', 'ruvnet-brain');
+  try { fs.statSync(path.join(dir, 'brain-off')); return true; } catch (e) { return !(e && (e.code === 'ENOENT' || e.code === 'ENOTDIR')); }
+}
+
+const ackFile = (brainHome) => path.join(brainHome, 'decision-recall-acks.json');
+function readAcks(file) { try { const o = JSON.parse(fs.readFileSync(file, 'utf8')); return o && typeof o === 'object' ? o : {}; } catch { return {}; } }
+
+/** The verdict. Returns { code, stderr?, stdout? }. */
+export function evaluate(payload, { env = process.env, now = Date.now() } = {}) {
+  if (['off'].includes(String(env.RUVNET_DECISION_RECALL_GATE || '').toLowerCase())
+    || String(env.RUVNET_AGENTDB_FIRST || '').toLowerCase() === 'off' || brainOff(env)) return { code: ALLOW };
+  const decision = adrDecisionIn(payload);
+  if (!decision) return { code: ALLOW };
+  let resolution;
+  try { resolution = resolveProjectStore({ projectDir: payload.cwd || process.cwd(), gitTimeoutMs: 400 }); } catch { return { code: ALLOW }; }
+  try { if (!fs.statSync(resolution.canonicalAgentDbPath).isFile()) return { code: ALLOW }; } catch { return { code: ALLOW }; }
+  const brainHome = brainHomeOf(env);
+  const receipt = freshConsultReceipt({ projectRoot: resolution.projectRoot, brainHome, now });
+  if (receipt) {
+    return /^ok-/.test(receipt.outcome) ? { code: ALLOW }
+      : { code: ALLOW, stdout: `AgentDB history was ${receipt.outcome} when this decision was consulted (${receipt.at}); state in the ${decision.kind} that prior decisions are UNKNOWN.` };
+  }
+  const session = String(payload.session_id || 'no-session');
+  const key = crypto.createHash('sha256').update(`${session}\u0000${resolution.projectRoot}\u0000${decision.path}`).digest('hex').slice(0, 32);
+  const file = ackFile(brainHome);
+  const acks = readAcks(file);
+  if (acks[key]) {
+    acks[key].retriedAt = new Date(now).toISOString();
+    try { fs.writeFileSync(file, JSON.stringify(acks)); } catch { /* the ledger never blocks a write */ }
+    return { code: ALLOW, stdout: `This ${decision.kind} was written without an AgentDB consult (retry after one refusal). Record it afterwards with decision-record.mjs --record.` };
+  }
+  // Keep the ledger bounded: drop acknowledgements older than a week.
+  for (const [k, v] of Object.entries(acks)) if (now - Date.parse(v?.at) > 7 * 86_400_000) delete acks[k];
+  acks[key] = { at: new Date(now).toISOString(), kind: decision.kind };
+  try { fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, JSON.stringify(acks), { mode: 0o600 }); } catch { return { code: ALLOW }; }
+  const script = path.join(path.dirname(fileURLToPath(import.meta.url)), 'decision-record.mjs');
+  return { code: REFUSE, stderr: [
+    `⛔ BLOCKED (once) — ${decision.kind} ${decision.path}: run decision-record.mjs --consult "<topic>" first (AgentDB decisions unread).`,
+    'Consult first (exact curated records, then ranked, one deadline; failure is reported, never empty):',
+    `  node ${JSON.stringify(script)} --consult "<the decision topic>"`,
+    'Then write the ADR, and record the decision after it:',
+    `  node ${JSON.stringify(script)} --record --what "…" --why "…" --shape "…" --evidence adr:${decision.path}`,
+    'This path is refused at most once per session; retrying is allowed and recorded. RUVNET_DECISION_RECALL_GATE=off disables it.',
+  ].join('\n') };
+}
+
+function isMain() {
+  try { return Boolean(process.argv[1]) && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return false; }
+}
+if (isMain()) {
+  let verdict = { code: ALLOW };
+  try {
+    const raw = fs.readFileSync(0, 'utf8');
+    verdict = evaluate(JSON.parse(raw || '{}'));
+  } catch { verdict = { code: ALLOW }; }
+  if (verdict.stdout) process.stdout.write(verdict.stdout);
+  if (verdict.stderr) process.stderr.write(`${verdict.stderr}\n`);
+  process.exit(verdict.code);
+}