ruvnet-brain 4.3.38 → 4.3.39

package/README.md

@@ -7,7 +7,7 @@ Created: 2026-06-29 22:36:38 EDT
 
 # 🧠 RuvNet Brain
 
-### 🧠 RuvNet Brain — [![RuvNet Brain version 4.3.38 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.3.38-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.39 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.3.39-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.**
 
@@ -562,7 +562,7 @@ node forge-ask-all.mjs --dir . --q "How does RuVector implement HNSW vector sear
 
 This project versions in the open (see the live badge up top for the exact plugin version; the downloadable knowledge bundle is a separate track) — we don't claim “done,” “complete,” or “zero hallucinations.” Where it stands:
 
-- ✅ **The grounding brain is real and proven** — 199 public stores · 161,283 public source chunks, dual embeddings, cross-encoder rerank, plugin (MCP tool + explicit skills; automatic hooks retired), all re-runnable.
+- ✅ **The grounding brain is real and proven** — 199 public stores · 161,322 public source chunks, dual embeddings, cross-encoder rerank, plugin (MCP tool + explicit skills; automatic hooks retired), all re-runnable.
 - ✅ **Code-level depth** — the code-rich repos are indexed to full function bodies; “how is it implemented?” returns the implementation. Verified in the shipped bundle (clean-room 3/3).
 - ✅ **Routing holds** — named 47/48, described 26/28, scenario 7/8; behavioral L1–L3 all pass (**L4 downgraded — it measures that the brain spoke, not that anything listened**); private stores fenced out of the public bundle (zero-leak verified).
 - ⚠️ **Two routing residuals** (above) — surfaced, not hidden.

package/kb/forge-update.mjs

