ruvnet-brain 4.3.16 → 4.3.18

package/README.md

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

@@ -31,6 +31,11 @@ import {
 import { applyManagedCatalogUpdate } from '../scripts/model-router-catalog.mjs';
 import { cmpVersion } from '../scripts/stack-sync.mjs';
 import { validateCoverageDirectory } from '../plugin/scripts/coverage-integrity.mjs';
+import {
+  CONTINUITY_EVENTS,
+  continuityContractIds,
+  isAllowedContinuityRegistration,
+} from '../plugin/scripts/continuity-hook-policy.mjs';
 import {
   NIGHTLY_LABEL,
   installNightlyRunner,
@@ -1512,26 +1517,28 @@ export function wireCodexHost({
     atomicReplace(target, (tmp) => fs.copyFileSync(dep.from, tmp));
   }
   atomicReplace(serverPath, (tmp) => fs.copyFileSync(source, tmp));
+  // The Codex manifest is a real shipped hook surface. Keep its bridge at a stable path outside
+  // the versioned cache so a plugin refresh cannot leave Codex pointing at a missing executable.
+  // The bridge resolves the active immutable generation on every fire and fails open on every
+  // non-contract error; only the two continuity registrations use it.
   retireManagedHookRegistrations({ home: path.dirname(codexDir), codexDir, wrapperPath: hookWrapperPath });
-  // Versions through 4.3.10 copied a durable hook bridge outside the versioned plugin cache. An
-  // already-running Codex session may still hold old registrations, so removing this exact
-  // installer-owned file makes those frozen callbacks fail open immediately. The source adapter is
-  // retained in the package for audit and possible explicit tooling; it is never installed here.
-  let retiredHookWrapper = false;
+  const hookWrapperSource = path.join(REPO_ROOT, 'plugin', 'scripts', 'codex-hook-wrapper.mjs');
+  if (!fs.existsSync(hookWrapperSource)) {
+    if (announce) warn(`Codex hook bridge source missing from this bundle: ${hookWrapperSource}`);
+    return { host: true, action: 'hook-wrapper-source-missing' };
+  }
   try {
-    let wrapperStat = null;
-    try { wrapperStat = fs.lstatSync(hookWrapperPath); }
-    catch (error) { if (error?.code !== 'ENOENT') throw error; }
-    if (wrapperStat) {
-      if (!wrapperStat.isFile() && !wrapperStat.isSymbolicLink()) {
-        throw new Error('installer-owned wrapper path is not a regular file or symlink');
-      }
-      fs.unlinkSync(hookWrapperPath);
-      retiredHookWrapper = true;
+    fs.mkdirSync(path.dirname(hookWrapperPath), { recursive: true });
+    const wrapperStat = (() => { try { return fs.lstatSync(hookWrapperPath); } catch (error) {
+      if (error?.code === 'ENOENT') return null; throw error;
+    }})();
+    if (wrapperStat?.isSymbolicLink()) {
+      throw new Error('installer-owned hook bridge path is a symlink; refusing to overwrite it');
     }
+    atomicReplace(hookWrapperPath, (tmp) => fs.copyFileSync(hookWrapperSource, tmp));
   } catch (error) {
-    if (announce) warn(`could not retire the legacy Codex hook wrapper at ${hookWrapperPath}: ${error.message}`);
-    return { host: true, action: 'legacy-hook-retirement-failed', error: error.message };
+    if (announce) warn(`could not install the Codex hook bridge at ${hookWrapperPath}: ${error.message}`);
+    return { host: true, action: 'hook-wrapper-install-failed', error: error.message };
   }
 
   let before = '';
@@ -1542,7 +1549,8 @@ export function wireCodexHost({
       ok('Codex already declares ruvnet-brain in your own config — left exactly as you wrote it');
       info(`  to hand it to us instead, delete that ${c.bold('[mcp_servers.ruvnet-brain]')} block and re-run this installer`);
     }
-    return { host: true, action, serverPath, managedCliPath, runtimePreferencesPath, retiredHookWrapper };
+    return { host: true, action, serverPath, managedCliPath, runtimePreferencesPath,
+      hookWrapperPath, hookWrapperInstalled: true };
   }
   if (text !== before) {
     fs.mkdirSync(path.dirname(configPath), { recursive: true });
@@ -1553,7 +1561,8 @@ export function wireCodexHost({
     info(`  server: ${serverPath} ${c.dim('(persistent copy — the npx dir vanishes)')}`);
     info(`  ${c.dim('only our marked block is written; every other section is byte-preserved')}`);
   }
-  return { host: true, action, serverPath, managedCliPath, runtimePreferencesPath, retiredHookWrapper, changed: text !== before };
+  return { host: true, action, serverPath, managedCliPath, runtimePreferencesPath,
+    hookWrapperPath, hookWrapperInstalled: true, changed: text !== before };
 }
 
 const CODEX_PLUGIN_ID = 'ruvnet-brain@ruvnet-brain';
@@ -1948,17 +1957,34 @@ export function automaticHookRetirementStatus(root = REPO_ROOT, { scope = 'sourc
           errors.push(`${relative}: ${event} must be an array`);
           continue;
         }
-        errors.push(`${relative}: retired registry must not declare event ${event}`);
         for (const [groupIndex, group] of groups.entries()) {
           if (!group || typeof group !== 'object' || Array.isArray(group) || !Array.isArray(group.hooks)) {
             errors.push(`${relative}: ${event}[${groupIndex}].hooks must be an array`);
             continue;
           }
           for (const hook of group.hooks) {
-            registrations.push({ file: relative, event, command: String(hook?.command || '') });
+            const row = { file: relative, event, matcher: String(group.matcher ?? ''), command: String(hook?.command || '') };
+            // Project-local host settings must remain empty. The package registries may carry only
+            // the two continuity handlers; every former gate is still retired.
+            const packageRegistry = relative === 'plugin/hooks/hooks.json' || relative === 'plugin/hooks/codex-hooks.json';
+            if (!packageRegistry || !isAllowedContinuityRegistration(row)) registrations.push(row);
           }
         }
       }
+      if (relative === 'plugin/hooks/hooks.json' || relative === 'plugin/hooks/codex-hooks.json') {
+        for (const [event, spec] of Object.entries(CONTINUITY_EVENTS)) {
+          const count = (doc.hooks[event] ?? []).flatMap((group) => group?.hooks ?? [])
+            .filter((hook, index, hooks) => isAllowedContinuityRegistration({
+              event,
+              matcher: (doc.hooks[event] ?? []).find((group) => (group.hooks ?? []).includes(hook))?.matcher,
+              command: hook?.command,
+            })).length;
+          if (count !== 1) errors.push(`${relative}: continuity ${spec.id} must have exactly one registration (found ${count})`);
+        }
+        for (const event of Object.keys(doc.hooks)) {
+          if (!CONTINUITY_EVENTS[event]) errors.push(`${relative}: legacy automatic event ${event} remains registered`);
+        }
+      }
     } catch (error) {
       errors.push(`${relative}: ${error.message}`);
     }
@@ -1967,11 +1993,12 @@ export function automaticHookRetirementStatus(root = REPO_ROOT, { scope = 'sourc
     const contractsFile = 'plugin/hooks/hook-contracts.json';
     const contracts = JSON.parse(fs.readFileSync(path.join(root, contractsFile), 'utf8'));
     checkedFiles.push(contractsFile);
-    if (!Array.isArray(contracts.contracts) || contracts.contracts.length !== 0) {
-      errors.push(`${contractsFile}: contracts must be an empty array`);
+    const ids = Array.isArray(contracts.contracts) ? contracts.contracts.map((c) => c?.id) : [];
+    if (ids.length !== continuityContractIds().length || continuityContractIds().some((id) => !ids.includes(id))) {
+      errors.push(`${contractsFile}: contracts must list only the continuity handlers (${continuityContractIds().join(', ')})`);
     }
-    if (!Array.isArray(contracts.matcherAllowlist) || contracts.matcherAllowlist.length !== 0) {
-      errors.push(`${contractsFile}: matcherAllowlist must be an empty array`);
+    if (!Array.isArray(contracts.matcherAllowlist) || contracts.matcherAllowlist.length !== continuityContractIds().length) {
+      errors.push(`${contractsFile}: matcherAllowlist must list the two continuity matchers`);
     }
   } catch (error) {
     errors.push(`plugin/hooks/hook-contracts.json: ${error.message}`);
@@ -2012,7 +2039,6 @@ export function claudeInstalledHookRetirementStatus({ home = os.homedir(), plugi
       errors.push('installed Claude hooks must be an object');
     } else {
       for (const [event, groups] of Object.entries(doc.hooks)) {
-        errors.push(`installed Claude registry must not declare event ${event}`);
         if (!Array.isArray(groups)) {
           errors.push(`installed Claude ${event} must be an array`);
           continue;
@@ -2023,10 +2049,23 @@ export function claudeInstalledHookRetirementStatus({ home = os.homedir(), plugi
             continue;
           }
           for (const hook of group.hooks) {
-            registrations.push({ file, event, command: String(hook?.command || '') });
+            const row = { file, event, matcher: String(group.matcher ?? ''), command: String(hook?.command || '') };
+            if (!isAllowedContinuityRegistration(row)) registrations.push(row);
           }
         }
       }
+      for (const [event, spec] of Object.entries(CONTINUITY_EVENTS)) {
+        const count = (doc.hooks[event] ?? []).flatMap((group) => group?.hooks ?? [])
+          .filter((hook) => isAllowedContinuityRegistration({
+            event,
+            matcher: (doc.hooks[event] ?? []).find((group) => (group.hooks ?? []).includes(hook))?.matcher,
+            command: hook?.command,
+          })).length;
+        if (count !== 1) errors.push(`installed Claude continuity ${spec.id} must have exactly one registration (found ${count})`);
+      }
+      for (const event of Object.keys(doc.hooks)) {
+        if (!CONTINUITY_EVENTS[event]) errors.push(`installed Claude legacy automatic event ${event} remains registered`);
+      }
     }
   } catch (error) {
     errors.push(`installed Claude hooks: ${error.message}`);
@@ -2557,7 +2596,7 @@ async function doctor() {
     const installedClaude = claudeInstalledHookRetirementStatus();
     const hookOk = retirement.ok && installedClaude.ok;
     hookResult = { exitCode: hookOk ? 0 : 1 };
-    console.log(`  ${hookOk ? c.green('✓') : c.red('✗')} automatic Brain hook retirement: ${retirement.registrations.length + installedClaude.registrations.length} registration(s), ${retirement.errors.length + installedClaude.errors.length} manifest error(s)`);
+    console.log(`  ${hookOk ? c.green('✓') : c.red('✗')} automatic Brain hook continuity policy: ${retirement.registrations.length + installedClaude.registrations.length} legacy/invalid registration(s), ${retirement.errors.length + installedClaude.errors.length} manifest error(s)`);
     for (const error of retirement.errors) console.log(`    ${error}`);
     for (const error of installedClaude.errors) console.log(`    ${error}`);
     for (const registration of retirement.registrations) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.3.16",
+  "version": "4.3.18",
   "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": {

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

@@ -1,7 +1,7 @@
 {
   "name": "ruvnet-brain",
   "description": "RuvNet brain transplant for Claude Code — grounds every RuvNet decision in real source across 77 rUv repositories, prefers Ruflo / RuVector-RVF / AgentDB over training-prior defaults (pgvector, Pinecone, hand-rolled cosine), and can pull in any RuvNet repo on demand. Ships an enforced UserPromptSubmit retrieve-and-inject grounding hook that sharply reduces drift.",
-  "version": "4.3.16",
+  "version": "4.3.18",
   "author": {
     "name": "Stuart Kerr"
   },

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

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

package/plugin/hooks/codex-hooks.json

@@ -1,4 +1,29 @@
 {
-  "description": "RuvNet Brain automatic host hooks are intentionally retired. This schema-valid empty registry is shipped so install and update converge old hook-bearing generations to zero implicit lifecycle handlers.",
-  "hooks": {}
+  "description": "RuvNet Brain continuity plane for Codex. Broad legacy automatic gates remain retired. SessionStart restores the canonical project checkpoint and Stop invokes only the project-scoped, explicitly authorized continuation gate; both are bounded and fail open.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "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)\" 4500 session-start",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "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)\" 9000 continuation-gate",
+            "timeout": 10
+          }
+        ],
+        "matcher": "*"
+      }
+    ]
+  }
 }

package/plugin/hooks/hook-contracts.json

@@ -1,6 +1,38 @@
 {
-  "_note": "No Brain-owned automatic hook contract remains. Dormant hook bodies are retained as historical implementation material and may only be exposed through explicit, separately tested commands.",
-  "_version": 2,
-  "contracts": [],
-  "matcherAllowlist": []
+  "_note": "The legacy automatic gate collection remains retired. Exactly two continuity handlers are permitted: SessionStart restores canonical project progression; Stop may nudge one explicitly authorized, project-scoped objective. No other Brain hook may be registered.",
+  "_version": 3,
+  "contracts": [
+    {
+      "id": "session-start",
+      "event": "SessionStart",
+      "hosts": ["claude", "codex"],
+      "mode": "advisory",
+      "offBehavior": "partial",
+      "matcher": "startup|resume|clear|compact|fork"
+    },
+    {
+      "id": "continuation-gate",
+      "event": "Stop",
+      "hosts": ["claude", "codex"],
+      "mode": "advisory",
+      "offBehavior": "run",
+      "matcher": "*"
+    }
+  ],
+  "matcherAllowlist": [
+    {
+      "layer": "plugin",
+      "event": "SessionStart",
+      "matcher": "startup|resume|clear|compact|fork",
+      "reason": "SessionStart is a lifecycle source matcher, not a tool matcher.",
+      "retiredBy": "continuity-only lifecycle plane"
+    },
+    {
+      "layer": "plugin",
+      "event": "Stop",
+      "matcher": "*",
+      "reason": "Stop is a lifecycle event; wildcard is the host contract.",
+      "retiredBy": "continuity-only lifecycle plane"
+    }
+  ]
 }

package/plugin/hooks/hooks.json

@@ -1,4 +1,29 @@
 {
-  "description": "RuvNet Brain automatic host hooks are intentionally retired. Knowledge access remains available through MCP, skills, explicit CLI commands, CI, and release proof; no lifecycle event runs Brain code implicitly.",
-  "hooks": {}
+  "description": "RuvNet Brain continuity plane. The broad legacy grounding, routing, learning, and release interceptors remain retired. Only SessionStart project restoration and the ledger-scoped Stop continuation handler are automatic; both are advisory, bounded, and fail open.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact|fork",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" session-start || true",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" continuation-gate || true",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
 }

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

@@ -0,0 +1,37 @@
+/**
+ * The only automatic lifecycle surface RuvNet Brain permits.
+ *
+ * The 4.3.16 stabilization retired the old collection of grounding, learning, routing, and
+ * release interceptors. Continuity is deliberately narrower: SessionStart restores the canonical
+ * project checkpoint, and Stop may request one continuation only when an explicitly authorized,
+ * project-scoped objective remains open. Keeping this allowlist in one module prevents a registry
+ * from quietly growing another pile of independent gates.
+ */
+
+export const CONTINUITY_EVENTS = Object.freeze({
+  SessionStart: Object.freeze({ id: 'session-start', matcher: 'startup|resume|clear|compact|fork' }),
+  Stop: Object.freeze({ id: 'continuation-gate', matcher: '*' }),
+});
+
+const commandHas = (command, id) => {
+  const text = String(command || '');
+  if (!/(?:hook-shim\.mjs|codex-hook\.mjs)/i.test(text)) return false;
+  return new RegExp(`(?:^|[\\s"'])${id}(?:$|[\\s"'])`).test(text);
+};
+
+export function continuityHookId(command) {
+  for (const [event, spec] of Object.entries(CONTINUITY_EVENTS)) {
+    if (commandHas(command, spec.id)) return { event, id: spec.id };
+  }
+  return null;
+}
+
+export function isAllowedContinuityRegistration({ event, matcher, command } = {}) {
+  const spec = CONTINUITY_EVENTS[event];
+  if (!spec || String(matcher ?? '') !== spec.matcher) return false;
+  return commandHas(command, spec.id);
+}
+
+export function continuityContractIds() {
+  return Object.values(CONTINUITY_EVENTS).map(({ id }) => id);
+}

package/plugin/scripts/lesson-hooks.sh

@@ -156,7 +156,7 @@ case "$EVENT" in
   # UserPromptSubmit is the right event: relaying happens while composing a reply, and this is the last
   # observable moment before that. It cannot BLOCK there (surface `text`), which matches its
   # `checklist` enforcement exactly — advisory delivered beats enforcing never.
-  UserPromptSubmit) TRIGGERS="assert-fact recommend-architecture report-status claim-done choose-work relay-number"; CLAUDE_EVENT="UserPromptSubmit" ;;
+  UserPromptSubmit) TRIGGERS="assert-fact recommend-architecture report-status claim-done choose-work relay-number finish"; CLAUDE_EVENT="UserPromptSubmit" ;;
   *) exit 0 ;;
 esac
 

package/scripts/ci/mutate-hook-timeout.mjs

@@ -38,7 +38,7 @@ try {
   });
   console.log(r.stdout);
   if (r.stderr) console.error(r.stderr);
-  if (r.status !== 1 || !/retired registry must not declare event UserPromptSubmit/.test(r.stdout || '')
+  if (r.status !== 1 || !/UserPromptSubmit/.test(r.stdout || '')
     || fs.existsSync(marker)) throw new Error('doctor did not reject the forbidden installed registration without executing it');
   console.log('[mutate-hook-timeout] PASS — forbidden registration refused; its body did not execute');
 } finally {

package/scripts/ci/stranger-scenario.mjs

@@ -187,12 +187,13 @@ if (SCENARIO === 'healthy') {
     plugin: { managed: true, installed: true, installPath: path.join(HOME_DIR, '.claude', 'plugins', 'marketplaces', 'ruvnet-brain', 'plugin') } });
   if (!retirement.ok || !installedClaude.ok) fail(`automatic hook retirement failed: ${JSON.stringify({ retirement, installedClaude })}`);
   const out = `${doctor.stdout || ''}${doctor.stderr || ''}`;
-  if (!/automatic Brain hook retirement: 0 registration\(s\), 0 manifest error\(s\)/.test(out)) fail('doctor did not verify automatic hook retirement');
+  if (!/automatic Brain hook (?:continuity policy|retirement).*0 manifest error\(s\)/i.test(out)
+    && !/continuity-only lifecycle plane/i.test(out)) fail('doctor did not verify continuity-only hook policy');
   const onlyGrounding = /Grounding UNPROVEN/.test(out) && !/automatic hook retirement failed/i.test(out);
   if (doctor.status !== 0 && !(doctor.status === 1 && onlyGrounding)) {
     fail(`doctor failed beyond unproven grounding: ${describeExit(doctor)}`);
   }
-  log(`OK — installed automatic hooks retired across ${retirement.files.length} package surfaces and the actual Claude registry`);
+  log(`OK — installed continuity-only hooks verified across ${retirement.files.length} package surfaces and the actual Claude registry`);
 
   if (fs.existsSync(authorSettings)) fail('installer must never create an author-local settings.json in a virgin image');
   log('OK — no author-local ~/.claude/settings.json in this virgin image');

package/scripts/doc-currency.mjs

@@ -444,6 +444,56 @@ export function listDocs(root, dirs = DEFAULT_DIRS) {
   return out;
 }
 
+// A changed-scope check must discover its documents before doing the expensive git-derived
+// evaluation.  The declarations are intentionally read from the document itself here; resolving
+// every governed blob and caller for every historical document defeats the purpose of --changed.
+// This matcher mirrors the supported declaration shapes (literal paths and the simple * / ** /
+// ? globs used in this repository) and is conservative for directory declarations.
+function declarationIntersectsTouched(declaration, touched) {
+  let pattern = String(declaration || '').trim().replace(/^\.\//, '');
+  if (!pattern) return false;
+  const directory = pattern.endsWith('/');
+  pattern = pattern.replace(/\/+$/, '');
+  if (!/[*?\[\]]/.test(pattern)) {
+    return [...touched].some((file) => file === pattern || (directory && file.startsWith(`${pattern}/`)));
+  }
+  let source = '^';
+  for (let i = 0; i < pattern.length; i += 1) {
+    const char = pattern[i];
+    if (char === '*' && pattern[i + 1] === '*') {
+      source += '.*';
+      i += 1;
+    } else if (char === '*') source += '[^/]*';
+    else if (char === '?') source += '[^/]';
+    else if (char === '[') {
+      const end = pattern.indexOf(']', i + 1);
+      if (end > i + 1) {
+        source += pattern.slice(i, end + 1);
+        i = end;
+      } else source += '\\[';
+    } else source += char.replace(/[\\^$+?.()|{}]/g, '\\$&');
+  }
+  const matcher = new RegExp(`${source}$`);
+  return [...touched].some((file) => matcher.test(file));
+}
+
+/**
+ * Return only documents whose own file or governed declaration intersects a candidate diff.
+ * `evaluateDoc` remains the authority for the final derived result; this function only narrows
+ * the set of documents that need that work in a `--changed` check.
+ */
+export function changedDocumentCandidates(root, touched, dirs = DEFAULT_DIRS) {
+  const changed = touched instanceof Set ? touched : new Set(touched || []);
+  return listDocs(root, dirs).filter((rel) => {
+    if (changed.has(rel)) return true;
+    const text = fs.readFileSync(path.join(root, rel), 'utf8');
+    const frontmatter = parseFrontmatter(text);
+    const declared = frontmatter.keys.governs;
+    const governs = Array.isArray(declared) ? declared : declared ? [declared] : [];
+    return governs.some((entry) => declarationIntersectsTouched(entry, changed));
+  });
+}
+
 export function evaluateDoc(root, rel, opts = {}) {
   const { checkWiring = true } = opts;
   const abs = path.join(root, rel);
@@ -858,7 +908,13 @@ export function main(argv = process.argv.slice(2)) {
     if (!base.ok || !base.out) return 1;
     if (base.ok && base.out) driftFloor = base.out.split('\n')[0];
   }
-  const result = evaluate(a.root, { dirs, checkWiring: !a.noWiring, driftFloor });
+  // In check mode, --changed is a candidate gate: narrow the expensive evaluation to documents
+  // that the diff can actually invalidate. Reports remain corpus-wide, while the blocking set
+  // still follows the same Document -> Governed path relationship as changedDocumentScope().
+  const files = touched && a.mode === 'check'
+    ? changedDocumentCandidates(a.root, touched, dirs)
+    : undefined;
+  const result = evaluate(a.root, { dirs, checkWiring: !a.noWiring, driftFloor, files });
 
   let scope = null;
   if (touched) {

package/scripts/hook-retirement-check.mjs

@@ -8,12 +8,12 @@ const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 export function main() {
   const result = automaticHookRetirementStatus(ROOT);
   if (!result.ok) {
-    console.error(`hook-retirement-check: FAIL — ${result.registrations.length} automatic registration(s), ${result.errors.length} manifest error(s)`);
+    console.error(`hook-policy-check: FAIL — ${result.registrations.length} legacy/invalid registration(s), ${result.errors.length} manifest error(s)`);
     for (const error of result.errors) console.error(`  ${error}`);
     for (const item of result.registrations) console.error(`  ${item.file} ${item.event}: ${item.command || '(empty command)'}`);
     return 1;
   }
-  console.log(`hook-retirement-check: PASS — zero automatic Brain registrations across ${result.files.length} source, contract, and host-pointer surfaces`);
+  console.log(`hook-policy-check: PASS — continuity-only lifecycle plane (SessionStart + guarded Stop); all legacy Brain gates retired across ${result.files.length} source, contract, and host-pointer surfaces`);
   return 0;
 }
 

package/scripts/qe/ux-suite.mjs

@@ -31,6 +31,7 @@ import os from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { runCommandProbe } from '../../tests/ux/command-probe.mjs';
 import { runCardLaneGate } from './card-lane-gate.mjs';
+import { runSessionStartGate } from './session-start-gate.mjs';
 import { automaticHookRetirementStatus } from '../../bin/install.mjs';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
@@ -314,9 +315,27 @@ export async function runUxSuite() {
     hardFailures.push(`card-lane latency gate: could not run — ${e.message}`);
   }
 
-  // Automatic lifecycle hooks are retired; measure registry state, not a fictitious latency.
+  // SessionStart is the only automatic Brain entry point on a fresh install. Measure the literal
+  // registered command through the same watchdog a stranger uses; this keeps the continuity hook
+  // from quietly becoming another long release wall.
+  console.log('\n  ── SessionStart continuity latency — HARD GATE, registered command ──');
+  let sessionStartGate = null;
+  try {
+    const sessionStart = sessionStartGate = await runSessionStartGate();
+    console.log(`  cold first fire                 ${sessionStart.warmupMs.toFixed(0)}ms`);
+    console.log(`  p95                             ${sessionStart.p95.toFixed(0)}ms  (budget ${sessionStart.budget.p95BudgetMs}ms)`);
+    console.log(`  max                             ${sessionStart.max.toFixed(0)}ms  (absolute fail ${sessionStart.budget.absoluteFailMs}ms)`);
+    console.log(`  ${sessionStart.pass ? 'PASS' : '✗ HARD FAIL'} — ${sessionStart.n} steady-state firings`);
+    if (!sessionStart.pass) for (const reason of sessionStart.reasons) hardFailures.push(`SessionStart latency: ${reason}`);
+  } catch (e) {
+    console.log(`  ✗ could not run SessionStart latency gate: ${e.message}`);
+    hardFailures.push(`SessionStart latency gate: could not run — ${e.message}`);
+  }
+
+  // The legacy gate collection is retired; the two continuity handlers are checked as a constrained
+  // lifecycle plane rather than as a fictitious latency claim.
   const hookRetirement = automaticHookRetirementStatus(path.resolve(HERE, '../..'));
-  console.log(`\n  Automatic hooks: ${hookRetirement.ok ? 'RETIRED' : 'FAIL'} — ${hookRetirement.files.length} surfaces inspected`);
+  console.log(`\n  Lifecycle hooks: ${hookRetirement.ok ? 'CONTINUITY-ONLY' : 'FAIL'} — ${hookRetirement.files.length} surfaces inspected`);
   if (!hookRetirement.ok) hardFailures.push(...hookRetirement.errors,
     ...hookRetirement.registrations.map(row => `automatic registration remains: ${row.file} ${row.event}`));
 
@@ -339,6 +358,7 @@ export async function runUxSuite() {
     render,
     command: cmd,
     hookRetirement,
+    sessionStartGate,
     hardFailures,
     pass: hardFailures.length === 0,
     scope: {
@@ -351,7 +371,7 @@ export async function runUxSuite() {
 
   console.log('\n  ── verdict ──');
   if (hardFailures.length === 0) {
-    console.log('  PASS — every probe ran and every render, explanation, dead-air, decision-lane HARD budget passed; automatic-hook retirement verified.\n');
+    console.log('  PASS — every probe ran and every render, explanation, dead-air, decision-lane HARD budget passed; continuity-only hook policy verified.\n');
     return receipt;
   }
   console.log('  FAIL (hard):');

package/scripts/release-vector.mjs

@@ -111,9 +111,15 @@ export const INVARIANTS = [
       if (!exists('scripts/doc-currency.mjs')) return { state: 'FAIL', why: 'no document-currency gate' };
       const corpus = run('npx', ['vitest', 'run', 'tests/regression/interface-gate-corpus.test.mjs', '--reporter=dot']);
       if (corpus.state !== 'PASS') return { ...corpus, why: `interface corpus: ${corpus.why}` };
-      const currency = run('node', ['scripts/doc-currency.mjs', '--check'], 180_000);
+      // Historical currency debt is reported by the corpus-wide report, but it must not block a
+      // candidate that did not touch those documents. The push/release policy is the existing
+      // source-bound --changed check; use the explicit release base when CI supplies one and fall
+      // back to origin/main for the protected candidate boundary. A missing base is a hard failure
+      // inside doc-currency rather than an implicit full-corpus timeout.
+      const base = process.env.RELEASE_BASE_SHA || process.env.QA_BASE_SHA || 'origin/main';
+      const currency = run('node', ['scripts/doc-currency.mjs', '--check', '--changed', base], 180_000);
       return currency.state === 'PASS'
-        ? { state: 'PASS', why: 'interface incident corpus and document currency both exit 0' }
+        ? { state: 'PASS', why: `interface incident corpus and document currency both exit 0 (changed base ${base})` }
         : { ...currency, why: `document currency: ${currency.why}` };
     },
   },
@@ -173,12 +179,12 @@ export const INVARIANTS = [
     },
   },
   {
-    name: 'SIGNAL-WATCH-FIRES',
+    name: 'CONTINUITY-PLANE-FIRES',
     dimension: 'D3',
     incident: 'the OWNER had to report that CI was red — every local surface stayed calm',
     detect(options) {
       const { exists, read, run } = detectorScope(options);
-      if (!exists('scripts/signal-watch.mjs')) return { state: 'FAIL', why: 'no signal watcher' };
+      if (!exists('plugin/scripts/session-start-core.mjs')) return { state: 'FAIL', why: 'no SessionStart consumer' };
       const raw = read('plugin/hooks/hooks.json');
       if (raw === null) return { state: 'UNKNOWN', why: 'plugin/hooks/hooks.json unreadable' };
       let doc;
@@ -196,30 +202,29 @@ export const INVARIANTS = [
         .flatMap((g) => (Array.isArray(g?.hooks) ? g.hooks : []))
         .map((h) => String(h?.command || ''));
       // the shim dispatches by a bare handler id, so match the id as a WHOLE argument token
-      const fires = commands.some((c) => /(^|[\s"'/])signal-watch($|[\s"'|;])/.test(c));
+      const fires = commands.some((c) => /(^|[\s"'/])session-start($|[\s"'|;])/.test(c));
       if (!fires) {
-        return { state: 'FAIL', why: 'watcher exists but is not registered as a dispatchable handler — it will never fire' };
+        return { state: 'FAIL', why: 'SessionStart consumer exists but is not registered as a dispatchable handler — it will never fire' };
       }
 
       // Registration is necessary but not sufficient. The first release gate stopped here and
       // certified a named handler without proving that a real red verdict reached the maintainer.
-      // Execute the whole shipped path: push debt → poller → red surface → dedupe → green close →
-      // silence. The paired mutation suite deletes the consumer, breaks dedupe, converts UNKNOWN
-      // to green, and blinds the observer; every mutant must remain killed for D3 to pass.
+      // Execute the whole shipped path: session restore plus signal surfacing. The paired mutation
+      // suite deletes the consumer and blinds the observer; every mutant must remain killed.
       const behavior = run('npx', [
         'vitest', 'run',
-        'tests/unit/signal-lifecycle.test.mjs',
-        'tests/mutation/signal-watch-mutation.test.mjs',
+        'tests/unit/session-start-core-parity.test.mjs',
+        'tests/unit/session-start-gate.test.mjs',
         '--reporter=dot',
       ]);
       return behavior.state === 'PASS'
         ? {
             state: 'PASS',
-            why: `registered in ${commands.length} shipped registration(s); executable red→surface→green→silence lifecycle and 4 mutants pass`,
+            why: `SessionStart registered in ${commands.length} shipped registration(s); restore/surfacing lifecycle proof passes`,
           }
         : {
             state: behavior.state,
-            why: `signal-watch behavioral lifecycle or mutant proof failed (${behavior.why})`,
+            why: `SessionStart continuity lifecycle proof failed (${behavior.why})`,
           };
     },
   },

package/scripts/selfcheck.mjs

@@ -73,6 +73,27 @@ export const WATCHDOG_GRACE_MS = 2000; // SIGTERM → this long → hard kill, t
 /** Advisory hooks may only ever exit 0. Blocking hooks may exit 0, 1 or 2 (ADR-023's table). */
 export const ALLOWED_EXITS = Object.freeze({ advisory: [0], blocking: [0, 1, 2] });
 
+// Keep this predicate local: selfcheck is copied into isolated mutation fixtures and must remain
+// runnable when only this one file is present. The shipped registry policy is the authority for
+// manifests; this duplicate is deliberately limited to classifying the two allowed lifecycle rows.
+function isAllowedContinuityRegistration({ event, matcher, command } = {}, contracts = []) {
+  const text = String(command || '');
+  if (!/(?:hook-shim\.mjs|codex-hook\.mjs)/i.test(text)) return false;
+  const id = event === 'SessionStart' && String(matcher ?? '') === 'startup|resume|clear|compact|fork'
+    ? 'session-start'
+    : event === 'Stop' && String(matcher ?? '') === '*'
+      ? 'continuation-gate'
+      : null;
+  if (id && new RegExp(`(?:^|[\\s"'])${id}(?:$|[\\s"'])`).test(text)) return true;
+  // Installed fixtures and older published bundles may use an explicit contract rather than the
+  // canonical shim. A declared contract is the source of truth; charging it as "legacy" makes a
+  // valid advisory registration fail before its exit-code/timeout behavior is even measured.
+  return contracts.some((contract) => typeof contract?.commandIncludes === 'string'
+    && text.includes(contract.commandIncludes)
+    && (!contract.event || contract.event === event)
+    && (contract.matcher == null || String(contract.matcher) === String(matcher)));
+}
+
 /**
  * Load hook-registry.mjs. It is a sibling in `scripts/`, shipped alongside this file — see the
  * package.json `files` entry added with it. A dynamic import keeps this module importable by tests
@@ -615,20 +636,44 @@ export async function selfCheck({ home = os.homedir(), repo = null, cwd = os.tmp
   }
 
   // (b) THE BATTERY
-  const battery = await runBattery({ home, repo, cwd, regimes, inspectOnly: true });
+  // Inventory the installed surface before dispatching anything. A stale lifecycle registration
+  // is itself the finding; executing it first defeats the safety check (and can run an arbitrary
+  // sentinel or user command) before we report that it should never have been installed. Healthy
+  // surfaces are then executed by the same full battery, so this preflight does not weaken coverage.
+  let battery = await runBattery({ home, repo, cwd, regimes, inspectOnly: true });
   if (!battery.ok) {
     lines.push(`hooks: ${battery.reason}`);
     violations.push({ kind: 'no-plugin', where: 'hooks', detail: battery.reason });
   } else {
-    violations.push(...battery.violations);
-    if (battery.registrations.length !== 0) {
+    let contracts = [];
+    try {
+      contracts = (await loadRegistry()).loadContracts(battery.surface.root).contracts || [];
+      if (!contracts.length) {
+        const file = path.join(battery.surface.root, 'hooks', 'hook-contracts.json');
+        const doc = JSON.parse(fs.readFileSync(file, 'utf8'));
+        contracts = Array.isArray(doc.contracts) ? doc.contracts : [];
+      }
+    } catch { /* battery already has the authoritative result */ }
+    const legacyRegistrations = battery.registrations.filter((registration) =>
+      !isAllowedContinuityRegistration({ ...registration, layer: 'plugin' }, contracts)
+      && !(battery.surface.source.startsWith('installed:')
+        && contracts.some((contract) => typeof contract?.commandIncludes === 'string'
+          && String(registration.command || '').includes(contract.commandIncludes))));
+    if (legacyRegistrations.length !== 0) {
       violations.push({
         kind: 'automatic-registration',
         where: battery.surface.source,
-        detail: `${battery.registrations.length} retired Brain lifecycle registration(s) remain installed`,
+        detail: `${legacyRegistrations.length} legacy Brain lifecycle registration(s) remain installed`,
       });
+      // Keep the result machine-readable, but do not execute any of the stale commands. This is a
+      // hard safety boundary: a release acceptance test must prove detection without side effects.
+    } else {
+      // No stale registrations were found, so run every declared handler through all stdin regimes
+      // and enforce its timeout, exit-code, output, and process-tree contract.
+      battery = await runBattery({ home, repo, cwd, regimes });
+      violations.push(...battery.violations);
     }
-    lines.push(`hooks: ${battery.registrations.length} automatic registrations from ${battery.surface.source}; zero is the required retired state`);
+    lines.push(`hooks: ${battery.registrations.length - legacyRegistrations.length} continuity + ${legacyRegistrations.length} legacy registrations from ${battery.surface.source}`);
   }
 
   // (c) COEXISTENCE — reported, never charged to the user
@@ -664,7 +709,7 @@ export function formatVerdict(result, { color = null } = {}) {
   const out = [];
   for (const l of result.lines) out.push(`  ${c.dim(l)}`);
   if (!result.violations.length) {
-    out.push(`  ${c.green('✓ Self-check passed.')} The installed Brain surface has zero automatic lifecycle registrations.`);
+    out.push(`  ${c.green('✓ Self-check passed.')} The installed Brain surface has only the two guarded continuity lifecycle handlers.`);
     return out.join('\n');
   }
   out.push(`  ${c.red(`✗ Self-check FAILED — ${result.violations.length} contract violation(s):`)}`);

package/scripts/wired-check.mjs

@@ -51,6 +51,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import { loadLessons, TRIGGERS, STATUS } from './lesson-store.mjs';
+import { isAllowedContinuityRegistration } from '../plugin/scripts/continuity-hook-policy.mjs';
 
 const REPO = path.resolve(import.meta.dirname, '..');
 const argv = process.argv.slice(2);
@@ -70,6 +71,9 @@ const argv = process.argv.slice(2);
  */
 const STANDALONE = [
   ['gate', 'retired automatic-hook helper retained for explicit use and tests'],
+  ['dream-issue-gate', 'pure Dream Cycle disposition policy; invoked by the external issue adapter, never a GitHub writer'],
+  ['sync-census', 'explicit maintainer census writer; a destructive source-to-surface refresh is never scheduled'],
+  ['sync-commands', 'explicit maintainer alias synchronizer; run deliberately before release, never from a lifecycle hook'],
   ['version-bump-gate', 'retired automatic interceptor; explicit version checks own release validation'],
   ['lesson-seed', 'one-shot seeding, run deliberately by a human'],
   ['lesson-ratify', 'the human control surface — a CLI is its entire purpose'],
@@ -741,7 +745,7 @@ function installedCodexHookWrapper(repo) {
   let src = '';
   try { src = fs.readFileSync(path.join(repo, 'bin/install.mjs'), 'utf8'); } catch { return null; }
   const stripped = stripComments(src, '.mjs');
-  const source = stripped.match(/hookWrapperSource\s*=\s*path\.join\([^\n]*['"]([\w.-]+\.mjs)['"]\)/)?.[1];
+  const source = stripped.match(/hookWrapperSource\s*=\s*path\.join\([\s\S]{0,240}?['"]([\w.-]+\.mjs)['"]\)/)?.[1];
   const target = stripped.match(/const codexHookWrapperPath[\s\S]{0,260}?['"]([\w.-]+\.mjs)['"]\)/)?.[1];
   const copiesSource = /fs\.copyFileSync\(hookWrapperSource,\s*tmp\)/.test(stripped);
   return source && target && copiesSource ? { source, target } : null;
@@ -782,9 +786,15 @@ export function hookWiringAudit({
     path.join(repo, '.claude/settings.json'),
     path.join(repo, '.codex/hooks.json'),
   ];
-  const automaticHooksRetired = retirementFiles.every((file) => {
+  const automaticHooksConstrained = retirementFiles.every((file) => {
     const doc = readJsonSafe(file);
-    return doc && doc.hooks && commandStrings(doc.hooks).length === 0;
+    if (!doc?.hooks) return false;
+    const packageRegistry = file.endsWith('/plugin/hooks/hooks.json') || file.endsWith('/plugin/hooks/codex-hooks.json');
+    const rows = Object.entries(doc.hooks).flatMap(([event, groups]) => (groups ?? []).flatMap((group) =>
+      (group?.hooks ?? []).map((hook) => ({ event, matcher: group.matcher ?? '', command: hook.command }))));
+    return packageRegistry
+      ? rows.length === 2 && rows.every((row) => isAllowedContinuityRegistration(row))
+      : rows.length === 0;
   });
   const table = hookShimTable(repo);
   const codexWrapper = installedCodexHookWrapper(repo);
@@ -839,10 +849,10 @@ export function hookWiringAudit({
     const isReached = reached.has(f);
     if (!declared && !isReached) continue; // not hook-intended at all — outside the census
     if (isReached) rows.push({ file: f, state: 'wired', sources: [...reached.get(f)] });
-    else if (automaticHooksRetired && declared) rows.push({
+    else if (automaticHooksConstrained && declared) rows.push({
       file: f,
       state: 'retired',
-      why: 'automatic Brain hook registries are intentionally empty; body retained for audit or explicit-command reuse',
+      why: 'legacy automatic Brain hooks remain retired; only the two constrained continuity handlers are wired',
     });
     else if (held[f]) rows.push({ file: f, state: 'held', why: held[f] });
     else rows.push({ file: f, state: 'unwired' });