@sabaiway/agent-workflow-kit 14.29.1 → 14.31.0

package/tools/gate-hook.mjs

@@ -24,11 +24,12 @@
 //   • place-then-wire ORDER — the hook file is placed BEFORE settings are wired (a
 //     wired-but-missing hook would error on every Bash call);
 //   • a target hook file with DIFFERENT content while our entry is NOT wired is a precondition
-//     STOP (no file write, no settings mutation — wiring an unknown script as a PreToolUse hook
-//     is exactly what consent must not slide past); the recovery is named: delete the file to
-//     reseed from the bundle. An identical file is `already current`; an already-wired entry
-//     pointing at a diverged file is REPORTED, never unwired or clobbered (the cheap-agents
-//     preserved-customization discipline — no refresh-in-place, no marker/checksum machinery);
+//     STOP for `--apply` (no file write, no settings mutation — wiring an unknown script as a
+//     PreToolUse hook is exactly what consent must not slide past); the recovery is named: the
+//     reseed route. An identical file is `already current`; an already-wired entry pointing at a
+//     diverged file is REPORTED, never unwired by `--apply`. A diverged hook is never clobbered
+//     except by `--apply --reseed`, the one consented replacement: it writes the bundled bytes in
+//     place over a placed hook and wires the entry only while it is wired in neither file;
 //   • never writes settings.local.json; never commits.
 //
 // The `--read-lane` flag is a SEPARATE operation (AD-055 Part II): it enables the opt-in read-only
@@ -39,7 +40,7 @@
 // STOP; 2 usage. Dependency-free beyond the kit's own internal exports, Node >= 22. No side
 // effects on import.
 
