ruvnet-brain 4.3.26 → 4.3.27

package/README.md

@@ -7,7 +7,7 @@ Created: 2026-06-29 22:36:38 EDT
 
 # 🧠 RuvNet Brain
 
-### 🧠 RuvNet Brain — [![RuvNet Brain version 4.3.26 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.3.26-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.27 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.3.27-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.**
 
@@ -562,7 +562,7 @@ node forge-ask-all.mjs --dir . --q "How does RuVector implement HNSW vector sear
 
 This project versions in the open (see the live badge up top for the exact plugin version; the downloadable knowledge bundle is a separate track) — we don't claim “done,” “complete,” or “zero hallucinations.” Where it stands:
 
-- ✅ **The grounding brain is real and proven** — 182 public stores · 143,719 public source chunks, dual embeddings, cross-encoder rerank, plugin (MCP tool + explicit skills; automatic hooks retired), all re-runnable.
+- ✅ **The grounding brain is real and proven** — 182 public stores · 143,682 public source chunks, dual embeddings, cross-encoder rerank, plugin (MCP tool + explicit skills; automatic hooks retired), all re-runnable.
 - ✅ **Code-level depth** — the code-rich repos are indexed to full function bodies; “how is it implemented?” returns the implementation. Verified in the shipped bundle (clean-room 3/3).
 - ✅ **Routing holds** — named 47/48, described 26/28, scenario 7/8; behavioral L1–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).
 - ⚠️ **Two routing residuals** (above) — surfaced, not hidden.

package/bin/install.mjs

@@ -30,6 +30,7 @@ import {
 } from '../kb/model-requirements.mjs';
 import { applyManagedCatalogUpdate } from '../scripts/model-router-catalog.mjs';
 import { cmpVersion } from '../scripts/stack-sync.mjs';
