ruvnet-brain 3.6.1-dev → 3.9.50-dev

package/README.md

@@ -4,7 +4,7 @@
 
 # 🧠 RuvNet Brain
 
-### 🧠 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)
+### 🧠 RuvNet Brain — [![RuvNet Brain version 3.9.50-dev — updated 2026-07-23 04:06 EDT](https://img.shields.io/badge/version_3.9.50--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.**
 
@@ -56,7 +56,70 @@
 
 ---
 
-## What's new in 3.6 — it can finally show you what you own
+## What's new in 3.9 — it anticipates, and it learns whether it was right
+
+**Building toward L4/L5 (3.9.x, dev).** The mechanisms for the top two rungs of the proactivity
+ladder are built and wired — but they are **not yet verified to 4.0's bar**, which requires all five
+of ADR-028's test classes green under independent grading. Until then, [ADR-028](docs/adr/0028-what-proactive-means.md)
+grades the shipped, *verified* state at **L2–L3**, and `-dev` is the honest version. 4.0 is claimed
+only when L3+L4+L5 are each measured, not when the code merely exists.
+
+- **L4 Anticipatory (mechanism built).** It infers what you're *trying to do* and names the capability
+  that serves that goal — before you hit the wall. Built to stay quiet: a match needs **two
+  independent cues** (the problem AND that the topic is your AI workflow), so near-misses get
+  silence. Measured on the negative table: **0 false positives**; fires on a genuine match. What's
+  still owed for L4: the full five-class verification, independently graded.
+- **L5 Compounding (mechanism built, metric now live).** Advocacy records whether it was right —
+  precision = acted-on ÷ offered, ADR-028's line between advocating and nagging. The numerator is
+  now **derived from an observed state transition** (offered → later switched on = applied) and
+  surfaced in the console; it reads an honest `null` until enough offers resolve, never a fabricated
+  score. A dismissal is evidence about **fit, not importance** — asymmetric budget: a suggestion dies
+  on one dismissal, an important finding needs three. What's still owed for L5: real precision data
+  from use, and the cross-project promotion test.
+- **The admin page is rebuilt around deltas**, not lifetime totals — and the humans who wrote in
+  are promoted to the top, ranked by recency rather than lifetime count.
+
+<details>
+<summary><b>Earlier &#8212; what 3.8 shipped</b> &#183; the gate that fires when you stop. <i>Expand.</i></summary>
+
+## 3.8 — the gate that fires when you stop
+
+**Shipped 2026-07-22.** Every gate in this project fires on an **action** — a write, a push, a
+claim. That is what makes it enforceable. But **stopping is the absence of an action**, so the most
+expensive failure of the night had no trigger at all, and a system built to prevent it did not.
+
+- **`continuation-gate.mjs`** runs when a turn ends. If work you committed to is unfinished, it
+  makes that the last thing in context. It cannot force another turn — claiming otherwise would be
+  the fabrication this project exists to kill — but it removes the silence that let a stop pass
+  unnoticed.
+- **Project-scoped ledgers.** Three simultaneous projects never see each other's commitments; a
+  "you didn't finish X" fired in a repo that never heard of X is a false alarm, and ADR-028 fixes
+  the false-alarm rate at zero.
+- **Installed machine-wide**, merged into existing hooks rather than replacing them, with a backup
+  taken first — that file governs every project on the machine.
+
+<details>
+<summary><b>Earlier &#8212; what 3.7 shipped</b> &#183; your lessons can now refuse your work. <i>Expand.</i></summary>
+
+## 3.7 — your lessons can now refuse your work
+
+**Shipped 2026-07-22.** 3.6 made the machine legible. 3.7 closes the loop: a lesson you taught is
+read by a gate at the moment it applies, and — once you ratify it — **refuses the action**.
+
+- **`lesson-gate.mjs`** — a gate asks the store "what applies right now?" and gets your own words
+  back, with the evidence and how many times you had to say it. Wired into the real pre-push gate.
+- **`lesson-ratify.mjs`** — see every lesson, ratify it, or delete it. **Demotion is sticky**: it
+  survives every future mining run, because a reject the nightly quietly undoes is worse than none.
+- **The model cannot ratify its own rules.** Lessons it inferred about itself are quarantined and
+  can never block, no matter what is asked of them — closing an injection path an adversarial
+  review found, where a hallucinated session summary could have become a blocking gate.
+- Proven end to end: before ratification the ship gate informs (exit 0); after ratifying the
+  version-discipline lesson it **refuses** (exit 1). Same wire, no code change — enforcement is data.
+
+<details>
+<summary><b>Earlier &#8212; what 3.6 shipped</b> &#183; it could finally show you what you own. <i>Expand.</i></summary>
+
+## 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?"**
@@ -79,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>
@@ -297,6 +363,9 @@ 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>
 </details>
 </details>
 </details>
@@ -340,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,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.
+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)
 
@@ -450,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,720 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

@@ -349,11 +349,18 @@ async function obtainBundle(release) {
     );
   }
   ok(`downloaded to ${tmp}`);
-  // Best-effort fetch of the detached Ed25519 signature published alongside the asset (SEC-0010 #6).
-  // If present we verify it before extracting; if absent (a pre-signing release) we warn but proceed
-  // (transitional — see SIGNING_REQUIRED at the verify gate).
-  try { await download(`${downloadUrl}.sig`, `${tmp}.sig`); } catch { /* no published sig yet */ }
-  return { zipPath: tmp, tmpDir, downloaded: true };
+  // Fetch the detached Ed25519 signature published alongside the asset (SEC-0010 #6).
+  // We record WHY a fetch failed rather than discarding it. Swallowing the error made two very
+  // different worlds look identical: "this release genuinely has no signature" and "someone
+  // 404'd/reset/stripped the .sig so verification would be skipped." The second is the whole
+  // downgrade attack — strip one small file and 800MB+ of executable .mjs extracts unverified.
+  let sigError = null;
+  try {
+    await download(`${downloadUrl}.sig`, `${tmp}.sig`);
+  } catch (e) {
+    sigError = e && e.message ? e.message : String(e);
+  }
+  return { zipPath: tmp, tmpDir, downloaded: true, sigError };
 }
 
 // ── step: unzip into the cache dir (flattening the top-level ruvnet-brain/ folder) ───────────────
@@ -581,9 +588,13 @@ function verifyInstall(cacheDir) {
 }
 
 // ── step: warm the model + prove grounding with one real question (best-effort, never fatal) ──────
