ruvnet-brain 4.5.7 → 4.5.9

package/README.md

@@ -7,7 +7,7 @@ Created: 2026-06-29 22:36:38 EDT
 
 # 🧠 RuvNet Brain
 
-### 🧠 RuvNet Brain — [![RuvNet Brain version 4.5.7 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.5.7-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.5.9 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.5.9-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.**
 

package/bin/install.mjs

@@ -79,6 +79,7 @@ import {
 } from '../scripts/console-runtime-identity.mjs';
 import { shellDiff as pluginShellDiff } from '../plugin/scripts/host-shell-boundary.mjs';
 import { codexTrustChanges, CODEX_TRUST_ACTION } from '../scripts/codex-hook-trust.mjs';
+import { probeFreshCodexDeclarations } from '../scripts/codex-fresh-host-proof.mjs';
 import { repairSecurityGuidance } from '../scripts/security-guidance-codex-compat.mjs';
 import { installNativeLaunchers, installRoutingRuntime } from '../scripts/model-routing-launchers.mjs';
 import { installTerminalLaunchers } from '../scripts/model-terminal-launchers.mjs';
@@ -460,7 +461,9 @@ function resolveCacheDir() {
   );
   info(`brain dir: ${c.bold(cacheDir)}`);
   if (custom) info(`(from your RUVNET_BRAIN_KB override)`);
-  fs.mkdirSync(cacheDir, { recursive: true });
+  // Activation creates the KB from a validated stage. A placeholder here becomes a false prior
+  // generation, which the cleanup proof correctly retains because it has no SOURCE.json.
+  fs.mkdirSync(path.dirname(cacheDir), { recursive: true });
   return { cacheDir, isCustom: Boolean(custom) };
 }
 
