ruvnet-brain 4.3.36 → 4.3.38

package/plugin/scripts/grounding-turn-evidence.mjs

@@ -0,0 +1,339 @@
+/**
+ * grounding-turn-evidence.mjs — the pure half of ADR-0030 decision-point gate #1: "before asserting
+ * what a tool or platform can or cannot do, did you CHECK a relevant source this turn, or are you
+ * recalling?" Plus gates #2 (architecture needs >= 3 options) and #3 (relayed numbers need a
+ * re-check), which run in SHADOW mode only: they are measured and logged, never delivered.
+ *
+ * WHY (owner, 2026-09-30): "a nudge without enforcement is worthless." The concrete incident: an
+ * answer asserted "No hook can change the model of the current turn" from a WebFetch page summary
+ * written by a small model, and a design was built on it. The existing grounding-turn-gate only
+ * checked that SOME search_ruvnet stamp was newer than the turn marker — presence, not relevance or
+ * order — armed only on rUv-stack prompts, and could not see WebFetch at all.
+ *
+ * DESIGN, deterministic and local (rUv ADR-G004 rejects LLM gate evaluation; no model is called):
+ *   1. UserPromptSubmit (grounding-turn-mark.mjs) arms the turn only when the prompt ASKS for a
+ *      capability / feasibility / architecture judgement AND names a subject (classifyPrompt). The
+ *      caller replayed a naive output-only regex at 13.5% of turns and an order-aware one at 0.93%,
+ *      mostly on harmless hedges; arming at prompt time is what keeps unarmed turns out of scope.
+ *   2. The sources read this turn come from the host transcript (turnSources) — the ordered,
+ *      complete record of every tool call and its result, including search_ruvnet's returned paths.
+ *      A WebFetch body is a small model's summary of the page, so it is WEAK evidence; so is a
+ *      subagent's relayed report and a WebSearch snippet list.
+ *   3. At Stop, each capability claim in the final answer (capability-claim-evidence.mjs's own
+ *      extractor, widened with this turn's vocabulary) needs one STRONG source whose path, URL,
+ *      command or query names the claim's subject and that was read AFTER the last weak source about
+ *      that subject (auditAssertions). Otherwise: one correction.
+ *
+ * Claims continuation-gate.mjs already audits (the RUVNET_TOOL behaviour class) are skipped here —
+ * one correction per claim, never two gates arguing over the same sentence.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { RUVNET_GATE1_TERMS } from './ruvnet-gate1-pattern.mjs';
+import { extractClaims } from './capability-claim-evidence.mjs';
+import { currentTurnRecords, strippedProse } from './completion-claim-evidence.mjs';
+
+const SCRIPTS_DIR = path.dirname(fileURLToPath(import.meta.url));
+
+// ── vocabulary ─────────────────────────────────────────────────────────────────────────────────────
+/** Platform nouns a capability question is usually about, beyond the product names. */
+const PLATFORM_NOUNS = ['hook', 'hooks', 'mcp', 'plugin', 'plugins', 'skill', 'skills', 'subagent', 'subagents',
+  'codex', 'claude code', 'cli', 'sdk', 'api', 'npm', 'github actions', 'workflow', 'launchd', 'cron',
+  'vercel', 'webfetch', 'websearch', 'hnsw', 'onnx', 'sqlite', 'rvf', 'metaharness', 'ruvllm', 'ruview',
+  'agentdb', 'ruflo', 'ruvector', 'aidefence', 'agentic-flow', 'agentic-qe', 'claude flow', 'agent browser'];
+const WEAK_WORDS = new Set(['the', 'and', 'for', 'with', 'this', 'that', 'brain', 'repo', 'store', 'docs', 'data',
+  'test', 'tests', 'main', 'core', 'app', 'web', 'site', 'code', 'tool', 'tools', 'model', 'models', 'agent',
+  'agents', 'file', 'files', 'flow', 'swarm', 'ruv', 'sparc', 'qe']);
+
+const brainHome = (env) => env.RUVNET_BRAIN_HOME || path.join(env.HOME || env.USERPROFILE || os.homedir(), '.cache', 'ruvnet-brain');
+
+/** Subject phrases: Gate-1 terms, platform nouns, repo aliases and installed store names. Never throws. */
+export function loadVocabulary({ env = process.env } = {}) {
+  const out = new Set([...RUVNET_GATE1_TERMS, ...PLATFORM_NOUNS]);
+  const kbDirs = [env.RUVNET_KB_DIR, path.join(brainHome(env), 'kb'), path.join(SCRIPTS_DIR, '..', '..', 'kb')].filter(Boolean);
+  for (const dir of kbDirs) {
+    try {
+      const aliases = JSON.parse(fs.readFileSync(path.join(dir, 'repo-aliases.json'), 'utf8'));
+      for (const [repo, list] of Object.entries(aliases || {})) { out.add(repo); for (const a of list || []) out.add(a); }
+    } catch { /* absent in this location */ }
+    try {
+      // Installed store names — but a plain single word ("support", "concepts", "marketing") is an
+      // English word far more often than a product; measured, it produced "doesn't support" claims.
+      for (const name of fs.readdirSync(dir)) {
+        if (!name.endsWith('.meta.json')) continue;
+        const store = name.slice(0, -'.meta.json'.length);
+        if (/[-_.0-9]/.test(store) || /^(?:ru|rv|agentic|cognitum)/i.test(store)) out.add(store);
+      }
+    } catch { /* absent in this location */ }
+  }
+  return [...out].map((v) => String(v).toLowerCase().trim())
+    .filter((v) => v.length >= 3 && !WEAK_WORDS.has(v) && /[a-z]/.test(v));
+}
+
+// ── tokens ─────────────────────────────────────────────────────────────────────────────────────────
+const singular = (t) => (t.length > 4 && t.endsWith('s') && !t.endsWith('ss') ? t.slice(0, -1) : t);
+/** Lowercased word tokens: each hyphen/dot/underscore compound (separators normalised to '-') and its
+ *  parts, singularised — so `code.claude.com/docs/en/hooks` yields claude, code, hook, … */
+export function tokenSet(text) {
+  const set = new Set();
+  const raw = String(text || '');
+  const s = `${raw.replace(/([a-z0-9])([A-Z])/g, '$1 $2')} ${raw}`.toLowerCase();
+  for (const compound of s.match(/[a-z0-9]+(?:[-_.][a-z0-9]+)*/g) || []) {
+    const parts = compound.split(/[-_.]/).filter(Boolean);
+    set.add(singular(parts.join('-')));
+    for (const part of parts) set.add(singular(part));
+  }
+  return set;
+}
+/** A subject phrase's words; a source binds the subject only when it names every one of them. */
+const subjectWords = (subject) => String(subject || '').toLowerCase().split(/\s+/)
+  .map((w) => singular(w.split(/[-_.]/).filter(Boolean).join('-'))).filter((w) => w.length >= 2);
+
+// ── prompt-time classification (UserPromptSubmit) ─────────────────────────────────────────────────
+const CAPABILITY_ASK = new RegExp([
+  String.raw`\b(?:can|could|does|do|is|are|will|would)\s+(?:it|we|you|i|there|(?:a|an|the|any|this|that|my|our)\s+[\w-]+|[\w-]+)\s+(?:[\w-]+\s+){0,3}?(?:do|support|handle|work|run|use|call|change|switch|make|force|read|write|access|detect|block|enforce|intercept|see|know|override|rewrite|route|pick|select|stop|prevent|allow|expose|return|send|trigger|fire)\b`,
+  String.raw`\bis\s+(?:it|there)\s+(?:possible|a\s+way|any\s+way)\b`, String.raw`\bpossible\s+to\b`, String.raw`\bable\s+to\b`,
+  String.raw`\bcapab(?:le|ility|ilities)\b`, String.raw`\bfeasib(?:le|ility)\b`, String.raw`\blimitations?\b`,
+  String.raw`\bwhat\s+(?:can|does|do)\b`, String.raw`\bhow\s+(?:does|do|can|could|would|should)\b`,
+  String.raw`\bwhether\b`, String.raw`\bsupports?\b`,
+].join('|'), 'i');
+const ARCHITECTURE_ASK = /\barchitect(?:ure|ural)?\b|\bdesign\b|\bapproach(?:es)?\b|\bbest\s+way\b|\bshould\s+(?:we|i)\s+(?:use|build|go|pick|choose)\b|\brecommend|\bwhich\s+(?:tool|library|option|approach)\b|\btrade-?offs?\b|\bfigure\s+out\s+(?:the\s+)?(?:best|how)\b/i;
+const CODE_ISH = /`([^`\n]{2,60})`|\b([A-Za-z][A-Za-z0-9]*(?:[-_.][A-Za-z0-9]+)+|[a-z]+[A-Z][A-Za-z0-9]+|[A-Z][a-z]+[A-Z][A-Za-z0-9]*)\b/g;
+
+/** Vocabulary phrases and code-ish identifiers the text names. */
+export function subjectsIn(text, vocab) {
+  const s = String(text || '');
+  const lower = s.toLowerCase();
+  const found = new Set();
+  for (const v of vocab) {
+    const re = new RegExp(`(?<![a-z0-9-])${v.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![a-z0-9-])`, 'i');
+    if (lower.includes(v) && re.test(s)) found.add(v);
+  }
+  for (const m of s.replace(/<\/?[A-Za-z_][\w-]*[^>]*>/g, ' ').matchAll(CODE_ISH)) {
+    const t = (m[1] || m[2] || '').trim();
+    if (t.length >= 4 && t.length <= 60 && !/^\d|\.(?:md|json|txt|png|jpg)$|^https?:|^e\.g\.?$|^i\.e\.?$/i.test(t) && !/\s/.test(t)) found.add(t.toLowerCase());
+    if (found.size >= 24) break;
+  }
+  return [...found].slice(0, 24);
+}
+
+/** Arm the turn when the prompt asks a capability/feasibility/architecture question about a subject. */
+export function classifyPrompt(text, vocab) {
+  const t = String(text || '');
+  const subjects = subjectsIn(t, vocab);
+  const architecture = ARCHITECTURE_ASK.test(t) && subjects.length > 0;
+  const capability = CAPABILITY_ASK.test(t) && subjects.length > 0;
+  return { assert: capability || architecture, architecture, subjects };
+}
+
+// ── the turn's sources (Stop, from the host transcript) ───────────────────────────────────────────
+const textOf = (c) => (typeof c === 'string' ? c : Array.isArray(c)
+  ? c.map((x) => (typeof x === 'string' ? x : x?.type === 'text' ? x.text : '')).join('\n') : '');
+const NOT_A_SOURCE = /^(?:Edit|Write|MultiEdit|NotebookEdit|TodoWrite|ToolSearch|AskUserQuestion|ExitPlanMode|SendMessage|TaskStop|Monitor|Skill|Artifact.*|EnterWorktree|ExitWorktree)$/;
+const MCP_MUTATING = /__(?:create|update|delete|remove|publish|deploy|push|write|send|set|merge|upload|patch|put|post|add|rename|move|approve|promote|rollback|cancel|buy|store|edit|import|reset|stop|terminate|spawn|execute)[a-z_-]*$/i;
+
+/** One tool call as evidence: what it looked at (`text`, used for binding) and how much to trust it. */
+export function sourceOf(name, input = {}, result = '') {
+  const n = String(name || '');
+  const r = String(result || '');
+  if (/(?:^|__)search_ruvnet$/.test(n)) {
+    const ok = /Searched \d+ RuvNet repos/.test(r) && !/^\s*(?:search_ruvnet error:|.{0,200}RUVNET BRAIN IS DOWN|.{0,200}RuvNet Brain is disabled)/s.test(r);
+    const paths = [...r.matchAll(/^path : (\S+)/gm)].map((m) => m[1]).slice(0, 20);
+    return { kind: 'search_ruvnet', ref: String(input.query || ''), strength: ok ? 'strong' : 'failed', ok, text: [input.query, ...paths].join(' ') };
+  }
+  if (n === 'WebFetch') return { kind: 'WebFetch', ref: String(input.url || ''), strength: 'weak', why: 'summarised-by-small-model', text: String(input.url || '') };
+  if (n === 'WebSearch') {
+    const urls = [...r.matchAll(/https?:\/\/[^\s)"'\]]+/g)].map((m) => m[0]).slice(0, 10);
+    return { kind: 'WebSearch', ref: String(input.query || ''), strength: 'weak', why: 'search-snippets', text: [input.query, ...urls].join(' ') };
+  }
+  if (n === 'Agent' || n === 'Task') {
+    return { kind: n, ref: String(input.description || input.subagent_type || ''), strength: 'weak', why: 'relayed-by-subagent',
+      text: `${input.description || ''} ${String(input.prompt || '').slice(0, 400)}`, result: r.slice(0, 20000) };
+  }
+  if (n === 'Read' || n === 'NotebookRead') return { kind: 'Read', ref: String(input.file_path || input.notebook_path || ''), strength: 'strong', text: String(input.file_path || input.notebook_path || ''), result: r.slice(0, 20000) };
+  if (n === 'Grep' || n === 'Glob') {
+    const ref = [input.pattern, input.path, input.glob].filter(Boolean).join(' ');
+    return { kind: n, ref, strength: 'strong', text: ref, result: r.slice(0, 20000) };
+  }
+  if (n === 'Bash') return { kind: 'Bash', ref: String(input.description || input.command || '').slice(0, 120), strength: 'strong', text: String(input.command || '').slice(0, 2000), result: r.slice(0, 20000) };
+  if (n.startsWith('mcp__') && !MCP_MUTATING.test(n)) {
+    return { kind: 'mcp', ref: n.split('__').pop(), strength: 'strong', text: `${n} ${JSON.stringify(input).slice(0, 1000)}`, result: r.slice(0, 20000) };
+  }
+  if (NOT_A_SOURCE.test(n)) return null;
+  return null;
+}
+
+/** Every source read this turn, in order, from a Claude JSONL transcript's lines. */
+export function turnSources(lines) {
+  const { boundaryFound, prompt, recs } = currentTurnRecords(lines);
+  const results = new Map();
+  for (const o of recs) {
+    const c = o?.message?.content;
+    if (Array.isArray(c)) for (const r of c) if (r?.type === 'tool_result' && r.tool_use_id) results.set(r.tool_use_id, textOf(r.content));
+  }
+  const sources = [];
+  for (const o of recs) {
+    const c = o?.message?.content;
+    if (o?.type !== 'assistant' || !Array.isArray(c)) continue;
+    for (const u of c) {
+      if (u?.type !== 'tool_use') continue;
+      const s = sourceOf(u.name, u.input || {}, results.get(u.id) || '');
+      if (s) sources.push({ ...s, order: sources.length });
+    }
+  }
+  return { boundaryFound, prompt, sources };
+}
+
+/** Did a search_ruvnet call this turn return a real grounded answer? (Gate 1, from the transcript.) */
+export const searchedThisTurn = (sources) => sources.some((s) => s.kind === 'search_ruvnet' && s.ok);
+
+// ── Stop-time audit ────────────────────────────────────────────────────────────────────────────────
+const HEDGE = /\?|\b(?:might|may|maybe|perhaps|probably|possibly|likely|unlikely|apparently|seems?|i\s+think|i\s+believe|i\s+suspect|i\s+(?:could|did)\s*n[o']?t\s+(?:confirm|verify|check)|not\s+sure|unsure|unverified|unconfirmed|not\s+verified|assum(?:e|ed|ing)|if|unless|whether|would|should|once|when)\b/i;
+const NEGATIVE = /\b(?:no\s+[\w-]+\s+(?:can|could|will)|cannot|can(?:'|’)t|can\s+not|is\s*n(?:'|’)?t\s+(?:possible|supported|able)|not\s+possible|impossible|does\s*n(?:'|’)?t\s+(?:support|allow|expose|provide|exist|let|offer)|does\s+not\s+(?:support|allow|expose|provide|exist|let|offer)|there(?:'|’)?s\s+no\s+(?:way|api|hook|setting|option)|there\s+is\s+no\s+(?:way|api|hook|setting|option)|has\s+no\s+(?:way|api|hook|setting|option)|only\s+(?:supports?|allows?|exposes?))\b/i;
+
+/** Not an assertion: a hedge or question, a table cell, a "Label: description" status line, or an
+ *  instruction introducing a command block ("Run this …:"). */
+const notAClaim = (s) => HEDGE.test(s) || s.includes('|') || /^[\w\s/-]{1,40}:\s/.test(s) || /:\s*$/.test(s);
+
+function sentences(message) {
+  return strippedProse(message).split(/(?<=[.!?])\s+|\n+/).map((s) => s.replace(/^[\s\-*•#>]+|\*\*/g, '').trim())
+    .filter((s) => s && s.length <= 400);
+}
+
+/** Capability claims about a vocabulary subject, excluding hedges and the sentences continuation-gate owns. */
+export function capabilityClaims(rawMessage, tools) {
+  // Headings name a topic, they do not assert one; emphasis markers break sentence splitting.
+  const message = String(rawMessage || '').replace(/^\s*#{1,6}\s.*$/gm, ' ').replace(/\*\*|__/g, '');
+  const owned = new Set(extractClaims(message).map((c) => c.text));
+  const out = new Map();
+  const subjectRe = tools.length ? new RegExp(`(?<![a-z0-9-])(${tools.map((t) => t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).sort((a, b) => b.length - a.length).join('|')})(?![a-z0-9-])`, 'i') : null;
+  for (const claim of extractClaims(message, { tools })) {
+    if (claim.class !== 'behavior' || owned.has(claim.text)) continue;
+    const text = claim.text.replace(/^[\s\-*•#>]+|\*\*/g, '').trim();
+    if (!notAClaim(text)) out.set(text, { text, subject: claim.tool.toLowerCase() });
+  }
+  if (subjectRe) {
+    for (const s of sentences(message)) {
+      const neg = NEGATIVE.exec(s);
+      if (out.has(s) || owned.has(s) || notAClaim(s) || !neg) continue;
+      // The subject must be what the negation is about: named before it, within a short clause.
+      const m = subjectRe.exec(s);
+      if (m && m.index <= neg.index + 12 && neg.index - m.index <= 40) out.set(s, { text: s, subject: m[1].toLowerCase() });
+    }
+  }
+  return [...out.values()];
+}
+
+/**
+ * Sources that name every word of the subject. A STRONG source may also bind through what it
+ * returned (a file read, a command's output, a search's hits); a weak one only through what it
+ * pointed at — a summary's own wording is exactly what is not trusted. A word of 5+ characters also
+ * matches inside a longer compound (`displaylink` in `DisplayLinkUserAgent`).
+ */
+export function bindingSources(subject, sources) {
+  const words = subjectWords(subject);
+  if (!words.length) return [];
+  const has = (tokens, w) => tokens.has(w) || (w.length >= 5 && [...tokens].some((t) => t.length > w.length && t.includes(w)));
+  return sources.filter((s) => {
+    const t = tokenSet(s.strength === 'strong' ? `${s.text} ${s.ref} ${s.result || ''}` : s.text);
+    return words.every((w) => has(t, w));
+  });
+}
+
+/**
+ * The audit. `sources` null = this host's sources are unknown (Codex rollout not parsed): only claims
+ * a stamp term can bind are judged, the rest are UNKNOWN and never blocked.
+ */
+/** Proper nouns / identifiers the ANSWER uses as a sentence subject (e.g. "Thunderbolt can't …"). */
+const ANSWER_SUBJECT = /(?<=[a-z,;:]\s)([A-Z][A-Za-z0-9]*(?:[-.][A-Za-z0-9]+)*)(?=\s+(?:can(?:not|'t|’t)?|does(?:n't|n’t|\s+not)?|supports?|only|is\s*n(?:'|’)?t|has\s+no|won't|will\s+not)\b)|^([A-Z][A-Za-z0-9]*(?:[-.][A-Za-z0-9]+)+|[A-Z][a-z]+[A-Z][A-Za-z0-9]*)(?=\s+(?:can|does|supports?|only|is\s*n))/gm;
+const NOT_SUBJECT = new Set(['i', 'it', 'this', 'that', 'there', 'they', 'we', 'you', 'he', 'she', 'which', 'what', 'who', 'nothing', 'none', 'one']);
+export function answerSubjects(message) {
+  const out = new Set();
+  for (const m of strippedProse(message).matchAll(ANSWER_SUBJECT)) {
+    const t = (m[1] || m[2] || '').toLowerCase();
+    if (t.length >= 3 && !NOT_SUBJECT.has(t)) out.add(t);
+  }
+  return [...out];
+}
+
+export function auditAssertions({ message, subjects = [], vocab = [], sources = null, stampTerms = [] }) {
+  const tools = [...new Set([...vocab, ...subjects, ...answerSubjects(message)])].filter((t) => t.length >= 3);
+  const claims = capabilityClaims(message, tools);
+  const findings = [];
+  const unknown = [];
+  for (const claim of claims) {
+    if (sources === null) {
+      const words = subjectWords(claim.subject);
+      const rUv = words.some((w) => RUVNET_GATE1_TERMS.includes(w));
+      if (!rUv) { unknown.push(claim); continue; }
+      if (!words.every((w) => stampTerms.includes(w))) findings.push({ ...claim, reason: 'no search_ruvnet stamp for this subject this turn', read: stampTerms.map((t) => `search_ruvnet stamp: ${t}`) });
+      continue;
+    }
+    const binding = bindingSources(claim.subject, sources.filter((s) => s.strength !== 'failed'));
+    const lastWeak = Math.max(-1, ...binding.filter((s) => s.strength === 'weak').map((s) => s.order));
+    const strongAfter = binding.some((s) => s.strength === 'strong' && s.order > lastWeak);
+    if (!strongAfter) {
+      findings.push({ ...claim, reason: lastWeak >= 0 ? 'the only sources about it this turn are weak (summarised or relayed)' : 'no source about it was read this turn',
+        read: describeSources(lastWeak >= 0 ? binding : sources) });
+    }
+  }
+  return { claims, findings, unknown };
+}
+
+export function describeSources(sources, max = 4) {
+  if (!sources.length) return ['nothing'];
+  const shown = sources.slice(-max).map((s) => `${s.kind} ${JSON.stringify(String(s.ref).slice(0, 70))}${s.strength === 'weak' ? ` [${s.why} = weak evidence]` : ''}`);
+  return sources.length > max ? [`${sources.length - max} earlier`, ...shown] : shown;
+}
+
+export function correctionText(findings) {
+  const f = findings[0];
+  const lines = [
+    `You asserted "${f.text.slice(0, 200)}" about ${f.subject}; no relevant source was read this turn`
+      + ` (${f.reason}; read: ${f.read.join('; ')}).`,
+    ...findings.slice(1, 3).map((x) => `Also unsourced: "${x.text.slice(0, 160)}" about ${x.subject}.`),
+    'Check the real source now (read the file, run the command with --help, search_ruvnet, or fetch the',
+    'raw page with curl — a WebFetch body is a small model\'s summary) or restate each claim as UNVERIFIED.',
+    'ADR-0030 decision point #1: "Did you CHECK, or are you recalling? Name the source."',
+  ];
+  return lines.join('\n');
+}
+
+// ── shadow gates #2 and #3 (logged, never delivered) ──────────────────────────────────────────────
+const RECOMMENDS = /\b(?:I(?:'d|’d|\s+would)?\s+(?:recommend|propose|suggest)|my\s+recommendation|recommended\s+(?:approach|option|design)|the\s+design\s+I(?:'d|’d|\s+would)\s+propose|I(?:'d|’d)\s+(?:go|build)\s+with|go\s+with\s+option)\b/i;
+const OPTION_MARK = /(?:^|\n)\s*(?:#{1,4}\s*|[-*•]\s*|\*\*)?(?:option|alternative|approach)\s*(?:[A-Z1-9]|one|two|three|four)\b|\b(?:option|alternative)\s+(?:[A-D1-4])\b/gi;
+export function architectureShadow({ architecture, message }) {
+  if (!architecture || !RECOMMENDS.test(strippedProse(message))) return null;
+  const options = new Set([...String(message).matchAll(OPTION_MARK)].map((m) => m[0].trim().toLowerCase().replace(/[^a-z0-9 ]/g, ''))).size;
+  return options >= 3 ? null : { gate: 'adr-0030-2-architecture-options', options, wouldBlock: true };
+}
+
+const NUMBER = /(?<![\w.])\d+(?:[.,]\d+)?(?:\s?%|\/\d+)?(?![\w])/g;
+export function relayShadow({ message, sources }) {
+  if (!sources?.length) return null;
+  const agentIdx = sources.filter((s) => s.kind === 'Agent' || s.kind === 'Task');
+  if (!agentIdx.length) return null;
+  const nums = [...new Set((strippedProse(message).match(NUMBER) || []).map((n) => n.replace(/\s/g, '')))]
+    .filter((n) => /[.%/]/.test(n) || n.replace(/\D/g, '').length >= 3).filter((n) => !/^(?:19|20)\d\d$/.test(n));
+  const relayed = nums.filter((n) => {
+    const from = agentIdx.find((a) => String(a.result || '').includes(n));
+    if (!from) return false;
+    return !sources.some((s) => s.order > from.order && s.kind !== 'Agent' && s.kind !== 'Task' && String(s.result || '').includes(n));
+  });
+  return relayed.length ? { gate: 'adr-0030-3-relayed-number', numbers: relayed.slice(0, 8), wouldBlock: true } : null;
+}
+
+/** Append one shadow row, bounded. Never throws. */
+export function logShadow(row, { env = process.env } = {}) {
+  try {
+    const file = env.RUVNET_ASSERTION_SHADOW_LOG || path.join(brainHome(env), 'assertion-gate-shadow.jsonl');
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.appendFileSync(file, `${JSON.stringify(row)}\n`);
+    if (fs.statSync(file).size > 512 * 1024) {
+      const keep = fs.readFileSync(file, 'utf8').split('\n').filter(Boolean).slice(-500);
+      fs.writeFileSync(file, `${keep.join('\n')}\n`);
+    }
+  } catch { /* shadow measurement never breaks a turn */ }
+}

package/plugin/scripts/grounding-turn-gate.mjs

@@ -58,6 +58,20 @@
  * interrupted/cancelled turn is never forced. The marker is consumed (deleted) whether or not it
  * fires, so a genuinely abandoned marker cannot pressure some unrelated later turn.
  *
+ * 2026-09-30 — ADR-0030 DECISION POINT #1, AND THE FALSE ALARM. Two changes, one registration:
+ *   - On Claude the "was search_ruvnet called" question is answered from the TRANSCRIPT (the ordered
+ *     record of every tool call and result, grounding-turn-evidence.mjs turnSources), not from stamp
+ *     mtimes. The stamp was a lossy proxy: 7 real false alarms were measured, 3 from a queued
+ *     mid-turn prompt re-dating the marker (fixed in grounding-turn-mark.mjs), 3 pre-H1 vocabulary
+ *     misses, 1 successful search whose stamp never minted. Codex's rollout is not parsed anywhere in
+ *     this repo, so Codex keeps the stamp evidence.
+ *   - When the marker says the prompt asked a capability/feasibility/architecture question, every
+ *     capability claim in the final answer needs a RELEVANT, STRONG source read this turn after the
+ *     last weak one (auditAssertions). A WebFetch body is a small model's summary: weak.
+ *   Gates #2/#3 of ADR-0030 run in shadow (logShadow) — measured, never delivered.
+ *   At most ONE correction per stop episode: both checks compose into one message, and
+ *   stop_hook_active silences the continued stop.
+ *
  * FAILS OPEN ALWAYS. Exit 0 unconditionally — a gate that breaks a turn's completion because a
  * cache directory was unreadable would be disabled within a day.
  */
@@ -65,8 +79,13 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { readStdinBounded } from './hook-input.mjs';
-import { markerPathFor } from './grounding-turn-mark.mjs';
+import { readStopHookInput } from './hook-input.mjs';
+import { markerPathFor, readMarker } from './grounding-turn-mark.mjs';
+import { readSettledTranscript } from './turn-outcome-capture.mjs';
+import {
+  architectureShadow, auditAssertions, correctionText, describeSources, loadVocabulary, logShadow,
+  relayShadow, searchedThisTurn, turnSources,
+} from './grounding-turn-evidence.mjs';
 
 const HOME = os.homedir();
 const EXIT_ALLOW = 0;
@@ -94,6 +113,14 @@ export function newestGroundingStampMs(dir = GROUNDED_DIR) {
   return newest;
 }
 
+/** Product terms whose stamp was minted at or after `sinceMs` (Codex's only view of this turn's searches). */
+export function stampTermsSince(sinceMs, dir = GROUNDED_DIR) {
+  try {
+    return fs.readdirSync(dir).filter((name) => !name.startsWith('.')
+      && fs.statSync(path.join(dir, name)).mtimeMs >= sinceMs - SKEW_MS);
+  } catch { return []; }
+}
+
 /** A little slack for filesystem mtime granularity (some filesystems round to whole seconds), so a
  *  stamp written the same wall-clock second as the marker is never wrongly judged "before" it. */
 const SKEW_MS = 1500;
@@ -106,18 +133,54 @@ export function wasGroundedSince(markerMs, newestStampMs) {
   return newestStampMs >= markerMs - SKEW_MS;
 }
 
-async function readHookInput() {
-  // Mirrors continuation-gate.mjs's own three-way source classification exactly (ADR-043 /
-  // Fable #1): only a payload we actually parsed off stdin may ever force a continuation.
-  if (process.stdin.isTTY) return { __source: 'tty' };
+/**
+ * The whole Stop decision for one armed turn: the correction text, or null. Exported so tests can
+ * drive it with a synthetic transcript. Every failure inside returns null (fail open).
+ */
+export function decide({ hookInput, marker, markerMs, env = process.env, read = readSettledTranscript }) {
   try {
-    const raw = (await readStdinBounded()).toString('utf8');
-    return { ...JSON.parse(raw || '{}'), __source: 'stdin' };
-  } catch { return { __source: 'unreadable' }; }
+    const host = env.RUVNET_HOOK_HOST === 'codex' ? 'codex' : 'claude';
+    const tp = hookInput.transcript_path;
+    let turn = null;
+    if (host === 'claude' && typeof tp === 'string' && /\.jsonl$/i.test(tp)) {
+      try { turn = turnSources(read(tp, { maxMs: 0 })); } catch { turn = null; }
+    }
+    const sources = turn ? turn.sources : null;
+    const message = String(hookInput.last_assistant_message || '');
+
+    let assertion = null;
+    if (marker.assert && message) {
+      const vocab = loadVocabulary({ env });
+      const audit = auditAssertions({ message, subjects: marker.subjects, vocab, sources,
+        stampTerms: sources ? [] : stampTermsSince(markerMs) });
+      if (audit.findings.length) assertion = audit.findings;
+      const shadow = [architectureShadow({ architecture: marker.architecture, message }), relayShadow({ message, sources })].filter(Boolean);
+      for (const row of shadow) logShadow({ ...row, at: new Date().toISOString(), session: hookInput.session_id, host });
+    }
+
+    const grounded = marker.gate1 === false ? true
+      : sources ? searchedThisTurn(sources) : wasGroundedSince(markerMs, newestGroundingStampMs());
+    if (assertion) {
+      return correctionText(assertion) + (grounded ? '' : '\nThis turn also touched the rUv stack and no successful search_ruvnet call was recorded: call it with the product term(s).');
+    }
+    if (grounded) return null;
+    return [
+      'This turn touched the RuvNet / rUv stack and ground-ruvnet\'s directive required calling the',
+      'search_ruvnet MCP tool before asserting what any RuvNet tool can/cannot do — but no successful',
+      sources ? `search_ruvnet call is in this turn's transcript (read this turn: ${describeSources(sources).join('; ')}).`
+        : 'search_ruvnet call was recorded this turn (checked against the grounding-stamp evidence).',
+      '',
+      'Do NOT end the turn on an ungrounded rUv-domain answer. Call `search_ruvnet` now with the',
+      'relevant product term(s) in the query, ground your answer in the cited source paths it returns,',
+      'and correct anything you already asserted from memory. Training priors on the rUv stack are',
+      'stale by construction (ADR-0012) — this is not a formality.',
+    ].join('\n');
+  } catch { return null; }
 }
 
