ruvnet-brain 4.0.1 → 4.0.4

package/scripts/goldie-weekly.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+# goldie-weekly.sh — the ONLY thing launchd invokes for Goldie (weekly model-landscape research).
+# Same discipline as nightly-wrapper.sh: verified outcomes, exactly one phone summary per run,
+# no silent path. Built 2026-07-12 per Stuart's mandate: the router must never run on a stale
+# picture of the model landscape, and no scheduled job may ever die quietly.
+#
+# Two layers, independent by design:
+#   1. DETERMINISTIC (scripts/goldie-research.mjs): live OpenRouter pricing -> catalog refresh +
+#      drift flags + radar + the dated brief. Pure data, no LLM, no key needed.
+#   2. JUDGMENT (headless Claude, subscription-covered): answers the brief's three standing
+#      questions (bucket count, best-model-per-bucket per public evals, radar adoption) with real
+#      web research, APPENDED to the same brief as a PROPOSAL — never auto-applied to policy.mjs.
+#      Skippable (GOLDIE_SKIP_JUDGMENT=1) and its failure never hides layer 1's result.
+set -u
+cd /Users/stuartkerr/Code/ruvnet-brain || exit 1
+mkdir -p logs
+LOG=logs/goldie.log
+TODAY=$(date +%F)
+BRIEF="$HOME/.claude/model-router/goldie/$TODAY.md"
+
+echo "===== goldie-weekly — $(date -u +%FT%TZ) =====" >> "$LOG"
+
+# ── Layer 1: deterministic refresh (must succeed for the run to count) ──
+if ! /usr/local/bin/node scripts/goldie-research.mjs >> "$LOG" 2>&1; then
+  sh scripts/notify.sh "🔴 Goldie FAILED — model catalog is going stale" \
+    "goldie-research.mjs could not produce this week's brief (OpenRouter fetch or catalog write failed). The router is now running on last week's picture. See logs/goldie.log." \
+    urgent "rotating_light" || true
+  exit 1
+fi
+
+# ── Layer 2: judgment (best-effort, never blocks; appends to the brief) ──
+JUDGMENT="skipped"
+if [ "${GOLDIE_SKIP_JUDGMENT:-0}" != "1" ] && command -v claude >/dev/null 2>&1; then
+  PROMPT="You are Goldie, the weekly model-landscape researcher for a prompt->model router.
+Read $BRIEF (this week's deterministic data) and ~/.claude/model-router/catalog.json (the candidate
+catalog) and ~/.claude/model-router/policy.default.mjs (the current placeholder policy). Then use web
+search on the current public evaluations (Artificial Analysis, LMArena, SWE-bench and similar) to
+answer the brief's three standing questions with sources and dates:
+(1) how many BUCKETS should prompts be classified into and what are they;
+(2) the best model per bucket right now on capability-per-cost-per-speed, split into: covered by a
+Claude Max subscription (claude-code harness), covered by a ChatGPT/Codex subscription (codex
+harness), and cheapest-capable OpenRouter API model;
+(3) whether any radar model in the brief deserves wiring up, and what that requires.
+Rules: cite sources with dates for every claim; distinguish MEASURED numbers from vendor claims;
+recommendations are PROPOSALS for catalog.json/policy.mjs — do not edit any file. End with a
+'## Proposed policy changes' section in plain, reviewable prose.
+Write your full answer to stdout as markdown."
+  # env -u ANTHROPIC_API_KEY: a stray/stale API key in the environment makes headless claude bill
+  # (or fail on) the API instead of riding the Claude Max login — the exact "spend where the
+  # subscription is free" mistake this system exists to kill. Found live 2026-07-12: an invalid
+  # inherited key failed the whole judgment layer with "Invalid API key". Subscription, always.
+  if OUT=$(timeout 900 env -u ANTHROPIC_API_KEY claude -p "$PROMPT" --model sonnet --allowed-tools "WebSearch,WebFetch,Read" 2>>"$LOG"); then
+    { echo ""; echo "---"; echo ""; echo "# Judgment layer (headless Claude, $(date -u +%FT%TZ))"; echo ""; echo "$OUT"; } >> "$BRIEF"
+    JUDGMENT="ok"
+  else
+    JUDGMENT="FAILED (see logs/goldie.log)"
+    { echo ""; echo "---"; echo ""; echo "# Judgment layer: FAILED this week ($(date -u +%FT%TZ)) — deterministic data above still fresh."; } >> "$BRIEF"
+  fi
+fi
+
+# ── Exactly one summary push per run — success included (silence is never a signal) ──
+HEADLINES=$(grep -E "PRICE DRIFT|NOT FOUND" "$BRIEF" | head -3)
+sh scripts/notify.sh "🧭 Goldie ran — model catalog refreshed" \
+  "Weekly brief: $BRIEF. Judgment layer: $JUDGMENT.${HEADLINES:+ ATTENTION: $HEADLINES}" \
+  default "compass" || true
+echo "===== goldie-weekly done (judgment: $JUDGMENT) =====" >> "$LOG"
+exit 0

