ruvnet-brain 4.6.0 → 4.6.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
CHANGED
|
@@ -1,599 +1,331 @@
|
|
|
1
|
-
Updated: 2026-10-10
|
|
1
|
+
Updated: 2026-10-10 10:41:47 EDT | Version 4.6.1
|
|
2
2
|
Created: 2026-06-29 22:36:38 EDT
|
|
3
3
|
|
|
4
4
|
<div align="center">
|
|
5
5
|
|
|
6
|
-
|
|
7
7
|
|
|
8
8
|
# 🧠 RuvNet Brain
|
|
9
9
|
|
|
10
|
-
###
|
|
10
|
+
### Discover the stack. Read the source. Build with confidence.
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
[](plugin/.claude-plugin/plugin.json)
|
|
13
13
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
## 4.6.0 coordinated updates and proof boundaries
|
|
17
|
-
|
|
18
|
-
The 4.6.0 source introduces one coordinated updater for installed tools, host plugins and the
|
|
19
|
-
Brain's signed knowledge bundle. RNBC presents **Keep all tools updated** with **Latest
|
|
20
|
-
(recommended)** or **Alpha**. The public default covers the RuvNet suite; wider developer-tool
|
|
21
|
-
maintenance requires an explicit choice. See the update policy in `CONTRIBUTING.md` and the
|
|
22
|
-
4.6.0 release notes in `docs/RELEASE-NOTES-4.6.0.md`.
|
|
23
|
-
|
|
24
|
-
A saved choice or registered schedule proves configuration. Completed runs, installed versions
|
|
25
|
-
and the protected release's public installation receipt prove different things. This source
|
|
26
|
-
version alone does not establish publication, all-tool freshness or a new product score.
|
|
27
|
-
|
|
28
|
-
> ## 🧭 North Star
|
|
29
|
-
>
|
|
30
|
-
> **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.
|
|
31
|
-
>
|
|
32
|
-
> **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."*
|
|
33
|
-
>
|
|
34
|
-
> **Retrieval was never the product. Proactive capability advocacy is the product.**
|
|
35
|
-
>
|
|
36
|
-
> 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.
|
|
37
|
-
>
|
|
38
|
-
> 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).
|
|
39
|
-
|
|
40
|
-
<div align="center">
|
|
14
|
+
**A source-grounded companion for Claude Code and Codex that helps you find and use Reuven Cohen's (rUv's) RuvNet ecosystem.**
|
|
41
15
|
|
|
42
|
-
[](https://isovision.ai/ruvnet-brain/)
|
|
16
|
+
[](https://www.npmjs.com/package/ruvnet-brain)
|
|
17
|
+
[](https://github.com/stuinfla/ruvnet-brain/releases/latest)
|
|
18
|
+
[](https://isovision.ai/ruvnet-brain/)
|
|
46
19
|
[](LICENSE)
|
|
47
|
-
[](#testing--proof)
|
|
48
|
-
[](#testing--proof)
|
|
49
20
|
|
|
50
|
-
|
|
51
|
-
> - **`plugin`** (badge above) — the Claude Code plugin itself: SKILL.md, the grounding hooks, the MCP server. Read live from [`plugin/.claude-plugin/plugin.json`](plugin/.claude-plugin/plugin.json). Updates often — this is where behavior fixes land.
|
|
52
|
-
> - **`installer (npm)`** (badge above) — the setup script's published version, read live from the [npm registry](https://www.npmjs.com/package/ruvnet-brain). It is a release surface of the same product, not an independent version track.
|
|
53
|
-
> - **Brain Release** — [`releases/latest`](https://github.com/stuinfla/ruvnet-brain/releases/latest) exposes the published knowledge bundle. It must agree with that release's npm, plugin, and signed artifact identities. A moving source badge does not establish publication.
|
|
54
|
-
> - **Update an existing Brain installation:** invoke its existing `ruvnet-brain --update` command. For an explicit developer checkout, use `node bin/install.mjs --update`. Initial installation may use `npx ruvnet-brain@latest`; routine updates preserve the installed owner instead of creating a second tool installation.
|
|
55
|
-
> - **Check installed tools:** `ruvnet-brain-update --check`. Apply the saved policy with `ruvnet-brain-update --apply`; inspect the receipt for exclusions and failures.
|
|
56
|
-
> - **Coordinate installed tools:** open RNBC and use **Keep all tools updated**. Choose **Latest (recommended)** or **Alpha**, and explicitly choose wider tool maintenance when wanted. The schedule runs at **03:30 in the user's local time** through the same coordinator as a manual run.
|
|
57
|
-
> - **Disable scheduled updates:** use the existing `ruvnet-brain --disable-nightly` command. Registration and run health are reported separately.
|
|
58
|
-
> - **Publication, local activation, and loaded session version are distinct observations.** An unchanged release does not by itself prove local health, freshness, or a successful update.
|
|
21
|
+
### [▶ Explore the visual walkthrough](https://isovision.ai/ruvnet-brain/)
|
|
59
22
|
|
|
60
|
-
|
|
23
|
+
[](https://isovision.ai/ruvnet-brain/)
|
|
61
24
|
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
<sub>An interactive, animated walkthrough of what you can actually build — **click the preview** to open it.</sub>
|
|
65
|
-
|
|
66
|
-
[](https://isovision.ai/ruvnet-brain/)
|
|
25
|
+
<sub>Built by **Stuart Kerr** at **Isovision.ai** · open source · MIT licensed</sub>
|
|
67
26
|
|
|
68
27
|
</div>
|
|
69
28
|
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
**The corpus stopped drifting behind the org.** Until 4.2 nothing ever ingested a new repo: the
|
|
75
|
-
nightly refreshed lessons, health and proofs and contained *zero* ingestion, so a repo entered the
|
|
76
|
-
brain only when a human typed the command. `brain-stamp.mjs` had been measuring that gap every
|
|
77
|
-
night, but nothing consumed it until the ingestion loop shipped.
|
|
78
|
-
|
|
79
|
-
- **187 stores, up from 69.** Everything rUv ships that has content, pulled in and kept level by
|
|
80
|
-
`scripts/ingest-new-repos.mjs` running nightly, newest-first. Empty repos (`size=0KB`) are skipped
|
|
81
|
-
rather than retried forever — a permanent nightly failure that is actually correct behaviour
|
|
82
|
-
trains you to ignore the failure line, which is how a real one would hide inside it.
|
|
83
|
-
- **174 capability cards, up from 39.** Ingesting a repo is not the same as making it reachable: a
|
|
84
|
-
store with no card is *dark* — valid bytes no by-description query can find. Cards are written
|
|
85
|
-
from each repo's **own** description and README, never from its name, and where there is no
|
|
86
|
-
grounded source text the store is **left dark and reported** rather than given an invented
|
|
87
|
-
sentence. 13 remain dark for exactly that reason.
|
|
88
|
-
- **The download barely grew** for 2.4x the corpus — most of rUv's repos are small, so the bulk
|
|
89
|
-
of the bundle was always the large ones. (No size is hand-typed here: a number typed onto a
|
|
90
|
-
public page rots the moment the next bundle is built, and this repo gates against exactly that.)
|
|
91
|
-
- **The nightly stopped discarding its own writes.** It hardcoded a node whose ABI did not match
|
|
92
|
-
agentdb's binding, so `lesson-bridge --apply` and `learning-replay` wrote into a silent
|
|
93
|
-
non-persistent fallback. It now resolves an ABI-matched interpreter and fails loudly instead.
|
|
94
|
-
|
|
95
|
-
## Earlier — 4.2 anticipated, and learned whether it was right
|
|
96
|
-
|
|
97
|
-
**Building toward L4/L5 (3.9.x, dev).** The mechanisms for the top two rungs of the proactivity
|
|
98
|
-
ladder are built and wired — but they are **not yet verified to 4.0's bar**, which requires all five
|
|
99
|
-
of ADR-028's test classes green under independent grading. Until then, [ADR-028](docs/adr/0028-what-proactive-means.md)
|
|
100
|
-
grades the shipped, *verified* state at **L2–L3**, and `-dev` is the honest version. 4.0 is claimed
|
|
101
|
-
only when L3+L4+L5 are each measured, not when the code merely exists.
|
|
102
|
-
|
|
103
|
-
- **L4 Anticipatory (mechanism built).** It infers what you're *trying to do* and names the capability
|
|
104
|
-
that serves that goal — before you hit the wall. Built to stay quiet: a match needs **two
|
|
105
|
-
independent cues** (the problem AND that the topic is your AI workflow), so near-misses get
|
|
106
|
-
silence. Measured on the negative table: **0 false positives**; fires on a genuine match. What's
|
|
107
|
-
still owed for L4: the full five-class verification, independently graded.
|
|
108
|
-
- **L5 Compounding (mechanism built, metric now live).** Advocacy records whether it was right —
|
|
109
|
-
precision = acted-on ÷ offered, ADR-028's line between advocating and nagging. The numerator is
|
|
110
|
-
now **derived from an observed state transition** (offered → later switched on = applied) and
|
|
111
|
-
surfaced in the console; it reads an honest `null` until enough offers resolve, never a fabricated
|
|
112
|
-
score. A dismissal is evidence about **fit, not importance** — asymmetric budget: a suggestion dies
|
|
113
|
-
on one dismissal, an important finding needs three. What's still owed for L5: real precision data
|
|
114
|
-
from use, and the cross-project promotion test.
|
|
115
|
-
- **The admin page is rebuilt around deltas**, not lifetime totals — and the humans who wrote in
|
|
116
|
-
are promoted to the top, ranked by recency rather than lifetime count.
|
|
117
|
-
|
|
118
|
-
<details>
|
|
119
|
-
<summary><b>Earlier — what 3.8 shipped</b> · the gate that fires when you stop. <i>Expand.</i></summary>
|
|
120
|
-
|
|
121
|
-
## 3.8 — the gate that fires when you stop
|
|
122
|
-
|
|
123
|
-
**Shipped 2026-07-22.** Every gate in this project fires on an **action** — a write, a push, a
|
|
124
|
-
claim. That is what makes it enforceable. But **stopping is the absence of an action**, so the most
|
|
125
|
-
expensive failure of the night had no trigger at all, and a system built to prevent it did not.
|
|
126
|
-
|
|
127
|
-
- **`continuation-gate.mjs`** runs when a turn ends. If work you committed to is unfinished, it
|
|
128
|
-
makes that the last thing in context. It cannot force another turn — claiming otherwise would be
|
|
129
|
-
the fabrication this project exists to kill — but it removes the silence that let a stop pass
|
|
130
|
-
unnoticed.
|
|
131
|
-
- **Project-scoped ledgers.** Three simultaneous projects never see each other's commitments; a
|
|
132
|
-
"you didn't finish X" fired in a repo that never heard of X is a false alarm, and ADR-028 fixes
|
|
133
|
-
the false-alarm rate at zero.
|
|
134
|
-
- **Installed machine-wide**, merged into existing hooks rather than replacing them, with a backup
|
|
135
|
-
taken first — that file governs every project on the machine.
|
|
136
|
-
|
|
137
|
-
<details>
|
|
138
|
-
<summary><b>Earlier — what 3.7 shipped</b> · your lessons can now refuse your work. <i>Expand.</i></summary>
|
|
139
|
-
|
|
140
|
-
## 3.7 — your lessons can now refuse your work
|
|
141
|
-
|
|
142
|
-
**Shipped 2026-07-22.** 3.6 made the machine legible. 3.7 closes the loop: a lesson you taught is
|
|
143
|
-
read by a gate at the moment it applies, and — once you ratify it — **refuses the action**.
|
|
29
|
+
The RuvNet ecosystem spans agent orchestration, vector search, memory, model routing,
|
|
30
|
+
testing and more. Finding the right building block is often harder than writing the first
|
|
31
|
+
line of code. Brain puts the source within reach of your coding assistant and helps it
|
|
32
|
+
recognize capabilities you may not yet know to ask for.
|
|
144
33
|
|
|
145
|
-
|
|
146
|
-
back, with the evidence and how many times you had to say it. Wired into the real pre-push gate.
|
|
147
|
-
- **`lesson-ratify.mjs`** — see every lesson, ratify it, or delete it. **Demotion is sticky**: it
|
|
148
|
-
survives every future mining run, because a reject the nightly quietly undoes is worse than none.
|
|
149
|
-
- **The model cannot ratify its own rules.** Lessons it inferred about itself are quarantined and
|
|
150
|
-
can never block, no matter what is asked of them — closing an injection path an adversarial
|
|
151
|
-
review found, where a hallucinated session summary could have become a blocking gate.
|
|
152
|
-
- Proven end to end: before ratification the ship gate informs (exit 0); after ratifying the
|
|
153
|
-
version-discipline lesson it **refuses** (exit 1). Same wire, no code change — enforcement is data.
|
|
34
|
+
**Ask for the outcome you want. Brain helps connect it to the real tools and code.**
|
|
154
35
|
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
## 3.6 — it can finally show you what you own
|
|
159
|
-
|
|
160
|
-
**Shipped 2026-07-22.** 3.5 made the brain speak. 3.6 makes it *legible*: a console panel that
|
|
161
|
-
answers the question the owner has been asking for weeks — **"what is actually turned on?"**
|
|
162
|
-
|
|
163
|
-
- **Eleven capabilities, each ON / OFF / UNKNOWN**, every state *derived* from a real check on your
|
|
164
|
-
machine at render time. `UNKNOWN` is a first-class state and is visually separated from `OFF` in a
|
|
165
|
-
non-colour channel, because collapsing the two is precisely the lie this release exists to kill.
|
|
166
|
-
- **A one-line plain-English "what it buys you"** on every row, and the evidence we observed.
|
|
167
|
-
- **Settings that are conservative by construction.** Each setting declares which of its *values*
|
|
168
|
-
escalate beyond the current project, and `default ∉ escalates` is asserted as a test — so the rule
|
|
169
|
-
holds for settings added later instead of relying on a comment nobody re-reads.
|
|
170
|
-
- **A false alarm found and killed.** 3.5's audit reported *"26 learning hooks installed and every
|
|
171
|
-
one is switched off."* That was wrong: `ruflo hooks list` renders a table column keyed `enabled`
|
|
172
|
-
against a payload that has no such key, so it prints "No" 26 times. The learner had 457
|
|
173
|
-
trajectories and had adapted 106 minutes earlier. We scraped a human-readable table instead of
|
|
174
|
-
reading state, which is the exact mistake this project keeps writing rules about. The detector now
|
|
175
|
-
reads the learner's own state file and **stays silent when it cannot tell** — ADR-028 fixes the
|
|
176
|
-
false-alarm rate at zero and calls it non-negotiable.
|
|
177
|
-
- **Three surfaces that were built and never wired** are now connected. `capability-registry.mjs`
|
|
178
|
-
had zero call sites; the client referenced it only in comments. Built-tested-unwired is this
|
|
179
|
-
project's signature failure, and it happened three times in one night.
|
|
180
|
-
|
|
181
|
-
Honest limit: this is still a dev release, **not 4.0**. 4.0 requires levels 3–5 of ADR-028's ladder
|
|
182
|
-
(contextual, anticipatory, compounding) **shipped and independently graded ≥95**. The mechanisms now
|
|
183
|
-
exist — L3's delivery seam (the chokepoint), an L4 goal surface, and L5 cross-project promotion (lessons
|
|
184
|
-
promoted to your global brain, and survival across `--update` is now *tested* rather than argued —
|
|
185
|
-
`tests/unit/promoted-lessons-survive-update.test.mjs` runs the real updater against a sandboxed HOME
|
|
186
|
-
and asserts the promoted block is byte-identical afterward) — but the ladder still grades **L2–L3**,
|
|
187
|
-
because L3 is built rather than live (deploy-gated) and the five acceptance metrics aren't all measured.
|
|
188
|
-
See `docs/4.0-READINESS.md` and `docs/4.0-EXECUTIVE-BRIEFING.md` (last independent grade: 70/100 overall).
|
|
189
|
-
|
|
190
|
-
<details>
|
|
191
|
-
<summary><b>Earlier — what 3.5 shipped</b> · it stopped waiting to be asked. <i>Expand for the receipts.</i></summary>
|
|
192
|
-
|
|
193
|
-
## 3.5 — it stopped waiting to be asked
|
|
36
|
+
> **Our north star:** useful capability discovery. A good answer should explain what helps,
|
|
37
|
+
> why it fits, where it is implemented, and what remains unproven. Retrieval supports that
|
|
38
|
+
> conversation; the goal is helping you build.
|
|
194
39
|
|
|
195
|
-
|
|
40
|
+
[Get started](#get-started) · [Try it](#try-it-on-your-next-task) ·
|
|
41
|
+
[How it works](#how-it-works) · [Capabilities](#what-brain-brings-to-your-workflow) ·
|
|
42
|
+
[Updates](#stay-current) · [Evidence](#evidence-and-honest-limits)
|
|
196
43
|
|
|
197
|
-
|
|
44
|
+
## What is Brain?
|
|
198
45
|
|
|
199
|
-
|
|
46
|
+
Brain brings three things together:
|
|
200
47
|
|
|
201
|
-
**
|
|
48
|
+
- **A local knowledge bundle** built from public RuvNet source and documentation, with
|
|
49
|
+
searchable passages, source paths, implementation bodies, symbols and capability cards.
|
|
50
|
+
- **A coding companion** delivered through native Claude Code and Codex plugins: the
|
|
51
|
+
`search_ruvnet` MCP tool, skills and lifecycle hooks that encourage source-grounded work.
|
|
52
|
+
- **A local control panel**, the RuvNet Brain Console (RNBC), for inspecting your installed
|
|
53
|
+
environment, choosing supported settings and seeing what actually ran.
|
|
202
54
|
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
- **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.
|
|
207
|
-
- **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.
|
|
55
|
+
It gives the assistant a practical way to read the stack instead of relying on remembered
|
|
56
|
+
APIs. You can ask by product name, describe a problem, or ask where a capability is
|
|
57
|
+
implemented. Results identify the repository and file so the answer can be checked.
|
|
208
58
|
|
|
209
|
-
|
|
59
|
+
**You keep control.** Recommendations, saved settings, executed tools and verified outcomes
|
|
60
|
+
are different things. Brain's evidence surfaces are designed to show those differences.
|
|
210
61
|
|
|
211
|
-
|
|
212
|
-
<summary><b>Earlier — what 3.4 shipped</b> · the invisible work, made visible and readable. <i>Expand for the receipts.</i></summary>
|
|
213
|
-
|
|
214
|
-
## 3.4 — the invisible work, made visible (and readable)
|
|
62
|
+
## Get started
|
|
215
63
|
|
|
216
|
-
|
|
64
|
+
You need Node.js **18 or newer**, npm, and a supported Claude Code or Codex installation.
|
|
65
|
+
Run the installer from your terminal:
|
|
217
66
|
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
- **Diagrams you can actually read** — two of them shipped with labels rendering at **8px and 3px**: present, un-clipped, and invisible. An SVG sized in one coordinate system, crushed into a narrower column, silently shrinks its own text and no error ever fires. There's now a gate for exactly that (`scripts/check-legibility.mjs`) — it measures the *effective* pixel size in the live page, proven to catch the known-bad case before it was trusted. Every diagram label now clears 12px on a phone.
|
|
221
|
-
- **The tips page has a door** — its only link wore the same style as a status readout beside it, and on a phone was hidden entirely — the page was **unreachable under 640px**. There's now an unmissable button where it belongs.
|
|
222
|
-
- **Real generated imagery** — three commissioned stills built from the console's own palette, so they belong to the page instead of sitting on top of it.
|
|
223
|
-
|
|
224
|
-
<details>
|
|
225
|
-
<summary><b>Earlier — what 3.3 proved</b> · it stopped reciting facts and started making a point. <i>Expand for the receipts.</i></summary>
|
|
226
|
-
|
|
227
|
-
## 3.3 — it stopped reciting facts and started making a point
|
|
228
|
-
|
|
229
|
-
**Shipped 2026-07-17.** 3.2 made the stack visible. Visible turned out not to be the same as *useful*: the console could tell you 21 things and leave you no smarter. Stuart, looking at his own product: *"I have no idea what message it's supposed to tell me… it seems to be facts without purpose."* 3.3 is the answer to that — every card now leads with a **verdict**, not a census.
|
|
230
|
-
|
|
231
|
-
- **A second page — [how to actually use this](console/tips.html)** — the question nobody could answer: *there are plugins, there are commands, and there's just… typing. Which am I supposed to use?* One page, three depths, and the first depth is **doing nothing**. Built on rUv's own doctrine: *"I don't have to load 350 skills that 99% of which I never use — the system is smart enough to know which one this task needs."*
|
|
232
|
-
- **MetaHarness, explained where you decide** — the card asked you to switch on a word you'd never seen. It now shows the architecture instead: the model **frozen** at the centre, seven policy surfaces evolving around it, four pillars underneath. rUv called this exact risk in ADR-076 (*"'Meta-harness' is a newer term… must define it in the first screen so it doesn't read as jargon"*); we'd shipped the jargon and skipped the mitigation. Every element traces to an accepted ADR.
|
|
233
|
-
- **The wiring card was lying to you** — it warned about 21 npx call sites. 18 were inside *clones of rUv's own repos* (one a `tests/init-test` fixture), and two were `echo` strings printing advice. Real exposure: **zero**. It now says so: *"Every rUv tool here resolves to one known version."* A card that shows amber for a problem you don't have is worse than no card.
|
|
234
|
-
- **The money leads** — the router card buried *$15.17 saved* as the dimmest text on the row while `FRONTIER — 0` read like missing data. It's the punchline: the expensive model never had to fire. Now it says that, in that order.
|
|
235
|
-
- **What caught Claude** — a new card. 21 gates read every move before it lands; 6 can stop one. The walls now record what they *catch*, not just what they pass — because the ledger held 13 receipts, 13 passing, while the design wall had refused a commit minutes earlier and written nothing down.
|
|
236
|
-
- **The console loads in 0.2s** (was ~14s) — a fleet-wide scan of 107 memory stores sat on the critical path of first paint. It hydrates late now.
|
|
237
|
-
|
|
238
|
-
</details>
|
|
239
|
-
|
|
240
|
-
<details>
|
|
241
|
-
<summary><b>Earlier — what 3.2 proved</b> · the invisible stack, made visible. <i>Expand for the receipts.</i></summary>
|
|
242
|
-
|
|
243
|
-
## 3.2 — the invisible stack, made visible
|
|
244
|
-
|
|
245
|
-
**Shipped 2026-07-16.** rUv's tools do their best work invisibly — which meant nobody could see them working, working stale, or working in conflict. The 3.x line makes the machinery visible, and everything it shows you is measured, never projected.
|
|
246
|
-
|
|
247
|
-
- **A living console** — `/rnbc` puts your whole stack on one page: what's installed, how it's wired, what your AI learned. Every warning arrives paired with a one-click, undoable fix, and the page re-checks itself after every change so you always see the *after* state.
|
|
248
|
-
- **Your brain, visible** — a live **Brain Activity** card: every memory stored, every lesson distilled, clickable down to the verbatim task → what-failed → what-works cards from your own AgentDB (ADR-0018).
|
|
249
|
-
- **Receipts, not estimates** — the routing dashboard recomputes from real routing receipts against *your* frontier; subscriptions price at $0; a providers row shows exactly which license pays for what.
|
|
250
|
-
- **No model fact ships from memory** — the 3.0 live-verification wall: every model/version claim checks the live catalog in CI (ADR-0016), and router profiles self-optimize from rUv's bench plus live prices (ADR-0015).
|
|
251
|
-
- **It learns YOU** — a recursive per-user learning loop (ADR-017): patterns from how you actually work, shared across your projects, isolated where they must be.
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
**Open it any time with `/rnbc`** (RuvNet Brain Console — `/rnb` and the older `/rvbc` work too) — and the first time you load the Brain, it offers to open it for you.
|
|
256
|
-
|
|
257
|
-
> New gate with this release: **narrative versions are tested.** If any public page says "What's new in X" where X isn't the shipping version, CI fails — because this README sat on 2.5 while 3.1 shipped, and nobody's eyes are a gate.
|
|
258
|
-
|
|
259
|
-
</details>
|
|
260
|
-
|
|
261
|
-
<details>
|
|
262
|
-
<summary><b>Earlier — what 2.5 proved</b> · it uses rUv's real tools (a CI gate makes silent hand-rolls impossible), every scheduled job must prove it ran, and no subagent inherits an expensive model by accident. <i>Expand for the receipts.</i></summary>
|
|
263
|
-
|
|
264
|
-
## 2.5 — the receipts
|
|
265
|
-
|
|
266
|
-
**Shipped 2026-07-13. Two hard lessons, both fixed at the root.**
|
|
267
|
-
|
|
268
|
-
### 1. It stopped faking rUv's tools — and now a CI gate makes faking impossible
|
|
269
|
-
|
|
270
|
-
The 2.4 router was **hand-rolled**: our own heuristic with a placeholder policy, presented as "the MetaHarness router." rUv had already shipped the real thing. 2.5 replaces it with **[`@metaharness/router`](https://www.npmjs.com/package/@metaharness/router)** — his actual learned cost-optimal router (k-NN over labelled embeddings, the productized DRACO Phase-2 finding, ADR-040/043).
|
|
271
|
-
|
|
272
|
-
Subscription membership is an eligibility constraint, not a measurement of allowance consumption. The managed terminal workflow uses the current per-user model and effort policy, supervised native workers, executable checks, independent review, and execution receipts. MetaHarness supplies routing and evaluation capabilities; registration or a price transform alone does not execute a prompt or prove a handoff. The supported entry paths and remaining boundaries are described in `docs/model-routing-operation.md`.
|
|
273
|
-
|
|
274
|
-
> **`npm run substitution:check`** — a new CI gate that fails the build if any code implements a capability rUv already ships *and* wears his name without either using the real package or openly disclosing the hand-roll. **Verified to fire on the exact commit where we got this wrong.** You may hand-roll. You may never hand-roll *silently*.
|
|
275
|
-
|
|
276
|
-
### 2. Every scheduled job must PROVE it ran — silence is no longer health
|
|
277
|
-
|
|
278
|
-
`launchctl` reports **exit 0 for a job that has never run** — byte-identical to success. So "check the exit code" cannot tell triumph from total absence, and a nightly job sat unfired for its entire life while every surface read green.
|
|
279
|
-
|
|
280
|
-
- **A registry** (`config/scheduled-jobs.json`) of what *must* run — so unloaded, deleted, or never-fired is a **violation**, not a silence.
|
|
281
|
-
- **A wrapper** every job runs through — start receipt, end receipt, real exit code, urgent phone push on failure. Break-tested through all four death modes (including SIGKILL, which no trap can catch — the watchdog catches that one).
|
|
282
|
-
- **A watchdog** that treats *absence of evidence as failure*, and which is **in its own registry** — because a supervisor nobody supervises just moves the blind spot up one level.
|
|
283
|
-
|
|
284
|
-
Result: **11 jobs supervised, every one producing a fresh successful receipt.** One had been *totally blind* — writing zero bytes on a healthy day, so "ran fine" and "never ran" were indistinguishable. Cured without changing a line of its logic.
|
|
285
|
-
|
|
286
|
-
### 3. Inherited subagent models are now auditable
|
|
287
|
-
|
|
288
|
-
**A subagent inherits your session's model unless something says otherwise.** Ten agents on an Opus session are ten Opus agents; on a Fable session that's `$10/$50` per Mtok — up to **10× what the same mechanical work costs on Haiku**. That single default was the biggest cost leak in the harness, and an advisory rule did not fix it (the router's entire first life saved **$0.018**).
|
|
289
|
-
|
|
290
|
-
The hook records both explicit-model and inherited-model dispatches so routing is *auditable* rather than merely claimed. It does not claim to block Agent/Task calls: Claude Code 2.1.220 consumes those `PreToolUse` results only after `tool_dispatch_end` ([issue #84](https://github.com/stuinfla/ruvnet-brain/issues/84), [upstream #83195](https://github.com/anthropics/claude-code/issues/83195)). Forks still inherit — that's what a fork is.
|
|
291
|
-
|
|
292
|
-
> **`npm run falsify`** — the adversary. Every question that had to be asked of this project ("is the nightly *actually* running?", "is that really rUv's code?", "why is my quota still burning?", "is CI *actually* green?") is now a check that fails on an **unproven claim**, not merely on broken code. Because tests you wrote yourself passing is circular evidence.
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
</details>
|
|
297
|
-
|
|
298
|
-
<details>
|
|
299
|
-
<summary><b>Earlier — what 2.0 proved</b> · the release where the brain stopped taking its own word for anything: 69 verified repos, a 120-question fail-closed eval gate, ~90% cheaper per-turn injection, and an 8-dimension evidence-backed scorecard (55 → 83 in two days). <i>Expand for the receipts.</i></summary>
|
|
300
|
-
|
|
301
|
-
### 2.0 — the receipts
|
|
302
|
-
|
|
303
|
-
**2.0 is the release where the brain got bigger — and, more importantly, stopped taking its own word for anything.** Every number below regenerates from an artifact on disk; the claims ledger (`node scripts/claims-verify.mjs`) re-checks the advertised ones in CI:
|
|
304
|
-
|
|
305
|
-
| | v1 (0.x–1.x) | v2.0 |
|
|
306
|
-
|---|---|---|
|
|
307
|
-
| **Corpus** | 24 repos built | **69 repos** built (of 248 in the org), each verified by a live retrieval query |
|
|
308
|
-
| **Depth** (flagship `ruvector`) | 18,491 passages · **0** full source bodies | **28,018 passages · 2,996 full bodies** — depth also restored to `agent-harness-generator` (8,896/715), `ruview` (7,434/765), `open-claude-code` (195/69) |
|
|
309
|
-
| **Corpus QA gate** | none | every canonical store must prove *embeds correctly + reads correctly* — vector count == passage count, depth floors, and a deterministic self-retrieval round trip — wired fail-closed into nightly promotion |
|
|
310
|
-
| **Retrieval eval** | 12 frozen questions | **120 frozen, hash-pinned questions** across 5 strata; promotion gated on Wilson lower bounds, fail-closed — it blocked a real release this morning, which is the feature working |
|
|
311
|
-
| **Token cost** | 6,183 bytes injected per hook turn · zero self-measurement | **684 bytes (~90% cut)** with an eval-PASS proving zero quality loss · a live token meter measuring real bytes/tokens per prompt class · ~27% faster repeat queries via the KB cache |
|
|
312
|
-
| **rUv's gists** | not indexed | **444 gists** indexed with per-chunk freshness/provenance banners, refreshed nightly with cost-disciplined skip |
|
|
313
|
-
| **Reliability** | claims were prose | **claims ledger** (6 marketing claims mechanically re-verified in CI) · integration tests in CI incl. Linux · a Windows CI job · an honest coverage denominator (all source files) |
|
|
314
|
-
| **Autonomy** | hooks asked questions to an empty room — the #1 real-user complaint | **`/loop` contract** — checkpoint / resume / done-criteria; hooks detect autonomous mode and stop asking — 10 mutation-verified tests |
|
|
315
|
-
| **Publishing** | manual npm token · a nightly release PATH bug | **self-renewing npm token** (launchd daemon, proven end-to-end) · PATH bug root-caused and cured |
|
|
316
|
-
| **Memory layer** | silent SQLite corruption · searches returning 0 · invisible flywheel patterns | **3 root-caused fixes** (an ABI-mismatched binary falling back to WAL-blind whole-file overwrites; keys that were never scored; a split-store display bug) — plus **6 exact patches queued upstream to ruflo** |
|
|
317
|
-
|
|
318
|
-
The depth jump wasn't tuning — it was two pipeline root-causes fixed for good: missing `--full` hints, and a day-one `v2/` skip-dir bug that had made two repos undepthable since the first build.
|
|
319
|
-
|
|
320
|
-
### The scorecard — 8 dimensions, self-scored /100, every deduction evidenced — 2026-07-10 (evening re-score)
|
|
321
|
-
|
|
322
|
-
| Dimension | v1 (2026-07-09) | v2.0 (2026-07-10) | Δ | What moved it |
|
|
323
|
-
|---|---:|---:|---:|---|
|
|
324
|
-
| End-user experience | 54 | 83 | +29 | One-command install now offers nightly self-updates (default yes); the page lives on isovision.ai; publishing renews itself |
|
|
325
|
-
| Knowledge corpus | 71 | 88 | +17 | 24→69 verified repos; an embeds-and-reads QA gate; full source depth restored — flagship went 0→2,996 source bodies |
|
|
326
|
-
| Effectiveness (eval-proven retrieval) | 58 | 88 | +30 | 120-question Wilson-bound gate — it blocked a bad release, then passed the fix *above* the old baseline |
|
|
327
|
-
| Acting like rUv | 38 | 72 | +34 | Memory layer root-caused and fixed with proofs; 6 exact patches queued upstream; real multi-agent swarm operations |
|
|
328
|
-
| Developer smarter | 62 | 84 | +22 | `/brain-score` runs this same scorecard on any repo; honest tool announcements; per-answer source receipts |
|
|
329
|
-
| Token cost efficiency | 41 | 82 | +41 | ~90% smaller per-turn injection, eval-proven free; a live token meter — measured, not guessed |
|
|
330
|
-
| Engineering reliability | 61 | 86 | +25 | 312 tests green; a claims ledger re-verifies marketing claims in CI; fail-closed publishing; Windows CI added |
|
|
331
|
-
| Safety & privacy | 74 | 82 | +8 | Private-store fence held under full rebuild; secrets never transit chat; autonomy hard fence |
|
|
332
|
-
| **Overall** | **55** | **83** | **+28** | — |
|
|
333
|
-
|
|
334
|
-
These are self-scores under a hard rule: **every deduction requires specific evidence, and a known architectural flaw caps a dimension at ≤70 until the flaw is fixed** — *acting like rUv* spent the morning capped for its memory-layer flaw; the flaw was root-caused and fixed with proofs, the cap lifted, and it re-scored 72. Overall **55 → 83 in two days**, each number regenerating from a stored receipt — and the same scoring that produced these blocked a release mid-day. **That's why they're credible: scores you can trust beat scores that flatter.**
|
|
335
|
-
|
|
336
|
-
</details>
|
|
337
|
-
|
|
338
|
-
**The honest small print, kept visible:** warm query is ~21 s on the large corpus (it grew with depth; candidate dedup/pruning is the next optimization) · the 8 newest repos are findable by name but don't yet have primers/capability cards for described-need routing (coming) · the Windows CI job is new and unproven until its first green run.
|
|
339
|
-
|
|
340
|
-
---
|
|
341
|
-
|
|
342
|
-
## The one thing to understand first
|
|
343
|
-
|
|
344
|
-
**Reuven Cohen (rUv) builds about nine months ahead of the state of the art.** His RuvNet building blocks — Ruflo, RuVector, AgentDB, agentic-flow, SPARC and ~20 more — are the working prototypes of what becomes mainstream AI tooling three quarters later. This is the actual front edge.
|
|
345
|
-
|
|
346
|
-
But **Claude was trained on _classical_ software development.** Point it at rUv's stack and it doesn't recognize the work: it drifts, it _doubts real capabilities_ (“ruflo can't edit files,” “RuvNet has no vector DB — use Pinecone”), and it quietly falls back to the patterns it knows (pgvector, LangChain, a hand-rolled cosine loop). A newcomer gets the **worst of both worlds** — a revolutionary toolset with no instruction manual, _and_ an assistant that talks them out of using it.
|
|
347
|
-
|
|
348
|
-
> **RuvNet Brain is the missing instruction manual.** It reads rUv's real source, hands Claude the _answer key_, and removes Claude's permission to make things up about the stack. Install it once, aim it at any repo, and a newcomer can build ~9 months ahead — without being rUv.
|
|
349
|
-
|
|
350
|
-
The novelty is **structural grounding, not plain retrieval.** Plain RAG only decides what to _add_ to context. This ships a `UserPromptSubmit` hook that injects a grounding directive on **every** RuvNet-relevant turn — the harness consumes that stdout structurally, so the directive is _always present_, not a decline-able suggestion. It's a **strong, always-on nudge** — Claude is pointed at the real source and told to ground before asserting on every relevant turn — not a hard block on the model's output. (That describes the *grounding* hook. Separately, a few `PreToolUse` gates **can** block a call — opt-in (model-router profile), repo-scoped, or path-scoped to the brain's own consent switch — and all fail open; [SECURITY.md](SECURITY.md#what-runs-automatically-and-when) lists every hook and whether it can block you.) **RAG decides what to add; this makes grounding the default the model has to actively argue its way out of.**
|
|
351
|
-
|
|
352
|
-
---
|
|
353
|
-
|
|
354
|
-
## The problem it solves
|
|
355
|
-
|
|
356
|
-
You know the failure mode. You ask Claude to build with Ruflo or RuVector, and instead of reading rUv's actual code it reaches for its training priors: _“let's just use pgvector,” “I'll hand-roll cosine similarity,” “I don't think ruflo can edit files.”_ It skims, it guesses, it doubts tools that work perfectly well — and the result drifts **off** the very stack you chose.
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
<details><summary>ASCII version (for AI / accessibility)</summary>
|
|
361
|
-
|
|
362
|
-
```
|
|
363
|
-
WITHOUT the brain — drift | WITH RuvNet Brain — grounded
|
|
364
|
-
|
|
|
365
|
-
You: build with Ruflo/RuVector | You: the same request
|
|
366
|
-
| | |
|
|
367
|
-
v | v
|
|
368
|
-
Claude falls back to priors | Enforcement hook grounds the turn
|
|
369
|
-
| | |
|
|
370
|
-
v | v
|
|
371
|
-
"just use pgvector" | search_ruvnet -> cited rUv source
|
|
372
|
-
hand-rolls cosine similarity | (whole files, labeled repo + path)
|
|
373
|
-
"ruflo can't edit files" | |
|
|
374
|
-
| | v
|
|
375
|
-
v | Builds ON the stack (RVF/HNSW, swarms)
|
|
376
|
-
Drifts OFF the stack |
|
|
67
|
+
```bash
|
|
68
|
+
npx ruvnet-brain@latest
|
|
377
69
|
```
|
|
378
70
|
|
|
379
|
-
|
|
71
|
+
The installer downloads the signed public knowledge bundle, installs its local reader and
|
|
72
|
+
configures the supported hosts it detects. The default Brain home is
|
|
73
|
+
`~/.cache/ruvnet-brain`; the knowledge bundle lives in its `kb/` directory. Follow the
|
|
74
|
+
installer's host/trust instructions and restart when it reports changed plugin declarations.
|
|
380
75
|
|
|
381
|
-
|
|
76
|
+
Local knowledge retrieval does not require an external embedding API or its API key.
|
|
77
|
+
Installation and updates download dependencies and release artifacts; your coding host and
|
|
78
|
+
any optional model providers retain their own account and billing requirements.
|
|
382
79
|
|
|
383
|
-
|
|
80
|
+
**Then ask your assistant:**
|
|
384
81
|
|
|
385
|
-
```
|
|
386
|
-
|
|
82
|
+
```text
|
|
83
|
+
How does Ruflo coordinate agents? Show the source that implements it.
|
|
387
84
|
```
|
|
388
85
|
|
|
389
|
-
|
|
86
|
+
Open the Console in Claude Code or Codex with **`/rnbc`** (also **`/rnb`**). It opens a local
|
|
87
|
+
page and scans your environment. Actions explain their effect before you apply them.
|
|
390
88
|
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
> **Anonymous usage counts — opt-in, counts only.** At the end of the install you're asked once: _"Share anonymous usage counts (installs/searches — never your queries or code)?"_ If you say yes, the only things ever transmitted are event counts (`install` / `search` / `session`) plus the bundle version — batched to at most one ping per machine per day. **Never** your queries, code, repo names, or paths; the entire client is one readable file (`kb/telemetry-ping.mjs`). Your answer is a plain-text file you can read or flip any time (`~/.cache/ruvnet-brain/.telemetry-consent`), and `npx ruvnet-brain --no-telemetry` declines without being asked. Found it useful? [Star the repo](https://github.com/stuinfla/ruvnet-brain) or [leave feedback in Discussions](https://github.com/stuinfla/ruvnet-brain/discussions).
|
|
394
|
-
|
|
395
|
-
<details><summary>Manual install (what the one-liner automates)</summary>
|
|
89
|
+
For an installed command, inspect the actual installation:
|
|
396
90
|
|
|
397
91
|
```bash
|
|
398
|
-
|
|
399
|
-
claude plugin install ruvnet-brain@ruvnet-brain --scope user
|
|
92
|
+
ruvnet-brain --doctor
|
|
400
93
|
```
|
|
401
94
|
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
</details>
|
|
406
|
-
</details>
|
|
407
|
-
</details>
|
|
408
|
-
</details>
|
|
409
|
-
</details>
|
|
410
|
-
|
|
411
|
-
**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.
|
|
95
|
+
If you used the one-shot installer and have no `ruvnet-brain` command on your PATH, use
|
|
96
|
+
`npx ruvnet-brain@latest --doctor`. Keep routine updates on the installation's existing owner
|
|
97
|
+
and path; see [stay current](#stay-current).
|
|
412
98
|
|
|
413
|
-
|
|
99
|
+
> The installer and local search support macOS, Linux and Windows. Hook delivery and optional
|
|
100
|
+
> executors depend on the host, OS and installed tools. Use `--doctor` and actual task receipts
|
|
101
|
+
> to inspect your environment; a registered hook or tool alone does not establish delivery.
|
|
414
102
|
|
|
415
|
-
|
|
103
|
+
## Try it on your next task
|
|
416
104
|
|
|
417
|
-
|
|
105
|
+
You do not need to know the repository names first. Start with a concrete need:
|
|
418
106
|
|
|
419
|
-
|
|
107
|
+
- **Find a building block:** “I need persistent memory for my agents. Which RuvNet options
|
|
108
|
+
fit, and where are their APIs implemented?”
|
|
109
|
+
- **Understand a mechanism:** “Show me how RVF stores and queries vectors. Cite the source,
|
|
110
|
+
and separate working implementation from design documents.”
|
|
111
|
+
- **Plan with evidence:** “Compare the RuvNet approaches for routing model calls. Explain
|
|
112
|
+
the tradeoffs before recommending one.”
|
|
113
|
+
- **Improve a codebase:** “Review this project's agent workflow. Identify a useful capability
|
|
114
|
+
we already have, then propose the smallest change and how we would verify it.”
|
|
115
|
+
- **Build with a bounded request:** “Use `/brain-build` to add a read-only report to this app,
|
|
116
|
+
keep existing data intact, and verify the rendered result.”
|
|
117
|
+
- **Resume work:** “Come up to speed on this project: what changed, what is still open,
|
|
118
|
+
and which decisions have source or test evidence?”
|
|
420
119
|
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
`🧠 RuvNet Brain jumped in · guidance only, no source read · v3.4.18-dev`
|
|
426
|
-
An unearned citation is worse than no citation, so the line may only name a path the tools genuinely returned — and on a prompt where nothing fires, it stays silent rather than manufacture a receipt. The version shown is the one **actually loaded in memory** for this session; if a newer one is staged awaiting a restart, the line says so plainly (`… vX staged, restart to load`). So you never have to wonder whether the brain is on, which version is acting, or whether an answer was grounded or guessed.
|
|
427
|
-
|
|
428
|
-
- **Public production and consumer scheduling are separate.** Only the protected release workflow may publish the immutable product generation. A consumer nightly update does not rebuild upstream sources, bump the product version, or publish a release. The retired primary-checkout LaunchAgent is not a supported producer. The complete native producer/consumer freshness proof remains open under [ADR-072](docs/adr/0072-whole-product-integrity-conformance.md); registration and downloaded timestamps are not substitutes for that evidence.
|
|
429
|
-
|
|
430
|
-
---
|
|
431
|
-
|
|
432
|
-
## ✨ What the knowledge bundle knows — the stack _down to the code_
|
|
433
|
-
|
|
434
|
-
Earlier bundles knew only the **docs and architecture**. v0.5 began re-indexing the code-rich repos to **full function bodies**, against each repo's real source layout — so “how is this actually implemented?” returns the implementation, not a summary. The table below is that v0.5 depth jump, kept as the before/after receipt; **2.0 went further still** — flagship `ruvector` alone now carries 28,018 passages and 2,996 full bodies (see the "what 2.0 proved" foldout near the top):
|
|
435
|
-
|
|
436
|
-
| Repo | Full-body code passages (v0.5) | |
|
|
437
|
-
|---|---:|---|
|
|
438
|
-
| `agentic-flow` | 296 → **984** | model-routing, ReasoningBank |
|
|
439
|
-
| `ruv-fann` | 52 → **779** | ruv-swarm, cuda-wasm, neuro-divergent |
|
|
440
|
-
| `qudag` | → **531** | post-quantum crypto core, exchange, MCP |
|
|
441
|
-
| `daa` | → **266** | orchestrator, economy, rules, swarm |
|
|
442
|
-
| `safla` | 0 → **136** | the metacognitive / self-modification layer |
|
|
443
|
-
|
|
444
|
-
Plus: the **“take the wheel” behavioral pipeline** (below), a **4-level behavioral test harness**, a build-integrity fix (empty files no longer pollute the index), and the private-store fence that keeps unpublished repos out of the public bundle.
|
|
445
|
-
|
|
446
|
-
---
|
|
120
|
+
These are starting prompts, not promises of a particular result. Ask the assistant to cite
|
|
121
|
+
what it read, say which tools executed, and name any missing prerequisite. Optional routing
|
|
122
|
+
requires available, authorized executors; recommendations do not automatically install tools
|
|
123
|
+
or authorize spending.
|
|
447
124
|
|
|
448
125
|
## How it works
|
|
449
126
|
|
|
450
|
-
|
|
127
|
+
Brain separates **building the knowledge**, **retrieving evidence**, and **acting on it**.
|
|
128
|
+
Public source is indexed into local RVF stores. At query time, the reader combines routing
|
|
129
|
+
and retrieval lanes, reranks candidates and returns source evidence through MCP. The coding
|
|
130
|
+
host uses that evidence while its own tools perform the work.
|
|
451
131
|
|
|
452
|
-
|
|
453
133
|
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
134
|
+
<details>
|
|
135
|
+
<summary>ASCII Version (for AI/accessibility)</summary>
|
|
136
|
+
|
|
137
|
+
```text
|
|
138
|
+
PUBLIC KNOWLEDGE YOUR LOCAL WORKFLOW
|
|
139
|
+
RuvNet source + docs Your task in Claude Code / Codex
|
|
140
|
+
| |
|
|
141
|
+
v v
|
|
142
|
+
Index source + symbols Skills + lifecycle guidance
|
|
143
|
+
| |
|
|
144
|
+
v v
|
|
145
|
+
Signed public bundle ---------------> search_ruvnet (MCP)
|
|
146
|
+
Local RVF stores + source passages Route -> retrieve -> rerank
|
|
147
|
+
|
|
|
148
|
+
v
|
|
149
|
+
Source evidence: repo + path
|
|
150
|
+
|
|
|
151
|
+
v
|
|
152
|
+
Host tools / authorized executors
|
|
153
|
+
|
|
|
154
|
+
v
|
|
155
|
+
Changes + checks + receipts
|
|
156
|
+
Eligible project memory (AgentDB)
|
|
157
|
+
```
|
|
457
158
|
|
|
458
|
-
|
|
159
|
+
</details>
|
|
459
160
|
|
|
460
|
-
|
|
161
|
+
The reader uses per-repository knowledge, capability cards, lexical and vector retrieval,
|
|
162
|
+
and a shared cross-encoder ranking lane. It labels evidence and checks implementation
|
|
163
|
+
requirements for queries that ask for code. A capability card helps find a product;
|
|
164
|
+
it does not by itself prove an implementation exists.
|
|
461
165
|
|
|
462
|
-
|
|
166
|
+
The public bundle contains RVF knowledge stores and source-passage sidecars. Project history
|
|
167
|
+
is separate: eligible capture and recall use the project's canonical AgentDB store, including
|
|
168
|
+
worktree resolution. Consent and failure reporting apply at those boundaries.
|
|
463
169
|
|
|
464
|
-
|
|
170
|
+
**Source:** [retrieval implementation](kb/forge-ask-all.mjs),
|
|
171
|
+
[MCP server](plugin/mcp/server.mjs), [Claude hooks](plugin/hooks/hooks.json),
|
|
172
|
+
[Codex hooks](plugin/hooks/codex-hooks.json).
|
|
465
173
|
|
|
466
|
-
|
|
174
|
+
## What Brain brings to your workflow
|
|
467
175
|
|
|
468
|
-
|
|
176
|
+
**Discover capabilities.** Ask about a need in plain language and get a starting point in the
|
|
177
|
+
RuvNet ecosystem. Source-grounded advocacy aims to surface relevant capabilities early,
|
|
178
|
+
with a reason they fit your task.
|
|
469
179
|
|
|
470
|
-
|
|
180
|
+
**Read implementation.** Search results can include code bodies and source documents, with
|
|
181
|
+
repository/path labels and evidence metadata. Evidence class matters: a design proposal and
|
|
182
|
+
an implementation answer carry different weight.
|
|
471
183
|
|
|
472
|
-
|
|
184
|
+
**Guide work across hosts.** The plugins share grounding and workflow skills while native
|
|
185
|
+
hook adapters account for Claude Code and Codex differences. `/brain-prompt` helps refine a
|
|
186
|
+
rough idea; `/brain-build` supplies a structured build contract. Configured routing can hand
|
|
187
|
+
bounded work to supported native executors and record the choice. Routing registration is
|
|
188
|
+
separate from observing a worker execute.
|
|
473
189
|
|
|
474
|
-
|
|
190
|
+
**Retain useful project context.** Where an eligible project store and consent permit it,
|
|
191
|
+
lifecycle capture records bounded, redacted observations and outcomes. Recall brings project
|
|
192
|
+
facts and lessons back as evidence. Pending writes and incomplete restoration stay visible;
|
|
193
|
+
inferred lessons do not silently become authoritative user instructions.
|
|
475
194
|
|
|
476
|
-
|
|
195
|
+
**Inspect and maintain your environment.** RNBC shows installed components and supported
|
|
196
|
+
settings. The coordinated updater uses one policy and shared owner lock for manual and
|
|
197
|
+
scheduled runs, preserving existing managers and install paths.
|
|
477
198
|
|
|
478
|
-
|
|
199
|
+
**Make proof part of the conversation.** Doctor, grounding receipts, update receipts and
|
|
200
|
+
release gates distinguish a configured capability from an observed result. They help you
|
|
201
|
+
identify the next check rather than infer success from a green registration line.
|
|
479
202
|
|
|
480
|
-
|
|
203
|
+
### Explore the ecosystem through Brain
|
|
481
204
|
|
|
482
|
-
|
|
205
|
+
Ask about **Ruflo** for coordination, **RuVector / RVF** for vector knowledge,
|
|
206
|
+
**AgentDB** for agent memory, **agentic-flow** for agent/model workflows,
|
|
207
|
+
**Agentic QE** for quality engineering, or **SPARC** for a structured development method.
|
|
208
|
+
Then deepen the answer with “show the implementation and prerequisites.” The bundle covers
|
|
209
|
+
many more public repositories; its release census and source metadata define its coverage.
|
|
483
210
|
|
|
484
|
-
|
|
211
|
+
## From a question to reviewable work
|
|
485
212
|
|
|
486
|
-
|
|
487
214
|
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
|
496
|
-
|
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
215
|
+
<details>
|
|
216
|
+
<summary>ASCII Version (for AI/accessibility)</summary>
|
|
217
|
+
|
|
218
|
+
```text
|
|
219
|
+
ASK DISCOVER READ ACT VERIFY
|
|
220
|
+
Your need -> Relevant -> Source -> Authorized -> Actual result
|
|
221
|
+
capability + limits host tools + limitations
|
|
222
|
+
^ |
|
|
223
|
+
| v
|
|
224
|
+
Next task <---------------- Project evidence
|
|
225
|
+
eligible memory
|
|
226
|
+
```
|
|
500
227
|
|
|
501
|
-
>
|
|
228
|
+
</details>
|
|
502
229
|
|
|
503
|
-
|
|
230
|
+
Start with the problem. Check the recommendation against its source. Make the change within
|
|
231
|
+
the requested scope. Inspect the actual result, then retain useful evidence for the next task.
|
|
232
|
+
The same sequence works for an explanation, a small repair or a larger delegated build.
|
|
504
233
|
|
|
505
|
-
##
|
|
234
|
+
## Stay current
|
|
506
235
|
|
|
507
|
-
|
|
236
|
+
**4.6.0 introduces coordinated installed-tool updates.** Open RNBC and choose
|
|
237
|
+
**Keep all tools updated**, with **Latest (recommended)** or **Alpha**. The default scope is
|
|
238
|
+
the installed RuvNet suite; broader developer-tool maintenance is an explicit choice.
|
|
239
|
+
Manual and scheduled runs share the coordinator, saved policy and owner lock.
|
|
240
|
+
The schedule is **03:30 in your local time**.
|
|
508
241
|
|
|
509
242
|
```bash
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
node plugin/test/run-tests.mjs # full plugin QA over real JSON-RPC
|
|
243
|
+
ruvnet-brain-update --check
|
|
244
|
+
ruvnet-brain-update --apply
|
|
513
245
|
```
|
|
514
246
|
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
247
|
+
Inspect the run receipt for what changed, failed or was excluded. A saved preference or a
|
|
248
|
+
registered schedule establishes configuration; a completed run establishes its outcome.
|
|
249
|
+
For an existing Brain installation, `ruvnet-brain --update` uses the update path.
|
|
250
|
+
`ruvnet-brain --disable-nightly` disables its scheduled updates.
|
|
251
|
+
|
|
252
|
+
**Code version and knowledge freshness are separate.** A code release can package the last
|
|
253
|
+
published corpus without having refreshed every upstream repository. Public corpus production
|
|
254
|
+
uses the protected release workflow; a consumer update downloads an available generation and
|
|
255
|
+
does not rebuild upstream knowledge. Check `--doctor`, `SOURCE.json` and refresh receipts
|
|
256
|
+
before treating an installation as current.
|
|
257
|
+
|
|
258
|
+
The **4.6.0 published-corpus baseline** is **199 public stores · 162,680 public source chunks**.
|
|
259
|
+
Those are bundle census values, not a claim that every upstream repository is fresh today.
|
|
260
|
+
Later corpus publication may advance the knowledge generation independently of code changes.
|
|
261
|
+
|
|
262
|
+
See [4.6.1 release notes](docs/RELEASE-NOTES-4.6.1.md) and
|
|
263
|
+
[4.6.0 coordinated-update notes](docs/RELEASE-NOTES-4.6.0.md) and the authoritative
|
|
264
|
+
[update and release policy](CONTRIBUTING.md).
|
|
265
|
+
|
|
266
|
+
## Evidence and honest limits
|
|
267
|
+
|
|
268
|
+
Brain supplies mechanisms and evidence; every claim has a boundary:
|
|
269
|
+
|
|
270
|
+
- **Grounding guides the assistant.** Hooks and skills encourage source reads. Selected tool
|
|
271
|
+
boundaries can refuse a call, but they do not guarantee the model always obeys, writes
|
|
272
|
+
correct code or chooses the best design.
|
|
273
|
+
- **Retrieval has a snapshot boundary.** Check dates and upstream source when currency matters.
|
|
274
|
+
Coverage is limited to the indexed public material; the private-store fence excludes
|
|
275
|
+
designated private stores from public bundles.
|
|
276
|
+
- **Local search and model execution have different costs.** The reader runs locally;
|
|
277
|
+
your host and optional provider calls may be metered. Brain does not claim automatic model
|
|
278
|
+
switching or savings from merely registering a route.
|
|
279
|
+
- **Memory has consent and delivery boundaries.** Queued capture is not committed history.
|
|
280
|
+
Native delivery, exact readback and restoration require their own evidence.
|
|
281
|
+
- **Publication is separate from source preparation.** The protected workflow binds a release
|
|
282
|
+
to its artifact and public installation checks. A README edit, local test or passing subset
|
|
283
|
+
does not establish a published release.
|
|
529
284
|
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
### The eval flywheel
|
|
533
|
-
|
|
534
|
-
Most of the numbers above were tuned against. [`evals/held-out.json`](evals/held-out.json) was not: **120 frozen, hash-pinned questions across 5 strata** (named, described, scenario, adversarial, provenance), phrased the way a newcomer would ask, each with the owning repo chosen **from first principles before the brain ever saw them**. `npm run eval` scores, among other things, two claims — both without asking a model's opinion:
|
|
285
|
+
<details>
|
|
286
|
+
<summary>Recorded coverage baseline and how it is checked</summary>
|
|
535
287
|
|
|
536
|
-
|
|
537
|
-
- **routed** — the citation came from a repo that actually owns the capability.
|
|
288
|
+
[-b58900?style=flat-square)](scripts/claims-verify.mjs)
|
|
538
289
|
|
|
539
|
-
|
|
290
|
+
This retained badge is a recorded baseline, not a new measurement from this documentation
|
|
291
|
+
revision. `npm run test:cov` creates the coverage artifact; `npm run claims:verify` checks the
|
|
292
|
+
advertised number against the source-bound artifact. A new release must rederive its claims.
|
|
293
|
+
Historical routing percentages and test totals are deliberately absent from this overview:
|
|
294
|
+
their original runs do not establish the current candidate's behavior.
|
|
540
295
|
|
|
541
|
-
|
|
296
|
+
</details>
|
|
542
297
|
|
|
543
|
-
|
|
298
|
+
## For contributors
|
|
544
299
|
|
|
545
|
-
|
|
300
|
+
The repository uses Node.js ESM. Start with [CONTRIBUTING.md](CONTRIBUTING.md), which owns
|
|
301
|
+
release, versioning, corpus and hook policies. Install checkout dependencies and run the
|
|
302
|
+
relevant checks:
|
|
546
303
|
|
|
547
304
|
```bash
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
305
|
+
npm ci
|
|
306
|
+
npm test
|
|
307
|
+
npm run single-source:check
|
|
308
|
+
npm run wired:check
|
|
551
309
|
```
|
|
552
310
|
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
## Honest status
|
|
558
|
-
|
|
559
|
-
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:
|
|
560
|
-
|
|
561
|
-
- ✅ **The grounding brain is real and proven** — 199 public stores · 162,680 public source chunks, dual embeddings, cross-encoder rerank, plugin (MCP tool + explicit skills; automatic hooks retired), all re-runnable.
|
|
562
|
-
- ✅ **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).
|
|
563
|
-
- ✅ **Routing holds** — named 47/48, described 26/28, scenario 7/8; behavioral L1–L3 all pass (**L4 downgraded — it measures that the brain spoke, not that anything listened**); private stores fenced out of the public bundle (zero-leak verified).
|
|
564
|
-
- ⚠️ **Two routing residuals** (above) — surfaced, not hidden.
|
|
565
|
-
- ✅ **Published on npm** — `npx ruvnet-brain` (short form); `npx github:stuinfla/ruvnet-brain` always tracks the latest commit if you want it even fresher.
|
|
566
|
-
- ✅ **Every automatic hook is documented** — [SECURITY.md](SECURITY.md#what-runs-automatically-and-when) lists each one, what it reads, and whether it can block a turn. Most are advisory; the gates that *can* block are opt-in (model-router profile) or scoped to this repo, and all fail open.
|
|
567
|
-
- ⏳ **The fully-autonomous engineering loop** ([ADR-0008](docs/adr/)) — the behavioral hook injects the loop CONTRACT (assess → SPARC → ADR/DDD → QA → score); the fully-autonomous loop is ADR-0008's open work.
|
|
568
|
-
|
|
569
|
-
---
|
|
570
|
-
|
|
571
|
-
## What's in the box
|
|
572
|
-
|
|
573
|
-
- `kb/` — the brain: per-repo `.rvf` + `.big.rvf` stores, full-passage sidecars, symbol indexes, per-repo primers, the concepts store, and the `forge-*` query tools (CLI + MCP `search_ruvnet`).
|
|
574
|
-
- `plugin/` — the Claude Code plugin (MCP server, grounding skill, `UserPromptSubmit` enforcement hook, marketplace manifest, test suite).
|
|
575
|
-
- `scripts/` — `gate.sh` (routing gate), `behavioral-l1-l4.mjs` (behavioral harness), `prove.mjs`, `build-bundle.mjs`, `brain-stamp.mjs`.
|
|
576
|
-
- `docs/` — [`VISION.md`](docs/VISION.md) (the why), [`adr/`](docs/adr/) (locked decisions incl. ADR-0008), [`DDD.md`](docs/DDD.md).
|
|
577
|
-
- `explainer/` — the source of the [live explainer](https://isovision.ai/ruvnet-brain/).
|
|
578
|
-
- `SPEC.md` · `PROGRESS.md` — the master spec and the living, timestamped build log.
|
|
579
|
-
|
|
580
|
-
The brain binaries ship via the [Release](https://github.com/stuinfla/ruvnet-brain/releases/latest), not git — a fresh clone is lightweight; `npx` fetches the full bundle.
|
|
581
|
-
|
|
582
|
-
---
|
|
583
|
-
|
|
584
|
-
## Community
|
|
311
|
+
Source and integration qualification are defined by `npm run release:qualify`; use the
|
|
312
|
+
current procedure and unique report paths in CONTRIBUTING. Claims, packed-artifact checks,
|
|
313
|
+
public installation and native-host evidence remain separate gates.
|
|
585
314
|
|
|
586
|
-
|
|
587
|
-
- **Questions, ideas, show-and-tell:** [Discussions](https://github.com/stuinfla/ruvnet-brain/discussions) · bugs go to [issues](https://github.com/stuinfla/ruvnet-brain/issues) — new issues and PRs page the maintainer's phone in real time, so first response is typically within 1 business day.
|
|
588
|
-
- **Contributors get credited:** merged PRs land in [`CONTRIBUTORS.md`](CONTRIBUTORS.md) — the two-signal hook gate and the `/brain-build` contract both started as user field reports. House rules: [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md); build/test map: [`CONTRIBUTING.md`](CONTRIBUTING.md).
|
|
315
|
+
Useful places to read:
|
|
589
316
|
|
|
590
|
-
|
|
317
|
+
- [`plugin/`](plugin/) — native plugins, skills, lifecycle hooks and MCP shell.
|
|
318
|
+
- [`kb/`](kb/) — retrieval implementation and knowledge tooling.
|
|
319
|
+
- [`scripts/`](scripts/) — install, update, console and release checks.
|
|
320
|
+
- [`docs/adr/`](docs/adr/) — architecture decisions and their acceptance limits.
|
|
321
|
+
- [`SECURITY.md`](SECURITY.md) — security boundaries and reporting.
|
|
322
|
+
- [`explainer/`](explainer/) — source for the public visual walkthrough. The companion page
|
|
323
|
+
is introductory; current implementation and policy are documented in this repository.
|
|
591
324
|
|
|
592
|
-
##
|
|
325
|
+
## Community and license
|
|
593
326
|
|
|
594
|
-
-
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
- **Built by:** [Stuart Kerr — Isovision.ai](https://isovision.ai)
|
|
327
|
+
Have a concrete example that helped, or a source-grounded failure we can reproduce?
|
|
328
|
+
Open an [issue](https://github.com/stuinfla/ruvnet-brain/issues) or join
|
|
329
|
+
[Discussions](https://github.com/stuinfla/ruvnet-brain/discussions).
|
|
598
330
|
|
|
599
|
-
|
|
331
|
+
RuvNet Brain is **MIT licensed**. See [LICENSE](LICENSE).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "ruvnet-brain",
|
|
3
|
-
"version": "4.6.
|
|
3
|
+
"version": "4.6.1",
|
|
4
4
|
"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.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "ruvnet-brain",
|
|
3
3
|
"description": "RuvNet brain transplant for Claude Code — grounds every RuvNet decision in real source across 77 rUv repositories, prefers Ruflo / RuVector-RVF / AgentDB over training-prior defaults (pgvector, Pinecone, hand-rolled cosine), and can pull in any RuvNet repo on demand. Ships a UserPromptSubmit retrieve-and-inject grounding hook and a PreToolUse write gate that refuses ungrounded rUv-product code until search_ruvnet has been consulted (ADR-0012 / ADR-067).",
|
|
4
|
-
"version": "4.6.
|
|
4
|
+
"version": "4.6.1",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "Stuart Kerr"
|
|
7
7
|
},
|
|
@@ -1,6 +1,11 @@
|
|
|
1
1
|
// Reviewed stabilization release boundaries. Legacy tests remain developer diagnostics.
|
|
2
2
|
export const RELEASE_REQUIREMENTS = Object.freeze({
|
|
3
3
|
"source": [
|
|
4
|
+
{
|
|
5
|
+
"id": "public-admin-release-and-engineering-status",
|
|
6
|
+
"reason": "Latest code release stays separate from corpus identity; issue and pull-request pagination preserves the complete engineering queue and failed probes remain unknown without inventing owner action",
|
|
7
|
+
"files": ["tests/unit/explainer-api.test.mjs", "tests/unit/admin-render.test.mjs"]
|
|
8
|
+
},
|
|
4
9
|
{
|
|
5
10
|
"id": "source-bound-installed-update-coordinator",
|
|
6
11
|
"reason": "Allowed channels and immutable Claude artifact paths reject downgrades, ambiguous registry records, changed bytes, extra active resources and escape paths; Console success requires the exact launched source closure. POSIX owner fixtures additionally enforce original-prefix installs, existing-tool-only policy, shared locks and source-bound scheduler receipts",
|