ruvnet-brain 3.9.18-dev → 3.9.51-dev

package/README.md

@@ -4,7 +4,7 @@
 
 # 🧠 RuvNet Brain
 
-### 🧠 RuvNet Brain — [![RuvNet Brain version 3.9.18-dev — updated 2026-07-23 04:06 EDT](https://img.shields.io/badge/version_3.9.18--dev-updated_2026--07--23_04:06_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 3.9.51-dev — updated 2026-07-23 04:06 EDT](https://img.shields.io/badge/version_3.9.51--dev-updated_2026--07--23_04:06_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.**
 
@@ -142,9 +142,12 @@ answers the question the owner has been asking for weeks — **"what is actually
   had zero call sites; the client referenced it only in comments. Built-tested-unwired is this
   project's signature failure, and it happened three times in one night.
 
-Honest limit: this is **3.6, not 4.0**. 4.0 requires levels 3–5 of ADR-028's proactivity ladder
-(contextual, anticipatory, compounding) and all three remain unbuilt — see `docs/4.0-READINESS.md`,
-which grades the current state at **L2** with evidence for every mark.
+Honest limit: this is still a dev release, **not 4.0**. 4.0 requires levels 3–5 of ADR-028's ladder
+(contextual, anticipatory, compounding) **shipped and independently graded ≥95**. The mechanisms now
+exist — L3's delivery seam (the chokepoint), an L4 goal surface, and L5 cross-project promotion (lessons
+promoted to your global brain, survival proven by isolation) — but the ladder still grades **L2–L3**,
+because L3 is built rather than live (deploy-gated) and the five acceptance metrics aren't all measured.
+See `docs/4.0-READINESS.md` and `docs/4.0-EXECUTIVE-BRIEFING.md` (last independent grade: 70/100 overall).
 
 <details>
 <summary><b>Earlier &#8212; what 3.5 shipped</b> &#183; it stopped waiting to be asked. <i>Expand for the receipts.</i></summary>
@@ -406,7 +409,7 @@ Plus: the **“take the wheel” behavioral pipeline** (below), a **4-level beha
 
 ## How it works
 
-The expensive work happens **once, at build time**: every covered repo is deep-walked (whole files, full function bodies, plus a symbol index), embedded into **two** vector variants (MiniLM-384 for edge/portability, bge-768 for depth) stored on-disk in **RVF / HNSW**, and distilled into a concepts + capability layer of per-repo primers and cards. That's **149,721 source chunks**. At **query time**, `search_ruvnet` searches every repo's store at once, pools the hits, and runs them through **one cross-encoder rerank** on a common scale — so the truly relevant file wins regardless of which repo it lives in — then returns whole source files, each labeled by repo and path.
+The expensive work happens **once, at build time**: every covered repo is deep-walked (whole files, full function bodies, plus a symbol index), embedded into **two** vector variants (MiniLM-384 for edge/portability, bge-768 for depth) stored on-disk in **RVF / HNSW**, and distilled into a concepts + capability layer of per-repo primers and cards. That's **149,729 source chunks**. At **query time**, `search_ruvnet` searches every repo's store at once, pools the hits, and runs them through **one cross-encoder rerank** on a common scale — so the truly relevant file wins regardless of which repo it lives in — then returns whole source files, each labeled by repo and path.
 
 ![RuvNet Brain architecture pipeline](assets/diagrams/architecture-pipeline.svg)
 
@@ -516,7 +519,7 @@ node forge-ask-all.mjs --dir . --q "How does RuVector implement HNSW vector sear
 
 This project versions in the open (see the live badge up top for the exact plugin version; the downloadable knowledge bundle is a separate track) — we don't claim “done,” “complete,” or “zero hallucinations.” Where it stands:
 
-- ✅ **The grounding brain is real and proven** — 54 public stores · 149,721 public source chunks (57 built stores incl. private), dual embeddings, cross-encoder rerank, plugin (MCP tool + enforcement hook + skill), all re-runnable.
+- ✅ **The grounding brain is real and proven** — 54 public stores · 149,729 public source chunks (57 built stores incl. private), dual embeddings, cross-encoder rerank, plugin (MCP tool + enforcement hook + skill), all re-runnable.
 - ✅ **Code-level depth** — the code-rich repos are indexed to full function bodies; “how is it implemented?” returns the implementation. Verified in the shipped bundle (clean-room 3/3).
 - ✅ **Routing holds** — named 47/48, described 26/28, scenario 7/8; behavioral L1–L4 all pass; private stores fenced out of the public bundle (zero-leak verified).
 - ⚠️ **Two routing residuals** (above) — surfaced, not hidden.

