@sabaiway/agent-workflow-kit 14.29.1 → 14.31.0

package/tools/ensure-ops.mjs

@@ -24,7 +24,7 @@
 //
 // Dependency-free, Node >= 22. Every fs primitive is injectable (deps.*). No side effects on import.
 
-import { readFileSync, lstatSync } from 'node:fs';
+import { readFileSync, lstatSync, unlinkSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { join } from 'node:path';
 import { CANON_README, CONFIG_REL, SEED_CONFIG, loadConfig, normalizeCanonical, refreshReadme } from './orchestration-config.mjs';
@@ -36,6 +36,8 @@ import { VEHICLES_REL } from './vehicle-settings.mjs';
 import { surveyAdrLayoutStrict } from './family-registry.mjs';
 import { ENSURE_TOKENS, FAILURE_CAUSES, SEED_SCRIPTS } from './ensure-vocabulary.mjs';
 import { NODE_EVIDENCE, describeNodeProbes, probeNodeEvidence } from './node-evidence.mjs';
+import { classifyDeployedScript } from './script-priors.mjs';
+import { parseFrontmatter } from '../references/scripts/check-docs-size.mjs';
 
 // The closed vocabulary lives in its own PURE leaf so the read-only doc-parity lint can bind the
 // relayed token set without importing this module's writer graph. Re-exported here because every
@@ -297,11 +299,12 @@ export const ensureScripts = ({ cwd, kitRoot, dryRun = false, deps = {} }) => {
 
 // ── docs/ai/index.md — the GENERATED navigator, regenerated when missing or stale ───────────────
 
-// The only ensure whose target is generated rather than authored: there is nothing to preserve, and
-// nothing to seed from either — the bundled generator IS the writer, driven through its idempotent
+// The only ensure whose target is generated rather than authored: nothing to seed from, and on the
+// bundled path nothing to preserve — the bundled generator IS the writer, driven through its idempotent
 // finalizer mode. Sync-over-async by the same precedent the ADR rotator uses (spawnSync the CLI):
 // the ensure framework is synchronous, and a second index implementation here would be the drift
-// the one-generator rule exists to prevent.
+// the one-generator rule exists to prevent. Under a hook module that is not the bundled one, the
+// project's own checker judges the navigator and a write it rejects is put back (spec docs-navigator).
 const INDEX_REL = 'docs/ai/index.md';
 const GENERATOR_PATH = ['references', 'scripts', 'check-docs-size.mjs'];
 const ENSURE_INDEX_OUTCOME = /^ensure-index: (regenerated|already-current)\b/m;
@@ -317,9 +320,90 @@ const MAY_HAVE_WRITTEN = 'the navigator may already have been written — re-rea
 
 const describeExit = (result) => (result.signal ? `on signal ${result.signal}` : `with code ${result.status}`);
 const bothStreams = (result) => `${String(result.stdout ?? '')}${String(result.stderr ?? '')}`.trim();
+const describeExitWithOutput = (result, subject = 'it') => `${subject} exited ${describeExit(result)}${bothStreams(result) ? `: ${bothStreams(result)}` : ''}`;
+
+const HOOK_MODULES = ['check-docs-size.mjs', 'spec-schema.mjs'];
+const KEPT_JUDGE = `the project's own checker (${SCRIPTS_DIR}/check-docs-size.mjs --check-index)`;
+const KEPT_FITS = `in sync under ${KEPT_JUDGE} and within the maxLines it stamps`;
+const KEPT_PROBE_TIMEOUT_MS = 30_000;
+const countLines = (text) => text.split('\n').length - (text.endsWith('\n') ? 1 : 0);
+const readStampedCap = (text) => { const value = parseFrontmatter(text)?.maxLines; const cap = value ? Number(value) : NaN; return Number.isNaN(cap) ? undefined : cap; };
+
+const surveyHookModule = (cwd, kitRoot, name, read, lstat) => {
+  const rel = `${SCRIPTS_DIR}/${name}`;
+  const probe = (() => { try { return probeSeedTarget(join(cwd, rel), lstat); } catch (err) { if (err?.code === 'ENOTDIR') return { present: false }; throw err; } })();
+  if (probe.wrongKind || !probe.present) return { rel, state: probe.wrongKind ? 'wrong-kind' : 'absent', wrongKind: probe.wrongKind };
+  const deployed = read(join(cwd, rel));
+  try {
+    return { rel, state: classifyDeployedScript(deployed, name, read(join(kitRoot, ...GENERATOR_PATH.slice(0, 2), name))) };
+  } catch (err) {
+    return { rel, state: 'bundle-unreadable', error: causeOf(err) };
+  }
+};
+
+const judgeKept = ({ cwd, spawn, read, lstat, deps }) => {
+  const result = spawn(process.execPath, [join(cwd, SCRIPTS_DIR, 'check-docs-size.mjs'), '--check-index'], { cwd, encoding: 'utf8', timeout: deps.keptProbeTimeoutMs ?? KEPT_PROBE_TIMEOUT_MS, killSignal: 'SIGKILL' });
+  if (result.error) return { error: `${causeOf(result.error)}${result.signal ? `, killed on signal ${result.signal}` : ''}` };
+  if (result.status !== 0) return { accepted: false, said: describeExitWithOutput(result), half: 'its index check' };
+  const text = lstatNoFollow(join(cwd, INDEX_REL), lstat)?.isFile() ? String(read(join(cwd, INDEX_REL), 'utf8')) : null;
+  const cap = text === null ? undefined : readStampedCap(text);
+  if (cap !== undefined && countLines(text) <= Number(cap)) return { accepted: true };
+  const why = text === null ? 'no navigator file stands' : cap === undefined ? 'the navigator stamps no maxLines' : `${countLines(text)} lines against the maxLines ${cap} it stamps`;
+  return { accepted: false, said: describeExitWithOutput(result), half: `the cap it stamps (${why})` };
+};
+
+const removeIndexIfPresent = (cwd, deps) => {
+  try {
+    (deps.unlink ?? unlinkSync)(join(cwd, INDEX_REL));
+  } catch (err) {
+    if (err?.code !== 'ENOENT') throw err;
+  }
+};
+
+const putBackIndex = (cwd, found, deps) => {
+  try {
+    if (found !== null) writeDocsAiFileAtomic(cwd, INDEX_REL, found, deps, { noun: 'the navigator' });
+    else removeIndexIfPresent(cwd, deps);
+  } catch (err) {
+    return causeOf(err);
+  }
+  return null;
+};
+
+const ensureKeptIndex = ({ cwd, kitRoot, drive, spawn, read, lstat, deps, hook }) => {
+  const judge = () => judgeKept({ cwd, spawn, read, lstat, deps });
+  const reportUnanswered = (verdict, after) => loud('index', 'index-probe-failed', `${INDEX_REL}: ${KEPT_JUDGE} could not be launched or did not answer in time (${verdict.error}) — ${after}`);
+  const first = judge();
+  if (first.error) return reportUnanswered(first, 'nothing was written');
+  if (first.accepted) return ok('index', 'already-current', `${INDEX_REL}: ${KEPT_FITS} — nothing written`);
+  const custom = [...hook, ...['check-docs-size.test.mjs', 'spec-schema.test.mjs'].map((name) => surveyHookModule(cwd, kitRoot, name, read, lstat))].filter((entry) => entry.state === 'custom').map((entry) => entry.rel).sort();
+  const route = custom.length > 0 ? `the replace line printed for the spec layer (${custom.join(', ')}), run on the user's yes` : "the spec layer's refresh of the modules the project's hook loads, then this step again";
+  const found = lstatNoFollow(join(cwd, INDEX_REL), lstat) === null ? null : read(join(cwd, INDEX_REL));
+  const restored = found === null ? 'the navigator was put back: found absent, it was removed again' : 'the navigator was put back byte for byte';
+  const restoreThen = (failure, compose) => {
+    const refused = putBackIndex(cwd, found, deps);
+    return refused === null ? compose() : loud('index', 'write-refused', `${INDEX_REL}: putting the navigator back failed (${refused})${failure ? ` after ${failure}` : ''} — a navigator ${KEPT_JUDGE} rejects may stand; re-read it before re-running`);
+  };
+  const run = drive('--ensure-index');
+  const refusal = String(run.stderr ?? '').match(ENSURE_INDEX_REFUSAL);
+  if (run.error || run.status !== 0 || !String(run.stdout ?? '').match(ENSURE_INDEX_OUTCOME)) {
+    const cause = run.error ? 'generator-unlaunchable' : run.status === 2 && refusal ? (refusal[1] === 'write-refused' ? 'write-refused' : 'index-probe-failed') : 'generator-failed';
+    const what = run.error ? `the bundled generator could not be started (${causeOf(run.error)})` : describeExitWithOutput(run, 'the bundled generator');
+    return restoreThen(what, () => loud('index', cause, `${INDEX_REL}: ${what} — ${restored}`));
+  }
+  let second;
+  try { second = judge(); } catch (err) { return restoreThen(`the navigator could not be read back (${causeOf(err)})`, () => loud('index', 'unexpected-error', `${INDEX_REL}: the navigator could not be read back after the bundled write (${causeOf(err)}) — ${restored}`)); }
+  if (second.error) return restoreThen(`${KEPT_JUDGE} could not answer (${second.error})`, () => reportUnanswered(second, restored));
+  if (second.accepted) return ok('index', 'regenerated', `${INDEX_REL}: written by the bundled generator — ${KEPT_FITS}`);
+  return restoreThen(null, () => ok('index', 'customized-preserved', `${INDEX_REL}: ${KEPT_JUDGE} rejected the bundled render on ${second.half} (${second.said}), and the navigator as found did not pass it either (${first.half}) — ${restored}. The route: ${route}`));
+};
+
+const buildKeptDryRunNote = (hook) =>
+  `a module the project's hook loads (${hook.filter((entry) => entry.state !== 'current').map((entry) => entry.rel).join(', ')}) is not the bundled one: unless the spec-layer step of this run first refreshes every such module, the real run judges the navigator by ${KEPT_JUDGE} and puts back a write it rejects`;
 
 export const ensureIndex = ({ cwd, kitRoot, dryRun = false, deps = {} }) => {
   const lstat = deps.lstat ?? lstatSync;
+  const read = deps.readFile ?? readFileSync;
   const spawn = deps.spawnSync ?? spawnSync;
   const generator = join(kitRoot, ...GENERATOR_PATH);
   const drive = (mode) => spawn(process.execPath, [generator, mode, `--root=${cwd}`], { encoding: 'utf8' });
@@ -330,14 +414,21 @@ export const ensureIndex = ({ cwd, kitRoot, dryRun = false, deps = {} }) => {
   if (probe.wrongKind) {
     return loud('index', 'wrong-node-kind', `${INDEX_REL}: exists but is ${probe.wrongKind} — the navigator is a generated file and this is not one; nothing was read or written, resolve it by hand and re-run`);
   }
-
+  const hook = HOOK_MODULES.reduce((acc, name) => (acc[0]?.state === 'absent' || acc[0]?.wrongKind ? acc : [...acc, surveyHookModule(cwd, kitRoot, name, read, lstat)]), []);
+  const wrong = hook.find((entry) => entry.state === 'wrong-kind');
+  if (wrong) return loud('index', 'wrong-node-kind', `${wrong.rel}: exists but is ${wrong.wrongKind} — the project's hook loads it, so nothing was read or written; resolve it by hand and re-run`);
+  const kept = hook[0].state !== 'absent' && !hook.every((entry) => entry.state === 'current');
+  const unreadable = kept && hook.find((entry) => entry.state === 'bundle-unreadable');
+  if (unreadable) return loud('index', 'bundle-unreadable', `${unreadable.rel}: the bundled module could not be read, so nothing was written — reinstall the kit. ${unreadable.error}`);
+  if (kept && !dryRun) return ensureKeptIndex({ cwd, kitRoot, drive, spawn, read, lstat, deps, hook });
+  const dryNote = kept ? [buildKeptDryRunNote(hook)] : [];
   if (dryRun) {
     const check = drive('--check-index');
     if (check.error) return unlaunchable(check);
     const out = bothStreams(check);
-    if (check.status === 0 && PROBE_FRESH.test(out)) return ok('index', 'already-current', `${INDEX_REL}: in sync with the source frontmatter — nothing would be written`);
-    if (check.status === 1 && PROBE_STALE.test(out)) return ok('index', 'would-regenerate', `${INDEX_REL}: missing or stale — would be written from the source frontmatter`);
-    return loud('index', 'index-probe-failed', `${INDEX_REL}: the freshness probe answered neither fresh nor stale (exited ${describeExit(check)}), so nothing was written. ${out}`);
+    if (check.status === 0 && PROBE_FRESH.test(out)) return ok('index', 'already-current', `${INDEX_REL}: in sync with the source frontmatter — nothing would be written`, ...dryNote);
+    if (check.status === 1 && PROBE_STALE.test(out)) return ok('index', 'would-regenerate', `${INDEX_REL}: missing or stale — would be written from the source frontmatter`, ...dryNote);
+    return loud('index', 'index-probe-failed', `${INDEX_REL}: the freshness probe answered neither fresh nor stale (exited ${describeExit(check)}), so nothing was written. ${out}`, ...dryNote);
   }
 
   const run = drive('--ensure-index');

package/tools/ensure-specs.mjs

@@ -3,8 +3,8 @@
 // a FIXED order the measured coupling dictates:
 //   1. the reader pair   scripts/spec-schema.mjs + .test.mjs      — created when absent; since 2a
 //      also REFRESHED when the deployed bytes are a body a release shipped (script-priors.mjs), a
-//      custom body preserved verbatim (brief D1 shipped it create-only; the 4.6.x bodies joining the
-//      catalog is what keeps those deployments out of the stranded-custom cell);
+//      custom body preserved verbatim until the user's yes runs the printed replace line
+//      (--replace-custom <digest>, spec docs-navigator);
 //   2. the checker pair  scripts/check-docs-size.mjs + .test.mjs  — the same prior-refresh lane, and
 //      only behind a reader pair this run leaves byte-current;
 //   3. the store root    docs/ai/specs/index.md                   — seeded (placeholders rendered)
@@ -17,16 +17,18 @@
 // The state table (enumerate by PROOF, never by exclusion): every file is classified into exactly one
 // of current | prior | custom | absent | wrong-kind before anything is written, each write admits
 // through ONE conjunction of those facts (decideWrites), and every other cell is a stated refusal —
-// a custom file of either pair preserves itself AND withholds every write that depends on it. Writes
-// run in order and each is idempotent, so a run that stopped partway converges on the next run.
+// a custom file of either pair preserves itself AND withholds every write that depends on it, and the
+// ONE replace line names every custom file; on the yes, a replace run whose digest still matches
+// rewrites them. Writes run in order and each is idempotent, so a stopped run converges on the next.
 //
 // Dependency-free, Node >= 22. Every fs primitive is injectable (deps.*). No side effects on import.
 
 import { readFileSync, lstatSync } from 'node:fs';
 import { join } from 'node:path';
 import { writeContainedFileAtomic, writeProjectFileCreateOnly } from './atomic-write.mjs';
-import { classifyDeployedScript } from './script-priors.mjs';
+import { classifyDeployedScript, digestOf } from './script-priors.mjs';
 import { composeFailure, composeOutcome, nodeEvidenceRefusal, probeSeedTarget, tmpNote } from './ensure-ops.mjs';
+import { shellQuoteArg } from './repo-lex.mjs';
 
 const OP = 'specs';
 const SCRIPTS_DIR = 'scripts';
@@ -59,9 +61,14 @@ const surveyScript = ({ cwd, kitRoot, name, read, lstat }) => {
   const probe = probeSeedTarget(join(cwd, SCRIPTS_DIR, name), lstat);
   if (probe.wrongKind) return { rel, name, state: 'wrong-kind', wrongKind: probe.wrongKind, bundle };
   if (!probe.present) return { rel, name, state: 'absent', bundle };
-  return { rel, name, state: classifyDeployedScript(read(join(cwd, SCRIPTS_DIR, name)), name, bundle), bundle };
+  const bytes = read(join(cwd, SCRIPTS_DIR, name));
+  return { rel, name, state: classifyDeployedScript(bytes, name, bundle), bundle, bytes };
 };
 
+// The custom set's digest binds the set AND the bytes: the rel-sorted `<rel> <sha256>` lines, LF-joined.
+export const customSetDigest = (files) =>
+  digestOf([...files].sort((a, b) => (a.rel < b.rel ? -1 : 1)).map((f) => `${f.rel} ${digestOf(f.bytes)}`).join('\n'));
+
 const surveyStoreRoot = (cwd, lstat) => {
   const probe = probeSeedTarget(join(cwd, STORE_ROOT_REL), lstat);
   if (probe.wrongKind) return { rel: STORE_ROOT_REL, state: 'wrong-kind', wrongKind: probe.wrongKind };
@@ -73,21 +80,25 @@ const surveyStoreRoot = (cwd, lstat) => {
 // Reader seeds are create-only and always admitted. A REFRESH overwrites bytes, so it runs only
 // inside a pair whose every file is proven refreshable (current | prior | absent) — one custom file
 // withholds its whole pair; the checker lane (its seeds included) and the store additionally wait
-// for a reader pair this run leaves byte-current (seeded + refreshed = current).
+// for a reader pair this run leaves byte-current (seeded + refreshed = current). Under the user's
+// replace yes a custom file is refreshable too: it is rewritten to the bundled body.
 const PAIR_ELIGIBLE = new Set(['current', 'prior', 'absent']);
+const REPLACE_ELIGIBLE = new Set([...PAIR_ELIGIBLE, 'custom']);
 
-export const decideWrites = ({ reader, checker, store }) => {
-  const readerEligible = reader.every((f) => PAIR_ELIGIBLE.has(f.state));
-  const checkerEligible = readerEligible && checker.every((f) => PAIR_ELIGIBLE.has(f.state));
+export const decideWrites = ({ reader, checker, store }, replace = false) => {
+  const eligible = replace ? REPLACE_ELIGIBLE : PAIR_ELIGIBLE;
+  const refreshable = replace ? ['prior', 'custom'] : ['prior'];
+  const readerEligible = reader.every((f) => eligible.has(f.state));
+  const checkerEligible = readerEligible && checker.every((f) => eligible.has(f.state));
   const writes = [];
   for (const f of reader) {
     if (f.state === 'absent') writes.push({ kind: 'seed', file: f });
-    if (readerEligible && f.state === 'prior') writes.push({ kind: 'refresh', file: f });
+    if (readerEligible && refreshable.includes(f.state)) writes.push({ kind: 'refresh', file: f });
   }
   if (checkerEligible) {
     for (const f of checker) {
       if (f.state === 'absent') writes.push({ kind: 'seed', file: f });
-      if (f.state === 'prior') writes.push({ kind: 'refresh', file: f });
+      if (refreshable.includes(f.state)) writes.push({ kind: 'refresh', file: f });
     }
   }
   if (checkerEligible && store.state === 'absent') writes.push({ kind: 'store' });
@@ -103,7 +114,10 @@ export const decideWrites = ({ reader, checker, store }) => {
 const LEFT_FOR = { withheld: 'it waits on the pair named above', stopped: 'the run stopped before it' };
 const SCRIPT_LINES = {
   current: () => 'already the bundled body — nothing written',
-  custom: () => "carries a body this kit did not ship as current — preserved verbatim; the writes that depend on it wait until the pair matches the bundled scripts (copy them by hand from the kit's references/scripts/ when convenient, then re-run the upgrade)",
+  custom: (fate) => ({
+    written: "carried an edited body — replaced by the bundled one on the user's yes",
+    stopped: 'carries an edited body — not replaced; the run stopped before it',
+  })[fate] ?? "carries a body this kit did not ship as current — preserved verbatim; the writes that depend on it wait until it is replaced on the user's yes (the replace line below)",
   absent: (fate) => ({
     written: 'copied from the bundled scripts',
     stood: 'appeared while this run was seeding it — the bundled body stands',
@@ -120,10 +134,13 @@ const STORE_LINES = {
   written: "created from the bundled template (today's date rendered)",
   stood: 'appeared while this run was seeding it — the existing file stands',
   would: 'absent — would be created from the bundled template',
-  withheld: "not seeded — an older or edited checker renders the spec store row by row and reds the hook's index check, so the store root waits for a current checker pair",
+  withheld: (custom) => `not seeded — it waits on the edited ${custom.join(', ')} (a body this kit did not ship): an older or edited checker renders the spec store row by row and reds the hook's index check, so the store root waits for a current checker pair`,
   stopped: 'absent — not created; the run stopped before it',
 };
-const storeLine = (store, fate) => `${STORE_ROOT_REL}: ${STORE_LINES[store.state === 'present' ? 'present' : fate]}`;
+const storeLine = (store, fate, custom) => {
+  const line = STORE_LINES[store.state === 'present' ? 'present' : fate];
+  return `${STORE_ROOT_REL}: ${typeof line === 'function' ? line(custom) : line}`;
+};
 const relOf = (write) => (write.kind === 'store' ? STORE_ROOT_REL : write.file.rel);
 
 // The fate of every path for the lines: a write that ran carries its result, an admitted write the
@@ -138,10 +155,17 @@ const composeLines = ({ reader, checker, store, writes, fates, withheld, stopped
   const fate = (rel) => fateOf(rel, { writes, fates, withheld, stopped });
   const lines = [...reader, ...checker].map((f) => scriptLine(f, fate(f.rel)));
   const storeFate = fate(STORE_ROOT_REL);
-  if (store.state === 'present' || storeFate !== 'none') lines.push(storeLine(store, storeFate));
+  const custom = [...reader, ...checker].filter((f) => f.state === 'custom').map((f) => f.rel);
+  if (store.state === 'present' || storeFate !== 'none') lines.push(storeLine(store, storeFate, custom));
   return lines;
 };
 
+// The ONE replace line: the exact command, its condition first, both paths shell-quoted.
+const replaceLineFor = (custom, kitRoot, cwd) => (custom.length === 0 ? [] : [
+  `to replace the edited files named above, run this only on the user's yes — the bundled bodies overwrite their edits: node ${shellQuoteArg(join(kitRoot, 'tools', 'ensure-configs.mjs'))} --reconcile --replace-custom ${customSetDigest(custom)} --cwd ${shellQuoteArg(cwd)}`,
+]);
+const RACE_LINE = 'the edited files changed since the replace line was printed (another set or other bytes), so nothing was written — ask the user again with the fresh replace line below';
+
 // A per-file loop can stop partway; the run says which files already landed — never "nothing happened".
 const partialNote = (count) =>
   (count > 0 ? [`the writes stopped PARTWAY — the ${count} file(s) named above were already written and are NOT rolled back`] : []);
@@ -156,7 +180,7 @@ const renderStoreRoot = (kitRoot, read, today) => {
   return body;
 };
 
-export const ensureSpecs = ({ cwd, kitRoot, dryRun = false, deps = {} }) => {
+export const ensureSpecs = ({ cwd, kitRoot, dryRun = false, deps = {}, replaceCustom }) => {
   const lstat = deps.lstat ?? lstatSync;
   const read = deps.readFile ?? readFileSync;
   const refusal = nodeEvidenceRefusal(OP, cwd, lstat);
@@ -172,7 +196,15 @@ export const ensureSpecs = ({ cwd, kitRoot, dryRun = false, deps = {} }) => {
     if (f.state === 'wrong-kind') return loud('wrong-node-kind', `${f.rel}: exists but is ${f.wrongKind} — nothing was read or written; resolve it by hand, then re-run`);
   }
 
-  const { writes, withheld } = decideWrites({ reader, checker, store });
+  const custom = [...reader, ...checker].filter((f) => f.state === 'custom');
+  const replace = replaceCustom !== undefined && custom.length > 0;
+  const replaceLine = replaceLineFor(custom, kitRoot, cwd);
+  if (replace && replaceCustom !== customSetDigest(custom)) {
+    const asFound = decideWrites({ reader, checker, store });
+    return loud('race-unresolved', RACE_LINE, ...composeLines({ reader, checker, store, ...asFound, fates: new Map(), stopped: true }), ...replaceLine);
+  }
+  const { writes, withheld } = decideWrites({ reader, checker, store }, replace);
+  const tail = replace ? [] : replaceLine;
   const kinds = new Set(writes.map((w) => w.kind));
   // ONE token by precedence — a write that happened (or, dry, would happen) always outranks the
   // preserved-custom report, which names a run that wrote nothing behind an edited pair.
@@ -184,14 +216,14 @@ export const ensureSpecs = ({ cwd, kitRoot, dryRun = false, deps = {} }) => {
   const fates = new Map();
   const linesNow = (stopped) => composeLines({ reader, checker, store, writes, fates, withheld, stopped });
   const writtenCount = () => [...fates.values()].filter((fate) => fate === 'written').length;
-  if (dryRun) return ok(tokenFor(kinds.has('seed') || kinds.has('store'), kinds.has('refresh')), linesNow(false));
+  if (dryRun) return ok(tokenFor(kinds.has('seed') || kinds.has('store'), kinds.has('refresh')), [...linesNow(false), ...tail]);
 
   let storeBody = null;
   if (kinds.has('store')) {
     try {
       storeBody = renderStoreRoot(kitRoot, read, deps.today ?? todayIso());
     } catch (err) {
-      return loud('template-unreadable', `${STORE_ROOT_REL}: ${causeOf(err)}`, ...linesNow(true));
+      return loud('template-unreadable', `${STORE_ROOT_REL}: ${causeOf(err)}`, ...linesNow(true), ...tail);
     }
   }
   const writeOne = ({ kind, file }) => {
@@ -209,14 +241,14 @@ export const ensureSpecs = ({ cwd, kitRoot, dryRun = false, deps = {} }) => {
     try {
       result = writeOne(write);
     } catch (err) {
-      return loud('write-refused', `${rel}: ${causeOf(err)}`, ...linesNow(true), ...notes, ...partialNote(writtenCount()));
+      return loud('write-refused', `${rel}: ${causeOf(err)}`, ...linesNow(true), ...notes, ...partialNote(writtenCount()), ...tail);
     }
     if (write.kind !== 'refresh' && !result.created && !stoodCurrent(write)) {
-      return loud('race-unresolved', `${rel}: appeared while this run was seeding it and does not carry the bundled body — something is writing there underneath this run; nothing further written, re-run when the tree is settled`, ...linesNow(true), ...notes, ...partialNote(writtenCount()));
+      return loud('race-unresolved', `${rel}: appeared while this run was seeding it and does not carry the bundled body — something is writing there underneath this run; nothing further written, re-run when the tree is settled`, ...linesNow(true), ...notes, ...partialNote(writtenCount()), ...tail);
     }
     fates.set(rel, write.kind !== 'refresh' && !result.created ? 'stood' : 'written');
     notes.push(...tmpNote(rel, result.tmpLeftBehind));
   }
   const landed = (kind) => writes.some((w) => w.kind === kind && fates.get(relOf(w)) === 'written');
-  return ok(tokenFor(landed('seed') || landed('store'), landed('refresh')), [...linesNow(false), ...notes]);
+  return ok(tokenFor(landed('seed') || landed('store'), landed('refresh')), [...linesNow(false), ...notes, ...tail]);
 };

package/tools/ensure-vocabulary.mjs

@@ -16,7 +16,8 @@ export const ENSURE_OPS = Object.freeze(['orchestration', 'gates', 'autonomy', '
 // Tokens that assert a WRITE happened. --dry-run may never emit one of these (the CLI's contract test
 // walks this set), and each has exactly one `would-` counterpart below. `refreshed` is the spec-layer
 // ensure's pair refresh (reader or checker) — a deployed script on a body a release shipped,
-// rewritten to the bundled one (a custom body is never refreshed).
+// rewritten to the bundled one; a custom body is rewritten only by the replace run the user's yes
+// starts (--replace-custom), never by a plain run.
 // `re-derived` is the executor ensure rewriting a placed executor whose bytes differ from the body derived from docs/ai/vehicles.json.
 export const WRITE_TOKENS = Object.freeze(['seeded', 'note-refreshed', 'refreshed', 'regenerated', 're-derived']);
 export const DRY_RUN_TOKENS = Object.freeze(['would-seed', 'would-refresh-note', 'would-refresh', 'would-regenerate', 'would-re-derive']);