ruvnet-brain 1.14.0-dev → 1.16.0-dev

package/README.md

@@ -4,7 +4,7 @@
 
 # 🧠 RuvNet Brain
 
-### 🧠 RuvNet Brain — [![RuvNet Brain version 1.14.0-dev — updated 2026-07-08 07:21 EDT](https://img.shields.io/badge/version_1.14.0--dev-updated_2026--07--08_07:21_EDT-1E90FF?style=for-the-badge&labelColor=0757BA)](https://github.com/stuinfla/ruvnet-brain/blob/main/plugin/.claude-plugin/plugin.json)
+### 🧠 RuvNet Brain — [![RuvNet Brain version 1.16.0-dev — updated 2026-07-09 04:53 EDT](https://img.shields.io/badge/version_1.16.0--dev-updated_2026--07--09_04:53_EDT-1E90FF?style=for-the-badge&labelColor=0757BA)](https://github.com/stuinfla/ruvnet-brain/blob/main/plugin/.claude-plugin/plugin.json)
 
 **A portable, source-grounded brain over Reuven Cohen's (rUv's) RuvNet stack — delivered as a Claude Code plugin that makes Claude _use_ the stack instead of fighting it.**
 
@@ -14,12 +14,15 @@
 [![explainer](https://img.shields.io/badge/▶%20see%20it%20live-isovision.ai%2Fruvnet--brain-e8a13a?style=flat-square)](https://isovision.ai/ruvnet-brain/)
 [![license](https://img.shields.io/badge/license-MIT-8ecae6?style=flat-square)](LICENSE)
 [![grounded](https://img.shields.io/badge/answers-cited%20rUv%20source-333?style=flat-square)](#testing--proof)
-[![coverage](https://img.shields.io/badge/coverage-75%25%20lines%20·%2072%25%20stmts-2e7d32?style=flat-square)](#testing--proof)
+[![coverage](https://img.shields.io/badge/coverage-10%25%20of%20ALL%20source%20·%20honest-b58900?style=flat-square)](#testing--proof)
 
 > **Three independent things version separately here — by design, not drift. Every number below is live (read straight from its real source, never hand-typed), so none of them can go stale:**
 > - **`plugin`** (badge above) — the Claude Code plugin itself: SKILL.md, the grounding hooks, the MCP server. Read live from [`plugin/.claude-plugin/plugin.json`](plugin/.claude-plugin/plugin.json). Updates often — this is where behavior fixes land.
 > - **`installer (npm)`** (badge above) — the `npx ruvnet-brain` setup script. Read live from the [npm registry](https://www.npmjs.com/package/ruvnet-brain). Only moves when the installer script itself changes — rare.
 > - **Brain Release** (the downloadable 512MB knowledge bundle, linked from the "download" badge above) — always resolves to [`releases/latest`](https://github.com/stuinfla/ruvnet-brain/releases/latest), currently `v0.5.0-dev`. Only moves when the underlying knowledge base is rebuilt — separate again from the two above.
+> - **Update an installed brain once:** `npx ruvnet-brain --update` — runs the bundle's own self-updater (backs up first, re-verifies, fails loud instead of half-applying).
+> - **Nightly auto-update is OFF by default:** `npx ruvnet-brain --enable-nightly` schedules it (macOS LaunchAgent, 03:47); `npx ruvnet-brain --disable-nightly` removes it; Linux/Windows get the cron line documented in the bundle's `forge-update.mjs`.
+> - **Either way, your copy only advances when a new Release is published** — the updater pulls `releases/latest`, so running it between releases is a safe no-op.
 
 <sub>Built by **[Stuart Kerr](https://isovision.ai)** at [Isovision.ai](https://isovision.ai) · free & fair use, to help everyone leverage the high end of agentic coding.</sub>
 
@@ -204,7 +207,7 @@ node plugin/test/run-tests.mjs                    # full plugin QA over real JSO
 | **L1–L4 behavioral harness** | **all pass** | route · deep-recall (returns _code_) · implement (cites the API) · orchestrate (the hook drives the full pipeline) |
 | **Plugin QA** | **26 / 26** | manifests, hook firing, MCP `initialize`/`tools/list`, capability battery |
 | **Clean-room install** | **3 / 3** | download the published 512 MB bundle fresh → unzip → query → grounded, cited answers |
-| **Unit tests** | **154 passing** · 75% lines | `npm run test:cov` — a CI floor fails the build if coverage slips |
+| **Unit tests** | **208 passing** · 10% of ALL source covered | `npm run test:cov` — the floor fails CI if it slips. 10% is the honest number over every shipped file; the previous "75%" measured a hand-picked 8-file subset |
 | **Grounding proof** | `npx ruvnet-brain --doctor` | asks a real question, then checks the cited path really exists in the on-disk store; a citation that doesn't resolve is reported as **NOT grounded** |
 | **Held-out eval** | **grounded 12/12** · routed 10/12 | `npm run eval` — 12 frozen questions never used for tuning, graded on ground truth, never by a model |
 

package/bin/install.mjs

@@ -65,6 +65,10 @@ const FLAG_DOCTOR = argv.includes('--doctor');
 const FLAG_NO_VERIFY = argv.includes('--no-verify');
 const FLAG_PIN = argv.includes('--pin'); // skip the latest-check, use the bundled default
 const FLAG_DEMO = argv.includes('--demo'); // guided, real (non-fabricated) walkthrough of the brain in action
+// ── freshness flags — invoke/schedule the SELF-UPDATER the bundle already ships (kb/forge-update.mjs) ──
+const FLAG_UPDATE = argv.includes('--update'); // one-shot: pull the latest Release bundle into the installed brain now
+const FLAG_ENABLE_NIGHTLY = argv.includes('--enable-nightly'); // schedule that update nightly (macOS LaunchAgent)
+const FLAG_DISABLE_NIGHTLY = argv.includes('--disable-nightly'); // remove the nightly schedule
 // ── onboarding-experience flags (all optional; every offer is safe to decline) ──
 const FLAG_YES = argv.includes('--yes') || argv.includes('-y'); // accept every optional offer non-interactively
 const FLAG_WITH_STACK = argv.includes('--with-stack'); // add missing Ruflo/RuVector without prompting
@@ -725,6 +729,163 @@ async function doctor() {
   );
 }
 
+// ── `--update` / `--enable-nightly` / `--disable-nightly`: end-user freshness controls ────────────
+// The brain bundle SHIPS its own self-updater (forge-update.mjs, right in the KB dir): it pulls the
+// canonical Release bundle, backs the current copy up, extracts, and re-verifies with forge-guard —
+// failing loud with no partial clobber. These flags never reimplement any of that; they only INVOKE
+// it once (--update) or SCHEDULE it per-user (--enable-nightly). Nothing here ever publishes.
+const NIGHTLY_LABEL = 'com.ruvnet.brain-update';
+const resolvedKbDir = () =>
+  process.env.RUVNET_BRAIN_KB || path.join(os.homedir(), '.cache', 'ruvnet-brain', 'kb');
+const nightlyPlistPath = () =>
+  path.join(os.homedir(), 'Library', 'LaunchAgents', `${NIGHTLY_LABEL}.plist`);
+// RUVNET_BRAIN_TEST=1 → write/remove the plist but NEVER call launchctl. Tests point HOME at a temp
+// dir; bootstrapping a temp-dir plist into the user's real gui domain would mutate exactly the
+// system state the tests promise not to touch.
+const TEST_MODE = process.env.RUVNET_BRAIN_TEST === '1';
+const xmlEscape = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+// The same nightly command, cron-flavored — the pattern forge-update.mjs documents in its header.
+// 03:47 on purpose: an off-hour minute, so it never piles onto the :00 cron rush.
+const cronExample = (kbDir) =>
+  `47 3 * * *  cd ${kbDir} && ${process.execPath} forge-update.mjs --apply >> ${kbDir}/update.log 2>&1`;
+
+function missingUpdaterHelp(kbDir) {
+  console.error(`\n${c.red('✗ can\'t update:')} ${c.bold('forge-update.mjs')} is missing from ${kbDir}.`);
+  console.error(`  Either no brain is installed there, or the bundle predates the self-updater.`);
+  console.error(`  Fix: re-run the installer —  ${c.bold('npx ruvnet-brain')}  ${c.dim('(add --force if a brain is already present)')}`);
+  console.error(`  — the current bundle ships forge-update.mjs; then this command will work.`);
+}
+
+function runUpdate() {
+  printBanner('update');
+  const kbDir = resolvedKbDir();
+  info(`brain dir: ${c.bold(kbDir)}`);
+  if (!fs.existsSync(path.join(kbDir, 'forge-update.mjs'))) {
+    missingUpdaterHelp(kbDir);
+    process.exit(1);
+  }
+  info(c.dim("running the bundle's own self-updater (backs up first, re-verifies, never half-applies)…\n"));
+  // Relative filename + matching cwd — same launch convention as smokeQuery(); stdio:'inherit'
+  // streams the updater's narration live and unedited.
+  const r = spawnSync(process.execPath, ['forge-update.mjs', '--apply'], { cwd: kbDir, stdio: 'inherit' });
+  if (r.error) {
+    console.error(`\n${c.red('✗ update failed to launch:')} ${r.error.message}`);
+    process.exit(1);
+  }
+  process.exit(r.status === null ? 1 : r.status); // exit with the updater's own verdict
+}
+
+function enableNightly() {
+  printBanner('enable nightly updates');
+  const kbDir = resolvedKbDir();
+
+  if (process.platform !== 'darwin') {
+    info('The LaunchAgent scheduler is macOS-only (for now).');
+    info("On this platform, schedule the bundle's self-updater with cron — the pattern");
+    info('forge-update.mjs itself documents:');
+    console.log(`\n    ${c.bold(cronExample(kbDir))}\n`);
+    info(`(${c.bold('crontab -e')}, paste the line, save. Remove the line to disable.)`);
+    return; // exit 0 — the user got the working recipe
+  }
+
+  info(`brain dir: ${c.bold(kbDir)}`);
+  if (!fs.existsSync(path.join(kbDir, 'forge-update.mjs'))) {
+    // Refuse to schedule a job that is guaranteed to fail every night — fail loud NOW instead.
+    missingUpdaterHelp(kbDir);
+    process.exit(1);
+  }
+
+  // Template the plist to THIS user's kb dir + node binary. Quotes guard paths with spaces;
+  // xmlEscape guards the XML (>> and && must survive as shell operators after plist parsing).
+  const logPath = path.join(kbDir, 'update.log');
+  const shellCmd = `cd "${kbDir}" && "${process.execPath}" forge-update.mjs --apply >> "${logPath}" 2>&1`;
+  const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${NIGHTLY_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/bin/sh</string>
+    <string>-c</string>
+    <string>${xmlEscape(shellCmd)}</string>
+  </array>
+  <key>StartCalendarInterval</key>
+  <dict>
+    <key>Hour</key>
+    <integer>3</integer>
+    <key>Minute</key>
+    <integer>47</integer>
+  </dict>
+  <key>RunAtLoad</key>
+  <false/>
+</dict>
+</plist>
+`;
+  const plistPath = nightlyPlistPath();
+  try {
+    fs.mkdirSync(path.dirname(plistPath), { recursive: true });
+    fs.writeFileSync(plistPath, plist);
+  } catch (e) {
+    console.error(`\n${c.red('✗ couldn\'t write the LaunchAgent:')} ${e.message}`);
+    process.exit(1);
+  }
+  ok(`wrote ${c.bold(plistPath)}`);
+  info(c.dim('runs nightly at 03:47 — an off-hour minute, so it never lands on the :00 rush'));
+
+  if (TEST_MODE) {
+    warn('RUVNET_BRAIN_TEST=1 — skipping launchctl bootout/bootstrap (plist written only)');
+  } else {
+    const uid = process.getuid();
+    // bootout first so re-running replaces the loaded job cleanly; failure just means "wasn't loaded".
+    spawnSync('launchctl', ['bootout', `gui/${uid}/${NIGHTLY_LABEL}`], { stdio: 'ignore' });
+    const boot = spawnSync('launchctl', ['bootstrap', `gui/${uid}`, plistPath], { encoding: 'utf8' });
+    if (boot.status === 0) ok('LaunchAgent loaded — your brain now updates while you sleep');
+    else {
+      warn(`launchctl bootstrap failed (${(boot.stderr || '').trim() || `exit ${boot.status}`}) — the plist is in place;`);
+      info(`load it yourself:  ${c.bold(`launchctl bootstrap gui/${uid} ${plistPath}`)}`);
+    }
+  }
+
+  console.log(`\n  ${c.bold('Verify it:')}   launchctl list | grep ${NIGHTLY_LABEL}`);
+  console.log(`  ${c.bold('Watch it:')}    tail ${logPath}   ${c.dim('(appears after the first nightly run)')}`);
+  console.log(`  ${c.bold('Disable it:')}  npx ruvnet-brain --disable-nightly`);
+  console.log(`\n  ${c.dim('It only ever PULLS the published Release bundle (backup + re-verify built in) — it never publishes,')}`);
+  console.log(`  ${c.dim('and a night with no new Release is a clean no-op.')}\n`);
+}
+
+function disableNightly() {
+  printBanner('disable nightly updates');
+  if (process.platform !== 'darwin') {
+    info('The LaunchAgent nightly is macOS-only, so nothing was scheduled here by this tool.');
+    info(`If you added the cron line yourself, remove it with:  ${c.bold('crontab -e')}`);
+    return;
+  }
+  const plistPath = nightlyPlistPath();
+  const existed = fs.existsSync(plistPath);
+  if (TEST_MODE) {
+    warn('RUVNET_BRAIN_TEST=1 — skipping launchctl bootout (plist removal only)');
+  } else {
+    // Ignore failure: "not loaded" is exactly the state we want anyway.
+    spawnSync('launchctl', ['bootout', `gui/${process.getuid()}/${NIGHTLY_LABEL}`], { stdio: 'ignore' });
+  }
+  if (existed) {
+    try {
+      fs.rmSync(plistPath);
+    } catch (e) {
+      console.error(`\n${c.red('✗ couldn\'t remove the LaunchAgent:')} ${e.message}`);
+      console.error(`  Remove it yourself:  rm ${plistPath}`);
+      process.exit(1);
+    }
+    ok(`nightly updates disabled — removed ${plistPath}`);
+  } else {
+    ok('nightly updates were already off — nothing to remove (safe to run any time)');
+  }
+  info(`re-enable any time:  ${c.bold('npx ruvnet-brain --enable-nightly')}`);
+}
+
 // ── tiny interactive yes/no — SAFE in non-TTY (returns the default; never blocks a piped install) ──
 function ask(question, def = false) {
   if (FLAG_YES) return Promise.resolve(true);
@@ -949,9 +1110,14 @@ function success({ cacheDir, isCustom, plugin, env }) {
     • Want to see it answer, live, right now?  ${c.bold('npx ruvnet-brain --demo')}  — 2 real questions, real cited answers.`);
 
   console.log(`\n  ${c.bold('Set it up your way:')} this default is ${c.bold('global')} — live in every VS Code project automatically,`);
-  console.log(`    which is what most people want. Want it different (project-only, moved, with the build stack added,`);
-  console.log(`    auto-updating nightly)? ${c.bold('Just tell Claude')} once it's on — the brain is smart enough to reconfigure`);
-  console.log(`    itself. You never have to learn its internals.`);
+  console.log(`    which is what most people want. Want it different (project-only, moved, with the build stack`);
+  console.log(`    added)? ${c.bold('Just tell Claude')} once it's on. You never have to learn its internals.`);
+
+  console.log(`\n  ${c.bold('Staying current:')} nightly updates are ${c.bold('OFF by default')} — nothing runs on your machine unasked.`);
+  console.log(`    • one-shot check + update now:   ${c.bold('npx ruvnet-brain --update')}`);
+  console.log(`    • nightly at 03:47 (macOS):      ${c.bold('npx ruvnet-brain --enable-nightly')}   ${c.dim('· off again: --disable-nightly')}`);
+  console.log(`    • Linux/Windows: the cron line documented in the brain's own ${c.bold('forge-update.mjs')}`);
+  console.log(`    ${c.dim('Either way, your copy only advances when a new Release is actually published.')}`);
 
   console.log(`\n  ${c.dim('You can\'t break anything — the plugin is disable-able and only acts on RuvNet-shaped work.')}`);
   console.log('');
@@ -969,6 +1135,11 @@ Usage:
   npx github:stuinfla/ruvnet-brain         Same, but from the bleeding-edge GitHub commit
   npx ruvnet-brain --doctor   Health-check an existing install (green/red per part)
   npx ruvnet-brain --demo     Guided walkthrough — 2 real questions, real cited answers
+  npx ruvnet-brain --update   One-shot: pull the latest Release bundle into your installed brain
+                              (runs the bundle's own forge-update.mjs --apply: backup + re-verify)
+  npx ruvnet-brain --enable-nightly    Schedule that update nightly at 03:47 — macOS LaunchAgent;
+                              other platforms get the documented cron line. OFF by default.
+  npx ruvnet-brain --disable-nightly   Remove the nightly schedule (safe to run any time)
   node bin/install.mjs --version <tag>     Install a specific Release tag (e.g. --version v0.4.0-dev)
   node bin/install.mjs --pin               Skip the latest-check; use the bundled known-good version
   node bin/install.mjs --local             Install from a repo clone's dist/ruvnet-brain.zip
@@ -992,6 +1163,9 @@ It is safe to re-run at any time. After installing, restart Claude Code so the g
   if (FLAG_HELP) return showHelp();
   if (FLAG_DOCTOR) return await doctor();
   if (FLAG_DEMO) return runDemo();
+  if (FLAG_UPDATE) return runUpdate();
+  if (FLAG_ENABLE_NIGHTLY) return enableNightly();
+  if (FLAG_DISABLE_NIGHTLY) return disableNightly();
 
   printBanner('installer');
   console.log(c.dim("I'll set up the brain and the Claude Code plugin, explaining each step as I go.\n"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "1.14.0-dev",
+  "version": "1.16.0-dev",
   "description": "One-command installer for RuvNet Brain — a portable, source-grounded brain over rUv's RuvNet building blocks, delivered as a Claude Code plugin so Claude uses the stack instead of fighting it.",
   "type": "module",
   "bin": {
@@ -9,16 +9,21 @@
   "scripts": {
     "test": "node plugin/test/run-tests.mjs",
     "version:check": "node scripts/sync-version.mjs --check",
+    "claims:verify": "node scripts/claims-verify.mjs",
     "version:sync": "node scripts/sync-version.mjs",
-    "test:unit": "vitest run",
-    "test:cov": "vitest run --coverage",
+    "test:unit": "vitest run tests/unit",
+    "test:cov": "vitest run tests/unit --coverage",
+    "test:all": "npm run test:unit && npm run test:integration && npm test",
     "metaharness:fix": "node scripts/fix-metaharness-memretrieve.mjs --apply",
     "metaharness:check": "node scripts/fix-metaharness-memretrieve.mjs --check",
     "eval": "node scripts/eval-brain.mjs",
     "eval:gate": "node scripts/eval-brain.mjs --gate",
     "eval:record": "node scripts/eval-brain.mjs --record",
     "embed:verifier": "node scripts/embed-verifier.mjs",
-    "embed:check": "node scripts/embed-verifier.mjs --check"
+    "embed:check": "node scripts/embed-verifier.mjs --check",
+    "gists:index": "node scripts/ingest-gists.mjs --index-only",
+    "gists:sync": "node scripts/ingest-gists.mjs && node kb/forge-big.mjs both --dir kb --name ruv-gists",
+    "test:integration": "vitest run tests/integration"
   },
   "files": [
     "bin/install.mjs",
@@ -50,6 +55,7 @@
   "bugs": "https://github.com/stuinfla/ruvnet-brain/issues",
   "author": "Stuart Kerr",
   "devDependencies": {
+    "@metaharness/darwin": "~0.8.0",
     "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }