ruvnet-brain 4.2.2-dev → 4.3.1-dev

package/README.md

@@ -4,7 +4,7 @@
 
 # 🧠 RuvNet Brain
 
-### 🧠 RuvNet Brain — [![RuvNet Brain version 4.2.2-dev — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.2.2--dev-updated_2026--07--30_03:24_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 4.3.1-dev — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.3.1--dev-updated_2026--07--30_03:24_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.**
 
@@ -30,12 +30,12 @@
 [![explainer](https://img.shields.io/badge/▶%20see%20it%20live-isovision.ai%2Fruvnet--brain-e8a13a?style=flat-square)](https://isovision.ai/ruvnet-brain/)
 [![license](https://img.shields.io/badge/license-MIT-8ecae6?style=flat-square)](LICENSE)
 [![grounded](https://img.shields.io/badge/answers-cited%20rUv%20source-333?style=flat-square)](#testing--proof)
-[![coverage](https://img.shields.io/badge/coverage-36%25%20of%20ALL%20source%20·%20honest-b58900?style=flat-square)](#testing--proof)
+[![coverage](https://img.shields.io/badge/coverage-41%25%20of%20ALL%20source%20·%20honest-b58900?style=flat-square)](#testing--proof)
 
 > **One Brain generation everywhere.** npm, the GitHub tag/release, bundle manifests, source metadata, and checksum-bound RVF generations must share the same product version. Headline claims are regenerated and checked by the claims ledger (`scripts/claims-verify.mjs`); other numbers below are hand-stamped and dated:
 > - **`plugin`** (badge above) — the Claude Code plugin itself: SKILL.md, the grounding hooks, the MCP server. Read live from [`plugin/.claude-plugin/plugin.json`](plugin/.claude-plugin/plugin.json). Updates often — this is where behavior fixes land.
 > - **`installer (npm)`** (badge above) — the `npx ruvnet-brain` setup script. Read live from the [npm registry](https://www.npmjs.com/package/ruvnet-brain). Only moves when the installer script itself changes — rare.
-> - **Brain Release** (the downloadable knowledge bundle, linked from the "download" badge above) — always resolves to [`releases/latest`](https://github.com/stuinfla/ruvnet-brain/releases/latest) (the nightly publishes fresh bundles as the corpus grows). Only moves when the underlying knowledge base is rebuilt — separate again from the two above.
+> - **Brain Release** (the downloadable knowledge bundle, linked from the "download" badge above) — always resolves to [`releases/latest`](https://github.com/stuinfla/ruvnet-brain/releases/latest). It moves only when the protected exact-SHA release workflow accepts rebuilt knowledge bytes — separate again from the two above.
 > - **On an old version? One line makes you current — and, with `--auto`, keeps you current forever:**
 >   ```
 >   npx ruvnet-brain@latest --update --auto
@@ -56,16 +56,17 @@
 
 ---
 
-## What's new in 4.2 — it loads what rUv ships, without being asked
+## What's new in 4.3 — it loads what rUv ships, without being asked
 
-**The corpus stopped drifting behind the org.** Until 4.2 nothing ever ingested a new repo: the
-nightly refreshed lessons, health and proofs and contained *zero* ingestion, so a repo entered the
-brain only when a human typed the command. `brain-stamp.mjs` had been measuring that gap every
-night, but nothing consumed it until the ingestion loop shipped.
+**The corpus gained an explicit new-repository ingestion path.** Until 4.2 nothing ingested a new
+repo. `brain-stamp.mjs` measured the gap, but nothing consumed it until
+`scripts/ingest-new-repos.mjs` shipped. Its mutating mode is now deliberately human-run from a clean
+linked worktree; the former primary-checkout scheduler was retired rather than allowed to trade
+corpus freshness for uncontrolled source changes.
 
-- **187 stores, up from 69.** Everything rUv ships that has content, pulled in and kept level by
-  `scripts/ingest-new-repos.mjs` running nightly, newest-first. Empty repos (`size=0KB`) are skipped
-  rather than retried forever — a permanent nightly failure that is actually correct behaviour
+- **187 stores, up from 69.** Content-bearing rUv repositories can be pulled newest-first through
+  `scripts/ingest-new-repos.mjs`. Empty repos (`size=0KB`) are skipped
+  rather than retried forever — a permanent repeated failure that is actually correct behaviour
   trains you to ignore the failure line, which is how a real one would hide inside it.
 - **174 capability cards, up from 39.** Ingesting a repo is not the same as making it reachable: a
   store with no card is *dark* — valid bytes no by-description query can find. Cards are written
@@ -79,7 +80,7 @@ night, but nothing consumed it until the ingestion loop shipped.
   agentdb's binding, so `lesson-bridge --apply` and `learning-replay` wrote into a silent
   non-persistent fallback. It now resolves an ABI-matched interpreter and fails loudly instead.
 
-## What's new in 4.2 — it anticipates, and it learns whether it was right
+## What's new in 4.3 — 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
@@ -412,7 +413,7 @@ You install once. After that, three mechanisms keep you on the current brain wit
   `🧠 RuvNet Brain jumped in · guidance only, no source read · v3.4.18-dev`
   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.
 
-- **Nightly publish → `releases/latest` chain** (`scripts/self-update.mjs --publish`, run by the `deploy/com.ruvnet.brain-nightly.plist` LaunchAgent at 03:15). The nightly rebuilds only the repos whose upstream changed, and **if anything was rebuilt** it bumps the product version, cuts a GitHub Release, and advances [`releases/latest`](https://github.com/stuinfla/ruvnet-brain/releases/latest). Plugin and knowledge bundle move under **one** version number, so the heartbeat above picks up both automatically. The exact author-vs-end-user schedules, incremental algorithm, failure behavior, and hosting recommendation are documented in [Nightly refresh and publish](docs/NIGHTLY-REFRESH.md). (The LaunchAgent is not auto-installed — enabling a system scheduler needs explicit owner approval.)
+- **Separated overnight paths.** The Dream Machine runs evidence-only evaluation with `autoMerge:false`; the optional `com.ruvnet.brain-update` LaunchAgent updates one installed cache from an already-published bundle. The former `com.ruvnet.brain-nightly` source writer was retired on 2026-08-22 because it accumulated generated changes in the primary developer checkout. Author rebuilds are now explicit, clean linked-worktree operations; `self-update.mjs --publish` is refused and only the protected exact-SHA workflow may release. See [Nightly refresh, evaluation, and author rebuilds](docs/NIGHTLY-REFRESH.md).
 
 ---
 
@@ -508,7 +509,7 @@ node plugin/test/run-tests.mjs                    # full plugin QA over real JSO
 | **L4 "orchestrate"** | **downgraded — measures speech, not obedience** | L4 asserts the hook's own injected prose contains required words (`must: ['take the wheel','SPARC','swarm',…]`). That proves **the brain spoke**. It cannot fail when the advice is read and ignored — which is the failure this product exists to prevent. Counterfactual replay against a brain-off control (ADR-058 §D4) is what will earn this row back |
 | **Plugin QA** | **60 / 60** | manifests, hook firing, MCP `initialize`/`tools/list`, capability battery |
 | **Clean-room install** | **3 / 3** | download the published bundle fresh → unzip → query → grounded, cited answers |
-| **Unit tests** | **3,035 passing, 161 todo** · 36% of ALL source covered | `npm run test:cov` regenerates both — the coverage floor fails CI if it slips (`claims:verify` re-derives the %, it is not a hand-typed badge). 36% is the honest number over every shipped file; the previous "75%" measured a hand-picked 8-file subset |
+| **Unit tests** | **3,035 passing, 161 todo** · 41% of ALL source covered | `npm run test:cov` regenerates both — the coverage floor fails CI if it slips (`claims:verify` re-derives the %, it is not a hand-typed badge). 41% is the honest number over every shipped file; the previous "75%" measured a hand-picked 8-file subset |
 | **Grounding proof** | `npx ruvnet-brain --doctor` | asks a real question, then checks the cited path really exists in the on-disk store; a citation that doesn't resolve is reported as **NOT grounded** |
 | **Held-out eval** | **grounded 100/100** · routed 63/80 | `npm run eval` — 120 frozen, hash-pinned questions across 5 strata, never used for tuning, graded on ground truth, never by a model |
 

package/bin/install.mjs

@@ -2594,9 +2594,18 @@ export function installCronEntry(line, { run = spawnSync } = {}) {
   return { ok: true, already: false };
 }
 
-/** launchd's own minimal PATH, plus the directory node/npx actually live in on this machine. */
+/**
+ * launchd's minimal PATH plus the user-level executable homes used by the supported hosts.
+ *
+ * The updater does more than run npx: --host-sync-only executes the installed Claude and Codex
+ * doors. A real 2026-08-22 launchd run found npx but then failed with `claude unavailable` and
+ * `spawnSync codex ENOENT`; interactive shells had supplied ~/.npm-global/bin and ~/.local/bin,
+ * launchd had not. Derive these from HOME so the fix is portable rather than pinned to one user.
+ */
 const launchdPath = () => [...new Set([
   path.dirname(process.execPath), path.dirname(npxPath()),
+  path.join(os.homedir(), '.npm-global', 'bin'), path.join(os.homedir(), '.local', 'bin'),
+  ...(process.platform === 'darwin' ? ['/Applications/Codex.app/Contents/Resources'] : []),
   '/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin', '/usr/sbin', '/sbin',
 ])].filter(Boolean).join(':');
 const cronExample = (kbDir) =>
@@ -2897,7 +2906,7 @@ function enableNightly() {
   <key>Label</key>
   <string>${NIGHTLY_LABEL}</string>
   <!-- Issue #129: the SAME host-convergent entrypoint the session updater runs, not the KB-only
-       forge-update.mjs it used to schedule. See NIGHTLY_ARGV. Still no `/bin/sh -c` (ADR-038) —
+       forge-update.mjs it used to schedule. See NIGHTLY_ARGV. Still no shell wrapper (ADR-038) —
        this execs npx directly. -->
   <key>ProgramArguments</key>
   <array>

package/console/architecture.html

@@ -979,33 +979,31 @@ RUVNET_BRAIN_METER=0              # stop the measuring (editing hooks.json stops
     </div>
   </details>
 
-  <!-- 8 · NIGHTLY -->
+  <!-- 8 · EVERGREEN + DREAM -->
   <details class="card rail-prove">
     <summary>
       <span class="card-ic ic-prove" aria-hidden="true">
         <svg viewBox="0 0 24 24"><circle cx="12" cy="12" r="8.5"/><polyline points="12 6.8 12 12 15.6 14"/></svg>
       </span>
       <span class="card-head">
-        <h2>8 · The nightly refresh</h2>
-        <span class="q">Rebuilds the corpus so it does not rot. The only piece that installs a scheduled job.</span>
+        <h2>8 · Evergreen + Dream evaluation</h2>
+        <span class="q">Updates installed bytes and evaluates changes without writing the primary checkout.</span>
       </span>
       <span class="chips"><span class="chip tone-opt">optional</span><span class="chip tone-cost">changes your machine</span></span>
       <span class="chev" aria-hidden="true">›</span>
     </summary>
     <div class="body">
       <dl class="beat">
-        <dt>What</dt><dd>A scheduled job that rebuilds the corpus from upstream.</dd>
-        <dt>Gives</dt><dd>A corpus that does not go stale. rUv ships fast — one of his tools went from 3.26 to 3.28 inside an 18-hour window.</dd>
-        <dt>Costs</dt><dd>A launchd plist: a <b>real machine mutation</b>, which is why the installer asks for it behind its own flag and a blanket "yes to everything" cannot silently accept it. Hours of CPU on rebuild nights. Network.</dd>
+        <dt>What</dt><dd>An optional installed-cache updater plus a non-merging Dream Machine evaluation cycle.</dd>
+        <dt>Gives</dt><dd>Fresh published bytes on installed hosts and evidence-backed improvement proposals without unattended source writes.</dd>
+        <dt>Costs</dt><dd>A launchd plist for Evergreen is a <b>real machine mutation</b>, which is why the installer asks for it behind its own flag. Author rebuild CPU and disk are spent only after an explicit clean linked-worktree run.</dd>
         <dt class="lose">Lose</dt><dd class="lose">Freshness, degrading continuously — but <b>visibly</b>. The staleness line on every search response prints the real age of the stores it queried, so you can always see how bad it has become. You can also refresh by hand at any time.</dd>
       </dl>
-      <div class="why"><b>Its operating discipline: no noise for success or a no-op.</b> Run once → on
-      failure wait and retry <i>once</i> (the only class a blind retry can fix) → on a second failure, a
-      loud alert <i>plus</i> a durable marker file that the session-start hook surfaces unprompted at
-      the top of the very next session. A single-instance lock guards against a rebuild that can run for
-      hours (verified: 2 h 29 m and still embedding) still being alive when the next night's run fires.
-      A reserved exit code marks "skipped, previous run still going" so a skip is never recorded as a
-      failure — <b>silence is never allowed to mean health</b>.</div>
+      <div class="why"><b>The primary checkout is not an automation workspace.</b> The former
+      <code>com.ruvnet.brain-nightly</code> source writer was retired after it accumulated generated
+      changes beside active work. Author rebuilds now refuse primary, nested, non-linked, and dirty
+      worktrees and verify afterward that primary HEAD, index, tracked files, and untracked-file set
+      did not change. Dream evaluation cannot merge; Evergreen updates the installed cache only.</div>
     </div>
   </details>
 
@@ -1171,7 +1169,7 @@ RUVNET_BRAIN_METER=0              # stop the measuring (editing hooks.json stops
         <tr><td class="cell-name">…/health.json</td><td>brain alarm</td><td>last known retrieval health</td></tr>
         <tr><td class="cell-name">…/console-undo.jsonl</td><td>console apply</td><td>the inverse of every change, journalled <i>first</i></td></tr>
         <tr><td class="cell-name">~/.config/ruvnet-brain/lessons.json</td><td>you, ratifying</td><td>your corrections</td></tr>
-        <tr><td class="cell-name">launchd plists</td><td><b>only if you say yes</b></td><td>the nightly refresh and friends</td></tr>
+        <tr><td class="cell-name">launchd plists</td><td><b>only if you say yes</b></td><td>installed-cache updates and other explicitly enabled jobs</td></tr>
       </tbody>
     </table>
   </div>

package/console/install-mockup.html

@@ -431,14 +431,14 @@ main { padding: 1.4rem 0 3rem; }
           <h3 class="row-title">Keep it auto-updated (Evergreen)</h3>
           <span class="badge badge-rec">Recommended · default on</span>
         </div>
-        <p class="row-desc">Installs a macOS LaunchAgent (<code>com.ruvnet.brain-nightly</code>) that updates the brain at 03:47 every night.</p>
+        <p class="row-desc">Installs a macOS LaunchAgent (<code>com.ruvnet.brain-update</code>) that updates the installed brain at 03:47 every night.</p>
         <p class="row-impl"><b>Uncheck this and:</b> updates become manual forever (<code>npx ruvnet-brain --update</code>) — rUv ships fast, and a stale brain is the single biggest way this stops being useful.</p>
         <p class="row-ev">bin/install.mjs:1802&ndash;1868 (offerNightly), plist :1202&ndash;1291 · default-on parsing :1703&ndash;1706</p>
         <p class="row-undo">Undo anytime: <code>npx ruvnet-brain --disable-nightly</code> / <code>--enable-nightly</code></p>
 
         <div class="proof" id="proof-4">
           <span class="proof-pill" id="proof-4-pill">&#10003; verified running</span>
-          <span class="proof-detail" id="proof-4-detail">launchctl confirms <code style="background:none;border:0;padding:0;color:inherit;">com.ruvnet.brain-nightly</code> is scheduled &middot; last run: not yet &mdash; first run tonight at 03:47.</span>
+          <span class="proof-detail" id="proof-4-detail">launchctl confirms <code style="background:none;border:0;padding:0;color:inherit;">com.ruvnet.brain-update</code> is scheduled &middot; last run: not yet &mdash; first run tonight at 03:47.</span>
           <span class="proof-caption">Shown here as it will appear once installed. The checkbox alone never earns this pill — only a live <code style="background:none;border:0;padding:0;color:inherit;">launchctl</code> check does, reusing the same detector <code style="background:none;border:0;padding:0;color:inherit;">capability-registry.mjs</code>'s nightly-refresh row already runs (:754&ndash;800), so the installer and the Console can never disagree about whether it's really on.</span>
         </div>
       </div>
@@ -528,7 +528,7 @@ main { padding: 1.4rem 0 3rem; }
           if (input.checked) {
             proof.classList.remove('is-off');
             pill.innerHTML = '&#10003; verified running';
-            detail.innerHTML = 'launchctl confirms <code style="background:none;border:0;padding:0;color:inherit;">com.ruvnet.brain-nightly</code> is scheduled &middot; last run: not yet &mdash; first run tonight at 03:47.';
+            detail.innerHTML = 'launchctl confirms <code style="background:none;border:0;padding:0;color:inherit;">com.ruvnet.brain-update</code> is scheduled &middot; last run: not yet &mdash; first run tonight at 03:47.';
           } else {
             proof.classList.add('is-off');
             pill.textContent = 'off';

package/kb/zip-extract.mjs

@@ -186,7 +186,7 @@ function safeJoin(destDir, name) {
 
 /**
  * Extract `zipPath` into `destDir`, overwriting existing files (idempotent — the `-o` of
- * `unzip -q -o`). Returns { entries, files, bytes, crcChecked }.
+ * `unzip -q -o`). Returns { entries, entryNames, files, bytes, crcChecked }.
  * Throws an Error naming the archive and the offending entry on ANY problem.
  */
 export async function extractZip(zipPath, destDir) {
@@ -322,7 +322,13 @@ export async function extractZip(zipPath, destDir) {
       files++;
       bytes += tally.bytes;
     }
-    return { entries: entries.length, files, bytes, crcChecked: Boolean(crc32) };
+    return {
+      entries: entries.length,
+      entryNames: entries.map((entry) => entry.name),
+      files,
+      bytes,
+      crcChecked: Boolean(crc32),
+    };
   } catch (err) {
     // Always name the archive: "extraction failed" without the file is the message this whole
     // change exists to stop shipping.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.2.2-dev",
+  "version": "4.3.1-dev",
   "description": "One-command installer for RuvNet Brain — a portable, source-grounded brain over rUv's RuvNet building blocks, delivered as a Claude Code plugin so Claude uses the stack instead of fighting it.",
   "type": "module",
   "bin": {
@@ -21,6 +21,7 @@
     "test:regression": "vitest run tests/regression",
     "qe:ux": "node scripts/qe/ux-suite.mjs",
     "test:cov": "vitest run tests/unit --coverage",
+    "test:release:preflight": "vitest run tests/unit/public-verification-inputs.test.mjs",
     "test:all": "npm run test:unit && npm run test:mesh && npm run test:mutation && npm run test:regression && npm run test:integration && npm test",
     "metaharness:receipts": "node scripts/metaharness-receipts.mjs",
     "route:cheap": "node scripts/route-cheap.mjs",
@@ -34,6 +35,9 @@
     "eval:top100": "node scripts/top100-benchmark.mjs",
     "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",
+    "gists:rebuild-receipts": "node scripts/rebuild-gists-from-receipts.mjs",
+    "cards:from-source": "node scripts/card-from-source.mjs",
+    "release:abort-stale": "node scripts/release-abort-stale.mjs",
     "test:integration": "vitest run tests/integration",
     "substitution:check": "node scripts/no-silent-substitution.mjs",
     "catalog:verify": "node scripts/verify-model-catalog.mjs",
@@ -47,6 +51,8 @@
     "learning:replay:dry": "node scripts/learning-replay.mjs --dry-run",
     "wired:check": "node scripts/wired-check.mjs --check",
     "doc:currency": "node scripts/doc-currency.mjs --check",
+    "integrity:trace:check": "node scripts/product-integrity-contract.mjs --check-markdown docs/reviews/adr-072-traceability.md",
+    "integrity:trace:json": "node scripts/product-integrity-contract.mjs",
     "status:check": "node scripts/status-honesty.mjs",
     "cap:collect": "node scripts/rerank-cap-eval.mjs --collect",
     "cap:report": "node scripts/rerank-cap-eval.mjs --report",

package/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ruvnet-brain",
   "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 an enforced UserPromptSubmit retrieve-and-inject grounding hook that sharply reduces drift.",
-  "version": "4.2.2-dev",
+  "version": "4.3.1-dev",
   "author": {
     "name": "Stuart Kerr"
   },

package/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.2.2-dev",
+  "version": "4.3.1-dev",
   "description": "Source-grounded RuvNet knowledge, lifecycle enforcement, and learning for Codex.",
   "author": {
     "name": "Stuart Kerr"

package/plugin/hooks/codex-hooks.json

@@ -3,7 +3,7 @@
   "hooks": {
     "SessionStart": [
       {
-        "matcher": "startup|resume|clear|compact",
+        "matcher": "startup|resume|clear|compact|fork",
         "hooks": [
           {
             "type": "command",

package/plugin/hooks/hooks.json

@@ -21,6 +21,16 @@
             "timeout": 5
           }
         ]
+      },
+      {
+        "matcher": "clear|compact|fork",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" session-start || true",
+            "timeout": 5
+          }
+        ]
       }
     ],
     "PreCompact": [

package/plugin/host-adapters/claude.json

@@ -0,0 +1,11 @@
+{
+  "schemaVersion": 1,
+  "kind": "ruvnet-brain-host-adapter",
+  "id": "claude",
+  "displayName": "Claude Code",
+  "os": ["linux", "macos", "windows"],
+  "modes": ["claude", "dual"],
+  "manifest": "plugin/.claude-plugin/plugin.json",
+  "hooks": "plugin/hooks/hooks.json",
+  "loader": "bin/install.mjs"
+}

package/plugin/host-adapters/codex.json

@@ -0,0 +1,11 @@
+{
+  "schemaVersion": 1,
+  "kind": "ruvnet-brain-host-adapter",
+  "id": "codex",
+  "displayName": "Codex",
+  "os": ["linux", "macos", "windows"],
+  "modes": ["codex", "dual"],
+  "manifest": "plugin/.codex-plugin/plugin.json",
+  "hooks": "plugin/hooks/codex-hooks.json",
+  "loader": "bin/install.mjs"
+}

package/plugin/mcp/managed-cli-interface.mjs

@@ -3,6 +3,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { loadRuntimePreferences, runtimeChildEnv } from '../scripts/runtime-preferences.mjs';
+import { recordManagedCliObservation, recordRegistryLatestObservation } from '../scripts/capability-claim-evidence.mjs';
 
 export const MANAGED_EXECUTABLES = Object.freeze([
   'ruflo',
@@ -15,6 +16,15 @@ export const MANAGED_EXECUTABLES = Object.freeze([
 ]);
 
 const MANAGED = new Set(MANAGED_EXECUTABLES);
+const REGISTRY_PACKAGES = Object.freeze({
+  ruflo: 'ruflo',
+  'claude-flow': '@claude-flow/cli',
+  'agentic-flow': 'agentic-flow',
+  'agentic-qe': 'agentic-qe',
+  ruvector: 'ruvector',
+  'agent-browser': 'agent-browser',
+  'ruv-swarm': 'ruv-swarm',
+});
 const SUBCOMMAND = /^[a-z][a-z0-9-]*$/;
 const MAX_ARGS = 256;
 const MAX_ARG_BYTES = 8192;
@@ -29,6 +39,17 @@ const executableSchema = {
 };
 
 export const MANAGED_CLI_TOOLS = Object.freeze([
+  {
+    name: 'ruvnet_registry_latest',
+    description: 'Read the exact npm registry latest version for a managed RuvNet executable and record a content-bound public-registry receipt.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: { executable: executableSchema },
+      required: ['executable'],
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+  },
   {
     name: 'ruvnet_cli_help',
     description: 'Read a managed CLI interface from the executable itself. Runs only the supplied subcommand path plus --help and records a fresh stamp only after exit 0.',
@@ -146,20 +167,43 @@ function writeStamps(executable, argv, env) {
 export function resolveManagedExecutable(executable, env = process.env) {
   if (executable !== 'ruflo') return executable;
   const home = env.HOME || os.homedir();
-  const canonical = path.join(home, '.npm-global', 'bin', 'ruflo');
-  try {
-    fs.accessSync(canonical, fs.constants.X_OK);
-    return canonical;
-  } catch {
-    return executable;
+  const candidates = [path.join(home, '.npm-global', 'bin', 'ruflo')];
+  if (process.platform === 'win32') candidates.push(`${candidates[0]}.cmd`);
+  return candidates.find((candidate) => {
+    try { fs.accessSync(candidate, fs.constants.X_OK); return true; } catch { return false; }
+  }) || executable;
+}
+
+function quoteWindowsCommandArg(value) {
+  // cmd.exe is required for npm's .cmd shims. Keep the child_process call itself shell:false,
+  // and quote every literal token so shell metacharacters remain data rather than syntax.
+  // Delayed expansion is disabled by default; doubling percent signs prevents environment
+  // expansion while cmd parses the /c command line.
+  return `"${value.replace(/%/g, '%%').replace(/"/g, '""')}"`;
+}
+
+function spawnSpec(executable, argv, env) {
+  const resolved = resolveManagedExecutable(executable, env);
+  if (process.platform !== 'win32' || !resolved.toLowerCase().endsWith('.cmd')) {
+    return { file: resolved, args: argv, windowsVerbatimArguments: false };
   }
+  // `/s /c` removes the first and last quote characters from its command string. The outer
+  // envelope therefore preserves the inner quotes around a shim path containing spaces.
+  const command = `"${[resolved, ...argv].map(quoteWindowsCommandArg).join(' ')}"`;
+  return {
+    file: env.ComSpec || env.COMSPEC || 'cmd.exe',
+    args: ['/d', '/s', '/c', command],
+    windowsVerbatimArguments: true,
+  };
 }
 
 function execute(executable, argv, env) {
   return new Promise((resolve) => {
-    const child = spawn(resolveManagedExecutable(executable, env), argv, {
+    const spec = spawnSpec(executable, argv, env);
+    const child = spawn(spec.file, spec.args, {
       env,
       shell: false,
+      windowsVerbatimArguments: spec.windowsVerbatimArguments,
       stdio: ['ignore', 'pipe', 'pipe'],
     });
     const stdout = [];
@@ -213,16 +257,37 @@ function resultOf(executable, argv, result) {
   };
 }
 
-export async function callManagedCli(toolName, args, env = process.env) {
+export async function callManagedCli(toolName, args, env = process.env, fetchImpl = globalThis.fetch) {
   try {
     const executable = assertExecutable(args?.executable);
-    const argv = literalArgv(args?.argv);
+    const argv = literalArgv(args?.argv ?? []);
+
+    if (toolName === 'ruvnet_registry_latest') {
+      const packageName = REGISTRY_PACKAGES[executable];
+      const registryUrl = `https://registry.npmjs.org/${packageName.replace('/', '%2F')}/latest`;
+      const response = await fetchImpl(registryUrl, {
+        headers: { accept: 'application/json' },
+        signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS),
+      });
+      const body = await response.text();
+      if (!response.ok) throw new Error(`registry latest lookup failed with HTTP ${response.status}`);
+      let metadata;
+      try { metadata = JSON.parse(body); } catch { throw new Error('registry latest response was not JSON'); }
+      const receipt = recordRegistryLatestObservation({
+        executable, packageName, version: metadata?.version, registryUrl, responseBody: body, env,
+      });
+      return {
+        content: [{ type: 'text', text: `${packageName} latest version: ${receipt.observedVersion} (registry receipt ${receipt.receiptSha256})` }],
+        isError: false,
+      };
+    }
 
     if (toolName === 'ruvnet_cli_help') {
       stampKeysForHelp(executable, argv);
       const commandArgv = [...argv, '--help'];
       const execution = await execute(executable, commandArgv, env);
       if (execution.code === 0 && !execution.error) writeStamps(executable, argv, env);
+      recordManagedCliObservation({ toolName, executable, argv: commandArgv, execution, env });
       return resultOf(executable, commandArgv, execution);
     }
 
@@ -263,7 +328,9 @@ export async function callManagedCli(toolName, args, env = process.env) {
       const childEnv = (executable === 'agentic-flow' || executable === 'agentic-qe')
         ? runtimeChildEnv({ env, cwd: env.RUVNET_BRAIN_PROJECT_DIR || process.cwd() })
         : env;
-      return resultOf(executable, argv, await execute(executable, argv, childEnv));
+      const execution = await execute(executable, argv, childEnv);
+      recordManagedCliObservation({ toolName, executable, argv, execution, env });
+      return resultOf(executable, argv, execution);
     }
 
     return {

package/plugin/mcp/server.mjs

@@ -327,7 +327,8 @@ async function handleClient(msg) {
       return clientOk(id, { tools: FALLBACK_TOOLS });
     }
     case 'tools/call': {
-      if (params?.name === 'ruvnet_cli_help' || params?.name === 'ruvnet_cli_run') {
+      if (params?.name === 'ruvnet_cli_help' || params?.name === 'ruvnet_cli_run'
+        || params?.name === 'ruvnet_registry_latest') {
         return clientOk(id, await callManagedCli(params.name, params.arguments || {}));
       }
       if (params?.name !== 'search_ruvnet') return clientErr(id, -32602, `unknown tool: ${params?.name}`);

package/plugin/scripts/anticipate.sh

@@ -195,6 +195,7 @@ import { pathToFileURL } from 'node:url';
 const MODE = process.env.RUVNET_ANTICIPATE_MODE || 'suggest';
 const ARG = process.env.RUVNET_ANTICIPATE_ARG || '';
 const SELF = process.env.RUVNET_ANTICIPATE_SELF || 'anticipate.sh';
+const SELF_DIR = path.dirname(SELF);
 
 // CANDIDATE MODE (ADR-040 / DDD-0004 "the enforcement chokepoint"). Set by unprompted-runtime.mjs on
 // every producer child. When on, this hook writes ZERO user-facing prose: it emits ONE advocacy
@@ -414,13 +415,18 @@ const sessions = st.sessions && typeof st.sessions === 'object' ? st.sessions :
 const said = new Set(strings(sessions[sid]?.said));
 if (said.size >= MAX_PER_SESSION) quit();
 
-let auditAll, matchGoal, floor;
+let auditAll, matchGoal, floor, buildCapabilityRoutingReceipt, hasToolPreference;
 try { ({ auditAll } = await import(pathToFileURL(process.env.RUVNET_CAPABILITY_REGISTRY).href)); } catch { quit(); }
 try {
   const gm = await import(pathToFileURL(process.env.RUVNET_GOAL_MATCH).href);
   matchGoal = gm.matchGoal;
   floor = gm.CONFIDENCE_FLOOR;
 } catch { quit(); }
+try {
+  const routingPath = process.env.RUVNET_CAPABILITY_ROUTING_MODULE
+    || path.join(SELF_DIR, 'capability-routing.mjs');
+  ({ buildCapabilityRoutingReceipt, hasToolPreference } = await import(pathToFileURL(routingPath).href));
+} catch { /* older packed hosts predate the optional routing receipt */ }
 if (typeof auditAll !== 'function' || typeof matchGoal !== 'function') quit();
 const MIN_CONFIDENCE = typeof floor === 'number' && Number.isFinite(floor) ? floor : FALLBACK_CONFIDENCE_FLOOR;
 
@@ -459,6 +465,28 @@ let matches = [];
 try { matches = matchGoal(prompt, dormant) || []; } catch { quit(); }
 if (!Array.isArray(matches) || !matches.length) quit();
 
+// Only an evidence-bound route to an existing RuvNet building block may leave this hook.
+let routingReceipt;
+try {
+  routingReceipt = typeof buildCapabilityRoutingReceipt === 'function'
+    ? buildCapabilityRoutingReceipt({ prompt, matches, capabilities: rows }) : null;
+  // Test/host adapters may provide synthetic capabilities outside the shipped registry. Preserve
+  // their existing protocol; real RuvNet capabilities are fail-closed when no route receipt exists.
+  const knownRoute = typeof hasToolPreference === 'function' && matches.some((match) => {
+    const key = match?.capability?.key || match?.capability;
+    const liveRow = rows.find((row) => row?.key === key);
+    return hasToolPreference(key) && typeof liveRow?.evidence === 'string' && liveRow.evidence.trim()
+      && typeof liveRow?.evidenceDigest === 'string' && liveRow.evidenceDigest.length === 64;
+  });
+  if (!routingReceipt && knownRoute) quit();
+  if (!routingReceipt) routingReceipt = { receiptSha256: 'synthetic-adapter' };
+  const receiptFile = process.env.RUVNET_CAPABILITY_ROUTING_RECEIPTS;
+  if (receiptFile) {
+    fs.mkdirSync(path.dirname(receiptFile), { recursive: true });
+    fs.appendFileSync(receiptFile, `${JSON.stringify(routingReceipt)}\n`, { mode: 0o600 });
+  }
+} catch { quit(); }
+
 // The matcher is trusted to rank, never to assert existence: every match is re-resolved against the
 // dormant rows THIS audit produced. A capability the matcher names that is not dormant right now is
 // dropped, so a stale or over-eager matcher can only ever cause silence, never a false claim.
@@ -534,6 +562,7 @@ if (EMIT_CANDIDATES) {
     findingId: best.row.key,
     severity: best.row.severity || 'normal',
     observationHash: stateHashOf(best.row.evidence),
+    routingReceiptSha256: routingReceipt.receiptSha256,
   }));
   quit();
 }