ruvnet-brain 4.0.1 → 4.0.4

package/scripts/private-fence.mjs

@@ -0,0 +1,69 @@
+// private-fence.mjs — the fence that keeps private repos out of anything we ship (SEC-0010 #5).
+//
+// This logic used to live inline in build-concepts.mjs, executed at import time, and it called
+// process.exit(1) on failure. That made it literally untestable: importing the module to test the
+// fence would kill the test runner. So the highest-severity code in the repo — the thing standing
+// between a private cognitum store and a public 512MB release — had zero tests.
+//
+// Here the decisions are pure: they RETURN {ok, reason} and never exit. The caller (a build script)
+// owns the exit. Same contract as before, now assertable.
+//
+// FAIL-CLOSED is the whole point. Three ways to fail, all of which must refuse to build:
+//   1. the fence file is missing        (unless the caller explicitly allows a no-private fork)
+//   2. the fence file is corrupt        (a fence you can't read is not a fence)
+//   3. a private repo's topics file is corrupt (same reasoning, one level down)
+// Fail-OPEN already shipped once (QE-0011 security#1): an L2 article whose repo attribution was
+// unknown defaulted to 'ruvnet' and went out the door. Hence the second, slug-based layer below.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Read kb/PRIVATE-STORES.json into a lowercased Set of private repo names.
+ * `allowNoFence` is the documented ALLOW_NO_PRIVATE_FENCE=1 escape hatch for a fork with no private
+ * repos — the ONLY case where a missing fence is acceptable.
+ */
+export function loadPrivateFence(kbDir, { allowNoFence = false } = {}) {
+  const p = path.join(kbDir, 'PRIVATE-STORES.json');
+  if (!fs.existsSync(p)) {
+    if (allowNoFence) return { ok: true, privateSet: new Set(), reason: 'no-fence-allowed' };
+    return { ok: false, privateSet: null, reason: `private fence missing (${p})` };
+  }
+  try {
+    const j = JSON.parse(fs.readFileSync(p, 'utf8'));
+    if (!Array.isArray(j.privateStores)) throw new Error('no privateStores array');
+    return { ok: true, privateSet: new Set(j.privateStores.map((s) => String(s).toLowerCase())), reason: 'ok' };
+  } catch (e) {
+    return { ok: false, privateSet: null, reason: `PRIVATE-STORES.json unreadable/corrupt (${e.message})` };
+  }
+}
+
+/** Case-insensitive membership — "Seed", "SEED" and "seed" must all fence. */
+export const isPrivate = (privateSet, repo) => privateSet.has(String(repo).toLowerCase());
+
+/**
+ * Second layer: collect the SLUGS owned by private repos, by reading each one's l2-topics file.
+ * An absent topics file is normal (that repo has no L2 articles) — absence is not corruption.
+ * A present-but-corrupt one is corruption, and must abort the build.
+ */
+export function loadPrivateSlugs(kbDir, privateSet) {
+  const slugs = new Set();
+  for (const repo of privateSet) {
+    const tf = path.join(kbDir, `l2-topics.${repo}.json`);
+    if (!fs.existsSync(tf)) continue;
+    try {
+      for (const t of JSON.parse(fs.readFileSync(tf, 'utf8'))) if (t.slug) slugs.add(t.slug);
+    } catch (e) {
+      return { ok: false, slugs: null, reason: `private topics file ${tf} is corrupt (${e.message})` };
+    }
+  }
+  return { ok: true, slugs, reason: 'ok' };
+}
+
+/**
+ * THE decision. An L2 article is fenced when its repo is private OR its slug belongs to a private
+ * repo. The second clause is what catches the shipped bug: `slugRepo.get(slug) || 'ruvnet'` hands
+ * an unattributed article a PUBLIC repo name, so repo-based fencing alone would wave it through.
+ */
+export const shouldFenceL2 = ({ repo, slug }, privateSet, privateSlugs) =>
+  isPrivate(privateSet, repo) || privateSlugs.has(slug);