-// ── BEGIN GENERATED: verify-citation.mjs (node scripts/embed-verifier.mjs) ──
-const VERIFY_CITATION_B64 = 'IyEvdXNyL2Jpbi9lbnYgbm9kZQovLyB2ZXJpZnktY2l0YXRpb24ubWpzIOKAlCBkZWNpZGUgd2hldGhlciBhbiBhbnN3ZXIgaXMgR1JPVU5ERUQsIGJ5IGdyb3VuZCB0cnV0aCByYXRoZXIgdGhhbiBieSB2aWJlcy4KLy8KLy8gV0hZIFRISVMgRVhJU1RTCi8vIC0tLS0tLS0tLS0tLS0tLQovLyBUaGUgb2xkIGdyb3VuZGluZyBjaGVjayBhc2tlZDogZG9lcyB0aGUgYW5zd2VyIGNvbnRhaW4gdGhlIHN0cmluZyAicnZmIiBvciAicnV2ZWN0b3IiPyBBIG1vZGVsCi8vIHRoYXQgaGFsbHVjaW5hdGVkICJqdXN0IHVzZSBSVkYhIiB3aXRoIHplcm8gc291cmNlcyBwYXNzZWQuIFNvIGRpZCBhbiBhbnN3ZXIgY2l0aW5nIGEgZmlsZSB0aGF0Ci8vIGRvZXMgbm90IGV4aXN0LiBLZXl3b3JkIHByZXNlbmNlIGlzIG5vdCBldmlkZW5jZSDigJQgYW4gTExNIHBhbmVsIG9uY2Ugc2NvcmVkIGEgemVyby1jaXRhdGlvbgovLyBhbnN3ZXIgOTgvMTAwIG9uIHRoaXMgcmVwby4KLy8KLy8gQSBjaXRhdGlvbiBpcyBvbmx5IHJlYWwgaWYgaXQgUkVTT0xWRVM6IHRoZSByZXBvIG11c3QgYmUgYW4gaW5kZXhlZCBzdG9yZSBvbiBkaXNrLCBhbmQgdGhlIGNpdGVkCi8vIGRvY3VtZW50IHBhdGggbXVzdCBhcHBlYXIgYXMgdGhlIGBwYXRoYCBvZiBhbiBhY3R1YWwgcGFzc2FnZSBpbnNpZGUgdGhhdCBzdG9yZSdzIHBhc3NhZ2VzIGZpbGUuCi8vIFRoYXQgaXMgY2hlY2thYmxlIHdpdGhvdXQgYSBtb2RlbCwgd2l0aG91dCB0aGUgbmV0d29yaywgYW5kIHdpdGhvdXQgdHJ1c3RpbmcgYW55dGhpbmcgdGhlIG1vZGVsCi8vIHNhaWQuIFRoaXMgbW9kdWxlIGRvZXMgZXhhY3RseSB0aGF0IGFuZCBub3RoaW5nIGVsc2UuCi8vCi8vIFRoZSByZWFkZXIgKGBmb3JnZS1hc2stYWxsLm1qc2ApIHByaW50cyBlYWNoIGhpdCBhczoKLy8gICAgICMxICByZXBvPWNvbmNlcHRzICBjZT0wLjIwMSAgdmVjPTAuODY4NiAga2luZD1kb2MKLy8gICAgIHBhdGggOiBjb25jZXB0cy9ydXZlY3Rvci9DQVJEL3J1dmVjdG9yLWNhcmQKLy8gICAgIHRpdGxlOiBydXZlY3RvciDigJQgQ2FwYWJpbGl0eQovLyBOb3RlIHRoZSBwcmludGVkIHBhdGggaXMgYDxyZXBvPi88ZG9jUGF0aD5gOyBpbnNpZGUgYGNvbmNlcHRzLnBhc3NhZ2VzLmpzb25sYCB0aGUgc3RvcmVkIGBwYXRoYAovLyBpcyBqdXN0IGBydXZlY3Rvci9DQVJEL3J1dmVjdG9yLWNhcmRgIChvcHRpb25hbGx5IHN1ZmZpeGVkIGAjMGAsIGAjMWAsIOKApiB3aGVuIGNodW5rZWQpLgoKaW1wb3J0IGZzIGZyb20gJ25vZGU6ZnMnOwppbXBvcnQgcGF0aCBmcm9tICdub2RlOnBhdGgnOwppbXBvcnQgcmVhZGxpbmUgZnJvbSAnbm9kZTpyZWFkbGluZSc7CgovKiogUGFyc2UgdGhlIHJlYWRlcidzIHN0ZG91dCBpbnRvIHN0cnVjdHVyZWQgY2l0YXRpb25zLiBOZXZlciB0aHJvd3M7IHVucGFyc2VhYmxlIGlucHV0IOKGkiBbXS4gKi8KZXhwb3J0IGZ1bmN0aW9uIHBhcnNlQ2l0YXRpb25zKHN0ZG91dCkgewogIGNvbnN0IG91dCA9IFtdOwogIGNvbnN0IHRleHQgPSBTdHJpbmcoc3Rkb3V0ID8/ICcnKTsKICBjb25zdCBibG9ja1JlID0gL14jKFxkKylccytyZXBvPShcUyspKD86XHMrY2U9KC0/W1xkLl0rKSk/KD86XHMrdmVjPSgtP1tcZC5dKykpPyg/OlxzK2tpbmQ9KFxTKykpPy9nbTsKICBsZXQgbTsKICB3aGlsZSAoKG0gPSBibG9ja1JlLmV4ZWModGV4dCkpICE9PSBudWxsKSB7CiAgICBjb25zdCByZXN0ID0gdGV4dC5zbGljZShtLmluZGV4KTsKICAgIGNvbnN0IHBhdGhNID0gL15wYXRoXHMqOlxzKiguKykkL20uZXhlYyhyZXN0KTsKICAgIGNvbnN0IHRpdGxlTSA9IC9edGl0bGVccyo6XHMqKC4rKSQvbS5leGVjKHJlc3QpOwogICAgaWYgKCFwYXRoTSkgY29udGludWU7CiAgICBjb25zdCByZXBvID0gbVsyXTsKICAgIGNvbnN0IGZ1bGxQYXRoID0gcGF0aE1bMV0udHJpbSgpOwogICAgLy8gU3RyaXAgdGhlIHJlcG8gcHJlZml4IHRoZSByZWFkZXIgYWRkcywgc28gdGhlIHJlbWFpbmRlciBjYW4gYmUgbWF0Y2hlZCBhZ2FpbnN0IHRoZSBzdG9yZS4KICAgIGNvbnN0IGRvY1BhdGggPSBmdWxsUGF0aC5zdGFydHNXaXRoKGAke3JlcG99L2ApID8gZnVsbFBhdGguc2xpY2UocmVwby5sZW5ndGggKyAxKSA6IGZ1bGxQYXRoOwogICAgb3V0LnB1c2goewogICAgICByYW5rOiBOdW1iZXIobVsxXSksCiAgICAgIHJlcG8sCiAgICAgIGNlOiBtWzNdICE9PSB1bmRlZmluZWQgPyBOdW1iZXIobVszXSkgOiBudWxsLAogICAgICB2ZWM6IG1bNF0gIT09IHVuZGVmaW5lZCA/IE51bWJlcihtWzRdKSA6IG51bGwsCiAgICAgIGtpbmQ6IG1bNV0gPz8gbnVsbCwKICAgICAgZnVsbFBhdGgsCiAgICAgIGRvY1BhdGgsCiAgICAgIHRpdGxlOiB0aXRsZU0gPyB0aXRsZU1bMV0udHJpbSgpIDogbnVsbCwKICAgIH0pOwogIH0KICByZXR1cm4gb3V0Owp9CgovKiogVGhlIHBhc3NhZ2VzIGZpbGVzIHRoYXQgY291bGQgaG9sZCBhIHJlcG8ncyBkb2N1bWVudHMg4oCUIHRoZSBzbGltIHN0b3JlIGFuZCB0aGUgZGVlcCBgLmJpZ2Agb25lLiAqLwpleHBvcnQgZnVuY3Rpb24gcGFzc2FnZXNGaWxlc0ZvcihyZXBvLCBrYkRpcikgewogIHJldHVybiBbcGF0aC5qb2luKGtiRGlyLCBgJHtyZXBvfS5wYXNzYWdlcy5qc29ubGApLCBwYXRoLmpvaW4oa2JEaXIsIGAke3JlcG99LmJpZy5wYXNzYWdlcy5qc29ubGApXQogICAgLmZpbHRlcigocCkgPT4gZnMuZXhpc3RzU3luYyhwKSk7Cn0KCi8qKiBUcnVlIHdoZW4gYHN0b3JlZGAgaXMgdGhlIGNpdGVkIGRvYywgYWxsb3dpbmcgZm9yIHRoZSBgI05gIGNodW5rIHN1ZmZpeCB0aGUgYnVpbGRlciBhcHBlbmRzLiAqLwpmdW5jdGlvbiBzYW1lUGF0aChzdG9yZWQsIGRvY1BhdGgpIHsKICByZXR1cm4gc3RvcmVkID09PSBkb2NQYXRoIHx8IHN0b3JlZC5zdGFydHNXaXRoKGAke2RvY1BhdGh9I2ApOwp9CgovKioKICogRG9lcyB0aGlzIGNpdGF0aW9uIHBvaW50IGF0IGEgcGFzc2FnZSB0aGF0IHJlYWxseSBleGlzdHMgb24gZGlzaz8KICogU3RyZWFtcyB0aGUgZmlsZSBhbmQgc3RvcHMgYXQgdGhlIGZpcnN0IG1hdGNoLCBzbyBhIDUwME1CIGAuYmlnYCBzdG9yZSBjb3N0cyBvbmx5IGFzIG11Y2ggYXMgaXQKICogdGFrZXMgdG8gcmVhY2ggdGhlIGhpdC4gQSBtYWxmb3JtZWQgSlNPTiBsaW5lIGlzIHNraXBwZWQsIG5ldmVyIGZhdGFsLgogKi8KZXhwb3J0IGFzeW5jIGZ1bmN0aW9uIGNpdGF0aW9uUmVzb2x2ZXMoY2l0YXRpb24sIGtiRGlyKSB7CiAgY29uc3QgZmlsZXMgPSBwYXNzYWdlc0ZpbGVzRm9yKGNpdGF0aW9uLnJlcG8sIGtiRGlyKTsKICBpZiAoIWZpbGVzLmxlbmd0aCkgcmV0dXJuIHsgcmVzb2x2ZWQ6IGZhbHNlLCByZWFzb246ICduby1zdG9yZScsIGZpbGU6IG51bGwsIHN0b3JlZFBhdGg6IG51bGwgfTsKICBmb3IgKGNvbnN0IGZpbGUgb2YgZmlsZXMpIHsKICAgIGNvbnN0IHJsID0gcmVhZGxpbmUuY3JlYXRlSW50ZXJmYWNlKHsgaW5wdXQ6IGZzLmNyZWF0ZVJlYWRTdHJlYW0oZmlsZSksIGNybGZEZWxheTogSW5maW5pdHkgfSk7CiAgICB0cnkgewogICAgICBmb3IgYXdhaXQgKGNvbnN0IGxpbmUgb2YgcmwpIHsKICAgICAgICBpZiAoIWxpbmUpIGNvbnRpbnVlOwogICAgICAgIGxldCByZWM7CiAgICAgICAgdHJ5IHsgcmVjID0gSlNPTi5wYXJzZShsaW5lKTsgfSBjYXRjaCB7IGNvbnRpbnVlOyB9CiAgICAgICAgaWYgKHR5cGVvZiByZWM/LnBhdGggPT09ICdzdHJpbmcnICYmIHNhbWVQYXRoKHJlYy5wYXRoLCBjaXRhdGlvbi5kb2NQYXRoKSkgewogICAgICAgICAgcmV0dXJuIHsgcmVzb2x2ZWQ6IHRydWUsIHJlYXNvbjogJ29rJywgZmlsZTogcGF0aC5iYXNlbmFtZShmaWxlKSwgc3RvcmVkUGF0aDogcmVjLnBhdGggfTsKICAgICAgICB9CiAgICAgIH0KICAgIH0gZmluYWxseSB7CiAgICAgIHJsLmNsb3NlKCk7CiAgICB9CiAgfQogIHJldHVybiB7IHJlc29sdmVkOiBmYWxzZSwgcmVhc29uOiAncGF0aC1ub3QtaW4tc3RvcmUnLCBmaWxlOiBudWxsLCBzdG9yZWRQYXRoOiBudWxsIH07Cn0KCi8qKgogKiBUaGUgZ2F0ZS4gQW4gYW5zd2VyIGlzIGdyb3VuZGVkIG9ubHkgd2hlbiBpdCBjaXRlcyBhdCBsZWFzdCBvbmUgcGFzc2FnZSB0aGF0IHJlc29sdmVzIG9uIGRpc2suCiAqIFJldHVybnMgdGhlIHJlY2VpcHQgc28gYSBjYWxsZXIgY2FuIFBSSU5UIHRoZSBldmlkZW5jZSBpbnN0ZWFkIG9mIGFzc2VydGluZyBhIGNvbmNsdXNpb24uCiAqLwpleHBvcnQgYXN5bmMgZnVuY3Rpb24gdmVyaWZ5R3JvdW5kaW5nKHN0ZG91dCwga2JEaXIpIHsKICBjb25zdCBjaXRhdGlvbnMgPSBwYXJzZUNpdGF0aW9ucyhzdGRvdXQpOwogIGlmICghY2l0YXRpb25zLmxlbmd0aCkgewogICAgcmV0dXJuIHsgZ3JvdW5kZWQ6IGZhbHNlLCByZWFzb246ICduby1jaXRhdGlvbnMnLCBjaXRhdGlvbnM6IFtdLCByZWNlaXB0OiBudWxsIH07CiAgfQogIGZvciAoY29uc3QgY2l0YXRpb24gb2YgY2l0YXRpb25zKSB7CiAgICBjb25zdCByID0gYXdhaXQgY2l0YXRpb25SZXNvbHZlcyhjaXRhdGlvbiwga2JEaXIpOwogICAgaWYgKHIucmVzb2x2ZWQpIHsKICAgICAgcmV0dXJuIHsKICAgICAgICBncm91bmRlZDogdHJ1ZSwKICAgICAgICByZWFzb246ICdvaycsCiAgICAgICAgY2l0YXRpb25zLAogICAgICAgIHJlY2VpcHQ6IHsgcmVwbzogY2l0YXRpb24ucmVwbywgcGF0aDogY2l0YXRpb24uZnVsbFBhdGgsIHRpdGxlOiBjaXRhdGlvbi50aXRsZSwgZmlsZTogci5maWxlLCBzdG9yZWRQYXRoOiByLnN0b3JlZFBhdGggfSwKICAgICAgfTsKICAgIH0KICB9CiAgcmV0dXJuIHsgZ3JvdW5kZWQ6IGZhbHNlLCByZWFzb246ICdjaXRhdGlvbnMtZG8tbm90LXJlc29sdmUnLCBjaXRhdGlvbnMsIHJlY2VpcHQ6IG51bGwgfTsKfQo=';
-// ── END GENERATED ──
+// The verifier ships as a real file (kb/verify-citation.mjs, in package.json files[]).
+// It used to live here as a ~4KB base64 literal that was decoded at runtime, written to disk as
+// .mjs, and then dynamically imported. That is the canonical staged-payload chain, and EDR
+// behavioural engines score write-then-execute on a just-created file as high-confidence dropper
+// activity — a benign explanation that arrives only AFTER the alarm. Copying a file we shipped is
+// the same capability with none of the signature. (base64 was originally chosen to dodge escaping
+// bugs — the module contains backticks, ${...} and backslashes — which shipping a file also solves.)
 
 // The verifier belongs next to the data it verifies, so it lives in the KB. But every bundle
 // published before 2026-07-09 predates it, and telling those users "grounding not verifiable —
