ruvnet-brain 4.3.17 → 4.3.19

package/README.md

@@ -7,7 +7,7 @@ Created: 2026-06-29 22:36:38 EDT
 
 # 🧠 RuvNet Brain
 
-### 🧠 RuvNet Brain — [![RuvNet Brain version 4.3.17 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.3.17-updated_2026--07--30_03:24_EDT-1E90FF?style=for-the-badge&labelColor=0757BA)](https://github.com/stuinfla/ruvnet-brain/blob/main/plugin/.claude-plugin/plugin.json)
+### 🧠 RuvNet Brain — [![RuvNet Brain version 4.3.19 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.3.19-updated_2026--07--30_03:24_EDT-1E90FF?style=for-the-badge&labelColor=0757BA)](https://github.com/stuinfla/ruvnet-brain/blob/main/plugin/.claude-plugin/plugin.json)
 
 **A portable, source-grounded brain over Reuven Cohen's (rUv's) RuvNet stack — delivered as a Claude Code plugin that makes Claude _use_ the stack instead of fighting it.**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.3.17",
+  "version": "4.3.19",
   "description": "One-command installer for RuvNet Brain — a portable, source-grounded brain over rUv's RuvNet building blocks, delivered as a Claude Code plugin so Claude uses the stack instead of fighting it.",
   "type": "module",
   "bin": {

package/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ruvnet-brain",
   "description": "RuvNet brain transplant for Claude Code — grounds every RuvNet decision in real source across 77 rUv repositories, prefers Ruflo / RuVector-RVF / AgentDB over training-prior defaults (pgvector, Pinecone, hand-rolled cosine), and can pull in any RuvNet repo on demand. Ships an enforced UserPromptSubmit retrieve-and-inject grounding hook that sharply reduces drift.",
-  "version": "4.3.17",
+  "version": "4.3.19",
   "author": {
     "name": "Stuart Kerr"
   },

package/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.3.17",
+  "version": "4.3.19",
   "description": "Source-grounded RuvNet knowledge, lifecycle enforcement, and learning for Codex.",
   "author": {
     "name": "Stuart Kerr"

package/scripts/doc-currency.mjs

@@ -444,6 +444,56 @@ export function listDocs(root, dirs = DEFAULT_DIRS) {
   return out;
 }
 
+// A changed-scope check must discover its documents before doing the expensive git-derived
+// evaluation.  The declarations are intentionally read from the document itself here; resolving
+// every governed blob and caller for every historical document defeats the purpose of --changed.
+// This matcher mirrors the supported declaration shapes (literal paths and the simple * / ** /
+// ? globs used in this repository) and is conservative for directory declarations.
+function declarationIntersectsTouched(declaration, touched) {
+  let pattern = String(declaration || '').trim().replace(/^\.\//, '');
+  if (!pattern) return false;
+  const directory = pattern.endsWith('/');
+  pattern = pattern.replace(/\/+$/, '');
+  if (!/[*?\[\]]/.test(pattern)) {
+    return [...touched].some((file) => file === pattern || (directory && file.startsWith(`${pattern}/`)));
+  }
+  let source = '^';
+  for (let i = 0; i < pattern.length; i += 1) {
+    const char = pattern[i];
+    if (char === '*' && pattern[i + 1] === '*') {
+      source += '.*';
+      i += 1;
+    } else if (char === '*') source += '[^/]*';
+    else if (char === '?') source += '[^/]';
+    else if (char === '[') {
+      const end = pattern.indexOf(']', i + 1);
+      if (end > i + 1) {
+        source += pattern.slice(i, end + 1);
+        i = end;
+      } else source += '\\[';
+    } else source += char.replace(/[\\^$+?.()|{}]/g, '\\$&');
+  }
+  const matcher = new RegExp(`${source}$`);
+  return [...touched].some((file) => matcher.test(file));
+}
+
+/**
+ * Return only documents whose own file or governed declaration intersects a candidate diff.
+ * `evaluateDoc` remains the authority for the final derived result; this function only narrows
+ * the set of documents that need that work in a `--changed` check.
+ */
+export function changedDocumentCandidates(root, touched, dirs = DEFAULT_DIRS) {
+  const changed = touched instanceof Set ? touched : new Set(touched || []);
+  return listDocs(root, dirs).filter((rel) => {
+    if (changed.has(rel)) return true;
+    const text = fs.readFileSync(path.join(root, rel), 'utf8');
+    const frontmatter = parseFrontmatter(text);
+    const declared = frontmatter.keys.governs;
+    const governs = Array.isArray(declared) ? declared : declared ? [declared] : [];
+    return governs.some((entry) => declarationIntersectsTouched(entry, changed));
+  });
+}
+
 export function evaluateDoc(root, rel, opts = {}) {
   const { checkWiring = true } = opts;
   const abs = path.join(root, rel);
@@ -858,7 +908,13 @@ export function main(argv = process.argv.slice(2)) {
     if (!base.ok || !base.out) return 1;
     if (base.ok && base.out) driftFloor = base.out.split('\n')[0];
   }
-  const result = evaluate(a.root, { dirs, checkWiring: !a.noWiring, driftFloor });
+  // In check mode, --changed is a candidate gate: narrow the expensive evaluation to documents
+  // that the diff can actually invalidate. Reports remain corpus-wide, while the blocking set
+  // still follows the same Document -> Governed path relationship as changedDocumentScope().
+  const files = touched && a.mode === 'check'
+    ? changedDocumentCandidates(a.root, touched, dirs)
+    : undefined;
+  const result = evaluate(a.root, { dirs, checkWiring: !a.noWiring, driftFloor, files });
 
   let scope = null;
   if (touched) {

package/scripts/eval-brain.mjs

@@ -80,10 +80,11 @@ export function wilson(k, n, z = 1.96) {
  * answers "does the query reach the store that actually holds the answer" (brain-score.mjs's own
  * wording for this metric) — that store is the one named in `receipt`, when one was verified.
  */
-export function gradeQuestion(q, { grounded, citations, bannerPresent, receipt }) {
+export function gradeQuestion(q, { grounded, citations, bannerPresent, receipt, repoAliases = {} }) {
   const top = citations?.[0] ?? null;
   const routedRepo = receipt?.repo ?? top?.repo ?? null;
-  const routed = !!(grounded && q.expectRepo?.length && routedRepo && q.expectRepo.includes(routedRepo));
+  const routed = !!(grounded && q.expectRepo?.length && routedRepo
+    && repoMatchesExpected(routedRepo, q.expectRepo, repoAliases));
   const abstained = !top || (typeof top.ce === 'number' && top.ce < ABSTAIN_CE);
   switch (q.stratum) {
     case 'adversarial':
@@ -97,6 +98,16 @@ export function gradeQuestion(q, { grounded, citations, bannerPresent, receipt }
   }
 }
 
+// Ground truth names the logical repository, while the deployed corpus may use a documented
+// store alias (for example agent-harness-generator -> metaharness).  Credit only aliases present
+// in the shipped registry; never turn an arbitrary similarly named store into a pass.
+export function repoMatchesExpected(actual, expected, aliases = {}) {
+  if (!actual || !Array.isArray(expected)) return false;
+  if (expected.includes(actual)) return true;
+  return expected.some((canonical) => Array.isArray(aliases?.[canonical])
+    && aliases[canonical].includes(actual));
+}
+
 /** Aggregate graded rows into the four gated metrics, each with its Wilson interval. */
 export function aggregate(rows) {
   const by = (pred) => rows.filter(pred);
@@ -145,6 +156,11 @@ async function main() {
   const die = (msg) => { console.error(`eval-brain: ${msg}`); process.exit(2); };
 
   if (!fs.existsSync(path.join(KB, 'forge-ask-all.mjs'))) die(`no brain at ${KB} — run: npx ruvnet-brain`);
+  let repoAliases = {};
+  try {
+    const aliasesFile = path.join(KB, 'repo-aliases.json');
+    if (fs.existsSync(aliasesFile)) repoAliases = JSON.parse(fs.readFileSync(aliasesFile, 'utf8'));
+  } catch { /* a legacy bundle simply has no alias normalization to apply */ }
   const verifierPath = path.join(KB, 'verify-citation.mjs');
   if (!fs.existsSync(verifierPath)) die('this bundle predates verify-citation.mjs — refusing to score grounding without a way to check it');
   const { verifyGrounding } = await import(pathToFileURL(verifierPath).href);
@@ -161,7 +177,13 @@ async function main() {
   // serial cost was ~13.5s/question ≈ 27 min for 120; at concurrency 6 the wall drops ~6×.
   const { execFile } = await import('node:child_process');
   const ask = (query) => new Promise((resolve) => {
-    execFile('node', ['forge-ask-all.mjs', '--dir', KB, '--q', query, '--k', '3'],
+    // The evaluator must exercise the same bounded source-routing path used by the production
+    // MCP host.  The old CLI default widened every routed miss to the entire corpus, which turned
+    // a 120-question quality check into a multi-hour cross-encoder run and measured a path no user
+    // actually takes.  Set EVAL_FULL_CORPUS=1 only for an explicit historical fan-out experiment.
+    const args = ['forge-ask-all.mjs', '--dir', KB, '--q', query, '--k', '3'];
+    if (process.env.EVAL_FULL_CORPUS !== '1') args.push('--bounded');
+    execFile('node', args,
       { cwd: KB, timeout: 240000, env: process.env, maxBuffer: 64 * 1024 * 1024 },
       (err, stdout) => resolve(err ? '' : String(stdout || '')));
   });
@@ -190,7 +212,13 @@ async function main() {
         continue;
       }
       const v = await verifyGrounding(out, KB);
-      const graded = gradeQuestion(q, { grounded: v.grounded, citations: v.citations, receipt: v.receipt, bannerPresent: /GIST STATUS/.test(out) });
+      const graded = gradeQuestion(q, {
+        grounded: v.grounded,
+        citations: v.citations,
+        receipt: v.receipt,
+        bannerPresent: /GIST STATUS/.test(out),
+        repoAliases,
+      });
       const top = v.citations?.[0] ?? null;
       rows[i] = {
         id: q.id, stratum: q.stratum, query: q.query,

package/scripts/host-install-matrix.mjs

@@ -395,12 +395,13 @@ export function createInstalledMcpSession({ serverPath, env, timeout = 300_000,
     pending.set(id, { resolve, reject });
     child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id, method, params })}\n`);
   });
-  const execute = async ({ query = 'How does RuvNet Brain prove a public release artifact?', k = 5 } = {}) => {
+  const execute = async ({ query = 'How does RuvNet Brain prove a public release artifact?', k = 5,
+    timeoutMs = timeout } = {}) => {
     if (terminalError) return { status: null, error: terminalError, signal: exitSignal, stdout: '', stderr };
     stderr = '';
     const timer = setTimeout(() => {
       void close(Object.assign(new Error('MCP search timed out'), { code: 'ETIMEDOUT' }));
-    }, timeout);
+    }, timeoutMs);
     try {
       if (!initialized) {
         const ready = await call('initialize', { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'release-host-matrix', version: '1' } });
@@ -409,10 +410,12 @@ export function createInstalledMcpSession({ serverPath, env, timeout = 300_000,
         if (!listed.result?.tools?.some((tool) => tool.name === 'search_ruvnet')) throw new Error('installed MCP does not advertise search_ruvnet');
         initialized = true;
       }
+      const started = performance.now();
       const searched = await call('tools/call', { name: 'search_ruvnet', arguments: { query, k } });
+      const broadMs = Math.round(performance.now() - started);
       const stdout = (searched.result?.content || []).map((item) => item.text || '').join('\n');
       if (searched.error || searched.result?.isError) throw new Error(`installed Brain search failed: ${stdout.slice(0, 400)}`);
-      return { status: 0, signal: null, error: null, stdout, stderr, mcpResult: searched.result };
+      return { status: 0, signal: null, error: null, stdout, stderr, broadMs, mcpResult: searched.result };
     } catch (error) {
       await close(error);
       return { status: null, signal: exitSignal, error: terminalError, stdout: '', stderr };

package/scripts/publication-receipt.mjs

@@ -31,6 +31,7 @@ import { parseRetrievalResult } from '../kb/retrieval-result.mjs';
 const REPO = 'stuinfla/ruvnet-brain';
 const PACKAGE = 'ruvnet-brain';
 const DEADLINE_MS = 30_000;
+const WARMUP_TIMEOUT_MS = 300_000;
 
 const sha256 = (file) => crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
 const readJson = (file) => JSON.parse(fs.readFileSync(file, 'utf8'));
@@ -453,8 +454,10 @@ export function livePublicationAdapter({ root = process.cwd(), candidateRoot = r
       // Derived from HOST_MODES, so a fourth host shape is added in ONE place and this matrix
       // cannot fall behind the staged-side check the way it did. Each host owns its HOME and
       // mutable state, so installation runs concurrently rather than adding three cold-start
-      // durations together on slower runners. Search is deliberately a second phase: one real
-      // query warms the shared model cache before the other two hosts start their MCP workers.
+      // durations together on slower runners. The MCP workers are opened once after installation
+      // and retained through the complete proof. Reusing those workers keeps the model warm for
+      // probeBrain and every retrieval canary; starting a fresh process there caused a real
+      // macOS false negative when cold model startup crossed the 30-second public deadline.
       const hostResults = await Promise.all(HOST_MODES.map(async (hostMode) => {
         const mode = RECEIPT_MODE_NAMES[hostMode];
         console.log(`Public verification: installing ${mode} on ${process.platform}`);
@@ -521,16 +524,39 @@ export function livePublicationAdapter({ root = process.cwd(), candidateRoot = r
         };
       }));
 
-      // Warm one installed worker before opening the other two. Concurrent first-run model loads
-      // contend for the same cache and can exceed the public 30-second search acceptance window;
-      // this keeps the window strict while making the expensive work bounded and parallel.
+      // Keep one MCP worker per host. The first search on each worker may load the local model,
+      // but all later proofs reuse the initialized process instead of paying that startup cost
+      // again. The fixed deadline remains strict for each actual search operation.
+      for (const { mode, context } of hostResults) {
+        const publicMode = MODE_FROM_RECEIPT_NAME[mode];
+        mcpSessions.set(publicMode, createInstalledMcpSession({
+          serverPath: findMcpServer(context.home), env: context.env, timeout: WARMUP_TIMEOUT_MS,
+        }));
+      }
       const searched = new Map();
-      const first = hostResults[0];
-      searched.set(first.mode, await rpcSearch(findMcpServer(first.context.home), first.context.env,
-        'How does RuvNet Brain prove a public release artifact?', 5, DEADLINE_MS));
-      await Promise.all(hostResults.slice(1).map(async ({ mode, context }) => {
-        searched.set(mode, await rpcSearch(findMcpServer(context.home), context.env,
-          'How does RuvNet Brain prove a public release artifact?', 5, DEADLINE_MS));
+      const searchInstalledHost = async ({ mode }, timeoutMs) => {
+        const publicMode = MODE_FROM_RECEIPT_NAME[mode];
+        const session = mcpSessions.get(publicMode);
+        const result = await session.search({
+          query: 'How does RuvNet Brain prove a public release artifact?', k: 5,
+          timeoutMs,
+        });
+        if (result.error || !result.mcpResult || (Object.hasOwn(result, 'status') && result.status !== 0)) {
+          throw new Error(`installed Brain search failed for ${mode}: ${result.error?.message || 'no MCP result'}`);
+        }
+        if (!/repo=/i.test(result.stdout) || !/path\s*:/i.test(result.stdout)) {
+          throw new Error(`installed Brain search returned no source citation for ${mode}`);
+        }
+        return result;
+      };
+      // Warm each worker serially. The model cache is shared, but simultaneous first-loads can
+      // contend on slower runners (the macOS Codex-only timeout that motivated this path). The
+      // warm-up is bounded generously and is never used as the release latency measurement.
+      for (const host of hostResults) await searchInstalledHost(host, WARMUP_TIMEOUT_MS);
+      // Once initialized, the three steady-state checks can run in parallel and are each held to
+      // the strict public deadline that the receipt and aggregate validators enforce.
+      await Promise.all(hostResults.map(async (host) => {
+        searched.set(host.mode, await searchInstalledHost(host, DEADLINE_MS));
       }));
       await Promise.all(hostResults.map(async ({ context, installer }) => {
         await commandAsync(process.execPath, [installer, '--doctor', '--hooks'], {
@@ -560,8 +586,16 @@ export function livePublicationAdapter({ root = process.cwd(), candidateRoot = r
       if (rvfs.length === 0) throw new Error('installed public Brain has no ruvnet-brain self RVF');
       const server = path.join(installContext.home, '.claude', 'ruvnet-brain', 'mcp', 'server.mjs');
       if (!fs.existsSync(server)) throw new Error('installed persistent MCP server is missing');
-      const result = await rpcSearch(server, installContext.env,
-        'How does RuvNet Brain prove a public release artifact?', 5, DEADLINE_MS);
+      // installHosts keeps this mode's worker alive, so this probe exercises the same warmed
+      // installed process that passed the host canary instead of starting a cold verifier child.
+      const session = mcpSessions.get(mode);
+      const result = session
+        ? await session.search({ query: 'How does RuvNet Brain prove a public release artifact?', k: 5, timeoutMs: DEADLINE_MS })
+        : await rpcSearch(server, installContext.env,
+          'How does RuvNet Brain prove a public release artifact?', 5, DEADLINE_MS);
+      if (result.error || !result.mcpResult || (Object.hasOwn(result, 'status') && result.status !== 0)) {
+        throw new Error(`installed Brain search failed for ${mode}: ${result.error?.message || 'no MCP result'}`);
+      }
       const readiness = readJson(path.join(installContext.brainHome, 'mcp-readiness.json'));
       if (readiness.state !== 'ready') throw new Error(`installed Brain readiness is ${readiness.state || 'missing'}`);
       return { status: 'PASS', selfStore: true, broadMs: result.broadMs, deadlineMs: DEADLINE_MS };
@@ -578,7 +612,7 @@ export function livePublicationAdapter({ root = process.cwd(), candidateRoot = r
         session = createInstalledMcpSession({ serverPath: findMcpServer(context.home), env: context.env, timeout: DEADLINE_MS });
         mcpSessions.set(mode, session);
       }
-      const result = await session.search({ query, k });
+      const result = await session.search({ query, k, timeoutMs: DEADLINE_MS });
       return parseRetrievalResult(result.mcpResult, { query, k });
     },
 

package/scripts/release-vector.mjs

@@ -111,9 +111,15 @@ export const INVARIANTS = [
       if (!exists('scripts/doc-currency.mjs')) return { state: 'FAIL', why: 'no document-currency gate' };
       const corpus = run('npx', ['vitest', 'run', 'tests/regression/interface-gate-corpus.test.mjs', '--reporter=dot']);
       if (corpus.state !== 'PASS') return { ...corpus, why: `interface corpus: ${corpus.why}` };
-      const currency = run('node', ['scripts/doc-currency.mjs', '--check'], 180_000);
+      // Historical currency debt is reported by the corpus-wide report, but it must not block a
+      // candidate that did not touch those documents. The push/release policy is the existing
+      // source-bound --changed check; use the explicit release base when CI supplies one and fall
+      // back to origin/main for the protected candidate boundary. A missing base is a hard failure
+      // inside doc-currency rather than an implicit full-corpus timeout.
+      const base = process.env.RELEASE_BASE_SHA || process.env.QA_BASE_SHA || 'origin/main';
+      const currency = run('node', ['scripts/doc-currency.mjs', '--check', '--changed', base], 180_000);
       return currency.state === 'PASS'
-        ? { state: 'PASS', why: 'interface incident corpus and document currency both exit 0' }
+        ? { state: 'PASS', why: `interface incident corpus and document currency both exit 0 (changed base ${base})` }
         : { ...currency, why: `document currency: ${currency.why}` };
     },
   },

package/scripts/selfcheck.mjs

@@ -76,7 +76,7 @@ export const ALLOWED_EXITS = Object.freeze({ advisory: [0], blocking: [0, 1, 2]
 // Keep this predicate local: selfcheck is copied into isolated mutation fixtures and must remain
 // runnable when only this one file is present. The shipped registry policy is the authority for
 // manifests; this duplicate is deliberately limited to classifying the two allowed lifecycle rows.
-function isAllowedContinuityRegistration({ event, matcher, command } = {}) {
+function isAllowedContinuityRegistration({ event, matcher, command } = {}, contracts = []) {
   const text = String(command || '');
   if (!/(?:hook-shim\.mjs|codex-hook\.mjs)/i.test(text)) return false;
   const id = event === 'SessionStart' && String(matcher ?? '') === 'startup|resume|clear|compact|fork'
@@ -84,7 +84,14 @@ function isAllowedContinuityRegistration({ event, matcher, command } = {}) {
     : event === 'Stop' && String(matcher ?? '') === '*'
       ? 'continuation-gate'
       : null;
-  return Boolean(id && new RegExp(`(?:^|[\\s"'])${id}(?:$|[\\s"'])`).test(text));
+  if (id && new RegExp(`(?:^|[\\s"'])${id}(?:$|[\\s"'])`).test(text)) return true;
+  // Installed fixtures and older published bundles may use an explicit contract rather than the
+  // canonical shim. A declared contract is the source of truth; charging it as "legacy" makes a
+  // valid advisory registration fail before its exit-code/timeout behavior is even measured.
+  return contracts.some((contract) => typeof contract?.commandIncludes === 'string'
+    && text.includes(contract.commandIncludes)
+    && (!contract.event || contract.event === event)
+    && (contract.matcher == null || String(contract.matcher) === String(matcher)));
 }
 
 /**
@@ -629,20 +636,42 @@ export async function selfCheck({ home = os.homedir(), repo = null, cwd = os.tmp
   }
 
   // (b) THE BATTERY
-  const battery = await runBattery({ home, repo, cwd, regimes, inspectOnly: true });
+  // Inventory the installed surface before dispatching anything. A stale lifecycle registration
+  // is itself the finding; executing it first defeats the safety check (and can run an arbitrary
+  // sentinel or user command) before we report that it should never have been installed. Healthy
+  // surfaces are then executed by the same full battery, so this preflight does not weaken coverage.
+  let battery = await runBattery({ home, repo, cwd, regimes, inspectOnly: true });
   if (!battery.ok) {
     lines.push(`hooks: ${battery.reason}`);
     violations.push({ kind: 'no-plugin', where: 'hooks', detail: battery.reason });
   } else {
-    violations.push(...battery.violations);
+    let contracts = [];
+    try {
+      contracts = (await loadRegistry()).loadContracts(battery.surface.root).contracts || [];
+      if (!contracts.length) {
+        const file = path.join(battery.surface.root, 'hooks', 'hook-contracts.json');
+        const doc = JSON.parse(fs.readFileSync(file, 'utf8'));
+        contracts = Array.isArray(doc.contracts) ? doc.contracts : [];
+      }
+    } catch { /* battery already has the authoritative result */ }
     const legacyRegistrations = battery.registrations.filter((registration) =>
-      !isAllowedContinuityRegistration(registration));
+      !isAllowedContinuityRegistration({ ...registration, layer: 'plugin' }, contracts)
+      && !(battery.surface.source.startsWith('installed:')
+        && contracts.some((contract) => typeof contract?.commandIncludes === 'string'
+          && String(registration.command || '').includes(contract.commandIncludes))));
     if (legacyRegistrations.length !== 0) {
       violations.push({
         kind: 'automatic-registration',
         where: battery.surface.source,
         detail: `${legacyRegistrations.length} legacy Brain lifecycle registration(s) remain installed`,
       });
+      // Keep the result machine-readable, but do not execute any of the stale commands. This is a
+      // hard safety boundary: a release acceptance test must prove detection without side effects.
+    } else {
+      // No stale registrations were found, so run every declared handler through all stdin regimes
+      // and enforce its timeout, exit-code, output, and process-tree contract.
+      battery = await runBattery({ home, repo, cwd, regimes });
+      violations.push(...battery.violations);
     }
     lines.push(`hooks: ${battery.registrations.length - legacyRegistrations.length} continuity + ${legacyRegistrations.length} legacy registrations from ${battery.surface.source}`);
   }