@sabaiway/agent-workflow-kit 5.10.0 → 5.11.1

package/references/scripts/archive-changelog.mjs

@@ -32,9 +32,9 @@
 //   --warm-days=N (default 30)
 //   --today=YYYY-MM-DD (default today UTC) — useful for tests / reproducible runs
 
-import { readFileSync, writeFileSync, mkdirSync, readdirSync, existsSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, existsSync, realpathSync } from 'node:fs';
 import { dirname, resolve, basename } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
 import { tokenizeMarkdown, findParagraphBreak, fail } from './markdown-blocks.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -542,5 +542,16 @@ export const runCli = (argv, deps = {}) => {
   }
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+// Run main() only when executed directly, never on import. Compare by REAL path: an entry point
+// reached through a symlink resolves to its target, so a raw string compare reads the two as
+// different and the CLI never runs. realpathSync collapses the link so both sides match.
+const isDirectRun = (() => {
+  const invoked = process.argv[1];
+  if (!invoked) return false;
+  try {
+    return realpathSync(invoked) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
 if (isDirectRun) process.exitCode = runCli(process.argv.slice(2));

package/references/scripts/archive-decisions.mjs

@@ -75,9 +75,9 @@
 //
 // Dependency-free, Node >= 22. Deployed into a consumer's scripts/ like its siblings.
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, rmSync, statSync, realpathSync } from 'node:fs';
 import { dirname, resolve, join, posix } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { tmpdir } from 'node:os';
@@ -1195,5 +1195,16 @@ export const runCli = (argv, deps = {}) => {
   }
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+// Run main() only when executed directly, never on import. Compare by REAL path: an entry point
+// reached through a symlink resolves to its target, so a raw string compare reads the two as
+// different and the CLI never runs. realpathSync collapses the link so both sides match.
+const isDirectRun = (() => {
+  const invoked = process.argv[1];
+  if (!invoked) return false;
+  try {
+    return realpathSync(invoked) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
 if (isDirectRun) process.exitCode = runCli(process.argv.slice(2));

package/references/scripts/archive-issues.mjs

@@ -31,9 +31,9 @@
 //   --cutoff-days=N (default 14)
 //   --today=YYYY-MM-DD (default UTC today)
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, realpathSync } from 'node:fs';
 import { dirname, resolve, basename } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
 import { tokenizeMarkdown, fail } from './markdown-blocks.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -411,5 +411,16 @@ export const runCli = (argv, deps = {}) => {
   }
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+// Run main() only when executed directly, never on import. Compare by REAL path: an entry point
+// reached through a symlink resolves to its target, so a raw string compare reads the two as
+// different and the CLI never runs. realpathSync collapses the link so both sides match.
+const isDirectRun = (() => {
+  const invoked = process.argv[1];
+  if (!invoked) return false;
+  try {
+    return realpathSync(invoked) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
 if (isDirectRun) process.exitCode = runCli(process.argv.slice(2));

package/references/scripts/check-docs-size.mjs

@@ -25,9 +25,9 @@
 //   --quiet            print only failures (and final summary)
 
 import { readFile, writeFile, readdir, stat, rename, rm } from 'node:fs/promises';
-import { existsSync, lstatSync } from 'node:fs';
+import { existsSync, lstatSync, realpathSync } from 'node:fs';
 import { dirname, resolve, relative, join, basename, sep } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
 import { randomBytes } from 'node:crypto';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -571,7 +571,18 @@ export const runCli = async (argv, deps = {}) => {
   return result(errorCount > 0 && !flags.report ? 1 : 0);
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+// Run main() only when executed directly, never on import. Compare by REAL path: an entry point
+// reached through a symlink resolves to its target, so a raw string compare reads the two as
+// different and the CLI never runs. realpathSync collapses the link so both sides match.
+const isDirectRun = (() => {
+  const invoked = process.argv[1];
+  if (!invoked) return false;
+  try {
+    return realpathSync(invoked) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
 if (isDirectRun) {
   const { code, stdout, stderr } = await runCli(process.argv.slice(2));
   if (stdout) process.stdout.write(stdout);

package/references/scripts/migrate-gates.mjs

@@ -28,7 +28,7 @@
 
 import { existsSync, lstatSync, readFileSync, writeFileSync, renameSync, unlinkSync, realpathSync } from 'node:fs';
 import { join, resolve, isAbsolute } from 'node:path';
-import { pathToFileURL, fileURLToPath } from 'node:url';
+import { fileURLToPath } from 'node:url';
 import { randomBytes } from 'node:crypto';
 import { spawnSync } from 'node:child_process';
 
@@ -718,5 +718,16 @@ export const main = (argv = process.argv.slice(2), io = {}) => {
   }
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+// Run main() only when executed directly, never on import. Compare by REAL path: an entry point
+// reached through a symlink resolves to its target, so a raw string compare reads the two as
+// different and the CLI never runs. realpathSync collapses the link so both sides match.
+const isDirectRun = (() => {
+  const invoked = process.argv[1];
+  if (!invoked) return false;
+  try {
+    return realpathSync(invoked) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
 if (isDirectRun) process.exitCode = main();

package/tools/ack-write.mjs

@@ -27,7 +27,8 @@
 
 import { lstatSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
+import { isDirectRun } from './direct-run.mjs';
 import { ACKS_FILE, ACK_LANES } from './recommendations.mjs';
 import { assertDocsAiDeployment, writeDocsAiFileAtomic, lstatNoFollow } from './atomic-write.mjs';
 import { shellQuoteArg } from './review-state.mjs';
@@ -207,5 +208,4 @@ export const main = (argv = process.argv.slice(2), deps = {}) => {
   }
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isDirectRun) process.exit(main(process.argv.slice(2)));
+if (isDirectRun(import.meta.url)) process.exit(main(process.argv.slice(2)));

package/tools/advisor-matrix.mjs

@@ -0,0 +1,165 @@
+// advisor-matrix.mjs — the advisor-matrix STRUCTURE check (delegation Plan 3, Phase 1), as a leaf.
+//
+// A doc-parity BINDING proves a token is somewhere in a file. Correspondence is a different claim,
+// and it is the one this table needs: the dispatch mode doc's routing matrix must carry one row per
+// registry row, in registry order, with every CELL equal. A reorder, a duplicate, a dropped row, a
+// mis-bound vehicle and a drifted availability or returns cell all leave every token present — so a
+// token check passes every one of them, which is exactly why this exists beside the bindings rather
+// than as more of them.
+//
+// Its own module rather than more lines in doc-parity.mjs: the lint's identity is "a closed registry
+// of value bindings plus the runner over them", and a table parser with its own refusal vocabulary is
+// a second thing. Split, each is a file you can hold whole — and the parser gets its own test file.
+//
+// Read-only: never writes, never commits, spawns nothing. Node built-ins plus the advisor registry
+// only. No side effects on import; no CLI (it is reached through doc-parity).
+
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ADVISOR_ROWS, ADVISOR_MATRIX_HEADER, ADVISOR_MATRIX_COLUMNS, renderAdvisorMatrix } from './dispatch-advisor.mjs';
+
+const KIT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+export const ADVISOR_MATRIX_DOC = 'references/modes/dispatch.md';
+
+// The table is found through an ANCHORED surface, not by "the first header line anywhere". Header
+// search alone is maskable in a way even an exactly-one rule does not close: a faithful copy of the
+// table plus a canonical one whose HEADER drifted leaves exactly one matching header — the decoy's —
+// and the check then reads the decoy and passes. The markers make the checked surface a property of
+// the DOC, so a copy outside them can neither stand in for the table nor hide its drift, and a
+// drifted header INSIDE them leaves the surface with zero headers and fails closed.
+export const ADVISOR_MATRIX_BEGIN = '<!-- advisor-matrix:begin -->';
+export const ADVISOR_MATRIX_END = '<!-- advisor-matrix:end -->';
+
+export const readKitDoc = (rel) => readFileSync(resolve(KIT_ROOT, rel), 'utf8');
+
+// Both line endings are ordinary here. Splitting on '\n' alone leaves a trailing '\r' on every line
+// of a CRLF-authored doc, and the marker match survives it (it trims) while the exact header match
+// does not — so the check would fail a CORRECT document while naming a drifted header. One split,
+// before anything compares.
+const splitLines = (text) => String(text).split(/\r?\n/);
+
+const linesMatching = (lines, marker) => lines.flatMap((line, i) => (line.trim() === marker ? [i] : []));
+
+// Only leading and trailing BLANK lines are dropped. Trimming the joined block with String.trim()
+// would also eat significant edge whitespace INSIDE the first and last lines, which is drift the
+// comparison is supposed to see.
+const trimBlankEdges = (lines) => {
+  let start = 0;
+  let end = lines.length;
+  while (start < end && lines[start].trim() === '') start += 1;
+  while (end > start && lines[end - 1].trim() === '') end -= 1;
+  return lines.slice(start, end);
+};
+
+// parseAdvisorMatrix(text) → { ok: true, lines, rows } | { ok: false, reason }. `lines` is the whole
+// anchored block; `rows` are its class rows, parsed for the DIAGNOSIS only — the verdict is the
+// whole-block comparison in checkMatrixStructure, so a deleted alignment rule, a rewritten harness
+// lane and an extra row are all caught, none of which a class-row walk would ever see.
+export const parseAdvisorMatrix = (text) => {
+  const lines = splitLines(text);
+  const begins = linesMatching(lines, ADVISOR_MATRIX_BEGIN);
+  const ends = linesMatching(lines, ADVISOR_MATRIX_END);
+  if (begins.length !== 1 || ends.length !== 1) {
+    return { ok: false, reason: `the anchored matrix surface is not unique — found ${begins.length} "${ADVISOR_MATRIX_BEGIN}" and ${ends.length} "${ADVISOR_MATRIX_END}" (exactly one of each is required)` };
+  }
+  if (ends[0] < begins[0]) {
+    return { ok: false, reason: 'the matrix end marker precedes its begin marker — the anchored surface is inverted' };
+  }
+  const surface = trimBlankEdges(lines.slice(begins[0] + 1, ends[0]));
+  const headers = surface.filter((line) => line === ADVISOR_MATRIX_HEADER);
+  if (headers.length !== 1) {
+    return { ok: false, reason: `the anchored matrix surface carries ${headers.length} header line(s) equal to "${ADVISOR_MATRIX_HEADER}" — exactly one is required` };
+  }
+  const rows = [];
+  for (const line of surface.slice(surface.indexOf(ADVISOR_MATRIX_HEADER) + 1)) {
+    if (!line.startsWith('|')) continue;
+    const cells = line.split('|').slice(1, -1).map((c) => c.trim());
+    // Arity refuses OUTRIGHT rather than skipping the row: a row whose cell count disagrees with the
+    // header's is malformed whatever it says, and skipping it would report the drift as a MISSING
+    // class row — a true verdict reached through a misleading sentence.
+    if (cells.length !== ADVISOR_MATRIX_COLUMNS.length) {
+      return { ok: false, reason: `a matrix row carries ${cells.length} cell(s), the table has ${ADVISOR_MATRIX_COLUMNS.length} columns: ${line.trim()}` };
+    }
+    const classCell = /^`(.+)`$/.exec(cells[0]);
+    // A row whose first cell is not a backticked class joins no CLASS comparison — the harness lane,
+    // or an interloper. Neither escapes: the whole-block equality below sees every line.
+    if (classCell === null) continue;
+    rows.push(Object.fromEntries(ADVISOR_MATRIX_COLUMNS.map(({ key }, i) => [key, i === 0 ? classCell[1] : cells[i]])));
+  }
+  return { ok: true, lines: surface, rows };
+};
+
+const quoted = (classes) => classes.map((c) => `\`${c}\``).join(', ');
+
+// The DIAGNOSIS over the class rows, and the ORDER of its questions is the point. A POSITIONAL walk
+// reads a deleted middle row as a corrupted step-class cell in the row that slid up behind it —
+// technically a difference at that index, and a useless pointer for whoever has to fix the doc. So
+// membership is settled first (duplicated / missing / unregistered), then ORDER, and only over rows
+// that agree on both does a cell comparison run — where the first differing CELL is named, because
+// "row 3 disagrees" leaves the reader to diff four columns by eye.
+const rowDrift = (actual, expected) => {
+  const actualClasses = actual.map((r) => r.stepClass);
+  const expectedClasses = expected.map((r) => r.stepClass);
+
+  const duplicated = actualClasses.filter((c, i) => actualClasses.indexOf(c) !== i);
+  if (duplicated.length > 0) return `the advisor matrix names ${quoted([...new Set(duplicated)])} more than once — the registry has exactly one row per step class`;
+
+  const missing = expectedClasses.filter((c) => !actualClasses.includes(c));
+  if (missing.length > 0) return `the advisor matrix is missing ${missing.length} registry row(s): ${quoted(missing)}`;
+
+  const unregistered = actualClasses.filter((c) => !expectedClasses.includes(c));
+  if (unregistered.length > 0) return `the advisor matrix names ${unregistered.length} row(s) the registry does not: ${quoted(unregistered)}`;
+
+  const outOfOrder = actualClasses.findIndex((c, i) => c !== expectedClasses[i]);
+  if (outOfOrder !== -1) return `the advisor matrix is out of registry order — row ${outOfOrder + 1} is \`${actualClasses[outOfOrder]}\`, the registry has \`${expectedClasses[outOfOrder]}\``;
+
+  for (const [i, row] of actual.entries()) {
+    const e = expected[i];
+    const differing = ADVISOR_MATRIX_COLUMNS.find(({ key }) => row[key] !== e[key]);
+    if (differing !== undefined) {
+      return `matrix row ${i + 1} (\`${row.stepClass}\`): the ${differing.label} cell reads "${row[differing.key]}", the registry has "${e[differing.key]}"`;
+    }
+  }
+  return null;
+};
+
+// blockDrift(actual, expected) → null when the two blocks are IDENTICAL, else the first line that
+// disagrees. It is the verdict and the fallback diagnosis in one: "the blocks are equal" is exactly
+// "no line disagrees", so there is no second comparison to keep in step with this one — and the
+// null return is the path every green run takes, not an unreachable defensive branch.
+const blockDrift = (actual, expected) => {
+  for (let i = 0; i < Math.max(actual.length, expected.length); i += 1) {
+    if (actual[i] === expected[i]) continue;
+    if (actual[i] === undefined) return `the anchored matrix is missing line ${i + 1}, which the canonical table renders as ${JSON.stringify(expected[i])}`;
+    if (expected[i] === undefined) return `the anchored matrix carries an extra line ${i + 1}: ${JSON.stringify(actual[i])}`;
+    return `matrix line ${i + 1} reads ${JSON.stringify(actual[i])}, the canonical table renders ${JSON.stringify(expected[i])}`;
+  }
+  return null;
+};
+
+// checkMatrixStructure(readText) → the same shape a doc-parity binding result carries, so the report,
+// the --check line and the --json payload all render it through their existing paths. The VERDICT is
+// whole-block equality against the canonical render: every way the doc's table can stop being the
+// registry's table is one comparison, and the enumeration of those ways never has to be maintained.
+export const checkMatrixStructure = (readText = readKitDoc) => {
+  const rel = ADVISOR_MATRIX_DOC;
+  const expected = ADVISOR_ROWS.map(({ stepClass, vehicle, availabilityNote, returns }) => ({ stepClass, vehicle, availabilityNote, returns }));
+  let text;
+  try {
+    text = readText(rel);
+  } catch (err) {
+    return { constant: 'advisor-matrix-structure', files: [{ rel, ok: false, reason: `unreadable (${(err && err.code) || (err && err.message) || 'read failed'})` }], ok: false };
+  }
+  const parsed = parseAdvisorMatrix(text);
+  if (parsed.ok === false) {
+    return { constant: 'advisor-matrix-structure', files: [{ rel, ok: false, reason: parsed.reason }], ok: false };
+  }
+  // The VERDICT is the block comparison; the row walk only refines the MESSAGE when it can point at a
+  // class row. A block difference the row walk cannot explain (the alignment rule, the harness lane,
+  // an interloping row, whitespace) keeps the line-level pointer.
+  const drift = blockDrift(parsed.lines, splitLines(renderAdvisorMatrix()));
+  const reason = drift === null ? null : (rowDrift(parsed.rows, expected) ?? drift);
+  return { constant: 'advisor-matrix-structure', files: [{ rel, ok: reason === null, reason }], ok: reason === null };
+};

package/tools/autonomy-doctor.mjs

@@ -40,7 +40,7 @@
 import { spawnSync } from 'node:child_process';
 import { closeSync, lstatSync, openSync } from 'node:fs';
 import { join } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { isDirectRun } from './direct-run.mjs';
 import { isExecutableFile, probeSandboxAvailability } from './velocity-profile.mjs';
 import { assertDocsAiDeployment } from './atomic-write.mjs';
 
@@ -484,5 +484,4 @@ export const main = (argv, deps = {}) => {
   return finish(applied.status, applied.finalPlan);
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isDirectRun) process.exit(main(process.argv.slice(2)));
+if (isDirectRun(import.meta.url)) process.exit(main(process.argv.slice(2)));

package/tools/bridge-settings.mjs

@@ -23,7 +23,7 @@
 //
 // Dependency-free, Node >= 22. No side effects on import (the isDirectRun idiom).
 
-import { pathToFileURL } from 'node:url';
+import { isDirectRun } from './direct-run.mjs';
 import { settingValueValid } from './manifest/validate.mjs';
 import { writeHostConfigFileAtomic } from './atomic-write.mjs';
 import {
@@ -294,8 +294,7 @@ export const main = (argv = [], ctx = {}) => {
   }
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isDirectRun) {
+if (isDirectRun(import.meta.url)) {
   const r = main(process.argv.slice(2));
   if (r.stdout) console.log(r.stdout);
   if (r.stderr) console.error(r.stderr);

package/tools/cheap-agents.mjs

@@ -27,7 +27,8 @@
 
 import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
+import { isDirectRun } from './direct-run.mjs';
 import { shellQuoteArg } from './repo-lex.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -251,5 +252,4 @@ export const main = (argv = process.argv.slice(2), deps = {}) => {
   }
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isDirectRun) process.exit(main(process.argv.slice(2)));
+if (isDirectRun(import.meta.url)) process.exit(main(process.argv.slice(2)));

package/tools/commands.mjs

@@ -19,7 +19,7 @@
 // the `### Mode:` headers in SKILL.md, so the catalog cannot silently drift from the documented modes.
 // Pure, dependency-free, Node >= 22. No side effects on import (the isDirectRun idiom).
 
-import { pathToFileURL } from 'node:url';
+import { isDirectRun } from './direct-run.mjs';
 
 const SKILL_NAME = 'agent-workflow-kit';
 const BARE_INVOCATION = `/${SKILL_NAME}`;
@@ -264,7 +264,7 @@ const CATALOG = [
     invocation: invocationOf('dispatch'),
     group: 'Orchestrate',
     kind: WRITER,
-    oneLine: 'Measure delegation: check a sub-task brief’s contract block (form only — never whether the task is genuinely bounded), pre-register an acceptance wave with its thresholds, record one observation, open a delegated thread from that brief, wait for that one dispatch to answer — a wait that ends without an answer says so and authorizes nothing — absorb the wrapper’s receipt back into the ledger, fold the returned work or close the thread with a recorded degrade, and print the per-class report of how much a delegated sub-task actually bought, derived from what was dispatched, returned and folded. Writes only its own ledger file beside the repo; never commits.',
+    oneLine: 'Measure delegation: check a sub-task brief’s contract block (form only — never whether the task is genuinely bounded), ask which vehicle should carry that kind of sub-task on THIS machine and what past threads of that kind actually did — advice you may ignore, never a gate, printed on its own and again under a valid contract check, pre-register an acceptance wave with its thresholds, record one observation, open a delegated thread from that brief, wait for that one dispatch to answer — a wait that ends without an answer says so and authorizes nothing — absorb the wrapper’s receipt back into the ledger, fold the returned work or close the thread with a recorded degrade, and print the per-class report of how much a delegated sub-task actually bought, derived from what was dispatched, returned and folded. After a landing, deliver the handoff verbatim and count only what is fully measurable. Writes only its own ledger file beside the repo; never commits.',
   },
   {
     // NEVER `guarded` — that kind promises dry-run-first, which these writers do not have; the
@@ -273,7 +273,7 @@ const CATALOG = [
     invocation: invocationOf('worktrees'),
     group: 'Orchestrate',
     kind: WRITER,
-    oneLine: 'Run features in parallel git worktrees: provision an isolated sibling copy, list them, stage a finished one back onto clean main (the commit still asks in dialogue), and remove a live-verified landed one. No preview step; list is read-only; cleanup --abandon destroys unlanded work.',
+    oneLine: 'Run features in parallel git worktrees: provision an isolated sibling copy, list them, print the cold-start prompt a fresh session in one of them needs — where it is, what MAIN answers NOW rather than what the record froze, the handoff as the one way back, and the bars nothing enforces — stage a finished one back onto clean main (the commit still asks in dialogue), and remove a live-verified landed one. No preview step; list is read-only and so is prompt; cleanup --abandon destroys unlanded work.',
   },
 ];
 
@@ -380,7 +380,6 @@ const main = (argv) => {
   console.log(formatHelp());
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isDirectRun) main(process.argv.slice(2));
+if (isDirectRun(import.meta.url)) main(process.argv.slice(2));
 
 export { KINDS, SKILL_NAME, BARE_INVOCATION };

package/tools/commit-guard.mjs

@@ -11,7 +11,15 @@
 //      up to INDEX_LAG_PATH_CAP with the remainder stated. A dirty tracked SUBMODULE is named
 //      separately with its own recovery. Fail-closed on an undecidable probe. This BLOCKS the
 //      deliberate partial commit by design — `--no-verify` is the stated residual, not a flag;
-//   1. recomputes the CURRENT tree fingerprint (the review-state export — read-only git plumbing);
+//   1. recomputes the CURRENT tree fingerprint (the review-state export — read-only git plumbing),
+//      and decides the two CONTENT-FREE lanes here, because no store read can answer them: a
+//      payload with no bytes yields the ONE fingerprint every clean moment of every repository
+//      shares, so any receipt at it was minted elsewhere and may attest nothing. With a DIRTY
+//      index that means staged content the payload cannot see (a gitlink hidden by
+//      `submodule.<name>.ignore` / `diff.ignoreSubmodules`) and the guard REFUSES, naming the
+//      configuration rather than re-staging; with a clean index the commit introduces no bytes
+//      (`--allow-empty`, a message-only `--amend`, an empty merge) and the guard PASSES while
+//      stating that it attests NOTHING — the receipt arms are skipped, never satisfied;
 //   2. reads the LATEST completed final-run record from the core-evidence store (only the latest
 //      attempt at a fingerprint is authoritative — a green receipt is DEAD once a later attempt at
 //      the same fingerprint went red) and refuses on: no record for the current fingerprint · a
@@ -34,11 +42,15 @@
 
 import { readFileSync, lstatSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { pathToFileURL, fileURLToPath } from 'node:url';
+import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
+import { isDirectRun } from './direct-run.mjs';
 import { computeTreeFingerprint, buildState, decideCheck, quoteReportName, shellQuoteArg } from './review-state.mjs';
-import { resolveEvidencePath, readEvidence, authoritativeOfKind, canonicalKindSerialization, computeWorkingState } from './core-evidence.mjs';
+import {
+  resolveEvidencePath, readEvidence, authoritativeOfKind, canonicalKindSerialization,
+  computeWorkingState, CONTENT_FREE_FINGERPRINT,
+} from './core-evidence.mjs';
 import { resolveLcovPath } from './coverage-check.mjs';
 import { GATES_REL, loadDeclaration } from './run-gates.mjs';
 import { computeFlowDecision } from './flow-check.mjs';
@@ -177,15 +189,42 @@ export const decideIndexLag = (state) => {
 };
 
 // runGuard({ cwd, env }) → { code, lines }. Every refusal names its recovery.
+// The flow decision's two renders, shared by every lane that consults it — the empty-commit lane
+// reaches the same store through the same consumer mode, so its wording can never drift from the
+// byte-carrying one.
+const flowRefusalLines = (flow) => [
+  `commit-guard: REFUSED — the flow store refuses this commit: ${flow.refusals[0]}`,
+  ...flow.refusals.slice(1).map((r) => `commit-guard: flow refusal — ${r}`),
+];
+const flowAdvisoryLines = (flow) => (flow.present && flow.armed
+  ? flow.advisories.map((a) => `commit-guard: flow advisory — ${a}`)
+  : []);
+
 export const runGuard = ({ cwd = process.cwd(), env = process.env } = {}) => {
   const rootTop = gitLine(['rev-parse', '--show-toplevel'], cwd);
   if (rootTop == null) return { code: 1, lines: ['commit-guard: not a git work tree — nothing to guard'] };
   // FIRST: a pure tree property needing no store read. Its recovery re-stages the tree and re-mints
   // the receipt, so every arm below is re-decided anyway — naming a stale fingerprint ahead of it
   // would send the operator down a recovery they must redo.
-  const indexLag = decideIndexLag(computeWorkingState(cwd));
+  const working = computeWorkingState(cwd);
+  const indexLag = decideIndexLag(working);
   if (indexLag !== null) return indexLag;
   const fingerprint = computeTreeFingerprint(cwd);
+  // The CONTENT-FREE lanes — the second pure tree property, decided here for the same reason the
+  // index lag is: no store read can answer it. A payload with no bytes states nothing about what
+  // this commit will carry, and its fingerprint is the ONE value every clean moment of every
+  // repository shares, so a receipt found at it was minted by some other moment, possibly at
+  // another base. Such evidence must therefore decide NOTHING here — neither refuse nor attest
+  // (the same fact flow-check-rungs.mjs applies to a red final). The index tells the two lanes
+  // apart, and `computeWorkingState` probes it with --ignore-submodules=none precisely so a
+  // config-hidden gitlink cannot pass for a clean one.
+  const contentFree = fingerprint === CONTENT_FREE_FINGERPRINT;
+  if (contentFree && working.stagedDirty) {
+    return {
+      code: 1,
+      lines: [`commit-guard: REFUSED — the index carries staged content the fingerprint domain cannot see (a submodule gitlink hidden from \`git diff\` by \`submodule.<name>.ignore\` or \`diff.ignoreSubmodules\`), so no final receipt can describe what this commit will carry. Recovery: clear that ignore setting (or set it to \`none\`) until \`git diff --cached --no-ext-diff\` shows the change, then re-run node ${FINAL_RUN_TOOL} --final`],
+    };
+  }
   // The guard's OWN reads resolve FIXED git-dir paths — a stray AW_CORE_EVIDENCE / AW_LCOV_FILE
   // in the committing shell must never redirect the LAST line of defense to a forged artifact
   // (the env stays a test seam for the producers, never for this consumer).
@@ -194,6 +233,27 @@ export const runGuard = ({ cwd = process.cwd(), env = process.env } = {}) => {
   if ((read.malformed ?? 0) > 0 || read.readError) {
     return { code: 1, lines: [`commit-guard: REFUSED — evidence store unavailable (${read.malformed} malformed line(s)${read.readError ? `, read error: ${read.readError}` : ''}); inspect ${storePath}`] };
   }
+  // The empty-commit lane: the index equals HEAD, so this commit introduces no bytes at all
+  // (`git commit --allow-empty`, a message- or signature-only `--amend`, an empty merge). The
+  // guard's whole claim is about bytes, so here it has none to make and says so. The receipt arms
+  // are SKIPPED rather than satisfied — consulting a content-free receipt would make the outcome
+  // depend on which stray clean moment happened to be recorded last. The flow arm still runs: an
+  // empty commit still moves HEAD, and the chain bookkeeping is about that, not about bytes; its
+  // own fingerprint-keyed correlations (the D10 flow→final binding, receipt and degrade coverage)
+  // drop out inside flow-check on the same fact, so no stray content-free record decides here
+  // either. Store HEALTH is deliberately NOT waived above: an unreadable store is not a
+  // correlation, and a store that cannot be read cannot answer the chain questions either.
+  if (contentFree) {
+    const emptyFlow = computeFlowDecision({ cwd, consumer: 'commit-guard', treeCarriesBytes: false });
+    if (emptyFlow.refusals.length > 0) return { code: 1, lines: flowRefusalLines(emptyFlow) };
+    return {
+      code: 0,
+      lines: [
+        'commit-guard: PASS — this commit changes no tree content (the index contributes no tree-content delta and the work tree adds nothing), so the guard attests NOTHING about it: a receipt found at the shared content-free fingerprint cannot be correlated to THIS moment or base',
+        ...flowAdvisoryLines(emptyFlow),
+      ],
+    };
+  }
   const finals = authoritativeOfKind(read.records, 'final');
   const current = finals.find((r) => r.fingerprintBefore === fingerprint) ?? null;
   if (!current) {
@@ -255,15 +315,7 @@ export const runGuard = ({ cwd = process.cwd(), env = process.env } = {}) => {
   // evidenceHashes.flow and the store has since VANISHED (present=false) — a deletion must
   // never un-arm the binding. A no-store repo with no flow-bearing receipt still yields zero
   // refusals (byte-exact pre-flow behavior).
-  if (flow.refusals.length > 0) {
-    return {
-      code: 1,
-      lines: [
-        `commit-guard: REFUSED — the flow store refuses this commit: ${flow.refusals[0]}`,
-        ...flow.refusals.slice(1).map((r) => `commit-guard: flow refusal — ${r}`),
-      ],
-    };
-  }
+  if (flow.refusals.length > 0) return { code: 1, lines: flowRefusalLines(flow) };
   // The ship-receipt arm: the SAME normative decision review-state --check computes, over a
   // SANITIZED env — the receipts/evidence/flow-store overrides are producer test seams, and
   // honoring them HERE would let a forged store bypass the fixed-path reads above.
@@ -278,10 +330,7 @@ export const runGuard = ({ cwd = process.cwd(), env = process.env } = {}) => {
   const flowSuffix = flow.present && flow.armed
     ? ` — flow: armed${review.flowLabels?.length ? ` (${review.flowLabels.join('; ')})` : ''}`
     : '';
-  const flowAdvisoryLines = flow.present && flow.armed
-    ? flow.advisories.map((a) => `commit-guard: flow advisory — ${a}`)
-    : [];
-  return { code: 0, lines: [`commit-guard: PASS — a green final receipt binds this exact tree (${fingerprint.slice(0, 12)}…), the declaration and evidence hashes match, and the review obligations are satisfied${flowSuffix}`, ...flowAdvisoryLines] };
+  return { code: 0, lines: [`commit-guard: PASS — a green final receipt binds this exact tree (${fingerprint.slice(0, 12)}…), the declaration and evidence hashes match, and the review obligations are satisfied${flowSuffix}`, ...flowAdvisoryLines(flow)] };
 };
 
 const HELP = `commit-guard — the read-only pre-commit guard (agent-workflow family, D10).
@@ -291,7 +340,16 @@ Usage:
 
 Re-runs NOTHING: refuses an INDEX that lags the verified working tree (FIRST — unstaged tracked
 paths, reviewable untracked paths, or a dirty tracked submodule, each named with its recovery;
-this deliberately blocks a partial commit), then recomputes the current tree fingerprint and binds
+this deliberately blocks a partial commit), then recomputes the current tree fingerprint.
+
+A CONTENT-FREE fingerprint (a payload with no bytes — the value every clean work tree shares)
+decides WITHOUT a receipt, because one found there was minted by another clean moment: with a dirty
+index it REFUSES (staged content the payload cannot see — a gitlink hidden by
+\`submodule.<name>.ignore\` / \`diff.ignoreSubmodules\`; the recovery is that configuration, not
+\`git add\`), and with a clean index it PASSES stating it attests NOTHING (the commit carries no
+bytes: \`--allow-empty\`, a message-only \`--amend\`, an empty merge).
+
+Otherwise it binds
 the LATEST completed run-gates --final receipt — refusing on { no receipt for this tree · a red
 latest attempt · before≠after · declaration content drift · evidence-hash drift · lcov drift ·
 a flow-store refusal (a PRESENT store's open own chain / base motion / coverage — verbatim; no
@@ -324,8 +382,7 @@ export const main = (argv, ctx = {}) => {
   }
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isDirectRun) {
+if (isDirectRun(import.meta.url)) {
   const r = main(process.argv.slice(2));
   if (r.stdout) process.stdout.write(r.stdout.endsWith('\n') ? r.stdout : `${r.stdout}\n`);
   if (r.stderr) process.stderr.write(r.stderr.endsWith('\n') ? r.stderr : `${r.stderr}\n`);

package/tools/core-evidence.mjs

@@ -36,11 +36,11 @@
 
 import { readFileSync, lstatSync, realpathSync, readlinkSync, openSync, readSync, closeSync } from 'node:fs';
 import { join, dirname, normalize, sep, basename } from 'node:path';
-import { pathToFileURL } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { writeContainedFileAtomic } from './atomic-write.mjs';
 import { parsePositiveIntKnob, probeVerdict } from './changed-surface.mjs';
+import { isDirectRun } from './direct-run.mjs';
 import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
 import { lexicalRepoRelative } from './repo-lex.mjs';
 // The coverage vocabulary leaf: run-gates RECORDS the token this validator checks, and run-gates
@@ -160,6 +160,16 @@ export const computeTreeFingerprint = (cwd, fsx) => {
   return payload == null ? null : createHash('sha256').update(payload).digest('hex');
 };
 
+// The fingerprint of a CONTENT-FREE payload — a clean work tree emits no bytes at all, so this ONE
+// value is shared by every clean moment of every repository. It therefore identifies no working
+// state and correlates to no base: evidence found at it was minted by some other clean moment,
+// possibly at another base, and can decide nothing in either direction. Two situations reach it,
+// and only the INDEX tells them apart (never the payload): an empty commit, where the index equals
+// HEAD and no byte enters the repository, and staged content the payload cannot see — a gitlink
+// hidden from `git diff` by an ignore configuration. Read by the consumers that correlate a
+// fingerprint to a base (flow-check-rungs.mjs #65) and by commit-guard's two content-free lanes.
+export const CONTENT_FREE_FINGERPRINT = createHash('sha256').update(Buffer.alloc(0)).digest('hex');
+
 // The index↔worktree split the fingerprint deliberately CANNOT see: the payload above concatenates
 // the staged and unstaged diffs, so against an otherwise-empty index a hunk moving into the index
 // leaves it byte-identical — while `git commit` builds the commit from the INDEX alone. This is the
@@ -1220,8 +1230,7 @@ export const main = (argv, ctx = {}) => {
   }
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isDirectRun) {
+if (isDirectRun(import.meta.url)) {
   const r = main(process.argv.slice(2));
   if (r.stdout) process.stdout.write(r.stdout.endsWith('\n') ? r.stdout : `${r.stdout}\n`);
   if (r.stderr) process.stderr.write(r.stderr.endsWith('\n') ? r.stderr : `${r.stderr}\n`);