ruvnet-brain 3.4.22-dev → 3.6.1-dev

package/README.md

@@ -4,10 +4,26 @@
 
 # 🧠 RuvNet Brain
 
-### 🧠 RuvNet Brain — [![RuvNet Brain version 3.4.22-dev — updated 2026-07-21 06:00 EDT](https://img.shields.io/badge/version_3.4.22--dev-updated_2026--07--21_06:00_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.6.1-dev — updated 2026-07-21 06:00 EDT](https://img.shields.io/badge/version_3.6.1--dev-updated_2026--07--21_06:00_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.**
 
+</div>
+
+> ## 🧭 North Star
+>
+> **rUv has built dozens of genuinely powerful capabilities that are effectively invisible — not undocumented, but _undiscovered_.** Ruflo's own docs call cross-project IPFS pattern transfer *"the substrate plugin's most underused capability."* The author knows people can't find his own work.
+>
+> **This project exists to close that gap** — a CTO on your shoulder that says *"you have this, it's off, here's what turning it on buys you."*
+>
+> **Retrieval was never the product. Proactive capability advocacy is the product.**
+>
+> The test we hold ourselves to: a developer who solves a hard problem with this tool and later learns they'd been sitting on a capability that would have made it trivial — that is a **failure of this project**, not of the user. Knowing which question to ask is the scarce thing; supplying that question is the job.
+>
+> Every feature is judged against this. If a surface can detect something useful and doesn't volunteer it, it is broken — see [ADR-027](docs/adr/0027-capability-advocacy-and-active-signals.md) and [DDD-0004](docs/ddd/0004-advocacy-context.md).
+
+<div align="center">
+
 [![plugin version](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fstuinfla%2Fruvnet-brain%2Fmain%2Fplugin%2F.claude-plugin%2Fplugin.json&query=%24.version&label=plugin&color=e8a13a&style=flat-square)](plugin/.claude-plugin/plugin.json)
 [![installer version](https://img.shields.io/npm/v/ruvnet-brain?label=installer%20%28npm%29&color=2e7d32&style=flat-square)](https://www.npmjs.com/package/ruvnet-brain)
 [![download](https://img.shields.io/badge/download-latest%20brain-2e7d32?style=flat-square)](https://github.com/stuinfla/ruvnet-brain/releases/latest)
@@ -40,7 +56,58 @@
 
 ---
 
-## What's new in 3.4 — the invisible work, made visible (and readable)
+## What's new in 3.6 — it can finally show you what you own
+
+**Shipped 2026-07-22.** 3.5 made the brain speak. 3.6 makes it *legible*: a console panel that
+answers the question the owner has been asking for weeks — **"what is actually turned on?"**
+
+- **Eleven capabilities, each ON / OFF / UNKNOWN**, every state *derived* from a real check on your
+  machine at render time. `UNKNOWN` is a first-class state and is visually separated from `OFF` in a
+  non-colour channel, because collapsing the two is precisely the lie this release exists to kill.
+- **A one-line plain-English "what it buys you"** on every row, and the evidence we observed.
+- **Settings that are conservative by construction.** Each setting declares which of its *values*
+  escalate beyond the current project, and `default ∉ escalates` is asserted as a test — so the rule
+  holds for settings added later instead of relying on a comment nobody re-reads.
+- **A false alarm found and killed.** 3.5's audit reported *"26 learning hooks installed and every
+  one is switched off."* That was wrong: `ruflo hooks list` renders a table column keyed `enabled`
+  against a payload that has no such key, so it prints "No" 26 times. The learner had 457
+  trajectories and had adapted 106 minutes earlier. We scraped a human-readable table instead of
+  reading state, which is the exact mistake this project keeps writing rules about. The detector now
+  reads the learner's own state file and **stays silent when it cannot tell** — ADR-028 fixes the
+  false-alarm rate at zero and calls it non-negotiable.
+- **Three surfaces that were built and never wired** are now connected. `capability-registry.mjs`
+  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.
+
+<details>
+<summary><b>Earlier &#8212; what 3.5 shipped</b> &#183; it stopped waiting to be asked. <i>Expand for the receipts.</i></summary>
+
+## 3.5 — it stopped waiting to be asked
+
+**Shipped 2026-07-22.** For three weeks this thing had indexed rUv's entire learning stack — ReasoningBank, SONA, MoE, the ADR-174 distillation pipeline — and could have answered any question about any of it. It never once said the only sentence that mattered:
+
+> *"Your learning system is installed, and it is switched off."*
+
+Stuart found it himself. The measurement: **1,884 captured events sat undelivered** while the learner held 5 trajectories and hadn't trained in six days. Draining the queue took it to 412 in one command. Three weeks of learning had been sitting there, available for the asking, and nobody knew to ask.
+
+**That gap is the product.** A brain that waits to be asked is a search box with good manners. 3.5 is the version where it speaks first.
+
+- **It now tells you what you own and aren't using.** On the author's machine, unprompted, from a real scan: *"36 project stores are embedded but have never been distilled — 6,858 memories sitting in those stores, teaching nothing."* Every recommendation is built from what was actually **observed on your machine** — never a hardcoded list of cool features, which would rot the week rUv ships again.
+- **Detection without a remedy is now structurally impossible.** The console used to detect a corrupt memory store, score it 49/100, render it into a card, and offer nothing. Stuart's verdict: *"the fact that it didn't recommend a fix is unconscionable."* Every recommendation now carries evidence, a cost, a plain-English impact, and a **real, tested undo** — enforced by a factory that throws, not by a code review that can be skipped.
+- **It stopped lying in four specific ways.** It claimed `ruflo` wasn't installed to anyone whose npm prefix wasn't the author's. It answered *"nothing to undo"* about a database repair for which it held a backup. It reported a distillation that wrote 684 patterns as having done nothing (the check used a read-only connection that can't see another process's WAL). And its installer threw away the stderr that explained every crash — so a missing module and a slow download looked identical. All four found by running the thing rather than trusting it.
+- **Every offered fix is provably runnable and reversible.** The remedy registry makes the id→executor→inverse binding a single value, and a closure test drives the real builders to prove nothing can be *offered* that cannot be *run* and *undone*. It found that this ADR's own headline recommendation had **no executor at all** — it rendered as a button that answered "Unknown recommendation id." Proven to fail on both known-bad cases before being trusted.
+- **It stopped writing into your repos** ([#36](https://github.com/stuinfla/ruvnet-brain/issues/36)) and **stopped hiding the error that explains a failure** ([#37](https://github.com/stuinfla/ruvnet-brain/issues/37)) — both reported by users, both fixed at root cause, with an upstream report filed to rUv for the two bugs that turned out to be his.
+
+The honest limit: this is **3.5, not 4.0**. The advocacy surface is live and the engine behind it is proven, but score-delta alarms aren't built and ADR-027 has not yet survived its own required adversarial review. A major version marks the release where the product becomes a different thing to the person using it. This is the release where it starts talking.
+
+<details>
+<summary><b>Earlier &#8212; what 3.4 shipped</b> &#183; the invisible work, made visible and readable. <i>Expand for the receipts.</i></summary>
+
+## 3.4 — the invisible work, made visible (and readable)
 
 **Shipped 2026-07-17.** 3.3 made every card lead with a point. Then Stuart looked at the two pages meant to *teach* the stack and scored them 55/100: the graphics were mediocre, the one page that should show how the pieces fit was a wall of text, and two diagrams were literally unreadable. 3.4 is the fix — the harness's invisible work, finally drawn, and drawn so you can actually read it.
 
@@ -230,6 +297,8 @@ claude plugin install ruvnet-brain@ruvnet-brain --scope user
 
 Registers the `search_ruvnet` MCP tool, the grounding skill, and the `UserPromptSubmit` enforcement hook — globally, at user scope. The plugin expects the brain at `~/.cache/ruvnet-brain/kb` (or point `RUVNET_BRAIN_KB` at your own copy). The first install may show a one-time trust prompt for the hook.
 
+</details>
+</details>
 </details>
 
 **Then just ask.** _“How does Ruflo orchestrate agent swarms, and what implements it?”_ The hook grounds the turn, Claude calls `search_ruvnet`, and it answers from cited source — down to the function body.
@@ -271,7 +340,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,691 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,720 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)
 
@@ -381,7 +450,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,691 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,720 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

@@ -643,7 +643,26 @@ async function smokeQuery(cacheDir) {
   const out = `${r.stdout || ''}`;
   if (r.status !== 0 || !out.trim()) {
     warn('no answer came back (first-run model download or offline) — the brain is installed; it\'ll warm on your first real question');
-    return { ran: true, grounded: false, reason: 'no-answer' };
+    // SHOW THE ACTUAL ERROR (issue #37 bug 2, Agentist-Elder, 2026-07-21).
+    //
+    // This captured stderr and then threw it away, so every hard failure — a crash, a missing
+    // module, a bad model path — arrived looking identical to a slow first-run download. That is
+    // exactly how a total grounding outage (a static import of a module missing from the bundle,
+    // crashing before any model code ran) presented as the reassuring line above and cost the
+    // reporter a full debugging session to attribute. Their words, and they are right: this
+    // wrapper "will hide the *next* breakage too, whatever it is."
+    //
+    // A diagnostic that discards the diagnosis is worse than no diagnostic, because it reads as
+    // information. Print it. Truncated, because a stack trace is not a friendly install screen —
+    // but never hidden.
+    const err = `${r.stderr || ''}`.trim();
+    if (err) {
+      const lines = err.split('\n');
+      info(c.dim('  the reader reported:'));
+      for (const line of lines.slice(0, 12)) info(c.dim(`    ${line.slice(0, 200)}`));
+      if (lines.length > 12) info(c.dim(`    … ${lines.length - 12} more line(s)`));
+    }
+    return { ran: true, grounded: false, reason: 'no-answer', stderr: err.slice(0, 4000) };
   }
 
   const verifier = await loadCitationVerifier(cacheDir);
@@ -709,6 +728,12 @@ function runDemo() {
     const out = `${r.stdout || ''}`.trim();
     if (r.status !== 0 || !out) {
       warn(`no answer came back — the local model may still be warming up (run this again in a moment)`);
+      // Same discarded-diagnosis bug as smokeQuery() — see the note there (issue #37 bug 2).
+      const err = `${r.stderr || ''}`.trim();
+      if (err) {
+        info(c.dim('  the reader reported:'));
+        for (const line of err.split('\n').slice(0, 8)) info(c.dim(`    ${line.slice(0, 200)}`));
+      }
       continue;
     }
     // Show the top hit's actual citation (repo/path/title + the start of its real cited text) —
@@ -732,14 +757,20 @@ function runDemo() {
 }
 
 // ── token meter one-liner for --doctor (ADR-0011 token_cost_efficiency) ──────────────────────────
-// The hooks + MCP server append one JSON line per fire to .ruvnet-brain/token-ledger.jsonl in the
-// project they run in (see scripts/token-report.mjs for the full breakdown). This summarizes what
-// was MEASURED yesterday+today in the cwd --doctor is run from — measured bytes, estimated tokens
-// (bytes/4, stated as an estimate). Fail-silent by design: a meter problem never reddens a checkup.
+// The hooks + MCP server append one JSON line per fire to a SINGLE user-level ledger at
+// ~/.cache/ruvnet-brain/token-ledger.jsonl (see scripts/token-report.mjs for the full breakdown).
+// It used to be written per-CWD, which scattered hidden .ruvnet-brain/ directories through users'
+// project trees and dirtied their git status — issue #36. Each line now carries a `cwd` field, so
+// the per-project view survives without writing anything into a project.
+// Fail-silent by design: a meter problem never reddens a checkup.
 function meterSummaryLine() {
   try {
-    const ledger = path.join(process.cwd(), '.ruvnet-brain', 'token-ledger.jsonl');
-    if (!fs.existsSync(ledger)) return 'meter: no data yet (this project has no .ruvnet-brain/token-ledger.jsonl — it appears after the first hook/MCP fire)';
+    const canonical = path.join(process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache'), 'ruvnet-brain', 'token-ledger.jsonl');
+    const legacy = path.join(process.cwd(), '.ruvnet-brain', 'token-ledger.jsonl');
+    // Read the legacy per-project ledger only if it exists and the canonical one does not — an
+    // existing user's measurements should not disappear the day the location changes.
+    const ledger = fs.existsSync(canonical) || !fs.existsSync(legacy) ? canonical : legacy;
+    if (!fs.existsSync(ledger)) return 'meter: no data yet (appears after the first hook/MCP fire)';
     const since = new Date();
     since.setHours(0, 0, 0, 0);
     since.setDate(since.getDate() - 1); // start of yesterday, local time
@@ -850,6 +881,33 @@ async function doctor() {
 // no env — every field is generic. The user still writes and posts the actual feedback themselves.
 const DISCUSSIONS_URL = `https://github.com/${REPO}/discussions`;
 
+/**
+ * Compare two release tags. Returns >0 if a is newer, <0 if older, 0 if equal.
+ *
+ * Local to this file on purpose: bin/install.mjs is the ONLY file that runs before anything is
+ * installed, so it may not import from scripts/ (which isn't in the npm `files` list). Duplicating
+ * ~10 lines is the correct trade against an installer that cannot run.
+ *
+ * Prerelease handling matters here because every tag this project ships is `X.Y.Z-dev`. Numeric
+ * parts compare numerically (so 3.10.0 > 3.9.0, which a string compare gets backwards), and a
+ * release WITHOUT a prerelease suffix outranks the same numbers WITH one, per semver.
+ */
+function cmpTag(a, b) {
+  const parse = (v) => {
+    const [core, pre = ''] = String(v).replace(/^v/, '').split('-');
+    return { nums: core.split('.').map((n) => parseInt(n, 10) || 0), pre };
+  };
+  const A = parse(a), B = parse(b);
+  for (let i = 0; i < Math.max(A.nums.length, B.nums.length); i++) {
+    const d = (A.nums[i] || 0) - (B.nums[i] || 0);
+    if (d !== 0) return d > 0 ? 1 : -1;
+  }
+  if (A.pre === B.pre) return 0;
+  if (!A.pre) return 1;   // 3.5.0 is newer than 3.5.0-dev
+  if (!B.pre) return -1;
+  return A.pre > B.pre ? 1 : -1;
+}
+
 function installedBrainVersion(cacheDir) {
   // Same read the telemetry ping uses: the bundle stamps its Release tag into SOURCE.json.
   // "unknown" is honest for a locally-built or pre-stamping bundle — never guess a tag.
@@ -2386,6 +2444,7 @@ It is safe to re-run at any time. After installing, restart Claude Code so the g
   // that is what happened, instead of implying everything is up to date.
   const alreadyInstalled = fs.existsSync(path.join(cacheDir, 'forge-mcp-all.mjs'));
   let staleSkip = false;
+  let ahead = false;
   let installedTag = null;
   let latestTag = null;
   let resolvedRelease = null;   // reused below so the release is resolved at most once
@@ -2406,12 +2465,28 @@ It is safe to re-run at any time. After installing, restart Claude Code so the g
     } catch { latestTag = null; }
     const norm = (v) => (v == null || v === 'unknown' ? null : String(v).replace(/^v/, ''));
     const a = norm(installedTag), b = norm(latestTag);
-    // Different (or unknowable-installed) => it is NOT current => download. Same => genuinely skip.
-    staleSkip = Boolean(b && (a === null || a !== b));
+    // BEHIND => download. SAME => skip. AHEAD => skip, and say so honestly.
+    //
+    // This was a bare `a !== b`, which treats "newer than the latest release" as staleness. Anyone
+    // running a pre-release or dev build — or who simply updated in the window before a release was
+    // cut — was told "Brain is out of date" and pushed through a 2 GB download that would DOWNGRADE
+    // them. Found 2026-07-22 the moment this repo's own version moved to 3.5.0-dev ahead of the
+    // 3.4.22-dev release: the installer immediately declared its own newest brain stale.
+    //
+    // stack-sync.mjs has modelled AHEAD as legal from the start ("AHEAD is legal and produces NO
+    // recommendation — that modelling choice is what makes the alpha-vs-latest downgrade war
+    // structurally impossible"). The installer never learned the same lesson. It has now.
+    ahead = Boolean(a && b && cmpTag(a, b) > 0);
+    staleSkip = Boolean(b && (a === null || (a !== b && !ahead)));
   }
 
   if (alreadyInstalled && !FLAG_FORCE && !staleSkip) {
-    if (latestTag) {
+    if (latestTag && ahead) {
+      // Never silently imply equality when the user is AHEAD — that would be a small lie, and it is
+      // the one that hides a downgrade. Skipping is right; misdescribing why is not.
+      step('Brain already current — skipping the download', `installed ${installedTag} is NEWER than the latest release (${latestTag})`);
+      ok(`found an up-to-date brain at ${cacheDir} — nothing to download, and we will never downgrade you`);
+    } else if (latestTag) {
       step('Brain already current — skipping the download', `installed ${installedTag} matches the latest release`);
       ok(`found an up-to-date brain at ${cacheDir}`);
     } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "3.4.22-dev",
+  "version": "3.6.1-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": {