-import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { constants as fsConstants, existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import {
@@ -99,6 +100,7 @@ const TARGET_CURRENT = 'already-current';
 const TARGET_DIVERGED = 'diverged';
 
 const USAGE = `usage: gate-hook [--dry-run | --apply] [--cwd <dir>] [--help]
+       gate-hook --reseed [--dry-run | --apply] [--cwd <dir>]      (replace a placed hook with the bundle)
        gate-hook --read-lane [--dry-run | --apply] [--cwd <dir>]   (enable the opt-in read-only compound lane)
 
 Places the bundled PreToolUse gate-approval hook to ${HOOK_FILE_REL} and wires ONE
@@ -107,11 +109,16 @@ nothing). --apply writes. The hook auto-approves byte-exact declared gate cmds
 (docs/ai/gates.json, project root) and asks on seeded-read-only commands carrying the
 documented runtime residual.
 
+--reseed replaces a PLACED hook whose bytes differ from the bundle with the bundled bytes, in
+place, and wires the entry only while it is wired in neither settings file; a current hook wired
+in either settings file is nothing to change, and a current unwired one is only wired. It refuses
+an absent hook (--apply places it) and a symlinked or non-regular one.
+
 --read-lane enables the opt-in read-only COMPOUND lane in ${LANES_REL} ("${READ_LANE_KEY}": true) — the
 hook then auto-approves compounds of the seeded read-only core carrying zero shell metaprogramming.
 --apply --read-lane verifies the PLACED hook is the CURRENT bundle first (a pre-1.48 hook never reads
-${LANES_REL}) and refuses with the delete-to-reseed recovery otherwise. Never touches ${SETTINGS_FILE}
-or docs/ai/gates.json.
+${LANES_REL}) and refuses otherwise, naming the reseed route (gate-hook --apply --reseed --cwd <dir>).
+Never touches ${SETTINGS_FILE} or docs/ai/gates.json.
 
 Never writes ${SETTINGS_LOCAL_FILE}; never commits.`;
 
@@ -120,15 +127,33 @@ export const fail = (exitCode, message) => Object.assign(new Error(message), { e
 export const makeGateHookError = (code, message) =>
   Object.assign(new Error(`${ERROR_PREFIX} ${message}`), { name: 'GateHookError', code, exitCode: EXIT_PRECONDITION });
 
-const fsDeps = (deps = {}) => ({
+export const fsDeps = (deps = {}) => ({
   exists: deps.exists ?? deps.existsSync ?? existsSync,
   lstat: deps.lstat ?? deps.lstatSync ?? lstatSync,
   mkdir: deps.mkdir ?? deps.mkdirSync ?? mkdirSync,
   readFile: deps.readFile ?? deps.readFileSync ?? readFileSync,
   writeFile: deps.writeFile ?? deps.writeFileSync ?? writeFileSync,
+  noFollow: 'noFollow' in deps ? deps.noFollow : fsConstants.O_NOFOLLOW,
 });
 
-const lstatNoFollow = (absPath, fs) => {
+// A hook file is written through open flags that refuse a symlink planted at the hook path after the
+// preflight: a create is exclusive (O_EXCL fails on any existing entry), a replace opens no-follow and
+// truncates in place (the inode stays). Without a no-follow flag a replace refuses before truncating.
+const LATE_CHANGE_CODES = new Set(['EEXIST', 'ELOOP', 'EMLINK', 'ENOENT', 'EISDIR']);
+export const writeHookFile = (absPath, rel, bytes, create, fs) => {
+  if (!create && !fs.noFollow) {
+    throw makeGateHookError(GATE_HOOK_SYMLINK, `this platform exposes no O_NOFOLLOW open flag — refusing to replace ${rel} in place (fail closed)`);
+  }
+  const flag = create ? 'wx' : fsConstants.O_WRONLY | fs.noFollow | fsConstants.O_TRUNC;
+  try {
+    fs.writeFile(absPath, bytes, { encoding: UTF8, flag });
+  } catch (err) {
+    if (!LATE_CHANGE_CODES.has(err?.code)) throw err;
+    throw makeGateHookError(GATE_HOOK_SYMLINK, `${rel} changed before the write — refusing to write through it (no settings change made); re-run`);
+  }
+};
+
+export const lstatNoFollow = (absPath, fs) => {
   try {
     return fs.lstat(absPath);
   } catch (err) {
@@ -153,7 +178,7 @@ export const readBundledHook = (deps = {}) => {
 
 // ── preflight (read-only; velocity discipline) ────────────────────────────────────────
 
-const readStamp = (absPath, fs) => {
+export const readStamp = (absPath, fs) => {
   try {
     if (!fs.exists(absPath)) return null;
     const stamp = String(fs.readFile(absPath, UTF8)).trim();
@@ -163,14 +188,14 @@ const readStamp = (absPath, fs) => {
   }
 };
 
-const assertDirSafe = (absPath, relPath, fs) => {
+export const assertDirSafe = (absPath, relPath, fs) => {
   const stat = lstatNoFollow(absPath, fs);
   if (stat === null) return;
   if (stat.isSymbolicLink()) throw makeGateHookError(GATE_HOOK_SYMLINK, `${relPath} is a symlink — refusing to write through it`);
   if (!stat.isDirectory()) throw makeGateHookError(GATE_HOOK_SYMLINK, `${relPath} exists but is not a directory — refusing to write through it`);
 };
 
-const assertSettingsWritable = (absPath, fs) => {
+export const assertSettingsWritable = (absPath, fs) => {
   const stat = lstatNoFollow(absPath, fs);
   if (stat !== null && !stat.isFile()) {
     throw makeGateHookError(GATE_HOOK_SYMLINK, `${SETTINGS_FILE} exists but is not a regular file — refusing to clobber it`);
@@ -178,12 +203,12 @@ const assertSettingsWritable = (absPath, fs) => {
 };
 
 // Target plan: place | already-current | diverged. A symlinked / non-regular target is a STOP —
-// never a write-through, never a comparison pretending it is a file.
-const planTarget = (absPath, bundleContent, fs) => {
+// never a write-through, never a comparison pretending it is a file. `rel` names the judged file.
+export const planTarget = (absPath, rel, bundleContent, fs) => {
   const stat = lstatNoFollow(absPath, fs);
   if (stat === null) return { action: TARGET_PLACE };
   if (stat.isSymbolicLink() || !stat.isFile()) {
-    throw makeGateHookError(GATE_HOOK_SYMLINK, `${HOOK_FILE_REL} exists but is not a regular file — refusing to touch it`);
+    throw makeGateHookError(GATE_HOOK_SYMLINK, `${rel} exists but is not a regular file — refusing to touch it`);
   }
   return fs.readFile(absPath, UTF8) === bundleContent ? { action: TARGET_CURRENT } : { action: TARGET_DIVERGED };
 };
@@ -191,22 +216,22 @@ const planTarget = (absPath, bundleContent, fs) => {
 // The reused readSettingsFile validates permissions.* ONLY — this writer scans and appends
 // inside `hooks`, so any existing `hooks` key must be shape-valid BEFORE a write is planned:
 // a malformed shape is a STOP with zero writes, never a merge-through-clobber.
-const assertHooksShape = (data, relPath) => {
+export const assertHooksShape = (data, relPath, event = PRE_TOOL_USE_EVENT) => {
   if (data === undefined || data.hooks === undefined) return;
   if (!isJsonObject(data.hooks)) {
     throw makeGateHookError(GATE_HOOK_MALFORMED, `${relPath}: "hooks" must be a JSON object`);
   }
-  const entries = data.hooks[PRE_TOOL_USE_EVENT];
+  const entries = data.hooks[event];
   if (entries === undefined) return;
   if (!Array.isArray(entries)) {
-    throw makeGateHookError(GATE_HOOK_MALFORMED, `${relPath}: "hooks.${PRE_TOOL_USE_EVENT}" must be an array`);
+    throw makeGateHookError(GATE_HOOK_MALFORMED, `${relPath}: "hooks.${event}" must be an array`);
   }
   for (const entry of entries) {
     if (!isJsonObject(entry)) {
-      throw makeGateHookError(GATE_HOOK_MALFORMED, `${relPath}: every "hooks.${PRE_TOOL_USE_EVENT}[]" entry must be a JSON object`);
+      throw makeGateHookError(GATE_HOOK_MALFORMED, `${relPath}: every "hooks.${event}[]" entry must be a JSON object`);
     }
     if (entry.hooks !== undefined && (!Array.isArray(entry.hooks) || entry.hooks.some((hook) => !isJsonObject(hook)))) {
-      throw makeGateHookError(GATE_HOOK_MALFORMED, `${relPath}: "hooks.${PRE_TOOL_USE_EVENT}[].hooks" must be an array of objects`);
+      throw makeGateHookError(GATE_HOOK_MALFORMED, `${relPath}: "hooks.${event}[].hooks" must be an array of objects`);
     }
   }
 };
@@ -243,15 +268,21 @@ export const mergeHookEntry = (base) => {
   return { ...root, hooks: { ...hooks, [PRE_TOOL_USE_EVENT]: [...entries, buildHookSettingsEntry()] } };
 };
 
-export const preflightGateHook = ({ cwd }, deps = {}) => {
+export const preflightGateHook = ({ cwd, reseed = false }, deps = {}) => {
   const fs = fsDeps(deps);
-  const projectDir = cwd ?? deps.cwd ?? process.cwd();
+  const projectDir = resolve(cwd ?? deps.cwd ?? process.cwd());
   const bundleContent = readBundledHook(deps);
   const stamp = readStamp(join(projectDir, WORKFLOW_STAMP), fs);
   const stampOk = stamp === EXPECTED_WORKFLOW_VERSION;
   assertDirSafe(join(projectDir, CLAUDE_DIR), CLAUDE_DIR, fs);
   assertDirSafe(join(projectDir, HOOKS_DIR), HOOKS_DIR, fs);
-  const target = planTarget(join(projectDir, HOOK_FILE_REL), bundleContent, fs);
+  const target = planTarget(join(projectDir, HOOK_FILE_REL), HOOK_FILE_REL, bundleContent, fs);
+  if (reseed && target.action === TARGET_PLACE) {
+    throw makeGateHookError(
+      GATE_HOOK_STALE,
+      `${HOOK_FILE_REL} is not placed — --reseed replaces a placed hook; place it with: ${applyGateHookCommand(projectDir)}`,
+    );
+  }
   assertSettingsWritable(join(projectDir, SETTINGS_FILE), fs);
   const projectSettings = readSettingsFile(join(projectDir, SETTINGS_FILE), { ...deps, cwd: projectDir });
   const localSettings = readSettingsFile(join(projectDir, SETTINGS_LOCAL_FILE), { ...deps, cwd: projectDir });
@@ -272,11 +303,12 @@ export const preflightGateHook = ({ cwd }, deps = {}) => {
   const wiredInLocal = isHookWired(localSettings.data);
   // Diverged target + our entry NOT wired anywhere = STOP on BOTH dry-run and apply: applying
   // would wire an unknown script as a PreToolUse hook — exactly what consent must not slide
-  // past. (Diverged + already wired is the user's own standing state: report-only, below.)
-  if (target.action === TARGET_DIVERGED && !wiredInProject && !wiredInLocal) {
+  // past. (Diverged + already wired is the user's own standing state: report-only, below.) Under
+  // --reseed this is exactly the state the reseed replaces before it wires.
+  if (!reseed && target.action === TARGET_DIVERGED && !wiredInProject && !wiredInLocal) {
     throw makeGateHookError(
       GATE_HOOK_DIVERGED,
-      `${HOOK_FILE_REL} exists with DIFFERENT content and is not wired — refusing to wire an unknown script as a PreToolUse hook; delete the file to reseed from the bundle, then re-run`,
+      `${HOOK_FILE_REL} exists with DIFFERENT content and is not wired — refusing to wire an unknown script as a PreToolUse hook; reseed it from the bundle: ${applyReseedCommand(projectDir)}`,
     );
   }
 
@@ -285,15 +317,16 @@ export const preflightGateHook = ({ cwd }, deps = {}) => {
 
 // ── the writer ────────────────────────────────────────────────────────────────────────
 
-const formatJson = (data, eol) =>
+export const formatJson = (data, eol) =>
   `${JSON.stringify(data, null, SETTINGS_JSON_INDENT).replace(JSON_NEWLINE_PATTERN, eol)}${eol}`;
 
-export const writeGateHook = ({ cwd, dryRun = true } = {}, deps = {}) => {
+export const writeGateHook = ({ cwd, dryRun = true, reseed = false } = {}, deps = {}) => {
   const fs = fsDeps(deps);
-  const preflight = preflightGateHook({ cwd: cwd ?? deps.cwd ?? process.cwd() }, deps);
+  const preflight = preflightGateHook({ cwd: cwd ?? deps.cwd ?? process.cwd(), reseed }, deps);
   const placePlanned = preflight.target.action === TARGET_PLACE;
+  const reseedPlanned = reseed && preflight.target.action === TARGET_DIVERGED;
   const wirePlanned = !preflight.wiredInProject && !preflight.wiredInLocal;
-  const base = { placePlanned, wirePlanned, ...preflight };
+  const base = { placePlanned, reseedPlanned, wirePlanned, reseed, ...preflight };
   if (dryRun) return { wrote: false, dryRun: true, ...base };
 
   if (!preflight.stampOk) {
@@ -307,8 +340,9 @@ export const writeGateHook = ({ cwd, dryRun = true } = {}, deps = {}) => {
   const hookAbs = join(preflight.projectDir, HOOK_FILE_REL);
   if (placePlanned) {
     fs.mkdir(join(preflight.projectDir, HOOKS_DIR), { recursive: true });
-    fs.writeFile(hookAbs, preflight.bundleContent, UTF8);
+    writeHookFile(hookAbs, HOOK_FILE_REL, preflight.bundleContent, true, fs);
   }
+  if (reseedPlanned) writeHookFile(hookAbs, HOOK_FILE_REL, preflight.bundleContent, false, fs); // in place: the inode stays
   if (wirePlanned) {
     // Re-verify the target no-follow immediately BEFORE wiring: preflight read it earlier, and an
     // external process could have swapped it (or slipped a symlink in) between preflight and now.
@@ -328,7 +362,7 @@ export const writeGateHook = ({ cwd, dryRun = true } = {}, deps = {}) => {
       UTF8,
     );
   }
-  return { wrote: placePlanned || wirePlanned, dryRun: false, ...base };
+  return { wrote: placePlanned || reseedPlanned || wirePlanned, dryRun: false, ...base };
 };
 
 // ── the read-lane writer (--read-lane; AD-055 Part II, Decisions 5/9) ──────────────────
@@ -338,7 +372,7 @@ export const writeGateHook = ({ cwd, dryRun = true } = {}, deps = {}) => {
 // merge-preserve, symlink/non-regular refusal, malformed-JSON fail-closed, atomic), PLUS a CURRENCY
 // CHECK (Decisions 9): --apply refuses unless the PLACED hook is byte-identical to the current
 // bundle — enabling a lane a pre-1.48 hook can never read would be a silent no-op the user paid
-// consent for. The refusal names the delete-to-reseed recovery.
+// consent for. The refusal names the reseed route.
 
 const laneStop = (message) => makeGateHookError(GATE_HOOK_LANE, message);
 
@@ -377,6 +411,7 @@ const preflightLaneTarget = (absPath, deps) => {
 };
 
 export const applyGateHookCommand = (root) => `node ${q(GATE_HOOK_TOOL)} --apply --cwd ${q(root)}`;
+export const applyReseedCommand = (root) => `node ${q(GATE_HOOK_TOOL)} --apply --reseed --cwd ${q(root)}`;
 export const applyReadLaneCommand = (root) => `node ${q(GATE_HOOK_TOOL)} --read-lane --cwd ${q(root)} --apply`;
 
 // The currency check (Decisions 9): the PLACED hook must be byte-identical to the current bundle,
@@ -399,7 +434,7 @@ const checkHookCurrency = (root, bundleContent, fs) => {
     return {
       current: false,
       reason: `${HOOK_FILE_REL} is not the current bundle`,
-      refusal: `${HOOK_FILE_REL} is NOT the current bundle — enabling the read-lane now would be a silent no-op (a pre-1.48 hook never reads ${LANES_REL}). Reseed it, then re-run with --read-lane:\n  rm ${q(join(root, HOOK_FILE_REL))}\n  ${applyGateHookCommand(root)}`,
+      refusal: `${HOOK_FILE_REL} is NOT the current bundle — enabling the read-lane now would be a silent no-op (a pre-1.48 hook never reads ${LANES_REL}). Reseed it, then re-run with --read-lane:\n  ${applyReseedCommand(root)}`,
     };
   }
   return { current: true, reason: 'the placed hook is the current bundle' };
@@ -499,7 +534,8 @@ const TRUST_POSTURE_LINE =
 const formatTargetLine = (result) => {
   if (result.target.action === TARGET_PLACE) return `  - ${HOOK_FILE_REL}: ${result.dryRun ? 'would place' : 'placed'}`;
   if (result.target.action === TARGET_CURRENT) return `  - ${HOOK_FILE_REL}: already current`;
-  return `  - ${HOOK_FILE_REL}: diverged from the bundle — preserved, never clobbered (already wired; delete the file to reseed from the bundle)`;
+  if (result.reseed) return `  - ${HOOK_FILE_REL}: ${result.dryRun ? 'would replace' : 'replaced'} with the bundle (it differed from the bundled runtime)`;
+  return `  - ${HOOK_FILE_REL}: diverged from the bundle — preserved, never clobbered (already wired; reseed it from the bundle: ${applyReseedCommand(result.projectDir)})`;
 };
 
 const formatSettingsLine = (result) => {
@@ -508,10 +544,13 @@ const formatSettingsLine = (result) => {
   return `  - ${SETTINGS_FILE}: ${result.dryRun ? 'would wire' : 'wired'} the ${PRE_TOOL_USE_EVENT} "${HOOK_MATCHER}" entry`;
 };
 
+const RESEED_CURRENT_LINE = 'nothing to change: the placed hook is current';
+
 export const formatResult = (result) => {
+  if (result.reseed && !result.reseedPlanned && !result.wirePlanned) return RESEED_CURRENT_LINE;
   const lines = [
     result.dryRun
-      ? 'agent-workflow gate hook — DRY RUN (no changes; re-run with --apply)'
+      ? `agent-workflow gate hook — DRY RUN (no changes; re-run with --apply${result.reseed ? ' --reseed' : ''})`
       : 'agent-workflow gate hook — APPLY',
     formatTargetLine(result),
     formatSettingsLine(result),
@@ -530,13 +569,14 @@ export const formatResult = (result) => {
 // ── CLI ───────────────────────────────────────────────────────────────────────────────
 
 export const parseArgs = (argv) => {
-  const opts = { dryRunFlag: false, apply: false, cwd: undefined, help: false, readLane: false };
+  const opts = { dryRunFlag: false, apply: false, cwd: undefined, help: false, readLane: false, reseed: false };
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === '--help' || arg === '-h') opts.help = true;
     else if (arg === '--dry-run') opts.dryRunFlag = true;
     else if (arg === '--apply') opts.apply = true;
     else if (arg === '--read-lane') opts.readLane = true;
+    else if (arg === '--reseed') opts.reseed = true;
     else if (arg === '--cwd') {
       i += 1;
       if (argv[i] === undefined || argv[i].startsWith('-')) throw fail(EXIT_USAGE, '--cwd needs a directory argument');
@@ -546,7 +586,8 @@ export const parseArgs = (argv) => {
     }
   }
   if (opts.dryRunFlag && opts.apply) throw fail(EXIT_USAGE, '--dry-run and --apply cannot be used together');
-  return { help: opts.help, dryRun: !opts.apply, cwd: opts.cwd, readLane: opts.readLane };
+  if (opts.reseed && opts.readLane) throw fail(EXIT_USAGE, '--reseed and --read-lane cannot be used together');
+  return { help: opts.help, dryRun: !opts.apply, cwd: opts.cwd, readLane: opts.readLane, reseed: opts.reseed };
 };
 
 export const main = (argv = process.argv.slice(2), deps = {}) => {
@@ -563,7 +604,7 @@ export const main = (argv = process.argv.slice(2), deps = {}) => {
       log(formatReadLaneResult(laneResult));
       return EXIT_OK;
     }
-    const result = writeGateHook({ cwd: args.cwd ?? deps.cwd ?? process.cwd(), dryRun: args.dryRun }, deps);
+    const result = writeGateHook({ cwd: args.cwd ?? deps.cwd ?? process.cwd(), dryRun: args.dryRun, reseed: args.reseed }, deps);
     log(formatResult(result));
     return EXIT_OK;
   } catch (err) {

package/tools/recommendations.mjs

@@ -47,6 +47,7 @@ import {
 import { loadAutonomy, isSparseSeedConfig, AUTONOMY_REL } from './autonomy-config.mjs';
 import { deriveDoctorPlan, TRUSTED_DIRS } from './autonomy-doctor.mjs';
 import { laneOf, applySlot } from './write-lanes.mjs';
+import { STATE_BLOCK_HOOK_COMMAND, STATE_BLOCK_HOOK_RUNTIME, isStopHookWired } from './state-block-hook.mjs';
 import { detectBackends } from './detect-backends.mjs';
 import { isDirectRun } from './direct-run.mjs';
 import { ACTIVITIES, resolveActivityRecipe, composeReadiness, safeLine } from './recipes.mjs';
@@ -599,16 +600,15 @@ const probeGates = ({ root, deps, add, skip, shared }) => {
     // ABSENT is not this arm either: a hook that is not placed belongs to the place offers above and
     // in the read-lane item, whose recovery actually places one.
     if (readPlacedHookCurrency(root, deps) !== HOOK_CURRENCY.STALE) return;
-    // The writer's OWN stale recovery, in its exact shape: `gate-hook --apply` never overwrites a
-    // placed diverged hook (it places only an ABSENT target), so remove-then-reseed is the only lane
-    // that converges — and it is maintainer territory, hence HAND-APPLY.
+    // The writer's OWN stale recovery: `gate-hook --apply --reseed` replaces the placed hook with
+    // the bundle in place — the one consented replacement; the slot renders it behind the check.
     // The RESULT is what the read-lane item defers to — not these conditions re-derived there. Both
     // probes read the placed hook independently, so a hook that changes between the two reads would
     // otherwise let each conclude the other owns it and leave a dark lane reported by nobody.
     shared.markerStaleRendered = add(
       'gate-hook',
       fillTemplate(WHATS['gate-hook.marker-stale'], {}),
-      `HAND-APPLY: rm ${q(join(root, GATE_HOOK_REL))}, then node ${q(toolPath('gate-hook.mjs'))} --apply --cwd ${q(root)}`,
+      `node ${q(toolPath('gate-hook.mjs'))} --apply --reseed --cwd ${q(root)}`,
       'gate-hook.marker-stale',
     );
   } catch (err) {
@@ -992,20 +992,20 @@ const probeReadLane = ({ root, deps, add, skip, shared }) => {
     if (readReadLaneToggle(root, deps)) {
       // The lane is ON: converged IFF the placed hook is byte-current — a stale (pre-1.48) hook never
       // reads lanes.json, so the enabled lane is a silent no-op the user must reseed (council B7). The
-      // rm target is ABSOLUTE (council R2-M3) so running the recovery from any cwd can only delete this
-      // repo's hook.
+      // reseed route pins the ABSOLUTE root (council R2-M3), so running it from any cwd can only
+      // replace this repo's hook.
       const currency = readPlacedHookCurrency(root, deps);
       if (currency === HOOK_CURRENCY.CURRENT) return; // converged
       if (currency === HOOK_CURRENCY.ABSENT) {
         // The survey saw it placed and it is gone by the time we read it. The missing arm is the
-        // honest report of that; a reseed recovery whose `rm` targets nothing is not.
+        // honest report of that; a reseed recovery, which refuses an absent hook, is not.
         placeRecovery();
         return;
       }
       // ONE render per condition — and the item that renders is the one whose CAUSE is true. A hook
       // that postdates the read-lane but predates the marker key reads lanes.json perfectly well, so
       // this arm's "an old hook never reads lanes.json" would be a false diagnosis over it, while the
-      // marker arm's is exact. Both carry the same remove-then-reseed recovery, so deferring costs
+      // marker arm's is exact. Both carry the same reseed recovery, so deferring costs
       // the reader nothing and buys a true sentence. The condition is that the marker arm REALLY
       // rendered — never the conditions it would have used, re-derived here: each probe reads the
       // placed hook itself, so a hook changing between the two reads could otherwise have both defer
@@ -1014,7 +1014,7 @@ const probeReadLane = ({ root, deps, add, skip, shared }) => {
       add(
         'read-lane',
         fillTemplate(WHATS['read-lane.stale'], {}),
-        `HAND-APPLY: rm ${q(join(root, GATE_HOOK_REL))}, then node ${q(toolPath('gate-hook.mjs'))} --apply --cwd ${q(root)}`,
+        `node ${q(toolPath('gate-hook.mjs'))} --apply --reseed --cwd ${q(root)}`,
         'read-lane.stale',
       );
       return;
@@ -1027,18 +1027,17 @@ const probeReadLane = ({ root, deps, add, skip, shared }) => {
 
 // The state-block-guard offer (AD-075 · OPT-IN-SHIPS-INVISIBLE). This item exists because its absence
 // fired: 3.14.0 shipped the detector with a mode doc, a catalog row and a README row — and no advisor
-// entry — so `upgrade` reported «nothing is broken» to a user who did not have it. There is no writer
-// for this hook, so the apply is a HAND-APPLY pointer at the mode doc, which carries the exact block
-// and the three merge cases.
+// entry — so `upgrade` reported «nothing is broken» to a user who did not have it. Its writer is
+// state-block-hook.mjs; convergence is that leaf's own isStopHookWired over both settings files.
 const probeStateBlockHook = ({ root, deps, add, skip }) => {
   try {
     const project = readSettingsFile(join(root, SETTINGS_FILE), { ...deps, cwd: root });
     const local = readSettingsFile(join(root, SETTINGS_LOCAL_FILE), { ...deps, cwd: root });
-    if (isStateBlockGuardWired(project.data) || isStateBlockGuardWired(local.data)) return; // converged
+    if (isStopHookWired(project.data) || isStopHookWired(local.data)) return; // converged
     add(
       'state-block',
       fillTemplate(WHATS['state-block'], {}),
-      `HAND-APPLY: add a Stop hook running ${STATE_BLOCK_HOOK_COMMAND} to ${SETTINGS_FILE} — the exact block and the three merge cases are in references/modes/state-block-guard.md`,
+      `node ${q(toolPath('state-block-hook.mjs'))} --apply --cwd ${q(root)}`,
     );
   } catch (err) {
     skip('state-block', err);
@@ -1215,28 +1214,9 @@ export const READ_LANE_KEY = 'readLane';
 const GATE_HOOK_REL = '.claude/hooks/agent-workflow-gates.mjs';
 const BUNDLED_HOOK_ABS = join(HERE, '..', 'references', 'hooks', 'gate-approve.mjs');
 
-// The state-block-guard wiring the advisor looks for. Matched on the RUNTIME FILE NAME inside the
-// command, not on an exact string: the hook has no writer, so every user pastes their own path —
-// a copy under `.claude/hooks/`, a kit-source path, `--require-block` or not. Any Stop entry that
-// runs this runtime counts as wired, which is the honest question ("is it watching?").
-export const STATE_BLOCK_HOOK_RUNTIME = 'state-block-guard.mjs';
-// NO `--require-block` in the offered command. That flag turns on the absent-block report, and this
-// kit does not mandate the three-part closing block — recommending it to every project would hand
-// them a hook that warns after nearly every turn. The mode doc explains when to add it. (Offering the
-// strict flag by default would also contradict the very reason the report was made opt-in.)
-export const STATE_BLOCK_HOOK_COMMAND = `node "$CLAUDE_PROJECT_DIR/.claude/hooks/${STATE_BLOCK_HOOK_RUNTIME}"`;
-const runsStateBlockGuard = (hook) => typeof hook?.command === 'string' && hook.command.includes(STATE_BLOCK_HOOK_RUNTIME);
-// Both entry shapes count. The matcher-group form (an object carrying its own `hooks` array) is what
-// this family ships and what was observed firing; a flat entry is accepted too, because the question
-// this probe answers is "is anything watching?" — and guessing NO for a wiring that works would nag
-// someone who already did the work.
-const isStateBlockGuardWired = (data) => {
-  const entries = data?.hooks?.Stop;
-  if (!Array.isArray(entries)) return false;
-  return entries.some((entry) => (Array.isArray(entry?.hooks)
-    ? entry.hooks.some(runsStateBlockGuard)
-    : runsStateBlockGuard(entry)));
-};
+// The state-block-guard wiring the advisor looks for is the writer leaf's own rule (any Stop entry of
+// either settings file running the runtime); the two constants are re-exported for their readers.
+export { STATE_BLOCK_HOOK_COMMAND, STATE_BLOCK_HOOK_RUNTIME };
 
 // The placed gate hook's currency, as the states a caller must tell APART (D8). Read through the
 // writer-class fail-closed no-follow primitive, never a bare readFile: a byte-compare that FOLLOWS a

package/tools/script-priors.mjs

@@ -1,8 +1,8 @@
 // script-priors.mjs — the APPEND-ONLY catalog of every enforcement-script body this family has shipped
 // into a project's `scripts/`, as sha256 digests, and the ONE classifier the spec-layer ensure asks
 // before it refreshes a deployed script: `current` (byte-equal to the bundled copy) · `prior` (a body
-// a release shipped, never edited since) · `custom` (anything else — preserved verbatim, never
-// overwritten). The lens-region idiom (AD-041) over whole script bodies.
+// a release shipped, never edited since) · `custom` (anything else — preserved verbatim, replaced only by
+// the replace run the user's yes starts). The lens-region idiom (AD-041) over whole script bodies.
 //
 // Append discipline: when a release changes one of PRIOR_FILES, append the OUTGOING body's row here
 // in the same release and copy its bytes to test/fixtures/script-priors/<firstShipped>/<file>.txt —
@@ -36,6 +36,7 @@ export const SCRIPT_PRIORS = Object.freeze([
   prior('check-docs-size.mjs', '4.6.0', '6.0.0', '22d020c3668cdbfb4cbc1f67a8a85b2baa2d0c4956808a50626d37409e81ab38'),
   prior('spec-schema.mjs', '5.0.0', '7.2.1', '6a7d1e836c158baab5a412a1ad76d34891934dc28c88486c264a4b5d46f5892a'),
   prior('spec-schema.test.mjs', '5.0.0', '7.2.1', '698564d7283281be1826019d214df475bb876687915de086818d8f5ece0e0336'),
+  prior('check-docs-size.mjs', '7.0.0', '8.1.5', '0cf90ae2cbfc809847574a8c71a6b1322c783359740b08e0ff179f0d9d04dffc'),
 ]);
 
 export const digestOf = (bytes) => createHash('sha256').update(bytes).digest('hex');