@@ -3045,6 +3048,21 @@ async function doctorRun({ json }) {
       const recorded = withLiveConsoleState(JSON.parse(fs.readFileSync(convergencePath, 'utf8')),
         { receiptDir: path.join(path.dirname(convergencePath), 'console-instances') });
       hostConvergence = classifyHostConvergence(recorded);
+      const codex = recorded.hosts?.codex;
+      if (codex?.state === 'ready' && codex.restartRequired === true && codex.restartScope === 'unproven') {
+        let binary = process.env.CODEX_BIN || 'codex';
+        if (!process.env.CODEX_BIN) {
+          try {
+            const configured = JSON.parse(fs.readFileSync(path.join(path.dirname(convergencePath), 'model-routing', 'terminal-launcher-config.json'), 'utf8'));
+            if (typeof configured.realCodex === 'string' && path.isAbsolute(configured.realCodex)) binary = configured.realCodex;
+          } catch { /* native PATH resolution remains bounded and fail closed */ }
+        }
+        const fresh = await probeFreshCodexDeclarations({ binary, codexHome: codexHomeDir(), cwd: process.cwd(),
+          releasedPluginRoot: path.join(REPO_ROOT, 'plugin'), expectedVersion: PACKAGE_VERSION });
+        hostConvergence = reconcileFreshCodexDeclarations(recorded, fresh);
+        if (fresh.ok) info('Codex fresh-declarations-ready: current trusted hook declarations only; hook bodies and MCP execution were not tested. Existing open windows remain unproven.');
+        else warn(`Codex fresh declarations remain unproven: ${fresh.reason}`);
+      }
       if (hostConvergence.healthy) {
         ok(`host convergence receipt: ${hostConvergence.state}`);
         if (hostConvergence.notice) info(hostConvergence.notice);
@@ -3922,6 +3940,36 @@ export function classifyHostConvergence(receipt, expectedVersion = PACKAGE_VERSI
   return { healthy: true, state: 'channels-converged' };
 }
 
+/** Activation and host readiness are independent; never claim a rollback from a host refusal. */
+export function hostSynchronizationFailureMessage(convergence, active, expectedVersion = PACKAGE_VERSION) {
+  const verified = active?.version === expectedVersion && Number.isSafeInteger(active.generation) && active.generation > 0
+    && active.codeRoot === `versions/${expectedVersion}`;
+  const state = verified ? `runtime ${expectedVersion} generation ${active.generation} is active`
+    : 'the active runtime generation could not be verified';
+  return `host synchronization is incomplete — ${state}${convergence?.error ? ` (${convergence.error})` : ''}`;
+}
+
+/** Doctor projection only. Fresh hook metadata cannot clear an executable or MCP boot gap. */
+export function reconcileFreshCodexDeclarations(recorded, proof, expectedVersion = PACKAGE_VERSION) {
+  const original = classifyHostConvergence(recorded, expectedVersion);
+  const codex = recorded?.hosts?.codex;
+  if (!proof?.ok || proof.state !== 'fresh-declarations-ready' || proof.expectedVersion !== expectedVersion
+    || recorded?.desiredVersion !== expectedVersion || codex?.version !== expectedVersion
+    || codex.state !== 'ready' || codex.restartRequired !== true || codex.restartScope !== 'unproven') return original;
+  // Older receipts carry the paths only in this machine-generated reason. An unknown reason,
+  // body file, skill/command surface, or MCP declaration retains the historical restart refusal.
+  const prefix = 'boot-level declarations changed: ';
+  const reason = codex.sessionSafetyReason;
+  const changed = typeof reason === 'string' && reason.startsWith(prefix) ? reason.slice(prefix.length).split(', ') : [];
+  if (!changed.length || changed.some((file) => !['hooks/codex-hooks.json', 'hooks/hooks.json'].includes(file))) {
+    return { ...original, freshDeclarations: proof, notice: 'Fresh Codex hook declarations are ready; executable/MCP boot readiness and existing open windows remain unproven.' };
+  }
+  const projected = classifyHostConvergence({ ...recorded, hosts: { ...recorded.hosts,
+    codex: { ...codex, restartScope: 'open-sessions' } } }, expectedVersion);
+  return { ...projected, ...(projected.healthy ? { state: 'fresh-declarations-ready' } : {}), freshDeclarations: proof,
+    notice: 'Fresh Codex hook declarations are ready; hook bodies and MCP execution were not tested. Existing open windows remain unproven.' };
+}
+
 const HOST_LABELS = { claude: 'Claude Code', codex: 'Codex' };
 /** The one accurate line for converged hosts whose already-open windows booted the old declarations. */
 export function openSessionsNotice(hosts, version) {
@@ -4233,7 +4281,9 @@ async function runUpdate() {
     info(c.dim('\nsynchronizing every detected host to this exact published version…\n'));
     const convergence = syncHostsAfterUpdate(kbDir);
     if (!convergence.ok) {
-      warn(`host synchronization is incomplete — runtime stays on the prior verified generation${convergence.error ? ` (${convergence.error})` : ''}`);
+      let active;
+      try { active = JSON.parse(fs.readFileSync(path.join(footprintRoots().brainHome, 'active.json'), 'utf8')); } catch { /* report unknown activation */ }
+      warn(hostSynchronizationFailureMessage(convergence, active));
       updateStatus = 1;
     } else if (convergence.convergence?.notice) info(convergence.convergence.notice);
     try { reportLegacyRufloDebris(); } catch (error) { warn(`legacy ruflo debris cleanup failed: ${error.message}`); }
@@ -4953,6 +5003,7 @@ export function syncManagedRouterTools({ routerDir = path.join(os.homedir(), '.c
   }
   // Preserve package-relative imports without replacing user policy.mjs overrides.
   for (const runtimeRelative of [path.join('plugin', 'scripts', 'runtime-preferences.mjs'),
+    path.join('plugin', 'scripts', 'project-identity.mjs'),
     path.join('config', 'model-router', 'policy.default.mjs')]) {
   const runtimeTarget = path.join(routerDir, runtimeRelative);
   const runtimeBytes = fs.readFileSync(path.join(packageRoot, runtimeRelative));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.5.7",
-  "description": "One-command installer for RuvNet Brain — a portable, source-grounded brain over rUv's RuvNet building blocks, delivered as a Claude Code plugin so Claude uses the stack instead of fighting it.",
+  "version": "4.5.9",
+  "description": "One-command installer for RuvNet Brain \u2014 a portable, source-grounded brain over rUv's RuvNet building blocks, delivered as a Claude Code plugin so Claude uses the stack instead of fighting it.",
   "type": "module",
   "bin": {
     "ruvnet-brain": "bin/install.mjs"
@@ -74,7 +74,9 @@
     "hooks:check": "node scripts/hook-retirement-check.mjs",
     "release:qualify": "node scripts/release-qualification.mjs",
     "rehearse:corpus": "node scripts/rehearse-corpus-pipeline.mjs",
-    "single-source:check": "node scripts/single-source-check.mjs"
+    "single-source:check": "node scripts/single-source-check.mjs",
+    "benchmark:continuity": "node scripts/qa/progression-validation-benchmark.mjs",
+    "host:codex:execution-proof": "node scripts/codex-host-execution-proof.mjs"
   },
   "files": [
     ".claude-plugin/marketplace.json",

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

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

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

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 the pre-existing, project-scoped continuation gate; session-snapshot was added at Stop on 2026-09-29 to record each turn's outcome (turn-outcome-capture.mjs) \u2014 Codex SessionEnd carries no last_assistant_message, so Stop is the only boundary that can. Its delivery rests on codex-cli 0.158.0's declared stop.command.input schema and the other Codex Stop handlers; it has NOT been live-observed and fails open. 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 \u00a7Amendment). 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 \u2014 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 \u2014 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 \u2014 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. Automatic normalized project observations are captured at prompt, pre-tool, post-tool and child completion; Claude also observes PostToolUseFailure. Pending and degraded memory are disclosed; this does not establish synchronous ADR-073 conformance or native Grok recall. SessionStart has an 8-second measured replay/restore envelope.",
+  "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 the pre-existing, project-scoped continuation gate; session-snapshot was added at Stop on 2026-09-29 to record each turn's outcome (turn-outcome-capture.mjs) \u2014 Codex SessionEnd carries no last_assistant_message, so Stop is the only boundary that can. Its delivery rests on codex-cli 0.158.0's declared stop.command.input schema and the other Codex Stop handlers; it has NOT been live-observed and fails open. 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 \u00a7Amendment). 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 \u2014 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 \u2014 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 \u2014 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. Automatic normalized project observations are captured at prompt, pre-tool, post-tool and child completion; Claude also observes PostToolUseFailure. Pending and degraded memory are disclosed; this does not establish synchronous ADR-073 conformance or native Grok recall. SessionStart has an 8-second measured replay/restore envelope. Issue377: consent-eligible learning captures only fixed workflow metadata; lifecycle recovery schedules one finite worker. Original records remain retained with hash-bound acknowledgments. Native delivery must be separately evidenced; registration is not proof.",
   "hooks": {
     "SessionStart": [
       {
@@ -11,6 +11,16 @@
             "timeout": 8
           }
         ]
+      },
+      {
+        "matcher": "startup|resume|clear|compact|fork",
+        "hooks": [
+          {
+            "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)\" 2500 learn-flush",
+            "timeout": 3
+          }
+        ]
       }
     ],
     "Stop": [
@@ -77,6 +87,16 @@
             "timeout": 5
           }
         ]
+      },
+      {
+        "matcher": "^(?:Bash|Write|Edit|MultiEdit|exec_command|apply_patch|functions(?:\\.|__)(?:exec_command|apply_patch))$",
+        "hooks": [
+          {
+            "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)\" 2500 learn-capture",
+            "timeout": 3
+          }
+        ]
       }
     ],
     "UserPromptSubmit": [
@@ -121,6 +141,16 @@
             "timeout": 3
           }
         ]
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "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)\" 2500 learn-flush",
+            "timeout": 3
+          }
+        ]
       }
     ],
     "SubagentStop": [

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 \u2014 never write rUv-product code the brain has not seen \u2014 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 \u2014 a second owner of that event, scoped by ADR-040 \u00a7Amendment 2026-09-11 to directives rather than speech), decision-gate\u2019s 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 \u2014 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 \u2014 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. Amended 2026-09-30 (ADR-0030 decision point #1, no new registration): grounding-turn-mark also arms a turn when the prompt asks a capability/feasibility/architecture question about any tool or platform, and grounding-turn-gate then requires every capability claim in the final answer to be bound to a relevant STRONG source read this turn after the last weak one (a WebFetch body is a small model's summary: weak); on Claude it reads the transcript instead of stamp mtimes, which removed the measured 'no search recorded' false alarms. ADR-0030 #2/#3 run in shadow only. Amendment 2026-10-03: normalized prompt/tool/failure/child observations are automatic; startup replays before restoring. Queued and unavailable evidence remain distinct from exact committed readback. Native Grok prompt recall is unsupported.",
-  "_version": 9,
+  "_version": 10,
   "_eventOwners": [
     {
       "event": "SessionStart",
@@ -169,6 +169,36 @@
         "codex"
       ],
       "responsibility": "Capture bounded redacted observable intent or outcome through the canonical progression bridge; retain pending/failed status and do not infer success from pre-tool intent."
+    },
+    {
+      "event": "PostToolUse",
+      "owner": "learn-capture",
+      "class": "workflow learning",
+      "hosts": [
+        "claude",
+        "codex"
+      ],
+      "responsibility": "Fixed vocabulary capture or finite selected-scope orphan recovery; no cross-scope legacy drain; registration alone does not prove native delivery."
+    },
+    {
+      "event": "SessionEnd",
+      "owner": "learn-flush",
+      "class": "workflow learning",
+      "hosts": [
+        "claude",
+        "codex"
+      ],
+      "responsibility": "Fixed vocabulary capture or finite selected-scope orphan recovery; no cross-scope legacy drain; registration alone does not prove native delivery."
+    },
+    {
+      "event": "SessionStart",
+      "owner": "learn-flush",
+      "class": "workflow learning",
+      "hosts": [
+        "claude",
+        "codex"
+      ],
+      "responsibility": "Fixed vocabulary capture or finite selected-scope orphan recovery; no cross-scope legacy drain; registration alone does not prove native delivery."
     }
   ],
   "_notInThisPlane": [
@@ -407,6 +437,42 @@
       "offBehavior": "run",
       "matcher": "*",
       "timeout": 10
+    },
+    {
+      "id": "learn-capture",
+      "event": "PostToolUse",
+      "hosts": [
+        "claude",
+        "codex"
+      ],
+      "mode": "advisory",
+      "offBehavior": "silence",
+      "matcher": "^(?:Bash|Write|Edit|MultiEdit|exec_command|apply_patch|functions(?:\\.|__)(?:exec_command|apply_patch))$",
+      "timeout": 3
+    },
+    {
+      "id": "learn-flush",
+      "event": "SessionEnd",
+      "hosts": [
+        "claude",
+        "codex"
+      ],
+      "mode": "advisory",
+      "offBehavior": "silence",
+      "matcher": "*",
+      "timeout": 3
+    },
+    {
+      "id": "learn-flush",
+      "event": "SessionStart",
+      "hosts": [
+        "claude",
+        "codex"
+      ],
+      "mode": "advisory",
+      "offBehavior": "silence",
+      "matcher": "startup|resume|clear|compact|fork",
+      "timeout": 3
     }
   ],
   "matcherAllowlist": [
@@ -549,6 +615,20 @@
       "matcher": "*",
       "reason": "Explicit supported Codex lifecycle registration, corresponding to the host-filtered continuity policy; its enforcing handler and live registration are checked independently.",
       "retiredBy": "not retired - canonical continuity host parity"
+    },
+    {
+      "layer": "plugin",
+      "event": "PostToolUse",
+      "matcher": "^(?:Bash|Write|Edit|MultiEdit|exec_command|apply_patch|functions(?:\\.|__)(?:exec_command|apply_patch))$",
+      "reason": "Consent-eligible normalized fixed workflow vocabulary, privacy-minimized before write.",
+      "retiredBy": "reviewed issue377 learning repair"
+    },
+    {
+      "layer": "codex",
+      "event": "PostToolUse",
+      "matcher": "^(?:Bash|Write|Edit|MultiEdit|exec_command|apply_patch|functions(?:\\.|__)(?:exec_command|apply_patch))$",
+      "reason": "Consent-eligible normalized fixed workflow vocabulary, privacy-minimized before write.",
+      "retiredBy": "reviewed issue377 learning repair"
     }
   ]
 }

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, 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 \u2014 ADR-040 \u00a7Amendment 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 the final answer asserts a rUv capability and 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 \u2014 the Stop stdout envelopes are advisory at the shim boundary but keep the agent working. Automatic normalized project observations are captured at prompt, pre-tool, post-tool and child completion; Claude also observes PostToolUseFailure. Pending and degraded memory are disclosed; this does not establish synchronous ADR-073 conformance or native Grok recall. SessionStart has an 8-second measured replay/restore envelope.",
+  "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 \u2014 ADR-040 \u00a7Amendment 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 the final answer asserts a rUv capability and 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 \u2014 the Stop stdout envelopes are advisory at the shim boundary but keep the agent working. Automatic normalized project observations are captured at prompt, pre-tool, post-tool and child completion; Claude also observes PostToolUseFailure. Pending and degraded memory are disclosed; this does not establish synchronous ADR-073 conformance or native Grok recall. SessionStart has an 8-second measured replay/restore envelope. Issue377: consent-eligible learning captures only fixed workflow metadata; lifecycle recovery schedules one finite worker. Original records remain retained with hash-bound acknowledgments. Native delivery must be separately evidenced; registration is not proof.",
   "hooks": {
     "SessionStart": [
       {
@@ -11,6 +11,16 @@
             "timeout": 8
           }
         ]
+      },
+      {
+        "matcher": "startup|resume|clear|compact|fork",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" learn-flush || true",
+            "timeout": 3
+          }
+        ]
       }
     ],
     "UserPromptSubmit": [
@@ -87,6 +97,16 @@
             "timeout": 5
           }
         ]