package/bin/install.mjs

@@ -1412,6 +1412,12 @@ function disableSpendGuard() {
   else ok('spend watchdog was already off — nothing to remove (safe to run any time)');
 }
 
+// Default STATE_PATH from scripts/upgrade-notice.mjs, duplicated (not imported — see the cmpTag()
+// comment above this file's own rule on why) so machineFootprint()/uninstallAll() can find and
+// remove it without a module this file may not statically depend on.
+const upgradeNoticeStatePath = () =>
+  process.env.RUVNET_UPGRADE_NOTICE_FILE || path.join(os.homedir(), '.config', 'ruvnet-brain', 'upgrade-notice.json');
+
 /**
  * Everything this installer can leave on a machine, DERIVED from disk — never asserted.
  *
@@ -1435,7 +1441,14 @@ export function machineFootprint() {
   if (cmds) items.push({
     label: 'Claude Code plugin',
     path: path.dirname(cmds),
-    undo: 'claude plugin uninstall ruvnet-brain@ruvnet-brain',
+    // `claude plugin uninstall` removes the INSTALLED plugin only — it leaves the marketplace itself
+    // registered (a separate git clone + registry entry: `claude plugin marketplace list` still
+    // shows it, and wirePlugin() above is the thing that added it via `claude plugin marketplace add
+    // stuinfla/ruvnet-brain`). Verified live against `claude plugin marketplace --help` (marketplace
+    // name = "ruvnet-brain", from this repo's own .claude-plugin/marketplace.json) that `remove` takes
+    // that same short name. Without this second command someone who ran every undo we printed would
+    // still have us registered as a marketplace.
+    undo: 'claude plugin uninstall ruvnet-brain@ruvnet-brain && claude plugin marketplace remove ruvnet-brain',
   });
   const cmdPath = path.join(os.homedir(), '.claude', 'CLAUDE.md');
   try {
@@ -1457,12 +1470,21 @@ export function machineFootprint() {
   add('Status-bar preference', path.join(telemetryStateDir(), '.statusline-pref'), 'delete this file');
   add('Model-router files', path.join(os.homedir(), '.claude', 'model-router'),
       'rm -rf ~/.claude/model-router');
-  // Config entries live INSIDE files the user owns, so they are reported as edits to review rather
-  // than as paths to delete — deleting someone's settings.json over one key would be indefensible.
+  // GAP FIX: this used to be a loose `.includes('ruvnet-brain')` substring test against the WHOLE
+  // settings.json file — which (a) could also fire on something unrelated (e.g. a marketplace
+  // autoUpdate setting that merely mentions our name) and get mislabeled as "the statusLine entry",
+  // and (b) meant this was ALWAYS reported as a manual edit, never auto-removed, even though this
+  // installer is the one that wrote the key and knows exactly what it wrote. detectStatusLine() now
+  // checks the actual parsed statusLine.command against the exact string writeSettingsStatusLine()
+  // writes — precise enough that removeSettingsStatusLine() (called from uninstallAll()) can safely
+  // reverse just this key, the same way removeClaudeMdBlock() reverses just its own block. A status
+  // line a user has since edited or folded into their own script no longer matches and is correctly
+  // left off this list entirely (nothing to claim, nothing to undo).
   try {
-    const settings = path.join(os.homedir(), '.claude', 'settings.json');
-    if (fs.existsSync(settings) && fs.readFileSync(settings, 'utf8').includes('ruvnet-brain')) {
-      items.push({ label: 'A statusLine entry in your settings.json', path: settings, undo: 'remove the "statusLine" entry that points at ruvnet-brain' });
+    const settings = settingsJsonPath();
+    const detected = detectStatusLine(settings);
+    if (detected.hasStatusLine && !detected.parseError && detected.command === `node "${statuslineHelperPath()}"`) {
+      items.push({ label: 'The statusLine entry in settings.json', path: settings, undo: 'npx ruvnet-brain --uninstall (removes just this key; settings.json is backed up first)' });
     }
   } catch { /* unreadable — do not claim it */ }
   try {
@@ -1471,6 +1493,14 @@ export function machineFootprint() {
       items.push({ label: 'The search_ruvnet MCP server registration', path: claudeJson, undo: 'claude mcp remove ruvnet-brain --scope user' });
     }
   } catch { /* unreadable — do not claim it */ }