package/scripts/health-repair.mjs

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+/**
+ * health-repair.mjs — the EXECUTOR behind the console's health recommendations.
+ *
+ * The console used to detect a corrupt memory store, score it 49/100, render it into a card, and
+ * offer nothing. Stuart, 2026-07-21: "when it finds a problem, the fact that it didn't recommend a
+ * fix is unconscionable." This is the other half — the part that actually repairs.
+ *
+ * Three actions, each matching a recommendation id from console-engine.buildHealthRecommendations:
+ *
+ *   --repair-memory   REINDEX a corrupt AgentDB store (index damage, never data loss)
+ *   --flush-learning  drain the capture queue into rUv's learner
+ *   --train-learning  run one training cycle
+ *
+ * DISCIPLINE, learned the hard way tonight:
+ *   • Back up BEFORE touching, using sqlite's own .backup — `cp` on a live WAL database silently
+ *     truncates the newest transactions (standing lesson, proven by experiment).
+ *   • Count rows before AND after, and refuse to report success if they differ.
+ *   • Never hand-roll learning: the flush/train paths shell out to rUv's own `ruflo hooks`.
+ *   • Every result is DERIVED from a re-measurement, never asserted from an exit code.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { findStores, diagnose } from './memory-doctor.mjs';
+
+const HOME = os.homedir();
+const argv = process.argv.slice(2);
+const has = (f) => argv.includes(f);
+
+/**
+ * Find ruflo HONESTLY.
+ *
+ * This was hardcoded to `~/.npm-global/bin/ruflo` — Stuart's prefix, not everyone's. On any machine
+ * with a different npm prefix (nvm, Homebrew, Volta, a plain `npm -g` on Linux), every learning
+ * action reported "ruflo not found — install it to enable learning" to a user who had ruflo
+ * installed and working. Telling someone their tool is missing when it is on their PATH is the
+ * product lying, and it is unfalsifiable from their side: they cannot see why we looked in one place.
+ *
+ * Rule 21 still holds — ONE ruflo, the global one, never `npx ruflo@latest`. This resolves WHERE
+ * that one global binary is rather than assuming a path.
+ */
+function resolveRuflo() {
+  const preferred = path.join(HOME, '.npm-global/bin/ruflo');
+  if (fs.existsSync(preferred)) return preferred;
+  const which = spawnSync('sh', ['-lc', 'command -v ruflo'], { encoding: 'utf8', timeout: 10_000 });
+  const found = String(which.stdout || '').trim().split('\n')[0];
+  return found && fs.existsSync(found) ? found : null;
+}
+const RUFLO = resolveRuflo();
+const RUFLO_ENV = { ...process.env, RUFLO_DAEMON_AUTOSTART: '0' };
+
+const sqlite = (db, sql) => execFileSync('sqlite3', [db, sql], { encoding: 'utf8', timeout: 120_000 }).trim();
+
+/** Every AgentDB store this repo knows about: the project's own, plus any passed explicitly. */
+function resolveDb() {
+  const explicit = argv[argv.indexOf('--db') + 1];
+  if (argv.includes('--db') && explicit) return explicit;
+  return path.join(process.cwd(), '.swarm', 'memory.db');
+}
+
+/**
+ * REINDEX a corrupt store. Index corruption ("wrong # of entries in index X") means the indexes
+ * drifted from the table; the rows themselves are intact, so rebuilding indexes FROM the table is
+ * lossless. Verified live: 1193 rows before, 1193 after, integrity_check ok.
+ */
+function repairMemory() {
+  const db = resolveDb();
+  if (!fs.existsSync(db)) return { ok: false, log: `no memory store at ${db.replace(HOME, '~')}` };
+
+  const before = sqlite(db, 'PRAGMA integrity_check;').split('\n')[0];
+  if (before === 'ok') return { ok: true, log: 'store was already clean — nothing to repair', noop: true };
+
+  const rowsBefore = Number(sqlite(db, 'SELECT COUNT(*) FROM memory_entries;'));
+
+  // Backup FIRST, via sqlite's own backup (never cp — a live WAL db loses its newest transactions).
+  const backup = `${db}.rescue-${new Date().toISOString().replace(/[:.]/g, '-')}`;
+  try { sqlite(db, `.backup '${backup}'`); }
+  catch (e) { return { ok: false, log: `refusing to repair — could not back up first: ${e.message}` }; }
+
+  try { sqlite(db, 'REINDEX;'); }
+  catch (e) { return { ok: false, log: `REINDEX failed: ${e.message}. Your backup is at ${backup.replace(HOME, '~')}`, backup }; }
+
+  // PROVE it, rather than trusting REINDEX's exit code.
+  const after = sqlite(db, 'PRAGMA integrity_check;').split('\n')[0];
+  const rowsAfter = Number(sqlite(db, 'SELECT COUNT(*) FROM memory_entries;'));
+
+  if (after !== 'ok') return { ok: false, log: `still corrupt after REINDEX: ${after}. Backup: ${backup.replace(HOME, '~')}`, backup };
+  if (rowsAfter !== rowsBefore) {
+    return { ok: false, log: `ROW COUNT CHANGED (${rowsBefore} → ${rowsAfter}) — treating as data loss. Restore: ${backup.replace(HOME, '~')}`, backup };
+  }
+  return { ok: true, log: `repaired — integrity ok, ${rowsAfter} entries intact (was ${rowsBefore}). Backup: ${backup.replace(HOME, '~')}`, backup };
+}
+
+/** Drain the capture queue into rUv's learner — his tool, not ours. */
+function flushLearning() {
+  const flusher = path.join(HOME, '.claude', 'plugins', 'marketplaces', 'ruvnet-brain', 'plugin', 'scripts', 'learn-flush.mjs');
+  const local = path.join(process.cwd(), 'plugin', 'scripts', 'learn-flush.mjs');
+  const script = fs.existsSync(flusher) ? flusher : (fs.existsSync(local) ? local : null);
+  if (!script) return { ok: false, log: 'learn-flush.mjs not found — cannot drain the queue' };
+
+  const queueDir = path.join(HOME, '.cache', 'ruvnet-brain', 'learn');
+  const depth = () => {
+    try {
+      return fs.readdirSync(queueDir).filter((f) => f.endsWith('.jsonl'))
+        .reduce((n, f) => n + fs.readFileSync(path.join(queueDir, f), 'utf8').split('\n').filter(Boolean).length, 0);
+    } catch { return 0; }
+  };
+  const before = depth();
+  try { execFileSync(process.execPath, [script], { stdio: 'ignore', timeout: 600_000 }); }
+  catch (e) { return { ok: false, log: `flush failed: ${e.message} — the queue is preserved for retry` }; }
+  const after = depth();
+  return { ok: true, log: `fed ${Math.max(0, before - after)} captured events into the learner (queue ${before} → ${after})` };
+}
+
+/** One training cycle, via rUv's own CLI, in the GLOBAL (cross-project) learner. */
+function trainLearning() {
+  if (!RUFLO) return { ok: false, log: 'ruflo is not on this machine — install it with `npm i -g ruflo@latest` to enable learning' };
+  try {
+    execFileSync(RUFLO, ['hooks', 'intelligence', '--train'], { cwd: HOME, env: RUFLO_ENV, stdio: 'ignore', timeout: 600_000 });
+  } catch (e) { return { ok: false, log: `training cycle failed: ${e.message}` }; }
+  return { ok: true, log: 'ran one training cycle in the cross-project learner' };
+}
+
+/**
+ * Distill every store that is embedded but has never been mined into patterns.
+ *
+ * This is the executor for ADR-027's North Star case: 87 stores holding 154,106 memories while
+ * learning nothing. The fix is NOT ours — it is rUv's ADR-174 distillation pipeline
+ * (`ruflo memory distill run`), which memory-doctor has been printing as the remedy all along while
+ * the console stayed quiet. We wire it; we do not reimplement it.
+ *
+ * Discipline, same as repairMemory():
+ *   • Snapshot each store FIRST with `ruflo memory backup` — rUv's own WAL-safe snapshotter, not cp.
+ *   • Skip stores distillation cannot help (cover < 50%): running there would burn minutes and then
+ *     truthfully report zero, which reads as failure. Not attempting is more honest than attempting.
+ *   • Re-diagnose after, and report the DERIVED pattern delta — never the exit code.
+ *   • $0: --judge defaults to 'structural' and --budget-usd defaults to 0. Nothing bills, nothing
+ *     leaves the machine. We pass both explicitly anyway so a future default change cannot silently
+ *     start spending a user's money.
+ */
+function distillFleet() {
+  if (!RUFLO) return { ok: false, log: 'ruflo is not on this machine — install it with `npm i -g ruflo@latest` to distill' };
+
+  const scope = argv.includes('--root') ? path.resolve(argv[argv.indexOf('--root') + 1]) : null;
+  const targets = [];
+  const corrupt = [];
+  let found = [];
+  try { found = scope ? findStores(scope) : findStores(); } catch { found = []; }
+  for (const db of found) {
+    const resolved = path.resolve(db);
+    let d;
+    try { d = diagnose(resolved); } catch { continue; }
+    if (d.unreadable || d.schemaless || !d.total) continue;
+    if (d.cover < 0.5 || (d.patterns ?? 0) > 0) continue;
+    // A corrupt store CANNOT be distilled — ruflo refuses it outright ("memory DB reports
+    // corruption — run recoverMemoryDatabase first"). Attempting anyway burns minutes, writes
+    // nothing, and returns a zero that reads as "distillation doesn't work". The honest answer is
+    // that repair comes FIRST, so name these instead of silently failing on them.
+    if (d.integrity && d.integrity !== 'ok') { corrupt.push(d.name); continue; }
+    targets.push({ db: resolved, name: d.name, before: d.patterns ?? 0 });
+  }
+  const corruptNote = corrupt.length
+    ? ` ${corrupt.length} store${corrupt.length === 1 ? ' was' : 's were'} skipped as corrupt and must be repaired before ${corrupt.length === 1 ? 'it' : 'they'} can be distilled: ${corrupt.slice(0, 5).join(', ')}${corrupt.length > 5 ? '…' : ''}.`
+    : '';
+  if (!targets.length) {
+    return { ok: !corrupt.length, log: `no stores were distillable — every embedded store already has patterns.${corruptNote}`, noop: true };
+  }
+
+  const done = [];
+  const failed = [];
+  const receiptPath = argv.includes('--receipt') ? argv[argv.indexOf('--receipt') + 1] : null;
+  const receipt = [];
+  const writeReceipt = () => {
+    if (!receiptPath) return;
+    try {
+      fs.mkdirSync(path.dirname(receiptPath), { recursive: true });
+      fs.writeFileSync(receiptPath, JSON.stringify({ at: new Date().toISOString(), stores: receipt }, null, 2));
+    } catch { /* the receipt is for undo; failing to write it must not fail the repair itself */ }
+  };
+
+  for (const t of targets) {
+    const dir = path.join(path.dirname(t.db), 'backups');
+    try { execFileSync(RUFLO, ['memory', 'backup', '--db', t.db, '--dir', dir], { env: RUFLO_ENV, stdio: 'ignore', timeout: 300_000 }); }
+    catch (e) { failed.push(`${t.name}: refused to distill — snapshot failed (${String(e.message).slice(0, 80)})`); continue; }
+    // Record the snapshot BEFORE distilling, and flush after every store. If the process is killed
+    // mid-fleet, the receipt still names every store already modified — a partial receipt is
+    // recoverable, a missing one is not.
+    receipt.push({ db: t.db, name: t.name, backupDir: dir });
+    writeReceipt();
+
+    try {
+      execFileSync(RUFLO, ['memory', 'distill', 'run', '--db', t.db, '--judge', 'structural', '--budget-usd', '0'],
+        { env: RUFLO_ENV, stdio: 'ignore', timeout: 1_800_000 });
+    } catch (e) { failed.push(`${t.name}: distill failed (${String(e.message).slice(0, 80)}); snapshot kept in ${dir.replace(HOME, '~')}`); continue; }
+
+    // PROVE it moved. An exit code of 0 is not evidence that anything was learned.
+    //
+    // Measured with a READ-WRITE sqlite3 connection, NOT memory-doctor's diagnose(). diagnose()
+    // opens `mode=ro`, and a read-only connection cannot build the WAL index for a database another
+    // process just wrote — so it read 0 patterns moments after distillation had in fact written 684.
+    // This executor then reported "produced no new patterns" about a run that worked perfectly.
+    // Caught live 2026-07-21. It is the standing lesson exactly: verify by the mechanism, not by a
+    // convenient instance of it — a probe that cannot see the write is not a verification.
+    let after = t.before;
+    try { after = Number(sqlite(t.db, 'SELECT count(*) FROM reasoning_patterns;')) || 0; } catch { /* unreadable — leave unchanged so we claim nothing */ }
+    if (after > t.before) done.push(`${t.name}: +${after - t.before} patterns`);
+    else failed.push(`${t.name}: ran but produced no new patterns (still ${after})`);
+  }
+
+  const log = [
+    done.length ? `distilled ${done.length} store${done.length === 1 ? '' : 's'} — ${done.join(', ')}` : 'no store gained patterns',
+    failed.length ? `${failed.length} did not: ${failed.join('; ')}` : '',
+    corruptNote.trim(),
+  ].filter(Boolean).join('. ');
+  return { ok: done.length > 0, log };
+}
+
+const action = has('--repair-memory') ? repairMemory
+  : has('--flush-learning') ? flushLearning
+    : has('--train-learning') ? trainLearning
+      : has('--distill-fleet') ? distillFleet
+        : null;
+
+if (!action) {
+  console.log('health-repair — repair actions behind the console\'s health recommendations\n');
+  console.log('  --repair-memory [--db <path>]   REINDEX a corrupt AgentDB store (backs up first, proves row count)');
+  console.log('  --flush-learning                drain the capture queue into the learner');
+  console.log('  --train-learning                run one training cycle');
+  console.log('  --distill-fleet [--root <dir>]  distill embedded-but-unmined stores (snapshots each first)');
+  process.exit(2);
+}
+
+const res = action();
+console.log(res.log);
+process.exit(res.ok ? 0 : 1);

