ruvnet-brain 4.0.1 → 4.0.2

package/scripts/build-l2.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// build-l2.mjs — L2 concept/synthesis layer (the validated closer for overview/playbook questions).
+// For a synthesis topic: retrieve the real source (rerankKb), have a strong LLM SYNTHESIZE a complete,
+// prescriptive, source-CITED article using ONLY that source, validate the citations are real, then
+// GRADE the article with the 3-vendor panel (does it now fully answer?). Proves L2 closes Q5/Q7/Q8.
+//
+//   node scripts/build-l2.mjs --name ruflo --variant big
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { rerankKb } from '../kb/forge-rerank.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const arg = (f, d) => { const i = process.argv.indexOf(f); return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : d; };
+const NAME = arg('--name', 'ruflo'), VARIANT = arg('--variant', 'big');
+const GEN_MODEL = arg('--gen', 'anthropic/claude-3.5-sonnet');
+const JUDGES = ['openai/gpt-4o-mini', 'deepseek/deepseek-chat', 'meta-llama/llama-3.3-70b-instruct'];
+const REPO = process.env.RUVNET_REPO || path.join(ROOT, '..', 'ruvnet-repos', NAME);
+const KEY = process.env.OPENROUTER_API_KEY || (fs.readFileSync((process.env.RUVNET_ENV_FILE || '.env'), 'utf8').match(/^OPENROUTER_API_KEY=(.+)$/m) || [])[1]?.trim();
+
+// Per-repo synthesis topics: prefer kb/l2-topics.<name>.json ([{slug,q},...] — the graded synthesis
+// gaps), else fall back to the original ruflo defaults so existing behavior is unchanged.
+const RUFLO_DEFAULT = [
+  { slug: 'guidance-mechanism', q: 'How does the guidance system produce a recommendation (guidance_recommend) — what is the mechanism?' },
+  { slug: 'adr-coverage', q: "Where are ruflo's ADRs kept and what areas do they cover?" },
+  { slug: 'memory-end-to-end', q: "How do I initialize and use ruflo's memory in a project end-to-end?" },
+];
+const TOPICS_FILE = path.join(ROOT, 'kb', `l2-topics.${NAME}.json`);
+const TOPICS = fs.existsSync(TOPICS_FILE) ? JSON.parse(fs.readFileSync(TOPICS_FILE, 'utf8')) : RUFLO_DEFAULT;
+
+async function or(model, sys, usr, max = 1400) {
+  const r = await fetch('https://openrouter.ai/api/v1/chat/completions', {
+    method: 'POST', headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ model, messages: [{ role: 'system', content: sys }, { role: 'user', content: usr }], temperature: 0, max_tokens: max }),
+  });
+  if (!r.ok) throw new Error(`${model} HTTP ${r.status}`);
+  return (await r.json()).choices?.[0]?.message?.content || '';
+}
+
+fs.mkdirSync(path.join(ROOT, 'kb/l2'), { recursive: true });
+for (const t of TOPICS) {
+  const hits = await rerankKb({ dir: path.join(ROOT, 'kb'), name: NAME, query: t.q, k: 8, variant: VARIANT });
+  const allowed = new Set(hits.map((h) => h.path));
+  const ctx = hits.map((h, i) => `[SOURCE ${i + 1}] ${h.path}\n${(h.fullText || '').slice(0, 2400)}`).join('\n\n');
+  const paths = hits.map((h) => h.path);
+  const sys = 'You are Ruv writing the authoritative internal explainer. Using ONLY the SOURCE excerpts provided, write a complete, prescriptive, actionable answer. You MUST cite real file paths inline in backticks for EVERY major claim, referencing at least 3 distinct SOURCE paths verbatim. Do NOT invent files or facts. If a part is not covered by the sources, say so explicitly rather than guessing.';
+  // ground-truth citation check: count how many of the PROVIDED source paths the article actually references
+  const countRefs = (txt) => [...new Set(paths.filter((p) => txt.includes(p) || txt.includes(p.split('/').pop())))];
+  const gen = (extra) => or(GEN_MODEL, sys + extra, `QUESTION: ${t.q}\n\nSOURCE PATHS YOU MUST CITE FROM (verbatim):\n${paths.map((p) => '- ' + p).join('\n')}\n\nSOURCES:\n${ctx}`, 1500)
+    .catch(() => or('openai/gpt-4o-mini', sys + extra, `QUESTION: ${t.q}\n\nSOURCES:\n${ctx}`, 1500));
+  let article = await gen('');
+  let realCited = countRefs(article);
+  if (realCited.length < 2) { article = await gen(' YOUR LAST ATTEMPT CITED TOO FEW REAL FILES — REJECTED. Cite at least 3 of the exact SOURCE PATHS listed above, verbatim, in backticks.'); realCited = countRefs(article); }
+  const accepted = realCited.length >= 2;                    // ADR-0002 R1: enforce grounding or REJECT
+  const odir = accepted ? 'l2' : 'l2/rejected';
+  fs.mkdirSync(path.join(ROOT, 'kb', odir), { recursive: true });
+  fs.writeFileSync(path.join(ROOT, 'kb', odir, `${t.slug}.md`), `# ${t.q}\n\n<!-- L2 synthesis · ${accepted ? 'ACCEPTED' : 'REJECTED (ungrounded)'} · ${realCited.length} verified source refs: ${realCited.slice(0, 5).join(', ')} -->\n\n${article}\n`);
+
+  // grade the article as the answer (3-vendor)
+  const jsys = 'Grade 1-100 whether this answer COMPLETELY and CORRECTLY answers the question (98=perfect/complete/actionable; incomplete-but-not-wrong=POISON<50). Return ONLY {"score":N,"reason":"<=15 words"}.';
+  const scores = [];
+  for (const j of JUDGES) {
+    try { const o = JSON.parse((await or(j, jsys, `QUESTION: ${t.q}\n\nANSWER:\n${article}`, 120)).match(/\{[\s\S]*\}/)[0]); scores.push(Number(o.score)); }
+    catch { /* skip */ }
+  }
+  const avg = scores.length ? (scores.reduce((a, b) => a + b, 0) / scores.length) : null;
+  console.log(`\n## ${t.slug}  [${accepted ? 'ACCEPTED' : 'REJECTED — ungrounded'}]`);
+  console.log(`   verified source refs: ${realCited.length} (${realCited.slice(0, 4).join(', ')})`);
+  console.log(`   3-vendor answer score: [${scores.join(', ')}] → avg ${avg?.toFixed(1)}`);
+}
+console.log('\nL2 articles written to kb/l2/. (Integration: include kb/l2 in the next KB rebuild so they are retrievable.)');