@@ -1073,6 +1073,23 @@ function writeSnapshotReceipt(backupPath, { state, reason = null, recoveryComman
  *
  * @returns {{removed: string[], kept: [string, string][], freed: number}}
  */
+/**
+ * WHY a guard run failed. forge-guard prints its `[FAIL] ...` lines to STDOUT, and execFileSync puts only
+ * STDERR in error.message, so a refused store used to read "Command failed: node .../forge-guard.mjs --name X"
+ * with the cause dropped (measured 2026-09-30: the customer canary refused a generation and its log did not
+ * say why). Keep the command line, then append the guard's own FAIL lines.
+ */
+export function describeGuardFailure(error) {
+  const text = (value) => (value == null ? '' : Buffer.isBuffer(value) ? value.toString('utf8') : String(value));
+  const fails = `${text(error?.stdout)}\n${text(error?.stderr)}`.split('\n')
+    .map((line) => line.trim()).filter((line) => /\[FAIL\]|Error:/.test(line));
+  // Keep the WHOLE message: execFileSync appends the child's stderr on the lines after the command line.
+  const message = String(error?.message || error);
+  const extra = fails.filter((line) => !message.includes(line));
+  const cause = extra.length ? ` -- ${extra.join(' | ').slice(0, 800)}` : '';
+  return `${message.slice(0, 1600)}${cause}`;
+}
+
 export function reclaimBackups({
   kbDir,
   backupsMade = [],
@@ -1694,7 +1711,7 @@ async function main() {
         if (phase === 'live') finalVerificationByStore.set(local.kbName, verified);
       }
       return { valid: true, failures: [] };
-    } catch (error) { return { valid: false, failures: [`forge-guard failed: ${error.message}`] }; }
+    } catch (error) { return { valid: false, failures: [`forge-guard failed: ${describeGuardFailure(error)}`] }; }
   };
   let transaction;
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.3.38",
+  "version": "4.3.39",
   "description": "One-command installer for RuvNet Brain \u2014 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 a UserPromptSubmit retrieve-and-inject grounding hook and a PreToolUse write gate that refuses ungrounded rUv-product code until search_ruvnet has been consulted (ADR-0012 / ADR-067).",
-  "version": "4.3.38",
+  "version": "4.3.39",
   "author": {
     "name": "Stuart Kerr"
   },

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

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

package/plugin/hooks/codex-hooks.json

@@ -65,8 +65,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node -e \"const f=require('node:fs'),o=require('node:os'),p=require('node:path'),c=require('node:child_process'),d=process.env.CODEX_HOME||p.join(o.homedir(),'.codex'),b=process.env.RUVNET_BRAIN_HOME||p.join(p.dirname(d),'.cache','ruvnet-brain'),w=p.join(b,'codex-hook.mjs');let s;try{s=f.statSync(w)}catch{}if(!s?.isFile())process.exit(0);const r=c.spawnSync(process.execPath,[w,...process.argv.slice(2)],{stdio:['inherit','pipe','pipe'],encoding:'utf8',env:process.env,timeout:Number(process.argv[1]),killSignal:'SIGKILL'});if(r.status===0||r.status===2){if(r.stdout)process.stdout.write(r.stdout);if(r.stderr)process.stderr.write(r.stderr)}process.exit(r.status===2?2:0)\" 2500 unprompted-speech UserPromptSubmit",
-            "timeout": 3
+            "command": "node -e \"const f=require('node:fs'),o=require('node:os'),p=require('node:path'),c=require('node:child_process'),d=process.env.CODEX_HOME||p.join(o.homedir(),'.codex'),b=process.env.RUVNET_BRAIN_HOME||p.join(p.dirname(d),'.cache','ruvnet-brain'),w=p.join(b,'codex-hook.mjs');let s;try{s=f.statSync(w)}catch{}if(!s?.isFile())process.exit(0);const r=c.spawnSync(process.execPath,[w,...process.argv.slice(2)],{stdio:['inherit','pipe','pipe'],encoding:'utf8',env:process.env,timeout:Number(process.argv[1]),killSignal:'SIGKILL'});if(r.status===0||r.status===2){if(r.stdout)process.stdout.write(r.stdout);if(r.stderr)process.stderr.write(r.stderr)}process.exit(r.status===2?2:0)\" 9000 unprompted-speech UserPromptSubmit",
+            "timeout": 10
           },
           {
             "type": "command",
@@ -75,8 +75,8 @@
           },
           {
             "type": "command",
-            "command": "node -e \"const f=require('node:fs'),o=require('node:os'),p=require('node:path'),c=require('node:child_process'),d=process.env.CODEX_HOME||p.join(o.homedir(),'.codex'),b=process.env.RUVNET_BRAIN_HOME||p.join(p.dirname(d),'.cache','ruvnet-brain'),w=p.join(b,'codex-hook.mjs');let s;try{s=f.statSync(w)}catch{}if(!s?.isFile())process.exit(0);const r=c.spawnSync(process.execPath,[w,...process.argv.slice(2)],{stdio:['inherit','pipe','pipe'],encoding:'utf8',env:process.env,timeout:Number(process.argv[1]),killSignal:'SIGKILL'});if(r.status===0||r.status===2){if(r.stdout)process.stdout.write(r.stdout);if(r.stderr)process.stderr.write(r.stderr)}process.exit(r.status===2?2:0)\" 1500 capacity-aware-parallel-work",
-            "timeout": 2
+            "command": "node -e \"const f=require('node:fs'),o=require('node:os'),p=require('node:path'),c=require('node:child_process'),d=process.env.CODEX_HOME||p.join(o.homedir(),'.codex'),b=process.env.RUVNET_BRAIN_HOME||p.join(p.dirname(d),'.cache','ruvnet-brain'),w=p.join(b,'codex-hook.mjs');let s;try{s=f.statSync(w)}catch{}if(!s?.isFile())process.exit(0);const r=c.spawnSync(process.execPath,[w,...process.argv.slice(2)],{stdio:['inherit','pipe','pipe'],encoding:'utf8',env:process.env,timeout:Number(process.argv[1]),killSignal:'SIGKILL'});if(r.status===0||r.status===2){if(r.stdout)process.stdout.write(r.stdout);if(r.stderr)process.stderr.write(r.stderr)}process.exit(r.status===2?2:0)\" 5500 capacity-aware-parallel-work",
+            "timeout": 6
           },
           {
             "type": "command",

package/plugin/hooks/hook-contracts.json

@@ -179,7 +179,7 @@
       "mode": "blocking",
       "offBehavior": "silence",
       "matcher": "*",
-      "timeout": 3
+      "timeout": 9
     },
     {
       "id": "continuation-gate",
@@ -250,7 +250,7 @@
       "mode": "advisory",
       "offBehavior": "run",
       "matcher": "*",
-      "timeout": 2
+      "timeout": 6
     },
     {
       "id": "decision-gate",

package/plugin/hooks/hooks.json

@@ -20,7 +20,7 @@
           {
             "type": "command",
             "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" unprompted-speech UserPromptSubmit",
-            "timeout": 3
+            "timeout": 9
           },
           {
             "type": "command",
@@ -30,7 +30,7 @@
           {
             "type": "command",
             "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" capacity-aware-parallel-work || true",
-            "timeout": 2
+            "timeout": 6
           },
           {
             "type": "command",

package/plugin/scripts/codex-hook-wrapper.mjs

@@ -69,6 +69,9 @@ function timeoutFor(hookId) {
   // tinguishable from a crash; 6000ms covers the gate's cap plus this chain's spawn overhead
   // (measured 773–1145ms end-to-end warm, so ~150–400ms of that is the wrapper/adapter/shim).
   if (hookId === 'decision-gate') return 6_000;
+  // Advisory capacity hook: 4 of 8 runs were killed at the old 2s host timeout on a loaded machine (measured
+  // 2026-09-30). Keep the wrapper's budget below the registration's own 5.5s so the wrapper, not the host, ends it.
+  if (hookId === 'capacity-aware-parallel-work') return 5_000;
   if (hookId === 'ground-ruvnet' || hookId === 'unprompted-speech' || hookId === 'continuation-gate') {
     return 8_500;
   }

package/scripts/approved-runtime.mjs

@@ -7,7 +7,7 @@
 // scripts/verify-bundle.mjs (:645) and keys/ruvnet-brain-signing.pub.pem (:648) — and the customer
 // updater extracts that archive straight into the user's Claude Code config. So an unattended corpus
 // promotion built at HEAD would ship whatever unreleased executable bytes happen to be on main that
-// night, to every installed client, with no owner approval anywhere in the path. That is a code
+// night, to every installed client, with no install-verified code release behind it. That is a code
 // release wearing a corpus release's clothes.
 //
 // The pin closes it by ENFORCED EQUALITY, not by a version string. Dual's correction is explicit:

package/scripts/corpus-canary.mjs

@@ -117,10 +117,13 @@ function coverageRows(file) {
 
 /**
  * Per-store freshness, judged from the generation's own sealed coverage (CORPUS-COVERAGE.json inside
- * the installed tree): the upstream observation must be under 48h old, no store whose upstream moved
- * may still carry the old commit, and every store whose upstream moved since the install's previous
- * generation must have been ingested inside the window. MISSING/INELIGIBLE rows are the coverage
- * validator's business (it already ran), not a freshness question.
+ * the installed tree): the upstream observation must be under 48h old, and no store may carry a commit
+ * other than the upstream commit observed then. Together those ARE the 48h guarantee. There is
+ * deliberately NO rule on a store's own ingestedAt: a store keeps the ingestion time of the last night
+ * its upstream moved (measured 2026-09-30: one generation holds ingestedAt from 2026-07-30 to
+ * 2026-09-30), so a "moved store must be ingested within 48h of now" rule would wrongly refuse a
+ * perfectly fresh generation about three nights after every code release.
+ * MISSING/INELIGIBLE rows are the coverage validator's business (it already ran), not a freshness question.
  */
 export function storeFreshness({ after, before = null, now }) {
   if (!after) return { ok: false, detail: 'CORPUS-COVERAGE.json is missing from the installed tree' };
@@ -131,7 +134,6 @@ export function storeFreshness({ after, before = null, now }) {
   if (age > FRESHNESS_LIMIT_MS || age < 0) problems.push(`upstream observed ${(age / 3_600_000).toFixed(1)}h ago (limit 48h)`);
   const priorCommit = new Map((before?.rows || []).map((row) => [row.key, row.artifact?.sourceCommit || null]));
   const stale = [];
-  const late = [];
   let moved = 0;
   for (const row of after.rows) {
     if (row.status === 'INELIGIBLE') continue;
@@ -139,17 +141,12 @@ export function storeFreshness({ after, before = null, now }) {
     const built = row.artifact?.sourceCommit || null;
     if (!upstream || !built) continue;
     if (upstream !== built) { stale.push(row.artifact?.store || row.key); continue; }
-    if (before && priorCommit.get(row.key) !== upstream) {
-      moved += 1;
-      const ingested = Date.parse(row.artifact?.ingestedAt);
-      if (!Number.isFinite(ingested) || now - ingested > FRESHNESS_LIMIT_MS) late.push(row.artifact?.store || row.key);
-    }
+    if (before && priorCommit.get(row.key) !== upstream) moved += 1;
   }
   if (stale.length) problems.push(`${stale.length} store(s) built from a commit older than their observed upstream: ${stale.slice(0, 10).join(', ')}`);
-  if (late.length) problems.push(`${late.length} moved store(s) ingested more than 48h ago: ${late.slice(0, 10).join(', ')}`);
   return problems.length
     ? { ok: false, detail: problems.join('; ') }
-    : { ok: true, detail: `observed ${(age / 3_600_000).toFixed(1)}h ago; ${after.rows.length} row(s), 0 stale; ${before ? `${moved} moved since the installed generation, all ingested <48h` : 'no prior coverage to diff against'}` };
+    : { ok: true, detail: `observed ${(age / 3_600_000).toFixed(1)}h ago; ${after.rows.length} row(s), 0 stale; ${before ? `${moved} moved since the installed generation, all at their observed upstream commit` : 'no prior coverage to diff against'}` };
 }
 
 /**

package/scripts/protected-release-invocation.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Local publication is deliberately impossible. The one publisher may mutate public channels only
-// when the reviewer-protected GitHub workflow carries a fully valid candidate seal into it.
+// when the branch-protected GitHub workflow carries a fully valid candidate seal into it.
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';

package/scripts/release.mjs

@@ -11,7 +11,7 @@
 // header called check-only "the DEFINITION OF DONE" and claimed it alone decided "shipped"; that was
 // never true and duplicated a second, drifting gate list alongside CI's real one). Publishing a
 // release — creating the GitHub Release, moving the npm dist-tag — happens ONLY inside the
-// reviewer-protected `protected-release.yml` workflow, against an exact-SHA CI-sealed candidate;
+// branch-protected `protected-release.yml` workflow, against an exact-SHA CI-sealed candidate;
 // `--publish` mode is that workflow's publisher (it validates the protected-invocation receipt before
 // doing anything and refuses outside it), never rebuilds or retests source, and treats the immutable
 // artifact as the evidence boundary. `--check` mode is a read-only LOCAL PREVIEW for a human on a dev
@@ -680,7 +680,7 @@ if (CORPUS_SEED) {
 console.log(`\n${c.b('RuvNet Brain — release / definition-of-done')} ${c.dim('· ' + (PUBLISH ? 'PUBLISH' : 'check-only') + ' · shipping ' + V())}\n`);
 
 // The local CLI remains useful as a read-only preflight, but publication authority lives only in
-// the reviewer-protected workflow. Validate the exact candidate receipt and artifact bytes before
+// the branch-protected workflow. Validate the exact candidate receipt and artifact bytes before
 // any command capable of pushing, tagging, releasing, or publishing can run.
 if (PUBLISH) {
   const protectedInvocation = validateProtectedPublishInvocation({ root: ROOT });
@@ -782,7 +782,7 @@ if (PUBLISH) {
     }
   }
   // ADR-0091 D6.6 — THE BACKWARD-MOVE RACE. Release QE sealed the corpus generation this bundle was
-  // built from; publication happens later, after owner approval. Clients always accept a code release
+  // built from; publication happens later, in the protected workflow. Clients always accept a code release
   // and drop their corpusGeneration marker when they install one (kb/forge-update.mjs), so publishing
   // a bundle built from generation G after G+1 already shipped rolls every user back one night.
   // Re-resolve with the SAME resolver, before any asset upload, and refuse on any difference -- or on

package/scripts/single-source-check.mjs

@@ -33,6 +33,8 @@ const HISTORY = /^(docs\/(adr|ddd|research|audits|reviews|qe)\/|CHANGELOG\.md$|P
 // kb/ is corpus content (primers/cards describing OTHER projects' own commands) and docs/issues/
 // are upstream bug reports quoting other configs — both are data, not instructions to this project.
 const instructions = tracked.filter((f) => /\.md$/.test(f) && !HISTORY.test(f) && !/^(kb|docs\/issues)\//.test(f));
+// Phrases that re-introduce a person as a release gate. Negated statements ("no human approval step") are filtered by the caller.
+const HUMAN_APPROVAL_STEP = /(owner|stuart'?s?|maintainer) (approves?|approval|click|must approve)\b[^.]*(deployment|release|publish|gate)|approves? the `?Production|hand (it|the work) over[^.]*click|required[- ]reviewers?\b|standing authori[sz]ation permits/i;
 const grepIn = (files, re) => files.flatMap((f) => read(f).split('\n')
   .map((l, i) => (re.test(l) ? `${f}:${i + 1}: ${l.trim().slice(0, 140)}` : null)).filter(Boolean));
 const none = (hits) => ({ ok: hits.length === 0, detail: hits.slice(0, 8).join('\n') || 'none' });
@@ -80,8 +82,10 @@ const checks = [
       return none(instructions.flatMap((f) => [...read(f).matchAll(/npm run ([a-z0-9:_-]+)/g)]
         .filter((m) => !scripts.has(m[1])).map((m) => `${f}: npm run ${m[1]}`)));
     } },
-  { id: 'B6', area: 'rules', scope: 'repo', title: 'No instruction grants standing authority to publish without the owner',
-    run: () => none(grepIn(instructions, /standing authori[sz]ation permits|no separate human reviewer click/i)) },
+  // The owner is not in the release loop (2026-09-30): the gates are machine gates, and no instruction may
+  // route a release through a person clicking in GitHub. B12 applies the same idea to the local CLAUDE.md/AGENTS.md.
+  { id: 'B6', area: 'rules', scope: 'repo', title: 'No instruction puts a human approval click (or a required reviewer) in the release path',
+    run: () => none(grepIn(instructions, HUMAN_APPROVAL_STEP).filter((l) => !/\bno (human|reviewer)\b|\bnever\b|\bnot asked\b/i.test(l))) },
   { id: 'B7', area: 'rules', scope: 'repo', title: 'Model IDs are selected only in their owner modules',
     run: () => {
       const re = /['"`](claude-(fable|opus|sonnet|haiku)-[0-9][a-z0-9.-]*|gpt-[0-9][a-z0-9.-]*)['"`]/;
@@ -127,7 +131,7 @@ const checks = [
   { id: 'B12', area: 'rules', scope: 'machine', title: 'The local (untracked) CLAUDE.md / AGENTS.md carry no contradicting instruction',
     run: () => {
       const main = path.join(HOME, 'Code/ruvnet-brain');
-      const bad = /npx (-y )?(@claude-flow|claude-flow|ruflo)\b|standing authori[sz]ation permits|no separate human reviewer click|npm run (build|dev|test:integration|test:coverage|test:security)\b|not direct Agent tool/i;
+      const bad = /npx (-y )?(@claude-flow|claude-flow|ruflo)\b|standing authori[sz]ation permits|owner (approves?|click)|Stuart's approval (of|in GitHub)|approves? the `?Production|hand (it|the work) over[^.]*click|npm run (build|dev|test:integration|test:coverage|test:security)\b|not direct Agent tool/i;
       return none(['CLAUDE.md', 'AGENTS.md'].flatMap((f) => readAbs(path.join(main, f)).split('\n')
         .map((l, i) => (bad.test(l) ? `${f}:${i + 1}: ${l.trim().slice(0, 120)}` : null)).filter(Boolean)));
     } },
@@ -157,11 +161,13 @@ const checks = [
     } },
   { id: 'C4', area: 'release', scope: 'machine', title: 'The corpus gist job has its authenticated token (RUVNET_GISTS_TOKEN)',
     run: () => { const r = spawnSync('gh', ['secret', 'list', '-R', 'stuinfla/ruvnet-brain'], { encoding: 'utf8' }); return { ok: /^RUVNET_GISTS_TOKEN\b/m.test(r.stdout), detail: r.stdout.split('\n').map((l) => l.split(/\s/)[0]).filter(Boolean).join(', ') }; } },
-  { id: 'C3', area: 'release', scope: 'machine', title: 'Publishing requires the owner: Production environment has a required reviewer',
+  { id: 'C3', area: 'release', scope: 'machine', title: 'The npm-scoped Production environment is a boundary: branch policy present, admins cannot bypass (no human reviewer is part of the design)',
     run: () => {
       const r = spawnSync('gh', ['api', 'repos/stuinfla/ruvnet-brain/environments', '-q',
-        '.environments[]|select(.name=="Production – ruvnet-brain")|[.protection_rules[]?|select(.type=="required_reviewers")]|length'], { encoding: 'utf8' });
-      return { ok: r.status === 0 && Number(r.stdout.trim()) > 0, detail: `required_reviewers rules: ${r.stdout.trim() || r.stderr.trim()}` };
+        '.environments[]|select(.name=="Production – ruvnet-brain")|[(.can_admins_bypass==false),([.protection_rules[]?|select(.type=="branch_policy")]|length)]|@json'], { encoding: 'utf8' });
+      let noBypass = false; let policies = 0;
+      try { [noBypass, policies] = JSON.parse(r.stdout.trim()); } catch { /* unreadable: falls through to fail */ }
+      return { ok: r.status === 0 && noBypass === true && policies > 0, detail: `can_admins_bypass=false: ${noBypass}; branch_policy rules: ${policies}${r.status === 0 ? '' : ` (${r.stderr.trim()})`}` };
     } },
 
   // D — one corpus / update path