package/scripts/helix-scenario-questions.json

@@ -0,0 +1,10 @@
+[
+  { "set": "helix-DESCRIBED (newcomer, no repo name)", "query": "How should I store and search a patient's medical history locally and privately using vectors?", "expectRepo": ["ruvector", "rulake", "concepts"], "minRelevance": -5 },
+  { "set": "helix-DESCRIBED (newcomer, no repo name)", "query": "How do I give a health agent persistent memory of past visits, labs, and medications?", "expectRepo": ["agentdb", "concepts"], "minRelevance": -5 },
+  { "set": "helix-DESCRIBED (newcomer, no repo name)", "query": "How can I run several agents in parallel to analyze one medical record?", "expectRepo": ["ruflo", "concepts"], "minRelevance": -5 },
+  { "set": "helix-DESCRIBED (newcomer, no repo name)", "query": "What methodology should I follow to plan and build the Helix data-ingestion pipeline step by step?", "expectRepo": ["sparc", "concepts", "ruflo"], "minRelevance": -5 },
+  { "set": "helix-NAMED (knows the RuvNet tool)", "query": "Should I use RuVector RVF with HNSW to store medical embeddings in Helix?", "expectRepo": ["ruvector", "concepts"], "minRelevance": -5 },
+  { "set": "helix-NAMED (knows the RuvNet tool)", "query": "Can ruflo orchestrate the diagnostic agents and swarms in Helix?", "expectRepo": ["ruflo", "concepts"], "minRelevance": -5 },
+  { "set": "helix-NAMED (knows the RuvNet tool)", "query": "Can AgentDB hold the patient's longitudinal health memory across sessions?", "expectRepo": ["agentdb", "concepts"], "minRelevance": -5 },
+  { "set": "helix-NAMED (knows the RuvNet tool)", "query": "Should I follow the SPARC methodology to build the Helix pipeline?", "expectRepo": ["sparc", "concepts", "ruflo"], "minRelevance": -5 }
+]