package/scripts/build-primer.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+// build-primer.mjs — per-repo top-down PRIMER (the 6 comprehension archetypes), grounded.
+// Same proven shape as build-l2: for each archetype, retrieve the real source (rerankKb), have a
+// strong LLM synthesize a prescriptive, source-CITED section using ONLY that source, then assemble
+// the sections into kb/<name>-primer.md and verify the whole primer cites >= MIN real files.
+//
+// The "capabilities" archetype is deliberate: it produces PROSE that names each real capability with
+// the file that implements it — the high-confidence retrieval target that makes an assistant STOP
+// doubting code-implemented capabilities (the capability-confidence gap measured on ruflo/rulake).
+//
+//   node scripts/build-primer.mjs --name ruflo --variant big
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { rerankKb } from '../kb/forge-rerank.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const arg = (f, d) => { const i = process.argv.indexOf(f); return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : d; };
+const NAME = arg('--name', 'ruflo'), VARIANT = arg('--variant', 'big');
+const KEY = process.env.OPENROUTER_API_KEY || (fs.readFileSync((process.env.RUVNET_ENV_FILE || '.env'), 'utf8').match(/^OPENROUTER_API_KEY=(.+)$/m) || [])[1]?.trim();
+if (!KEY) { console.error('No OPENROUTER_API_KEY'); process.exit(2); }
+const GEN_MODEL = arg('--gen', 'deepseek/deepseek-chat');
+const JUDGES = ['openai/gpt-4o-mini', 'deepseek/deepseek-chat', 'meta-llama/llama-3.3-70b-instruct'];
+
+// The 6 archetypes a raw repo can't answer top-down. {key,title,q}. The capabilities section is #2.
+const ARCHES = [
+  { key: 'what', title: 'What it is & who it\'s for', q: `What is ${NAME} and who is it for?` },
+  { key: 'capabilities', title: 'Capabilities (what it can do)', q: `What can ${NAME} actually do? List its main capabilities, and for EACH name the source file that implements it.` },
+  { key: 'concepts', title: 'Core concepts & how they work', q: `What are ${NAME}'s core concepts and how does each one work?` },
+  { key: 'maturity', title: 'Maturity (shipped vs proposed)', q: `How mature is ${NAME}? Which features are shipped/accepted vs proposed (cite ADR status)?` },
+  { key: 'docs', title: 'Where the documentation lives', q: `Where is ${NAME}'s documentation organized (guides, ADRs, references)?` },
+  { key: 'use', title: 'How to use it end-to-end', q: `How do I install and use ${NAME} end-to-end?` },
+];
+
+async function or(model, sys, usr, max = 1500) {
+  const r = await fetch('https://openrouter.ai/api/v1/chat/completions', {
+    method: 'POST', headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ model, messages: [{ role: 'system', content: sys }, { role: 'user', content: usr }], temperature: 0, max_tokens: max }),
+  });
+  if (!r.ok) throw new Error(`${model} HTTP ${r.status}`);
+  return (await r.json()).choices?.[0]?.message?.content || '';
+}
+
+const KB = path.join(ROOT, 'kb');
+const allPaths = new Set();
+let sections = [];
+for (const a of ARCHES) {
+  const hits = await rerankKb({ dir: KB, name: NAME, query: a.q, k: 8, variant: VARIANT });
+  const paths = hits.map((h) => h.path);
+  paths.forEach((p) => allPaths.add(p));
+  const ctx = hits.map((h, i) => `[SOURCE ${i + 1}] ${h.path}\n${(h.fullText || '').slice(0, 2200)}`).join('\n\n');
+  const sys = `You are Ruv writing the authoritative primer for ${NAME}. Using ONLY the SOURCE excerpts, write the "${a.title}" section: complete, prescriptive, and CONFIDENT about what exists. Cite real file paths inline in backticks for every concrete claim (cite >= 2 distinct SOURCE paths verbatim). For capabilities, state plainly that the feature EXISTS and point to the implementing file — never hedge about whether it can do something the source shows. If something is genuinely not covered, say so; do not invent.`;
+  let body = await or(GEN_MODEL, sys, `SECTION: ${a.title}\nQUESTION: ${a.q}\n\nSOURCE PATHS (cite verbatim):\n${paths.map((p) => '- ' + p).join('\n')}\n\nSOURCES:\n${ctx}`)
+    .catch(() => or('openai/gpt-4o-mini', sys, `QUESTION: ${a.q}\n\nSOURCES:\n${ctx}`));
+  sections.push(`## ${a.title}\n\n${body.trim()}\n`);
+  console.log(`  [${NAME}] section "${a.key}" — ${body.length} chars, ${paths.length} sources`);
+}
+
+const primer = `# ${NAME} — Primer\n\n<!-- Generated primer · grounded in real source via rerankKb (${VARIANT}) · archetypes: ${ARCHES.map(a => a.key).join(', ')} -->\n\n${sections.join('\n')}`;
+const countRefs = (txt) => [...new Set([...allPaths].filter((p) => txt.includes(p) || txt.includes(p.split('/').pop())))];
+const refs = countRefs(primer);
+const outFile = path.join(KB, `${NAME}-primer.md`);
+fs.writeFileSync(outFile, primer);
+
+// 3-vendor "is this a complete, correct primer?" score (informational; the hard gate is citation count)
+const jsys = 'Grade 1-100 whether this repo primer is COMPLETE, CORRECT and CONFIDENT for an engineer new to the repo (98=excellent/actionable; vague-or-hedgy=POISON<50). Return ONLY {"score":N,"reason":"<=15 words"}.';
+const scores = [];
+for (const j of JUDGES) { try { scores.push(Number(JSON.parse((await or(j, jsys, `PRIMER:\n${primer.slice(0, 9000)}`, 120)).match(/\{[\s\S]*\}/)[0]).score)); } catch { /* skip */ } }
+const avg = scores.length ? (scores.reduce((a, b) => a + b, 0) / scores.length) : null;
+console.log(`\n## ${NAME}-primer.md  [${refs.length >= 6 ? 'GROUNDED' : 'THIN — only ' + refs.length + ' refs'}]`);
+console.log(`   verified source refs: ${refs.length}`);
+console.log(`   3-vendor primer score: [${scores.join(', ')}] → avg ${avg?.toFixed(1)}`);
+console.log(`   written: kb/${NAME}-primer.md`);