package/scripts/proactivity-metrics.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+// proactivity-metrics.mjs — ADR-041 detector-layer recall + false-alarm harness.
+//
+// Spawns the REAL scripts/capability-registry.mjs (a fresh child, so HOME=<scratch> redirects
+// os.homedir() at module load — capability-registry.mjs:60) against a ground-truth scratch machine, and
+// scores it against the manifest. It never imports the detector; it runs the real process and reads its
+// real JSON, so a bug anywhere in the probe path is in scope — which is the whole point (ADR-028's shipped
+// "26 hooks off" lies all lived in that probe path).
+//
+//   detector-recall      = cohort capabilities the detector reports 'off' on the DORMANT machine
+//                          ------------------------------------------------------------------------
+//                          cohort capabilities the manifest declares dormant            (target >= 0.80)
+//   detector-false-alarm = cohort capabilities the detector reports 'off' on the HEALTHY machine
+//                          (target = 0 — a verified-healthy machine must raise no dormancy flag)
+//
+// The registryPath argument exists so the mutation test can point this at a deliberately-broken copy and
+// watch the numbers move — the falsifiability ADR-041 demands (a harness that cannot fall on a broken
+// detector is not a measurement).
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { buildState, readManifest } from '../tests/helpers/ground-truth-machine.mjs';
+
+const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+export const REAL_REGISTRY = path.join(REPO, 'scripts', 'capability-registry.mjs');
+
+/** Run the real detector against a scratch machine; return { key: state } for every row it emitted. */
+export function runDetector(home, project, registryPath = REAL_REGISTRY) {
+  const res = spawnSync(process.execPath, [registryPath, '--json', '--project', project], {
+    env: { ...process.env, HOME: home },
+    encoding: 'utf8',
+    timeout: 60_000,
+  });
+  if (res.status !== 0 || !res.stdout) {
+    throw new Error(`detector exited ${res.status}; stderr: ${String(res.stderr).slice(0, 300)}`);
+  }
+  const rows = JSON.parse(res.stdout);
+  const out = {};
+  for (const r of rows) if (r && typeof r.key === 'string') out[r.key] = r.state;
+  return out;
+}
+
+/**
+ * Build both ground-truth machines, run the detector against each, and score. Returns the two headline
+ * numbers plus the per-capability detail (for a failing assertion to point at). Cleans up its scratch dirs.
+ */
+export function measure({ registryPath = REAL_REGISTRY } = {}) {
+  const manifest = readManifest();
+  const cohort = manifest.cohort;
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'gtm-'));
+  try {
+    const dormant = buildState('dormant', path.join(root, 'dormant'));
+    const healthy = buildState('healthy', path.join(root, 'healthy'));
+
+    const dormantSeen = runDetector(dormant.home, dormant.project, registryPath);
+    const healthySeen = runDetector(healthy.home, healthy.project, registryPath);
+
+    // Recall: of the cohort caps the manifest says are dormant, how many did the detector get RIGHT?
+    //
+    // BOTH LINES USED TO TEST `=== 'off'`, AND THAT MADE THIS HARNESS BLIND TO STATE.IDLE — the very
+    // state added on 2026-07-24 because "off" was too coarse. Two failures came from the one literal:
+    //
+    //   1. SILENT EXCLUSION. A capability the manifest declares `idle` was filtered out of the
+    //      denominator entirely, so adding one to the cohort moved no number and the harness reported
+    //      an unchanged, healthy-looking 1.00 while measuring strictly less than before. A metric that
+    //      quietly ignores what it cannot classify is worse than one that fails.
+    //   2. THE MUTANT SURVIVED. MEASURED: deleting learning-enable's staleness check — the exact bug
+    //      fixed hours earlier, where a learner holding 457 trajectories and quiet for 30 days reports
+    //      ON — left recall at 1.00 and the gate PASSING. The harness could not fall on the precise
+    //      defect the pillar exists to catch.
+    //
+    // EXACT MATCH, not merely "some dormant state", is the bar. A detector answering `off` for an idle
+    // capability HAS noticed the dormancy, but it is still wrong in the way that costs the user: OFF
+    // points at `turnOn`, which is how "turn this on" got printed beside 457 already-learned patterns.
+    // Distinguishing them is the entire reason IDLE was introduced, so the metric must require it.
+    const DORMANT_STATES = new Set(['off', 'idle']);
+    const dormantKeys = cohort.filter((k) => DORMANT_STATES.has(manifest.states.dormant[k]));
+    const recalled = dormantKeys.filter((k) => dormantSeen[k] === manifest.states.dormant[k]);
+    const recall = dormantKeys.length ? recalled.length / dormantKeys.length : 1;
+
+    // False alarm: of the cohort, how many did the detector call DORMANT on the HEALTHY machine?
+    // `idle` counts here too — telling a user that a working capability has gone quiet is the same
+    // broken promise as calling it off, and ADR-028 is explicit that one false alarm costs more trust
+    // than ten true ones earn.
+    const falseAlarms = cohort.filter((k) => DORMANT_STATES.has(healthySeen[k]));
+
+    return {
+      recall,
+      falseAlarmCount: falseAlarms.length,
+      cohort,
+      dormantSeen: Object.fromEntries(cohort.map((k) => [k, dormantSeen[k]])),
+      healthySeen: Object.fromEntries(cohort.map((k) => [k, healthySeen[k]])),
+      // DERIVED from `recalled`, never restated. It used to carry its own `!== 'off'` predicate, and
+      // when the recall rule above was corrected for STATE.IDLE this line kept the old one — so the
+      // CLI printed "PASS — recall 1.00" while the test reading missedDormant on the same run saw a
+      // miss. Two independent definitions of one fact will always drift; the reported number and the
+      // list explaining it must come from the same comparison or one of them is lying.
+      missedDormant: dormantKeys.filter((k) => !recalled.includes(k)),
+      falseAlarms,
+    };
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+const invokedDirectly = process.argv[1] && path.resolve(process.argv[1]).endsWith('proactivity-metrics.mjs');
+if (invokedDirectly) {
+  const m = measure();
+  console.log(JSON.stringify({ recall: m.recall, falseAlarmCount: m.falseAlarmCount,
+    dormant: m.dormantSeen, healthy: m.healthySeen }, null, 2));
+  const ok = m.recall >= 0.80 && m.falseAlarmCount === 0;
+  console.log(ok ? `\nPASS — recall ${m.recall.toFixed(2)} (>=0.80), false-alarm ${m.falseAlarmCount} (=0)`
+    : `\nFAIL — recall ${m.recall.toFixed(2)}, false-alarm ${m.falseAlarmCount}; missed=${JSON.stringify(m.missedDormant)} falseAlarms=${JSON.stringify(m.falseAlarms)}`);
+  process.exit(ok ? 0 : 1);
+}

package/scripts/proof-questions.json

@@ -0,0 +1,56 @@
+[
+  { "set": "tuned", "query": "Can ruflo orchestrate agent swarms?", "expectRepo": ["ruflo", "concepts"], "minRelevance": -3 },
+  { "set": "tuned", "query": "Does RuVector use HNSW for vector search?", "expectRepo": ["ruvector", "concepts"], "minRelevance": -3 },
+  { "set": "tuned", "query": "Can AgentDB run Cypher graph queries over agent memory?", "expectRepo": ["agentdb", "concepts"], "minRelevance": -3 },
+  { "set": "tuned", "query": "Can agentic-flow switch between alternative low-cost AI models in Claude Code?", "expectRepo": ["agentic-flow", "concepts"], "minRelevance": -3 },
+  { "set": "tuned", "query": "What phases does the SPARC methodology define?", "expectRepo": ["sparc", "concepts", "ruflo"], "minRelevance": -3 },
+  { "set": "tuned", "query": "Does QuDAG provide quantum-resistant DAG-based anonymous communication?", "expectRepo": ["qudag", "concepts"], "minRelevance": -3 },
+  { "set": "tuned", "query": "Can RuLake cache vector queries in front of a vector store?", "expectRepo": ["rulake", "concepts"], "minRelevance": -3 },
+  { "set": "tuned", "query": "Does SAFLA implement a self-aware feedback loop?", "expectRepo": ["safla", "concepts"], "minRelevance": -3 },
+  { "set": "tuned", "query": "What is agent-harness-generator (metaharness) and what does it scaffold?", "expectRepo": ["metaharness", "concepts"], "minRelevance": -3 },
+
+  { "set": "held-out", "query": "How does RuVector store and search vectors on disk?", "expectRepo": ["ruvector", "concepts"], "minRelevance": -3 },
+  { "set": "held-out", "query": "What graph-database features does AgentDB provide?", "expectRepo": ["agentdb", "concepts"], "minRelevance": -3 },
+  { "set": "held-out", "query": "Is ruv-FANN a fast neural network library written in Rust?", "expectRepo": ["ruv-fann", "concepts"], "minRelevance": -3 },
+  { "set": "held-out", "query": "What does SynthLang compress or optimize?", "expectRepo": ["synthlang", "concepts"], "minRelevance": -3 },
+  { "set": "held-out", "query": "Can rupixel retrieve documents using visual embeddings?", "expectRepo": ["rupixel", "concepts"], "minRelevance": -3 },
+  { "set": "held-out", "query": "What is agenticow's copy-on-write approach to agent memory?", "expectRepo": ["agenticow", "concepts"], "minRelevance": -3 },
+  { "set": "held-out", "query": "Does CVE-bench benchmark security fixes reproduced from real CVEs?", "expectRepo": ["cve-bench", "concepts"], "minRelevance": -3 },
+  { "set": "held-out", "query": "What is dspy.ts and what does it do?", "expectRepo": ["dspy.ts", "concepts"], "minRelevance": -3 },
+  { "set": "held-out", "query": "Does FACT provide fast-access cached tools for reliable AI integration?", "expectRepo": ["fact", "concepts"], "minRelevance": -3 },
+  { "set": "held-out", "query": "What does the daa project enable for decentralized autonomous applications?", "expectRepo": ["daa", "concepts"], "minRelevance": -3 },
+
+  { "set": "anti-drift", "query": "Can Ruflo agents actually create and edit files on disk, or are they limited to chat responses?", "expectRepo": ["ruflo", "concepts"], "minRelevance": -3 },
+  { "set": "anti-drift", "query": "Should I reach for pgvector or Pinecone, or does the RuvNet stack have its own vector database?", "expectRepo": ["ruvector", "rulake", "concepts"], "minRelevance": -3 },
+  { "set": "anti-drift", "query": "Is there a RuvNet tool for cheap model routing so I don't pay full price in Claude Code?", "expectRepo": ["agentic-flow", "concepts"], "minRelevance": -3 },
+  { "set": "anti-drift", "query": "What is the RuvNet way to give an agent persistent structured memory across sessions?", "expectRepo": ["agentdb", "concepts"], "minRelevance": -3 },
+  { "set": "anti-drift", "query": "Does the RuvNet ecosystem include a methodology for planning a non-trivial build?", "expectRepo": ["sparc", "concepts", "ruflo"], "minRelevance": -3 },
+  { "set": "anti-drift", "query": "Is there a RuvNet caching layer to make repeated vector queries sub-millisecond?", "expectRepo": ["rulake", "concepts"], "minRelevance": -3 },
+  { "set": "anti-drift", "query": "Does RuvNet have anything that senses people, presence, or falls through walls using WiFi, with no camera?", "expectRepo": ["ruview", "concepts"], "minRelevance": -3 },
+  { "set": "anti-drift", "query": "Does RuvNet have anything for quantum-resistant secure messaging between agents?", "expectRepo": ["qudag", "concepts"], "minRelevance": -3 },
+  { "set": "anti-drift", "query": "Is there a RuvNet neural network library I can run in Rust or WASM?", "expectRepo": ["ruv-fann", "concepts"], "minRelevance": -3 },
+  { "set": "anti-drift", "query": "Which RuvNet tool benchmarks an agent's ability to fix real security vulnerabilities?", "expectRepo": ["cve-bench", "concepts"], "minRelevance": -3 },
+
+  { "set": "cross-repo", "query": "If I want both vector search and structured agent memory, which RuvNet tools combine?", "expectRepo": ["ruvector", "agentdb", "rulake", "concepts"], "minRelevance": -3 },
+  { "set": "cross-repo", "query": "How do Ruflo and agentic-flow relate, orchestration versus model routing?", "expectRepo": ["ruflo", "agentic-flow", "concepts"], "minRelevance": -3 },
+  { "set": "cross-repo", "query": "What is the difference between RuVector and RuLake?", "expectRepo": ["ruvector", "rulake", "concepts"], "minRelevance": -3 },
+
+  { "set": "implementation", "query": "How does RuVector implement the HNSW navigable small-world graph on disk?", "expectRepo": ["ruvector", "concepts"], "minRelevance": -3 },
+  { "set": "implementation", "query": "How does AgentDB store causal edges between memory nodes?", "expectRepo": ["agentdb", "concepts"], "minRelevance": -3 },
+  { "set": "implementation", "query": "How does SPARC structure its five phases with quality gates?", "expectRepo": ["sparc", "concepts", "ruflo"], "minRelevance": -3 },
+  { "set": "implementation", "query": "How does SAFLA close its self-aware feedback learning loop?", "expectRepo": ["safla", "concepts"], "minRelevance": -3 },
+  { "set": "implementation", "query": "How does SynthLang compress prompts to reduce token cost?", "expectRepo": ["synthlang", "concepts"], "minRelevance": -3 },
+
+  { "set": "coverage", "query": "What is rupixel and what kind of embeddings does it use?", "expectRepo": ["rupixel", "concepts"], "minRelevance": -3 },
+  { "set": "coverage", "query": "What is agenticow and how does copy-on-write help agent memory?", "expectRepo": ["agenticow", "concepts"], "minRelevance": -3 },
+  { "set": "coverage", "query": "What is daa and what does it enable for decentralized autonomous agents?", "expectRepo": ["daa", "concepts"], "minRelevance": -3 },
+  { "set": "coverage", "query": "What is dspy.ts and how does it bring DSPy-style programming to TypeScript?", "expectRepo": ["dspy.ts", "concepts"], "minRelevance": -3 },
+  { "set": "coverage", "query": "What does FACT actually cache, and why is it about caching rather than retrieval?", "expectRepo": ["fact", "concepts"], "minRelevance": -3 },
+  { "set": "coverage", "query": "What does agent-harness-generator / metaharness mint, and what is Darwin Mode?", "expectRepo": ["metaharness", "concepts"], "minRelevance": -3 },
+
+  { "set": "adversarial", "query": "I heard RuvNet can't do real multi-agent swarms, is that true?", "expectRepo": ["ruflo", "concepts"], "minRelevance": -3 },
+  { "set": "adversarial", "query": "Does ruv-FANN actually run, or is it just an idea?", "expectRepo": ["ruv-fann", "concepts"], "minRelevance": -3 },
+  { "set": "adversarial", "query": "Give me the RuvNet building block for orchestrating parallel coding agents.", "expectRepo": ["ruflo", "concepts"], "minRelevance": -3 },
+  { "set": "adversarial", "query": "What is the RuvNet equivalent of LangGraph for agent workflows?", "expectRepo": ["ruflo", "agentic-flow", "concepts"], "minRelevance": -3 },
+  { "set": "adversarial", "query": "Which RuvNet repo would I use to A/B test and score different agent harnesses?", "expectRepo": ["metaharness", "concepts"], "minRelevance": -3 }
+]

package/scripts/protected-release-invocation.mjs

@@ -0,0 +1,76 @@
+#!/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.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { evaluateCandidateReceipt } from './release-proof.mjs';
+import { getVersion } from './version.mjs';
+
+export const PROTECTED_WORKFLOW = 'protected-release';
+export const PROTECTED_VERSION = getVersion();
+
+const hex = (value, length) => new RegExp(`^[0-9a-f]{${length}}$`).test(String(value || ''));
+const digestOf = (receipt) => String(receipt?.artifact?.sha256 || '').replace(/^sha256:/, '');
+
+export function validateProtectedPublishInvocation({ root = process.cwd(), env = process.env } = {}) {
+  const failures = [];
+  let releaseMode = 'unknown';
+  if (env.GITHUB_ACTIONS !== 'true' || env.GITHUB_WORKFLOW !== PROTECTED_WORKFLOW) {
+    failures.push('publication is allowed only inside the protected-release GitHub workflow');
+  }
+
+  const expectedSha = String(env.RUVNET_EXPECTED_SHA || '');
+  const expectedDigest = String(env.RUVNET_EXPECTED_ARTIFACT_SHA256 || '').replace(/^sha256:/, '');
+  const expectedVersion = String(env.RUVNET_EXPECTED_VERSION || '');
+  if (!hex(expectedSha, 40)) failures.push('expected candidate SHA is missing or malformed');
+  if (!hex(expectedDigest, 64)) failures.push('expected artifact digest is missing or malformed');
+  if (expectedVersion !== PROTECTED_VERSION) failures.push(`release generation must be ${PROTECTED_VERSION}`);
+
+  const receiptRelative = String(env.RUVNET_CANDIDATE_RECEIPT || '');
+  const evidenceRoot = path.resolve(root, 'release-evidence');
+  const receiptPath = path.resolve(root, receiptRelative || '.missing-candidate-receipt');
+  if (!receiptRelative || !(receiptPath === evidenceRoot || receiptPath.startsWith(`${evidenceRoot}${path.sep}`))) {
+    failures.push('candidate receipt must be inside release-evidence');
+  }
+
+  let receipt = null;
+  try {
+    receipt = JSON.parse(fs.readFileSync(receiptPath, 'utf8'));
+  } catch (error) {
+    failures.push(`candidate receipt unavailable: ${error.message}`);
+  }
+
+  if (receipt) {
+    const seal = evaluateCandidateReceipt(receipt);
+    if (seal.verdict !== 'PASS') failures.push(`candidate seal failed: ${seal.failures.map(({ code }) => code).join(',')}`);
+    const receiptDigest = digestOf(receipt);
+    if (receipt.sha !== expectedSha) failures.push('candidate receipt SHA mismatch');
+    if (receiptDigest !== expectedDigest) failures.push('candidate artifact digest mismatch');
+    if (receipt.version !== expectedVersion) failures.push('candidate version mismatch');
+    const expectedMode = receipt.phase === 'stabilization-candidate' ? 'stabilization' : 'strict';
+    releaseMode = expectedMode;
+    if (env.RUVNET_RELEASE_MODE !== expectedMode) failures.push(`release mode must be ${expectedMode} for this receipt`);
+
+    const artifactPath = path.resolve(root, String(receipt.artifact?.path || '.missing-artifact'));
+    if (!(artifactPath === evidenceRoot || artifactPath.startsWith(`${evidenceRoot}${path.sep}`))) {
+      failures.push('candidate artifact must be inside release-evidence');
+    } else {
+      try {
+        const actual = crypto.createHash('sha256').update(fs.readFileSync(artifactPath)).digest('hex');
+        if (actual !== expectedDigest) failures.push('candidate artifact bytes do not match the seal');
+      } catch (error) {
+        failures.push(`candidate artifact unavailable: ${error.message}`);
+      }
+    }
+  }
+
+  return {
+    verdict: failures.length === 0 ? 'PASS' : 'FAIL',
+    sha: expectedSha,
+    artifactSha256: expectedDigest,
+    version: expectedVersion,
+    mode: releaseMode,
+    failures,
+  };
+}

package/scripts/prove.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+// prove.mjs — run a question battery through the REAL retrieval engine and emit an auditable
+// proof artifact. It calls searchAll() directly — the *exact* function the search_ruvnet MCP tool
+// wraps — so the scores are the same ones a live Claude session sees, just without the JSON-RPC
+// envelope. Models load once for the whole battery.
+//
+//   KB_MODEL_CACHE=/path/to/models-cache node scripts/prove.mjs
+//   [--questions scripts/proof-questions.json] [--k 3]
+//
+// Writes:  PROOF.md (human table + summary)  and  data/proof-results.json (machine-readable)
+// Exit 0 if every question resolves to an expected repo at/above its threshold; 1 otherwise.
+import path from 'node:path';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { searchAll } from '../kb/forge-ask-all.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const KB = path.join(ROOT, 'kb');
+const arg = (f, d) => { const i = process.argv.indexOf(f); return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : d; };
+const QFILE = path.resolve(arg('--questions', path.join(ROOT, 'scripts', 'proof-questions.json')));
+const K = parseInt(arg('--k', '3'), 10);
+const OUTBASE = arg('--out', 'PROOF'); // PROOF.md + data/<lower>-results.json
+
+const questions = JSON.parse(fs.readFileSync(QFILE, 'utf8'));
+const started = new Date().toISOString();
+console.log(`[prove] ${questions.length} questions · k=${K} · brain=${KB}\n`);
+
+const results = [];
+for (let i = 0; i < questions.length; i++) {
+  const q = questions[i];
+  let ranked = [];
+  try { const out = await searchAll({ dir: KB, query: q.query, k: K, pool: 8 }); ranked = out?.results || []; }
+  catch (e) { console.log(`ERR   #${i + 1}  ${e.message}`); }
+  const top = ranked[0] || null;
+  const got = top?.repo ?? null;
+  const eff = (got === 'concepts' && top?.path) ? (top.path.split('/')[0] || got) : got; // primer's home repo
+  const score = top?.ceScore ?? null;
+  const citedPath = top ? `${top.repo}/${top.path}` : null;
+  const exp = q.expectRepo;
+  const repoOk = !exp || (Array.isArray(exp) ? (exp.includes(got) || exp.includes(eff)) : (got === exp || eff === exp));
+  const relOk = score == null ? true : score >= (q.minRelevance ?? -3);
+  const pass = !!got && repoOk && relOk;
+  results.push({ n: i + 1, set: q.set || '', query: q.query, expect: exp, got, eff, score, citedPath, pass });
+  const s = score == null ? 'n/a' : score.toFixed(3);
+  console.log(`${pass ? 'PASS' : 'FAIL'}  #${String(i + 1).padStart(2)}  ${(eff || '(no hit)').padEnd(24)} @ ${String(s).padStart(7)}  ${q.query.slice(0, 64)}`);
+}
+
+const passed = results.filter((r) => r.pass).length;
+const scored = results.filter((r) => r.score != null).map((r) => r.score).sort((a, b) => a - b);
+const median = scored.length ? scored[Math.floor(scored.length / 2)] : null;
+const bySet = {};
+for (const r of results) { const k = r.set || 'other'; (bySet[k] ??= { pass: 0, total: 0 }); bySet[k].total++; if (r.pass) bySet[k].pass++; }
+
+// machine artifact
+fs.mkdirSync(path.join(ROOT, 'data'), { recursive: true });
+fs.writeFileSync(path.join(ROOT, 'data', `${OUTBASE.toLowerCase()}-results.json`),
+  JSON.stringify({ started, finished: new Date().toISOString(), k: K, passed, total: results.length, bySet, results }, null, 2));
+
+// human artifact
+const esc = (s) => String(s).replace(/\|/g, '\\|');
+const setLines = Object.entries(bySet).map(([k, v]) => `| ${k} | ${v.pass}/${v.total} |`).join('\n');
+const rows = results.map((r) => `| ${r.n} | ${r.set} | ${esc(r.query)} | ${r.eff || '—'} | ${r.score == null ? 'n/a' : r.score.toFixed(3)} | ${esc(r.citedPath || '—')} | ${r.pass ? '✅' : '❌'} |`).join('\n');
+const md = `# RuvNet Brain — Proof of Retrieval (live run)
+
+> Generated by \`node scripts/prove.mjs\` on ${started}. Re-run it yourself; this file is the output, not a claim.
+> Each row is a real query through \`searchAll()\` — the exact engine the \`search_ruvnet\` MCP tool wraps.
+
+## Headline
+
+**${passed}/${results.length} questions resolved to an expected repo** at/above threshold. Median top-hit relevance: **${median == null ? 'n/a' : median.toFixed(3)}**.
+
+| Question set | Passed |
+|---|---|
+${setLines}
+
+- **tuned / held-out** — the capability-confidence gate (held-out built *after* tuning ⇒ not overfit).
+- **anti-drift** — questions phrased the way a skeptic would, where Claude normally reaches for pgvector/Pinecone or doubts a real tool.
+- **adversarial** — negative-framed ("I heard it *can't*…") to prove the brain doesn't fold.
+- **implementation / coverage / cross-repo** — depth and breadth across all 19 repos.
+
+## Every question, every score
+
+| # | set | question | resolved repo | relevance | cited source | ok |
+|--:|---|---|---|--:|---|:--:|
+${rows}
+
+> "relevance" is the cross-encoder score after name-affinity boost; higher is sharper. Negative is normal for
+> a cross-encoder and still ranks correctly — what matters for the *never-wrongly-doubt* guarantee is that the
+> top hit lands on the right repo with a cited file you can open.
+`;
+fs.writeFileSync(path.join(ROOT, `${OUTBASE}.md`), md);
+
+console.log(`\n[prove] ${passed}/${results.length} passed · median ${median == null ? 'n/a' : median.toFixed(3)}`);
+console.log('[prove] wrote PROOF.md + data/proof-results.json');
+process.exit(passed === results.length ? 0 : 1);

package/scripts/proxy/claude-proxied.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# claude-proxied.sh — launch ONE Claude Code session routed through the proxy.
+#
+# THIS IS THE ISOLATION BOUNDARY OF THE WHOLE TRIAL.
+#
+# ANTHROPIC_BASE_URL is exported for this process only. Nothing is written to
+# ~/.claude/settings.json, so every other Claude Code window on this machine —
+# including the one you are reading this in — keeps talking directly to
+# Anthropic, exactly as before. Close this session and the wiring is gone.
+#
+# What happens inside this session (ADR-313 addendum): setting
+# ANTHROPIC_BASE_URL makes Claude Code stop managing its own Max/Pro OAuth
+# session. That is fine here and ONLY because the proxy defaults to the
+# Passthrough plane, which reads ~/.claude/.credentials.json (read-only) and
+# forwards to the real api.anthropic.com with your actual subscription token.
+# Your subscription is still what pays and still what answers.
+#
+# If the plane were ever anything other than passthrough, this script refuses
+# to launch — a silent flip to a cheap tier while you believe you are on your
+# subscription is the single worst failure mode here, so it is checked, not
+# assumed.
+set -euo pipefail
+
+TOKEN_FILE="$HOME/.ruflo/proxy-token"
+
+if ! ruflo proxy status --json 2>/dev/null | grep -q '"running":true'; then
+  echo "Proxy is not running. Start it first:"
+  echo "  ./scripts/proxy/proxy-up.sh"
+  exit 1
+fi
+
+if [ ! -r "$TOKEN_FILE" ]; then
+  echo "Missing proxy token at $TOKEN_FILE — reinstall with ./scripts/proxy/proxy-up.sh"
+  exit 1
+fi
+
+PLANE=$(ruflo proxy config 2>/dev/null | head -1)
+if ! echo "$PLANE" | grep -qi 'passthrough'; then
+  echo "REFUSING TO LAUNCH — data plane is not passthrough:"
+  echo "  $PLANE"
+  echo
+  echo "This trial only sanctions the passthrough plane (your own subscription)."
+  echo "Revert to it with: ruflo proxy config --local-only   (or re-read ADR-0026)"
+  exit 1
+fi
+
+export ANTHROPIC_BASE_URL="http://127.0.0.1:11435"
+export ANTHROPIC_AUTH_TOKEN="$(cat "$TOKEN_FILE")"
+
+echo "Launching a proxied Claude Code session."
+echo "  ANTHROPIC_BASE_URL = $ANTHROPIC_BASE_URL   (this process only)"
+echo "  data plane         = passthrough (your own Anthropic subscription)"
+echo "  other windows      = unaffected"
+echo "  watch traffic with = ruflo proxy logs -f"
+echo
+
+exec claude "$@"

package/scripts/proxy/proxy-revert.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# proxy-revert.sh — remove the Meta LLM Proxy trial completely.
+#
+# This is the safety net for the whole trial, so it is deliberately boring and
+# total: stop the process, uninstall via rUv's own lifecycle command, then
+# PROVE nothing is left rather than claiming it.
+#
+# It does not touch ~/.claude/settings.json — the trial never wrote there (see
+# proxy-verify.mjs check 3), so there is nothing to undo.
+set -uo pipefail
+
+echo "Reverting the Meta LLM Proxy trial..."
+echo
+
+echo "--- stopping (if running) ---"
+ruflo proxy stop 2>&1 | sed 's/^/  /' || true
+echo
+
+echo "--- uninstalling binary, token, consent receipt (ruflo proxy uninstall) ---"
+ruflo proxy uninstall 2>&1 | sed 's/^/  /' || true
+echo
+
+echo "--- PROOF it is gone (derived, not asserted) ---"
+FAIL=0
+
+STATUS=$(ruflo proxy status --json 2>/dev/null || echo '{}')
+echo "  ruflo proxy status: $STATUS"
+case "$STATUS" in
+  *'"installed":true'*) echo "    ^ still installed" ; FAIL=1 ;;
+esac
+case "$STATUS" in
+  *'"running":true'*)   echo "    ^ still running"   ; FAIL=1 ;;
+esac
+
+if lsof -iTCP:11435 -sTCP:LISTEN -n -P >/dev/null 2>&1; then
+  echo "  port 11435: STILL LISTENING  <-- revert incomplete"; FAIL=1
+else
+  echo "  port 11435: clear"
+fi
+
+if [ -f "$HOME/.ruflo/proxy-token" ]; then
+  echo "  proxy-token: STILL PRESENT  <-- revert incomplete"; FAIL=1
+else
+  echo "  proxy-token: removed"
+fi
+
+if grep -q 'ANTHROPIC_BASE_URL' "$HOME/.claude/settings.json" 2>/dev/null; then
+  echo "  ~/.claude/settings.json: contains ANTHROPIC_BASE_URL  <-- unexpected"; FAIL=1
+else
+  echo "  ~/.claude/settings.json: clean (never modified by this trial)"
+fi
+
+echo
+if [ "$FAIL" = 0 ]; then
+  echo "Reverted. The machine is back to its pre-trial state."
+  exit 0
+fi
+echo "REVERT INCOMPLETE — see the lines marked above."
+exit 1

