ruvnet-brain 4.3.17 → 4.3.18

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.18 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.3.18-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.18",
   "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.18",
   "author": {
     "name": "Stuart Kerr"
   },

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

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.3.17",
+  "version": "4.3.18",
   "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/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}`);
   }