package/scripts/build-symbols.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+// build-symbols.mjs — ADR-0003 point-deeper symbol index.
+// Scans <name>.passages.jsonl and extracts a deterministic map from code symbols / file stems /
+// package names → the SOURCE paths that define them, so retrieval can hard-route an implementation
+// question to the real file instead of losing to a prose doc. Language-agnostic-ish (TS/JS/Rust/Py).
+//
+//   node scripts/build-symbols.mjs --name ruflo   → writes kb/<name>.symbols.json
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const arg = (f, d) => { const i = process.argv.indexOf(f); return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : d; };
+const NAME = arg('--name', 'ruflo');
+const KB = path.join(ROOT, 'kb');
+const PASSAGES = path.join(KB, `${NAME}.passages.jsonl`);
+
+const isSourcePath = (p) => /\.(ts|tsx|js|jsx|mjs|cjs|rs|py|go)$/i.test(p)
+  && !/\.(test|spec|d)\.[tj]sx?$/i.test(p)
+  && !/(^|\/)(tests?|__tests__|testing|fixtures?|\.claude|examples?)\//i.test(p);
+
+// symbol-definition patterns (capture the NAME)
+const DEF_RES = [
+  /\bexport\s+(?:default\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)/g,
+  /\bexport\s+(?:default\s+)?(?:abstract\s+)?class\s+([A-Za-z_$][\w$]*)/g,
+  /\bexport\s+(?:interface|type|enum)\s+([A-Za-z_$][\w$]*)/g,
+  /\bexport\s+const\s+([A-Za-z_$][\w$]*)\s*[:=]/g,
+  /\bpub\s+(?:async\s+)?fn\s+([a-z_][\w]*)/g,           // rust
+  /\bpub\s+(?:struct|enum|trait)\s+([A-Za-z_][\w]*)/g,  // rust
+  /(?:^|\s)class\s+([A-Za-z_$][\w$]*)/g,
+];
+// MCP tool / handler names (snake_case strings registered as tools)
+const TOOL_RES = [
+  /\bname:\s*['"]([a-z][a-z0-9_]+)['"]/g,
+  /(?:registerTool|tool|addTool|defineTool)\(\s*['"]([a-z][a-z0-9_]+)['"]/g,
+  /['"]([a-z]+_[a-z0-9_]+)['"]\s*:/g,                   // 'swarm_init': handler
+];
+
+const bySymbol = Object.create(null);   // exact identifier (lowercased) → Set(paths); null-proto: no __proto__/constructor collision
+const byStem = Object.create(null);     // file basename stem → Set(paths)
+const byPackage = Object.create(null);  // @claude-flow/<pkg> or crates/<pkg> → Set(src paths)
+const add = (map, key, p) => { if (!key) return; key = key.toLowerCase(); (map[key] ||= new Set()).add(p); };
+
+let n = 0, srcN = 0;
+for (const line of fs.readFileSync(PASSAGES, 'utf8').split('\n')) {
+  if (!line.trim()) continue;
+  let o; try { o = JSON.parse(line); } catch { continue; }
+  n++;
+  const p = o.path || ''; if (!isSourcePath(p)) continue;
+  srcN++;
+  const text = o.text || '';
+  for (const re of DEF_RES) { let m; re.lastIndex = 0; while ((m = re.exec(text))) { if (m[1] && m[1].length >= 3) add(bySymbol, m[1], p); } }
+  for (const re of TOOL_RES) { let m; re.lastIndex = 0; while ((m = re.exec(text))) { if (m[1] && m[1].length >= 4) add(bySymbol, m[1], p); } }
+  // stem
+  const stem = (p.split('/').pop() || '').replace(/\.[^.]+$/, '');
+  if (stem && stem !== 'index' && stem !== 'mod' && stem.length >= 3) add(byStem, stem, p);
+  // package
+  const pkg = p.match(/@[\w-]+\/([\w-]+)\//) || p.match(/(?:^|\/)crates\/([\w-]+)\//);
+  if (pkg) add(byPackage, pkg[1], p);
+}
+
+const freeze = (map, cap = 8) => Object.fromEntries(Object.entries(map).map(([k, v]) => [k, [...v].slice(0, cap)]));
+const out = { name: NAME, generated: 'STAMP', sourcePassages: srcN,
+  bySymbol: freeze(bySymbol), byStem: freeze(byStem), byPackage: freeze(byPackage, 30) };
+fs.writeFileSync(path.join(KB, `${NAME}.symbols.json`), JSON.stringify(out));
+console.log(`symbols: ${Object.keys(out.bySymbol).length} | stems: ${Object.keys(out.byStem).length} | packages: ${Object.keys(out.byPackage).length} (from ${srcN}/${n} source passages)`);
+console.log('sample symbols:', Object.keys(out.bySymbol).filter(s => /swarm_init|guidance_recommend|memorymanager|agentdb|sqlitebackend/.test(s)).slice(0, 10));
+console.log('packages:', Object.keys(out.byPackage).slice(0, 20).join(', '));

package/scripts/calibrate-router.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+// calibrate-router.mjs — measure the cheap→frontier tiers on REAL runs so "faster" and
+// "cheaper" are measured claims, and feed the learned router contrastive labels.
+//
+// WHY (2026-07-13, Stuart): "Nobody cares that they're saving 20 seconds. They care that
+// they're doing things 40% faster… cheaper AND faster = fundamentally more efficient."
+// A faster-% needs a measured baseline — this harness produces it. No number here is invented:
+// every duration is a wall-clock measurement of a real run, every quality label is a
+// deterministic check against a known answer, and failures are recorded as failures.
+//
+// BILLING SAFETY (the $1,600 / issue-#557 lesson): every spawned `claude -p` runs with
+// ANTHROPIC_API_KEY / CLAUDE_API_KEY / ANTHROPIC_AUTH_TOKEN stripped from its environment —
+// subscription billing only; worst case is plan throttling, never a surprise bill.
+//
+// FAIRNESS NOTE: durations include the CLI's startup overhead, identically for every tier —
+// the tier-vs-tier ratio is apples-to-apples; absolute numbers are "task via harness", not
+// raw model latency.
+//
+// Writes:
+//   • labels → recordOutcome(prompt, {model: quality, ...})  — one contrastive row per task,
+//     all tiers scored (the DRACO row shape rUv's router trains on)
+//   • receipts → ~/.claude/metaharness/routing-receipts.jsonl with source:'calibration',
+//     duration_ms (cheap tier) + baseline_duration_ms (frontier) → powers the ⚡ faster-% card
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { recordOutcome } from './metaharness-router.mjs';
+import { estimateCosts, estTokens } from './route-cheap.mjs';
+
+const CLAUDE = path.join(os.homedir(), '.npm-global/bin/claude');
+const RECEIPTS = process.env.METAHARNESS_RECEIPTS
+  || path.join(os.homedir(), '.claude', 'metaharness', 'routing-receipts.jsonl');
+
+const MODELS = [
+  { alias: 'haiku', name: 'claude-haiku-4.5' },
+  { alias: 'sonnet', name: 'claude-sonnet-5' },
+  { alias: 'opus', name: 'claude-opus-4.8' },   // the baseline tier
+];
+const BASELINE = 'claude-opus-4.8';
+
+// Deterministic tasks: known answers, graded by regex — no LLM judge, no judgment calls.
+const TASKS = [
+  { class: 'mechanical', prompt: 'Reply with exactly this single word and nothing else: CALIBRATED', pass: /CALIBRATED/ },
+  { class: 'mechanical', prompt: 'List only the function names, comma-separated, from this code and say nothing else:\nfunction parseHeader(x){}\nconst mapRows = (y) => y;\nasync function flushQueue(){}', pass: /parseHeader.*mapRows.*flushQueue/s },
+  { class: 'analytical', prompt: 'What is 17 * 23? Reply with the number only.', pass: /\b391\b/ },
+  { class: 'analytical', prompt: "In JavaScript, what does this print? console.log(0.1 + 0.2 === 0.3, (0.1 + 0.2).toFixed(1) === '0.3'). Reply with exactly the two words printed, space-separated.", pass: /false\s+true/i },
+  { class: 'analytical', prompt: 'In JavaScript: for (var i = 0; i < 3; i++) { setTimeout(() => console.log(i)); } What three numbers print? Reply with them space-separated only.', pass: /3\s+3\s+3/ },
+];
+
+function runOnce(alias, prompt) {
+  const env = { ...process.env };
+  delete env.ANTHROPIC_API_KEY; delete env.CLAUDE_API_KEY; delete env.ANTHROPIC_AUTH_TOKEN;
+  const t0 = Date.now();
+  const r = spawnSync(CLAUDE, ['-p', prompt, '--model', alias], { env, encoding: 'utf8', timeout: 180000 });
+  return { ms: Date.now() - t0, out: (r.stdout || '').trim(), ok: r.status === 0 };
+}
+
+const results = [];
+for (const [ti, task] of TASKS.entries()) {
+  const row = { task, runs: {} };
+  for (const m of MODELS) {
+    const r = runOnce(m.alias, task.prompt);
+    const passed = r.ok && task.pass.test(r.out);
+    row.runs[m.name] = { ms: r.ms, passed, out: r.out.slice(0, 60) };
+    console.log(`task ${ti + 1}/${TASKS.length} [${task.class}] ${m.name}: ${passed ? 'PASS' : 'FAIL'} in ${(r.ms / 1000).toFixed(1)}s${passed ? '' : ` — got: ${r.out.slice(0, 50) || '(no output)'}`}`);
+  }
+  results.push(row);
+
+  // Label: one contrastive row per task, every tier scored. Failures ARE the valuable labels.
+  const scores = {};
+  for (const m of MODELS) scores[m.name] = row.runs[m.name].passed ? 0.95 : 0.1;
+  await recordOutcome(task.prompt, scores);
+
+  // Receipts: one row per cheap tier vs the frontier baseline, with MEASURED times both sides.
+  const base = row.runs[BASELINE];
+  for (const m of MODELS) {
+    if (m.name === BASELINE) continue;
+    const run = row.runs[m.name];
+    const inTok = estTokens(task.prompt); const outTok = estTokens(run.out || 'x');
+    const c = estimateCosts(m.name, inTok, outTok, BASELINE);
+    if (!c) continue;
+    fs.appendFileSync(RECEIPTS, JSON.stringify({
+      ts: new Date().toISOString(), source: 'calibration', task_class: task.class,
+      task: task.prompt.slice(0, 80), model: m.name, frontier_ref: BASELINE,
+      est_in_tokens: inTok, est_out_tokens: outTok, token_source: 'estimated',
+      est_cost: c.cost, est_frontier_cost: c.frontier, saved: c.saved,
+      duration_ms: run.ms, baseline_duration_ms: base.ms, quality_pass: run.passed,
+    }) + '\n');
+  }
+}
+
+const cheap = results.flatMap((r) => [r.runs['claude-haiku-4.5'].ms]);
+const base = results.map((r) => r.runs[BASELINE].ms);
+const sum = (a) => a.reduce((s, x) => s + x, 0);
+console.log(`\nhaiku total ${(sum(cheap) / 1000).toFixed(1)}s vs opus baseline ${(sum(base) / 1000).toFixed(1)}s on ${TASKS.length} tasks`);
+console.log('labels + receipts written. Render: node scripts/metaharness-receipts.mjs');

package/scripts/capability-audit.mjs

@@ -0,0 +1,321 @@
+#!/usr/bin/env node
+/**
+ * capability-audit.mjs — the OFFENSIVE half of retrieval.
+ *
+ * WHY THIS EXISTS, and it is the sharpest failure this project has recorded.
+ *
+ * For three weeks the brain was queried ONLY defensively. Every consultation was triggered by the
+ * `ground-before-write` gate asking "am I about to duplicate something rUv already ships?" That gate
+ * is excellent and fired correctly every time. But it only ever fires when code is about to be
+ * written, so the question "what should we be USING that we aren't?" was never asked once.
+ *
+ * On 2026-07-22 the owner asked it manually, and the answer was sitting inside this very repository:
+ *
+ *     .metaharness/ — Darwin ran here on 2026-07-07.
+ *     It lifted the harness score 0.285 -> 0.765 (+168%) by evolving `reviewer`,
+ *     `memoryPolicy`, and `scorePolicy` — the exact surfaces we spent that night hand-building.
+ *     It promoted nothing, and sat idle for two weeks with OPENROUTER_API_KEY funded the whole time.
+ *
+ * His words: "If you knew it was out there, why the hell didn't you recommend it already? Why am I
+ * having to do this with you at 11:30 at night when we've been working together for three weeks?"
+ *
+ * The honest answer is that nothing in the system was obliged to look. v3.5 shipped advocacy that
+ * audits MEMORY health (corrupt stores, undrained queues, undistilled memories) and had no detector
+ * for a dormant capability at all — proactive about one category, blind to the one that mattered.
+ *
+ * DESIGN RULE, non-negotiable: every detector reports ONLY what it observed on THIS machine, with
+ * the observation as evidence. There is no hardcoded list of "cool features to suggest" — such a
+ * list would rot the week rUv ships again, and recommending a capability the user does not have is
+ * the same lie as any other (ADR-027).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { readLearnerState, verdict as learnerVerdict, STALE_DAYS } from './learning-enable.mjs';
+
+// NOTE: execFileSync was imported here and never used. It is deliberately not re-added. Shelling out
+// to `ruflo` for state is what made a read-only status check start a background daemon and write four
+// files into the user's HOME (see capability-registry.rufloBin) — an unused import of the tool that
+// causes that is an invitation, and this file is READ-ONLY by intent.
+
+const HOME = os.homedir();
+const DAY = 86_400_000;
+const argv = process.argv.slice(2);
+
+/** Newest mtime anywhere under a path — "when did this capability last actually do anything?" */
+function lastActivity(p, depth = 3) {
+  let newest = 0;
+  const walk = (d, lvl) => {
+    if (lvl > depth) return;
+    let entries = [];
+    try { entries = fs.readdirSync(d, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      const full = path.join(d, e.name);
+      try {
+        const st = fs.statSync(full);
+        if (st.mtimeMs > newest) newest = st.mtimeMs;
+        if (e.isDirectory()) walk(full, lvl + 1);
+      } catch { /* unreadable entry — skip */ }
+    }
+  };
+  try { if (fs.statSync(p).isDirectory()) walk(p, 0); else newest = fs.statSync(p).mtimeMs; } catch { return 0; }
+  return newest;
+}
+
+const daysSince = (ms) => (ms ? (Date.now() - ms) / DAY : null);
+
+/**
+ * DETECTOR: harness self-evolution that ran and then stopped.
+ *
+ * This is the ground-truth case the audit was built around. Detecting "installed" is worthless —
+ * `.metaharness/` existing tells you nothing. What matters is that it RAN, PRODUCED A REAL LIFT, and
+ * then went quiet, because that combination is invisible to every other surface and is pure
+ * unrealised value the user already paid for.
+ */
+export function detectDormantEvolution(repo = process.cwd()) {
+  const dir = path.join(repo, '.metaharness');
+  const archive = path.join(dir, 'archive.json');
+  if (!fs.existsSync(archive)) return null;
+
+  let entries = [];
+  try {
+    const raw = JSON.parse(fs.readFileSync(archive, 'utf8'));
+    entries = Array.isArray(raw) ? raw : (Object.values(raw).find(Array.isArray) || []);
+  } catch { return null; }
+  if (!entries.length) return null;
+
+  const rows = entries
+    .map((e) => ({
+      id: e?.variant?.id,
+      surface: e?.variant?.mutationSurface,
+      score: e?.score?.finalScore,
+      promoted: e?.score?.promoted === true,
+      task: e?.score?.taskSuccess,
+    }))
+    .filter((r) => typeof r.score === 'number');
+  if (!rows.length) return null;
+
+  const baseline = rows.find((r) => r.surface && r.score === Math.min(...rows.map((x) => x.score)));
+  const best = rows.reduce((a, b) => (b.score > a.score ? b : a), rows[0]);
+  const idleDays = daysSince(lastActivity(dir));
+  // EXCLUDE the baseline from the promoted count. The baseline is always "promoted" (it beats a
+  // parent score of 0), so counting it reports "1 variant promoted" for a run where every actual
+  // IMPROVEMENT was discarded — the precise flavour of confident-but-misleading reporting this
+  // whole audit exists to catch. Caught by diffing this detector against the raw archive.
+  const improvements = rows.filter((r) => r.id !== 'baseline');
+  const promotedCount = improvements.filter((r) => r.promoted).length;
+  const surfaces = [...new Set(rows.map((r) => r.surface).filter(Boolean))];
+
+  // ALSO read the MACHINE-WIDE champion, not just this repo's archive.
+  //
+  // The first version of this detector read only ./.metaharness/archive.json and reported "none of
+  // the improvements were kept" — true of that archive, and misleading about the machine, because
+  // ~/.claude-flow/harness-active-policy.json held a champion promoted a week LATER by a different
+  // run. Stating a repo-scoped fact in machine-scoped language is the same confident-but-wrong
+  // shape this whole audit exists to catch, so it gets caught here too.
+  let champion = null;
+  try {
+    const cp = path.join(HOME, '.claude-flow', 'harness-active-policy.json');
+    if (fs.existsSync(cp)) {
+      const c = JSON.parse(fs.readFileSync(cp, 'utf8'));
+      if (c && c.championId) {
+        champion = {
+          id: String(c.championId).slice(0, 20),
+          tier: c.provenanceTier || 'unknown',
+          appliedDaysAgo: c.appliedAt ? Math.round(daysSince(c.appliedAt)) : null,
+        };
+      }
+    }
+  } catch { /* absent or unreadable — report the repo-scoped truth alone */ }
+
+  // Only a capability that DEMONSTRATED value and then stopped is worth interrupting someone about.
+  if (!(idleDays > 3 && best.score > (baseline?.score ?? 0))) return null;
+
+  return {
+    id: 'capability:resume-harness-evolution',
+    title: 'Your harness improved itself, then stopped — and nobody was told',
+    severity: 'IMPORTANT',
+    evidence: [
+      { observed: `harness self-evolution ran in this repo and reached a score of ${best.score} from a baseline of ${baseline?.score ?? 0}` },
+      { observed: `${surfaces.length} policy surfaces were explored (${surfaces.slice(0, 4).join(', ')}${surfaces.length > 4 ? '…' : ''})` },
+      { observed: `this repo's run has been idle ${Math.round(idleDays)} days, and ${promotedCount === 0 ? `NONE of its ${improvements.length} improvements were kept — they all plateaued at the same score, so the promotion rule could not choose between them` : `${promotedCount} of ${improvements.length} improvements were kept`}` },
+      champion
+        ? { observed: `machine-wide, a champion policy IS active (${champion.id}…, provenance ${champion.tier}, applied ${champion.appliedDaysAgo} days ago) — so evolution is not entirely dead, it is just not running HERE` }
+        : { observed: 'no machine-wide champion policy is active either — nothing from any run is currently in force' },
+    ],
+    // Never overstate. A plateau is a known, documented condition with a known fix — say which.
+    why: promotedCount === 0
+      ? 'Every variant scored the same, so the lightweight promotion rule could not choose between them and kept none. This exact ceiling is documented upstream, and the fix is a graded benchmark gate rather than more evolution.'
+      : 'It produced promoted variants and then went quiet.',
+    detail: { best: best.score, baseline: baseline?.score ?? 0, idleDays: Math.round(idleDays), surfaces, promotedCount },
+  };
+}
+
+/** DETECTOR: a paid capability that is funded and unused — the most wasteful dormancy there is. */
+export function detectFundedButIdle(repo = process.cwd()) {
+  const funded = Boolean(process.env.OPENROUTER_API_KEY);
+  if (!funded) return null;
+  const dir = path.join(repo, '.metaharness');
+  if (!fs.existsSync(dir)) return null;
+  const idleDays = daysSince(lastActivity(dir));
+  if (!(idleDays > 7)) return null;
+  return {
+    id: 'capability:funded-but-idle',
+    title: 'You are paying for a capability that has not run in weeks',
+    severity: 'SUGGESTED',
+    evidence: [
+      { observed: 'an OpenRouter key is configured, which is what unlocks the write/evolve layer' },
+      { observed: `the last evolution activity in this repo was ${Math.round(idleDays)} days ago` },
+    ],
+    why: 'The expensive part is already paid for; only the running of it stopped.',
+    detail: { idleDays: Math.round(idleDays) },
+  };
+}
+
+/**
+ * DETECTOR: is the learner actually learning?
+ *
+ * ⚠️ THIS DETECTOR PREVIOUSLY SHIPPED A FALSE ALARM, and the correction is the most instructive
+ * thing in this file.
+ *
+ * The first version parsed `ruflo hooks list` and reported "26 learning hooks installed and every
+ * one is switched off". That was WRONG, and it was reported to the owner as a headline finding —
+ * including as the answer to his direct question about whether learning was on.
+ *
+ * What actually happens: `ruflo hooks list --format json` returns `{name, type, status:"active"}`
+ * and contains NO `enabled` key. The CLI's table renderer draws a column keyed `enabled`, reads
+ * `undefined`, and prints "No" 26 times. `ruflo hooks enable` does not exist. The list is a MENU of
+ * available hooks, not a dashboard of enabled ones.
+ *
+ * Meanwhile the real signal said the opposite the whole time: ~/.claude-flow/neural/stats.json held
+ * 457 trajectories and 457 patterns, last adapted 106 minutes earlier — DURING the session in which
+ * we told the owner learning was off.
+ *
+ * This is exactly L01 (verify through a channel CAPABLE of observing the truth) committed inside the
+ * detector written to catch L01. A human-readable CLI table is a PRESENTATION, and presentations
+ * drift from their payloads. Read the state file, or read `--format json` — never scrape a table.
+ *
+ * ADR-028 sets the false-alarm rate at ZERO and calls it non-negotiable: one false alarm costs more
+ * trust than ten true findings earn. So this detector now reports only what a state file proves, and
+ * stays SILENT when it cannot tell.
+ */
+export function detectLearnerIdle() {
+  // DELEGATED, for the same reason capability-registry delegates: there must be exactly ONE reading
+  // of stats.json on this machine. The hand-rolled version here repeated the registry's schema-drift
+  // bug in its most damaging form — `Number(s.trajectoriesRecorded ?? 0)` yields 0 when rUv renames
+  // the field, and 0-and-0 fell straight into the IMPORTANT branch below. The result would have been
+  // an alarming "Your learner has never recorded anything" fired at every user at once, about a
+  // learner that was working perfectly. ADR-028 puts the acceptable false-alarm rate at ZERO and
+  // calls it non-negotiable; a detector that turns an upstream rename into a machine-wide accusation
+  // is the worst possible way to violate that.
+  //
+  // readLearnerState's `num()` returns null rather than 0 for an unreadable counter, so drift now
+  // arrives as UNKNOWN_SHAPE — and this detector stays SILENT on it, because "I cannot read the
+  // counters" is not a dormant capability and there is nothing for the user to act on.
+  const learner = readLearnerState({ home: HOME });
+  const v = learnerVerdict(learner);
+  const { trajectories, patterns } = learner;
+
+  // NO_LEARNER_STATE / CORRUPT / UNKNOWN_SHAPE / UNKNOWN_PARTIAL: nothing provable, so say nothing.
+  // Silence here is correct — an audit that speaks up when it cannot see is how false alarms are
+  // manufactured. UNKNOWN_PARTIAL (one counter renamed upstream, one still readable) is deliberately
+  // in that list: the readable half cannot settle a question that needs both, and half a measurement
+  // is not grounds for telling somebody their learner is broken.
+  if (v.code === 'INITIALISED_EMPTY') {
+    // A learner that has genuinely, measurably recorded nothing is dormant and worth saying so.
+    return {
+      id: 'capability:learner-never-ran',
+      title: 'Your learner has never recorded anything',
+      severity: 'IMPORTANT',
+      evidence: [
+        { observed: 'the learner\'s own state file exists, carries the counters this version understands, and both read 0' },
+      ],
+      why: 'The learning machinery is present and has never been fed, so nothing you do is being turned into reusable experience.',
+      detail: { trajectories, patterns },
+    };
+  }
+
+  if (v.code === 'IDLE') {
+    // Recording, but nothing recently — a real, provable dormancy. STALE_DAYS is imported, not
+    // re-typed: this file used its own literal 7 while learning-enable used STALE_DAYS, which is two
+    // definitions of "idle" waiting to drift apart.
+    const idleDays = Math.floor(learner.ageMinutes / 1440);
+    return {
+      id: 'capability:learner-gone-quiet',
+      title: 'Your learner has gone quiet',
+      severity: 'SUGGESTED',
+      evidence: [
+        { observed: `${trajectories} trajectories and ${patterns} patterns recorded, but the last adaptation was ${idleDays} days ago (idle past ${STALE_DAYS})` },
+      ],
+      why: 'It learned before and stopped, so recent work is not becoming reusable experience.',
+      detail: { trajectories, patterns, idleDays },
+    };
+  }
+
+  // Learning is live, or unreadable. Report NOTHING — a healthy machine must produce no findings at
+  // all, and an unreadable one must not be described as unhealthy.
+  return null;
+}
+
+export const DETECTORS = [detectDormantEvolution, detectFundedButIdle, detectLearnerIdle];
+
+/**
+ * Run every detector. Never throws — an advisory surface must not break the thing that calls it.
+ *
+ * BUT IT NO LONGER SWALLOWS THE FAILURE EITHER, and that distinction is the finding.
+ *
+ * The old `catch {}` was correct about one thing — a single broken detector must not silence the
+ * other two — and catastrophically wrong about what to do next. With all three detectors forced to
+ * throw (EACCES / bad JSON / ENOENT), this function returned `[]`, and `[]` is exactly what a
+ * perfectly healthy machine returns. The CLI then printed:
+ *
+ *     "No dormant capability found on this machine. That is a real answer, not a shrug —
+ *      every detector reports only what it observed here."
+ *
+ * Total instrument failure, rendered as a confident all-clear, with copy that explicitly forecloses
+ * the doubt. A newcomer whose file permissions differ from ours gets told their machine is fine by a
+ * system that could not see their machine at all. That is the unknown-as-a-measurement lie in its
+ * purest form — it just arrives as silence instead of as the word "off".
+ *
+ * So failures are now COUNTED and RETURNED. The caller is obliged to say how many of the checks
+ * actually ran before it characterises the result.
+ */
+export function auditCapabilities(repo = process.cwd()) {
+  const findings = [];
+  const failures = [];
+  for (const d of DETECTORS) {
+    try { const f = d(repo); if (f) findings.push(f); }
+    catch (e) { failures.push({ detector: d.name || 'anonymous detector', reason: String(e?.message || e).split('\n')[0].slice(0, 120) }); }
+  }
+  return { findings, failures, ran: DETECTORS.length - failures.length, total: DETECTORS.length };
+}
+
+// ── CLI ──────────────────────────────────────────────────────────────────────────────────────────
+const invokedDirectly = process.argv[1] && path.resolve(process.argv[1]).endsWith('capability-audit.mjs');
+if (invokedDirectly) {
+  const audit = auditCapabilities(argv.includes('--repo') ? argv[argv.indexOf('--repo') + 1] : process.cwd());
+  const { findings, failures, ran, total } = audit;
+  if (argv.includes('--json')) { console.log(JSON.stringify(audit, null, 2)); process.exit(0); }
+
+  // Broken instruments are reported BEFORE any verdict, because they change what the verdict means.
+  for (const f of failures) console.log(`\n  ! ${f.detector} could not run: ${f.reason}`);
+
+  if (!findings.length) {
+    // The all-clear is only offered when every check actually ran. Otherwise the honest line is that
+    // we could not look — never "nothing found", which reads identically and is not the same claim.
+    console.log(failures.length
+      ? `\n  ${ran} of ${total} checks ran, and they found nothing dormant. The ${failures.length} that\n`
+        + '  could not run are listed above — this is NOT an all-clear, because part of the machine\n'
+        + '  was not examined at all.\n'
+      : '\n  No dormant capability found on this machine. That is a real answer, not a shrug —\n'
+        + `  all ${ran} of ${total} checks ran, and every detector reports only what it observed here.\n`);
+    process.exit(0);
+  }
+  const n = findings.length;
+  console.log(`\n  ${n} ${n === 1 ? 'capability' : 'capabilities'} you already own ${n === 1 ? 'is' : 'are'} not being used:\n`);
+  for (const f of findings) {
+    console.log(`  [${f.severity}] ${f.title}`);
+    for (const e of f.evidence) console.log(`      · ${e.observed}`);
+    console.log(`      why: ${f.why}\n`);
+  }
+}