+
 async function main() {
-  const hookInput = await readHookInput();
+  const hookInput = await readStopHookInput();
   if (hookInput.__source !== 'stdin') process.exit(EXIT_ALLOW);
   if (hookInput.stop_hook_active) process.exit(EXIT_ALLOW);
   if (hookInput.hook_event_name !== 'Stop' || hookInput.interrupted || hookInput.cancelled) {
@@ -135,27 +198,16 @@ async function main() {
   // unrelated turn (same reasoning as continuation-gate.mjs's cooldown lock, applied here as a
   // single-use marker instead of a timed window, because "did this turn ground itself" has no
   // meaningful reading beyond the one turn it was written for).
+  const armed = readMarker(marker) || { gate1: true, subjects: [] };
   try { fs.unlinkSync(marker); } catch { /* a marker that vanished between stat and unlink already told us what we needed */ }
 
-  const grounded = wasGroundedSince(markerStat.mtimeMs, newestGroundingStampMs());
-  if (grounded) process.exit(EXIT_ALLOW);
-
-  const lines = [
-    'This turn touched the RuvNet / rUv stack and ground-ruvnet\'s directive required calling the',
-    'search_ruvnet MCP tool before asserting what any RuvNet tool can/cannot do — but no successful',
-    'search_ruvnet call was recorded this turn (checked against the same grounding-stamp evidence',
-    'ground-before-write.sh already trusts).',
-    '',
-    'Do NOT end the turn on an ungrounded rUv-domain answer. Call `search_ruvnet` now with the',
-    'relevant product term(s) in the query, ground your answer in the cited source paths it returns,',
-    'and correct anything you already asserted from memory. Training priors on the rUv stack are',
-    'stale by construction (ADR-0012) — this is not a formality.',
-  ];
+  const text = decide({ hookInput, marker: armed, markerMs: markerStat.mtimeMs });
+  if (!text) process.exit(EXIT_ALLOW);
 
   process.stdout.write(JSON.stringify({
     hookSpecificOutput: {
       hookEventName: 'Stop',
-      additionalContext: lines.join('\n'),
+      additionalContext: text,
     },
   }));
   process.exit(EXIT_ALLOW);

package/plugin/scripts/grounding-turn-mark.mjs

@@ -24,6 +24,22 @@
  * one). Its CONTENT is a JSON blob for a human reading the cache, but the Stop-time gate only ever
  * trusts the mtime.
  *
+ * 2026-09-30 — TWO ARMS, ONE MARKER (ADR-0030 decision point #1). The marker now also records, as
+ * JSON content, whether the prompt ASKS for a capability / feasibility / architecture judgement about
+ * a subject (grounding-turn-evidence.mjs classifyPrompt) and which subjects it named, so the Stop gate
+ * can require a relevant source for any capability claim the answer makes — on any platform, not
+ * only the rUv stack. `gate1` keeps the original meaning (the prompt matched Gate 1).
+ *
+ * THE FALSE-ALARM FIX. Measured on real transcripts (7 turns where the Stop gate said "no successful
+ * search_ruvnet call was recorded" although one had been made): in 3 of them a QUEUED message (a
+ * real user message typed mid-turn, or a task notification before H2) fired UserPromptSubmit again
+ * AFTER the search and rewrote this marker, moving the turn boundary past the evidence. So an
+ * unconsumed marker is now MERGED, never re-dated: its mtime (the boundary) stays at the first arm
+ * of the stop episode. A marker older than STALE_MS (an interrupted turn never reaches Stop) is
+ * replaced instead. Of the other 4, three were pre-H1 vocabulary misses (fixed by H1) and one was a
+ * successful search whose stamp never minted (2026-09-30, cause not recoverable from the transcript);
+ * so on Claude the Stop gate now reads the transcript itself (grounding-turn-gate.mjs).
+ *
  * CONTRACT: PostToolUse-shaped hooks in this repo are advisory; this one is too — it can never
  * block a prompt. It exits 0 unconditionally and writes nothing to stdout Claude/Codex would act
  * on (UserPromptSubmit's silence contract). A write failure (unwritable cache dir, race, etc.) is
@@ -36,6 +52,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { readStdinBounded, isHarnessGenerated } from './hook-input.mjs';
 import { ruvnetGate1Matches } from './ruvnet-gate1-pattern.mjs';
+import { classifyPrompt, loadVocabulary } from './grounding-turn-evidence.mjs';
 
 const HOME = os.homedir();
 export const MARKER_DIR = process.env.RUVNET_GROUNDING_TURN_DIR
@@ -49,17 +66,50 @@ export function markerPathFor(sessionId, dir = MARKER_DIR) {
   return safe ? path.join(dir, `${safe}.json`) : null;
 }
 
-/** Exported for the unit test: pure decision, no I/O. */
-export function shouldMark(hookInput) {
-  if (!hookInput || hookInput.hook_event_name !== 'UserPromptSubmit') return false;
-  if (!hookInput.session_id) return false;
-  const text = String(hookInput.prompt ?? hookInput.user_prompt ?? hookInput.input ?? '');
+const promptOf = (hookInput) => String(hookInput?.prompt ?? hookInput?.user_prompt ?? hookInput?.input ?? '');
+const eligible = (hookInput) => Boolean(hookInput && hookInput.hook_event_name === 'UserPromptSubmit' && hookInput.session_id
   // H2: a background task notification, slash-command scaffold, or other harness-authored message
   // arrives on UserPromptSubmit exactly like real user text — arming the Stop-time grounding gate off
   // one of these (because it happens to mention a rUv term) would demand a search_ruvnet call to
   // close out a "turn" nobody had a hand in.
-  if (isHarnessGenerated(text)) return false;
-  return ruvnetGate1Matches(text);
+  && !isHarnessGenerated(promptOf(hookInput)));
+
+/** Exported for the unit test: pure decision, no I/O. Gate 1 (the rUv-stack search requirement). */
+export function shouldMark(hookInput) {
+  return eligible(hookInput) && ruvnetGate1Matches(promptOf(hookInput));
+}
+
+/** Both arms for one prompt, or null when neither fires. Pure apart from the vocabulary it is given. */
+export function armFor(hookInput, vocab = []) {
+  if (!eligible(hookInput)) return null;
+  const gate1 = ruvnetGate1Matches(promptOf(hookInput));
+  const c = classifyPrompt(promptOf(hookInput), vocab);
+  if (!gate1 && !c.assert) return null;
+  return { gate1, assert: c.assert, architecture: c.architecture, subjects: c.subjects };
+}
+
+export const STALE_MS = 2 * 3600_000;
+/** A marker's JSON, or null. Old markers (no `gate1` field) were only ever written for Gate 1. */
+export function readMarker(file) {
+  try {
+    const m = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return m && typeof m === 'object' ? { gate1: m.gate1 !== false, assert: !!m.assert, architecture: !!m.architecture,
+      subjects: Array.isArray(m.subjects) ? m.subjects.map(String) : [], at: m.at } : null;
+  } catch { return null; }
+}
+
+/** Merge an arm into an unconsumed marker WITHOUT moving its mtime (the turn boundary). */
+export function writeArm(file, arm, meta = {}, now = Date.now()) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  let st = null;
+  try { st = fs.statSync(file); } catch { /* none yet */ }
+  const prev = st && now - st.mtimeMs < STALE_MS ? readMarker(file) : null;
+  const next = prev ? { ...meta, at: prev.at, gate1: prev.gate1 || arm.gate1, assert: prev.assert || arm.assert,
+    architecture: prev.architecture || arm.architecture, subjects: [...new Set([...prev.subjects, ...arm.subjects])].slice(0, 32) }
+    : { ...meta, at: new Date(now).toISOString(), ...arm };
+  fs.writeFileSync(file, JSON.stringify(next) + '\n');
+  if (prev) fs.utimesSync(file, st.atime, st.mtime);
+  return next;
 }
 
 async function main() {
@@ -69,17 +119,14 @@ async function main() {
     hookInput = JSON.parse(raw || '{}');
   } catch { process.exit(0); }
 
-  if (!shouldMark(hookInput)) process.exit(0);
+  let arm = null;
+  try { arm = armFor(hookInput, loadVocabulary()); } catch { arm = shouldMark(hookInput) ? { gate1: true, assert: false, architecture: false, subjects: [] } : null; }
+  if (!arm) process.exit(0);
 
   const file = markerPathFor(hookInput.session_id);
   if (!file) process.exit(0);
   try {
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, JSON.stringify({
-      at: new Date().toISOString(),
-      sessionId: hookInput.session_id,
-      turnId: hookInput.turn_id || hookInput.prompt_id || null,
-    }) + '\n');
+    writeArm(file, arm, { sessionId: hookInput.session_id, turnId: hookInput.turn_id || hookInput.prompt_id || null });
   } catch { /* fail-open: no marker means the Stop gate stays silent, never a false block */ }
   process.exit(0);
 }

package/plugin/scripts/hook-input.mjs

@@ -96,6 +96,21 @@ export function readStdinBounded({ maxBytes = 65536, idleMs = 50, emptyMs = 250
   });
 }
 
+/**
+ * The Stop-hook payload with its provenance, shared by every Stop gate (was a verbatim copy in
+ * continuation-gate and grounding-turn-gate). Three sources, treated differently by callers:
+ * 'tty' (run bare, never force), 'unreadable' (read/parse failed — fs.readFileSync(0) throws EAGAIN
+ * intermittently on macOS; laundering that into {} would read as a fresh stop), 'stdin' (parsed — the
+ * only source allowed to force). ADR-043.
+ */
+export async function readStopHookInput() {
+  if (process.stdin.isTTY) return { __source: 'tty' };
+  try {
+    const raw = (await readStdinBounded()).toString('utf8');
+    return { ...JSON.parse(raw || '{}'), __source: 'stdin' };
+  } catch { return { __source: 'unreadable' }; }
+}
+
 /** The tool being invoked ("Bash", "Write", …), or "" if absent. */
 export function toolName(ev) {
   return ev && typeof ev.tool_name === 'string' ? ev.tool_name : '';

package/plugin/scripts/hook-shim.mjs

@@ -120,7 +120,9 @@ const TABLE = {
   // way — it stopped trusting hook-shim.mjs as a blind generic spawner, not their presence here.
   'learn-capture':    { file: 'learn-capture.sh',    interpreter: 'bash', mode: 'advisory', offBehavior: 'silence' },
   'learn-flush':      { file: 'learn-flush.mjs',     interpreter: 'node', mode: 'advisory', offBehavior: 'silence' },
-  'session-snapshot': { file: 'session-snapshot-hook.mjs', interpreter: 'node', mode: 'advisory', offBehavior: 'run', stdinBytes: 65536 },
+  // 1 MiB, not 64 KiB: the Stop payload now carries `last_assistant_message`, and a long closing
+  // message truncated mid-JSON would parse as `{}` and silently drop the whole capture.
+  'session-snapshot': { file: 'session-snapshot-hook.mjs', interpreter: 'node', mode: 'advisory', offBehavior: 'run', stdinBytes: 1048576 },
   'md-stamp':         { file: 'md-stamp.mjs',        interpreter: 'node', mode: 'advisory', offBehavior: 'silence' },
   // THE EXTERNAL-SIGNAL WATCH PLANE, W1 OBSERVED (ADR-058 §D3; DDD-0013 Context 2). PostToolUse,
   // matcher ^Bash$ (anchored — an unanchored matcher is F3/F4). Classifies gh/vercel/netlify/npm