ruvnet-brain 4.5.8 → 4.5.9

package/README.md

@@ -7,7 +7,7 @@ Created: 2026-06-29 22:36:38 EDT
 
 # 🧠 RuvNet Brain
 
-### 🧠 RuvNet Brain — [![RuvNet Brain version 4.5.8 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.5.8-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.5.9 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.5.9-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/bin/install.mjs

@@ -461,7 +461,9 @@ function resolveCacheDir() {
   );
   info(`brain dir: ${c.bold(cacheDir)}`);
   if (custom) info(`(from your RUVNET_BRAIN_KB override)`);
-  fs.mkdirSync(cacheDir, { recursive: true });
+  // Activation creates the KB from a validated stage. A placeholder here becomes a false prior
+  // generation, which the cleanup proof correctly retains because it has no SOURCE.json.
+  fs.mkdirSync(path.dirname(cacheDir), { recursive: true });
   return { cacheDir, isCustom: Boolean(custom) };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.5.8",
+  "version": "4.5.9",
   "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.5.8",
+  "version": "4.5.9",
   "author": {
     "name": "Stuart Kerr"
   },

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

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

package/plugin/scripts/advocacy-catalog.mjs

@@ -145,6 +145,7 @@ export const INTENTS = Object.freeze([
     fit: 'the request is to retrieve by meaning rather than by literal match',
     cues: Object.freeze([
       /\bby meaning\b/,
+      /^(?:please\s+)?(?:search|retrieve|find)\s+(?:these|those|my|our|the)\s+(?:docs?|documents?|passages?|chunks?|notes?)\s+by meaning\b/,
       /\bsemantic(ally)?\s+(search|retriev|match|similar)/,
       /\b(instead of|rather than|not just|beyond)\s+(an?\s+)?(exact\s+)?(keywords?|string|substring|literal|grep)/,
       /\bvector\s+(search|database|db|store|index|embedding)/,

package/plugin/scripts/ground-before-write.sh

@@ -98,11 +98,10 @@ SKIP_RECENCY=0
 [ "${RUVNET_SKIP_GROUNDING_CHECK:-0}" = "1" ] && SKIP_RECENCY=1
 
 # This gate is a BLOCKING wall (the #1-failure preventer), so by deliberate design (ADR-0021, and
-# enforced by ground-before-write.test.mjs) it depends on NOTHING fragile — pure bash builtins, no
-# node/jq/python — and therefore cannot fail-open because a tool went missing. The #13 quote-truncation
-# that justified hook-input.mjs for design-wall does NOT bite here: the product-term scan below runs
-# over the RAW payload (untouched by field()), and the only parsed values are tool_name (Write/Edit —
-# no quotes) and file_path (a truncated path merely fails the extension check → exit 0, harmless).
+# enforced by ground-before-write.test.mjs) its default refusal depends on no JSON parser. The optional
+# inert-code exemption below can narrow a valid input; a missing helper or any uncertainty leaves the
+# raw product scan intact. The legacy field parser below selects only tool name and code-file path;
+# it never supplies the code text used by the optional projection.
 field() { local re="\"$1\"[[:space:]]*:[[:space:]]*\"([^\"]*)\""; [[ $INPUT =~ $re ]] && printf '%s' "${BASH_REMATCH[1]}"; }
 
 # Case-insensitive (4.5): Grok sends `write` / `search_replace`; a case-sensitive match allowed a Grok
@@ -134,8 +133,8 @@ shopt -s nocasematch 2>/dev/null || true
 STAMP_DIR="$HOME/.cache/ruvnet-brain/grounded"
 NOW=$(date +%s 2>/dev/null) || exit 0
 
-# Scan the WHOLE tool input (path + content + new_string) — where the code mentions the
-# product is where the hand-roll hides.
+# Scan raw product terms without a parser; the optional inert-text exemption below may narrow
+# this result, but missing dependencies cannot erase the raw refusal.
 MISSING=""
 SEEN=""
 for t in agentdb metaharness ruvector aidefence agentic-flow agentic-qe ruv-swarm rvf ruflo; do
@@ -156,10 +155,10 @@ done
 # PASSED: a term the model has never grounded is stopped by stage 1 and never reaches here.
 #
 # ── THE DEPENDENCY CONTRACT, AND WHY THIS DOES NOT BREAK IT ────────────────────────────────────
-# Everything above this line is pure bash builtins, by standing contract (ADR-0021, enforced by
-# ground-before-write.test.mjs): the recency wall is THE blocking wall, so it can never fail open
-# because a tool went missing. That contract is unchanged and still tested — the assertion now
-# reads the file UP TO THIS MARKER.
+# Everything above this marker remains pure bash: the recency wall computes a refusal without
+# node/jq/python (ADR-0021). The optional exemption below can only narrow that raw result after
+# proving an inert mention; absence or uncertainty retains it. The substance stage keeps its
+# separate, explicitly fail-open contradiction contract.
 #
 # The substance stage is different in kind and is allowed one dependency, node, because deciding
 # "does this write contradict the source the brain returned?" requires a real JSON parse of the
@@ -169,6 +168,23 @@ done
 # produce a refusal here is a detector that found a contradiction, which is ADR-055 §1.2's
 # "malfunction ≠ decision" applied to the one stage that has something to malfunction.
 # ═══════════════════════════════════════════════════════════════════════════════════════════════
+# Optional positive exemption (#373), only when a raw product mention exists. A missing helper,
+# node, empty output or lexical uncertainty leaves the pure-bash result unchanged. This stage
+# cannot manufacture a refusal and never changes the raw payload used by the substance wall.
+PROJECTION="$(dirname "${BASH_SOURCE[0]}")/grounding-code-projection.mjs"
+if [ -n "$SEEN" ] && [ -f "$PROJECTION" ] && command -v node >/dev/null 2>&1; then
+  PROJECTED=$(printf '%s' "$INPUT" | node "$PROJECTION" 2>/dev/null)
+  if [ "$?" = "0" ] && [ -n "$PROJECTED" ]; then
+    PROJECTED_MISSING=""; PROJECTED_SEEN=""
+    for t in $SEEN; do
+      [[ $PROJECTED == *"$t"* ]] || continue
+      PROJECTED_SEEN="$PROJECTED_SEEN$t "
+      [[ " $MISSING" == *" $t "* ]] && PROJECTED_MISSING="$PROJECTED_MISSING$t "
+    done
+    MISSING="$PROJECTED_MISSING"; SEEN="$PROJECTED_SEEN"
+  fi
+fi
+
 if [ -z "$MISSING" ] || [ "$SKIP_RECENCY" = "1" ]; then
   [ -n "$SEEN" ] || exit 0
   SUBSTANCE="$(dirname "${BASH_SOURCE[0]}")/grounding-substance.mjs"

package/plugin/scripts/grounding-code-projection.mjs

@@ -0,0 +1,85 @@
+// Optional conservative #373 projection. Uncertainty keeps the original raw bash gate.
+// Keep executable strings and paths: mentioning a product in code still requires grounding.
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+export function codeWithoutInertText(source, python = false) {
+  if (/\r(?!\n)|[\u2028\u2029]/.test(source)) throw new Error('Unsupported line boundary');
+  // Template interpolation and Python f-string expressions need a parser, not a guessed lexer.
+  if ((!python && source.includes('`')) || (python && /(?:^|[^\w])(?:fr|rf|f)["']/i.test(source))) throw new Error('Interpolation requires original scan');
+  if (python) {
+    // A different source decoder can turn apparent comments into executable statements.
+    for (const line of source.split(/\r?\n/).slice(0, 2)) {
+      const cookie = line.match(/^[ \t\f]*#.*?coding[=:][ \t]*([^ \t\r\n]+)/i);
+      if (cookie && !/^utf[-_]?8$/i.test(cookie[1])) throw new Error('Unsupported source encoding');
+    }
+    if (/\\\r?\n/.test(source)) throw new Error('Continuation requires original scan');
+  }
+  let out = ''; let i = 0;
+  while (i < source.length) {
+    const c = source[i]; const pair = source.slice(i, i + 2);
+    if ((python && c === '#') || (!python && pair === '//')) {
+      const end = source.indexOf('\n', i); i = end < 0 ? source.length : end; continue;
+    }
+    if (!python && pair === '/*') {
+      const end = source.indexOf('*/', i + 2); if (end < 0) throw new Error('Incomplete comment');
+      out += ' '; i = end + 2; continue;
+    }
+    if (c === '"' || c === "'" || (!python && c === '`')) {
+      const start = i; const triple = python && source.slice(i, i + 3) === c.repeat(3);
+      const delimiter = triple ? c.repeat(3) : c;
+      i += delimiter.length;
+      let closed = false;
+      while (i < source.length) {
+        if (source[i] === '\\') { i += 2; continue; }
+        if (source.slice(i, i + delimiter.length) === delimiter) { i += delimiter.length; closed = true; break; }
+        if (!triple && c !== '`' && /[\r\n]/.test(source[i])) throw new Error('Incomplete string');
+        i++;
+      }
+      if (!closed) throw new Error('Incomplete string');
+      // Exempt only a leading module docstring before any executable text. Standalone-looking
+      // literals inside functions, open expressions or control flow retain the original scan.
+      const before = source.slice(source.lastIndexOf('\n', start - 1) + 1, start);
+      const endOfLine = source.indexOf('\n', i); const after = source.slice(i, endOfLine < 0 ? source.length : endOfLine);
+      const inert = triple && out.trim() === '' && !/\b(?:exec|eval|compile|__doc__)\b/.test(source) && /^[ \t]*$/.test(before) && /^[ \t\r]*(?:#.*)?$/.test(after);
+      out += inert ? ' ' : source.slice(start, i); continue;
+    }
+    // Regex literals, heredocs, language-specific nested comments etc. are not guessed.
+    if (!python && c === '/') throw new Error('Ambiguous slash');
+    if (!python && pair === '<' + '<') throw new Error('Unsupported heredoc');
+    out += c; i++;
+  }
+  return out;
+}
+
+export function projectGroundingInput(raw) {
+  const event = JSON.parse(raw); const input = event.tool_input ?? event.toolInput;
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw new Error('Unknown write input');
+  const file = input.file_path; if (typeof file !== 'string') throw new Error('Unknown path');
+  // Limited lexical scope; other languages retain their existing strict gate.
+  if (!/\.(?:py|[cm]?js|jsx|ts|tsx)$/.test(file)) throw new Error('Unsupported language');
+  // Partial edits have no enclosing lexical context. Only complete Write or a verified
+  // single Add File patch may receive an exemption; never reconstruct user files here.
+  const tool = event.tool_name ?? event.toolName;
+  let code;
+  if (tool === 'Write' && typeof input.content === 'string' && !Object.hasOwn(input, 'edits')) {
+    code = input.content;
+  } else if (tool === 'Edit' && typeof input.new_string === 'string' && input.new_string.startsWith('*** Begin Patch')) {
+    const lines = input.new_string.trimEnd().split(/\r?\n/);
+    if (lines[0] !== '*** Begin Patch' || lines[1] !== `*** Add File: ${file}`
+      || lines.at(-1) !== '*** End Patch' || !lines.slice(2, -1).every((line) => line.startsWith('+'))) {
+      throw new Error('Ambiguous patch');
+    }
+    code = lines.slice(2, -1).map((line) => line.slice(1)).join('\n');
+  } else throw new Error('Partial or unknown write context');
+  const projectedCode = codeWithoutInertText(code, file.endsWith('.py'));
+  // Never exempt a product-owned path. Preserve managed-store paths even without a product name.
+  const projection = `${file}\n${projectedCode}`;
+  if (/\.swarm|(?:agentdb-)?memory\.db|memory_entries/i.test(projection)) throw new Error('Managed memory indicators need original scan');
+  return projection;
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  try { process.stdout.write(projectGroundingInput(fs.readFileSync(0, 'utf8'))); }
+  catch { process.exitCode = 1; } // A failed exemption leaves the original guard in force.
+}

package/scripts/release-qualification-contract.mjs

@@ -1,6 +1,15 @@
 // Reviewed stabilization release boundaries. Legacy tests remain developer diagnostics.
 export const RELEASE_REQUIREMENTS = Object.freeze({
   "source": [
+    {
+      "id": "bounded-advocacy-and-write-grounding",
+      "reason": "Explicit document meaning requests retain corroboration; literal searches stay silent; POSIX complete-write exemptions preserve executable and managed-store grounding",
+      "files": ["tests/unit/advocacy-route.test.mjs", "tests/unit/advocacy-catalog.test.mjs", "tests/unit/card-lane.test.mjs"],
+      "platformFiles": {
+        "linux": ["tests/unit/advocacy-route-budget.test.mjs", "tests/unit/ground-before-write.test.mjs", "tests/unit/grounding-code-projection.test.mjs"],
+        "macos": ["tests/unit/advocacy-route-budget.test.mjs", "tests/unit/ground-before-write.test.mjs", "tests/unit/grounding-code-projection.test.mjs"]
+      }
+    },
     {
       "id": "owned-startup-execution-evidence",
       "reason": "Opt-in native execution and private stage diagnostics bind released source and preserve unknown convergence and incomplete cleanup boundaries",