+      },
+      {
+        "matcher": "^(?:Bash|Write|Edit|MultiEdit|exec_command|apply_patch|functions(?:\\.|__)(?:exec_command|apply_patch))$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" learn-capture || true",
+            "timeout": 3
+          }
+        ]
       }
     ],
     "Stop": [
@@ -133,6 +153,16 @@
             "timeout": 10
           }
         ]
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" learn-flush || true",
+            "timeout": 3
+          }
+        ]
       }
     ],
     "SubagentStop": [

package/plugin/scripts/advocacy-catalog.mjs

@@ -145,6 +145,7 @@ export const INTENTS = Object.freeze([
     fit: 'the request is to retrieve by meaning rather than by literal match',
     cues: Object.freeze([
       /\bby meaning\b/,
+      /^(?:please\s+)?(?:search|retrieve|find)\s+(?:these|those|my|our|the)\s+(?:docs?|documents?|passages?|chunks?|notes?)\s+by meaning\b/,
       /\bsemantic(ally)?\s+(search|retriev|match|similar)/,
       /\b(instead of|rather than|not just|beyond)\s+(an?\s+)?(exact\s+)?(keywords?|string|substring|literal|grep)/,
       /\bvector\s+(search|database|db|store|index|embedding)/,

package/plugin/scripts/agentdb-recall.mjs

@@ -14,6 +14,9 @@ import { resolveRuflo, rufloInvocation } from './ruflo-bin.mjs';
 import { rufloCwdFor, rufloScratchRoot } from './project-progression-store.mjs';
 import { resolveProjectStore } from './project-store-resolver.mjs';
 import { isHarnessGenerated, readStdinBounded } from './hook-input.mjs';
+import { learningContext } from './runtime-preferences.mjs';
+import { learningTarget, LEARNING_NAMESPACE } from './learning-store.mjs';
+import { safeAction } from './learning-queue.mjs';
 
 import { redactText } from './continuity-events.mjs';
 export const STORE_FILES = Object.freeze(['memory.db']);
@@ -146,11 +149,22 @@ export function evidenceExcerpt(value, key, prompt = '') {
   return clean(start >= 0 ? text.slice(start) : text, 110);
 }
 
+export function learningObservationExcerpt(raw) {
+  try {
+    const row = JSON.parse(raw);
+    if (Object.keys(row).sort().join(',') !== 'action,authoritative,outcome,provenance,schemaVersion,scope,tool'
+      || row.schemaVersion !== 1 || row.authoritative !== false || row.provenance !== 'system-observation'
+      || row.outcome !== 'host-reported-success' || !['project', 'user'].includes(row.scope)
+      || !['Bash', 'Write', 'Edit', 'MultiEdit'].includes(row.tool) || safeAction(row.tool, row.action) !== row.action) return null;
+    return `Unratified host-reported success: ${row.tool} ${row.action}. Verify current results.`;
+  } catch { return null; }
+}
+
 export function pickRows(results, limit = 3) {
   const candidates = results.flatMap((r) => r.rows.filter((p) => p.namespace === r.namespace && (!NOISE_KEY.test(p.key) || p.namespace === 'turns' && /^turn[-_]/i.test(p.key))
     && (!r.family || p.key.toLowerCase().includes(r.family))
-    && Number.isFinite(p.score) && p.score >= MIN_RELEVANCE).map((p) => ({ ...p, targeted: Boolean(r.family) })));
-  const signal = (p) => SIGNAL_NAMESPACES.has(p.namespace) ? 2 : p.namespace === 'turns' ? 1 : 0;
+    && Number.isFinite(p.score) && p.score >= MIN_RELEVANCE).map((p) => ({ ...p, storePath: r.storePath, targeted: Boolean(r.family) })));
+  const signal = (p) => SIGNAL_NAMESPACES.has(p.namespace) ? 2 : p.namespace === 'turns' ? 1 : p.namespace === LEARNING_NAMESPACE ? -1 : 0;
   const ranked = candidates.sort((a, b) => Number(b.targeted) - Number(a.targeted) || signal(b) - signal(a) || b.score - a.score);
   // Curated lessons and patterns are signal; lifecycle transcript telemetry is not.
   // Do not reserve a slot for a weak match just because its namespace was searched.
@@ -159,7 +173,7 @@ export function pickRows(results, limit = 3) {
     if (chosen.length >= limit) break;
     if (!chosen.some((r) => r.key === row.key && r.namespace === row.namespace)) chosen.push(row);
   }
-  return chosen.map((p) => ({ store: 'memory.db', key: p.key, namespace: p.namespace,
+  return chosen.map((p) => ({ store: 'memory.db', ...(p.storePath ? { storePath: p.storePath } : {}), key: p.key, namespace: p.namespace,
     score: p.score, preview: clean(p.preview, 110) }));
 }
 
@@ -227,7 +241,15 @@ export async function recall({ prompt, projectDir = process.cwd(), env = process
     const budget = Number.isFinite(requested) && requested > 0 ? Math.min(requested, 1900) : DEFAULT_DEADLINE_MS;
     const deadline = started + budget;
     const { root, stores } = agentdbStores(projectDir, Math.max(1, Math.min(100, Math.floor(budget / 4))));
-    if (!stores.length) return empty;
+    let learningStore;
+    try {
+      const context = learningContext({ env, cwd: root });
+      if (context.enabled) {
+        const db = learningTarget(context, { env });
+        if (fs.lstatSync(db).isFile()) learningStore = { name: 'memory.db', path: db };
+      }
+    } catch { /* No global fallback: only an explicitly authorized existing learning store. */ }
+    if (!stores.length && !learningStore) return empty;
     const bin = ruflo === undefined ? resolveRuflo({ env }) : ruflo;
     if (!bin) return { ...empty, stores };
     const store = stores[0];
@@ -238,10 +260,15 @@ export async function recall({ prompt, projectDir = process.cwd(), env = process
       : /where are we|status|catch me up/i.test(prompt) ? 'project-state-current'
       : /releas|publish|workflow run|dispatch/i.test(prompt) ? 'release'
       : /requirement|always|every prompt/i.test(prompt) ? 'decision-agentdb' : null;
-    const jobs = namespaces.flatMap((namespace) => [{ namespace, family: null, args: ['--format', 'json', '-q', query, '-n', namespace, '--limit', '12'] },
-      ...(family && !SIGNAL_NAMESPACES.has(namespace) && namespace !== 'turns' ? [{ namespace, family, args: ['--format', 'json', '-q', family, '-n', namespace, '-t', 'keyword', '--limit', '4'] }] : [])]);
-    const results = await Promise.all(jobs.map(async ({ namespace, family: recordFamily, args }) => ({ namespace, family: recordFamily,
-      ...await searchOnce({ ruflo: bin, store, deadline, env, scratch: scratchFor, args }) })));
+    const jobs = (store ? namespaces : []).flatMap((namespace) => [{ store, namespace, family: null, args: ['--format', 'json', '-q', query, '-n', namespace, '--limit', '12'] },
+      ...(family && !SIGNAL_NAMESPACES.has(namespace) && namespace !== 'turns' ? [{ store, namespace, family, args: ['--format', 'json', '-q', family, '-n', namespace, '-t', 'keyword', '--limit', '4'] }] : [])]);
+    const words = promptKeywords(prompt, 14);
+    const workflowQuery = words.map(word => safeAction('Bash', word))
+      .find(action => action && action !== 'command');
+    if (learningStore && workflowQuery) jobs.push({ store: learningStore, namespace: LEARNING_NAMESPACE, family: null,
+      args: ['--format', 'json', '-q', workflowQuery, '-n', LEARNING_NAMESPACE, '-t', 'keyword', '--limit', '4'] });
+    const results = await Promise.all(jobs.map(async ({ store: jobStore, namespace, family: recordFamily, args }) => ({ namespace, family: recordFamily, storePath: jobStore.path,
+      ...await searchOnce({ ruflo: bin, store: jobStore, deadline, env, scratch: scratchFor, args }) })));
     let status = results.every((r) => r.state === 'ok') ? 'ok'
       : results.some((r) => r.state === 'timed out') ? 'timed out' : 'unavailable';
     // Overfetch a bounded six exact values so rejected turn metadata cannot hide
@@ -250,11 +277,12 @@ export async function recall({ prompt, projectDir = process.cwd(), env = process
     // Ruflo previews are ~60 characters. Read the actual selected values within
     // the same deadline so the block contains useful evidence rather than titles.
     const retrieved = await Promise.all(candidates.map(async (p) => {
-      const r = await searchOnce({ ruflo: bin, store, deadline, env, scratch: scratchFor, operation: 'retrieve',
+      const r = await searchOnce({ ruflo: bin, store: { name: 'memory.db', path: p.storePath }, deadline, env, scratch: scratchFor, operation: 'retrieve',
         args: ['-k', p.key, '-n', p.namespace, '--value-only'] });
       if (r.state === 'ok' && r.value && !r.value.startsWith('[WARN]')) {
         const clauses = p.namespace === 'turns' ? turnOutcomeClauses(r.value, prompt) : null;
-        const preview = clauses ? turnOutcomeExcerpt(r.value, prompt) : evidenceExcerpt(r.value, p.key, prompt);
+        const preview = p.namespace === LEARNING_NAMESPACE ? learningObservationExcerpt(r.value)
+          : clauses ? turnOutcomeExcerpt(r.value, prompt) : evidenceExcerpt(r.value, p.key, prompt);
         return { pick: preview ? { ...p, preview, clauses } : null, state: 'ok' };
       }
       return { pick: null, state: r.state === 'ok' ? 'unavailable' : r.state };

package/plugin/scripts/continuity-hook-policy.mjs

@@ -123,6 +123,7 @@ const registration = (id, matcher, hosts) => Object.freeze({ id, matcher, hosts:
 export const CONTINUITY_EVENTS = Object.freeze({
   SessionStart: Object.freeze([
     registration('session-start', 'startup|resume|clear|compact|fork', ['claude', 'codex']),
+    registration('learn-flush', 'startup|resume|clear|compact|fork', ['claude', 'codex']),
   ]),
   UserPromptSubmit: Object.freeze([
     registration('session-snapshot', '*', ['claude', 'codex']),
@@ -153,6 +154,7 @@ export const CONTINUITY_EVENTS = Object.freeze({
   // no change either (proven live: the real MCP tool_response's `content[0].text` carries the exact
   // "Searched N RuvNet repos" banner and query text the script already looks for).
   PostToolUse: Object.freeze([
+    registration('learn-capture', '^(?:Bash|Write|Edit|MultiEdit|exec_command|apply_patch|functions(?:\\.|__)(?:exec_command|apply_patch))$', ['claude', 'codex']),
     registration('session-snapshot', '*', ['claude', 'codex']),
     registration('grounding-stamp', '^(?:.*__)?search_ruvnet$', ['claude', 'codex']),
   ]),
@@ -184,6 +186,7 @@ export const CONTINUITY_EVENTS = Object.freeze({
     registration('session-snapshot', '*', ['claude']),
   ]),
   SessionEnd: Object.freeze([
+    registration('learn-flush', '*', ['claude', 'codex']),
     registration('session-snapshot', '*', ['claude', 'codex']),
   ]),
 });

package/plugin/scripts/ground-before-write.sh

@@ -98,11 +98,10 @@ SKIP_RECENCY=0
 [ "${RUVNET_SKIP_GROUNDING_CHECK:-0}" = "1" ] && SKIP_RECENCY=1
 
 # This gate is a BLOCKING wall (the #1-failure preventer), so by deliberate design (ADR-0021, and
-# enforced by ground-before-write.test.mjs) it depends on NOTHING fragile — pure bash builtins, no
-# node/jq/python — and therefore cannot fail-open because a tool went missing. The #13 quote-truncation
-# that justified hook-input.mjs for design-wall does NOT bite here: the product-term scan below runs
-# over the RAW payload (untouched by field()), and the only parsed values are tool_name (Write/Edit —
-# no quotes) and file_path (a truncated path merely fails the extension check → exit 0, harmless).
+# enforced by ground-before-write.test.mjs) its default refusal depends on no JSON parser. The optional
+# inert-code exemption below can narrow a valid input; a missing helper or any uncertainty leaves the
+# raw product scan intact. The legacy field parser below selects only tool name and code-file path;
+# it never supplies the code text used by the optional projection.
 field() { local re="\"$1\"[[:space:]]*:[[:space:]]*\"([^\"]*)\""; [[ $INPUT =~ $re ]] && printf '%s' "${BASH_REMATCH[1]}"; }
 
 # Case-insensitive (4.5): Grok sends `write` / `search_replace`; a case-sensitive match allowed a Grok
@@ -134,8 +133,8 @@ shopt -s nocasematch 2>/dev/null || true
 STAMP_DIR="$HOME/.cache/ruvnet-brain/grounded"
 NOW=$(date +%s 2>/dev/null) || exit 0
 
-# Scan the WHOLE tool input (path + content + new_string) — where the code mentions the
-# product is where the hand-roll hides.
+# Scan raw product terms without a parser; the optional inert-text exemption below may narrow
+# this result, but missing dependencies cannot erase the raw refusal.
 MISSING=""
 SEEN=""
 for t in agentdb metaharness ruvector aidefence agentic-flow agentic-qe ruv-swarm rvf ruflo; do
@@ -156,10 +155,10 @@ done
 # PASSED: a term the model has never grounded is stopped by stage 1 and never reaches here.
 #
 # ── THE DEPENDENCY CONTRACT, AND WHY THIS DOES NOT BREAK IT ────────────────────────────────────
-# Everything above this line is pure bash builtins, by standing contract (ADR-0021, enforced by
-# ground-before-write.test.mjs): the recency wall is THE blocking wall, so it can never fail open
-# because a tool went missing. That contract is unchanged and still tested — the assertion now
-# reads the file UP TO THIS MARKER.
+# Everything above this marker remains pure bash: the recency wall computes a refusal without
+# node/jq/python (ADR-0021). The optional exemption below can only narrow that raw result after
+# proving an inert mention; absence or uncertainty retains it. The substance stage keeps its
+# separate, explicitly fail-open contradiction contract.
 #
 # The substance stage is different in kind and is allowed one dependency, node, because deciding
 # "does this write contradict the source the brain returned?" requires a real JSON parse of the
@@ -169,6 +168,23 @@ done
 # produce a refusal here is a detector that found a contradiction, which is ADR-055 §1.2's
 # "malfunction ≠ decision" applied to the one stage that has something to malfunction.
 # ═══════════════════════════════════════════════════════════════════════════════════════════════
+# Optional positive exemption (#373), only when a raw product mention exists. A missing helper,
+# node, empty output or lexical uncertainty leaves the pure-bash result unchanged. This stage
+# cannot manufacture a refusal and never changes the raw payload used by the substance wall.
+PROJECTION="$(dirname "${BASH_SOURCE[0]}")/grounding-code-projection.mjs"
+if [ -n "$SEEN" ] && [ -f "$PROJECTION" ] && command -v node >/dev/null 2>&1; then
+  PROJECTED=$(printf '%s' "$INPUT" | node "$PROJECTION" 2>/dev/null)
+  if [ "$?" = "0" ] && [ -n "$PROJECTED" ]; then
+    PROJECTED_MISSING=""; PROJECTED_SEEN=""
+    for t in $SEEN; do
+      [[ $PROJECTED == *"$t"* ]] || continue
+      PROJECTED_SEEN="$PROJECTED_SEEN$t "
+      [[ " $MISSING" == *" $t "* ]] && PROJECTED_MISSING="$PROJECTED_MISSING$t "
+    done
+    MISSING="$PROJECTED_MISSING"; SEEN="$PROJECTED_SEEN"
+  fi
+fi
+
 if [ -z "$MISSING" ] || [ "$SKIP_RECENCY" = "1" ]; then
   [ -n "$SEEN" ] || exit 0
   SUBSTANCE="$(dirname "${BASH_SOURCE[0]}")/grounding-substance.mjs"