@@ -593,9 +604,10 @@ const VERIFY_CITATION_B64 = 'IyEvdXNyL2Jpbi9lbnYgbm9kZQovLyB2ZXJpZnktY2l0YXRpb24
 function ensureVerifier(cacheDir) {
   const p = path.join(cacheDir, 'verify-citation.mjs');
   if (fs.existsSync(p)) return 'from-bundle';
-  if (!VERIFY_CITATION_B64) return 'unavailable';
+  const shipped = path.join(REPO_ROOT, 'kb', 'verify-citation.mjs');
+  if (!fs.existsSync(shipped)) return 'unavailable';
   try {
-    fs.writeFileSync(p, Buffer.from(VERIFY_CITATION_B64, 'base64').toString('utf8'), 'utf8');
+    fs.copyFileSync(shipped, p);
     return 'installed';
   } catch { return 'unavailable'; }
 }
@@ -699,7 +711,7 @@ const DEMO_QUESTIONS = [
     why: 'shows it grounding in Ruflo (the real orchestration engine) instead of guessing at a generic pattern',
   },
 ];
-function runDemo() {
+async function runDemo() {
   printBanner('demo');
   const cacheDir = process.env.RUVNET_BRAIN_KB || path.join(os.homedir(), '.cache', 'ruvnet-brain', 'kb');
   const ask = path.join(cacheDir, 'forge-ask-all.mjs');
@@ -750,6 +762,47 @@ function runDemo() {
   console.log(`\n${c.green('─'.repeat(64))}`);
   console.log(`  ${c.bold('That\'s it — no cloud calls, no API key, just your local brain.')}`);
   console.log(`${c.green('─'.repeat(64))}`);
+  // ── SCOPE + UPGRADE CONVERSATION ────────────────────────────────────────────────────────────
+  //
+  // The owner, 2026-07-22: "Normally this happens on a per-user basis, which lets learning,
+  // intelligence, access and software versions stay updated across ALL your projects. Only choose
+  // per-project if this is something you absolutely only use in one place. Our strong
+  // recommendation is per-user — but we always want YOU to be the arbiter of how things run on
+  // your machine."
+  //
+  // And, critically, for people who already have it installed: "That's only going to help people
+  // newly installing. It needs to be smart enough when it comes up to say version 4 is here, here
+  // are your choices."
+  //
+  // Both modules were BUILT AND WIRED TO NOTHING until this was added — the seventh instance of
+  // built-tested-unwired in one session, which is why scripts/wired-check.mjs now gates the release.
+  //
+  // Read-only here by design: this INFORMS and never changes scope on its own. P3 (nudge, never
+  // force) and P4 (the user is the arbiter). Fail-silent, because an informational block must never
+  // break an install that otherwise succeeded.
+  try {
+    const { detectCurrentScope, explainChoice, RECOMMENDED } = await import(new URL('../scripts/install-scope.mjs', import.meta.url).href);
+    const current = detectCurrentScope();
+    if (current && current.scope !== RECOMMENDED) {
+      console.log(`\n${c.dim('  ── how this is set up on your machine ──')}`);
+      for (const line of String(explainChoice({ current: current.scope })).split('\n').slice(0, 12)) {
+        console.log(`  ${line}`);
+      }
+    }
+  } catch { /* informational only — never break an install */ }
+
+  try {
+    const { shouldNotify, noticeFor } = await import(new URL('../scripts/upgrade-notice.mjs', import.meta.url).href);
+    const v = wrapperVersion();
+    if (v && shouldNotify(v)) {
+      const notice = noticeFor(v);
+      if (notice) {
+        console.log('');
+        for (const line of String(notice).split('\n').slice(0, 14)) console.log(`  ${line}`);
+      }
+    }
+  } catch { /* informational only */ }
+
   console.log(`\n  Now try it for real: open Claude Code in any project and ask it something about`);
   console.log(`  RuVector, Ruflo, AgentDB, or SPARC — it'll ground the same way, automatically.`);
   console.log(`  Run this demo again any time:  ${c.bold('npx ruvnet-brain --demo')}`);
@@ -1166,10 +1219,15 @@ function enableNightly() {
     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).
+  // Template the plist to THIS user's kb dir + node binary.
+  //
+  // No `/bin/sh -c` (ADR-038): a LaunchAgent whose ProgramArguments invoke a shell is the standard
+  // macOS persistence pattern, and EDR persistence monitors score it well above a plist that execs a
+  // binary directly. launchd provides everything the shell was doing here natively —
+  // WorkingDirectory replaces `cd`, StandardOutPath/StandardErrorPath replace `>>` and `2>&1` — so
+  // dropping the shell costs nothing and removes both a shell parse of interpolated paths and the
+  // signature. Same schedule, same command, same log.
   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">
@@ -1178,10 +1236,16 @@ function enableNightly() {
   <string>${NIGHTLY_LABEL}</string>
   <key>ProgramArguments</key>
   <array>
-    <string>/bin/sh</string>
-    <string>-c</string>
-    <string>${xmlEscape(shellCmd)}</string>
+    <string>${xmlEscape(process.execPath)}</string>
+    <string>forge-update.mjs</string>
+    <string>--apply</string>
   </array>
+  <key>WorkingDirectory</key>
+  <string>${xmlEscape(kbDir)}</string>
+  <key>StandardOutPath</key>
+  <string>${xmlEscape(logPath)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xmlEscape(logPath)}</string>
   <key>StartCalendarInterval</key>
   <dict>
     <key>Hour</key>
@@ -1348,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.
  *
@@ -1371,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 {
@@ -1393,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 {
@@ -1407,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;
 }
@@ -1487,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));
 
@@ -1506,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
@@ -1536,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}`); }
@@ -1868,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);
@@ -2160,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() {
@@ -2427,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" ──────────────────────────
@@ -2506,17 +2730,25 @@ It is safe to re-run at any time. After installing, restart Claude Code so the g
       FLAG_LOCAL || fs.existsSync(path.join(REPO_ROOT, 'dist', 'ruvnet-brain.zip'));
     // Reuse the staleness check's resolution when it already ran — one network round-trip, not two.
     const release = localZipPresent ? null : (resolvedRelease || await resolveRelease());
-    const { zipPath, tmpDir, downloaded } = await obtainBundle(release);
+    const { zipPath, tmpDir, downloaded, sigError } = await obtainBundle(release);
     // Verify the Ed25519 signature BEFORE extracting a downloaded bundle into the user's config
-    // (SEC-0010 #6 — trust root = keys/ruvnet-brain-signing.pub.pem shipped inside this package).
-    // SIGNING_REQUIRED is transitional: while releases predate signing, a MISSING sig warns-and-proceeds
-    // but a PRESENT-but-INVALID sig ALWAYS fails closed. Flip to true once every release is signed.
-    const SIGNING_REQUIRED = false;
+    // (SEC-0010 #6 — trust root = the pubkey EMBEDDED in this file, so an attacker who swaps the
+    // bundle cannot also swap the key it is checked against).
+    //
+    // SIGNING_REQUIRED was `false` transitionally, for releases that predated signing. That is over:
+    // every release from v2.0.0 on is signed, including the pinned offline fallback (RELEASE_VERSION).
+    // Leaving it false left a real downgrade path — strip or 404 the small .sig file and the missing-
+    // signature branch printed a warning and extracted 800MB+ of executable .mjs anyway. No alarm
+    // fired, because no signature was ever obtained. Now a missing signature fails closed like an
+    // invalid one, and --no-verify remains the single explicit, user-chosen override.
+    const SIGNING_REQUIRED = true;
     if (downloaded && !FLAG_NO_VERIFY) {
       const sigPath = `${zipPath}.sig`;
       const hasSig = fs.existsSync(sigPath);
-      if (!hasSig && !SIGNING_REQUIRED) {
-        warn('this release is not signed yet — proceeding (bundle integrity not cryptographically verified)');
+      if (!hasSig) {
+        try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch { /* ignore */ }
+        die(`no signature published alongside this release — refusing to extract an unverified bundle${sigError ? `\n  (signature fetch failed: ${sigError})` : ''}`,
+            `Every release from v2.0.0 on is signed, so a missing signature means the download was\nincomplete, blocked, or tampered with. Re-run to fetch a fresh copy. If it persists, report it.\n(Override at your own risk with ${c.bold('--no-verify')}.)`);
       } else {
         step('Verifying the bundle signature', 'so a tampered or MITM-swapped download can never be extracted');
         const { ok: valid, reason } = verifyBundle(zipPath, sigPath);
@@ -2570,6 +2802,39 @@ It is safe to re-run at any time. After installing, restart Claude Code so the g
   // out what we did — which is precisely the position the 2026-07-20 corporate-machine reporter was
   // left in. Derived from disk, so it can only ever describe what is actually there.
   try { printFootprint(); } catch { /* a summary must never break a finished install */ }
+
+  // ── SCOPE + UPGRADE, on the path a real user actually takes ─────────────────────────────────
+  //
+  // These two blocks were first added inside runDemo(), which only runs with --demo — so almost
+  // nobody would have seen them. Caught by running the install path instead of reasoning about it
+  // (P1: verify through the USER'S path, never your own). printFootprint() is the right neighbour:
+  // it already exists to tell someone exactly what is now on their machine.
+  //
+  // Read-only and fail-silent. This INFORMS; it never changes scope on its own. P3 (nudge, never
+  // force) and P4 (the user is the arbiter of their own machine).
+  try {
+    const { detectCurrentScope, explainChoice, RECOMMENDED } = await import(new URL('../scripts/install-scope.mjs', import.meta.url).href);
+    const current = detectCurrentScope();
+    if (current && current.scope !== RECOMMENDED) {
+      console.log(`\n${c.dim('  ── how this is set up on your machine ──')}`);
+      for (const line of String(explainChoice({ current: current.scope })).split('\n').slice(0, 12)) console.log(`  ${line}`);
+    }
+  } catch { /* informational only */ }
+
+  try {
+    const { shouldNotify, noticeFor, recordNotified } = await import(new URL('../scripts/upgrade-notice.mjs', import.meta.url).href);
+    const v = wrapperVersion();
+    if (v && shouldNotify(v)) {
+      const notice = noticeFor(v);
+      if (notice) {
+        console.log('');
+        for (const line of String(notice).split('\n').slice(0, 14)) console.log(`  ${line}`);
+        // Record it so this fires at most once per minor version — the anti-nag rule is only real
+        // if the "already told them" state is actually written.
+        try { recordNotified(v); } catch { /* best effort */ }
+      }
+    }
+  } catch { /* informational only */ }
 })().catch((e) => {
   die(e && e.message ? e.message : String(e));
 });

package/kb/verify-citation.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+// verify-citation.mjs — decide whether an answer is GROUNDED, by ground truth rather than by vibes.
+//
+// WHY THIS EXISTS
+// ---------------
+// The old grounding check asked: does the answer contain the string "rvf" or "ruvector"? A model
+// that hallucinated "just use RVF!" with zero sources passed. So did an answer citing a file that
+// does not exist. Keyword presence is not evidence — an LLM panel once scored a zero-citation
+// answer 98/100 on this repo.
+//
+// A citation is only real if it RESOLVES: the repo must be an indexed store on disk, and the cited
+// document path must appear as the `path` of an actual passage inside that store's passages file.
+// That is checkable without a model, without the network, and without trusting anything the model
+// said. This module does exactly that and nothing else.
+//
+// The reader (`forge-ask-all.mjs`) prints each hit as:
+//     #1  repo=concepts  ce=0.201  vec=0.8686  kind=doc
+//     path : concepts/ruvector/CARD/ruvector-card
+//     title: ruvector — Capability
+// Note the printed path is `<repo>/<docPath>`; inside `concepts.passages.jsonl` the stored `path`
+// is just `ruvector/CARD/ruvector-card` (optionally suffixed `#0`, `#1`, … when chunked).
+
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+
+/** Parse the reader's stdout into structured citations. Never throws; unparseable input → []. */
+export function parseCitations(stdout) {
+  const out = [];
+  const text = String(stdout ?? '');
+  const blockRe = /^#(\d+)\s+repo=(\S+)(?:\s+ce=(-?[\d.]+))?(?:\s+vec=(-?[\d.]+))?(?:\s+kind=(\S+))?/gm;
+  let m;
+  while ((m = blockRe.exec(text)) !== null) {
+    const rest = text.slice(m.index);
+    const pathM = /^path\s*:\s*(.+)$/m.exec(rest);
+    const titleM = /^title\s*:\s*(.+)$/m.exec(rest);
+    if (!pathM) continue;
+    const repo = m[2];
+    const fullPath = pathM[1].trim();
+    // Strip the repo prefix the reader adds, so the remainder can be matched against the store.
+    const docPath = fullPath.startsWith(`${repo}/`) ? fullPath.slice(repo.length + 1) : fullPath;
+    out.push({
+      rank: Number(m[1]),
+      repo,
+      ce: m[3] !== undefined ? Number(m[3]) : null,
+      vec: m[4] !== undefined ? Number(m[4]) : null,
+      kind: m[5] ?? null,
+      fullPath,
+      docPath,
+      title: titleM ? titleM[1].trim() : null,
+    });
+  }
+  return out;
+}
+
+/** The passages files that could hold a repo's documents — the slim store and the deep `.big` one. */
+export function passagesFilesFor(repo, kbDir) {
+  return [path.join(kbDir, `${repo}.passages.jsonl`), path.join(kbDir, `${repo}.big.passages.jsonl`)]
+    .filter((p) => fs.existsSync(p));
+}
+
+/** True when `stored` is the cited doc, allowing for the `#N` chunk suffix the builder appends. */
+function samePath(stored, docPath) {
+  return stored === docPath || stored.startsWith(`${docPath}#`);
+}
+
+/**
+ * Does this citation point at a passage that really exists on disk?
+ * Streams the file and stops at the first match, so a 500MB `.big` store costs only as much as it
+ * takes to reach the hit. A malformed JSON line is skipped, never fatal.
+ */
+export async function citationResolves(citation, kbDir) {
+  const files = passagesFilesFor(citation.repo, kbDir);
+  if (!files.length) return { resolved: false, reason: 'no-store', file: null, storedPath: null };
+  for (const file of files) {
+    const rl = readline.createInterface({ input: fs.createReadStream(file), crlfDelay: Infinity });
+    try {
+      for await (const line of rl) {
+        if (!line) continue;
+        let rec;
+        try { rec = JSON.parse(line); } catch { continue; }
+        if (typeof rec?.path === 'string' && samePath(rec.path, citation.docPath)) {
+          return { resolved: true, reason: 'ok', file: path.basename(file), storedPath: rec.path };
+        }
+      }
+    } finally {
+      rl.close();
+    }
+  }
+  return { resolved: false, reason: 'path-not-in-store', file: null, storedPath: null };
+}
+
+/**
+ * The gate. An answer is grounded only when it cites at least one passage that resolves on disk.
+ * Returns the receipt so a caller can PRINT the evidence instead of asserting a conclusion.
+ */
+export async function verifyGrounding(stdout, kbDir) {
+  const citations = parseCitations(stdout);
+  if (!citations.length) {
+    return { grounded: false, reason: 'no-citations', citations: [], receipt: null };
+  }
+  for (const citation of citations) {
+    const r = await citationResolves(citation, kbDir);
+    if (r.resolved) {
+      return {
+        grounded: true,
+        reason: 'ok',
+        citations,
+        receipt: { repo: citation.repo, path: citation.fullPath, title: citation.title, file: r.file, storedPath: r.storedPath },
+      };
+    }
+  }
+  return { grounded: false, reason: 'citations-do-not-resolve', citations, receipt: null };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ruvnet-brain",
-  "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.",
+  "version": "3.9.50-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": {
     "ruvnet-brain": "bin/install.mjs"
@@ -22,8 +22,6 @@
     "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",
     "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",
@@ -31,13 +29,17 @@
     "catalog:verify": "node scripts/verify-model-catalog.mjs",
     "catalog:refresh": "node scripts/refresh-model-catalog.mjs",
     "falsify": "node scripts/falsify.mjs",
-    "sbom": "npx --yes @cyclonedx/cyclonedx-npm --omit dev --output-file sbom/ruvnet-brain.cdx.json --mc-type application --validate"
+    "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",
+    "status:check": "node scripts/status-honesty.mjs"
   },
   "files": [
     "bin/install.mjs",
     "README.md",
     "LICENSE",
-    "config/",
+    "config/model-router/",
+    "kb/verify-citation.mjs",
     "scripts/model-router-engine.mjs",
     "scripts/model-router-setup.mjs",
     "scripts/model-router-status.mjs",

package/config/ruvnet-autoupdate.sh.snapshot

@@ -1,109 +0,0 @@
-#!/bin/bash
-# Ruvnet Ecosystem Auto-Update
-# Updated: 2026-05-07
-#
-# Runs every night at 03:30 via ~/Library/LaunchAgents/com.stuartkerr.ruflo-autoupdate.plist
-# Discovers all currently-installed Ruvnet ecosystem packages and refreshes them.
-#
-# Tag policy:
-#   - ruflo, @claude-flow/cli       → @alpha (Stuart runs alpha track)
-#   - agentdb                       → RETIRED 2026-05-30: AgentDB is bundled inside
-#                                     @claude-flow/memory (Ruflo); no standalone install.
-#   - everything else (@ruvector/*, ruvector, @claude-flow/aidefence,
-#     agent-browser, agentic-flow, flow-nexus)
-#                                   → @latest
-
-set -uo pipefail
-
-LOG="$HOME/Library/Logs/ruflo-autoupdate.log"
-PATH="$HOME/.npm-global/bin:/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin"
-export PATH
-
-ts() { date -u +"[%Y-%m-%dT%H:%M:%SZ]"; }
-
-echo "$(ts) ──── Ruvnet ecosystem update starting ────" | tee -a "$LOG"
-
-# Packages known to fail on this platform — skipped from auto-update.
-# @ruvector/edge-net pulls wrtc which needs a darwin-arm64 prebuilt binary
-# from S3 that returns 404. Bug in upstream wrtc package, not actionable here.
-SKIP_PACKAGES="@ruvector/edge-net"
-
-is_skipped() {
-  local pkg="$1"
-  for sk in $SKIP_PACKAGES; do
-    [ "$pkg" = "$sk" ] && return 0
-  done
-  return 1
-}
-
-# Discover all currently-installed packages of interest
-# Discover all currently-installed RuvNet packages.
-# 2026-07-13: the old filter listed only 7 names/prefixes, so agentic-qe, @metaharness/*, qudag,
-# ruv-swarm, ruvbot, ruvi, ruvector-extensions and agentic-robotics were installed but NEVER updated
-# — silently frozen at whatever version they landed on. Live drift found that day: agentic-qe
-# 3.11.5 vs 3.12.0, ruvbot 0.3.1 vs 0.3.2, ruvector-extensions 0.1.1 vs 0.1.2.
-# Principle: if it is an installed RuvNet package, it gets kept current. No arbitrary allowlist.
-# (@marketing/ai-swarms is a LOCAL npm link — never npm-install over it; it is excluded by name.)
-PACKAGES=$(npm ls -g --depth=0 --json 2>/dev/null | jq -r '
-  .dependencies // {} | keys[] | select(
-    startswith("@ruvector/") or
-    startswith("@claude-flow/") or
-    startswith("@metaharness/") or
-    startswith("@agentic-robotics/") or
-    . == "ruflo" or
-    . == "ruvector" or
-    . == "ruvector-extensions" or
-    . == "agent-browser" or
-    . == "agentic-flow" or
-    . == "agentic-qe" or
-    . == "agentic-robotics" or
-    . == "flow-nexus" or
-    . == "qudag" or
-    . == "ruv-swarm" or
-    . == "ruvbot" or
-    . == "ruvi"
-  ) | select(startswith("@marketing/") | not)
-')
-
-if [ -z "$PACKAGES" ]; then
-  echo "$(ts) ERROR: no Ruvnet packages found via 'npm ls -g'" | tee -a "$LOG"
-  exit 1
-fi
-
-# Build install args with the right tag per package
-INSTALL_ARGS=""
-SKIPPED=""
-ALPHA_PACKAGES="ruflo @claude-flow/cli"
-for pkg in $PACKAGES; do
-  if is_skipped "$pkg"; then
-    SKIPPED="$SKIPPED $pkg"
-    continue
-  fi
-  TAG="@latest"
-  for alpha_pkg in $ALPHA_PACKAGES; do
-    if [ "$pkg" = "$alpha_pkg" ]; then
-      TAG="@alpha"
-      break
-    fi
-  done
-  INSTALL_ARGS="$INSTALL_ARGS ${pkg}${TAG}"
-done
-
-if [ -n "$SKIPPED" ]; then
-  echo "$(ts) Skipping known-broken packages:$SKIPPED" | tee -a "$LOG"
-fi
-
-echo "$(ts) Updating: $INSTALL_ARGS" | tee -a "$LOG"
-
-# Run the install — keep going even if one package fails
-npm install -g $INSTALL_ARGS 2>&1 | tee -a "$LOG"
-
-EXIT_CODE=$?
-if [ $EXIT_CODE -eq 0 ]; then
-  echo "$(ts) ✓ auto-update finished cleanly" | tee -a "$LOG"
-else
-  echo "$(ts) ⚠ auto-update finished with exit code $EXIT_CODE — check log for failed packages" | tee -a "$LOG"
-fi
-
-echo "" | tee -a "$LOG"
-exit $EXIT_CODE

package/config/scheduled-jobs.json

@@ -1,119 +0,0 @@
-{
-  "_why": "THE REGISTRY OF WHAT MUST BE RUNNING. Created 2026-07-13 after a failure that must never repeat: com.ruvnet.brain-nightly's launchd trigger had NEVER fired, and nothing noticed, because 'is it running?' was only ever answered by looking at a job's own exit code \u2014 and launchd reports exit 0 for a job that has never run, which is indistinguishable from success. Silence was being read as health.",
-  "_how_it_works": "scripts/job-heartbeat.sh wraps every job and writes start/end/exit receipts that a dying job cannot forge or skip (trap-protected). scripts/nightly-watchdog.mjs compares THIS registry against reality: a job listed here that is not loaded, or loaded but has no fresh receipt, or has a receipt with a non-zero exit, is a VIOLATION and gongs the phone. Absence of evidence is failure, never 'probably fine'.",
-  "_adding_a_job": "Add it here FIRST, then wrap its plist command in job-heartbeat.sh. A job not in this registry is unwatched by definition \u2014 that is the whole point of a registry rather than per-job good intentions.",
-  "heartbeatDir": "~/.cache/ruvnet-brain/heartbeats",
-  "jobs": [
-    {
-      "label": "com.ruvnet.brain-nightly",
-      "what": "Refreshes every RuvNet repo, rebuilds the brain, publishes the GitHub Release",
-      "schedule": "daily 03:15",
-      "maxAgeHours": 26,
-      "required": true,
-      "legacyLog": "logs/nightly.log"
-    },
-    {
-      "label": "com.ruvnet.brain-gists",
-      "what": "Pulls rUv's new gists into the brain and re-embeds when they change",
-      "schedule": "daily 21:47",
-      "maxAgeHours": 26,
-      "required": true,
-      "legacyLog": "logs/gists-nightly.log"
-    },
-    {
-      "label": "com.ruvnet.goldie-weekly",
-      "what": "Re-researches the cheapest/best models and refreshes the router catalog",
-      "schedule": "Mondays 07:30",
-      "maxAgeHours": 192,
-      "required": true,
-      "legacyLog": "logs/goldie.log"
-    },
-    {
-      "label": "com.ruvnet.model-refresh",
-      "what": "Refreshes the live model list (~/.claude/models.json) that the router prices against",
-      "schedule": "daily 09:00",
-      "maxAgeHours": 26,
-      "required": true
-    },
-    {
-      "label": "com.ruvnet.npm-token-renew",
-      "what": "Renews the npm publish token before it expires (silently lets publishing die if it stops)",
-      "schedule": "daily 03:33",
-      "maxAgeHours": 26,
-      "required": true,
-      "_was_blind": "THE PUREST CASE OF THE BUG. On a healthy day this script returns early and writes ZERO BYTES anywhere \u2014 its log and state file sat frozen 2+ days stale while it fired on schedule every night. 'Ran and did nothing (healthy)' was literally indistinguishable from 'never ran', ~76 days out of every 90. The heartbeat wrapper fixes this for free: the RECEIPT is written by the wrapper, so the job no longer has to remember to report."
-    },
-    {
-      "label": "com.stuartkerr.api-spend-watchdog",
-      "what": "Hourly guard against runaway API spend and agent bursts \u2014 the one that actually pages the phone",
-      "schedule": "hourly",
-      "maxAgeHours": 3,
-      "required": true,
-      "_note": "It has been pushing '4 scheduled jobs failing silently' every hour, correctly \u2014 but off launchctl's exit-code field, which CANNOT see a job that never ran. It alerts; it just can't see the hole. Now it is itself watched: nothing supervised the supervisor."
-    },
-    {
-      "label": "com.stuartkerr.ruflo-autoupdate",
-      "what": "Keeps the whole RuvNet/Ruflo npm stack current (npm i -g ~26 packages on @latest/@alpha)",
-      "schedule": "daily 03:30",
-      "maxAgeHours": 26,
-      "required": true,
-      "_note": "This is THE job that keeps rUv's stack fresh on this machine. It was unwatched until 2026-07-13 \u2014 the single most important update job here had no supervision at all."
-    },
-    {
-      "label": "com.cognitum.ruvector-autoupdate",
-      "what": "Every 6h: git pull of ~/RuVector_Clean (the RuVector source the Rust crates build from)",
-      "schedule": "every 6h",
-      "maxAgeHours": 8,
-      "required": true,
-      "_note": "Its git stash pop has silently failed once (orphaned stash@{0} from 2026-06-28 \u2014 it swallowed local edits and nothing said so). The heartbeat now catches a non-zero exit; the orphaned stash still needs a human decision."
-    },
-    {
-      "label": "com.stuartkerr.clear-claude-tmp",
-      "what": "Every 3h: purges Claude Code task-output temp files older than 2 days (the dir hits ~800MB)",
-      "schedule": "every 3h",
-      "maxAgeHours": 5,
-      "required": true,
-      "_was_lying": "Its log line had the date BAKED IN at plist-write time \u2014 all 43 entries since 2026-04-06 were byte-identical. It worked; its log was a lie. Now a real script with a real $(date) and a real delete count."
-    },
-    {
-      "label": "com.ruvnet.nightly-watchdog",
-      "what": "Watches all of the above. Listed here so that IT is watched too \u2014 a watchdog nobody watches is the same blind spot one level up",
-      "schedule": "daily 09:00",
-      "maxAgeHours": 26,
-      "required": true
-    },
-    {
-      "label": "com.ruvnet.issue-watch",
-      "what": "Hourly GitHub-issues SLA watcher (stuinfla/ruvnet-brain) \u2014 pages ntfy when an open issue sits >4h with no comment from the repo owner",
-      "schedule": "hourly",
-      "maxAgeHours": 3,
-      "required": true
-    },
-    {
-      "label": "com.ruvnet.issue-fix",
-      "what": "Every 30 min (was 10 \u2014 a real run takes ~13 min, so the 10-min schedule SIGTERMed its own overlapping runs, fixed 2026-07-18): auto-fixes newly opened GitHub issues (stuinfla/ruvnet-brain) \u2014 bounded headless `claude -p` per issue in a disposable git worktree, pushes an issue-fix/<N> branch + comment or posts an honest triage comment, never touches main, never closes an issue",
-      "schedule": "every 10 min",
-      "maxAgeHours": 1,
-      "required": true
-    },
-    {
-      "label": "com.ruvnet.routing-flywheel",
-      "schedule": "nightly 04:45",
-      "maxAgeHours": 26,
-      "what": "nightly data-readiness DRY-RUN of the routing flywheel (the plist runs --dry-run: reads receipts + prints readiness, runs NO loop and writes NO receipt — honest label per F13 2026-07-18; switch the plist to --synthetic to run a real $0 loop)"
-    },
-    {
-      "label": "com.ruvnet.npx-witness",
-      "schedule": "WatchPaths on ~/.npm/_npx (event-driven, no cadence)",
-      "maxAgeHours": 2160,
-      "what": "records every npx-cache mutation to the witness log (pure observer). Event-driven: weeks of silence are NORMAL when nothing touches _npx — maxAgeHours is a 90-day tripwire against the job being unloaded, not a freshness SLA. Registered per F2 2026-07-18: it was loaded+wrapped but absent here, i.e. unwatched by the registry's own definition."
-    }
-  ],
-  "_retired": [
-    {
-      "label": "io.ruv.auto-subscribe",
-      "retired": "2026-07-14",
-      "why": "archived as cruft (archive-cruft-2026-07-14/); hourly RuvNet package auto-install is superseded by com.stuartkerr.ruflo-autoupdate (daily) + com.cognitum.ruvector-autoupdate. Removed from watch registry 2026-07-18 so nightly-watchdog stops flagging a deliberately-killed job."
-    }
-  ]
-}