ruvnet-brain 3.9.134-dev → 4.0.2

package/scripts/stamp-existing-rvf-generations.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// Bind every existing canonical RVF to the current Brain release without re-embedding. Optional
+// legacy pruning is fail-closed: the canonical passages/meta and big RVF sidecars must exist first.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { writeRvfGeneration } from './rvf-generation.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const KB = path.join(ROOT, 'kb');
+const PRUNE = process.argv.includes('--prune-legacy');
+const stores = fs.readdirSync(KB)
+  .filter((file) => file.endsWith('.big.rvf'))
+  .map((file) => file.slice(0, -'.big.rvf'.length))
+  .sort();
+
+let pruned = 0;
+for (const store of stores) {
+  const embedFile = path.join(KB, `${store}.big.rvf.embed.json`);
+  const idmapFile = path.join(KB, `${store}.big.rvf.idmap.json`);
+  const passagesFile = path.join(KB, `${store}.passages.jsonl`);
+  const metaFile = path.join(KB, `${store}.meta.json`);
+  for (const required of [embedFile, idmapFile, passagesFile, metaFile]) {
+    if (!fs.existsSync(required)) throw new Error(`${store}: missing ${path.basename(required)}; refusing to stamp/prune`);
+  }
+  const embed = JSON.parse(fs.readFileSync(embedFile, 'utf8'));
+  const generation = writeRvfGeneration({
+    dir: KB,
+    store,
+    model: embed.model,
+    dimensions: embed.dimensions,
+    sourceCommit: null,
+  });
+  console.log(`[generation] ${store}: ${generation.sha256.slice(0, 16)}… ${generation.bytes} bytes`);
+
+  if (PRUNE) {
+    for (const legacy of [
+      `${store}.rvf`,
+      `${store}.rvf.idmap.json`,
+      `${store}.rvf.embed.json`,
+      `${store}.big.passages.jsonl`,
+      `${store}.big.meta.json`,
+    ]) {
+      const file = path.join(KB, legacy);
+      if (fs.existsSync(file)) {
+        fs.rmSync(file);
+        pruned++;
+      }
+    }
+  }
+}
+console.log(`[generation] stamped ${stores.length} canonical RVFs${PRUNE ? `; pruned ${pruned} legacy files` : ''}`);

package/scripts/stamp-sweep.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+// scripts/stamp-sweep.mjs — ADR-056 §2. The ONE-TIME half of the owner's first rule.
+//
+//   node scripts/stamp-sweep.mjs             report: every authored .md, its stamp state, its verdict
+//   node scripts/stamp-sweep.mjs --apply     write the stamps git can prove
+//   node scripts/stamp-sweep.mjs --json      machine-readable, same evaluation
+//
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+// WHY THIS EXISTS SEPARATELY FROM THE HOOK. `plugin/scripts/md-stamp.mjs` maintains stamps when a
+// file is edited. That is necessary and it is not sufficient, and the adversarial duel on ADR-056
+// said why in one sentence:
+//
+//     "Insert-on-touch fires only when a file IS edited — so it reaches actively-edited files, the
+//      ones least likely to be stale, and never reaches a stale file, BY DEFINITION OF STALE."
+//
+// The owner's rule is about the documents sitting on disk TODAY: "so I know if they're stale or
+// current actually in there so that I can read it, not just you." Measured 2026-07-27: 166 of 239
+// .md files carry no stamp. The hook would have reached approximately none of them. This reaches
+// them once; the hook keeps them true afterwards.
+//
+// ONE IMPLEMENTATION, TWO CALLERS. Every placement decision lives in md-stamp.mjs (`ensureStamp`,
+// `stampInsertionPoint`, `hasStamp`) and is imported here. A second copy of "where does the stamp
+// go" is the exact drift this whole ADR is about.
+//
+// NOTHING IS EVER INVENTED — the load-bearing rule, inherited verbatim from doc-currency.mjs:
+//   · no git history        -> SKIP and say so. A file git cannot date does not get a date.
+//   · dirty working tree    -> SKIP. The last commit's date is not the date of the current contents,
+//                             and stamping it would assert a freshness that is not true.
+//   · already stamped       -> SKIP, byte-for-byte untouched.
+//   · unrecognised prologue -> SKIP. MDX exports, HTML comments, license banners: an insertion that
+//                             corrupts someone's document is worse than a document with no date.
+//
+// GENERATED MARKDOWN IS NOT AN AUTHORED DOCUMENT. 96 of the 166 unstamped files live under kb/,
+// dist/ and .agentic-qe/logs/. Stamping machine output is noise wearing the costume of signal, and
+// it would bury the ~70 files where the stamp actually carries information.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { ensureStamp, hasStamp, stampInsertionPoint } from '../plugin/scripts/md-stamp.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+export const REPO_ROOT = path.resolve(HERE, '..');
+
+// Directories whose markdown is GENERATED, vendored, or archival — never authored by a human here.
+export const EXCLUDED = [
+  'node_modules', '.git', 'kb', 'dist', 'clones', 'archive', '.agentic-qe',
+  'coverage', '.next', 'build', 'tmp', '.swarm',
+];
+
+function git(root, args) {
+  const r = spawnSync('git', args, { cwd: root, encoding: 'utf8' });
+  return { ok: r.status === 0, out: (r.stdout || '').trim() };
+}
+
+/** Every authored .md tracked by git. Untracked files are out of scope — git cannot date them. */
+export function authoredDocs(root = REPO_ROOT) {
+  const ls = git(root, ['ls-files', '--', '*.md']);
+  if (!ls.ok) return [];
+  return ls.out.split('\n').filter(Boolean).filter((rel) => {
+    const segs = rel.split('/');
+    return !segs.some((s) => EXCLUDED.includes(s));
+  });
+}
+
+/** Dates git can PROVE for this path. Absent is absent; nothing is inferred from a neighbour. */
+export function gitDates(root, rel) {
+  const created = git(root, ['log', '--follow', '--diff-filter=A', '--format=%cs', '-1', '--', rel]);
+  const updated = git(root, ['log', '-1', '--format=%cs', '--', rel]);
+  const dirty = git(root, ['status', '--porcelain', '--', rel]);
+  return {
+    created: created.ok && /^\d{4}-\d{2}-\d{2}$/.test(created.out) ? created.out : null,
+    updated: updated.ok && /^\d{4}-\d{2}-\d{2}$/.test(updated.out) ? updated.out : null,
+    dirty: Boolean(dirty.out),
+  };
+}
+
+export function evaluate(root = REPO_ROOT, docs = authoredDocs(root)) {
+  const rows = [];
+  for (const rel of docs) {
+    const abs = path.join(root, rel);
+    let content;
+    try { content = fs.readFileSync(abs, 'utf8'); } catch { continue; }
+
+    if (hasStamp(content)) { rows.push({ rel, verdict: 'already-stamped' }); continue; }
+
+    const at = stampInsertionPoint(content);
+    if (!at) { rows.push({ rel, verdict: 'skip-prologue', why: 'prologue shape not recognised — refusing to insert' }); continue; }
+
+    const d = gitDates(root, rel);
+    if (d.dirty) { rows.push({ rel, verdict: 'skip-dirty', why: 'working tree modified — the last commit date is not the date of these contents' }); continue; }
+    if (!d.updated) { rows.push({ rel, verdict: 'skip-no-history', why: 'no commits — no date can be derived, and none will be invented' }); continue; }
+
+    const next = ensureStamp(content, { updated: d.updated, created: d.created });
+    if (next === content) { rows.push({ rel, verdict: 'no-change' }); continue; }
+    rows.push({ rel, verdict: 'would-stamp', placement: at.kind, updated: d.updated, created: d.created, next });
+  }
+  return rows;
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const apply = argv.includes('--apply');
+  const asJson = argv.includes('--json');
+  const rows = evaluate();
+
+  if (asJson) {
+    console.log(JSON.stringify(rows.map(({ next, ...r }) => r), null, 2));
+    return 0;
+  }
+
+  const by = (v) => rows.filter((r) => r.verdict === v);
+  const todo = by('would-stamp');
+
+  console.log(`\nstamp sweep — ${rows.length} authored document(s) under ${REPO_ROOT}\n`);
+  for (const r of todo) {
+    const c = r.created && r.created !== r.updated ? `, created ${r.created}` : '';
+    console.log(`  ${apply ? '[stamped] ' : '[would stamp]'} ${r.rel} — updated ${r.updated}${c} (derived-from-git, ${r.placement})`);
+    if (apply) {
+      try { fs.writeFileSync(path.join(REPO_ROOT, r.rel), r.next); }
+      catch (e) { console.log(`  [failed]  ${r.rel}: ${e.message}`); }
+    }
+  }
+
+  const skipped = [...by('skip-prologue'), ...by('skip-dirty'), ...by('skip-no-history')];
+  if (skipped.length) {
+    console.log(`\n  ${skipped.length} deliberately NOT stamped — no date will be invented:\n`);
+    for (const s of skipped) console.log(`    ○ ${s.rel}\n       ${s.why}`);
+  }
+
+  console.log(`\nsummary: ${by('already-stamped').length} already stamped · ${todo.length} `
+    + `${apply ? 'stamped' : 'stampable'} · ${skipped.length} skipped (honestly)`);
+  if (!apply && todo.length) console.log('\ndry run — nothing written. Re-run with --apply to write them.');
+  console.log('Dates are only ever copied out of git; nothing is reconstructed.\n');
+  return 0;
+}
+
+function isMain() {
+  try { return process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url); }
+  catch { return false; }
+}
+
+if (isMain()) process.exit(main());