package/scripts/proxy/proxy-up.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# proxy-up.sh — install + start the Meta LLM Proxy, then verify it.
+#
+# Thin orchestration over rUv's own lifecycle commands (ADR-307):
+#   ruflo proxy install / start / status / doctor
+# It adds no logic of its own except the macOS workaround documented below.
+set -uo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+
+# --- macOS workaround: upstream bug in @claude-flow/security's PathValidator --
+#
+# `ruflo proxy install` extracts into a tmpdir and then validates that the
+# extracted binary really lives inside that tmpdir (defense against a symlink
+# swap). The validator canonicalizes the CANDIDATE path with fs.realpath but
+# resolves the ALLOWED PREFIX with path.resolve only:
+#
+#   path-validator.ts:177-178   prefixes -> path.resolve(p)          (no realpath)
+#   path-validator.ts:229,234   candidate -> path.resolve + realpath
+#   path-validator.ts:262       resolvedPath.startsWith(prefix + sep)
+#
+# On macOS os.tmpdir() is /var/folders/... which is a symlink to
+# /private/var/folders/... So the candidate becomes /private/var/... while the
+# prefix stays /var/... and the startsWith check can NEVER pass. Install fails
+# with "extracted binary path failed validation: Path is outside allowed
+# directories" for every macOS user.
+#
+# Handing the installer an ALREADY-CANONICAL TMPDIR makes the validator's own
+# assumption true. This changes nothing about what is downloaded or verified —
+# the Ed25519 signature and sha256 checks run exactly as before.
+#
+# Upstream fix would be one line: realpath the prefixes too.
+if [ "$(uname -s)" = "Darwin" ]; then
+  CANONICAL_TMP="$(node -e 'console.log(require("fs").realpathSync(require("os").tmpdir()))' 2>/dev/null || echo "")"
+  if [ -n "$CANONICAL_TMP" ]; then
+    export TMPDIR="$CANONICAL_TMP"
+    echo "macOS: TMPDIR canonicalized to $TMPDIR (upstream PathValidator symlink bug)"
+    echo
+  fi
+fi
+
+echo "--- install (idempotent; verifies Ed25519 signature + sha256) ---"
+if ruflo proxy status --json 2>/dev/null | grep -q '"installed":true'; then
+  echo "  already installed"
+else
+  ruflo proxy install --yes 2>&1 | tail -4 | sed 's/^/  /'
+fi
+echo
+
+echo "--- start (detached; survives terminal close, NOT a reboot) ---"
+if ruflo proxy status --json 2>/dev/null | grep -q '"running":true'; then
+  echo "  already running"
+else
+  ruflo proxy start --service 2>&1 | tail -3 | sed 's/^/  /'
+  sleep 2
+fi
+echo
+
+echo "--- verify ---"
+node "$REPO_ROOT/scripts/proxy/proxy-verify.mjs"