+  // GAP FIX: recordNotified() (scripts/upgrade-notice.mjs, invoked from main() and runDemo() below)
+  // writes this file the first time a "what's new" notice is shown — a real disk artifact this
+  // installer's own code path creates, that was never listed here and never removed on --uninstall.
+  // Path duplicated rather than imported (see the cmpTag() comment above: this file must not import
+  // from scripts/ at module scope, since scripts/upgrade-notice.mjs isn't in the npm `files` list —
+  // it only reaches a user via a repo clone or `npx github:...`, never a plain npm publish; harmless
+  // no-op existence check either way). Env override name matches STATE_PATH there exactly.
+  add('Upgrade-notice state (release-notice tracking)', upgradeNoticeStatePath(), 'delete this file');
 
   return items;
 }
@@ -1551,7 +1581,10 @@ function uninstallAll() {
   // ours to delete, so they are handed over as commands.
   const AUTO = new Set(['Brain bundle (knowledge base)', 'Nightly updater (LaunchAgent)',
     'Spend watchdog (LaunchAgent)', 'Spend watchdog script', 'CLAUDE.md block (6 lines, between markers)',
-    'Model-router files', 'Status-bar version script', 'Status-bar preference', 'Usage-counts preference']);
+    'Model-router files', 'Status-bar version script', 'Status-bar preference', 'Usage-counts preference',
+    // Two gaps closed here: the statusLine KEY is now removable in place (we know exactly what we
+    // wrote — see removeSettingsStatusLine()), and the upgrade-notice tracker is a file we fully own.
+    'The statusLine entry in settings.json', 'Upgrade-notice state (release-notice tracking)']);
   const willRemove = before.filter((it) => AUTO.has(it.label));
   const manual = before.filter((it) => !AUTO.has(it.label));
 