package/scripts/status-honesty.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+// scripts/status-honesty.mjs — THE ANTI-FAKING GATE (ADR-0024). No script may ASSERT a terminal
+// success status; success must be DERIVED from a verifiable artifact.
+//
+// WHY (Stuart, 2026-07-18, after the word "faking" kept coming back): "The fact that you're still
+// creating code in a sloppy way that allows it to fake results is toxic and needs to be blown out of
+// the system." The historical sin: issue-fix.mjs once hardcoded status:'completed' for issues it
+// never touched — no branch, no comment, no artifact. The class, per rUv's own architecture:
+//   - a status FIELD can be forged; only RE-DERIVATION from the real artifact catches it
+//     (ruvector proof-gate #506: "a structural scan cannot catch a structurally-valid forgery");
+//   - verification must pin to the trusted source, never the self-asserted field
+//     (ruflo signed-artifact: "an attacker controls that field; pinning to it is a no-op").
+//
+// LAYER 1 (this file): a lexical scanner over every automation script. It flags any WRITE of a
+// terminal success literal (status:'completed', state:"ok", outcome:'success', …) whose statement
+// shows NO derivation marker — no captured exit code, no comparison, no ternary on a runtime result,
+// no registered verifier call. A comment cannot satisfy it; only a derivation expression can.
+// SCOPE IS DELIBERATE: terminal RECEIPT/STATUS tokens only (the historical sin's exact shape), not
+// generic `ok: true` returns — a gate that cries wolf gets disabled, which is worse than no gate.
+// KNOWN RESIDUAL (documented, accepted): a lexical layer can be gamed by computed keys or an
+// always-true verifier — that is why Layer 2 (behavioral fixtures in derived-status.test.mjs)
+// executes the real wrapper and the real outcome-verifier, and why the known-bad fixture must FAIL
+// on every run. Text can lie; execution can't.
+//
+// Usage: node scripts/status-honesty.mjs            exit 0 = clean, 1 = violations (printed)
+//        imported by tests/unit/derived-status.test.mjs (scanSource / scanRepo)
+
+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)), '..');
+
+// Terminal success literals — the exact shape of the historical sin. Word-bounded, quote-flexible.
+const SUCCESS_WRITES = [
+  /\bstatus\s*[:=]\s*['"](completed|success|succeeded|done|fixed|shipped|passed)['"]/,
+  /\bstate\s*[:=]\s*['"](ok|completed|success|succeeded|passed)['"]/,
+  /\boutcome\s*[:=]\s*['"](success|succeeded|completed)['"]/,
+  /"state"\s*:\s*"(ok|completed|success)"/, // literal JSON in sh heredocs/printf
+];
+
+// Derivation markers: evidence the assignment is CONDITIONAL on a runtime result. The registry is
+// extended by PR — a new receipt-writer fails this gate by default until its derivation is named.
+const DERIVATION_MARKERS = [
+  '=== 0', '!== 0', '== 0', '!= 0', '-eq 0', '-ne 0', // exit-code comparisons (js + sh)
+  '? ', // ternary on a captured result (paired with the comparisons above in practice)
+  '.has(', // SUCCESS_OUTCOMES.has(...) — the issue-fix standard
+  'r.status', 'res.status', 'res.ok', 'r.ok', '.exitCode', 'exit_code', 'status ===', 'code -eq',
+  'remoteBranchExists', 'installedVersion', 'verifyOutcome', 'delivered', 'succeeded ?', 'sent ===',
+];
+
+/** Scan one source text. Returns violations: [{line, text}] — success literal with no derivation. */
+export function scanSource(src, _name = '(inline)') {
+  const violations = [];
+  const lines = src.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const t = line.trim();
+    if (t.startsWith('//') || t.startsWith('#') || t.startsWith('*')) continue; // comments assert nothing
+    if (!SUCCESS_WRITES.some((re) => re.test(line))) continue;
+    // The statement window: this line ± 2 (multi-line object literals / sh case arms).
+    const windowText = lines.slice(Math.max(0, i - 2), i + 3).join('\n');
+    if (DERIVATION_MARKERS.some((m) => windowText.includes(m))) continue;
+    violations.push({ line: i + 1, text: t.slice(0, 160) });
+  }
+  return violations;
+}
+
+const SCAN_DIRS = ['scripts', 'plugin/scripts', 'scripts/git-hooks'];
+const EXT = /\.(mjs|cjs|js|sh)$/;
+const EXEMPT = new Set([
+  // the scanner itself (its pattern table would self-flag) and test fixtures (known-bad lives there)
+  'scripts/status-honesty.mjs',
+]);
+
+/** Scan the repo. Returns [{file, violations}] for files with hits. */
+export function scanRepo(root = ROOT) {
+  const out = [];
+  for (const dir of SCAN_DIRS) {
+    const abs = path.join(root, dir);
+    if (!fs.existsSync(abs)) continue;
+    for (const f of fs.readdirSync(abs)) {
+      if (!EXT.test(f)) continue;
+      const rel = path.join(dir, f);
+      if (EXEMPT.has(rel)) continue;
+      const v = scanSource(fs.readFileSync(path.join(root, rel), 'utf8'), rel);
+      if (v.length) out.push({ file: rel, violations: v });
+    }
+  }
+  return out;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const bad = scanRepo();
+  if (bad.length) {
+    console.error('status-honesty: ASSERTED (underived) terminal success literals found:\n');
+    for (const b of bad) for (const v of b.violations) console.error(`  ${b.file}:${v.line}  ${v.text}`);
+    console.error('\nA success status must DERIVE from a verifiable artifact (exit code, re-checked branch/comment, re-read file). Name the derivation in the same statement, or record the honest failure.');
+    process.exit(1);
+  }
+  console.log('status-honesty: clean — every terminal success literal is derivation-conditioned.');
+}

package/scripts/sync-version.mjs

@@ -0,0 +1,217 @@
+// sync-version.mjs — propagate the ONE source-of-truth version (plugin.json) into the files that must
+// carry a literal, and (with --check) fail if any surface has drifted. SEC-0010 #2 / ADR-0009 decision 1.
+//
+//   node scripts/sync-version.mjs           # write plugin.json's version into all inheriting files
+//   node scripts/sync-version.mjs --check    # CI mode: exit 1 if any surface disagrees (writes nothing)
+//
+// The ONE hand-edited number is plugin/.claude-plugin/plugin.json `version`. Bump it there, run this,
+// and every other surface follows. `--check` in CI makes drift impossible to merge.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getVersion } from './version.mjs';
+import { getVersionTag } from './version.mjs';
+import { verifyRvfGenerations } from './rvf-generation.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const CHECK = process.argv.includes('--check');
+const V = getVersion();
+const TODAY = new Date().toISOString().slice(0, 10);
+let drift = 0;
+
+export function readLockVersion(s) {
+  const doc = JSON.parse(s);
+  const top = doc.version ?? null;
+  const root = doc.packages?.['']?.version ?? null;
+  return top === root ? top : `mixed(${top}, ${root})`;
+}
+
+export function writeLockVersion(s, version) {
+  const doc = JSON.parse(s);
+  doc.version = version;
+  if (doc.packages?.['']) doc.packages[''].version = version;
+  return `${JSON.stringify(doc, null, 2)}\n`;
+}
+
+// Each target: a file, a regex to find the version-bearing line, and the corrected line.
+const targets = [
+  { // Codex plugin manifest — same product, same release train as the Claude manifest
+    file: 'plugin/.codex-plugin/plugin.json',
+    get: (s) => (JSON.parse(s).version),
+    set: (s) => s.replace(/("version"\s*:\s*)"[^"]+"/, `$1"${V}"`),
+  },
+  { // npm installer package — inherits the product version (publish in lockstep)
+    file: 'package.json',
+    get: (s) => (JSON.parse(s).version),
+    set: (s) => s.replace(/("version"\s*:\s*)"[^"]+"/, `$1"${V}"`),
+  },
+  { // npm lock metadata is part of the packed candidate lineage too
+    file: 'package-lock.json',
+    get: readLockVersion,
+    set: (s) => writeLockVersion(s, V),
+  },
+  { // the brain bundle's product-version stamp (corpus provenance stays in SOURCE.json separately)
+    file: 'data/manifest.json',
+    get: (s) => { const m = s.match(/"brainVersion"\s*:\s*"([^"]+)"/); return m ? m[1] : null; },
+    set: (s) => s.replace(/("brainVersion"\s*:\s*)"[^"]+"/, `$1"${V}"`),
+  },
+  { // the MCP server's advertised version
+    file: 'kb/package.json',
+    get: (s) => (JSON.parse(s).version),
+    set: (s) => s.replace(/("version"\s*:\s*)"[^"]+"/, `$1"${V}"`),
+  },
+  { // the human primer's header stamp — shipped in the bundle, read by real users
+    // (drifted to v2.0.0 during the 2.0.1 release because no target covered it — 2026-07-10 gremlin hunt)
+    file: 'primer/ruvnet-primer.md',
+    get: (s) => { const m = s.match(/Brain version: v([^\s·`]+)/); return m ? m[1] : null; },
+    set: (s) => s.replace(/(Brain version: v)[^\s·`]+/, `$1${V}`),
+  },
+  { // the live explainer page carries the version twice (JSON-LD softwareVersion + the status badge).
+    // get() returns the value only when BOTH agree; a mismatch reports as drift too.
+    file: 'explainer/index.html',
+    get: (s) => {
+      const ld = s.match(/"softwareVersion"\s*:\s*"([^"]+)"/)?.[1] ?? null;
+      const badge = s.match(/&middot;\s*v([0-9][^\s<]*)</)?.[1] ?? null;
+      return ld === badge ? ld : `mixed(${ld}, ${badge})`;
+    },
+    set: (s) => s
+      .replace(/("softwareVersion"\s*:\s*)"[^"]+"/, `$1"${V}"`)
+      .replace(/(&middot;\s*v)[0-9][^\s<]*</, `$1${V}<`),
+  },
+];
+
+for (const t of targets) {
+  const p = path.join(ROOT, t.file);
+  if (!fs.existsSync(p)) continue;
+  const s = fs.readFileSync(p, 'utf8');
+  const cur = t.get(s);
+  if (cur === V) continue;
+  if (CHECK) { console.error(`[version] DRIFT: ${t.file} = ${cur}, expected ${V}`); drift++; }
+  else { fs.writeFileSync(p, t.set(s)); console.log(`[version] ${t.file}: ${cur} -> ${V}`); }
+}
+
+// The installed knowledge bundle and the checksum-bound RVF generation ledger are release
+// surfaces too. They are generated artifacts, so tolerate absence in a source-only checkout; when
+// present they must carry the same bare field and v-prefixed tag as npm/GitHub.
+for (const rel of ['kb/RVF-GENERATIONS.json']) {
+  const p = path.join(ROOT, rel);
+  if (!fs.existsSync(p)) continue;
+  const doc = JSON.parse(fs.readFileSync(p, 'utf8'));
+  const expectedTag = getVersionTag();
+  const bad = doc.brainVersion !== V || doc.releaseTag !== expectedTag;
+  if (!bad) continue;
+  if (CHECK) {
+    console.error(`[version] DRIFT: ${rel} = ${doc.brainVersion}/${doc.releaseTag}, expected ${V}/${expectedTag}`);
+    drift++;
+  } else {
+    doc.brainVersion = V;
+    doc.releaseTag = expectedTag;
+    fs.writeFileSync(p, `${JSON.stringify(doc, null, 2)}\n`);
+    console.log(`[version] ${rel}: -> ${V}/${expectedTag}`);
+  }
+}
+
+if (CHECK && fs.existsSync(path.join(ROOT, 'kb/RVF-GENERATIONS.json'))) {
+  const kbDir = path.join(ROOT, 'kb');
+  const requiredStores = fs.readdirSync(kbDir)
+    .filter((file) => file.endsWith('.big.rvf'))
+    .map((file) => file.slice(0, -'.big.rvf'.length));
+  // CI/source-only clones intentionally omit the gitignored RVF binaries. In that shape, validate
+  // the committed ledger's version fields but defer byte checks to bundle assembly, where the RVFs
+  // are present. A checkout containing any canonical RVF remains fail-closed for every ledger row.
+  const { failures } = verifyRvfGenerations(kbDir, {
+    requiredStores,
+    allowMissingFiles: requiredStores.length === 0,
+  });
+  for (const failure of failures) {
+    console.error(`[version] RVF GENERATION DRIFT: ${failure}`);
+    drift++;
+  }
+}
+
+// README: the heading badge encodes the product version twice — the human-readable alt text
+// ("RuvNet Brain version X — updated Y") and the shields.io URL token ("version_X-updated_Y", with
+// hyphens escaped as `--`). --check flags version drift; write-mode now FIXES it in place (version
+// only — the nightly publisher owns the `updated_` timestamp), so `--check` and a plain write agree.
+{
+  const p = path.join(ROOT, 'README.md');
+  const s = fs.readFileSync(p, 'utf8');
+  const m = s.match(/version_([0-9][^-\s)]*(?:--[^-\s)]*)*)-updated_/); // inside the badge URL
+  const badgeVer = m ? m[1].replace(/--/g, '-') : null;
+  if (badgeVer !== V) {
+    if (CHECK) { console.error(`[version] DRIFT: README badge = ${badgeVer}, expected ${V}`); drift++; }
+    else {
+      const vBadge = V.replace(/-/g, '--'); // shields.io escapes a literal hyphen as `--`
+      const next = s
+        // URL token:  version_<ver>-updated_<timestamp>  → swap <ver>, keep the timestamp
+        .replace(/(version_)[0-9][^-\s)]*(?:--[^-\s)]*)*(-updated_)/, `$1${vBadge}$2`)
+        // alt text:  "RuvNet Brain version <ver> — updated <timestamp>" → swap <ver>, keep the timestamp
+        .replace(/(RuvNet Brain version )\S+( — updated )/, `$1${V}$2`);
+      if (next !== s) { fs.writeFileSync(p, next); console.log(`[version] README badge: ${badgeVer} -> ${V}`); }
+    }
+  }
+}
+
+// Guard: no stray hardcoded product-version literal anywhere in the source tree — every code path must
+// read getVersion() (or inherit a synced literal via the `targets` above / the README badge). Rather than
+// a fixed 3-file allowlist (which silently missed strays in every other file), walk the WHOLE tree and
+// scan source files, skipping the regenerable / external / VCS dirs. A quoted vX.Y.Z / X.Y.Z(-dev)? literal
+// is flagged when it IS the current product version (bare or `v`-tagged) OR is a `-dev` prerelease literal —
+// i.e. anything that is meant to be the product version, not just the `-dev` form the old guard caught.
+// A line can opt out with `sync-version-ignore` (one documented last-ditch fallback); the version toolchain
+// itself is exempt because it legitimately embeds version strings in doc examples + unit-test fixtures.
+if (CHECK) {
+  // `worktrees` (2026-07-27): parallel agents run in git worktrees under .claude/worktrees/, which
+  // is GITIGNORED (.gitignore:110) but still on disk — and this walker reads the FILESYSTEM, not
+  // git's index. So every agent worktree's copy of the repo got scanned for version literals and
+  // the pre-push gate refused a legitimate push over version strings inside transient checkouts
+  // that ship to nobody. A shipping-surface scan must not see a scratch copy of itself.
+  const SKIP_DIRS = new Set(['node_modules', 'clones', 'dist', '.git', 'worktrees']);
+  const CODE_EXT = new Set(['.mjs', '.js', '.cjs', '.ts', '.sh']);
+  const EXEMPT = new Set([ // the version machinery defines/tests these literals — linting them = false positive
+    'scripts/version.mjs', 'scripts/version.test.mjs', 'scripts/sync-version.mjs', 'scripts/self-update.mjs',
+    // The unit tests moved from scripts/ to tests/unit/ but this list did not follow them, so `--check`
+    // has been failing on its OWN test fixtures — a gate nobody could pass, which is a gate nobody heeds.
+    'tests/unit/version.test.mjs', 'tests/unit/sync-version-drift.test.mjs', 'tests/unit/self-update-plan.test.mjs',
+    // Asserts stripTag('v1.14.1-dev') === '1.14.1-dev' — the literals ARE the fixture.
+    'tests/unit/version-tag-vs-field.test.mjs',
+  ]);
+  const litRe = /['"`](v?\d+\.\d+\.\d+(?:-dev)?)['"`]/g;
+
+  const walk = (dir) => {
+    const files = [];
+    for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+      const abs = path.join(dir, ent.name);
+      if (ent.isDirectory()) { if (!SKIP_DIRS.has(ent.name)) files.push(...walk(abs)); }
+      else if (ent.isFile() && CODE_EXT.has(path.extname(ent.name))) files.push(abs);
+    }
+    return files;
+  };
+
+  const strays = [];
+  for (const abs of walk(ROOT)) {
+    // EXEMPT keys are forward-slash; path.relative() yields backslashes on Windows, which made the
+    // guard flag its own exempt fixtures there — the same gate-nobody-can-pass failure as above.
+    const rel = path.relative(ROOT, abs).split(path.sep).join('/');
+    if (EXEMPT.has(rel)) continue;
+    fs.readFileSync(abs, 'utf8').split('\n').forEach((ln, i) => {
+      if (ln.includes('sync-version-ignore')) return;
+      for (const mm of ln.matchAll(litRe)) {
+        const lit = mm[1].replace(/^v/, '');
+        if (lit === V || lit.endsWith('-dev')) strays.push(`${rel}:${i + 1}: ${ln.trim()}`);
+      }
+    });
+  }
+  if (strays.length) {
+    console.error(`[version] DRIFT: ${strays.length} stray hardcoded version literal(s) — read getVersion() instead:`);
+    for (const s of strays) console.error(`    ${s}`);
+    drift++;
+  }
+}
+
+if (CHECK) {
+  if (drift) { console.error(`\n[version] ${drift} surface(s) drifted from the source of truth (${V}). Run: node scripts/sync-version.mjs`); process.exit(1); }
+  console.log(`[version] all surfaces agree on ${V} ✓`);
+} else {
+  console.log(`[version] synced everything to ${V} (source: plugin/.claude-plugin/plugin.json)`);
+}

