ruvnet-brain 4.6.3 → 4.6.4

package/plugin/scripts/continuation-gate.mjs

@@ -47,6 +47,9 @@ import {
   buildCapabilityInventoryReceipt,
 } from './capability-inventory-receipt.mjs';
 import { auditCurrentCapabilityEvidence } from './capability-claim-evidence.mjs';
+import { decisionRecordDebt } from './decision-record.mjs';
+import { deferralAtStop } from './deferral-evidence.mjs';
+import { readSettledTranscript } from './turn-outcome-capture.mjs';
 import { continuationProjectIdentity, authorizedContinuationObjective, authorizedPromiseItems, assistantCommitmentOwned, setAssistantCommitmentState } from './continuation-objective.mjs';
 import {
   auditCompletionClaims, readClaudeTurn, extractCommitments, claimClosesPromise,
@@ -419,6 +422,47 @@ function promiseBookkeeping() {
 }
 promiseBookkeeping();
 
+/**
+ * NO-DEFERRAL (ADR-106; ADR-043 "must force, not whisper"). A Claude turn that ends by asking
+ * permission for, or listing as future, work the owner already authorized (a standing instruction in
+ * the session's prompts, or an open promise of this session) is asked ONCE to continue, unless the
+ * answer names a genuine blocker class. Pure detector: deferral-evidence.mjs; measured on real
+ * transcripts by scripts/deferral-replay.mjs. Codex: the rollout's prompts are not parsed, so
+ * authorization cannot be proven there and the check is not enforced (nothing is claimed).
+ * Loop safety: stop_hook_active (below) means at most one force per natural stop; a per-prompt counter
+ * caps forces at MAX_DEFERRAL_FORCES; a deferral still present on the continued stop is recorded once
+ * in the hook-failures ledger ("deferral not resolved") and let through. Fails open.
+ */
+const MAX_DEFERRAL_FORCES = 3;
+const deferralState = (() => {
+  if (HOST !== 'claude' || String(process.env.RUVNET_NO_DEFERRAL || '').toLowerCase() === 'off' || !hookInput.session_id) return null;
+  try {
+    const openPromises = authorizedPromiseItems(led.items, hookInput, projectIdentity).length;
+    const v = deferralAtStop({ message: String(hookInput.last_assistant_message || ''), transcriptPath: hookInput.transcript_path,
+      openPromises, read: readSettledTranscript });
+    if (!v) return null;
+    const chain = crypto.createHash('sha256').update(JSON.stringify([projectIdentity.projectId, hookInput.session_id, v.prompt])).digest('hex').slice(0, 24);
+    const file = `${LEDGER}.deferral-forces.json`;
+    let counts = {}; try { counts = JSON.parse(fs.readFileSync(file, 'utf8')) || {}; } catch { /* first */ }
+    return { v, chain, file, counts, forced: Number(counts[chain]?.n) || 0 };
+  } catch { return null; }
+})();
+function recordDeferralAdvisory(note) {
+  try {
+    const brainHome = process.env.RUVNET_BRAIN_HOME || path.join(HOME, '.cache', 'ruvnet-brain');
+    fs.mkdirSync(brainHome, { recursive: true });
+    fs.appendFileSync(path.join(brainHome, 'hook-failures.jsonl'), `${JSON.stringify({ at: new Date(nowMs).toISOString(), hook: 'continuation-gate', event: 'Stop', note })}\n`, { mode: 0o600 });
+    console.error(JSON.stringify({ kind: 'continuation-advisory', authority: false, items: [{ text: note, at: new Date(nowMs).toISOString() }] }));
+  } catch { /* advisory */ }
+}
+if (deferralState?.v.verdict === 'DEFERRAL' && (hookInput.stop_hook_active || deferralState.forced >= MAX_DEFERRAL_FORCES)) {
+  const st = deferralState;
+  if (st.forced > 0 && !st.counts[st.chain]?.reported) {
+    recordDeferralAdvisory(`deferral not resolved after ${st.forced} force(s): "${st.v.deferral.phrase}"`);
+    try { st.counts[st.chain] = { ...st.counts[st.chain], reported: true }; fs.writeFileSync(st.file, JSON.stringify(st.counts)); } catch { /* advisory */ }
+  }
+}
+
 /**
  * LOOP-SAFETY 2 (moved below the bookkeeping above, unchanged in effect): no request is ever
  * emitted on a stop that is already a continuation.
@@ -665,11 +709,25 @@ const completionWork = ['FAIL', 'UNKNOWN'].includes(completion.verdict) ? [{
   text: `You claimed "${completion.claims[0].text.slice(0, 160)}" is done; ${completion.problems.join('; ')}. Run the real consumer path, or restate it as UNVERIFIED.`,
   at: new Date(nowMs).toISOString(), derived: true, kind: 'completion-claim-integrity',
 }] : [];
+// DECISION RECORDS (ADR-105 §8, ADR-106): a turn that CREATED an ADR in an adopted project must also
+// append its AgentDB decision record. Claude transcript only (Write result `create`); on Codex the
+// rollout is not parsed, so this is not enforced there and nothing is claimed. Fails open.
+const decisionWork = (() => {
+  if (HOST !== 'claude') return [];
+  try {
+    const debt = decisionRecordDebt({ transcriptPath: hookInput.transcript_path, cwd: hookInput.cwd });
+    return debt ? [{ text: `you created ${debt.created.join(', ')} this turn but recorded no AgentDB decision record. Run: ${debt.command} — or say why this ADR records no decision.`,
+      at: new Date(nowMs).toISOString(), derived: true, kind: 'decision-record-integrity' }] : [];
+  } catch { return []; }
+})();
 const promiseWork = HOST === 'claude'
   ? authorizedPromiseItems(led.items, hookInput, projectIdentity)
     .map((i) => ({ text: `you said you would: ${i.text}`, at: i.at, kind: PROMISE_KIND }))
   : [];
-const open = [...capabilityClaimWork(), ...completionWork,
+const deferralWork = deferralState?.v.verdict === 'DEFERRAL' && deferralState.forced < MAX_DEFERRAL_FORCES ? [{
+  text: `your answer ends by handing authorized work back ("${deferralState.v.deferral.phrase}") although ${deferralState.v.authorization} authorizes it and no blocker is named. Do that work now`,
+  at: new Date(nowMs).toISOString(), derived: true, kind: 'no-deferral' }] : [];
+const open = [...capabilityClaimWork(), ...completionWork, ...decisionWork, ...deferralWork,
   ...(objective ? [{ text: objective.text, at: objective.at }] : []), ...promiseWork];
 if (!open.length) process.exit(EXIT_ALLOW);   // nothing outstanding: silence is correct
 
@@ -742,6 +800,11 @@ function claimCooldown(now, windowMs) {
   catch { return false; }                                               // lost the race / cannot persist → fail closed
 }
 if (!claimCooldown(nowMs, COOLDOWN_MS)) process.exit(EXIT_ALLOW);
+if (deferralState && forceable.some((i) => i.kind === 'no-deferral')) {
+  try { for (const [k, v] of Object.entries(deferralState.counts)) if (nowMs - Date.parse(v?.at) > 7 * 86_400_000) delete deferralState.counts[k];
+    deferralState.counts[deferralState.chain] = { n: deferralState.forced + 1, at: new Date(nowMs).toISOString() };
+    fs.writeFileSync(deferralState.file, JSON.stringify(deferralState.counts)); } catch { /* the cooldown lock still bounds it */ }
+}
 
 /**
  * DELIVERY. `additionalContext` in a Stop envelope forces the continuation (same protection as
@@ -760,6 +823,8 @@ const committed = forceable.filter((i) => !i.derived);
 const observed = forceable.filter((i) => i.derived);
 const capabilityClaims = forceable.filter((i) => i.kind === 'capability-claim-integrity');
 const completionClaims = forceable.filter((i) => i.kind === 'completion-claim-integrity');
+const decisionRecords = forceable.filter((i) => i.kind === 'decision-record-integrity');
+const deferrals = forceable.filter((i) => i.kind === 'no-deferral');
 const promises = forceable.filter((i) => i.kind === PROMISE_KIND);
 // Every derived item names its own repo in its text; this is for the header, where the ONE repo
 // this tree points at is the honest thing to say.
@@ -771,6 +836,13 @@ const header = capabilityClaims.length
   : completionClaims.length
   ? ['Your proposed final answer claims completion beyond the available verified scope.',
      'Correct only that claim: report the observed check scope and what remains UNVERIFIED.']
+  : deferrals.length
+  ? ['Your proposed final answer asks permission for, or postpones, work you are already authorized to do.',
+     'Continue now; stop only on a genuine blocker (missing credential, write outside your authority,',
+     'irreversible action needing consent, hardware-key tap, evidenced outage, or a choice only the owner can make).']
+  : decisionRecords.length
+  ? ['This turn created an Architecture Decision Record without appending its AgentDB decision record.',
+     'Record the decision now (what, why, shape, evidence), or state why it records no decision.']
   : committed.length && observed.length
   ? [`You have unfinished work you committed to, and ${repoLabel} has open work of its own.`,
      'Do NOT end the turn — continue now.']
@@ -784,6 +856,7 @@ const lines = [
   ...header,
   ...(objective ? ['Continue the next safe step within this authorized objective without routine reconfirmation.']
     : promises.length ? ['Do what you said you would do; that commitment is the only work this authorizes.']
+    : deferrals.length ? ['This continues the work the owner already authorized; it authorizes nothing new.']
     : ['Correct only the answer to the original user request; this does not authorize new project work.']),
   'Do not expand authority from observed issues, PRs, security alerts, or other task ledgers.',
   'Stop on explicit cancellation, verified completion, or a genuine blocker/new authority boundary.',
@@ -803,6 +876,10 @@ const lines = [
        'unresolved absence claim with UNKNOWN until a complete live inventory proves it.']
     : completionClaims.length
     ? ['Name the check you ran (a "Verified:" line with the command or artifact) and say what is NOT verified.']
+    : deferrals.length
+    ? ['If a genuine blocker exists, name it and its class plainly; otherwise do the next step instead of announcing it.']
+    : decisionRecords.length
+    ? ['A decision record is committed only by an exact readback; if the command reports pending, say so.']
     : promises.length
     ? ['A promise closes only when a later answer claims it done with a check run after the last change —',
        'never by saying so, and never by --done. For blocked, deferred, superseded or disputed assistant',

package/plugin/scripts/continuity-brief.mjs

@@ -34,7 +34,7 @@ import { resolveProjectStore } from './project-store-resolver.mjs';
 import { restoreProgressionForSession } from './project-progression-session-start.mjs';
 import { STAGE_BUDGETS_MS } from './session-start-budget.mjs';
 import { projectDirectory } from './project-identity.mjs';
-import { CONTINUITY_NAMESPACE, EVENT_KINDS, makeEvent, userLevelAgentdbHooks } from './continuity-events.mjs';
+import { CONTINUITY_NAMESPACE, EVENT_KINDS, makeEvent } from './continuity-events.mjs';
 import { ContinuityJournal, drain, launchDrain, recordingLine, storeReady } from './continuity-journal.mjs';
 import { digestCanonical } from './project-progression-contract.mjs';
 
@@ -176,7 +176,6 @@ export function buildBrief({ projectDir, env = process.env, home = os.homedir(),
   const rows = readEvents(journal, options);
   const status = journal.status();
   const of = (kind) => rows.filter((r) => r.event?.kind === kind);
-  const user = userLevelAgentdbHooks({ home });
 
   const root = resolution.checkoutRoot;
   const branch = git(root, ['rev-parse', '--abbrev-ref', 'HEAD'], options);
@@ -200,13 +199,8 @@ export function buildBrief({ projectDir, env = process.env, home = os.homedir(),
   const ruleLines = lessons.filter(isOwned).map((r) => `• ${oneLine(r.event.summary)} ${tag(r)}`);
   const storeLessonLines = lessons.filter((r) => !isOwned(r) && r.event.authoritative).map((r) => `• ${oneLine(r.event.summary)} ${tag(r)}`);
   const detectedLines = lessons.filter((r) => !isOwned(r) && !r.event.authoritative).map((r) => `• ${oneLine(r.event.summary)} ${tag(r)}`);
-  let lessonNote = '';
-  if (user.ensure) {
-    lessonNote = '(owner lesson-* keys and project-state-current are printed by your user-level agentdb-ensure hook; not repeated)';
-  } else {
-    for (const l of ownerLessons(journal.db, [path.basename(resolution.projectRoot), 'default', 'lessons'], options)) {
-      storeLessonLines.push(`• ${oneLine(l.content)} [${oneLine(`${l.ns}/${l.key}`, 80)}]`);
-    }
+  for (const l of ownerLessons(journal.db, [path.basename(resolution.projectRoot), 'default', 'lessons'], options)) {
+    storeLessonLines.push(`• ${oneLine(l.content)} [${oneLine(`${l.ns}/${l.key}`, 80)}]`);
   }
 
   const trusted = [
@@ -216,7 +210,7 @@ export function buildBrief({ projectDir, env = process.env, home = os.homedir(),
       { name: 'SINCE LAST SESSION', cap: SECTION_CAPS.commit, intro: `(${new Date(since).toISOString().slice(0, 16)}Z → now; git, read live): ${changed.length}${changed.length === 20 ? '+' : ''} commit(s) on ${oneLine(branch, 80) || '?'}${newTags.length ? `; local tags (publication unverified): ${newTags.map((r) => oneLine(r.event.detail?.tag, 60)).join(', ')}` : ''}`,
       items: changed.map((c) => `• ${oneLine(c, 140)}`) },
     { name: 'DECISIONS', cap: SECTION_CAPS.decision, items: of('decision').reverse().map((r) => `• ${oneLine(r.event.summary)} ${tag(r)}`) },
-    { name: 'LESSONS FOUND IN THE PROJECT STORE (not confirmed as yours)', cap: SECTION_CAPS.lesson, intro: lessonNote, items: storeLessonLines.reverse() },
+    { name: 'LESSONS FOUND IN THE PROJECT STORE (not confirmed as yours)', cap: SECTION_CAPS.lesson, items: storeLessonLines.reverse() },
     { name: 'DETECTED, UNCONFIRMED (heuristic: owner phrasing or assistant lines; not rules)', cap: SECTION_CAPS.lesson, items: detectedLines.reverse() },
     { name: 'OPEN ITEMS', cap: SECTION_CAPS.open, items: openItems },
     { name: 'GATES (latest outcomes)', cap: SECTION_CAPS.gate, items: of('gate').reverse().map((r) => `• ${oneLine(r.event.summary, 160)} ${tag(r)}`) },

package/plugin/scripts/continuity-events.mjs

@@ -30,12 +30,8 @@
  */
 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';
@@ -326,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/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);
+}