@@ -1570,6 +1603,14 @@ function uninstallAll() {
   const claudeMd = removeClaudeMdBlock();
   if (claudeMd === 'removed') ok('removed our block from ~/.claude/CLAUDE.md (your content untouched, backup saved)');
 
+  // GAP FIX: this used to be permanently "manual" — machineFootprint() treated ANY settings.json edit
+  // as something only the user could safely touch. That blanket rule was right for edits we cannot
+  // attribute with confidence, but wrong for this one specific key: we wrote it ourselves and know
+  // the exact string we wrote, so we can reverse exactly that (never a status line the user has since
+  // customized — removeSettingsStatusLine() checks the live command before touching anything).
+  const statusLine = removeSettingsStatusLine();
+  if (statusLine === 'removed') ok('removed the statusLine entry from ~/.claude/settings.json (your other settings untouched, backup saved)');
+
   // NEVER rm -rf A PATH WE HAVE NOT PROVEN IS OURS. resolvedKbDir() honours $RUVNET_BRAIN_KB, which
   // the docs encourage for custom install locations — so `RUVNET_BRAIN_KB=$HOME npx ruvnet-brain
   // --uninstall` would have recursively deleted the user's home directory. Found by adversarial
@@ -1600,6 +1641,11 @@ function uninstallAll() {
     ['status-bar script', path.join(os.homedir(), '.cache', 'ruvnet-brain', 'ruvnet-brain-statusline.cjs')],
     ['status-bar preference', path.join(telemetryStateDir(), '.statusline-pref')],
     ['usage-counts preference', telemetryConsentPath()],
+    // GAP FIX: written by recordNotified() (scripts/upgrade-notice.mjs) whenever the "what's new"
+    // notice fires from main()/runDemo() below — a single-purpose file under a directory this
+    // installer alone writes to, safe to remove outright (not the whole ~/.config/ruvnet-brain/ dir,
+    // which can also hold lessons.json/settings.json this installer never creates and must not touch).
+    ['upgrade-notice state', upgradeNoticeStatePath()],
   ]) {
     if (!fs.existsSync(target)) continue;
     try { fs.rmSync(target, { recursive: true, force: true }); ok(`removed the ${label}`); }
@@ -1932,6 +1978,91 @@ export async function offerTelemetry(cacheDir) {
  * So: persistent background jobs and global-config edits require their OWN explicit flag. There is
  * no combination of `-y` alone that installs a daemon.
  */
+/**
+ * THE PLAN — everything this run may do, stated BEFORE the first thing is done.
+ *
+ * WHY THIS EXISTS (real user feedback, 2026-07-24, relayed by the owner): people were not running
+ * `npx ruvnet-brain` *because they could not tell what it would do.* One of them, a sophisticated
+ * user, put the general objection precisely: he dislikes "the virus/plugin approach… it all works in
+ * memory, with invisible hooks and all."
+ *
+ * The installer already asked consent for every high-impact step — watchdog, nightly updates,
+ * telemetry, stack tools, statusline. That was necessary and NOT sufficient: consent granted one
+ * question at a time, after the run has already started, never tells you the SHAPE of what you
+ * agreed to. You cannot decline a thing you have not yet been told is coming, and a person deciding
+ * whether to paste a command into their terminal is deciding about the whole run, not about step 4.
+ *
+ * So: the whole list, up front, with what each one costs you and how to undo it. Steps marked [?] are
+ * asked individually as before — this screen does not replace those prompts, it makes them
+ * predictable. Nothing here mutates anything; it prints and waits.
+ *
+ * TRUTHFULNESS RULE: every line below names a real step this file performs and a real reversal
+ * command. If a step is added to the installer and not to this list, the list becomes a lie about
+ * the installer — which is worse than having no list. Keep them together.
+ */
+async function printPlanAndConfirm() {
+  const H = os.homedir();
+  const short = (p) => p.replace(H, '~');
+
+  const steps = [
+    { auto: true,  name: 'Download the knowledge base',
+      // short() already renders $HOME as "~"; prefixing another one produced "~~/.cache/…".
+      cost: short(resolveCacheDir().cacheDir),
+      what: 'Real rUv source, on your disk, so answers cite files instead of guessing.',
+      undo: 'npx ruvnet-brain --uninstall' },
+    { auto: true,  name: 'Register the Claude Code plugin + MCP server',
+      cost: `an entry in ${short(path.join(H, '.claude'))}`,
+      what: 'Gives Claude a search_ruvnet tool. Adds no hooks you have not agreed to.',
+      undo: 'npx ruvnet-brain --uninstall' },
+    { ask: true,   name: 'Add rUv tools you are missing',
+      cost: 'npm installs, only the ones you pick',
+      what: 'So the brain can build with them, not just answer questions about them.',
+      undo: 'npm uninstall -g <tool>' },
+    { ask: true,   name: 'Nightly auto-updates',
+      cost: 'one LaunchAgent',
+      what: 'Keeps the KB and plugin current. Recommended — rUv ships fast, and a stale brain is the main way this stops being useful.',
+      undo: 'npx ruvnet-brain --disable-nightly' },
+    { ask: true,   name: 'Spend watchdog',
+      cost: 'one LaunchAgent',
+      what: 'Warns you if an agent fleet starts burning API credit unexpectedly.',
+      undo: 'npx ruvnet-brain --disable-spend-guard' },
+    { ask: true,   name: 'Status-bar version segment',
+      cost: 'one line in settings.json',
+      what: 'Shows which brain version is live while you work.',
+      undo: 'npx ruvnet-brain --no-statusline, or delete the statusLine entry' },
+    { ask: true,   name: 'Anonymous usage counts',
+      cost: 'a counter ping',
+      what: 'Installs and searches only — never your queries, your code, or your paths.',
+      undo: 'npx ruvnet-brain --no-telemetry' },
+  ];
+
+  console.log(`  ${c.bold('Here is everything this will do.')} Nothing has happened yet.\n`);
+  for (const s of steps) {
+    const mark = s.auto ? c.green('✓') : c.cyan('?');
+    console.log(`  ${mark} ${c.bold(s.name)}  ${c.dim('· ' + s.cost)}`);
+    console.log(`      ${s.what}`);
+    console.log(`      ${c.dim('undo: ' + s.undo)}\n`);
+  }
+  console.log(`  ${c.green('✓')} happens automatically.  ${c.cyan('?')} is asked first — and "no" is a complete answer.`);
+  console.log(`  ${c.dim('Every step is reversible, and `npx ruvnet-brain --what-changed` lists everything it touched.')}\n`);
+
+  // FLAG_YES means the caller already decided; a plan screen that blocks automation would break
+  // agentic-kit and every scripted install. Print it, then proceed — the information is the point,
+  // the pause is a courtesy to humans.
+  if (FLAG_YES || FLAG_AUTO || !process.stdin.isTTY) {
+    console.log(c.dim('  (non-interactive — continuing)\n'));
+    return;
+  }
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const a = await new Promise((r) => rl.question(`  ${c.cyan('?')} Continue? ${c.dim('[Y/n]')} `, r));
+  rl.close();
+  if (/^n/i.test(String(a).trim())) {
+    console.log(`\n  Stopped. Nothing was changed.\n`);
+    process.exit(0);
+  }
+  console.log('');
+}
+
 function ask(question, def = false, { blanketYes = true } = {}) {
   if (FLAG_YES && blanketYes) return Promise.resolve(true);
   if (!process.stdin.isTTY) return Promise.resolve(def);
@@ -2224,6 +2355,33 @@ function writeSettingsStatusLine(detected, command) {
   return backup;
 }
 
+// The uninstall-side mirror of writeSettingsStatusLine() above — this installer is the ONLY writer
+// that can safely reverse this specific edit, because it is the only one that knows the EXACT string
+// it wrote. Match on that exact command (never a loose "mentions ruvnet-brain" guess — see the
+// machineFootprint() comment this replaces) so a status line the user has since folded their own
+// script into, or edited by hand, is left completely alone. Same "refuse rather than guess"
+// discipline removeClaudeMdBlock() already applies to CLAUDE.md, and the same backup-first courtesy.
+function removeSettingsStatusLine() {
+  const settingsPath = settingsJsonPath();
+  const detected = detectStatusLine(settingsPath);
+  if (!detected.exists || detected.parseError || !detected.hasStatusLine) return 'absent';
+  const ours = `node "${statuslineHelperPath()}"`;
+  if (detected.command !== ours) return 'not-ours'; // never touch a status line we didn't write
+  try {
+    const backup = backupSettingsJson(settingsPath);
+    const next = { ...(detected.json || {}) };
+    delete next.statusLine;
+    const tmp = `${settingsPath}.ruvnet-tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(next, null, 2) + '\n');
+    fs.renameSync(tmp, settingsPath);
+    info(c.dim(`  your original is saved at ${backup}`));
+    return 'removed';
+  } catch (e) {
+    warn(`couldn't remove the statusLine entry (${e.message}) — remove it yourself from ${settingsPath}`);
+    return 'error';
+  }
+}
+
 // Only called after explicit consent. NEVER overwrites an existing statusLine — detectStatusLine()
 // is the single source of truth for "is one already there", checked fresh right before any write.
 function applyStatusline() {
@@ -2491,6 +2649,8 @@ It is safe to re-run at any time. After installing, restart Claude Code so the g
     }
   }
 
+  await printPlanAndConfirm();
+
   const { cacheDir, isCustom } = resolveCacheDir();
 
   // ── "ALREADY PRESENT" IS THE WRONG QUESTION — ask "already CURRENT" ──────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "3.9.18-dev",
+  "version": "3.9.51-dev",
   "description": "One-command installer for RuvNet Brain \u2014 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": {
@@ -31,7 +31,8 @@
     "falsify": "node scripts/falsify.mjs",
     "sbom": "npx --yes @cyclonedx/cyclonedx-npm --omit dev --output-file sbom/ruvnet-brain.cdx.json --mc-type application --validate",
     "wired:check": "node scripts/wired-check.mjs --check",
-    "doc:currency": "node scripts/doc-currency.mjs --check"
+    "doc:currency": "node scripts/doc-currency.mjs --check",
+    "status:check": "node scripts/status-honesty.mjs"
   },
   "files": [
     "bin/install.mjs",