ruvnet-brain 4.7.21 → 4.7.23

package/scripts/onboarding-console.mjs

@@ -64,7 +64,7 @@ import {
 } from '../kb/brain-profile.mjs';
 // Lessons: read model + the two user verbs. Every mutation goes through lesson-store's own
 // updateLessons/ratify/demote/restore — this file adds a SURFACE, never a second writer.
-import { loadLessons, updateLessons, ratify, demote, restore, pending, weightOf, TRIGGERS, ENFORCEMENT, ORIGIN, SOURCE_CLASS, STATUS } from './lesson-store.mjs';
+import { loadLessons, lessonApplies, projectNameFor, STORE_PATH as LESSON_STORE_PATH, updateLessons, ratify, demote, restore, pending, weightOf, TRIGGERS, ENFORCEMENT, ORIGIN, SOURCE_CLASS, STATUS } from './lesson-store.mjs';
 import {
   openRouterCredentialStatus,
   saveOpenRouterCredential,
@@ -1401,6 +1401,8 @@ function setLesson(body) {
 // --refresh-cache child. A request never scans — not inline on a first-ever run, and not via
 // setImmediate either (deferring synchronous work still blocks the loop when it runs). A machine with
 // no fleet scan yet is reported `warming`, never as a fabricated zero.
+// #500: bump when the meaning of the cached fleet changes. 2 = one entry per resolved store; 3 = + stable `id`.
+const ACTIVITY_CACHE_SCHEMA = 3; // 3 = each project also carries `id`, the store's dev:inode identity
 let ACTIVITY_MACHINE_CACHE = null;
 const CONSOLE_CACHE_PATH = path.join(CONSOLE_ROOT, '.cache/ruvnet-brain/console-cache.json');
 
@@ -1862,7 +1864,9 @@ function loadConsoleCache() {
   let restored = false;
   try {
     const j = JSON.parse(fs.readFileSync(CONSOLE_CACHE_PATH, 'utf8'));
-    if (j.activity && j.activity.at) { ACTIVITY_MACHINE_CACHE = j.activity; restored = true; }
+    // #500: a cache written before the fleet scan deduped by store identity can hold one database
+    // counted twice (a nested docs/adr/.swarm beside its parent). Never trust it — re-measure.
+    if (j.activity && j.activity.at && j.activity.schema === ACTIVITY_CACHE_SCHEMA) { ACTIVITY_MACHINE_CACHE = j.activity; restored = true; }
     if (j.trust && j.trust.at) { TRUST_CACHE = j.trust; restored = true; }
   } catch { /* no cache yet — first ever boot */ }
   return restored;
@@ -1896,7 +1900,7 @@ function saveConsoleCache() {
 function adoptFleetFromDisk() {
   try {
     const j = readJSON(CONSOLE_CACHE_PATH);
-    if (j && j.activity && j.activity.at && (!ACTIVITY_MACHINE_CACHE || j.activity.at > ACTIVITY_MACHINE_CACHE.at)) {
+    if (j && j.activity && j.activity.at && j.activity.schema === ACTIVITY_CACHE_SCHEMA && (!ACTIVITY_MACHINE_CACHE || j.activity.at > ACTIVITY_MACHINE_CACHE.at)) {
       ACTIVITY_MACHINE_CACHE = j.activity;
     }
   } catch { /* no cache yet — the caller kicks a child and reports `warming` */ }
@@ -1912,8 +1916,10 @@ function refreshFleetCache() {
       // pathIdentity, not path.resolve: resolve() normalises `.`/`..` and nothing else, so a project
       // reached through a symlink OR through the other capitalisation of a case-insensitive volume
       // was two distinct strings for one directory, and its memories were summed twice (#107).
-      const resolved = pathIdentity(s.project) ?? path.resolve(s.project);
-      if (seen.has(resolved)) continue; // a project visible under two roots counts once
+      // #500: dedupe on the DATABASE, which is what holds the memories. Two directories (a repo and its
+      // nested docs/adr/.swarm, or a linked worktree) can resolve to one store; project paths differ.
+      const resolved = pathIdentity(s.db) ?? path.resolve(s.db);
+      if (seen.has(resolved)) continue; // a store visible twice counts once
       seen.add(resolved);
       const n = Number(robustRead(s.db, "SELECT COUNT(*) FROM memory_entries WHERE status='active'").value || 0);
       if (n > 0) {
@@ -1922,17 +1928,25 @@ function refreshFleetCache() {
         const lastTouched = Number(robustRead(s.db, 'SELECT MAX(updated_at) FROM memory_entries').value || 0);
         // rel = the root-relative path — the SAME key reconcile:<id> recommendations use (wiringSurvey
         // computes projName the same way, relative to whichever root the project was found under).
-        projects.push({ name: path.basename(s.project), rel: path.relative(root, s.project), memories: n, lastTouched });
+        // Name from the RESOLVED project root. A linked worktree whose main checkout lies outside this
+        // scan root would give a '..'-prefixed rel, but reconcile:<id> keys (wiringSurvey) are relative to
+        // the directory found under the root — so fall back to the found directory in that case.
+        const inRoot = path.relative(root, s.project);
+        const rel = (inRoot === '' || inRoot.startsWith('..') || path.isAbsolute(inRoot)) ? path.relative(root, s.found || s.project) : inRoot;
+        // `id` = the store's own dev:inode identity (pathIdentity follows symlinks and sees hard links), so a
+        // client can tell WHICH project is "you" without comparing folder names (two repos can share one).
+        projects.push({ id: resolved, name: path.basename(s.project), rel, memories: n, lastTouched });
         total += n;
       }
     }
   }
   projects.sort((a, b) => b.memories - a.memories);
-  ACTIVITY_MACHINE_CACHE = { at: Date.now(), projects, totalMemories: total };
+  ACTIVITY_MACHINE_CACHE = { schema: ACTIVITY_CACHE_SCHEMA, at: Date.now(), projects, totalMemories: total };
   saveConsoleCache();
 }
-function findMemoryStores(root) {
+export function findMemoryStores(root) {
   const out = [];
+  const seenDb = new Set();
   const walk = (dir, depth) => {
     if (depth > 3) return;
     let ents; try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
@@ -1944,8 +1958,12 @@ function findMemoryStores(root) {
         // Fleet activity is project memory, so resolve the canonical store rather than selecting a
         // coordination database by size. The latter is diagnostic-only and can contain unrelated rows.
         try {
-          const resolved = resolveProjectStore({ projectDir: dir }).canonicalAgentDbPath;
-          if (fs.existsSync(resolved)) out.push({ project: dir, db: resolved });
+          const store = resolveProjectStore({ projectDir: dir });
+          const resolved = store.canonicalAgentDbPath;
+          // #500: record the RESOLVED project root and one entry per database. A nested docs/adr/.swarm
+          // resolves to its parent's store; recording `dir` listed that one database twice.
+          const id = pathIdentity(resolved) ?? path.resolve(resolved);
+          if (fs.existsSync(resolved) && !seenDb.has(id)) { seenDb.add(id); out.push({ project: store.projectRoot, found: dir, db: resolved }); }
         } catch { /* an unresolvable directory is not a project store */ }
         continue;
       }
@@ -1956,6 +1974,38 @@ function findMemoryStores(root) {
   walk(root, 0);
   return out;
 }
+// #499: approved lessons are the ratified rules in the lesson store (the SAME active rule as
+// gatherLessons().counts.active). `available:false` means the store could not be read — unknown, never 0.
+//   count      = machine-wide (every ratified/active, non-demoted lesson)
+//   applicable = the subset that applies to THIS project, by the SAME rule plugin/scripts/lesson-gate.mjs
+//                uses (lesson-store.lessonApplies): unscoped, or scoped to this project, or proven in >=2 projects.
+//   items      = per-lesson id/title/scope/enforcement/status for the applicable ones, bounded (the metadata
+//                the reporter asked to keep), `itemsTruncated` says when the bound cut the list.
+const APPROVED_ITEMS_MAX = 25;
+function approvedLessonsFigure(here) {
+  try {
+    // loadLessons() swallows a parse failure and returns [] — which would read as "0 approved". A file
+    // that exists but does not parse is UNKNOWN; only an absent file is a true zero.
+    if (fs.existsSync(LESSON_STORE_PATH)) JSON.parse(fs.readFileSync(LESSON_STORE_PATH, 'utf8'));
+    const approved = loadLessons().filter((l) => (l.status === STATUS.RATIFIED || l.status === STATUS.ACTIVE) && !l.demoted);
+    const mine = approved.filter((l) => lessonApplies(l, here)); // the gate's own rule (lesson-store.lessonApplies)
+    const items = mine.slice(0, APPROVED_ITEMS_MAX).map((l) => {
+      const ps = Array.isArray(l.projects) ? l.projects : [];
+      const text = String(l.statement || '');
+      return { id: l.id, title: text.length > 140 ? `${text.slice(0, 139)}…` : text,
+        scope: ps.length ? ps.join(', ') : 'all projects', enforcement: l.enforcement ?? null,
+        ratified: l.status === STATUS.RATIFIED || l.status === STATUS.ACTIVE, status: l.status };
+    });
+    return { available: true, count: approved.length, applicable: mine.length, items, itemsTruncated: mine.length > items.length };
+  } catch { return { available: false, count: null, applicable: null, items: [], itemsTruncated: false }; }
+}
+// #499: a count that could not be read is null, not 0 — "0" would claim the store is empty.
+function readCount(db, sql) {
+  const r = robustRead(db, sql);
+  if (!r.ok) return null;
+  const n = Number(r.value ?? 0);
+  return Number.isFinite(n) ? n : null;
+}
 function gatherActivity(cwd) {
   let project;
   let db;
@@ -1965,19 +2015,27 @@ function gatherActivity(cwd) {
     db = resolved.canonicalAgentDbPath;
   } catch {
     const measuredAt = new Date().toISOString();
-    return { generatedAt: measuredAt, project: path.basename(cwd), hasStore: false, continuity: 'unavailable', ...freshnessOf(measuredAt) };
+    return { generatedAt: measuredAt, project: path.basename(cwd), hasStore: false, continuity: 'unavailable', approvedLessons: approvedLessonsFigure(projectNameFor(cwd)), ...freshnessOf(measuredAt) };
   }
   if (!fs.existsSync(db)) {
     // No store to read — the existence check above IS the entire measurement, so it IS the
     // observation instant. Stamped here, not with a value taken before the check ran.
     const measuredAt = new Date().toISOString();
-    return { generatedAt: measuredAt, project: path.basename(project), hasStore: false, ...freshnessOf(measuredAt) };
+    return { generatedAt: measuredAt, project: path.basename(project), hasStore: false, approvedLessons: approvedLessonsFigure(path.basename(project)), ...freshnessOf(measuredAt) };
   }
-  const out = { project: path.basename(project), hasStore: true };
+  // projectId = the same dev:inode identity the fleet entries carry, so the client matches on identity, not the folder name.
+  const out = { project: path.basename(project), projectId: pathIdentity(db) ?? path.resolve(db), hasStore: true, approvedLessons: approvedLessonsFigure(path.basename(project)) };
   const rows = (sql) => robustReadJSON(db, sql).rows;
+  const agentdbLessons = readCount(db, "SELECT COUNT(*) FROM memory_entries WHERE namespace='lessons' AND status='active'");
   out.totals = {
-    memories: Number(robustRead(db, "SELECT COUNT(*) FROM memory_entries WHERE status='active'").value || 0),
-    lessons: Number(robustRead(db, "SELECT COUNT(*) FROM memory_entries WHERE namespace='lessons' AND status='active'").value || 0),
+    memories: readCount(db, "SELECT COUNT(*) FROM memory_entries WHERE status='active'"),
+    agentdbLessons,
+    lessons: agentdbLessons, // legacy alias of agentdbLessons
+    // #499: the learning pipeline's OWN measurements (null = unreadable, shown as Unknown, never 0). Distillation
+    // writes patterns/episodes, never `lessons` rows; observations are the namespace it mines.
+    observations: readCount(db, "SELECT COUNT(*) FROM memory_entries WHERE namespace='learning-observations' AND status='active'"),
+    patterns: readCount(db, 'SELECT COUNT(*) FROM reasoning_patterns'),
+    episodes: readCount(db, 'SELECT COUNT(*) FROM episodes'),
   };
   out.lessons = rows("SELECT key, access_count, date(created_at/1000,'unixepoch') AS learned, substr(content,1,600) AS excerpt FROM memory_entries WHERE namespace='lessons' AND status='active' ORDER BY created_at DESC");
   out.recent = rows("SELECT key, namespace, type, datetime(updated_at/1000,'unixepoch','localtime') AS at FROM memory_entries WHERE status='active' ORDER BY updated_at DESC LIMIT 18");
@@ -3550,6 +3608,9 @@ export {
   saveBrainProfile,
   setLesson,
   gatherLessons,
+  gatherActivity,
+  refreshFleetCache,
+  loadConsoleCache,
   gatherRouterEngine,
   autoEligibleIds,
   gatherConfig,

package/scripts/recall-latency-probe.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+/**
+ * Measures the real hook paths against a real store (#429): prompt-time recall() and SessionStart restore().
+ *   node scripts/recall-latency-probe.mjs --project <repo> [--runs N]
+ * Prints per-run milliseconds, outcome and `uptime` (machine load). Exit 1 unless EVERY prompt recall is
+ * ok-with-results / ok-empty within 1900 ms and EVERY restore is 'restored' within 3500 ms. The thresholds are
+ * the product's budgets, not tuned to the machine.
+ */
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { recall } from '../plugin/scripts/agentdb-recall.mjs';
+import { restore } from '../plugin/scripts/ruflo-memory-hooks.mjs';
+
+export const RECALL_LIMIT_MS = 1900;
+export const RESTORE_LIMIT_MS = 3500;
+const PROMPT = 'Where are we on the recall latency work? Catch me up on the last decision.';
+
+const argValue = (name) => { const at = process.argv.indexOf(name); return at >= 0 ? process.argv[at + 1] : undefined; };
+const uptime = () => { try { return execFileSync('uptime', { encoding: 'utf8' }).trim(); } catch { return 'uptime unavailable'; } };
+
+async function main() {
+  const project = argValue('--project');
+  const runs = Number(argValue('--runs') ?? 5);
+  if (!project || !Number.isInteger(runs) || runs < 1) {
+    console.error('usage: recall-latency-probe.mjs --project <repo> [--runs N]');
+    process.exit(2);
+  }
+  const dir = path.resolve(project);
+  let failures = 0;
+  for (let run = 1; run <= runs; run += 1) {
+    const t0 = Date.now();
+    const r = await recall({ prompt: PROMPT, projectDir: dir });
+    const recallMs = Date.now() - t0;
+    const recallOk = ['ok-with-results', 'ok-empty'].includes(r.outcome) && recallMs <= RECALL_LIMIT_MS;
+    const t1 = Date.now();
+    const s = await restore({ cwd: dir });
+    const restoreMs = Date.now() - t1;
+    const restoreOk = s.status === 'restored' && restoreMs <= RESTORE_LIMIT_MS;
+    if (!recallOk) failures += 1;
+    if (!restoreOk) failures += 1;
+    console.log(`run ${run}: recall ${recallMs} ms ${r.outcome}${r.status?.['memory.db'] && r.outcome !== 'ok-with-results' ? ` [${r.status['memory.db']}]` : ''}${r.reason ? ` (${r.reason})` : ''} ${recallOk ? 'PASS' : 'FAIL'}`
+      + ` | restore ${restoreMs} ms ${s.status} ${restoreOk ? 'PASS' : 'FAIL'} | ${uptime()}`);
+  }
+  console.log(failures ? `FAIL: ${failures} of ${runs * 2} measurements outside budget (recall <= ${RECALL_LIMIT_MS} ms, restore <= ${RESTORE_LIMIT_MS} ms)`
+    : `PASS: all ${runs * 2} measurements within budget`);
+  process.exit(failures ? 1 : 0);
+}
+await main();

package/scripts/release-prepush-checks.mjs

@@ -0,0 +1,251 @@
+// scripts/release-prepush-checks.mjs — the individual checks behind `npm run release:prepush`.
+//
+// Each check is `async (ctx) => ({ ok, detail, warnings? })`. Every effect (git, gh, node, network)
+// goes through `ctx.deps`, so the unit tests drive the checks with no real git, gh or network.
+// The rules here restate nothing: the commands come from package.json, the census rules from
+// scripts/claims-verify.mjs, the test inventory from scripts/release-qualification.mjs.
+
+import path from 'node:path';
+
+export const RELEASE_BRANCH = /^release\/(\d+\.\d+\.\d+)$/;
+export const MAX_ADDED_BYTES = 5 * 1024 * 1024;
+export const QUALIFICATION_SUITES = ['source', 'integration'];
+export const QUALIFICATION_PLATFORMS = ['linux', 'macos', 'windows'];
+export const ANCHOR_TEST_DIRS = ['tests/mesh/', 'tests/mutation/', 'tests/regression/'];
+const CHANGED_TEST = /^tests\/(?:unit|integration|mesh|mutation|regression)\/.+\.test\.mjs$/;
+export const RECENT_PRERELEASE_MS = 3 * 60 * 60 * 1000;
+export const SEED_LINE = /\[corpus-next-seed\] (published-generation|committed-bootstrap) (\S+)/g;
+
+// The preflight's first-push gates, by the npm script that defines each (never a restated flag), plus
+// the two the preflight runs directly (.github/workflows/release-candidate-preflight.yml).
+export const STATIC_GATES = [
+  { name: 'node-check-release', argv: ['--check', 'scripts/release.mjs'] },
+  { name: 'version-check', script: 'version:check' },
+  { name: 'release-authority', script: 'release:authority' },
+  { name: 'architecture-review-lock', argv: ['scripts/architecture-review-lock.mjs'] },
+  { name: 'convergence-check', script: 'convergence:check' },
+  { name: 'hooks-check', script: 'hooks:check' },
+  { name: 'single-source-check', script: 'single-source:check' },
+  { name: 'wired-check', script: 'wired:check' },
+  { name: 'substitution-check', script: 'substitution:check' },
+];
+
+/**
+ * Stray-artifact rules for files ADDED on the branch. Every pattern is anchored to a path segment or a
+ * basename suffix: a loose `agentdb*` or `*.rvf*` would match legitimate tracked files such as
+ * kb/l2/agentdb.md or plugin/scripts/package-cards.rvf.
+ */
+export const STRAY_PATTERNS = [
+  { name: 'ruflo/agentdb working store (.swarm/)', re: /(^|\/)\.swarm\// },
+  { name: 'database file', re: /\.db(-wal|-shm)?$/ },
+  { name: 'local Claude settings', re: /(^|\/)\.claude\/settings\.local[^/]*$/ },
+  { name: 'backup file (*.bak*)', re: /(^|\/)[^/]*\.bak(?:$|[-._\d])[^/]*$/ },
+  { name: 'opencode workspace', re: /(^|\/)\.opencode\// },
+  { name: 'VS Code workspace', re: /(^|\/)\.vscode\// },
+];
+
+export function strayFindings(added, { rootFilesAtMain, sizes }) {
+  const findings = [];
+  for (const file of added) {
+    for (const rule of STRAY_PATTERNS) if (rule.re.test(file)) findings.push(`${file}: ${rule.name}`);
+    if (!file.includes('/') && !rootFilesAtMain.has(file)) findings.push(`${file}: new root-level file (absent at origin/main)`);
+    const size = sizes.get(file);
+    if (size > MAX_ADDED_BYTES) findings.push(`${file}: ${(size / 1048576).toFixed(1)} MB added (limit 5 MB)`);
+  }
+  return findings;
+}
+
+const lines = (text) => String(text || '').split('\n').map((line) => line.trim()).filter(Boolean);
+const fail = (detail, extra = {}) => ({ ok: false, detail, ...extra });
+const pass = (detail, extra = {}) => ({ ok: true, detail, ...extra });
+
+async function git(ctx, args) {
+  const result = await ctx.deps.exec('git', args, { cwd: ctx.root });
+  if (result.status !== 0) throw new Error(`git ${args.join(' ')}: ${String(result.stderr || result.stdout).trim()}`);
+  return result.stdout;
+}
+
+/** (a) release/X.Y.Z branch, X.Y.Z = package.json version, no tracked changes. */
+export async function branchIdentity(ctx) {
+  const branch = (await git(ctx, ['rev-parse', '--abbrev-ref', 'HEAD'])).trim();
+  const version = JSON.parse(await git(ctx, ['show', 'HEAD:package.json'])).version;
+  const dirty = lines(await git(ctx, ['status', '--porcelain', '--untracked-files=no']));
+  const problems = [];
+  const match = RELEASE_BRANCH.exec(branch);
+  if (!match) problems.push(`HEAD is on "${branch}", not a release/X.Y.Z branch`);
+  else if (match[1] !== version) problems.push(`branch says ${match[1]} but package.json says ${version}`);
+  if (dirty.length) problems.push(`${dirty.length} tracked change(s) not committed: ${dirty.slice(0, 5).join(', ')}`);
+  return problems.length ? fail(problems.join('; ')) : pass(`${branch} = package.json ${version}; tracked tree clean`);
+}
+
+/** (b) one static gate; its exit status is the verdict, its last output lines the detail. */
+export function staticGate(gate) {
+  return async (ctx) => {
+    let argv = gate.argv;
+    if (gate.script) {
+      const command = ctx.packageScripts[gate.script];
+      if (!command) return fail(`package.json has no "${gate.script}" script`);
+      const node = /^node\s+(.+)$/.exec(command.trim());
+      argv = node && !/[|&;<>$`]/.test(node[1]) ? node[1].split(/\s+/) : null;
+      if (!argv) {
+        const npm = await ctx.deps.exec('npm', ['run', '--silent', gate.script], { cwd: ctx.root });
+        return npm.status === 0 ? pass(`npm run ${gate.script}`) : fail(tail(npm));
+      }
+    }
+    const result = await ctx.deps.exec(process.execPath, argv, { cwd: ctx.root });
+    return result.status === 0 ? pass(`node ${argv.join(' ')}`) : fail(`node ${argv.join(' ')} exited ${result.status}: ${tail(result)}`);
+  };
+}
+const tail = (result) => lines(`${result.stdout || ''}\n${result.stderr || ''}`).slice(-6).join(' | ').slice(0, 1200);
+
+/** (c) the qualification inventory builds for every suite and platform, and every file is tracked at HEAD. */
+export async function qualificationInventory(ctx) {
+  const tracked = new Set(lines(await git(ctx, ['ls-tree', '-r', '--name-only', 'HEAD'])));
+  const { qualificationPlan } = await ctx.deps.importModule(path.join(ctx.root, 'scripts/release-qualification.mjs'));
+  const problems = [];
+  let files = 0;
+  for (const suite of QUALIFICATION_SUITES) for (const platform of QUALIFICATION_PLATFORMS) {
+    try {
+      const plan = qualificationPlan(suite, platform);
+      files += plan.files.length;
+      for (const file of plan.files) if (!tracked.has(file)) problems.push(`${suite}/${platform}: ${file} is not tracked at HEAD`);
+    } catch (error) { problems.push(`${suite}/${platform}: ${error.message}`); }
+  }
+  return problems.length ? fail(problems.join('; ')) : pass(`6 plans, ${files} listed files, all tracked at HEAD`);
+}
+
+/** (d) nothing stray was added on the branch. */
+export async function strayArtifacts(ctx) {
+  const base = (await git(ctx, ['merge-base', 'origin/main', 'HEAD'])).trim();
+  const added = lines(await git(ctx, ['diff', '--name-only', '--no-renames', '--diff-filter=A', base, 'HEAD']));
+  const rootFilesAtMain = new Set(lines(await git(ctx, ['ls-tree', '--name-only', 'origin/main'])));
+  const sizes = new Map();
+  for (const row of lines(await git(ctx, ['ls-tree', '-r', '-l', 'HEAD']))) {
+    const m = /^\S+ blob \S+\s+(\d+)\t(.+)$/.exec(row);
+    if (m) sizes.set(m[2], Number(m[1]));
+  }
+  const findings = strayFindings(added, { rootFilesAtMain, sizes });
+  return findings.length ? fail(findings.join('; ')) : pass(`${added.length} added file(s) since ${base.slice(0, 8)}; none stray`);
+}
+
+/** The surface rules of scripts/claims-verify.mjs (qualifyCensusArtifacts), with old and new numbers named. */
+export function surfaceCensusProblems(file, text, census, { SURFACE_CLAIM_RULES }) {
+  const expected = { ...census, builtStores: census.publicStores };
+  const problems = [];
+  const want = census.chunks.toLocaleString('en-US');
+  if (!text.includes(want)) problems.push(`${file}: chunk count ${want} absent`);
+  for (const rule of SURFACE_CLAIM_RULES) for (const match of text.matchAll(rule.re)) for (const group of rule.groups) {
+    const found = Number(match[group.i].replace(/,/g, ''));
+    if (found !== expected[rule.key]) {
+      problems.push(`${file}: ${rule.name} ${found.toLocaleString('en-US')} -> ${expected[rule.key].toLocaleString('en-US')}`);
+    }
+  }
+  return problems;
+}
+
+async function surfacesAgainst(ctx, rev, census) {
+  const claims = await ctx.deps.importModule(path.join(ctx.root, 'scripts/claims-verify.mjs'));
+  const problems = [];
+  for (const file of claims.CHUNK_SURFACES) {
+    const text = await git(ctx, ['show', `${rev}:${file}`]);
+    problems.push(...surfaceCensusProblems(file, text, census, claims));
+  }
+  return { problems, surfaces: claims.CHUNK_SURFACES.length };
+}
+
+/** Which generation is the newest NOW (or the one named for a replay). */
+async function targetGeneration(ctx) {
+  if (ctx.generation) return { tag: ctx.generation, bytes: null, origin: 'named' };
+  const seed = await ctx.deps.resolveSeed();
+  return { tag: seed.tag, bytes: seed.bytes ?? null, origin: seed.origin };
+}
+
+async function corpusWarnings(ctx) {
+  const warnings = [];
+  const now = ctx.deps.now();
+  const releases = await ctx.deps.exec('gh', ['release', 'list', '--repo', ctx.repo, '--limit', '20', '--json', 'tagName,isPrerelease,publishedAt'], { cwd: ctx.root });
+  if (releases.status !== 0) warnings.push('could not list releases to look for a fresh corpus prerelease');
+  else for (const row of JSON.parse(releases.stdout || '[]')) {
+    const age = now - Date.parse(row.publishedAt);
+    if (row.isPrerelease && /^corpus-sha256-/.test(row.tagName) && age < RECENT_PRERELEASE_MS) {
+      warnings.push(`${row.tagName} is a prerelease published ${Math.round(age / 60000)} min ago — a newer generation may promote soon`);
+    }
+  }
+  const runs = await ctx.deps.exec('gh', ['run', 'list', '--repo', ctx.repo, '--workflow', 'protected-release.yml', '--limit', '10', '--json', 'databaseId,displayTitle,status'], { cwd: ctx.root });
+  if (runs.status !== 0) warnings.push('could not list protected-release runs to look for a corpus publish in flight');
+  else for (const run of JSON.parse(runs.stdout || '[]')) {
+    if (run.status !== 'completed' && /^protected-release corpus\b/.test(run.displayTitle || '')) {
+      warnings.push(`corpus publish run ${run.databaseId} is ${run.status} — the newest generation may change under this release`);
+    }
+  }
+  return warnings;
+}
+
+/** (e) every committed claim surface quotes the census of the newest generation. */
+export async function censusCheck(ctx) {
+  const generation = await targetGeneration(ctx);
+  const [census, warnings] = await Promise.all([
+    ctx.deps.census({ tag: generation.tag, bytes: generation.bytes }),
+    corpusWarnings(ctx).catch((error) => [`corpus activity check failed: ${error.message}`]),
+  ]);
+  const { problems, surfaces } = await surfacesAgainst(ctx, 'HEAD', census);
+  const summary = `${generation.tag} (${generation.origin}): ${census.publicStores} public stores, ${census.chunks.toLocaleString('en-US')} chunks`;
+  return problems.length
+    ? fail(`${summary}; stale surfaces: ${problems.join('; ')} — restamp with scripts/sync-census.mjs`, { warnings })
+    : pass(`${summary}; all ${surfaces} surfaces agree`, { warnings });
+}
+
+/** (f) text-anchored mesh/mutation/regression tests for changed source, plus changed tests. */
+export async function anchoredTests(ctx) {
+  const base = (await git(ctx, ['merge-base', 'origin/main', 'HEAD'])).trim();
+  const changed = lines(await git(ctx, ['diff', '--name-only', '--no-renames', base, 'HEAD']));
+  const tracked = lines(await git(ctx, ['ls-tree', '-r', '--name-only', 'HEAD']));
+  const trackedSet = new Set(tracked);
+  const sources = changed.filter((file) => !file.startsWith('tests/') && trackedSet.has(file));
+  const selected = new Set(changed.filter((file) => CHANGED_TEST.test(file) && trackedSet.has(file)));
+  for (const file of tracked) {
+    if (!file.endsWith('.test.mjs') || !ANCHOR_TEST_DIRS.some((dir) => file.startsWith(dir))) continue;
+    const text = await ctx.deps.readFile(path.join(ctx.root, file));
+    if (sources.some((source) => text.includes(source))) selected.add(file);
+  }
+  const files = [...selected].sort();
+  if (!files.length) return pass(`no anchored or changed tests for ${sources.length} changed source file(s)`, { files });
+  const result = await ctx.deps.exec(process.execPath, [path.join(ctx.root, 'node_modules/vitest/vitest.mjs'), 'run', ...files], { cwd: ctx.root });
+  return result.status === 0 ? pass(`${files.length} test file(s) passed: ${files.join(', ')}`, { files })
+    : fail(`vitest exited ${result.status} on ${files.join(', ')}: ${tail(result)}`, { files });
+}
+
+/** (g) pre-dispatch: the generation the preflight sealed for SHA must still be the newest. */
+export async function sealedGeneration(ctx) {
+  const sha = ctx.sha;
+  if (!/^[0-9a-f]{40}$/.test(String(sha || ''))) return fail('--pre-dispatch needs --sha <full 40-character commit>');
+  const gh = async (args) => {
+    const result = await ctx.deps.exec('gh', args, { cwd: ctx.root });
+    if (result.status !== 0) throw new Error(`gh ${args.slice(0, 2).join(' ')}: ${tail(result)}`);
+    return result.stdout;
+  };
+  const runs = JSON.parse(await gh(['run', 'list', '--repo', ctx.repo, '--workflow', 'release-candidate-preflight.yml', '--commit', sha,
+    '--limit', '20', '--json', 'databaseId,conclusion,status,event,headBranch,createdAt']));
+  const green = runs.filter((run) => run.event === 'push' && run.conclusion === 'success' && RELEASE_BRANCH.test(run.headBranch || ''))
+    .sort((a, b) => Date.parse(b.createdAt) - Date.parse(a.createdAt))[0];
+  if (!green) return fail(`no successful release-candidate-preflight push run for ${sha.slice(0, 8)} on a release/* branch`);
+  const newest = await targetGeneration(ctx);
+  let sealed = null;
+  const jobs = JSON.parse(await gh(['run', 'view', String(green.databaseId), '--repo', ctx.repo, '--json', 'jobs'])).jobs || [];
+  const qe = jobs.find((job) => /(^|\/ )release-qe$/.test(job.name || ''));
+  if (qe) {
+    const log = await ctx.deps.exec('gh', ['run', 'view', '--repo', ctx.repo, '--job', String(qe.databaseId), '--log'], { cwd: ctx.root });
+    if (log.status === 0) sealed = [...String(log.stdout).matchAll(SEED_LINE)].map((m) => m[2]).pop() || null;
+  }
+  if (sealed) {
+    return sealed === newest.tag
+      ? pass(`preflight run ${green.databaseId} sealed ${sealed}, still the newest generation`)
+      : fail(`preflight run ${green.databaseId} sealed ${sealed}, but the newest generation is now ${newest.tag} — restamp the census, push, and re-run preflight`);
+  }
+  // Fallback when the job log is gone or reworded: the surfaces at SHA must quote the newest census.
+  const census = await ctx.deps.census({ tag: newest.tag, bytes: newest.bytes });
+  const { problems } = await surfacesAgainst(ctx, sha, census);
+  return problems.length
+    ? fail(`no sealed-generation line in preflight run ${green.databaseId}; surfaces at ${sha.slice(0, 8)} disagree with ${newest.tag}: ${problems.join('; ')}`)
+    : pass(`no sealed-generation line in preflight run ${green.databaseId}; surfaces at ${sha.slice(0, 8)} equal the census of ${newest.tag} (fallback)`);
+}

package/scripts/release-prepush.mjs

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+// scripts/release-prepush.mjs — run, before the FIRST push of a release/X.Y.Z branch, every check
+// release-candidate-preflight would otherwise fail on in its first minutes (CONTRIBUTING.md,
+// "Releasing code"). An explicit command on purpose: tests/unit/development-push-boundary.test.mjs
+// keeps ordinary pushes free of release gates, so this is never wired into the git pre-push hook.
+//
+//   npm run release:prepush [-- --receipt <file>] [--generation <corpus tag>]
+//   npm run release:prepush -- --pre-dispatch --sha <SHA> [--receipt <file>]
+//
+// Runs ALL checks, collects every failure, prints each check's wall time and exits 1 on any failure.
+// --pre-dispatch runs only the sealed-generation check: the corpus generation the preflight sealed for
+// SHA must still be the newest one before protected-release.yml is dispatched.
+// Programmatic: runPrepush({ root, sha, preDispatch, generation, repo, deps }) -> { ok, checks }.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { rangeCensus } from './generation-census.mjs';
+import {
+  STATIC_GATES, anchoredTests, branchIdentity, censusCheck, qualificationInventory, sealedGeneration, staticGate, strayArtifacts,
+} from './release-prepush-checks.mjs';
+import { isDirectInvocation } from '../plugin/scripts/entrypoint.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const EXEC_TIMEOUT_MS = 10 * 60 * 1000;
+
+/** Promise-returning spawn: never blocks the event loop, so checks really run side by side. */
+export function exec(command, args, { cwd, timeoutMs = EXEC_TIMEOUT_MS, env = process.env } = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
+    const out = [], err = [];
+    child.stdout.on('data', (chunk) => out.push(chunk));
+    child.stderr.on('data', (chunk) => err.push(chunk));
+    const timer = setTimeout(() => child.kill('SIGKILL'), timeoutMs);
+    const done = (status, error) => {
+      clearTimeout(timer);
+      resolve({ status, stdout: Buffer.concat(out).toString('utf8'),
+        stderr: Buffer.concat(err).toString('utf8') + (error ? `\n${error.message}` : '') });
+    };
+    child.on('error', (error) => done(127, error));
+    child.on('close', (code, signal) => done(code ?? (signal ? 128 : 1)));
+  });
+}
+
+function repoFromRemote(url) {
+  const m = /github\.com[:/]([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/.exec(String(url || '').trim());
+  return m ? `${m[1]}/${m[2]}` : null;
+}
+
+/** The real effects. Tests replace any of them. */
+export function defaultDeps({ root = ROOT, repo } = {}) {
+  let token;
+  const ghToken = async () => {
+    if (token === undefined) {
+      const result = await exec('gh', ['auth', 'token'], { cwd: root, timeoutMs: 15_000 });
+      token = process.env.GH_TOKEN || process.env.GITHUB_TOKEN || (result.status === 0 ? result.stdout.trim() : null) || null;
+    }
+    return token;
+  };
+  return {
+    exec,
+    now: () => Date.now(),
+    readFile: async (file) => fs.promises.readFile(file, 'utf8'),
+    importModule: (file) => import(pathToFileURL(file).href),
+    // The exact CI invocation (ci.yml release-qe), as a child process; its stdout is the descriptor.
+    resolveSeed: async () => {
+      const result = await exec(process.execPath, [path.join(root, 'scripts/corpus-next-seed.mjs'), '--repo', repo, '--require-coverage'], { cwd: root });
+      if (result.status !== 0) throw new Error(`corpus-next-seed exited ${result.status}: ${result.stderr.trim().split('\n').slice(-3).join(' | ')}`);
+      return JSON.parse(result.stdout);
+    },
+    census: async ({ tag, bytes }) => rangeCensus({ repo, tag, bytes, token: await ghToken(),
+      privateStoresFile: path.join(root, 'kb/PRIVATE-STORES.json'), cacheDir: os.tmpdir() }),
+  };
+}
+
+export async function runPrepush({ root = ROOT, sha = null, preDispatch = false, generation = null, repo = null, deps = {} } = {}) {
+  const resolvedRoot = path.resolve(root);
+  const probe = { ...defaultDeps({ root: resolvedRoot, repo: 'unresolved/unresolved' }), ...deps };
+  let resolvedRepo = repo || process.env.GITHUB_REPOSITORY || null;
+  if (!resolvedRepo) {
+    const remote = await probe.exec('git', ['remote', 'get-url', 'origin'], { cwd: resolvedRoot });
+    resolvedRepo = remote.status === 0 ? repoFromRemote(remote.stdout) : null;
+  }
+  const merged = { ...defaultDeps({ root: resolvedRoot, repo: resolvedRepo }), ...deps };
+  let packageScripts = {};
+  try { packageScripts = JSON.parse(await merged.readFile(path.join(resolvedRoot, 'package.json'))).scripts || {}; } catch { /* the gates name it */ }
+  const ctx = { root: resolvedRoot, repo: resolvedRepo, sha, generation, deps: merged, packageScripts };
+
+  const plan = preDispatch
+    ? [['sealed-generation', sealedGeneration]]
+    : [
+      ['branch-identity', branchIdentity],
+      ...STATIC_GATES.map((gate) => [gate.name, staticGate(gate)]),
+      ['qualification-inventory', qualificationInventory],
+      ['stray-artifacts', strayArtifacts],
+      ['census', censusCheck],
+      ['anchored-tests', anchoredTests],
+    ];
+  const checks = await Promise.all(plan.map(async ([name, check]) => {
+    const started = Date.now();
+    let outcome;
+    try {
+      outcome = resolvedRepo || !['census', 'sealed-generation'].includes(name)
+        ? await check(ctx)
+        : { ok: false, detail: 'cannot tell which GitHub repository this is (no GITHUB_REPOSITORY, no github.com origin)' };
+    } catch (error) {
+      outcome = { ok: false, detail: `check threw: ${error.message}` };
+    }
+    return { name, ok: outcome.ok === true, ms: Date.now() - started, detail: outcome.detail,
+      ...(outcome.warnings?.length ? { warnings: outcome.warnings } : {}), ...(outcome.files ? { files: outcome.files } : {}) };
+  }));
+  return { ok: checks.every((check) => check.ok), checks };
+}
+
+function parseArgs(argv) {
+  const opts = { preDispatch: false, sha: null, generation: null, receipt: null, repo: null };
+  for (let i = 0; i < argv.length; i += 1) {
+    const flag = argv[i];
+    const value = () => {
+      const next = argv[i + 1];
+      if (!next || next.startsWith('--')) throw new Error(`${flag} needs a value`);
+      i += 1;
+      return next;
+    };
+    if (flag === '--pre-dispatch') opts.preDispatch = true;
+    else if (flag === '--sha') opts.sha = value();
+    else if (flag === '--generation') opts.generation = value();
+    else if (flag === '--receipt') opts.receipt = value();
+    else if (flag === '--repo') opts.repo = value();
+    else throw new Error(`unknown argument ${flag}`);
+  }
+  if (opts.sha && !opts.preDispatch) throw new Error('--sha is only meaningful with --pre-dispatch');
+  return opts;
+}
+
+export async function main(argv = process.argv.slice(2), { stdout = process.stdout, stderr = process.stderr, deps = {}, root = ROOT } = {}) {
+  let opts;
+  try { opts = parseArgs(argv); } catch (error) {
+    stderr.write(`[release:prepush] ${error.message}\nUsage: npm run release:prepush [-- --receipt FILE] [--generation TAG] | -- --pre-dispatch --sha SHA\n`);
+    return 2;
+  }
+  const started = Date.now();
+  const result = await runPrepush({ root, sha: opts.sha, preDispatch: opts.preDispatch, generation: opts.generation, repo: opts.repo, deps });
+  const totalMs = Date.now() - started;
+  for (const check of result.checks) {
+    stdout.write(`${check.ok ? 'PASS' : 'FAIL'}  ${check.name.padEnd(26)} ${(check.ms / 1000).toFixed(1).padStart(6)} s  ${check.detail}\n`);
+    for (const warning of check.warnings || []) stdout.write(`WARN  ${check.name.padEnd(26)}          ${warning}\n`);
+  }
+  const failed = result.checks.filter((check) => !check.ok);
+  stdout.write(`\n[release:prepush] ${result.ok ? 'PASS' : `FAIL (${failed.length}: ${failed.map((c) => c.name).join(', ')})`} in ${(totalMs / 1000).toFixed(1)} s\n`);
+  if (opts.receipt) {
+    const head = await (deps.exec || exec)('git', ['rev-parse', 'HEAD'], { cwd: root });
+    const receipt = { schemaVersion: 1, kind: 'ruvnet-brain-release-prepush', mode: opts.preDispatch ? 'pre-dispatch' : 'pre-push',
+      head: head.stdout.trim() || null, sha: opts.sha, generation: opts.generation, ok: result.ok,
+      finishedAt: new Date().toISOString(), totalMs, checks: result.checks };
+    fs.writeFileSync(path.resolve(opts.receipt), `${JSON.stringify(receipt, null, 2)}\n`);
+  }
+  return result.ok ? 0 : 1;
+}
+
+if (isDirectInvocation(import.meta.url)) {
+  main().then((code) => { process.exitCode = code; }).catch((error) => {
+    console.error(`[release:prepush] ${error?.stack || error}`);
+    process.exitCode = 1;
+  });
+}