+import { inspectInstalledBrain, classifySmokeEvidence, DOCTOR_SMOKE_QUERY, doctorSmokeArgs } from '../scripts/installed-brain-health.mjs';
 import { validateCoverageDirectory } from '../plugin/scripts/coverage-integrity.mjs';
 import {
   continuityContractIds,
@@ -2402,9 +2403,9 @@ async function smokeQuery(cacheDir) {
   if (!fs.existsSync(ask)) return { ran: false };
   step(
     'Asking the brain a real question',
-    'this warms the local model so your first real answer is instant — and proves grounding works end to end',
+    'this warms the local model and checks that retrieval returns usable, cited evidence',
   );
-  const Q = 'How should I store embeddings in this project without running a server?';
+  const Q = DOCTOR_SMOKE_QUERY;
   info(`Q: ${c.cyan(`"${Q}"`)}`);
   info(c.dim('(first run downloads a small local model once — this can take a minute)'));
   const started = Date.now();
@@ -2415,7 +2416,7 @@ async function smokeQuery(cacheDir) {
     // absolute path via spawnSync (no shell involved) that identity check silently fails on this
     // machine, so main() never runs — exit 0, zero stdout, zero stderr, no exception. Looks like a
     // clean success; is actually a total no-op. Verified: switching to a relative name + cwd fixes it.
-    r = spawnSync('node', ['forge-ask-all.mjs', '--dir', cacheDir, '--q', Q, '--k', '3'], {
+    r = spawnSync('node', doctorSmokeArgs(cacheDir), {
       cwd: cacheDir,
       encoding: 'utf8',
       timeout: 240000,
@@ -2476,6 +2477,11 @@ async function smokeQuery(cacheDir) {
   }
 
   const v = await verifier.verifyGrounding(out, cacheDir);
+  const evidence = classifySmokeEvidence(v, out);
+  if (v.grounded && !evidence.usable) {
+    warn(`the citation resolves, but the question was not answered with sufficient evidence (${evidence.reason})`);
+    return { ran: true, grounded: false, citationResolved: true, reason: evidence.reason, secs };
+  }
   if (v.grounded) {
     ok(`grounded in rUv's real source — verified in ${secs}s, not guessed ✦`);
     console.log(`      ${c.dim('cited:')}    ${c.bold(v.receipt.path)}`);
@@ -2693,6 +2699,13 @@ async function doctor() {
   // Two independent version streams (KB bundle vs plugin wrapper) — see checkVersionDrift()'s
   // header comment for the full story. Silent unless they've genuinely diverged.
   reportVersionDrift(cacheDir);
+  const installedIdentity = inspectInstalledBrain(cacheDir, PACKAGE_VERSION);
+  info(`installed identities: package ${installedIdentity.packageVersion || 'unknown'}; search engine ${installedIdentity.searchVersion || 'unknown'}; validator ${installedIdentity.validatorVersion || 'unknown'}`);
+  if (installedIdentity.corpusTag) info(`corpus generation: ${installedIdentity.corpusTag}`);
+  if (!installedIdentity.healthy) {
+    for (const issue of installedIdentity.issues) warn(`installed identity: ${issue}`);
+    info(`Repair the installed generation: ${c.bold('npx ruvnet-brain@latest --update')}`);
+  }
   // Extraction no longer needs an external binary at all — kb/zip-extract.mjs does it with node:zlib
   // (see unzipInto()). So this reports the file's PRESENCE, not a PATH lookup: if it is missing from
   // the install, extraction on Windows silently loses its primary method, which is exactly the class
@@ -2883,6 +2896,8 @@ async function doctor() {
   const codexWiringFailed = Boolean(cx.host && !cx.wired);
   const codexReadinessFailed = Boolean(codexMcp?.blocking);
   const failed = (hookResult ? hookResult.exitCode !== 0 : !allGreen)
+    || !installedIdentity.healthy
+    || smoke.grounded !== true
     || groundingUnprovenPersisted
     || (codexLifecycleFailed && !codexTrustBypassed)
     || codexWiringFailed
@@ -3056,7 +3071,7 @@ function reportVersionDrift(cacheDir) {
   const state = checkVersionDrift(cacheDir);
   if (!state.drift) return state;
   warn(`the brain (${c.bold(state.kb)}) and the Claude Code plugin (${c.bold(state.wrapper)}) have drifted apart —`);
-  info(`that's normal (they update on separate schedules) and neither one is broken. To bring the`);
+  info(`they update on separate schedules; this comparison does not prove either is healthy. To bring the`);
   info(`plugin up to date:  ${c.bold('claude plugin marketplace update ruvnet-brain')}  ${c.dim('(body updates go live without a restart; boot-surface changes are called out)')}`);
   return state;
 }

package/data/model-catalog.json

@@ -4,7 +4,7 @@
     "generated": "2026-07-15",
     "schema_version": 1,
     "sources": {
-      "prices": "OpenRouter /api/v1/models live catalog, pulled 2026-09-04 (in/out USD per Mtok).",
+      "prices": "OpenRouter /api/v1/models live catalog, pulled 2026-09-19 (in/out USD per Mtok).",
       "rankings": "Artificial Analysis Intelligence Index (artificialanalysis.ai) + Arena/LMArena (arena.ai) — the ONLY independent evaluators carrying current-generation models as of 2026-07-15; each figure cross-verified twice.",
       "provenance_rule": "rUv ADR-206: vendor-reported scores are optimistic and harness-confounded — trust independent (AA/Arena) numbers, treat vendor self-scaffold SWE-bench/LiveCodeBench figures as noisy features, never as truth.",
       "benchmark_lag": "The canonical hard coding benchmarks (SWE-bench Verified standardized harness, LiveCodeBench, Aider polyglot) were ALL months stale on 2026-07-15 and carry NONE of these models. The '88.6% / 95% SWE-bench' figures in the press are vendor self-scaffold scores, not the standardized harness — excluded here.",

package/docs/RELEASE-NOTES-4.0.md

@@ -1,6 +1,6 @@
 # RuvNet-Brain 4.0 line — what's new (the major-release highlights)
 
-Updated: 2026-08-01
+Updated: 2026-09-20
 
 > **Source of truth** for the `/whats-new` command and the first-run upgrade message. Curated, honest,
 > major-only — not the point-release churn. If a claim here isn't true of the shipping build, it does not
@@ -19,10 +19,11 @@ it's landing now.
 
 ### Release proof is fail-closed
 The 4.0 release path now separates a clean candidate seal from a post-publication seal. Dirty
-lineage, zero/skipped/todo tests, open issues, red or pending exact-SHA workflows, a missing
+lineage, zero/skipped/todo tests, open `release-blocker` issues, red or pending exact-SHA workflows, a missing
 `ruvnet-brain` self-RVF store, weak query-deadline margin, missing independent graders,
 host/artifact mismatches, and public-byte drift are release failures rather than warnings.
-`npm run release:proof -- --status --quick` shows the current live blockers.
+The local `release:proof --status --quick` command is only a diagnostic and cannot qualify a
+candidate; use the exact-SHA preflight receipt and protected publisher evidence.
 
 ### 1. The Console is the front door
 Type `/rvbc` and your whole RuvNet stack is on one live local page: what's installed, what the AI has

package/kb/capability-only.mjs

@@ -0,0 +1,27 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const isCapabilityOnly = name => String(name).toLowerCase() === 'cognitum-ruos';
+export const CAPABILITY_RETIRED_SUFFIXES = [
+  '-primer.md', '.symbols.json', '.rvf', '.rvf.idmap.json', '.rvf.embed.json', '.big.passages.jsonl', '.big.meta.json',
+];
+
+// Reject historical source-bearing stores at the final packaging boundary, even
+// when their upstream SHA and signed generation receipt are otherwise current.
+export function assertCapabilityOnlyStore(dir, name) {
+  if (!isCapabilityOnly(name)) return;
+  const expected = fs.readFileSync(new URL('./capability-summaries/cognitum-ruos/CAPABILITIES.md', import.meta.url), 'utf8');
+  const rows = fs.readFileSync(path.join(dir, `${name}.passages.jsonl`), 'utf8')
+    .trim().split('\n').map(line => JSON.parse(line));
+  if (rows.length !== 1 || rows[0].path !== 'CAPABILITIES.md' || rows[0].text !== expected) {
+    throw new Error(`${name}: capability-only policy requires the current curated summary, without source passages`);
+  }
+  const meta = JSON.parse(fs.readFileSync(path.join(dir, `${name}.meta.json`), 'utf8'));
+  const entries = Object.values(meta.entries || {});
+  if (entries.length !== 1 || entries[0].path !== 'CAPABILITIES.md' || entries[0].kind !== 'doc') {
+    throw new Error(`${name}: capability-only metadata contains unexpected source paths`);
+  }
+  if (CAPABILITY_RETIRED_SUFFIXES.some(suffix => fs.existsSync(path.join(dir, `${name}${suffix}`)))) {
+    throw new Error(`${name}: capability-only store must not carry a symbol index or legacy source sidecar`);
+  }
+}

package/kb/capability-summaries/cognitum-ruos/CAPABILITIES.md

@@ -0,0 +1,26 @@
+Updated: 2026-09-19 | Version 1.0.0
+Created: 2026-09-19
+
+# Cognitum ruOS capabilities
+
+Cognitum ruOS is an agentic operating system for AI workstations. It is designed
+to observe workstation conditions, reason about what needs attention, and take
+appropriate actions with less manual intervention.
+
+Its documented capabilities include:
+
+- Workstation health monitoring and recovery from service failures.
+- Adapting performance profiles to workload and user context.
+- Local AI assistance and persistent knowledge for workstation tasks.
+- Learning from prior sessions and evaluating knowledge quality.
+- Backup, recovery, and software updates.
+- Voice interaction and optional sensing with user consent.
+- Security checks around AI interactions.
+
+It is relevant when a user wants a workstation that helps maintain itself and
+supports ongoing AI-assisted work. These are documented capabilities, not a claim
+that ruOS is installed, provisioned, or independently benchmarked on this machine.
+
+This Brain entry intentionally covers capabilities and use cases only. Proprietary
+source code, internal architecture, algorithms, configuration, and implementation
+instructions are outside its published knowledge scope.

package/kb/verify-citation.mjs

@@ -42,7 +42,7 @@ import readline from 'node:readline';
 export function parseCitations(stdout) {
   const out = [];
   const text = String(stdout ?? '');
-  const blockRe = /^#(\d+)\s+repo=(\S+)(?:\s+ce=(-?[\d.]+))?(?:\s+vec=(-?[\d.]+))?(?:\s+kind=(\S+))?/gm;
+  const blockRe = /^#(\d+)[ \t]+repo=(\S+)([^\r\n]*)/gm;
   const nextHeaderRe = /^#\d+\s+repo=\S+/gm;
   let m;
   let expectedRank = 1;
@@ -63,15 +63,27 @@ export function parseCitations(stdout) {
     if (!pathM) continue;
     expectedRank = rank + 1;
     const repo = m[2];
+    // Metadata comes only from the header, never from a retrieved document body.
+    // A proof label is descriptive; consumers must independently validate its evidence.
+    const field = (name) => new RegExp(`(?:^|[ \\t])${name}=([^ \\t]+)`).exec(m[3])?.[1] ?? null;
+    const score = (name) => {
+      const value = field(name);
+      return value !== null && /^-?\d+(?:\.\d+)?$/.test(value) ? Number(value) : null;
+    };
     const fullPath = pathM[1].trim();
     // Strip the repo prefix the reader adds, so the remainder can be matched against the store.
     const docPath = fullPath.startsWith(`${repo}/`) ? fullPath.slice(repo.length + 1) : fullPath;
+    // Retain only the reader's bounded document body. Missing/truncated delimiters fail
+    // closed, so evaluators cannot borrow claims from headers, diagnostics, or later hits.
+    const body = /^----- full document -----\r?\n([\s\S]*?)\r?\n={67}(?:\r?\n|$)/m.exec(block);
     out.push({
       rank,
       repo,
-      ce: m[3] !== undefined ? Number(m[3]) : null,
-      vec: m[4] !== undefined ? Number(m[4]) : null,
-      kind: m[5] ?? null,
+      ce: score('ce'),
+      vec: score('vec'),
+      kind: field('kind'),
+      proofMethod: field('proof'),
+      returnedText: body ? body[1] : null,
       fullPath,
       docPath,
       title: titleM ? titleM[1].trim() : null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.3.26",
+  "version": "4.3.27",
   "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": {
@@ -12,6 +12,8 @@
     "release:proof": "node scripts/release-proof.mjs",
     "benchmark:brain50": "node scripts/brain-latency-50.mjs",
     "benchmark:novice50": "node scripts/brain-novice-50.mjs",
+    "benchmark:operational": "node scripts/run-operational-benchmark.v3.mjs",
+    "benchmark:operational:v2": "node scripts/run-operational-benchmark.mjs",
     "version:check": "node scripts/sync-version.mjs --check",
     "version:set": "node scripts/set-version.mjs",
     "qa:pr": "node scripts/qa-runner.mjs",
@@ -94,6 +96,8 @@
     "kb/verify-citation.mjs",
     "kb/retrieval-result.mjs",
     "kb/corpus-release-identity.mjs",
+    "kb/capability-only.mjs",
+    "kb/capability-summaries/",
     "kb/zip-extract.mjs",
     "kb/brain-profile.mjs",
     "kb/lifecycle-evidence-retention.mjs",

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 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).",
-  "version": "4.3.26",
+  "version": "4.3.27",
   "author": {
     "name": "Stuart Kerr"
   },

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

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

package/plugin/docs/RELEASE-NOTES-4.0.md

@@ -1,6 +1,6 @@
 # RuvNet-Brain 4.0 line — what's new (the major-release highlights)
 
-Updated: 2026-08-01
+Updated: 2026-09-20
 
 > **Source of truth** for the `/whats-new` command and the first-run upgrade message. Curated, honest,
 > major-only — not the point-release churn. If a claim here isn't true of the shipping build, it does not
@@ -19,10 +19,11 @@ it's landing now.
 
 ### Release proof is fail-closed
 The 4.0 release path now separates a clean candidate seal from a post-publication seal. Dirty
-lineage, zero/skipped/todo tests, open issues, red or pending exact-SHA workflows, a missing
+lineage, zero/skipped/todo tests, open `release-blocker` issues, red or pending exact-SHA workflows, a missing
 `ruvnet-brain` self-RVF store, weak query-deadline margin, missing independent graders,
 host/artifact mismatches, and public-byte drift are release failures rather than warnings.
-`npm run release:proof -- --status --quick` shows the current live blockers.
+The local `release:proof --status --quick` command is only a diagnostic and cannot qualify a
+candidate; use the exact-SHA preflight receipt and protected publisher evidence.
 
 ### 1. The Console is the front door
 Type `/rvbc` and your whole RuvNet stack is on one live local page: what's installed, what the AI has

package/plugin/hooks/codex-hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "RuvNet Brain continuity plane for Codex. Broad legacy automatic gates remain retired. Registrations here are MEASURED, not assumed: a probe hook was registered on all twelve event names the installed codex-cli 0.154.0 binary declares and a real `codex exec` run was observed (2026-09-11). SessionStart, UserPromptSubmit and SessionEnd FIRED and carry handlers. Stop keeps only the pre-existing, project-scoped continuation gate. PreCompact is DECLARED ABSENT here: the binary declares the event but the probe never observed it, and a capture registered on an unobserved event would look symmetrical while capturing nothing. All handlers are bounded and fail open. Amended 2026-09-11: UserPromptSubmit also runs ground-ruvnet (grounding injection, ADR-040 §Amendment). Amended 2026-09-12: the 2026-09-11 PreToolUse/PostToolUse \"not observed\" note was measured with a prompt (`codex exec \"reply OK\"`) that never invoked a tool, so neither event had anything to fire on — that was an untested path, not a failing one. Re-probed with prompts that actually call a tool: a real apply_patch write fired PreToolUse/PostToolUse with tool_name \"apply_patch\", and a real MCP call to this repo's own search_ruvnet server fired both with tool_name \"mcp__ruvnet_brain__search_ruvnet\". Both are now registered below: decision-gate's write route (matcher includes apply_patch, Codex's raw write-tool name) and grounding-stamp (unchanged matcher already recognizes the mcp__..__search_ruvnet shape). The bash route (exec_command) remains unregistered — today's measurement covered a write and an MCP call, not exec_command, and extending on that evidence would be the same unproven leap this note replaces. Also added 2026-09-12: grounding-turn-mark (UserPromptSubmit) and grounding-turn-gate (Stop), the \"answered without searching\" pair — a prompt-level grounding directive is advisory, so this records whether it fired and forces continuation at Stop if no search_ruvnet call was recorded since (reusing grounding-stamp's own stamp evidence). Both are registered on Codex identically to Claude: the Stop-block contract (hookSpecificOutput.additionalContext) already has a proven Codex translation via codex-hook-adapter.mjs's Stop branch (see tests/unit/codex-lifecycle-hooks.test.mjs), the same path continuation-gate already uses.",
+  "description": "RuvNet Brain continuity plane for Codex. Broad legacy automatic gates remain retired. Registrations here are MEASURED, not assumed: a probe hook was registered on all twelve event names the installed codex-cli 0.154.0 binary declares and a real `codex exec` run was observed (2026-09-11). SessionStart, UserPromptSubmit and SessionEnd FIRED and carry handlers. Stop keeps only the pre-existing, project-scoped continuation gate. PreCompact is DECLARED ABSENT here: the binary declares the event but the probe never observed it, and a capture registered on an unobserved event would look symmetrical while capturing nothing. All handlers are bounded and fail open. Amended 2026-09-11: UserPromptSubmit also runs ground-ruvnet (grounding injection, ADR-040 §Amendment). Amended 2026-09-12: the 2026-09-11 PreToolUse/PostToolUse \"not observed\" note was measured with a prompt (`codex exec \"reply OK\"`) that never invoked a tool, so neither event had anything to fire on — that was an untested path, not a failing one. Re-probed with prompts that actually call a tool: a real apply_patch write fired PreToolUse/PostToolUse with tool_name \"apply_patch\", and a real MCP call to this repo's own search_ruvnet server fired both with tool_name \"mcp__ruvnet_brain__search_ruvnet\". Both are now registered below: decision-gate's write route (matcher includes apply_patch, Codex's raw write-tool name) and grounding-stamp (unchanged matcher already recognizes the mcp__..__search_ruvnet shape). The bash route (exec_command) remains unregistered — today's measurement covered a write and an MCP call, not exec_command, and extending on that evidence would be the same unproven leap this note replaces. Also added 2026-09-12: grounding-turn-mark (UserPromptSubmit) and grounding-turn-gate (Stop), the \"answered without searching\" pair — a prompt-level grounding directive is advisory, so this records whether it fired and forces continuation at Stop if no search_ruvnet call was recorded since (reusing grounding-stamp's own stamp evidence). Both are registered on Codex identically to Claude: the Stop-block contract (hookSpecificOutput.additionalContext) already has a proven Codex translation via codex-hook-adapter.mjs's Stop branch (see tests/unit/codex-lifecycle-hooks.test.mjs), the same path continuation-gate already uses. Capacity-aware parallel-work guidance is also registered at UserPromptSubmit: it advises the coordinator to launch only real independent workers within sampled resource headroom and the live runtime/tool cap; it never spawns workers or claims execution.",
   "hooks": {
     "SessionStart": [
       {
@@ -68,6 +68,11 @@
             "command": "node -e \"const f=require('node:fs'),o=require('node:os'),p=require('node:path'),c=require('node:child_process'),d=process.env.CODEX_HOME||p.join(o.homedir(),'.codex'),b=process.env.RUVNET_BRAIN_HOME||p.join(p.dirname(d),'.cache','ruvnet-brain'),w=p.join(b,'codex-hook.mjs');let s;try{s=f.statSync(w)}catch{}if(!s?.isFile())process.exit(0);const r=c.spawnSync(process.execPath,[w,...process.argv.slice(2)],{stdio:['inherit','pipe','pipe'],encoding:'utf8',env:process.env,timeout:Number(process.argv[1]),killSignal:'SIGKILL'});if(r.status===0||r.status===2){if(r.stdout)process.stdout.write(r.stdout);if(r.stderr)process.stderr.write(r.stderr)}process.exit(r.status===2?2:0)\" 9000 ground-ruvnet",
             "timeout": 10
           },
+          {
+            "type": "command",
+            "command": "node -e \"const f=require('node:fs'),o=require('node:os'),p=require('node:path'),c=require('node:child_process'),d=process.env.CODEX_HOME||p.join(o.homedir(),'.codex'),b=process.env.RUVNET_BRAIN_HOME||p.join(p.dirname(d),'.cache','ruvnet-brain'),w=p.join(b,'codex-hook.mjs');let s;try{s=f.statSync(w)}catch{}if(!s?.isFile())process.exit(0);const r=c.spawnSync(process.execPath,[w,...process.argv.slice(2)],{stdio:['inherit','pipe','pipe'],encoding:'utf8',env:process.env,timeout:Number(process.argv[1]),killSignal:'SIGKILL'});if(r.status===0||r.status===2){if(r.stdout)process.stdout.write(r.stdout);if(r.stderr)process.stderr.write(r.stderr)}process.exit(r.status===2?2:0)\" 1500 capacity-aware-parallel-work",
+            "timeout": 2
+          },
           {
             "type": "command",
             "command": "node -e \"const f=require('node:fs'),o=require('node:os'),p=require('node:path'),c=require('node:child_process'),d=process.env.CODEX_HOME||p.join(o.homedir(),'.codex'),b=process.env.RUVNET_BRAIN_HOME||p.join(p.dirname(d),'.cache','ruvnet-brain'),w=p.join(b,'codex-hook.mjs');let s;try{s=f.statSync(w)}catch{}if(!s?.isFile())process.exit(0);const r=c.spawnSync(process.execPath,[w,...process.argv.slice(2)],{stdio:['inherit','pipe','pipe'],encoding:'utf8',env:process.env,timeout:Number(process.argv[1]),killSignal:'SIGKILL'});if(r.status===0||r.status===2){if(r.stdout)process.stdout.write(r.stdout);if(r.stderr)process.stderr.write(r.stderr)}process.exit(r.status===2?2:0)\" 4500 grounding-turn-mark",

package/plugin/hooks/hook-contracts.json

@@ -1,6 +1,6 @@
 {
-  "_note": "The legacy automatic gate collection remains retired. What is permitted is the continuity plane below and nothing else: SessionStart restores the canonical project checkpoint; UserPromptSubmit runs the single unprompted-speech chokepoint; Stop may nudge one explicitly authorized project-scoped objective AND capture a project snapshot; PreCompact and SessionEnd capture a project snapshot. Version 3 of this file permitted exactly two handlers, which was not a safety property but a contradiction: it demanded a restore while forbidding any event that could WRITE the journal the restore reads, so the canonical store held zero progression rows. Adding to this list is still a deliberate act that must pass `npm run hooks:check`; what changed is that the shape can now express the plane that actually works. Amended 2026-09-11 (Stuart): the continuity-only charter had retired the ONLY enforcement of ADR-0012 — never write rUv-product code the brain has not seen — and the failure it exists to prevent recurred the day it was measured absent. The plane now also carries three grounding registrations: ground-ruvnet (UserPromptSubmit, grounding injection — a second owner of that event, scoped by ADR-040 §Amendment 2026-09-11 to directives rather than speech), decision-gate’s write route (PreToolUse, the one refuser, ADR-067), and grounding-stamp (PostToolUse on a successful search_ruvnet, the receipt that opens the write gate). Amended 2026-09-12: the 2026-09-11 claim that Codex PreToolUse/PostToolUse delivery had never been observed was measured with a prompt that never invoked a tool (`codex exec \"reply OK\"`), so it was an untested path, not a failing one. Re-measured with prompts that actually call a tool (a real apply_patch write, a real MCP search_ruvnet call against this repo's own server): both events FIRED on codex-cli 0.154.0 with real payloads. decision-gate's write route and grounding-stamp are now dual-host (see _codexCapture and contracts below); the bash route (exec_command) remains Claude-only — today's measurement did not exercise it. Also amended 2026-09-12: added grounding-turn-mark (UserPromptSubmit) and grounding-turn-gate (Stop), the \"answered without searching\" pair — ground-ruvnet's Gate 1 directive is advisory, so nothing previously checked whether the model complied before the turn ended. grounding-turn-mark records that Gate 1 fired for a turn; grounding-turn-gate forces continuation at Stop if grounding-stamp's own evidence shows no search_ruvnet call happened since. Both dual-host from the start (the Stop-block contract is already proven on Codex via continuation-gate).",
-  "_version": 7,
+  "_note": "The legacy automatic gate collection remains retired. What is permitted is the continuity plane below and nothing else: SessionStart restores the canonical project checkpoint; UserPromptSubmit runs the single unprompted-speech chokepoint; Stop may nudge one explicitly authorized project-scoped objective AND capture a project snapshot; PreCompact and SessionEnd capture a project snapshot. Version 3 of this file permitted exactly two handlers, which was not a safety property but a contradiction: it demanded a restore while forbidding any event that could WRITE the journal the restore reads, so the canonical store held zero progression rows. Adding to this list is still a deliberate act that must pass `npm run hooks:check`; what changed is that the shape can now express the plane that actually works. Amended 2026-09-11 (Stuart): the continuity-only charter had retired the ONLY enforcement of ADR-0012 — never write rUv-product code the brain has not seen — and the failure it exists to prevent recurred the day it was measured absent. The plane now also carries three grounding registrations: ground-ruvnet (UserPromptSubmit, grounding injection — a second owner of that event, scoped by ADR-040 §Amendment 2026-09-11 to directives rather than speech), decision-gate’s write route (PreToolUse, the one refuser, ADR-067), and grounding-stamp (PostToolUse on a successful search_ruvnet, the receipt that opens the write gate). Amended 2026-09-12: the 2026-09-11 claim that Codex PreToolUse/PostToolUse delivery had never been observed was measured with a prompt that never invoked a tool (`codex exec \"reply OK\"`), so it was an untested path, not a failing one. Re-measured with prompts that actually call a tool (a real apply_patch write, a real MCP search_ruvnet call against this repo's own server): both events FIRED on codex-cli 0.154.0 with real payloads. decision-gate's write route and grounding-stamp are now dual-host (see _codexCapture and contracts below); the bash route (exec_command) remains Claude-only — today's measurement did not exercise it. Also amended 2026-09-12: added grounding-turn-mark (UserPromptSubmit) and grounding-turn-gate (Stop), the \"answered without searching\" pair — ground-ruvnet's Gate 1 directive is advisory, so nothing previously checked whether the model complied before the turn ended. grounding-turn-mark records that Gate 1 fired for a turn; grounding-turn-gate forces continuation at Stop if grounding-stamp's own evidence shows no search_ruvnet call happened since. Both dual-host from the start (the Stop-block contract is already proven on Codex via continuation-gate). Added capacity-aware-parallel-work at UserPromptSubmit on both measured hosts: it is context-only, resource-bounded, and requires the coordinator to check actual tool/runtime slots; it does not spawn or claim workers.",
+  "_version": 8,
   "_eventOwners": [
     {
       "event": "SessionStart",
@@ -70,6 +70,16 @@
       ],
       "responsibility": "Injects a grounding directive into the model’s context when the prompt names the rUv stack, reaches for a classical default, or asks to build: call search_ruvnet before you assert. Not speech — emits no advocacy, promotion, lesson or alarm and reads no dial; silenced by the brain switch (ADR-054); scoped by ADR-040 §Amendment 2026-09-11."
     },
+    {
+      "event": "UserPromptSubmit",
+      "owner": "capacity-aware-parallel-work",
+      "class": "capacity-aware coordination guidance",
+      "hosts": [
+        "claude",
+        "codex"
+      ],
+      "responsibility": "For clearly substantial, independently splittable work, adds context-only guidance based on bounded memory-pressure, swap, compression, and normalized-load signals. It never creates workers, claims they are running, or overrides the coordinator’s live agent-tool/runtime cap; unknown capacity recommends serial execution."
+    },
     {
       "event": "PreToolUse",
       "owner": "decision-gate",
@@ -228,6 +238,18 @@
       "matcher": "*",
       "timeout": 10
     },
+    {
+      "id": "capacity-aware-parallel-work",
+      "event": "UserPromptSubmit",
+      "hosts": [
+        "claude",
+        "codex"
+      ],
+      "mode": "advisory",
+      "offBehavior": "run",
+      "matcher": "*",
+      "timeout": 2
+    },
     {
       "id": "decision-gate",
       "event": "PreToolUse",

package/plugin/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "RuvNet Brain lifecycle plane. The broad legacy routing, learning, and release interceptors remain retired. What is automatic is exactly: SessionStart restores the canonical project checkpoint; UserPromptSubmit runs the single unprompted-speech chokepoint AND the ground-ruvnet grounding injection (a directive to the model, not speech — ADR-040 §Amendment 2026-09-11); PreToolUse runs decision-gate's write route, the ONE process that may refuse a Write/Edit/MultiEdit/NotebookEdit/apply_patch (ADR-067, composing ground-before-write per ADR-0012) — apply_patch is Codex's own write tool name, added 2026-09-12 once a real apply_patch call was measured to fire this event live (codex-hooks.json carries the matching Codex registration; this is a dead branch on Claude, which never names a tool apply_patch); PostToolUse on a successful search_ruvnet mints the grounding stamp that opens that gate; grounding-turn-mark (UserPromptSubmit) records that the grounding directive fired this turn, and grounding-turn-gate (Stop) forces continuation if no search_ruvnet call was recorded since — the \"answered without searching\" gate, added 2026-09-12 (a directive alone is advisory; nothing previously checked whether the model actually complied); Stop also runs the ledger-scoped continuation handler and captures a project snapshot; PreCompact and SessionEnd capture a project snapshot. Every capture is bounded and fails open; only decision-gate may block on exit code, and it fails open on its own errors — grounding-turn-gate and continuation-gate force continuation via the Stop stdout envelope instead, which is advisory in the shim's own mode table but still keeps the agent working.",
+  "description": "RuvNet Brain lifecycle plane. The broad legacy routing, learning, and release interceptors remain retired. What is automatic is exactly: SessionStart restores the canonical project checkpoint; UserPromptSubmit runs the single unprompted-speech chokepoint, ground-ruvnet grounding injection, and a capacity-aware context hint for clearly large independent work. The capacity hook uses bounded CPU/memory-pressure evidence, never starts agents, and tells the coordinator to check live tools and clamp to the runtime cap; it is not user-facing speech. ground-ruvnet remains a directive to the model, not speech — ADR-040 §Amendment 2026-09-11. PreToolUse runs decision-gate's write route, the ONE process that may refuse a Write/Edit/MultiEdit/NotebookEdit/apply_patch (ADR-067, composing ground-before-write per ADR-0012); PostToolUse on a successful search_ruvnet mints the grounding stamp that opens that gate. grounding-turn-mark (UserPromptSubmit) records that the grounding directive fired this turn, and grounding-turn-gate (Stop) forces continuation if no search_ruvnet call was recorded since. Stop also runs the ledger-scoped continuation handler and captures a project snapshot; PreCompact and SessionEnd capture a project snapshot. Every capture is bounded and fails open; only decision-gate may block on exit code, and it fails open on its own errors — the Stop stdout envelopes are advisory at the shim boundary but keep the agent working.",
   "hooks": {
     "SessionStart": [
       {
@@ -27,6 +27,11 @@
             "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" ground-ruvnet || true",
             "timeout": 10
           },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" capacity-aware-parallel-work || true",
+            "timeout": 2
+          },
           {
             "type": "command",
             "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" grounding-turn-mark || true",

package/plugin/scripts/capacity-aware-parallel-work.mjs

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+/**
+ * UserPromptSubmit advisory for substantial work with independent workstreams.
+ *
+ * This hook classifies only the submitted prompt and samples local pressure signals. It NEVER
+ * creates agents or claims that agents are running. The coordinator still has to check the live
+ * agent tools and runtime concurrency ceiling, then spawn real workers and inspect their results.
+ * Missing or malformed input, unavailable probes, and unexpected errors are silent and fail open.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const UNKNOWN_RUNTIME_TOTAL_AGENT_CEILING = 4;
+const INPUT_LIMIT = 32 * 1024;
+const PROBE_TIMEOUT_MS = 450;
+const GIB = 1024 ** 3;
+
+const ACTION = /\b(?:build|implement|refactor|migrate|investigate|audit|review|design|fix|add|remove|optimi[sz]e|plan|execute|ship)\b/i;
+const EXPLICIT_FANOUT = /\b(?:parallel(?:ize|ise)?|swarm|delegate|spawn (?:real )?agents?|independent workstreams?|separate owners?)\b/i;
+const BROAD_SCOPE = /\b(?:cross[- ]cutting|end[- ]to[- ]end|multi[- ]step|large[- ]scale|whole (?:repo|repository|codebase|system)|entire (?:repo|repository|codebase|system)|full (?:repo|repository|codebase|system)|across (?:the )?(?:repo|repository|codebase|system)|multiple (?:modules|files|packages|components|services)|several (?:modules|files|packages|components|services|workstreams))\b/i;
+const TRIVIAL_SCOPE = /\b(?:tiny|trivial|simple|single[- ]line|one[- ]line|small typo|rename (?:one|a|single) variable|format one file|just (?:a )?quick fix)\b/i;
+const COMPONENTS = [
+  /\bapi\b/i, /\bcli\b/i, /\bui\b|\bfront[- ]end\b|\binterface\b/i,
+  /\btests?\b|\bqa\b/i, /\bdocs?\b|\bdocumentation\b/i,
+  /\bdata(?:base| layer| model)?\b|\bschema\b/i, /\bsecurity\b/i,
+  /\binfra(?:structure)?\b|\bdeployment\b/i, /\bhooks?\b/i,
+  /\binstaller\b|\bpackaging\b/i, /\bruntime\b/i,
+];
+
+function estimateWorkUnitCount(prompt) {
+  const componentCount = COMPONENTS.reduce((n, re) => n + Number(re.test(prompt)), 0);
+  if (componentCount >= 2) return componentCount;
+  const numberedItems = [...prompt.matchAll(/(?:^|\n)\s*(?:\d+[.)]|[-*])\s+\S/g)].length;
+  return numberedItems >= 2 ? numberedItems : null;
+}
+
+export function isSubstantialParallelWork(prompt) {
+  const text = typeof prompt === 'string' ? prompt.trim() : '';
+  if (!text || TRIVIAL_SCOPE.test(text) || !ACTION.test(text)) return false;
+  if (EXPLICIT_FANOUT.test(text)) return true;
+  const breadth = BROAD_SCOPE.test(text);
+  const componentCount = COMPONENTS.reduce((n, re) => n + Number(re.test(text)), 0);
+  const numberedItems = [...text.matchAll(/(?:^|\n)\s*(?:\d+[.)]|[-*])\s+\S/g)].length;
+  return (breadth && componentCount >= 2) || componentCount >= 3 || numberedItems >= 3;
+}
+
+function parseUsedBytes(text) {
+  const match = String(text).match(/\bused\s*=\s*([\d.]+)\s*([KMGT]?)B?\b/i);
+  if (!match) return null;
+  const scale = { '': 1, K: 1024, M: 1024 ** 2, G: GIB, T: 1024 ** 4 }[match[2].toUpperCase()];
+  const value = Number(match[1]) * scale;
+  return Number.isFinite(value) && value >= 0 ? value : null;
+}
+
+export function parseMacPressureOutput(text, { totalMemoryBytes, normalizedLoad }) {
+  const source = String(text || '');
+  const freeMatch = source.match(/System-wide memory free percentage:\s*(\d+(?:\.\d+)?)%/i);
+  const pageSizeMatch = source.match(/page size of\s+([\d,]+)\s+bytes/i);
+  const compressorMatch = source.match(/Pages occupied by compressor:\s*([\d,]+)/i);
+  const swapMatch = source.match(/vm\.swapusage:.*?used\s*=\s*([\d.]+)\s*([KMGT]?)B?\b/i);
+  if (!freeMatch || !pageSizeMatch || !compressorMatch || !swapMatch) return null;
+  const pageSize = Number(pageSizeMatch[1].replaceAll(',', ''));
+  const compressedPages = Number(compressorMatch[1].replaceAll(',', ''));
+  const swapUsedBytes = parseUsedBytes(`used = ${swapMatch[1]}${swapMatch[2]}B`);
+  const freePct = Number(freeMatch[1]);
+  const compressorBytes = pageSize * compressedPages;
+  if (![pageSize, compressedPages, swapUsedBytes, freePct, totalMemoryBytes, normalizedLoad]
+    .every(Number.isFinite) || pageSize <= 0 || compressedPages < 0 || totalMemoryBytes <= 0
+    || freePct < 0 || freePct > 100 || normalizedLoad < 0) return null;
+  return { freePct, swapUsedBytes, compressorBytes, totalMemoryBytes, normalizedLoad };
+}
+
+/** Classify measured pressure. Unknown or incomplete measurements recommend serial work. */
+export function pressureRecommendation(sample) {
+  if (!sample || ![
+    sample.freePct, sample.swapUsedBytes, sample.compressorBytes,
+    sample.totalMemoryBytes, sample.normalizedLoad,
+  ].every(Number.isFinite) || sample.totalMemoryBytes <= 0) {
+    return { tier: 'unknown', totalAgents: 1, reason: 'capacity signals unavailable' };
+  }
+  const compressedRatio = sample.compressorBytes / sample.totalMemoryBytes;
+  if (sample.freePct < 45 || sample.swapUsedBytes > 0 || compressedRatio >= 0.4
+    || sample.normalizedLoad >= 1) {
+    return { tier: 'constrained', totalAgents: 1, reason: 'resource pressure is high' };
+  }
+  // The local load-per-logical-core signal is a bounded CPU-pressure proxy, not a claim to a
+  // precise CPU utilization sample. Above 75% it trims fan-out to three total agents.
+  if (sample.normalizedLoad >= 0.75) {
+    return { tier: 'high-cpu', totalAgents: 3, reason: 'CPU pressure is high' };
+  }
+  if (sample.freePct < 75 || compressedRatio >= 0.2 || sample.normalizedLoad >= 0.55) {
+    return { tier: 'moderate', totalAgents: 2, reason: 'resource headroom is partial' };
+  }
+  return { tier: 'available', totalAgents: null, reason: 'measured headroom is available' };
+}
+
+/**
+ * Apply lower configured/runtime caps after pressure sizing. A configured worker ceiling never
+ * proves runtime availability; an authoritative runtime cap, when supplied by the host, wins.
+ */
+export function effectiveAgentRecommendation(sample, {
+  configuredMaxChildren = null,
+  runtimeTotalAgentCap = null,
+  workUnitCount = null,
+} = {}) {
+  const pressure = pressureRecommendation(sample);
+  const runtimeCapKnown = Number.isInteger(runtimeTotalAgentCap) && runtimeTotalAgentCap >= 1;
+  const limits = [pressure.totalAgents ?? (runtimeCapKnown ? runtimeTotalAgentCap : UNKNOWN_RUNTIME_TOTAL_AGENT_CEILING)];
+  if (Number.isInteger(configuredMaxChildren) && configuredMaxChildren >= 0) {
+    limits.push(configuredMaxChildren + 1); // configured workers plus the coordinating agent
+  }
+  if (runtimeCapKnown) {
+    limits.push(runtimeTotalAgentCap);
+  }
+  if (Number.isInteger(workUnitCount) && workUnitCount >= 0) limits.push(workUnitCount + 1);
+  const totalAgents = Math.min(...limits);
+  return {
+    ...pressure,
+    totalAgents,
+    workers: Math.max(0, totalAgents - 1),
+    runtimeCapKnown,
+  };
+}
+
+function readInput() {
+  const chunks = [];
+  const buffer = Buffer.alloc(4096);
+  let total = 0;
+  while (total < INPUT_LIMIT) {
+    const count = fs.readSync(0, buffer, 0, Math.min(buffer.length, INPUT_LIMIT - total), null);
+    if (!count) break;
+    chunks.push(Buffer.from(buffer.subarray(0, count)));
+    total += count;
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+function collectMacPressure() {
+  if (process.platform !== 'darwin') return null;
+  try {
+    // One bounded subprocess gathers pressure, swap, and compressor bytes. Never use raw free RAM
+    // as the capacity signal; memory_pressure, actual swap, compression, and normalized load drive
+    // the tier. The hook intentionally does not wait for a timed CPU sample.
+    const probe = spawnSync('/bin/sh', ['-c', '/usr/bin/memory_pressure -Q; /usr/sbin/sysctl vm.swapusage; /usr/bin/vm_stat'], {
+      encoding: 'utf8', timeout: PROBE_TIMEOUT_MS, maxBuffer: 24 * 1024,
+      env: { PATH: '/usr/bin:/bin:/usr/sbin:/sbin' },
+    });
+    if (probe.error || probe.status !== 0) return null;
+    const cpuCount = os.cpus().length;
+    const load = os.loadavg()[0];
+    if (!cpuCount || !Number.isFinite(load) || load < 0) return null;
+    return parseMacPressureOutput(probe.stdout, {
+      totalMemoryBytes: os.totalmem(), normalizedLoad: load / cpuCount,
+    });
+  } catch {
+    return null;
+  }
+}
+
+export function formatAdvisory(recommendation) {
+  const n = recommendation.totalAgents;
+  const runtime = recommendation.runtimeCapKnown
+    ? 'Do not exceed the host-reported runtime cap; configured concurrency is only a ceiling.'
+    : `This hook cannot see the live runtime/tool cap; ${UNKNOWN_RUNTIME_TOTAL_AGENT_CEILING} total is only a conservative ceiling until the coordinator checks it. Configured concurrency is not proof of available slots.`;
+  const workerPlan = recommendation.workers > 0
+    ? `At most ${recommendation.workers} worker agent${recommendation.workers === 1 ? '' : 's'}`
+    : 'No additional worker agents';
+  return [
+    'Capacity-aware parallel-work advisory (context only; no workers were started).',
+    `This prompt appears to contain independent work. Resource tier: ${recommendation.tier}; recommend no more than ${n} total agent${n === 1 ? '' : 's'} including the coordinator (${workerPlan}).`,
+    `${runtime} Treat configured concurrency as a ceiling only; never infer that configured slots are available.`,
+    'If a real agent-spawn/task tool is available and slots remain, launch actual workers now with non-overlapping deliverables and collect their results. If tools or slots are unavailable, continue serially and do not claim parallel workers exist.',
+  ].join('\n');
+}
+
+export function runCapacityHook(rawInput, sample) {
+  let input;
+  try { input = JSON.parse(String(rawInput || '')); } catch { return ''; }
+  const prompt = input?.prompt ?? input?.user_prompt ?? input?.input;
+  if (!isSubstantialParallelWork(prompt)) return '';
+  return formatAdvisory(effectiveAgentRecommendation(sample === undefined ? collectMacPressure() : sample, {
+    configuredMaxChildren: input?.configured_max_children,
+    runtimeTotalAgentCap: input?.runtime_total_agent_cap,
+    workUnitCount: input?.independent_workstream_count ?? estimateWorkUnitCount(prompt),
+  }));
+}
+
+function main() {
+  try {
+    const output = runCapacityHook(readInput());
+    if (output) process.stdout.write(`${output}\n`);
+  } catch {
+    // This advisory has no authority to block or delay user work when anything is unavailable.
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) main();