@sabaiway/agent-workflow-kit 10.6.0 → 11.1.0

package/tools/fs-read-nofollow.mjs

@@ -5,7 +5,7 @@
 // no-follow read without a cycle. flow-store-read.mjs re-exports everything here, so every
 // existing consumer keeps its import site. Dependency-free, Node >= 22.
 
-import { readFileSync, lstatSync, openSync, closeSync, fstatSync, constants as fsConstants } from 'node:fs';
+import { readFileSync, readSync, lstatSync, openSync, closeSync, fstatSync, constants as fsConstants } from 'node:fs';
 
 // Local no-follow lstat (null ONLY on a true ENOENT).
 export const lstatNoFollowRead = (path, lstat = lstatSync) => {
@@ -24,6 +24,14 @@ export const describeNonRegular = (st) =>
 // ignoreBOM: a BOM must surface as malformed line 1, not vanish and get rewritten without it.
 const FATAL_UTF8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
 const hasOpenFlag = (v) => typeof v === 'number' && v !== 0;
+const errCode = (err) => (err && err.code) || (err && err.message) || null;
+// The open failures with a NAME of their own (shared by both readers); null for every other.
+const openFailure = (err) => {
+  if (err && err.code === 'ENOENT') return { outcome: 'absent' };
+  if (err && err.code === 'ELOOP') return { outcome: 'foreign', className: 'symlink', isDirectory: false };
+  if (err && err.code === 'EISDIR') return { outcome: 'foreign', className: 'directory', isDirectory: true };
+  return null;
+};
 
 // The ONE race-free read for store/lock bytes: open O_NOFOLLOW|O_NONBLOCK, fstat the DESCRIPTOR,
 // read through it, decode fatally — a pathname swapped after the open cannot change what the fd
@@ -89,9 +97,8 @@ const readNoFollowCore = (path, io, closeBox) => {
     }
     return { outcome: 'ok', content, dev: st.dev, ino: st.ino };
   } catch (err) {
-    if (err && err.code === 'ENOENT') return { outcome: 'absent' };
-    if (err && err.code === 'ELOOP') return { outcome: 'foreign', className: 'symlink', isDirectory: false };
-    if (err && err.code === 'EISDIR') return { outcome: 'foreign', className: 'directory', isDirectory: true };
+    const known = openFailure(err);
+    if (known !== null) return known;
     try {
       const st = lstatNoFollowRead(path, lstat);
       if (st && !st.isFile()) return { outcome: 'foreign', className: describeNonRegular(st), isDirectory: st.isDirectory() };
@@ -108,6 +115,51 @@ const readNoFollowCore = (path, io, closeBox) => {
   }
 };
 
+// readFileBytesNoFollowCapped(path, cap, io?) → ok { bytes } | over-cap { cap } | absent | foreign |
+// error — the control-byte gate's read: open O_NOFOLLOW|O_NONBLOCK, fstat the DESCRIPTOR for its
+// kind, read on it in bounded chunks until EOF or cap+1 bytes; the fstat SIZE is never consulted (a
+// file growing after the fstat still refuses); no decode (a lone 0xE9 is ok bytes); no lstat fallback.
+// ONE skeleton: no open without both flags; fstat the DESCRIPTOR; the body runs on a regular file only.
+const READ_CHUNK = 64 * 1024;
+const withRegularDescriptor = (path, io, body) => {
+  const consts = io.constants ?? fsConstants;
+  const open = io.open ?? openSync;
+  const fstat = io.fstat ?? fstatSync;
+  const close = io.close ?? closeSync;
+  if (!hasOpenFlag(consts.O_NONBLOCK) || !hasOpenFlag(consts.O_NOFOLLOW)) {
+    return { outcome: 'error', code: 'this platform exposes no usable O_NOFOLLOW|O_NONBLOCK open flags — refusing to open (fail closed)' };
+  }
+  let fd = null;
+  let result;
+  try {
+    fd = open(path, (consts.O_RDONLY ?? 0) | consts.O_NOFOLLOW | consts.O_NONBLOCK);
+    const st = fstat(fd);
+    result = st.isFile() ? body(fd) : { outcome: 'foreign', className: describeNonRegular(st), isDirectory: st.isDirectory() };
+  } catch (err) {
+    result = openFailure(err) ?? { outcome: 'error', code: errCode(err) ?? 'read failed' };
+  } finally {
+    if (fd !== null) {
+      try { close(fd); } catch (err) { result = { outcome: 'error', code: `descriptor close failed (${errCode(err) ?? 'close failed'}) — fail closed` }; }
+    }
+  }
+  return result;
+};
+// probeRegularFileNoFollow(path, io?) → ok | absent | foreign | error: the kind check alone, no read.
+export const probeRegularFileNoFollow = (path, io = {}) => withRegularDescriptor(path, io, () => ({ outcome: 'ok' }));
+export const readFileBytesNoFollowCapped = (path, cap, io = {}) => withRegularDescriptor(path, io, (fd) => {
+  const read = io.read ?? readSync;
+  const chunks = [];
+  let total = 0;
+  while (total <= cap) {
+    const chunk = Buffer.allocUnsafe(Math.min(READ_CHUNK, cap + 1 - total));
+    const n = read(fd, chunk, 0, chunk.length, null);
+    if (n === 0) break;
+    chunks.push(chunk.subarray(0, n));
+    total += n;
+  }
+  return total > cap ? { outcome: 'over-cap', cap } : { outcome: 'ok', bytes: Buffer.concat(chunks, total) };
+});
+
 // readFileBytesNoFollow(path, io?) → { outcome: 'ok', bytes } | absent | foreign | error — the
 // BYTES twin of the reader above for consumers whose domain is byte offsets (the Phase-4
 // receipt-deadline watermark, the finding-manifest digest domain): keepFd internally so the raw

package/tools/git-env.mjs

@@ -0,0 +1,120 @@
+// git-env.mjs — the kit's git-location leaf: WHICH repository a git spawn will talk to, judged by
+// AGREEMENT, never by a variable ban (measured 2026-08-31, git 2.43: an ambient GIT_DIR made three
+// consumers judge ANOTHER repository in silence; a killed git read as "not a git work tree", a pass).
+// The six-state table, the GIT_* strip, the hermetic env, the ls-files parser. A pure LEAF.
+
+import { realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+export const GIT_MAX_BUFFER = 256 * 1024 * 1024;
+export const GIT_LOCATION_STATES = Object.freeze(['work-tree', 'not-a-repository', 'error', 'redirected', 'no-work-tree', 'env-only']);
+const LOCATION_VARIABLES = 'GIT_DIR / GIT_WORK_TREE / GIT_COMMON_DIR';
+
+// ASCII-case-insensitive prefix (a case-insensitive host honours `git_dir` as GIT_DIR) — an ASCII
+// class, never toUpperCase(): Unicode case folding would also strip a foreign `g<dotless-i>t_dir`.
+export const stripGitLocationEnv = (env) => Object.fromEntries(Object.entries(env).filter(([key]) => !/^[Gg][Ii][Tt]_/.test(key)));
+
+// The test fixtures' env, never a consumer's: the strip plus every host-reaching knob pinned.
+export const hermeticGitEnv = (env, home) => ({
+  ...stripGitLocationEnv(env),
+  HOME: home, XDG_CONFIG_HOME: home, GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_SYSTEM: '/dev/null',
+  GIT_CONFIG_NOSYSTEM: '1', GIT_ATTR_NOSYSTEM: '1', LC_ALL: 'C',
+});
+
+// An env naming no PATH (a partial override, a test's `{}`) borrows the process PATH; one naming a PATH is honoured as is.
+export const withGitPath = (env) => (env.PATH === undefined && process.env.PATH !== undefined ? { ...env, PATH: process.env.PATH } : env);
+
+// `ls-files -s -z` records: mode, object, stage, TAB, then the path BYTES up to the NUL — undecoded.
+export const parseIndexEntries = (buf) => {
+  const entries = [];
+  for (let start = 0; start < buf.length;) {
+    let end = buf.indexOf(0, start);
+    if (end === -1) end = buf.length;
+    const record = buf.subarray(start, end);
+    const tab = record.indexOf(0x09);
+    if (tab !== -1) {
+      const [mode, sha, stage] = record.subarray(0, tab).toString('utf8').split(' ');
+      entries.push({ mode, sha, stage: Number(stage), path: record.subarray(tab + 1) });
+    }
+    start = end + 1;
+  }
+  return entries;
+};
+
+const NOT_A_REPOSITORY = /not a git repository/u;
+const NO_WORK_TREE = /must be run in a work tree/u;
+
+// ONE rev-parse identity per spawn → ok { line } | not-a-repository | no-work-tree | error (a throw,
+// ENOENT, a signal, any other exit, an EMPTY answer). The answer is the stdout minus exactly one
+// terminating LF — never a split: a path may carry a newline. LC_ALL=C pins git's own wording.
+const probe = (arg, { cwd, env, spawn }) => {
+  let r;
+  try {
+    r = spawn('git', ['rev-parse', arg], { cwd, env: { ...withGitPath(env), LC_ALL: 'C' }, maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
+  } catch (err) {
+    return { kind: 'error', cause: `git threw synchronously (${err?.message ?? err})` };
+  }
+  if (r == null || typeof r !== 'object') return { kind: 'error', cause: 'the git runner returned no result' };
+  if (r.error) return { kind: 'error', cause: `git could not run (${r.error.code ?? r.error.message ?? r.error})` };
+  if (r.signal) return { kind: 'error', cause: `git rev-parse ${arg} was killed by ${r.signal}` };
+  const stderr = String(r.stderr ?? '').trim();
+  if (r.status === 128 && NOT_A_REPOSITORY.test(stderr)) return { kind: 'not-a-repository', cause: stderr };
+  if (r.status === 128 && NO_WORK_TREE.test(stderr)) return { kind: 'no-work-tree', cause: stderr };
+  if (r.status !== 0) return { kind: 'error', cause: `git rev-parse ${arg} exited ${r.status}${stderr ? ` (${stderr})` : ''}` };
+  const line = String(r.stdout ?? '').replace(/\n$/u, '');
+  if (line.length === 0) return { kind: 'error', cause: `git rev-parse ${arg} answered nothing` };
+  return { kind: 'ok', line };
+};
+
+const identity = (cwd, line, realpath) => {
+  try { return { ok: true, path: realpath(resolve(cwd, line)) }; } catch (err) { return { ok: false, cause: `${line} cannot be resolved (${err?.code ?? err?.message ?? err})` }; }
+};
+
+const located = (state, cause, facts = {}) => ({ state, cause, top: null, gitDir: null, commonDir: null, ...facts });
+
+// resolveGitLocation(cwd, { spawn, env, realpath }) → { state, cause, top, gitDir, commonDir }: the
+// REALPATH identity of the git dir, the common dir and the work-tree top, ambient env vs the
+// GIT_-stripped discovery from cwd. Only `work-tree` proceeds.
+export const resolveGitLocation = (cwd, deps = {}) => {
+  const spawn = deps.spawn ?? spawnSync;
+  const env = deps.env ?? process.env;
+  const realpath = deps.realpath ?? realpathSync;
+  const ambient = { cwd, env, spawn };
+  const stripped = { cwd, env: stripGitLocationEnv(env), spawn };
+  // Precedence (fail closed): the GIT DIR probes decide whether each discovery reaches a repository;
+  // the COMMON DIR and TOP probes then owe ok (or no-work-tree for the top) — anything else is error.
+  const a = probe('--absolute-git-dir', ambient);
+  const s = probe('--absolute-git-dir', stripped);
+  if (a.kind === 'error' || a.kind === 'no-work-tree') return located('error', a.cause);
+  if (s.kind === 'error' || s.kind === 'no-work-tree') return located('error', `under the GIT_-stripped discovery from ${cwd}: ${s.cause}`);
+  if (a.kind === 'not-a-repository' && s.kind === 'not-a-repository') return located('not-a-repository', a.cause);
+  if (a.kind === 'not-a-repository') return located('redirected', `the ambient git environment (${LOCATION_VARIABLES}) reaches no repository (${a.cause}) while the discovery from ${cwd} does`);
+  if (s.kind === 'not-a-repository') return located('env-only', `the ambient git environment (${LOCATION_VARIABLES}) reaches the git dir ${a.line} while the GIT_-stripped discovery from ${cwd} reaches no repository (${s.cause})`);
+  const ids = {};
+  const ac = probe('--git-common-dir', ambient);
+  const sc = probe('--git-common-dir', stripped);
+  if (ac.kind !== 'ok') return located('error', `the common dir under the ambient git environment: ${ac.cause}`);
+  if (sc.kind !== 'ok') return located('error', `the common dir under the GIT_-stripped discovery: ${sc.cause}`);
+  for (const [name, ax, sx] of [['git dir', a, s], ['common dir', ac, sc]]) {
+    const x = identity(cwd, ax.line, realpath);
+    const y = identity(cwd, sx.line, realpath);
+    if (!x.ok) return located('error', `the ${name} under the ambient git environment: ${x.cause}`);
+    if (!y.ok) return located('error', `the ${name} under the GIT_-stripped discovery: ${y.cause}`);
+    if (x.path !== y.path) return located('redirected', `the ${name} differs: the ambient git environment (${LOCATION_VARIABLES}) resolves it to ${x.path}, the discovery from ${cwd} to ${y.path}`);
+    ids[name] = x.path;
+  }
+  const at = probe('--show-toplevel', ambient);
+  const st = probe('--show-toplevel', stripped);
+  if (at.kind === 'error' || at.kind === 'not-a-repository') return located('error', at.cause);
+  if (st.kind === 'error' || st.kind === 'not-a-repository') return located('error', `under the GIT_-stripped discovery from ${cwd}: ${st.cause}`);
+  if (at.kind === 'no-work-tree' && st.kind === 'no-work-tree') return located('no-work-tree', `the git dir ${ids['git dir']} agrees but git names no work tree (${at.cause})`);
+  if (at.kind === 'no-work-tree') return located('redirected', `the ambient git environment (${LOCATION_VARIABLES}) names no work tree (${at.cause}) while the discovery from ${cwd} reaches one`);
+  if (st.kind === 'no-work-tree') return located('redirected', `the ambient git environment (${LOCATION_VARIABLES}) reaches a work tree at ${at.line} while the discovery from ${cwd} names none (${st.cause})`);
+  const x = identity(cwd, at.line, realpath);
+  const y = identity(cwd, st.line, realpath);
+  if (!x.ok) return located('error', `the work-tree top under the ambient git environment: ${x.cause}`);
+  if (!y.ok) return located('error', `the work-tree top under the GIT_-stripped discovery: ${y.cause}`);
+  if (x.path !== y.path) return located('redirected', `the work-tree top differs: the ambient git environment (${LOCATION_VARIABLES}) resolves it to ${x.path}, the discovery from ${cwd} to ${y.path}`);
+  return located('work-tree', null, { top: at.line, gitDir: ids['git dir'], commonDir: ids['common dir'] });
+};

package/tools/grounding.mjs

@@ -33,6 +33,7 @@ import { spawnSync } from 'node:child_process';
 import { isDirectRun } from './direct-run.mjs';
 import { fail } from './orchestration-config.mjs';
 import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
+import { stripGitLocationEnv } from './git-env.mjs';
 // (f) --autonomy (AD-044 Plan 3): the effective per-project autonomy policy for the facts payload.
 // READ core only — never autonomy-write.mjs (the import-split invariant).
 import { AUTONOMY_REL, loadAutonomy, resolveAutonomy, isSparseSeedConfig } from './autonomy-config.mjs';
@@ -163,9 +164,9 @@ const systemTempRoots = () => [...new Set([tmpdir(), process.env.TMPDIR, '/tmp']
 
 const gitLine = (args, cwd) => {
   // Ambient GIT_* location vars (GIT_DIR / GIT_WORK_TREE / …) would let rev-parse prove a FOREIGN
-  // tree — every location answer must come from cwd alone, for every gitLine consumer.
-  const env = Object.fromEntries(Object.entries(process.env).filter(([k]) => !/^GIT_/i.test(k)));
-  const r = spawnSync('git', args, { cwd, env, encoding: 'utf8', windowsHide: true });
+  // tree — every location answer must come from cwd alone, for every gitLine consumer. The strip
+  // is the git-env leaf's (GIT_* only — never the test fixtures' hermetic pins).
+  const r = spawnSync('git', args, { cwd, env: stripGitLocationEnv(process.env), encoding: 'utf8', windowsHide: true });
   return r.error || r.status == null ? null : { status: r.status, stdout: r.stdout ?? '' };
 };
 

package/tools/plan-shape-facts.mjs

@@ -1,6 +1,7 @@
 import { lstatSync, readdirSync, realpathSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
+import { classIds, readShippedRobustnessLiterals } from './robustness-literals.mjs';
 import { segmentPrefixOf, validateSourceSizeConfig } from './source-size-config.mjs';
 import { getLineCount, isSweep, resolveAnchorCandidates, unique } from './plan-shape.mjs';
 
@@ -83,6 +84,14 @@ const loadPractice = (root) => {
   }
 };
 
+const loadRobustClasses = (deps) => {
+  try {
+    return classIds(readShippedRobustnessLiterals(deps));
+  } catch (error) {
+    throw usageError(`robustness-literals list is unreadable (${error.message})`);
+  }
+};
+
 const isInScope = (path, config) => Boolean(config &&
   config.roots.some((root) => segmentPrefixOf(root, path)) &&
   !config.exclude.some((excluded) => segmentPrefixOf(excluded, path)) &&
@@ -111,6 +120,12 @@ const compileGlob = (pattern) => {
   }
 };
 
+const expandPatterns = (repoFiles, patterns) => Object.fromEntries(patterns.map((pattern) => {
+  const compiled = compileGlob(pattern);
+  if (!compiled) throw planError(`unsupported glob in plan path: ${pattern}`);
+  return [pattern, repoFiles.filter((path) => compiled.test(path))];
+}));
+
 const matchFilesEntry = (entry, ownedPath) => {
   const normalized = entry.replace(/^\.\//, '').replace(/\/$/, '');
   if (normalized === '' || normalized === '.') return { known: true, matches: true };
@@ -185,20 +200,18 @@ const describePath = (root, path, practice, repoFiles, packageCache) => {
   };
 };
 
-export const openRepo = (root) => {
+export const openRepo = (root, { robustnessDeps } = {}) => {
   const repoRoot = realpathSync(root);
-  return { repoRoot, repoFiles: walkRegularFiles(repoRoot), practice: loadPractice(repoRoot), packageCache: new Map() };
+  return { repoRoot, repoFiles: walkRegularFiles(repoRoot), practice: loadPractice(repoRoot), robustClasses: loadRobustClasses(robustnessDeps), packageCache: new Map() };
 };
 
-export const buildFacts = (root, { paths = [], repo = openRepo(root) } = {}) => {
-  const { repoRoot, repoFiles, practice, packageCache } = repo;
-  const expansions = Object.fromEntries(paths.filter(isSweep).map((pattern) => {
-    const compiled = compileGlob(pattern);
-    if (!compiled) throw planError(`unsupported glob in plan path: ${pattern}`);
-    return [pattern, repoFiles.filter((path) => compiled.test(path))];
-  }));
+export const expandSweepPaths = (root, patterns) => expandPatterns(walkRegularFiles(realpathSync(root)), patterns);
+
+export const buildFacts = (root, { paths = [], robustnessDeps, repo = openRepo(root, { robustnessDeps }) } = {}) => {
+  const { repoRoot, repoFiles, practice, robustClasses, packageCache } = repo;
+  const expansions = expandPatterns(repoFiles, paths.filter(isSweep));
   const allPaths = unique([...paths, ...Object.values(expansions).flat()]);
   const pathFacts = Object.fromEntries(allPaths.map((path) => [path, describePath(repoRoot, path, practice, repoFiles, packageCache)]));
   const candidates = (suffix, precedingPaths = []) => resolveAnchorCandidates(repoFiles, suffix, precedingPaths);
-  return { capDeclared: practice.capDeclared, cap: practice.cap, pathFacts, expansions, repoFiles, candidates };
+  return { capDeclared: practice.capDeclared, cap: practice.cap, robustClasses, pathFacts, expansions, repoFiles, candidates };
 };

package/tools/plan-shape.mjs

@@ -1,4 +1,5 @@
 import { tokenizeMarkdown } from '../references/scripts/markdown-blocks.mjs';
+import { parseRobustTag } from './robustness-literals.mjs';
 
 export const PLAN_TITLE_PREFIX = '# Plan: ';
 export const PLAN_HEADINGS = Object.freeze([
@@ -243,8 +244,15 @@ const getCurrentLines = (rows, facts, verbs) => rows
 const checkAuthoring = (parsed, facts) => {
   const findings = [];
   const bullets = getVerificationBullets(parsed.document);
+  const robustClasses = new Set(facts.robustClasses ?? []);
   for (const [index, row] of parsed.rows.entries()) {
     if (!row.valid) continue;
+    const robust = parseRobustTag(row.responsibility);
+    const unknownRobustClass = robust.classes?.find((classId) => !robustClasses.has(classId));
+    if (robust.refusal || unknownRobustClass !== undefined) {
+      const reason = robust.refusal ? `tag grammar refused ${robust.refusal}` : `class ${unknownRobustClass} is not in the shipped list`;
+      findings.push(makeFinding(row.line, 'robust-class', `${row.id} robust tag: ${reason}`, row.id));
+    }
     const paths = getConcretePaths(row, facts);
     const expectedKind = row.verb === 'create' ? 'absent' : 'regular';
     if (paths.length === 0 && isSweep(row.path)) findings.push(makeFinding(row.line, 'kind', `${row.id} sweep resolves to no regular path`, row.id));

package/tools/procedures.mjs

@@ -424,6 +424,7 @@ const foldScopeAdvice = (activity, config, plans) => {
 // only what no canon can: the POPULATED checker commands, and the session register they read. The
 // register is NEVER defaulted by the tool — naming it here is the whole point of the block.
 export const SPEC_CHECK_TOOL = join(dirname(fileURLToPath(import.meta.url)), 'spec-check-cli.mjs');
+export const ROBUSTNESS_BRIEF_TOOL = join(dirname(fileURLToPath(import.meta.url)), 'robustness-brief.mjs');
 const SPEC_OPS_REGISTER = `${PLANS_REL}/spec-ops.list`;
 const specCheckAdvice = (activity) => {
   if (activity !== 'plan-execution') return [];
@@ -435,6 +436,16 @@ const specCheckAdvice = (activity) => {
   ];
 };
 
+const robustnessBriefAdvice = (activity, plans) => {
+  if (activity !== 'plan-execution') return [];
+  const operand = populatedPlan(plans);
+  return [
+    'Robustness brief (every tagged ledger row) — generate the concrete literals before dispatch:',
+    `  • node ${renderToolPath(ROBUSTNESS_BRIEF_TOOL)} --plan ${operand ?? '<plan-file>'}`,
+    ...planDiscoveryCaveat(plans, '--plan', 'populate --plan with the plan in flight.', operand === null ? ['--plan'] : []),
+  ];
+};
+
 // The cost-lane advisory block (cost-tiered execution — orchestration.md §5 canon, paraphrased
 // at the point of use like reviewLoopAdvice paraphrases procedures.md Fold + loop / orchestration §4). Rendered UNCONDITIONALLY for
 // every activity — the lanes route EVERY step, review-backed or not (unlike reviewLoopAdvice,
@@ -596,7 +607,7 @@ const foldLaneAdvice = ({
   return foldLaneLines(judgeLedger(ledger, { backend: HELD_RECEIPT_BACKEND, degrades: [] }));
 };
 
-const formatHuman = ({ activity, section, slots, warnings, plans, autonomy, flowHalves, flowArmed, readersSweep, declaredPractice, foldScope, specCheck, foldLane }) => {
+const formatHuman = ({ activity, section, slots, warnings, plans, autonomy, flowHalves, flowArmed, readersSweep, declaredPractice, foldScope, specCheck, robustnessBrief, foldLane }) => {
   const lines = [
     section,
     '',
@@ -628,6 +639,7 @@ const formatHuman = ({ activity, section, slots, warnings, plans, autonomy, flow
   if (advice.length) lines.push('', ...advice);
   if (foldScope.length) lines.push('', ...foldScope);
   if (specCheck.length) lines.push('', ...specCheck);
+  if (robustnessBrief.length) lines.push('', ...robustnessBrief);
   lines.push('', ...costLanesAdvice());
   if (declaredPractice.length) lines.push('', ...declaredPractice);
   if (warnings.length) {
@@ -637,7 +649,7 @@ const formatHuman = ({ activity, section, slots, warnings, plans, autonomy, flow
   return lines.join('\n');
 };
 
-const buildJson = ({ activity, section, slots, configSource, warnings, plans, autonomy, flowHalves, flowArmed, readersSweep, declaredPractice, foldScope, specCheck, foldLane }) => ({
+const buildJson = ({ activity, section, slots, configSource, warnings, plans, autonomy, flowHalves, flowArmed, readersSweep, declaredPractice, foldScope, specCheck, robustnessBrief, foldLane }) => ({
   activity,
   section,
   slots: Object.fromEntries(
@@ -658,6 +670,7 @@ const buildJson = ({ activity, section, slots, configSource, warnings, plans, au
   foldScope,
   // ADDITIVE (spec layer 2b): the spec-store block, structured (empty outside plan-execution).
   specCheck,
+  robustnessBrief,
   foldLane,
   // ADDITIVE (AD-044 Plan 4): the per-activity autonomy block, structured (empty when unresolvable).
   autonomy: autonomyAdvice(activity, autonomy),
@@ -752,6 +765,7 @@ export const main = (argv, ctx = {}) => {
     const declaredPractice = declaredPracticeAdvice(cwd, readFile, lstat);
     const foldScope = foldScopeAdvice(activity, config, plans);
     const specCheck = specCheckAdvice(activity);
+    const robustnessBrief = robustnessBriefAdvice(activity, plans);
     const foldLane = foldLaneAdvice({
       activity,
       slots,
@@ -763,8 +777,8 @@ export const main = (argv, ctx = {}) => {
       readHead: ctx.readHeadInstant,
     });
     const stdout = json
-      ? JSON.stringify(buildJson({ activity, section, slots, configSource, warnings, plans, autonomy, flowHalves, flowArmed: flowState?.armed === true, readersSweep, declaredPractice, foldScope, specCheck, foldLane }), null, 2)
-      : formatHuman({ activity, section, slots, warnings, plans, autonomy, flowHalves, flowArmed: flowState?.armed === true, readersSweep, declaredPractice, foldScope, specCheck, foldLane });
+      ? JSON.stringify(buildJson({ activity, section, slots, configSource, warnings, plans, autonomy, flowHalves, flowArmed: flowState?.armed === true, readersSweep, declaredPractice, foldScope, specCheck, robustnessBrief, foldLane }), null, 2)
+      : formatHuman({ activity, section, slots, warnings, plans, autonomy, flowHalves, flowArmed: flowState?.armed === true, readersSweep, declaredPractice, foldScope, specCheck, robustnessBrief, foldLane });
     if (autonomy?.error) {
       return { code: 1, stdout, stderr: `procedures: malformed ${AUTONOMY_REL} — ${autonomy.error}` };
     }

package/tools/recommendations.mjs

@@ -83,6 +83,7 @@ import { DEFAULT_BUNDLE_ROOT } from './bridge-settings-read.mjs';
 import { assertContainedRealPath } from './fs-safe.mjs';
 import { loadWorktreesConfig, resolveProbeDir } from './worktrees.mjs';
 import { preflightCheapAgents, EXECUTOR_VEHICLE } from './cheap-agents.mjs';
+import { NODE_EVIDENCE, NODE_EVIDENCE_SCRIPTS, probeNodeEvidence } from './node-evidence.mjs';
 // The vehicle READINESS comes from the read-only half — the same survey `recipes` and `status` read.
 import { surveyExecutorVehicle, readStamp, readFsDeps, WORKFLOW_STAMP, EXPECTED_WORKFLOW_VERSION } from './cheap-agents-read.mjs';
 // The ack store's path, keys, lane registry, fingerprint and guarded reader live in their own leaf
@@ -108,7 +109,12 @@ export { ACKS_FILE, ACKS_LANE_KEY, ACKS_WORKTREES_DIR_KEY, ACKS_COVERAGE_DOMAIN_
 const HERE = dirname(fileURLToPath(import.meta.url));
 const toolPath = (rel) => join(HERE, rel);
 const q = shellQuoteArg;
-
+const ENFORCEMENT_ABSENT_CODE = 'ENOENT';
+const ENFORCEMENT_KIT_ROOT = resolve(HERE, '..');
+const ENFORCEMENT_BUNDLE_ROOT = join(ENFORCEMENT_KIT_ROOT, 'references', 'scripts');
+const ENFORCEMENT_WHAT = 'the enforcement scripts are not deployed beside docs/ai (no Node evidence) \u2014 the offer copies them and installs the pre-commit hook';
+const ENFORCEMENT_APPLY_TEMPLATE = 'HAND-APPLY: mkdir -p {root}/scripts && cp {kit}/references/scripts/*.mjs {root}/scripts/ && node {root}/scripts/install-git-hooks.mjs';
+const COMMIT_GUARD_INSTALLER_REMEDY = 'the hook installer (scripts/install-git-hooks.mjs) is not deployed \u2014 deploy the enforcement scripts (bootstrap steps 8\u20139) and install the hook, then re-run';
 // ── the section contract tokens (doc-parity-bound in upgrade.md + the mode doc) ────────────────
 export const RECOMMENDATIONS_SECTION_HEADER = '## Recommendations (agent-workflow)';
 export const RECOMMENDATIONS_EMPTY_LINE = 'no recommendations — flow optimal.';
@@ -166,6 +172,7 @@ export const SEVERITIES = Object.freeze({
   // offer to enable something.
   'gate-hook.marker-stale': SEVERITY_ATTENTION,
   'commit-guard': SEVERITY_OPTIONAL,
+  enforcement: SEVERITY_OPTIONAL,
   'read-lane': SEVERITY_OPTIONAL,
   'read-lane.stale': SEVERITY_ATTENTION,
   'read-lane.missing': SEVERITY_ATTENTION,
@@ -249,6 +256,7 @@ export const WHATS = Object.freeze({
   'gate-hook': '{n} declared gate(s) prompt per run — the gate-approval hook is not wired',
   'gate-hook.marker-stale': 'the declaration carries the lcovProducer key but the placed hook predates it — the hook goes dark and every gate prompts',
   'commit-guard': 'the gate matrix is final-run-capable but no commit-guard arms the pre-commit hook — a commit needs no green receipt yet',
+  enforcement: ENFORCEMENT_WHAT,
   'read-lane': 'the gate hook is wired but the read-only compound lane is off — pipes/chains of seeded reads still prompt one by one',
   'read-lane.stale': 'the read-lane is ON but the placed gate hook is stale — an old hook never reads lanes.json, so the lane is silently dark; reseed it',
   'read-lane.missing': 'the gate hook is wired but its placed file is missing — every Bash call errors and the read-lane is dark; re-place it',
@@ -313,6 +321,7 @@ export const BENEFITS = Object.freeze({
   'source-size': 'maintainability — a module you can hold whole stays reviewable, and size drift becomes recorded, reasoned debt',
   'gate-hook': 'velocity — your own declared gate commands auto-approve byte-exactly (opt-in PreToolUse hook)',
   'commit-guard': 'integrity — commits require the ONE green --final receipt at the exact staged fingerprint (consented pre-commit arm)',
+  enforcement: 'enforcement — bundled checks and the pre-commit hook keep caps, archives, and the generated index current',
   'read-lane': 'velocity — pipes/chains of your seeded read-only commands auto-approve instead of prompting (opt-in, conservatively classified)',
   'state-block': 'no silent stalls — a turn ending on «you are not needed», or on work it never started, warns at once instead of waiting to be spotted',
   'mcp-channel': 'velocity — path facts and literal searches arrive as typed tool calls whose arguments are JSON fields, never a shell string',
@@ -361,6 +370,7 @@ export const OPT_IN_CAPABILITIES = Object.freeze([
   { id: 'gate-hook', mode: 'hook', advisorKey: 'gate-hook' },
   { id: 'read-lane', mode: 'hook', advisorKey: 'read-lane' },
   { id: 'commit-guard', mode: 'commit-guard', advisorKey: 'commit-guard' },
+  { id: 'enforcement', mode: 'bootstrap', advisorKey: 'enforcement' },
   { id: 'state-block', mode: 'state-block-guard', advisorKey: 'state-block' },
   { id: 'sandbox-masks', mode: 'sandbox-masks', advisorKey: 'sandbox-masks' },
   { id: 'mcp-channel', mode: 'mcp', advisorKey: 'mcp-channel' },
@@ -843,7 +853,7 @@ const probeCommitGuard = ({ root, deps, add, skip }) => {
     if (!isFinalCapableDeclaration(gates, root)) return; // no receipt to guard yet — no offer
     const installer = join(root, 'scripts', 'install-git-hooks.mjs');
     if (!(deps.exists ?? existsSync)(installer)) {
-      skip('commit-guard', new Error('the hook installer (scripts/install-git-hooks.mjs) is not deployed — run upgrade first'));
+      skip('commit-guard', new Error(COMMIT_GUARD_INSTALLER_REMEDY));
       return;
     }
     const hooksPath = (deps.gitHooksPath ?? resolveGitHooksPath)(root);
@@ -866,6 +876,45 @@ const probeCommitGuard = ({ root, deps, add, skip }) => {
   }
 };
 
+const readEnforcementNode = (path, lstat) => {
+  try {
+    return lstat(path);
+  } catch (err) {
+    if (err?.code === ENFORCEMENT_ABSENT_CODE) return null;
+    throw new Error(`${path}: ${err?.code ?? err?.message ?? err}`);
+  }
+};
+
+export const probeEnforcement = ({ root, deps, add, skip }) => {
+  try {
+    const lstat = deps.lstat ?? lstatSync;
+    const docsAi = join(root, 'docs', 'ai');
+    const docsAiNode = readEnforcementNode(docsAi, lstat);
+    if (docsAiNode === null) return;
+    if (!docsAiNode.isDirectory()) throw new Error(`${docsAi} is not a plain directory`);
+    const evidence = probeNodeEvidence(root, lstat);
+    if (evidence.state === NODE_EVIDENCE.PACKAGE_JSON || evidence.state === NODE_EVIDENCE.DEPLOYED_SCRIPTS) return;
+    if (evidence.state === NODE_EVIDENCE.UNREADABLE) throw new Error(`${root}: ${evidence.error}`);
+    if (evidence.state !== NODE_EVIDENCE.NONE) throw new Error(`unknown Node-evidence state: ${evidence.state}`);
+    if (evidence.wrongKind.length > 0) throw new Error(join(root, evidence.wrongKind[0]));
+    const readDir = deps.readdir ?? readdirSync;
+    const bundleRoot = deps.scriptsBundleRoot ?? ENFORCEMENT_BUNDLE_ROOT;
+    const bundleBasenames = readDir(bundleRoot).filter((name) => name.endsWith('.mjs')).sort();
+    if (NODE_EVIDENCE_SCRIPTS.some((name) => !bundleBasenames.includes(name))) throw new Error(`${bundleRoot}: a runnable enforcement script is missing`);
+    const scripts = join(root, 'scripts');
+    const scriptsNode = readEnforcementNode(scripts, lstat);
+    if (scriptsNode !== null && !scriptsNode.isDirectory()) throw new Error(`${scripts} is not a plain directory`);
+    for (const basename of scriptsNode === null ? [] : bundleBasenames) {
+      const destination = join(scripts, basename);
+      if (readEnforcementNode(destination, lstat) === null) continue;
+      throw new Error(`${destination} already exists; the enforcement copy would clobber it`);
+    }
+    add('enforcement', ENFORCEMENT_WHAT, fillTemplate(ENFORCEMENT_APPLY_TEMPLATE, { root: q(root), kit: q(ENFORCEMENT_KIT_ROOT) }));
+  } catch (err) {
+    skip('enforcement', err);
+  }
+};
+
 // The read-lane offer (AD-055 Part II, Help-through-Recommendations): once the gate hook is PLACED
 // and WIRED, offer to enable the opt-in read-only compound lane. Mutually exclusive with the
 // gate-hook item BY CONSTRUCTION — that item keys on `!wired`, this one on `wired` — so an unplaced
@@ -1242,7 +1291,7 @@ const readReadLaneToggle = (root, deps) => {
 // D3: the risk-marked keys — every key here has a per-item posture note in the mode doc, surfaced
 // at the consent moment; the static contract test asserts EXACT bidirectional coverage
 // (risk-marked keys == mode-doc note keys — a dropped note goes red, not silent).
-export const RISK_NOTED_KEYS = Object.freeze(['sandbox-lane', 'read-lane', 'worktrees-dir', 'adr-store-migration', 'gates-inert', 'source-size', 'gate-hook', 'mcp-channel', 'spec-adoption']);
+export const RISK_NOTED_KEYS = Object.freeze(['sandbox-lane', 'read-lane', 'worktrees-dir', 'adr-store-migration', 'gates-inert', 'source-size', 'gate-hook', 'mcp-channel', 'spec-adoption', 'enforcement']);
 
 // The feature-spec layer's adoption state (contract: kit/spec-adoption). The canon lets a plan cite
 // zero governing specs while a project adopts the layer, and nothing ever said whether adoption had
@@ -1547,6 +1596,7 @@ const PROBES = Object.freeze([
   probeGatesInert,
   probeSourceSize,
   probeCommitGuard,
+  probeEnforcement,
   probeReadLane,
   probeStateBlockHook,
   probeCheapAgents,

package/tools/repo-lex.mjs

@@ -39,6 +39,35 @@ const LINE_BREAKING_ALL = new RegExp(LINE_BREAKING_SOURCE, 'gu');
 export const isRenderableLine = (value) => typeof value === 'string' && !LINE_BREAKING.test(value);
 export const escapeForDisplay = (value) => String(value).replace(LINE_BREAKING_ALL, (ch) => `\\u${ch.codePointAt(0).toString(16).padStart(4, '0')}`);
 
+// The control-byte gate's predicate over ONE byte (an integer 0..255, a Buffer element): C0 minus
+// TAB, LF and CR, plus DEL. Bytes at or above 0x80 are never judged here (UTF-8 validity and C1
+// controls are the gate's stated non-goals). ONE home, beside the artifact-path rule below, which
+// keeps refusing TAB, LF and CR as its bash twins do.
+export const isRefusedControlByte = (byte) => byte <= 0x08 || byte === 0x0b || byte === 0x0c || (byte >= 0x0e && byte <= 0x1f) || byte === 0x7f;
+
+// The injective renderer of a path's raw BYTES for a report line: bytes decode as UTF-8 where a
+// sequence is valid, every LINE_BREAKING code point and a valid U+FFFD render as \u{XXXX}, an invalid
+// byte as \xNN and a backslash as \\ — so two names differing only in an unrenderable byte render differently,
+// a name carrying a raw byte differs from a name spelling its escape, and no output line carries a
+// raw control byte or U+FFFD. Separate from escapeForDisplay, whose string-rendering consumers keep their contract.
+const utf8SequenceLength = (lead) => (lead < 0x80 ? 1 : (lead & 0xe0) === 0xc0 ? 2 : (lead & 0xf0) === 0xe0 ? 3 : (lead & 0xf8) === 0xf0 ? 4 : 0);
+export const renderPathForDisplay = (bytes) => {
+  let out = '';
+  for (let i = 0; i < bytes.length;) {
+    const length = utf8SequenceLength(bytes[i]);
+    const slice = length > 0 && i + length <= bytes.length ? bytes.subarray(i, i + length) : null;
+    const decoded = slice === null ? null : slice.toString('utf8');
+    if (decoded === null || !Buffer.from(decoded, 'utf8').equals(slice)) {
+      out += `\\x${bytes[i].toString(16).padStart(2, '0')}`;
+      i += 1;
+      continue;
+    }
+    out += decoded === '\\' ? '\\\\' : LINE_BREAKING.test(decoded) || decoded.codePointAt(0) === 0xfffd ? `\\u{${decoded.codePointAt(0).toString(16)}}` : decoded;
+    i += length;
+  }
+  return out;
+};
+
 // The receipt encoder's carriability rule for an artifact path (S21), the JS twin of the wrappers'
 // refuse_uncarriable_artifact_byte: a quote, a backslash, a C0 control or DEL — deliberately NOT
 // \p{Cc} (C1 is the declared residual, and the two normalizations are parity-pinned on this set).