package/scripts/token-report.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+// scripts/token-report.mjs — the read side of the token meter (ADR-0011 token_cost_efficiency).
+//
+// The brain injects context via hooks (ground-ruvnet.sh / session-start.sh) and serves retrieval
+// via MCP (forge-mcp-all.mjs); each of those appends one JSON line per fire to
+// .ruvnet-brain/token-ledger.jsonl with the REAL measured size of what it emitted. This script
+// aggregates that ledger into a plain-text table: per class, the fire count and the p50/p95 byte
+// sizes plus an estimated token total — HONESTLY labeled an estimate (tokens ≈ bytes/4; we measure
+// bytes exactly, we do not run a tokenizer). Zero dependencies, Node built-ins only.
+//
+//   node scripts/token-report.mjs                       # reads ./.ruvnet-brain/token-ledger.jsonl
+//   node scripts/token-report.mjs --ledger <path>       # explicit ledger (tests use this)
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const argv = process.argv.slice(2);
+const ledgerIdx = argv.indexOf('--ledger');
+// The canonical ledger is user-level (issue #36 — writing per-CWD scattered hidden directories into
+// users' project trees). A legacy per-project ledger is still READ when one exists and the canonical
+// one does not, so nobody's existing measurements silently vanish in the move.
+const CANONICAL_LEDGER = path.join(process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache'), 'ruvnet-brain', 'token-ledger.jsonl');
+const LEGACY_LEDGER = path.join(process.cwd(), '.ruvnet-brain', 'token-ledger.jsonl');
+const LEDGER =
+  ledgerIdx !== -1 && argv[ledgerIdx + 1]
+    ? argv[ledgerIdx + 1]
+    : (fs.existsSync(CANONICAL_LEDGER) || !fs.existsSync(LEGACY_LEDGER) ? CANONICAL_LEDGER : LEGACY_LEDGER);
+
+// Nearest-rank percentile on a pre-sorted ascending array — the standard textbook definition,
+// chosen because it always returns a value that actually occurred (no interpolation to invent one).
+function percentile(sortedAsc, p) {
+  if (sortedAsc.length === 0) return 0;
+  const rank = Math.max(1, Math.ceil((p / 100) * sortedAsc.length));
+  return sortedAsc[rank - 1];
+}
+
+const estTokens = (bytes) => Math.round(bytes / 4);
+
+if (!fs.existsSync(LEDGER)) {
+  console.log(`meter: no data yet (${LEDGER} not found — it appears after the first hook/MCP fire)`);
+  process.exit(0);
+}
+
+// One group per class: hook lines group by their prompt-class, MCP lines by tool name — the label
+// says which side of the brain spent the bytes.
+const groups = new Map();
+let skipped = 0;
+for (const line of fs.readFileSync(LEDGER, 'utf8').split('\n')) {
+  if (!line.trim()) continue;
+  let e;
+  try { e = JSON.parse(line); } catch { skipped++; continue; }
+  const bytes = Number(e?.bytes);
+  if (!e || !e.source || !Number.isFinite(bytes)) { skipped++; continue; }
+  const label = e.source === 'mcp' ? `mcp:${e.tool || 'unknown'}` : `hook:${e.class || 'unknown'}`;
+  if (!groups.has(label)) groups.set(label, []);
+  groups.get(label).push(bytes);
+}
+
+if (groups.size === 0) {
+  console.log(`meter: no data yet (${LEDGER} has no valid entries)`);
+  process.exit(0);
+}
+
+const rows = [...groups.entries()]
+  .map(([label, list]) => {
+    const sorted = [...list].sort((a, b) => a - b);
+    const total = sorted.reduce((s, b) => s + b, 0);
+    return {
+      label,
+      count: sorted.length,
+      p50: percentile(sorted, 50),
+      p95: percentile(sorted, 95),
+      total,
+      tokens: estTokens(total),
+    };
+  })
+  .sort((a, b) => b.total - a.total);
+
+const grandBytes = rows.reduce((s, r) => s + r.total, 0);
+const grandCount = rows.reduce((s, r) => s + r.count, 0);
+
+// Plain fixed-width table — no dependencies, pipes cleanly.
+const cols = [
+  ['class', (r) => r.label],
+  ['count', (r) => String(r.count)],
+  ['p50 bytes', (r) => String(r.p50)],
+  ['p95 bytes', (r) => String(r.p95)],
+  ['total bytes', (r) => String(r.total)],
+  ['~tokens (bytes/4)', (r) => String(r.tokens)],
+];
+const widths = cols.map(([h, f]) => Math.max(h.length, ...rows.map((r) => f(r).length)));
+const fmt = (cells) => cells.map((cell, i) => String(cell).padEnd(widths[i])).join('  ');
+
+console.log(`token meter — ${LEDGER}`);
+console.log(fmt(cols.map(([h]) => h)));
+console.log(fmt(widths.map((w) => '-'.repeat(w))));
+for (const r of rows) console.log(fmt(cols.map(([, f]) => f(r))));
+console.log('');
+console.log(
+  `session total: ${grandCount} injections, ${grandBytes} bytes ≈ ${estTokens(grandBytes)} tokens (estimate: bytes/4)`,
+);
+if (skipped > 0) console.log(`(${skipped} malformed line(s) skipped)`);