package/scripts/ingest-gists.mjs

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+// ingest-gists.mjs — pull rUv's public GitHub gists into the brain as their own store.
+//
+// WHY GISTS. The brain indexes rUv's REPOS, which is where an idea lands LAST. His gists are where
+// it appears FIRST: `ruflo-3.24.0-flywheel.md` was published as a gist days before anything but an
+// ADR existed in our corpus. Indexing them moves the brain's clock from "what rUv has shipped" to
+// "what rUv is thinking" — which is the whole premise of this project.
+//
+// WHY THEY ARE FENCED. A gist is an announcement, not shipped source. It routinely describes work
+// that is proposed, unreleased, or still moving. If the brain quotes a gist as fact, it will tell
+// users about features that do not exist — the exact drift this project exists to prevent, wearing
+// a new hat. So every gist passage carries a provenance banner in its own text, the same way the
+// KB already stamps `ADR STATUS: PROPOSED` onto ADR passages. Retrieval then hands the model the
+// claim AND its epistemic status together; they cannot be separated downstream.
+//
+//   node scripts/ingest-gists.mjs                    # incremental (only re-fetch changed gists)
+//   node scripts/ingest-gists.mjs --full             # ignore the cache, refetch everything
+//   node scripts/ingest-gists.mjs --owner ruvnet     # default owner
+//   node scripts/ingest-gists.mjs --dry-run          # list what would change, write nothing
+//
+// Then embed (the store becomes searchable with no restart — forge-ask-all discovers *.rvf at query
+// time):
+//   node kb/forge-big.mjs both --dir kb --name ruv-gists
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const KB = path.join(ROOT, 'kb');
+const NAME = 'ruv-gists';
+const CACHE = path.join(KB, `.${NAME}.cache.json`);
+
+const argv = process.argv.slice(2);
+const arg = (f, d = null) => { const i = argv.indexOf(f); return i !== -1 && argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : d; };
+const OWNER = arg('--owner', 'ruvnet');
+const FULL = argv.includes('--full');
+const DRY = argv.includes('--dry-run');
+// --index-only writes the human/git-trackable index from the LIST endpoint alone (~5 API calls,
+// no per-gist fetch, no embedding). That is what the nightly job runs: the KB stores are gitignored
+// and ship via Release, so nightly CI can keep the INDEX fresh even though it cannot commit vectors.
+const INDEX_ONLY = argv.includes('--index-only');
+const INDEX_PATH = path.join(ROOT, 'docs', 'RUV-GISTS.md');
+
+// Markdown/text only. A gist's code files are better read from the repo they land in; prose is the
+// thing repos don't carry.
+const TEXT_EXT = new Set(['.md', '.markdown', '.txt', '.rst']);
+
+/** Authenticated GitHub calls via `gh` — 5000 req/hr instead of 60, and no token handling here. */
+function gh(endpointArgs) {
+  const r = spawnSync('gh', endpointArgs, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  if (r.status !== 0) throw new Error(`gh ${endpointArgs.join(' ')} failed: ${(r.stderr || '').trim().slice(0, 200)}`);
+  return r.stdout;
+}
+
+async function listGists(owner) {
+  try {
+    const raw = gh(['api', `users/${owner}/gists?per_page=100`, '--paginate', '--slurp']);
+    const pages = JSON.parse(raw);
+    // --slurp yields an array of pages OR a flat array depending on gh version; flatten defensively.
+    return pages.flat().filter((g) => g && g.id);
+  } catch (err) {
+    // In Actions, gh can NEVER list gists: GITHUB_TOKEN is a GitHub App token and the gists API is
+    // closed to those ("Resource not accessible by integration", HTTP 403 — every nightly run since
+    // birth). Public gists need no auth at all, so fall back to the plain API (60 req/hr per IP).
+    console.error(`  gh failed (${String(err.message).slice(0, 100)}) — falling back to unauthenticated API`);
+    return listGistsPublic(owner);
+  }
+}
+
+// Hermetic-test seam (same pattern as the router's MODEL_ROUTER_CATALOG): integration tests point
+// this at an unreachable port to exercise the fallback's failure path without touching the live API.
+const API_BASE = process.env.RUVNET_GISTS_API || 'https://api.github.com';
+
+async function listGistsPublic(owner) {
+  const all = [];
+  for (let page = 1; page <= 10; page++) {
+    const res = await fetch(`${API_BASE}/users/${owner}/gists?per_page=100&page=${page}`, {
+      headers: { accept: 'application/vnd.github+json', 'user-agent': 'ruvnet-brain-gists-index' },
+    });
+    if (res.status === 403 || res.status === 429) {
+      const err = new Error(`unauthenticated gists list rate-limited (HTTP ${res.status})`);
+      err.rateLimited = true; // runner IPs share the anonymous quota — a known, transient condition
+      throw err;
+    }
+    if (!res.ok) throw new Error(`unauthenticated gists list failed: HTTP ${res.status}`);
+    const items = await res.json();
+    all.push(...items.filter((g) => g && g.id));
+    if (items.length < 100) break;
+  }
+  return all;
+}
+
+/** Raw file bodies. The list endpoint truncates `content`, so fetch each gist individually. */
+function fetchGist(id) {
+  return JSON.parse(gh(['api', `gists/${id}`]));
+}
+
+// ~3200-char paragraph-aligned chunks — same shape build-concepts.mjs uses, so the reader's chunk
+// handling and the `#N` suffix convention stay uniform across stores.
+function chunk(text, size = 3200) {
+  const out = [];
+  let buf = '';
+  for (const para of text.split(/\n\n+/)) {
+    if (buf && buf.length + para.length + 2 > size) { out.push(buf); buf = ''; }
+    buf = buf ? `${buf}\n\n${para}` : para;
+  }
+  if (buf.trim()) out.push(buf);
+  return out.length ? out : [];
+}
+
+/** The banner that travels WITH the text, so a retrieval hit can never lose its provenance. */
+const banner = (g, file) =>
+  `SOURCE: GitHub gist by @${OWNER} — "${(g.description || file).replace(/\s+/g, ' ').trim().slice(0, 160)}"\n` +
+  `GIST STATUS: rUv's own notes / release announcement — may describe PROPOSED or UNRELEASED work.\n` +
+  `Treat as intent, not as confirmed shipped behavior: verify against repo source before asserting.\n` +
+  `updated: ${g.updated_at?.slice(0, 10)} · https://gist.github.com/${OWNER}/${g.id}\n\n`;
+
+/** A tiny, git-trackable feed of what rUv has published, newest first. Costs ~5 API calls. */
+function writeIndex(gists) {
+  const rows = [...gists].sort((a, b) => b.updated_at.localeCompare(a.updated_at));
+  const lines = [
+    '# rUv\'s public gists — index',
+    '',
+    '> Auto-generated by `node scripts/ingest-gists.mjs --index-only`. Newest first.',
+    '>',
+    '> **These are announcements and notes, not shipped source.** A gist routinely describes work that is',
+    '> proposed, unreleased, or still moving. Verify against repo source before asserting behavior.',
+    '',
+    `_${rows.length} gists · refreshed ${new Date().toISOString().slice(0, 10)}_`,
+    '',
+    '| Updated | Gist | Description |',
+    '|---|---|---|',
+  ];
+  for (const g of rows) {
+    const file = Object.keys(g.files || {})[0] || '(no files)';
+    const desc = (g.description || '').replace(/\s+/g, ' ').replace(/\|/g, '\\|').trim().slice(0, 120) || '—';
+    lines.push(`| ${g.updated_at.slice(0, 10)} | [${file}](https://gist.github.com/${OWNER}/${g.id}) | ${desc} |`);
+  }
+  fs.mkdirSync(path.dirname(INDEX_PATH), { recursive: true });
+  fs.writeFileSync(INDEX_PATH, lines.join('\n') + '\n');
+  console.log(`  wrote ${path.relative(ROOT, INDEX_PATH)} (${rows.length} rows)`);
+}
+
+async function main() {
+  if (!fs.existsSync(KB)) { console.error(`ingest-gists: no kb dir at ${KB}`); process.exit(2); }
+
+  const cache = !FULL && fs.existsSync(CACHE) ? JSON.parse(fs.readFileSync(CACHE, 'utf8')) : {};
+  console.log(`ingest-gists: listing public gists for @${OWNER}…`);
+  let gists;
+  try {
+    gists = await listGists(OWNER);
+  } catch (err) {
+    if (INDEX_ONLY && err.rateLimited) {
+      // The index is a freshness feed; one skipped night self-heals on the next run. Exit 0 so a
+      // transient shared-IP rate limit doesn't page anyone — real script errors still exit 1.
+      console.error(`ingest-gists: SKIP — ${err.message}; the index catches up on the next nightly.`);
+      process.exit(0);
+    }
+    throw err;
+  }
+  console.log(`  ${gists.length} gists found`);
+
+  if (INDEX_ONLY) { writeIndex(gists); return; }
+
+  const changed = gists.filter((g) => cache[g.id] !== g.updated_at);
+  console.log(`  ${changed.length} new or updated since last run${FULL ? ' (--full: cache ignored)' : ''}`);
+  if (DRY) {
+    for (const g of changed.slice(0, 20)) console.log(`    ${g.updated_at.slice(0, 10)}  ${Object.keys(g.files)[0]}`);
+    if (changed.length > 20) console.log(`    … and ${changed.length - 20} more`);
+    return;
+  }
+  if (!changed.length && fs.existsSync(path.join(KB, `${NAME}.passages.jsonl`))) {
+    console.log('  nothing to do — store is current.');
+    return;
+  }
+
+  // Full rebuild of the passage file (ids must stay dense and aligned with the .rvf idmap; a
+  // partial append would desynchronise them — the failure mode that maps a vector to the wrong text).
+  const passages = [];
+  const entries = {};
+  let id = 0;
+  let files = 0;
+  let skipped = 0;
+
+  for (const [i, stub] of gists.entries()) {
+    if (i % 25 === 0) process.stdout.write(`\r  fetching ${i}/${gists.length}…`);
+    let g;
+    try { g = fetchGist(stub.id); } catch { skipped++; continue; }
+    for (const [fname, f] of Object.entries(g.files || {})) {
+      if (!TEXT_EXT.has(path.extname(fname).toLowerCase())) continue;
+      const body = f.truncated && f.raw_url ? '' : (f.content || '');
+      if (!body.trim()) { skipped++; continue; }
+      const title = (g.description || fname).replace(/\s+/g, ' ').trim().slice(0, 180) || fname;
+      const head = banner(g, fname);
+      // Banner on EVERY chunk, not just the first. Retrieval returns ONE chunk — if the provenance
+      // lives only in chunk 0, then chunk 2 reaches the model as an unlabelled assertion, which is
+      // exactly the fence this file claims to build. (Caught by reading a real retrieval: the top
+      // hit for "enable the flywheel" was `…flywheel.md#2` and carried no status line.)
+      const chunks = chunk(body);
+      chunks.forEach((c, ci) => {
+        const sid = String(id++);
+        const p = `${g.id.slice(0, 8)}/${fname}${chunks.length > 1 ? `#${ci}` : ''}`;
+        const text = head + c;
+        passages.push({ id: sid, text, path: p, title });
+        entries[sid] = { path: p, kind: 'doc', title, chunk: ci, preview: text.slice(0, 200) };
+      });
+      files++;
+    }
+    cache[stub.id] = stub.updated_at;
+  }
+  process.stdout.write('\r');
+
+  fs.writeFileSync(path.join(KB, `${NAME}.passages.jsonl`), passages.map((p) => JSON.stringify(p)).join('\n') + '\n');
+  fs.writeFileSync(path.join(KB, `${NAME}.meta.json`), JSON.stringify({
+    model: NAME, dimensions: 0, metric: 'cosine', name: NAME,
+    generated: new Date().toISOString(), repo: `gists/${OWNER}`,
+    note: "rUv's public gists — announcements and thinking, PROPOSED unless confirmed in repo source.",
+    entries,
+  }, null, 2));
+  fs.writeFileSync(CACHE, JSON.stringify(cache, null, 2));
+
+  console.log(`ingest-gists: ${gists.length} gists · ${files} text files · ${passages.length} passages · ${skipped} skipped`);
+  writeIndex(gists);
+  console.log(`  wrote kb/${NAME}.passages.jsonl + kb/${NAME}.meta.json`);
+  console.log(`  next: node kb/forge-big.mjs both --dir kb --name ${NAME}   (embed → ${NAME}.big.rvf)`);
+}
+
+await main();