@sabaiway/agent-workflow-kit 10.6.0 → 11.0.0

package/tools/review-state.mjs

@@ -21,8 +21,8 @@
 //           the tree is clean (nothing to review — under a non-solo review obligation the PASS
 //           still NAMES every plan in flight and states that the gate arms as soon as the tree
 //           turns dirty, so a latent arm is discoverable before it blocks a pending commit); when
-//           the cwd is not a git work tree
-//           (the gate can never arm there, so nothing is announced); and when
+//           git ITSELF answers not-a-repository under both discoveries (the ONLY non-work-tree
+//           location that passes; the five other states refuse by name); and when
 //           the obligations are SATISFIED: under `reviewed`, >=1 backend's latest normal receipt
 //           attests SHIP-CLASS (ship / ship with nits) for the current tree; under `council`,
 //           EVERY review-capable backend attests ship-class OR carries an explicit current-tree
@@ -109,7 +109,8 @@ import { selectReliedOnReceipt, evaluateVetoOverride, evaluateInternalAttestatio
 // in leaf modules so the procedures read surface reaches them without this module's write-API
 // graph; re-exported here so every historical consumer keeps its import site.
 import { PLANS_REL, isScratchPlanName, plansInFlight } from './plan-files.mjs';
-import { shellQuoteArg } from './repo-lex.mjs';
+import { escapeForDisplay, shellQuoteArg } from './repo-lex.mjs';
+import { GIT_MAX_BUFFER, resolveGitLocation, stripGitLocationEnv, withGitPath } from './git-env.mjs';
 import { readDelegationLedger } from './dispatch-store-read.mjs';
 import {
   decideHeldSession, HELD_EXECUTE_WRAPPER, HELD_RECEIPT_BACKEND, judgeLedger,
@@ -148,7 +149,6 @@ export {
 const ACTIVITY = 'plan-execution';
 const SLOT = 'review';
 const CORE_EVIDENCE_TOOL = shellQuoteArg(join(dirname(fileURLToPath(import.meta.url)), 'core-evidence.mjs'));
-const GIT_MAX_BUFFER = 256 * 1024 * 1024; // a full-tree diff can be large; never truncate silently
 // --await (BUGFREE-3 / AD-049, item (d)) bounds + poll cadence. The default timeout is generous —
 // a real grounded bridge review can take minutes — and every value is overridable (--timeout / the
 // injectable clock) so hermetic tests never spend wall-clock.
@@ -157,18 +157,18 @@ export const AWAIT_POLL_MS = 5000;
 
 // ── git plumbing (read-only queries; injectable for tests) ─────────────────────────
 
-const gitRaw = (args, cwd) =>
-  spawnSync('git', args, { cwd, maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
+const gitRaw = (args, cwd, env) =>
+  spawnSync('git', args, { cwd, env: withGitPath(env ?? process.env), maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
 
 // stdout Buffer of a git query, or null when git fails (not a repo / git absent).
-const gitBuf = (args, cwd) => {
-  const r = gitRaw(args, cwd);
+const gitBuf = (args, cwd, env) => {
+  const r = gitRaw(args, cwd, env);
   if (r.error || r.status !== 0) return null;
   return r.stdout;
 };
 
-const gitLine = (args, cwd) => {
-  const buf = gitBuf(args, cwd);
+const gitLine = (args, cwd, env) => {
+  const buf = gitBuf(args, cwd, env);
   return buf == null ? null : buf.toString('utf8').replace(/\r?\n$/, '');
 };
 
@@ -181,10 +181,10 @@ const gitLine = (args, cwd) => {
 // ignores them by construction; this count only feeds ONE non-failing advisory line naming the
 // cosmetic sandbox-masks apply — an applied managed block hides the paths from --exclude-standard,
 // so the advisory disappears exactly when the status noise does (no standing detector).
-export const countNeverCommittableUntracked = (cwd, { lstat = lstatSync } = {}) => {
-  const top = gitLine(['rev-parse', '--show-toplevel'], cwd);
+export const countNeverCommittableUntracked = (cwd, { lstat = lstatSync, env } = {}) => {
+  const top = gitLine(['rev-parse', '--show-toplevel'], cwd, env);
   if (top == null) return 0;
-  const untrackedZ = gitBuf(['ls-files', '--others', '--exclude-standard', '-z'], top);
+  const untrackedZ = gitBuf(['ls-files', '--others', '--exclude-standard', '-z'], top, env);
   if (untrackedZ == null) return 0;
   return untrackedZ
     .toString('utf8')
@@ -345,7 +345,10 @@ export const buildHeldSessionState = ({
 // must read the same config/plans or a dirty unreceipted tree could false-PASS as "no plan in
 // flight". Outside a git tree the cwd is the only anchor (and --check exits 0).
 export const buildState = ({ cwd, env = process.env, detect = detectBackends, surveyVehicle, lstat = lstatSync, readFile = readFileSync } = {}) => {
-  const root = gitLine(['rev-parse', '--show-toplevel'], cwd) ?? cwd;
+  // WHICH repository, first; the config/plan anchor is the stripped discovery's top (from a subdirectory the bare cwd would miss docs/plans — decideCheck refuses on an unanchored root).
+  const location = resolveGitLocation(cwd, { env });
+  const anchoredTop = location.top ?? gitLine(['rev-parse', '--show-toplevel'], cwd, stripGitLocationEnv(env));
+  const root = anchoredTop ?? cwd;
   const { config, source: configSource } = loadConfig(root);
   // A bridge-detector throw reaches the hook, never a catch that would also lose the surveyed
   // executor vehicle: bridge readiness goes unknown (fail closed below), the carrier stays known.
@@ -354,16 +357,15 @@ export const buildState = ({ cwd, env = process.env, detect = detectBackends, su
     detectionWarning = `backend detection failed (${(err && err.message) || err}) — bridge readiness unknown.`;
   };
   const detection = composeReadiness(root, { detect, surveyVehicle, onDetectError });
-  // The resolver stays for DISPLAY/diagnostics only; the OBLIGATIONS come from the configured
-  // recipe (never the readiness-degraded effective one — no silent solo).
+  // The resolver stays for DISPLAY only; the OBLIGATIONS come from the configured recipe (never the readiness-degraded effective one — no silent solo).
   const resolved = resolveActivityRecipe({ config: config ?? {}, readiness: detection, activity: ACTIVITY, slot: SLOT });
   const obligations = requiredBackendsForConfiguredRecipe({ config: config ?? {}, readiness: detection, detectionFailed: detectionWarning != null });
   const requiredBackends = obligations.backends;
   const plans = plansInFlight(root);
   // The injected lstat threads through EVERY stat-dependent computation (fingerprint, clean, the
   // mask count) — a partial injection would let a test observe an inconsistent state.
-  const fingerprint = computeTreeFingerprint(cwd, { lstat });
-  const clean = fingerprint == null ? null : isTreeClean(cwd, { lstat });
+  const fingerprint = location.state === 'work-tree' ? computeTreeFingerprint(cwd, { lstat, env }) : null;
+  const clean = fingerprint == null ? null : isTreeClean(cwd, { lstat, env });
   const receiptsPath = resolveReceiptsPath(cwd, env);
   const receiptsRead = receiptsPath ? readReceipts(receiptsPath) : { receipts: [], malformed: 0 };
   const { receipts, malformed } = receiptsRead;
@@ -469,6 +471,8 @@ export const buildState = ({ cwd, env = process.env, detect = detectBackends, su
     backends: armedBackends,
     plans,
     root,
+    rootAnchored: anchoredTop !== null,
+    location,
     fingerprint,
     clean,
     receiptsPath,
@@ -482,7 +486,7 @@ export const buildState = ({ cwd, env = process.env, detect = detectBackends, su
     evidenceUnavailable: degrade.unavailable,
     degradedExempt,
     heldSession,
-    maskedUntracked: countNeverCommittableUntracked(cwd, { lstat }),
+    maskedUntracked: countNeverCommittableUntracked(cwd, { lstat, env }),
     detectionWarning,
     flowPresent,
     flowArmed,
@@ -519,7 +523,7 @@ const backendFailurePart = (b, state) => {
   if (b.state === 'unrecognized-verdict') return `${b.backend}: the latest normal receipt carries an unrecognized verdict (${JSON.stringify(b.verdict)}) — an unknown verdict never attests (fail-closed); re-run the review`;
   if (b.state === 'ungrounded') return `${b.backend}: the latest normal receipt is ungrounded — re-run grounded (--facts)`;
   if (b.state === 'probe') return `${b.backend}: only probe receipts for the current tree (CODEX_PROBE=1 / AGY_PROBE=1 relaxes the quality guards) — a probe review never attests; re-run a real one`;
-  if (b.state === 'rejected') return `${b.backend}: current-tree receipts rejected — ${rejectionCause(b)} (fail-closed); inspect ${state.receiptsPath}`;
+  if (b.state === 'rejected') return `${b.backend}: current-tree receipts rejected — ${rejectionCause(b)} (fail-closed); inspect ${escapeForDisplay(state.receiptsPath)}`;
   if (b.state === 'stale') return `${b.backend}: receipts exist but none matches the current tree (edited after review) — run a fresh review`;
   return `${b.backend}: no receipt — run its review wrapper, or record an explicit degrade (node ${CORE_EVIDENCE_TOOL} degrade --backend ${b.backend} --reason "...")`;
 };
@@ -530,7 +534,7 @@ const describesHeldRecovery = (state) => {
   const canRetry = substitution.folded === false;
   if (state.evidenceUnavailable === true) {
     const retry = canRetry ? '; or fold the retry of that thread' : '';
-    return ` — the evidence store is unavailable, so the degrade lane cannot be judged: repair it (inspect ${state.evidenceStorePath}) and re-check${retry}`;
+    return ` — the evidence store is unavailable, so the degrade lane cannot be judged: repair it (inspect ${escapeForDisplay(state.evidenceStorePath)}) and re-check${retry}`;
   }
   const canDegrade = typeof substitution.postTreeDigest === 'string'
     && state.fingerprint === substitution.postTreeDigest;
@@ -553,11 +557,13 @@ export const decideCheck = (state) => {
   // Store diagnostics ride EVERY check line, early exits (and the unknowable arm) included — a
   // malformed receipt line, an unavailable evidence store, or an unreadable receipts store is
   // never hidden behind any exit.
-  const malformedNote = state.malformed > 0 ? ` — ${state.malformed} malformed receipt line(s) ignored; inspect ${state.receiptsPath}` : '';
+  const malformedNote = state.malformed > 0 ? ` — ${state.malformed} malformed receipt line(s) ignored; inspect ${escapeForDisplay(state.receiptsPath)}` : '';
   const evidenceNote = state.evidenceUnavailable
-    ? ` — evidence store unavailable (${state.evidenceMalformed} malformed line(s)${state.evidenceReadError ? `, read error: ${state.evidenceReadError}` : ''}); the degrade escape is denied (fail-closed) — inspect ${state.evidenceStorePath}`
+    ? ` — evidence store unavailable (${state.evidenceMalformed} malformed line(s)${state.evidenceReadError ? `, read error: ${state.evidenceReadError}` : ''}); the degrade escape is denied (fail-closed) — inspect ${escapeForDisplay(state.evidenceStorePath)}`
     : '';
-  const earlyNotes = `${malformedNote}${evidenceNote}${state.receiptsReadError ? ` — receipts store unreadable (${state.receiptsReadError}); inspect ${state.receiptsPath}` : ''}`;
+  const earlyNotes = `${malformedNote}${evidenceNote}${state.receiptsReadError ? ` — receipts store unreadable (${state.receiptsReadError}); inspect ${escapeForDisplay(state.receiptsPath)}` : ''}`;
+  // The git LOCATION (hand-built states carry none; the fingerprint decides there) rules below the solo arm: not-a-repository passes, the four other non-work-tree states refuse by name.
+  const location = state.location ?? { state: state.fingerprint == null ? 'not-a-repository' : 'work-tree', cause: 'no location was resolved for a hand-built state' };
   if (state.heldSession !== null && state.heldSession !== undefined) {
     const held = decideHeldSession(state.heldSession);
     const heldRecovery = describesHeldRecovery(state);
@@ -574,11 +580,14 @@ export const decideCheck = (state) => {
       : `no reviewer backend is ready — the computed ${ACTIVITY}.${SLOT} default is solo`;
     return { code: 0, reason: `${why} — no receipt required${earlyNotes}` };
   }
+  // An UNANCHORED root (git dead everywhere): the bare-cwd plan inventory cannot say "no plan".
+  if (location.state !== 'work-tree' && location.state !== 'not-a-repository' && state.rootAnchored === false) return { code: 1, reason: `the git location is ${location.state} — ${escapeForDisplay(location.cause)} — and the project root cannot be anchored, so the plan arm cannot decide (fail closed)${earlyNotes}` };
   if (state.plans.length === 0) return { code: 0, reason: `no plan in flight (docs/plans/ holds no active plan) — no receipt required${earlyNotes}` };
-  if (state.fingerprint == null) return { code: 0, reason: `not a git work tree — nothing to fingerprint${earlyNotes}` };
-  // A clean tree PASSES, but never silently: the no-plan arm above already returned, so reaching
-  // here means >=1 plan IS in flight and this gate arms the moment the tree turns dirty. Naming
-  // each file forward-looking is what makes the arm discoverable BEFORE it blocks a pending commit.
+  if (location.state !== 'work-tree' && location.state !== 'not-a-repository') return { code: 1, reason: `the git location is ${location.state} — ${escapeForDisplay(location.cause)} — refusing to judge receipts for a tree git cannot name (fail closed)${earlyNotes}` };
+  if (location.state === 'not-a-repository') return { code: 0, reason: `not a git repository (git's own answer: ${escapeForDisplay(location.cause)}) — nothing to fingerprint${earlyNotes}` };
+  if (state.fingerprint == null || state.clean === null) return { code: 1, reason: `the tree ${state.fingerprint == null ? 'fingerprint' : 'clean check'} is undecidable in a work tree (a git query failed or was killed) — refusing to judge receipts (fail closed)${earlyNotes}` };
+  // A clean tree PASSES, but never silently: >=1 plan IS in flight here, and this gate arms the
+  // moment the tree turns dirty — naming each file makes the arm discoverable BEFORE it blocks.
   if (state.clean === true) {
     // Each name is byte-preserving and quoted because this reason is one gate-report line.
     const named = state.plans.map((p) => quoteReportName(p)).join(', ');
@@ -595,7 +604,7 @@ export const decideCheck = (state) => {
   // whatever the recipe consults, so a recipe flip to solo can never bury one.
   if (state.obligations.recipe === 'solo') {
     if (state.receiptsReadError != null) {
-      return { code: 1, reason: `the receipts store is unreadable (${state.receiptsReadError}) — "no standing veto" cannot be established, so the internal-only floor fails closed; inspect ${state.receiptsPath}${earlyNotes}` };
+      return { code: 1, reason: `the receipts store is unreadable (${state.receiptsReadError}) — "no standing veto" cannot be established, so the internal-only floor fails closed; inspect ${escapeForDisplay(state.receiptsPath)}${earlyNotes}` };
     }
     const standing = state.soloVetoRows.filter((b) => (b.state === 'current' && !b.shipClass && !b.overrideLabel) || b.state === 'unrecognized-verdict');
     if (standing.length > 0) {
@@ -641,7 +650,7 @@ export const decideCheck = (state) => {
       .filter((b) => !(printed.has(b.backend) && b.state === 'rejected'))
       .reduce((n, b) => n + (b.markerRejected ?? 0) + (b.unmarkedRejected ?? 0), 0);
     const markerNote = total > 0
-      ? ` — ${total} receipt(s) rejected: an untrustworthy probe marker (malformed, or absent — silence is not a declaration) — fail-closed; inspect ${state.receiptsPath}`
+      ? ` — ${total} receipt(s) rejected: an untrustworthy probe marker (malformed, or absent — silence is not a declaration) — fail-closed; inspect ${escapeForDisplay(state.receiptsPath)}`
       : '';
     return `${markerNote}${earlyNotes}`;
   };
@@ -716,12 +725,12 @@ const formatHuman = (state, check) => {
   ];
   if (state.detectionWarning) lines.push(`  ⚠ ${state.detectionWarning}`);
   lines.push(`  plan in flight: ${state.plans.length ? state.plans.map((name) => quoteReportName(name)).join(', ') : '(none)'}`);
-  if (state.fingerprint == null) lines.push('  tree: not a git work tree');
+  if (state.fingerprint == null) lines.push(`  tree: ${state.location != null && state.location.state !== 'work-tree' ? `git location ${state.location.state} — ${escapeForDisplay(state.location.cause)}` : 'the fingerprint is undecidable (a git query failed or was killed)'}`);
   else if (state.clean === true) lines.push('  tree: clean (nothing to review)');
   else lines.push(`  tree fingerprint: ${state.fingerprint}`);
   if (state.heldSession != null) lines.push(`  ${decideHeldSession(state.heldSession).line}`);
-  lines.push(`  receipts: ${state.receiptsPath ?? '(unresolvable — no git dir)'} (${state.receiptCount} line(s)${state.malformed ? `, ${state.malformed} malformed — inspect the file` : ''})`);
-  if (state.receiptsReadError) lines.push(`  ⚠ receipts store unreadable (${state.receiptsReadError}) — inspect ${state.receiptsPath}`);
+  lines.push(`  receipts: ${state.receiptsPath == null ? '(unresolvable — no git dir)' : escapeForDisplay(state.receiptsPath)} (${state.receiptCount} line(s)${state.malformed ? `, ${state.malformed} malformed — inspect the file` : ''})`);
+  if (state.receiptsReadError) lines.push(`  ⚠ receipts store unreadable (${state.receiptsReadError}) — inspect ${escapeForDisplay(state.receiptsPath)}`);
   if (state.evidenceUnavailable) lines.push(`  ⚠ evidence store unavailable (${state.evidenceMalformed} malformed line(s)${state.evidenceReadError ? `, read error: ${state.evidenceReadError}` : ''}) — the degrade escape is denied (fail-closed)`);
   const exempt = new Set(state.degradedExempt);
   for (const b of state.backends) {
@@ -778,7 +787,7 @@ malformed, foreign or audit-refused ledger, a failed HEAD read, or a SUBSTITUTED
 exits 1 (a substitution is lifted only by a codex-exec degrade at the substituted return's own
 tree, or the fold of that thread's retry). THEN: 0 for solo / no plan in flight /
 a clean tree (under a non-solo review obligation the PASS names every plan in flight and its arm) /
-not-a-git-tree / obligations satisfied (reviewed: >=1 ship-class attestation;
+a cwd where git ITSELF answers not-a-repository (the only passing non-work-tree state; the four others exit 1 by name) / obligations satisfied (reviewed: >=1 ship-class attestation;
 council: every backend ship-class or degrade-recorded, >=1 real ship); 1 on a veto, an
 unrecognized verdict, a missing/stale/ungrounded/probe-only backend without a degrade record,
 an all-degraded tree, or a down detector with no configured recipe.

package/tools/robustness-brief.mjs

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+
+import { realpathSync } from 'node:fs';
+import { isAbsolute, resolve, sep } from 'node:path';
+import { readShippedRobustnessLiterals, parseRobustTag } from './robustness-literals.mjs';
+import { checkPlanStructure, formatFindings, isSweep } from './plan-shape.mjs';
+import { expandSweepPaths } from './plan-shape-facts.mjs';
+import { readFileBytesNoFollowCapped } from './fs-read-nofollow.mjs';
+import { escapeForDisplay, lexicalRepoRelative } from './repo-lex.mjs';
+import { isDirectRun } from './direct-run.mjs';
+
+const PLAN_READ_CAP = 1_048_576;
+const ROW_ID = /^[A-Za-z0-9._-]+$/u;
+const SEARCHABLE_KINDS = new Set(['env', 'flag', 'ref', 'syscall', 'errno', 'argv']);
+const SHIPPED_LIST_PATH = 'agent-workflow-kit/references/robustness-literals.json';
+const USAGE = 'Usage: node robustness-brief.mjs --plan <plan> [--row <id>] [--coverage]';
+const usage = (message) => Object.assign(new Error(message), { usage: true });
+const isInside = (root, path) => path === root || path.startsWith(`${root}${sep}`);
+const decodePlan = (bytes) => new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+
+const parseArgs = (argv, index = 0, state = { plan: null, row: null, coverage: false }) => {
+  if (index === argv.length) {
+    if (state.plan === null) throw usage('absent --plan');
+    if (state.row !== null && state.coverage) throw usage('--row cannot be combined with --coverage');
+    return state;
+  }
+  const flag = argv[index];
+  if (flag === '--coverage') {
+    if (state.coverage) throw usage('duplicate --coverage');
+    return parseArgs(argv, index + 1, { ...state, coverage: true });
+  }
+  const key = flag === '--plan' ? 'plan' : flag === '--row' ? 'row' : null;
+  const value = argv[index + 1];
+  if (key === null) throw usage(`unknown argument ${flag}`);
+  if (state[key] !== null) throw usage(`duplicate ${flag}`);
+  if (value === undefined || value.startsWith('--') || value.length === 0) throw usage(`absent operand for ${flag}`);
+  if (key === 'row' && !ROW_ID.test(value)) throw usage(`invalid --row ${value}`);
+  return parseArgs(argv, index + 2, { ...state, [key]: value });
+};
+
+const renderClass = (entry) => [
+  `- **${entry.id}** — ${entry.prove}`,
+  ...entry.members.map((member) => `  - \`${member.literal}\` — ${member.note} (${member.source})`),
+];
+
+const isIdentifierByte = (byte) => (byte >= 0x30 && byte <= 0x39) ||
+  (byte >= 0x41 && byte <= 0x5a) || byte === 0x5f || (byte >= 0x61 && byte <= 0x7a);
+const hasBoundedLiteral = (bytes, literal) => {
+  const token = Buffer.from(literal, 'utf8');
+  const cursor = { from: 0 };
+  while (cursor.from <= bytes.length - token.length) {
+    const hit = bytes.indexOf(token, cursor.from);
+    if (hit === -1) return false;
+    const leftBounded = hit === 0 || !isIdentifierByte(bytes[hit - 1]);
+    const rightBounded = literal.endsWith('_') || hit + token.length === bytes.length || !isIdentifierByte(bytes[hit + token.length]);
+    if (leftBounded && rightBounded) return true;
+    cursor.from = hit + 1;
+  }
+  return false;
+};
+export const isCoverageDocument = (path) => /\.(?:md|txt)$/u.test(path) || path === SHIPPED_LIST_PATH;
+const describeReadOutcome = (read) => read.outcome === 'foreign'
+  ? `non-regular ${read.className ?? 'file'}`
+  : read.outcome === 'over-cap' ? `over-cap${read.cap ? ` (cap ${read.cap})` : ''}`
+    : read.outcome === 'error' ? `error${read.code ? ` (${read.code})` : ''}` : String(read.outcome ?? 'unknown');
+const readCoverageFile = (readRowFile, path) => {
+  try {
+    const read = readRowFile(path);
+    if (read == null) return { outcome: 'error', code: 'empty read outcome' };
+    if (read.outcome === 'ok' && !Buffer.isBuffer(read.bytes)) return { outcome: 'error', code: 'ok outcome carried no Buffer' };
+    return read;
+  } catch (error) {
+    return { outcome: 'error', code: error?.code ?? error?.message ?? 'read threw' };
+  }
+};
+export const computeRowCoverage = (planText, list, { expandRowPath, readRowFile }) => {
+  const shape = checkPlanStructure(planText, {});
+  const classes = new Set(list.classes.map(({ id }) => id));
+  const entries = shape.parsed.rows.filter((entry) => entry.valid && !isCoverageDocument(entry.path));
+  return entries.reduce((answer, entry) => {
+    if (answer.refusal !== null) return answer;
+    const robust = parseRobustTag(entry.responsibility);
+    if (robust.refusal) return { ...answer, refusal: { id: entry.id, reason: robust.refusal } };
+    const unknown = robust.classes.find((classId) => !classes.has(classId));
+    if (unknown) return { ...answer, refusal: { id: entry.id, reason: `unknown class ${unknown}` } };
+    const tagged = robust.classes;
+    const emptyRow = { id: entry.id, path: entry.path, tagged, present: [], uncovered: [], absent: false, deleted: false };
+    if (entry.verb === 'delete') {
+      return { ...answer, rows: [...answer.rows, { ...emptyRow, deleted: true }] };
+    }
+    const paths = isSweep(entry.path) ? expandRowPath(entry.path) : [entry.path];
+    const reads = paths.map((path) => ({ path, read: readCoverageFile(readRowFile, path) }));
+    const refused = reads.find(({ read }) => !['ok', 'absent'].includes(read.outcome));
+    if (refused) {
+      return { ...answer, refusal: { id: entry.id, path: refused.path, outcome: describeReadOutcome(refused.read) } };
+    }
+    if (paths.length === 0 || reads.some(({ read }) => read.outcome === 'absent')) {
+      return { ...answer, rows: [...answer.rows, { ...emptyRow, absent: true }] };
+    }
+    const matches = list.classes.flatMap((classEntry) => {
+      const member = classEntry.members.find((candidate) => SEARCHABLE_KINDS.has(candidate.kind) &&
+        reads.some(({ read }) => hasBoundedLiteral(read.bytes, candidate.literal)));
+      return member ? [{ id: entry.id, classId: classEntry.id, literal: member.literal }] : [];
+    });
+    const present = matches.map(({ classId }) => classId);
+    const uncovered = present.filter((classId) => !tagged.includes(classId));
+    return {
+      rows: [...answer.rows, { ...emptyRow, present, uncovered }],
+      evidence: [...answer.evidence, ...matches.filter(({ classId }) => uncovered.includes(classId))],
+      refusal: null,
+    };
+  }, { rows: [], evidence: [], refusal: null });
+};
+
+const renderCell = (value) => escapeForDisplay(value).replaceAll('|', '\\|');
+export const renderCoverage = (rows, displayPath) => [
+  `## Robustness coverage — ${escapeForDisplay(displayPath)}`,
+  '| row | path | tagged | present | uncovered |',
+  '| --- | --- | --- | --- | --- |',
+  ...rows.map((row) => row.deleted
+    ? `| ${row.id} | ${renderCell(row.path)} | delete | — | — |`
+    : row.absent ? `| ${row.id} | ${renderCell(row.path)} | absent | — | — |`
+      : `| ${row.id} | ${renderCell(row.path)} | ${row.tagged.join(',') || '—'} | ${row.present.join(',') || '—'} | ${row.uncovered.join(',') || '—'} |`),
+];
+
+export const renderBrief = (planText, list, { row, displayPath }) => {
+  const shape = checkPlanStructure(planText, {});
+  if (shape.findings.length > 0) return { code: 1, lines: formatFindings(shape, escapeForDisplay(displayPath)).split('\n').map(escapeForDisplay) };
+  const classes = new Map(list.classes.map((entry) => [entry.id, entry]));
+  const rows = shape.parsed.rows.filter((entry) => entry.valid).map((entry) => ({
+    ...entry,
+    robust: parseRobustTag(entry.responsibility),
+  }));
+  const refused = rows.find((entry) => entry.robust.refusal || entry.robust.classes.some((classId) => !classes.has(classId)));
+  if (refused) {
+    const reason = refused.robust.refusal ?? `unknown class ${refused.robust.classes.find((classId) => !classes.has(classId))}`;
+    return { code: 1, lines: [`robustness-brief: ${refused.id}: robust-class — ${reason}`] };
+  }
+  const selected = row === null ? rows.filter((entry) => entry.robust.classes.length > 0) : rows.filter((entry) => entry.id === row);
+  if (row !== null && selected.length === 0) return { code: 1, lines: [`robustness-brief: ${row}: row is absent`] };
+  if (row !== null && selected[0].robust.classes.length === 0) return { code: 1, lines: [`robustness-brief: ${row}: row is untagged`] };
+  if (selected.length === 0) return { code: 0, lines: [`Robustness literals: ${escapeForDisplay(displayPath)} has no robust tags.`] };
+  return {
+    code: 0,
+    lines: [
+      `## Robustness literals — list version ${list.version} · ${escapeForDisplay(displayPath)}`,
+      ...selected.flatMap((entry) => [
+        '',
+        `### ${entry.id} — ${escapeForDisplay(entry.path)}`,
+        ...entry.robust.classes.flatMap((classId) => renderClass(classes.get(classId))),
+      ]),
+    ],
+  };
+};
+
+export const main = (argv = process.argv.slice(2), deps = {}) => {
+  try {
+    const parsed = parseArgs(argv);
+    const cwd = deps.cwd ?? process.cwd();
+    const realpath = deps.realpath ?? realpathSync;
+    const cwdReal = realpath(cwd);
+    if (!isAbsolute(parsed.plan) && !lexicalRepoRelative(parsed.plan).ok) throw usage(`uncontained --plan ${parsed.plan}`);
+    const planPath = resolve(cwd, parsed.plan);
+    let planReal;
+    try {
+      planReal = realpath(planPath);
+    } catch (error) {
+      if (error?.code === 'ENOENT') throw usage(`absent --plan ${parsed.plan}`);
+      throw usage(`unreadable --plan ${parsed.plan} (${error?.code ?? error.message})`);
+    }
+    if (!isInside(cwdReal, planReal)) throw usage(`uncontained --plan ${parsed.plan}`);
+    const read = (deps.readPlan ?? readFileBytesNoFollowCapped)(planPath, PLAN_READ_CAP);
+    if (read.outcome !== 'ok') {
+      const outcome = read.outcome === 'foreign' ? `non-regular ${read.className ?? 'file'}` : read.outcome;
+      throw usage(`${outcome} --plan ${parsed.plan}${read.cap ? ` (cap ${read.cap})` : ''}`);
+    }
+    let planText;
+    try {
+      planText = decodePlan(read.bytes);
+    } catch {
+      throw usage(`malformed-utf8 --plan ${parsed.plan}`);
+    }
+    const list = (deps.readList ?? readShippedRobustnessLiterals)();
+    const brief = renderBrief(planText, list, { row: parsed.row, displayPath: parsed.plan });
+    if (!parsed.coverage || checkPlanStructure(planText, {}).findings.length > 0) return brief;
+    const sweepPaths = checkPlanStructure(planText, {}).parsed.rows
+      .filter((entry) => entry.valid && isSweep(entry.path) && !isCoverageDocument(entry.path))
+      .map((entry) => entry.path);
+    const expansions = deps.expandRowPath === undefined && sweepPaths.length > 0 ? expandSweepPaths(cwd, sweepPaths) : null;
+    const coverage = computeRowCoverage(planText, list, {
+      expandRowPath: deps.expandRowPath ?? ((path) => expansions[path] ?? []),
+      readRowFile: deps.readRowFile ?? ((path) => readFileBytesNoFollowCapped(resolve(cwd, path), PLAN_READ_CAP)),
+    });
+    if (coverage.refusal) {
+      const { id, path, outcome, reason } = coverage.refusal;
+      throw usage(reason === undefined ? `${id}: ${escapeForDisplay(path)} — ${outcome}` : `${id}: robust-class — ${reason}`);
+    }
+    const lines = [...renderCoverage(coverage.rows, parsed.plan), ...coverage.evidence.map(({ id, classId, literal }) => `${id}:${classId}:${literal}`)];
+    return { code: coverage.evidence.length > 0 ? 1 : 0, lines };
+  } catch (error) {
+    return { code: 2, lines: [`robustness-brief: usage — ${escapeForDisplay(error.message)}`, USAGE] };
+  }
+};
+
+if (isDirectRun(import.meta.url)) {
+  const result = main();
+  (result.code === 2 ? console.error : console.log)(result.lines.join('\n'));
+  process.exitCode = result.code;
+}

package/tools/robustness-literals.mjs

@@ -0,0 +1,101 @@
+import { createHash } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
+
+export const KINDS = Object.freeze(['env', 'flag', 'ref', 'syscall', 'errno', 'state', 'argv']);
+const KIND_SET = new Set(KINDS);
+const TOP_KEYS = Object.freeze(['schema', 'version', 'classes']);
+const CLASS_KEYS = Object.freeze(['id', 'prove', 'members']);
+const MEMBER_KEYS = Object.freeze(['literal', 'kind', 'note', 'source']);
+const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+const ADR = /^AD-\d+$/u;
+const CONTROL = /[\p{Cc}\u2028\u2029\uFFFD]/u;
+const SHIPPED_LIST = fileURLToPath(new URL('../references/robustness-literals.json', import.meta.url));
+
+const refuse = (code, detail) => {
+  throw Object.assign(new Error(`robustness-literals: ${code}${detail ? ` — ${detail}` : ''}`), { code });
+};
+const requireObject = (value, label) => {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) refuse('type', `${label} must be an object`);
+};
+const requireKeys = (value, keys, label) => {
+  requireObject(value, label);
+  const unknown = Object.keys(value).find((key) => !keys.includes(key));
+  if (unknown !== undefined) refuse('unknown-key', `${label}.${unknown}`);
+  const missing = keys.find((key) => !Object.hasOwn(value, key));
+  if (missing !== undefined) refuse('missing-key', `${label}.${missing}`);
+};
+const requireString = (value, label) => {
+  if (typeof value !== 'string') refuse('type', `${label} must be a string`);
+  if (value.length === 0) refuse('empty-string', label);
+  if (CONTROL.test(value)) refuse('control', label);
+};
+const isRepoSource = (source) => !source.startsWith('/') && !source.includes('\\') &&
+  !source.split('/').includes('..') && (source.includes('/') || source.includes('.'));
+const freezeList = (list) => Object.freeze({
+  ...list,
+  classes: Object.freeze(list.classes.map((entry) => Object.freeze({
+    ...entry,
+    members: Object.freeze(entry.members.map((member) => Object.freeze(member))),
+  }))),
+});
+
+const validateList = (value) => {
+  requireKeys(value, TOP_KEYS, 'list');
+  if (value.schema !== 1) refuse('schema', 'schema must be 1');
+  if (!Number.isSafeInteger(value.version) || value.version < 1) refuse('version', 'version must be an integer >= 1');
+  if (!Array.isArray(value.classes)) refuse('type', 'classes must be an array');
+  if (value.classes.length === 0) refuse('empty-class', 'classes must not be empty');
+  const ids = new Set();
+  for (const [classIndex, entry] of value.classes.entries()) {
+    const label = `classes[${classIndex}]`;
+    requireKeys(entry, CLASS_KEYS, label);
+    requireString(entry.id, `${label}.id`);
+    if (!SLUG.test(entry.id)) refuse('class-id', entry.id);
+    if (ids.has(entry.id)) refuse('duplicate-class', entry.id);
+    ids.add(entry.id);
+    requireString(entry.prove, `${label}.prove`);
+    if (!Array.isArray(entry.members)) refuse('type', `${label}.members must be an array`);
+    if (entry.members.length === 0) refuse('empty-class', entry.id);
+    const literals = new Set();
+    for (const [memberIndex, member] of entry.members.entries()) {
+      const memberLabel = `${label}.members[${memberIndex}]`;
+      requireKeys(member, MEMBER_KEYS, memberLabel);
+      for (const key of MEMBER_KEYS) requireString(member[key], `${memberLabel}.${key}`);
+      if (literals.has(member.literal)) refuse('duplicate-literal', `${entry.id}:${member.literal}`);
+      literals.add(member.literal);
+      if (!KIND_SET.has(member.kind)) refuse('kind', member.kind);
+      if (!ADR.test(member.source) && !SLUG.test(member.source) && !isRepoSource(member.source)) refuse('source', member.source);
+    }
+  }
+  return freezeList(value);
+};
+
+export const readRobustnessLiterals = (path, io = {}) => {
+  const read = readRegularFileNoFollow(path, io);
+  if (read.outcome !== 'ok') refuse('type', `${path} must be a readable regular file (${read.className ?? read.code ?? read.outcome})`);
+  try {
+    return validateList(JSON.parse(read.content));
+  } catch (error) {
+    if (error?.code) throw error;
+    refuse('type', `${path} is not valid JSON (${error.message})`);
+  }
+};
+
+export const readShippedRobustnessLiterals = (deps = {}) =>
+  readRobustnessLiterals((deps.resolvePath ?? (() => SHIPPED_LIST))(), deps.io);
+
+export const parseRobustTag = (text) => {
+  const matches = [...String(text ?? '').matchAll(/robust:(\S*)/gu)];
+  if (matches.length === 0) return { classes: [] };
+  if (matches.length > 1) return { refusal: 'multiple-tags' };
+  if (matches[0][1] === '') return { refusal: 'no-class' };
+  const classes = matches[0][1].split(',');
+  if (classes.some((entry) => entry === '')) return { refusal: 'empty-class' };
+  if (new Set(classes).size !== classes.length) return { refusal: 'duplicate-class' };
+  if (classes.some((entry) => !SLUG.test(entry))) return { refusal: 'invalid-class' };
+  return { classes };
+};
+
+export const classIds = (list) => Object.freeze(list.classes.map((entry) => entry.id));
+export const digestOf = (list) => createHash('sha256').update(JSON.stringify(list.classes)).digest('hex');

package/tools/sandbox-masks.mjs

@@ -42,6 +42,7 @@ import { isDirectRun } from './direct-run.mjs';
 import { fail } from './orchestration-config.mjs';
 import { isNeverCommittableStat, shellQuoteArg } from './review-state.mjs';
 import { assertContainedRealPath } from './fs-safe.mjs';
+import { GIT_MAX_BUFFER } from './git-env.mjs';
 
 export const MASKS_FENCE_START = '# >>> agent-workflow sandbox-masks — managed block, fully REPLACED by the kit sandbox-masks lane; do not hand-edit inside >>>';
 export const MASKS_FENCE_END = '# <<< agent-workflow sandbox-masks <<<';
@@ -59,7 +60,7 @@ const gitLine = (args, cwd) => {
 // The UNFILTERED untracked walk: --others WITHOUT --exclude-standard, so a mask already hidden by
 // an earlier apply stays visible to a rerun (the full-block replace re-derives it, codex).
 const listUntrackedUnfilteredZ = (root) => {
-  const r = spawnSync('git', ['ls-files', '--others', '-z'], { cwd: root, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, windowsHide: true });
+  const r = spawnSync('git', ['ls-files', '--others', '-z'], { cwd: root, encoding: 'utf8', maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
   if (r.error || r.status !== 0) return null;
   return r.stdout.split('\0').filter(Boolean);
 };

package/tools/set-flow.mjs

@@ -50,6 +50,7 @@ import { loadDeclaration } from './run-gates.mjs';
 import { compareSemver } from './semver-lite.mjs';
 import { lexicalRepoRelative } from './core-evidence.mjs';
 import { readAuthoritativeVersion } from './manifest/validate.mjs';
+import { GIT_MAX_BUFFER } from './git-env.mjs';
 
 const KIT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const GATES_REL = 'docs/ai/gates.json';
@@ -197,7 +198,7 @@ const meetsVersionFloor = (version, floor) => {
   return cmp !== null && cmp >= 0;
 };
 
-const defaultRunGit = (args, cwd) => spawnSync('git', args, { cwd, maxBuffer: 64 * 1024 * 1024, windowsHide: true });
+const defaultRunGit = (args, cwd) => spawnSync('git', args, { cwd, maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
 
 const gitToplevel = (cwd, runGit) => {
   const r = runGit(['rev-parse', '--show-toplevel'], cwd);

package/tools/source-size-scope.mjs

@@ -18,37 +18,18 @@ import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { configFail, configPathFor, scopeFail } from './source-size-refusal.mjs';
+import { GIT_MAX_BUFFER, parseIndexEntries, resolveGitLocation, withGitPath } from './git-env.mjs';
 
 const LF = 0x0a;
 const CR = 0x0d;
-const TAB = 0x09;
 const SLASH = 0x2f;
 
-const GIT_MAX_BUFFER = 256 * 1024 * 1024;
 const SYMLINK_MODE = '120000';
 const GITLINK_MODE = '160000';
 
-// Raw bytes in, raw bytes out: `ls-files -s -z` emits mode, object and stage, then a TAB, then the
-// path, then a NUL — and the path half is never decoded before it has been matched, so a name
-// carrying a tab or a newline survives intact (splitting on lines would mangle it).
-// The object id is carried through rather than dropped: the record already holds it, and a consumer
-// that must read what the index HOLDS (not what the worktree happens to show) needs exactly that.
-const parseIndexEntries = (buf) => {
-  const entries = [];
-  let start = 0;
-  while (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(TAB);
-    if (tab !== -1) {
-      const head = record.subarray(0, tab).toString('utf8').split(' ');
-      entries.push({ mode: head[0], sha: head[1], stage: Number(head[2]), path: record.subarray(tab + 1) });
-    }
-    start = end + 1;
-  }
-  return entries;
-};
+// The `ls-files -s -z` record parser lives in the git leaf (raw bytes in, raw path bytes out, the
+// object id carried through so a consumer reading what the index HOLDS has it) — one home shared
+// with the control-byte gate.
 
 // A path whose bytes are not valid UTF-8 round-trips to something DIFFERENT (the replacement char is
 // lossy) — that is the whole test, and it is exact.
@@ -65,11 +46,24 @@ const bufSegmentPrefix = (path, prefix) =>
 const bufEndsWith = (path, suffix) =>
   path.length >= suffix.length && path.subarray(path.length - suffix.length).equals(suffix);
 
+// The enumeration-error class (exit 2) also refuses every git LOCATION but a work tree, by its own
+// state name — a redirecting GIT_DIR would otherwise enumerate ANOTHER repository's index in
+// silence — and a runner that throws, which is an answer here, never a raw stack.
 export const enumerateIndex = (cwd, deps = {}) => {
   const spawn = deps.spawn ?? spawnSync;
-  const result = spawn('git', ['ls-files', '-s', '-z'], { cwd, maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
+  const env = deps.env ?? process.env;
+  const location = resolveGitLocation(cwd, { spawn, env });
+  if (location.state !== 'work-tree') {
+    throw configFail(`the git index could not be enumerated in ${cwd} (the git location is ${location.state}: ${location.cause}) — the declared scope is unknown, so nothing is judged`);
+  }
+  let result;
+  try {
+    result = spawn('git', ['ls-files', '-s', '-z'], { cwd, env: withGitPath(env), maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
+  } catch (err) {
+    result = { error: err };
+  }
   if (result.error || result.status !== 0) {
-    const why = result.error ? result.error.message : `git exited ${result.status}`;
+    const why = result.error ? result.error.message : result.signal ? `git was killed by ${result.signal}` : `git exited ${result.status}`;
     throw configFail(`the git index could not be enumerated in ${cwd} (${why}) — the declared scope is unknown, so nothing is judged`);
   }
   return parseIndexEntries(result.stdout);