ruvnet-brain 4.6.3 → 4.7.0

package/plugin/scripts/decision-gate.mjs

@@ -162,7 +162,8 @@ 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('substitution-wall', 'substitution-wall.mjs', 'node'), // owner ruling 2026-10-12: only CALL rUv's memory tools; refuses a rebuilt transport (outbox/queue/journal/replay), in this repo only
+  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 +182,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', 'substitution-wall', 'ground-before-write', 'decision-recall', 'adr-currency', 'duplicate-code'],
 };
 
 export function policiesFor(event, registry = REGISTRY, all = REFUSAL_POLICIES) {
@@ -287,7 +288,6 @@ function payloadInput(payload) { return parsed(payload).tool_input || {}; }
  * `Cannot access 'speechEventFor' before initialization` on this gate's first live refusal.
  */
 function speechEventFor(event) { return event === 'bash' ? 'PreToolUse-bash' : 'PreToolUse-write'; }
-
 // ── Runtime ──────────────────────────────────────────────────────────────────────────────────────
 if (isMain()) {
   const started = Date.now();

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);
+}

package/plugin/scripts/decision-record.mjs

@@ -0,0 +1,324 @@
+#!/usr/bin/env node
+/**
+ * decision-record.mjs — ADR-105 §8 as code: AgentDB is CONSULTED before a decision and the decision
+ * is RECORDED after it, in the one canonical store, through the one door (ADR-105 §1–§3).
+ *
+ *   node decision-record.mjs --consult "<topic>"            consequential recall + persisted receipt
+ *   node decision-record.mjs --record --what W --why Y --shape S --evidence kind:ref [...]
+ *                            [--supersedes <key>]... [--status ratified|detected-unconfirmed]
+ *
+ * Two hooks consume the facts this file produces (ADR-106): decision-gate's `decision-recall` policy
+ * reads the consult receipt before a new ADR or an ADR status change; continuation-gate reads the
+ * transcript audit below at Stop. Neither hook writes memory.
+ *
+ * Store contract (ADR-105 §3, `ruflo memory store --help` read 2026-10-11): every write is
+ * `--no-upsert --require-native --append-only --path <abs>` from a private scratch cwd with no
+ * CLAUDE_FLOW_MEMORY_PATH; a row is committed only when an exact-key readback returns the same
+ * bytes; any other refusal is LOUD — a hook-failures row plus the printed reason — and is never reported as
+ * done. Nothing is kept on disk for a later replay (owner ruling 2026-10-12: no private outbox).
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { redactText } from './continuity-events.mjs';
+import { maskExcludedPaths } from './turn-capture-privacy.mjs';
+import { resolveTurnDb, readSettledTranscript } from './turn-outcome-capture.mjs';
+import { resolveProjectStore } from './project-store-resolver.mjs';
+import { resolveRuflo, rufloInvocation } from './ruflo-bin.mjs';
+import { rufloRunDir } from './ruflo-bin.mjs';
+import { currentTurnRecords } from './completion-claim-evidence.mjs';
+import { recordHookFailure } from './hook-failures.mjs';
+
+export const DECISION_SCHEMA = 'ruvnet-brain.decision-record';
+export const STATUSES = Object.freeze(['ratified', 'detected-unconfirmed']);
+export const EVIDENCE_KINDS = Object.freeze(['path', 'commit', 'receipt', 'adr', 'url']);
+export const BOUNDS = Object.freeze({ what: 400, why: 800, shape: 1200, evidence: 8, evidenceRef: 200, supersedes: 8, value: 4096 });
+export const CONSULT_MAX_AGE_MS = 2 * 3600_000;
+const KEY_RE = /^decision-[a-z0-9-]{1,48}-\d{8}T\d{9}Z$/;
+const SCRIPT = fileURLToPath(import.meta.url);
+
+/** An ADR document path (README/index files are not decisions). */
+export function isAdrPath(file) {
+  const p = String(file || '').replace(/\\/g, '/');
+  if (!/\.md$/i.test(p) || /(^|\/)(README|index)\.md$/i.test(p)) return false;
+  return /(^|\/)adrs?\/[^/]+\.md$/i.test(p) || /(^|\/)ADR-[^/]+\.md$/i.test(p);
+}
+
+const bound = (s, n) => String(s ?? '').slice(0, n);
+export const brainHomeOf = (env = process.env) => env.RUVNET_BRAIN_HOME || path.join(env.HOME || os.homedir(), '.cache', 'ruvnet-brain');
+
+/** `decision-<kebab slug ≤48>-<YYYYMMDDTHHMMSSmmmZ>` (ADR-105 §8). */
+export function decisionKey(what, at) {
+  const slug = String(what || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48).replace(/-+$/, '') || 'decision';
+  const stamp = new Date(at).toISOString().replace(/[-:.]/g, '');
+  return `decision-${slug}-${stamp}`;
+}
+
+/** Structural validation of a stored record. Returns a list of problems (empty = valid). */
+export function validateDecisionRecord(r) {
+  const errors = [];
+  if (!r || typeof r !== 'object' || Array.isArray(r)) return ['record must be an object'];
+  if (r.schema !== DECISION_SCHEMA || r.schemaVersion !== 1) errors.push('schema/schemaVersion');
+  for (const f of ['project', 'projectIdentity', 'at', 'host']) if (typeof r[f] !== 'string' || !r[f]) errors.push(`${f} required`);
+  if (r.session !== null && typeof r.session !== 'string') errors.push('session must be a string or null');
+  if (!['claude', 'codex', 'cli'].includes(r.host)) errors.push('host must be claude, codex or cli');
+  if (!STATUSES.includes(r.status)) errors.push(`status must be one of ${STATUSES.join(', ')}`);
+  if (typeof r.what !== 'string' || !r.what.trim()) errors.push('what required');
+  for (const f of ['what', 'why', 'shape']) if (r[f] !== undefined && (typeof r[f] !== 'string' || r[f].length > BOUNDS[f])) errors.push(`${f} exceeds ${BOUNDS[f]} chars`);
+  const evidence = Array.isArray(r.evidence) ? r.evidence : [];
+  if (r.evidence !== undefined && !Array.isArray(r.evidence)) errors.push('evidence must be an array');
+  if (evidence.length > BOUNDS.evidence) errors.push(`evidence exceeds ${BOUNDS.evidence} items`);
+  for (const e of evidence) {
+    if (!e || !EVIDENCE_KINDS.includes(e.kind) || typeof e.ref !== 'string' || !e.ref || e.ref.length > BOUNDS.evidenceRef) errors.push('evidence item must be {kind: path|commit|receipt|adr|url, ref ≤200}');
+  }
+  if (r.status === 'ratified') {
+    if (typeof r.why !== 'string' || !r.why.trim()) errors.push('why required for a ratified decision');
+    if (typeof r.shape !== 'string' || !r.shape.trim()) errors.push('shape required for a ratified decision');
+    if (!evidence.length) errors.push('at least one evidence item required for a ratified decision');
+  }
+  const sup = r.supersedes ?? [];
+  if (!Array.isArray(sup) || sup.length > BOUNDS.supersedes || sup.some((k) => !KEY_RE.test(k))) errors.push('supersedes must be ≤8 exact decision keys');
+  // A detected record is evidence, never authority: it may not retire a decision (append-only, no undo).
+  if (Array.isArray(sup) && sup.length && r.status !== 'ratified') errors.push('only a ratified decision may supersede');
+  return errors;
+}
+
+/** Redact (shared scanner), mask excluded paths, then bound — in that order (ADR-105 §8). */
+export function buildDecisionRecord(input, { projectRoot, projectIdentity, host = 'cli', session = null, now = Date.now(), exclusions = [] }) {
+  const clean = (s, n) => bound(maskExcludedPaths(redactText(String(s ?? '').trim()), exclusions, projectRoot), n);
+  const record = {
+    schema: DECISION_SCHEMA, schemaVersion: 1, project: projectRoot, projectIdentity,
+    at: new Date(now).toISOString(), host, session,
+    status: input.status || 'ratified',
+    what: clean(input.what, BOUNDS.what),
+    ...(input.why ? { why: clean(input.why, BOUNDS.why) } : {}),
+    ...(input.shape ? { shape: clean(input.shape, BOUNDS.shape) } : {}),
+    evidence: (input.evidence || []).slice(0, BOUNDS.evidence).map((e) => ({ kind: e.kind, ref: clean(e.ref, BOUNDS.evidenceRef) })),
+    supersedes: [...new Set(input.supersedes || [])],
+  };
+  const errors = validateDecisionRecord(record);
+  const value = JSON.stringify(record);
+  if (Buffer.byteLength(value) > BOUNDS.value) errors.push(`record exceeds ${BOUNDS.value} bytes`);
+  return { record, key: decisionKey(record.what, now), value, errors };
+}
+
+/**
+ * Supersession is a link on the NEWER record (an append-only store cannot edit the old row).
+ * Only a valid ratified record supersedes; a detected one is evidence, never authority.
+ */
+export function supersededKeys(records) {
+  const out = new Set();
+  for (const r of records) {
+    if (!r || r.schema !== DECISION_SCHEMA || r.status !== 'ratified' || validateDecisionRecord(r).length) continue;
+    for (const k of r.supersedes || []) out.add(k);
+  }
+  return out;
+}
+
+/**
+ * Supersession tombstones (review finding 1). A newer record's `supersedes` is only visible to recall
+ * when that newer record is itself read, so a superseder that ranking or the deadline left out let the
+ * old decision be served as live. Each superseded key therefore also gets an append-only tombstone row
+ * `supersession-<old key>` in the same namespace; recall sees it in the key enumeration it already does,
+ * with no extra read. The prefix never matches recall's `^decision[-_]` decision-key test.
+ */
+export const SUPERSESSION_SCHEMA = 'ruvnet-brain.decision-supersession';
+export const TOMBSTONE_PREFIX = 'supersession-';
+export const tombstoneKey = (oldKey) => `${TOMBSTONE_PREFIX}${oldKey}`;
+export function tombstonedKeys(keys) {
+  return new Set((keys || []).filter((k) => typeof k === 'string' && k.startsWith(`${TOMBSTONE_PREFIX}decision-`))
+    .map((k) => k.slice(TOMBSTONE_PREFIX.length)));
+}
+
+function runRuflo(ruflo, db, args, { spawn = spawnSync } = {}) {
+  const cwd = rufloRunDir(db);
+  try {
+    const { executable, args: argv } = rufloInvocation(ruflo, args);
+    const r = spawn(executable, argv, { cwd, encoding: 'utf8', timeout: 60_000, windowsHide: true,
+      env: { ...process.env, RUFLO_DAEMON_AUTOSTART: '0', CLAUDE_FLOW_MEMORY_PATH: undefined } });
+    return { status: Number.isInteger(r.status) ? r.status : 1, stdout: String(r.stdout || ''), output: `${r.stderr || ''}\n${r.stdout || ''}${r.error ? `\n${r.error.message}` : ''}` };
+  } finally { fs.rmSync(cwd, { recursive: true, force: true }); }
+}
+
+export function defaultStore({ ruflo, db, namespace, key, value }) {
+  return runRuflo(ruflo, db, ['memory', 'store', '--key', key, '--value', value, '--namespace', namespace,
+    '--no-upsert', '--require-native', '--append-only', '--provenance', 'agent_output', '--path', db]);
+}
+export function defaultReadBack({ ruflo, db, namespace, key }) {
+  const r = runRuflo(ruflo, db, ['memory', 'retrieve', '--key', key, '--namespace', namespace, '--value-only', '--path', db]);
+  return { content: r.status === 0 ? r.stdout.trim() : null };
+}
+
+/**
+ * The §3 door. committed | already-stored | quarantined | refused — never "committed" without an
+ * exact readback of the same bytes, and a refusal is never treated as a duplicate.
+ */
+export function storeDecision({ ruflo, db, namespace, key, value, store = defaultStore, readBack = defaultReadBack }) {
+  const prior = readBack({ ruflo, db, namespace, key });
+  if (typeof prior.content === 'string' && prior.content === value) return { state: 'already-stored', key };
+  if (typeof prior.content === 'string' && prior.content && prior.content !== value) return { state: 'quarantined', key, reason: 'a different stored row holds this key' };
+  const result = store({ ruflo, db, namespace, key, value });
+  const back = readBack({ ruflo, db, namespace, key });
+  if (result.status === 0 && back.content === value) return { state: 'committed', key };
+  if (typeof back.content === 'string' && back.content && back.content !== value) return { state: 'quarantined', key, reason: 'a different stored row holds this key' };
+  const reason = redactText(String(result.output || '').trim().split('\n').filter(Boolean).slice(-1)[0] || `store exited ${result.status}`).slice(0, 300);
+  recordHookFailure({ hook: 'decision-record', event: 'record', error: `not recorded: ${reason}`.slice(0, 160) });
+  return { state: 'refused', key, reason };
+}
+
+// ── consult receipt (read before deciding) ─────────────────────────────────────────────────────
+export const consultFile = (projectRoot, brainHome) => path.join(brainHome, 'decision-consult',
+  `${crypto.createHash('sha256').update(String(projectRoot)).digest('hex').slice(0, 24)}.json`);
+
+export function writeConsultReceipt({ projectRoot, brainHome, outcome, topic, records = [], categories = null, now = Date.now() }) {
+  const file = consultFile(projectRoot, brainHome);
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify({ schemaVersion: 1, kind: 'decision-consult', projectRoot, at: new Date(now).toISOString(), outcome,
+    topicDigest: crypto.createHash('sha256').update(String(topic)).digest('hex'), records, categories }), { mode: 0o600 });
+  fs.renameSync(tmp, file);
+  return file;
+}
+
+/** The receipt for this project if it is younger than maxAgeMs, else null. Any outcome counts: it proves the consult ran. */
+export function freshConsultReceipt({ projectRoot, brainHome, now = Date.now(), maxAgeMs = CONSULT_MAX_AGE_MS }) {
+  try {
+    const r = JSON.parse(fs.readFileSync(consultFile(projectRoot, brainHome), 'utf8'));
+    const age = now - Date.parse(r.at);
+    return r.kind === 'decision-consult' && r.projectRoot === projectRoot && age >= 0 && age <= maxAgeMs ? r : null;
+  } catch { return null; }
+}
+
+// ── transcript audit (write after deciding) ────────────────────────────────────────────────────
+const RECORD_COMMAND = /decision-record\.mjs["']?\s[^\n|;&]*--record\b/;
+
+/**
+ * From the CURRENT turn's transcript records: ADR files this turn CREATED (Write result type
+ * `create`, measured on real Claude transcripts) and whether a successful `--record` ran after the
+ * last of them. Pure over parsed records.
+ */
+export function auditDecisionTurn(records) {
+  const results = new Map();
+  for (const o of records) {
+    const c = o?.message?.content;
+    if (!Array.isArray(c)) continue;
+    for (const r of c) if (r?.type === 'tool_result' && r.tool_use_id) results.set(r.tool_use_id, { error: r.is_error === true, use: o.toolUseResult });
+  }
+  const created = [];
+  let lastCreate = -1;
+  let recordedAt = -1;
+  let i = 0;
+  for (const o of records) {
+    const c = o?.message?.content;
+    if (o?.type !== 'assistant' || !Array.isArray(c)) continue;
+    for (const u of c) {
+      if (u?.type !== 'tool_use') continue;
+      i += 1;
+      const result = results.get(u.id);
+      if (!result || result.error) continue;
+      if (u.name === 'Write' && isAdrPath(u.input?.file_path) && result.use?.type === 'create') { created.push(u.input.file_path); lastCreate = i; }
+      if (u.name === 'Bash' && RECORD_COMMAND.test(String(u.input?.command || ''))) recordedAt = i;
+    }
+  }
+  return { created, recorded: created.length > 0 && recordedAt > lastCreate };
+}
+
+/** Stop-side debt: an ADR created this turn in an ADOPTED project with no later decision record. */
+export function decisionRecordDebt({ transcriptPath, cwd, read = readSettledTranscript, env = process.env }) {
+  if (String(env.RUVNET_DECISION_RECORD_CHECK || '').toLowerCase() === 'off' || String(env.RUVNET_AGENTDB_FIRST || '').toLowerCase() === 'off') return null;
+  if (typeof transcriptPath !== 'string' || !/\.jsonl$/i.test(transcriptPath) || !cwd) return null;
+  let audit;
+  try { audit = auditDecisionTurn(currentTurnRecords(read(transcriptPath, { maxMs: 0 })).recs); } catch { return null; }
+  if (!audit.created.length || audit.recorded) return null;
+  try { if (!fs.statSync(resolveProjectStore({ projectDir: cwd, gitTimeoutMs: 500 }).canonicalAgentDbPath).isFile()) return null; } catch { return null; }
+  return { created: audit.created, command: `node ${JSON.stringify(SCRIPT)} --record --what "…" --why "…" --shape "…" --evidence adr:${audit.created.at(-1)}` };
+}
+
+// ── CLI ─────────────────────────────────────────────────────────────────────────────────────────
+function parseArgs(argv) {
+  const o = { evidence: [], supersedes: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = () => { const v = argv[++i]; if (v === undefined) throw new Error(`${a} needs a value`); return v; };
+    if (['--consult', '--record'].includes(a)) { o.mode = a.slice(2); if (a === '--consult') o.topic = next(); }
+    else if (a === '--what') o.what = next();
+    else if (a === '--why') o.why = next();
+    else if (a === '--shape') o.shape = next();
+    else if (a === '--status') o.status = next();
+    else if (a === '--project') o.project = next();
+    else if (a === '--supersedes') o.supersedes.push(next());
+    else if (a === '--evidence') {
+      const v = next(); const at = v.indexOf(':');
+      if (at < 1) throw new Error('--evidence must be kind:ref');
+      o.evidence.push({ kind: v.slice(0, at), ref: v.slice(at + 1) });
+    } else throw new Error(`unknown argument ${a}`);
+  }
+  return o;
+}
+
+export async function main(argv = process.argv.slice(2), { env = process.env, out = process.stdout, err = process.stderr, recallFn, store, readBack } = {}) {
+  let o;
+  try { o = parseArgs(argv); } catch (e) { err.write(`decision-record: ${e.message}\n`); return 2; }
+  if (!o.mode) { err.write('decision-record: one of --consult "<topic>", --record is required\n'); return 2; }
+  const projectDir = path.resolve(o.project || process.cwd());
+  const brainHome = brainHomeOf(env);
+  let target;
+  try { target = resolveTurnDb({ projectDir, brainHome, gitTimeoutMs: 1000 }); } catch (e) { err.write(`decision-record: project store unresolved: ${redactText(e.message)}\n`); return 3; }
+  if (o.mode === 'consult') {
+    const recall = recallFn || (await import('./agentdb-recall.mjs')).recall;
+    const r = await recall({ prompt: o.topic, projectDir, env, consequential: true });
+    const projectRoot = target.projectRoot;
+    if (projectRoot) writeConsultReceipt({ projectRoot, brainHome, outcome: r.outcome || 'unavailable', topic: o.topic,
+      records: (r.receipt?.records || []).map((x) => x.key), categories: r.receipt?.categories || r.categories || null });
+    if (r.block) out.write(`${r.block}\n`);
+    const ok = /^ok-/.test(r.outcome || '');
+    out.write(`decision consult: ${r.outcome || 'unavailable'}${ok ? '' : ' — history is UNKNOWN for this decision; say so in the decision'}${r.reason ? ` (${r.reason})` : ''}\n`);
+    return ok ? 0 : 3;
+  }
+  if (target.skipped) { err.write(`decision-record: not recorded — ${target.skipped}\n`); return 3; }
+  const ruflo = resolveRuflo({ env });
+  if (!ruflo) { err.write('decision-record: not recorded — global ruflo not found\n'); return 3; }
+  try { if (!fs.statSync(target.db).isFile()) throw new Error(); } catch { err.write('decision-record: not recorded — project has no canonical store (.swarm/memory.db)\n'); return 3; }
+  const identity = resolveProjectStore({ projectDir, gitTimeoutMs: 1000 }).projectIdentity.id;
+  const built = buildDecisionRecord(o, { projectRoot: target.projectRoot, projectIdentity: identity,
+    host: env.RUVNET_HOOK_HOST === 'codex' ? 'codex' : env.CLAUDE_PLUGIN_ROOT || env.CLAUDECODE ? 'claude' : 'cli',
+    exclusions: target.contentPathExcludes || [] });
+  if (built.errors.length) { err.write(`decision-record: invalid — ${built.errors.join('; ')}\n`); return 2; }
+  const namespace = path.basename(target.projectRoot);
+  // Review finding 2: the store is append-only, so a wrong --supersedes key would hide a real decision
+  // with no undo. Every key must read back as a decision record of THIS project before anything is written.
+  for (const key of built.record.supersedes) {
+    const back = (readBack || defaultReadBack)({ ruflo, db: target.db, namespace, key });
+    let row = null; try { row = back.content ? JSON.parse(back.content) : null; } catch { /* not a record */ }
+    if (row?.schema !== DECISION_SCHEMA || row.project !== target.projectRoot) {
+      err.write(`decision-record: invalid — --supersedes ${key} is not an existing decision record of this project; nothing was written\n`);
+      return 2;
+    }
+    out.write(`decision-record: supersedes ${key} — ${String(row.what).slice(0, 120)}\n`);
+  }
+  const r = storeDecision({ ruflo, db: target.db, namespace, key: built.key, value: built.value, ...(store ? { store } : {}), ...(readBack ? { readBack } : {}) });
+  out.write(`decision-record: ${r.state} ${r.key} (namespace ${namespace})${r.reason ? ` — ${r.reason}` : ''}${r.state === 'refused' ? ` — NOT recorded (logged to hook-failures). A store that committed but did not read back may still hold it: run \`ruflo memory retrieve -k ${r.key} -n ${namespace} --path ${target.db}\` before re-running --record` : ''}\n`);
+  if (!['committed', 'already-stored'].includes(r.state)) return 3;
+  let ok = true;
+  for (const oldKey of built.record.supersedes) {
+    const value = JSON.stringify({ schema: SUPERSESSION_SCHEMA, schemaVersion: 1, project: target.projectRoot, superseded: oldKey, by: built.key, at: built.record.at });
+    let t = storeDecision({ ruflo, db: target.db, namespace, key: tombstoneKey(oldKey), value, ...(store ? { store } : {}), ...(readBack ? { readBack } : {}) });
+    if (t.state === 'quarantined') {
+      // A tombstone from an EARLIER superseder of the same decision already retires it: not a conflict.
+      let prior = null;
+      try { prior = JSON.parse((readBack || defaultReadBack)({ ruflo, db: target.db, namespace, key: t.key }).content || 'null'); } catch { /* conflict stands */ }
+      if (prior?.schema === SUPERSESSION_SCHEMA && prior.superseded === oldKey && prior.project === target.projectRoot) t = { state: 'already-stored', key: t.key };
+    }
+    out.write(`decision-record: tombstone ${t.state} ${t.key}${t.reason ? ` — ${t.reason}` : ''}\n`);
+    ok &&= ['committed', 'already-stored'].includes(t.state);
+  }
+  return ok ? 0 : 3;
+}
+
+function isMain() {
+  try { return Boolean(process.argv[1]) && fs.realpathSync(process.argv[1]) === fs.realpathSync(SCRIPT); } catch { return false; }
+}
+if (isMain()) main().then((code) => { process.exitCode = code; }, (e) => { process.stderr.write(`decision-record: ${e.message}\n`); process.exitCode = 1; });

package/plugin/scripts/deferral-evidence.mjs

@@ -0,0 +1,134 @@
+/**
+ * deferral-evidence.mjs — "do not end the turn on authorized work by asking permission" as a pure,
+ * replayable detector (ADR-106 `no-deferral`; ADR-043 "must force, not whisper").
+ *
+ * The owner's measured complaint: turns end with "Say go and I'll start", "Decisions I need from you",
+ * "Do you want me to…", "Next: …", "I'll come back when…" on work he had already authorized. The
+ * Stop gate corrects completion claims and records promises; this file supplies the third check.
+ *
+ * A turn is a DEFERRAL only when all three hold, and each is a fact read from text:
+ *   (a) the END of the final answer seeks permission or lists its own next actions as future work;
+ *   (b) authorization exists — a standing instruction in the session's prompts, or an open promise;
+ *   (c) the answer names no genuine blocker class (credential, out-of-authority write, irreversible
+ *       action needing consent, hardware-key tap, evidenced outage, or a choice only the user can make).
+ * Heuristic by construction. scripts/deferral-replay.mjs measures it on real transcripts; the
+ * measured false-positive rate is recorded in ADR-106, not assumed.
+ */
+import { strippedProse } from './completion-claim-evidence.mjs';
+import { isHarnessGenerated } from './hook-input.mjs';
+
+const TAIL_CHARS = 700;
+
+/** Permission-seeking / hand-back phrasing. Matched only in the last part of the answer. */
+const PERMISSION = [
+  /\bsay\s+(?:the\s+word|go|yes)\b/i,
+  /\b(?:do\s+you\s+)?want\s+me\s+to\b/i,
+  /\bwould\s+you\s+like\s+(?:me\s+)?to\b/i,
+  /\b(?:should|shall)\s+I\b/i,
+  /\bdo\s+you\s+want\b/i,
+  /\blet\s+me\s+know\s+(?:if|whether|when|which|how)\b/i,
+  /(?<!\b(?:no|nothing|without|any)\s+(?:further\s+)?)\b(?:decisions?|input|approval|confirmation|sign-?off|answers?|go-?ahead)\s+(?:I\s+need\s+)?(?:from|needed\s+from)\s+you\b/i,
+  /\bI\s+need\s+(?:you|your)\b/i,
+  /\bwaiting\s+(?:on|for)\s+(?:you|your)\b/i,
+  /\b(?:ready\s+when\s+you\s+are|on\s+your\s+(?:go|word|ok))\b/i,
+  /\b(?:ok|okay)\s+to\s+proceed\b|\bproceed\?/i,
+  /\b(?:green[-\s]?light|your\s+call)\b/i,
+];
+
+/** Own next actions stated as future work instead of done. */
+const FUTURE_WORK = [
+  /^(?:\s*[-*•#]+\s*|\s*\*\*)*next(?:\s+steps?)?(?:\*\*)?\s*[:—–-]\s*\S/im,
+  /\bI(?:'ll|’ll|\s+will)\s+(?:come\s+back|follow\s+up|pick\s+(?:this|it)\s+(?:back\s+)?up|resume|continue|get\s+to|start|tackle|handle|do)\b[^.\n]{0,120}\b(?:after|when|once|later|next\s+(?:session|turn|time)|tomorrow)\b/i,
+  /\b(?:remaining|still\s+to\s+do|left\s+to\s+do|todo)\s*[:—–-]\s*\S/i,
+];
+
+/** A genuine authority boundary or an answer only the user can give. Matched anywhere in the answer. */
+export const BLOCKER_CLASSES = Object.freeze({
+  credential: /\b(?:setup\s+key|authenticator|backup\s+codes?)\b|\b(?:api[\s-]?key|token|secret|credential|password|passphrase|login|sign[\s-]?in|oauth)\b[^.\n]{0,80}\b(?:missing|needed|required|absent|expired|not\s+(?:set|available|present|found)|revoked|invalid)\b|\b(?:missing|need|needs|no)\s+(?:an?\s+)?(?:api[\s-]?key|token|secret|credential|password)\b/i,
+  hardwareTap: /\b(?:hardware[\s-]?key|security[\s-]?key|yubikey|touch\s?id|passkey|2fa|otp|tap\s+(?:the|your)\s+key)\b/i,
+  outsideAuthority: /\b(?:outside\s+(?:my|the)\s+(?:stated\s+)?(?:authority|scope)|not\s+(?:authori[sz]ed|permitted|allowed)\s+to|no\s+(?:write\s+)?authority|user-level|~\/\.claude|~\/\.codex|only\s+you\s+can|I\s+can(?:'t|’t|not)\s+(?:contact|reach|send|sign|log\s+in)|npm\s+(?:publish|deprecate)|deprecat(?:e|ed|ing)\s+(?:it\s+)?on\s+npm)\b/i,
+  irreversible: /\b(?:irreversible|cannot\s+be\s+undone|can't\s+be\s+undone|destructive|data\s+loss|force[\s-]?push|drop\s+(?:the\s+)?(?:table|database)|delete\s+(?:the\s+)?(?:branch|repo|database|production)|before\s+anything\s+is\s+deleted|rm\s+-rf)\b/i,
+  outage: /\b(?:outage|is\s+down|503|502|rate[\s-]?limit(?:ed)?|unreachable|connection\s+refused|timed?\s*out\s+(?:connecting|reaching))\b/i,
+  background: /\b(?:awaiting|standing\s+by\s+for|report(?:s)?\s+back|the\s+moment\b[^.\n]{0,60}\b(?:lands|has|finishes|arrives)|once\s+[^.\n]{0,60}\b(?:lands|finishes|completes|returns|is\s+back)|waiting\s+on\s+(?!you|your)[^.\n]{0,40}\b(?:CI|v\d|run|build|agent|tests?|review|suite|checks?)|still\s+running|running\s+in\s+the\s+background|I(?:'m|’m|\s+am)\s+waiting\s+for\s+(?:both|the|it|CI|checks?|reviews?|results?)|when\s+(?:the\s+)?[^.\n]{0,60}\b(?:arrives|lands|returns|reports|finishes|passes|completes|comes\s+back|is\s+back))\b/i,
+  userAction: /\b(?:restart\s+(?:the|your)\s+(?:Mac|computer|machine)|reboot|type\s+(?:the|your)\s+password|First\s+Aid|plug\s+(?:it\s+)?in|unplug|eject)\b/i,
+  purchase: /\b(?:amazon\.com|buy|purchase|price[ds]?|\$\s?\d)\b/i,
+  ownerFact: /\b(?:show\s+me\s+where|tell\s+me\s+(?:where|which\s+file|what\s+you\s+(?:mean|meant)))\b/i,
+  ownerChoice: /\b(?:should|do\s+you\s+want)\b[^?\n]{0,200}\bor\b[^?\n]{0,200}\?|\b(?:which\s+(?:one|option)\s+(?:do\s+)?you|(?:option|choice)\s+(?:A|1)\b[^.\n]{0,200}\b(?:option|choice)\s+(?:B|2)\b|only\s+you\s+(?:know|can\s+(?:decide|choose|answer)))\b/i,
+});
+
+/** Standing authorization phrases in the owner's prompts. */
+const STANDING = /\b(?:don['’]?t\s+stop|do\s+not\s+stop|keep\s+going|never\s+stop|get\s+it\s+(?:done|shipped)|finish\s+(?:it|this|the\s+job|everything)|until\s+(?:it['’]?s\s+)?done|carry\s+(?:it|this)\s+to\s+done|i\s+didn['’]?t\s+tell\s+you\s+to\s+stop|just\s+do\s+it|go\s+ahead|you\s+are\s+authori[sz]ed|fix\s+it\s+now|do\s+it\s+all|make\s+the\s+call)\b/i;
+
+const tailOf = (message) => {
+  const prose = strippedProse(message).replace(/\n{3,}/g, '\n\n').trim();
+  return prose.slice(-TAIL_CHARS);
+};
+
+/** The answer itself says work continues, or that nothing is needed from the owner: not a hand-back. */
+const PROGRESSING = /\b(?:I(?:'m|’m|\s+am)\s+(?:now\s+)?(?:continuing|starting|moving|proceeding)|starting\s+(?:on\s+)?[^.\n]{0,60}\bnow|moving\s+(?:into|on\s+to)\s+[^.\n]{0,60}\bnow|continuing\s+without|nothing\s+(?:is\s+)?(?:waiting\s+on|needed\s+from|required\s+from)\s+you|no\s+(?:further\s+)?input\s+(?:is\s+)?needed)\b/i;
+
+/** Pure: does this final answer end by deferring? Returns the matched phrase or null. */
+export function deferralIn(message) {
+  const tail = tailOf(message);
+  if (!tail || PROGRESSING.test(tail)) return null;
+  for (const re of [...PERMISSION, ...FUTURE_WORK]) {
+    const m = re.exec(tail);
+    if (m) return { phrase: m[0].trim().slice(0, 80), kind: PERMISSION.includes(re) ? 'permission' : 'future-work' };
+  }
+  return null;
+}
+
+/** Pure: which genuine blocker classes the answer names (empty = none). */
+export function blockersIn(message) {
+  const text = strippedProse(message);
+  return Object.entries(BLOCKER_CLASSES).filter(([, re]) => re.test(text)).map(([name]) => name);
+}
+
+/** Pure: is there a standing instruction in any of these owner prompts? */
+export function standingAuthorization(prompts) {
+  for (const p of prompts || []) {
+    const m = STANDING.exec(String(p || ''));
+    if (m) return m[0];
+  }
+  return null;
+}
+
+/**
+ * The verdict. `prompts` = owner prompt texts of the session so far; `openPromises` = count of open
+ * first-person promises from this session in the work ledger.
+ */
+export function auditDeferral(message, { prompts = [], openPromises = 0 } = {}) {
+  const deferral = deferralIn(message);
+  if (!deferral) return { verdict: 'NONE' };
+  const blockers = blockersIn(message);
+  if (blockers.length) return { verdict: 'BLOCKER', deferral, blockers };
+  const standing = standingAuthorization(prompts);
+  if (!standing && openPromises < 1) return { verdict: 'UNAUTHORIZED', deferral };
+  return { verdict: 'DEFERRAL', deferral, authorization: standing ? `standing instruction "${standing}"` : `${openPromises} open promise(s)` };
+}
+
+/** Owner prompt texts from raw Claude transcript lines (main thread, not tool results, not meta). */
+export function ownerPrompts(lines) {
+  const out = [];
+  for (const l of lines || []) {
+    let o; try { o = typeof l === 'string' ? JSON.parse(l) : l; } catch { continue; }
+    const c = o?.message?.content;
+    if (o?.type !== 'user' || o.isSidechain || o.isMeta) continue;
+    if (Array.isArray(c) && c.some((x) => x?.type === 'tool_result')) continue;
+    const text = typeof c === 'string' ? c : Array.isArray(c) ? c.filter((x) => x?.type === 'text').map((x) => x.text).join('\n') : '';
+    if (text.trim() && !isHarnessGenerated(text)) out.push(text.slice(0, 8000));
+  }
+  return out;
+}
+
+/**
+ * The Stop-side read (Claude): owner prompts from the transcript tail plus the current prompt's text,
+ * which keys the per-prompt force counter. A transcript we cannot read yields no verdict (fail open).
+ */
+export function deferralAtStop({ message, transcriptPath, openPromises = 0, read }) {
+  if (typeof transcriptPath !== 'string' || !/\.jsonl$/i.test(transcriptPath) || !message) return null;
+  let lines;
+  try { lines = read(transcriptPath, { maxMs: 0 }); } catch { return null; }
+  const prompts = ownerPrompts(lines);
+  return { ...auditDeferral(message, { prompts, openPromises }), prompt: prompts.at(-1) || '' };
+}