@sabaiway/agent-workflow-kit 5.11.0 → 5.11.2

package/CHANGELOG.md

@@ -4,6 +4,117 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 5.11.2 — the record vocabulary becomes a facade over five leaves (AD-103)
+
+**Nothing you import changes, and that is the whole claim — now certified rather than asserted.**
+`tools/flow-record.mjs` was the kit's most expensive module to read: 795 lines holding eleven of its
+own section seams, from the closed record vocabulary through the field shapes, the identity family,
+the two legality walks and the wrapper finding manifest. It keeps its path and its 29 export names,
+and becomes a 55-line re-export facade over five single-responsibility leaves.
+
+- **`tools/flow-record.mjs` keeps its path, its 29 export names and every one of its 30 import
+  sites.** The internals moved verbatim into `flow-vocabulary.mjs` (96, the lowest leaf: the closed
+  kinds, purposes, terminal lanes, seed assignment and transition table) · `flow-record-shape.mjs`
+  (283, the closed per-kind field shapes and `validateFlowRecord`) · `flow-record-identity.mjs` (115,
+  every answer to "what identifies this record or this set" — keys, tree identity, the canonical
+  digest, the owner-scoped projection) · `flow-legality.mjs` (248, the two raw-order legality walks)
+  · `flow-finding-manifest.mjs` (70). The edges run one way and the family is acyclic by
+  construction; no leaf reaches a write module, so "pure form" is a structural pin instead of a
+  header sentence.
+- **Conservation is certified by ORDER as well as by count.** A comparator normalises both sides
+  identically and then checks, per leaf, that its line SEQUENCE equals the concatenation of its
+  declared source ranges in declared order — a reordering is caught, not just a loss — AND that the
+  multiset over the union of the five leaves equals the pre-split module. Over the 587 executable
+  lines: five sequences EQUAL, the difference EMPTY in both directions. It was then run three more
+  times — against the unsplit module alone, with one leaf omitted, and with one line duplicated — so
+  a comparator that could not report loss or excess could not pass for one that does.
+- **The five shared grammars live in exactly one place.** `HEX64_RE`, `isHex64`, `isPlainObject`,
+  `isNonEmptyString` and `refuse` are exported off-surface from the lowest leaf and used by the
+  others. They are the record family's named grammars — `isHex64` IS the 64-hex digest grammar every
+  consumer takes by reference — and a per-leaf copy is the only way two of them could ever drift.
+  The layout suite pins that off-surface set exactly, so it cannot widen unnoticed.
+- **The owning suite never moved.** `tools/flow-record.test.mjs` is BYTE-IDENTICAL and reproduces
+  58/58; the fifteen named suites show an empty `git diff --name-only` in the worktree and under
+  `--cached`. `test/flow-record-layout.test.mjs` (not shipped) pins the frozen 29-name surface, the
+  facade-declared owner of every name, that the facade carries no logic at all, the size caps, and
+  the one-way edges including their negative direction — four of its five cases were red-proofed on
+  the unsplit tree before the split existed.
+- **`test/package-content.test.mjs` moves its payload pin from 227 to 232 files** and names the five
+  leaves: the facade imports all five, so a leaf falling out of the published tarball would break
+  every flow read at load, and the pin is what says so.
+- **One consumer line changed in the whole tree, and it is a comment.** `dispatch-record.mjs:15`
+  cited the fail-closed rule by line number (`flow-record.mjs:22-24`); the split falsified that
+  reference, so it now names the rule semantically.
+
+Recorded size effect, reason `tranche 3: flow-record split`:
+
+```text
+  agent-workflow-kit/test/package-content.test.mjs: lines 600 → 617 (raise)
+  agent-workflow-kit/tools/flow-record.mjs: lines 795 → none
+  agent-workflow-kit: aggregate lines 125315 → 125669 (raise)
+```
+
+## 5.11.1 — the flow store becomes a facade over five leaves, and the direct-run guard fix finally reaches you (AD-102)
+
+**A tool invoked through a symlink used to run nothing and exit 0 — and five of the affected tools are
+declared gates.** That fix has been sitting in-repo, unpublished, since the delegation series' own
+measurement came back FAIL and the fix was correctly held back from a release it should not have
+justified (AD-101). It ships here, on a regular train, because it is a bug fix and every deployed
+host still carries the broken form. Beside it, the flow store stops being one 827-line module.
+
+- **The direct-run entry guard now decides by REAL PATH, in all 66 frozen sites.** The lexical form
+  compared `import.meta.url` against `process.argv[1]`, which is false when the entry point is a
+  symlink — so the tool did nothing, said nothing, and exited 0. Every one of the 39 kit tools now
+  decides through the shipped `isDirectRun(import.meta.url)` leaf; the seven mirrored
+  `references/scripts` and `references/hooks` payload scripts, which cannot reach that leaf from a
+  deployed project, inline the same fail-closed realpath guard. `velocity-profile.mjs` also drops a
+  vestigial exported predicate with no importer. The new `test/direct-run-sweep.test.mjs` pins list
+  completeness, in-process import of all 39, the absence of the lexical byte pattern, and a SPAWNED
+  symlink smoke — observed red 3/3 before the fix, so the silent-pass class is proven dead rather than
+  believed dead.
+- **`tools/flow-store.mjs` keeps its path, its 29 export names and every one of its 22 import sites,
+  and becomes a 50-line re-export facade.** The flow-specific write side moved verbatim into five
+  leaves with one responsibility each and one-way edges: `flow-chain-state.mjs` (91, the pure chain
+  walk and the prior-terminal reference validator) · `flow-subset-budget.mjs` (81, the pure
+  Decision-7/8 counting-context budget) · `flow-append.mjs` (309, the store's ONE write door, keeping
+  the locked subset-attempt factory beside the lane it is the only sanctioned entrance to) ·
+  `flow-adoption-mint.mjs` (70) · `flow-delta-proof.mjs` (307, the bookkeeping-delta custody proof).
+  Nothing about the public surface moved, so nothing you import changes.
+- **The split is proven, not asserted.** A line-multiset conservation check compares the pre-split
+  module against the union of the five leaves and expects exactly two lines to have gained a copy —
+  and it was run twice more, against the unsplit module alone and with one leaf omitted, so that a
+  comparator which cannot report loss could not pass for one that does. The three owning suites are
+  BYTE-IDENTICAL and reproduce 169/169; the ten named suites show an empty `git diff --name-only`.
+  `test/flow-store-layout.test.mjs` (not shipped) now pins the frozen surface, that every facade name
+  is the SAME binding as its leaf's export, that the facade carries no logic at all, the size caps,
+  and the one-way import direction including its negative edges.
+- **`test/package-content.test.mjs` moves its payload pin from 222 to 227 files** and names the five
+  leaves: the facade imports all five, so a leaf falling out of the published tarball would break
+  every append at load, and the pin is what says so.
+
+Recorded size effect, reason `tranche 2: flow-store split`:
+
+```text
+  agent-workflow-kit/test/package-content.test.mjs: lines 583 -> 600 (raise)
+  agent-workflow-kit/tools/flow-store.mjs: lines 827 -> none
+  agent-workflow-kit: aggregate lines 124960 -> 125315 (raise)
+```
+
+Recorded size effect of the direct-run sweep that ships with it (reason: a standalone deployed script
+cannot reach the kit's shared direct-run leaf, so it inlines the realpath guard — one lexical line
+becomes an 11-line fail-closed IIFE; the 39 converted tool guards themselves only shrink):
+
+```text
+  agent-workflow-kit/references/hooks/gate-approve.mjs: lines 559 -> 570 (raise)
+  agent-workflow-kit/references/hooks/state-block-guard.mjs: lines 425 -> 437 (raise)
+  agent-workflow-kit/references/scripts/archive-changelog.mjs: lines 546 -> 557 (raise)
+  agent-workflow-kit/references/scripts/archive-decisions.mjs: lines 1199 -> 1210 (raise)
+  agent-workflow-kit/references/scripts/archive-issues.mjs: lines 415 -> 426 (raise)
+  agent-workflow-kit/references/scripts/check-docs-size.mjs: lines 580 -> 591 (raise)
+  agent-workflow-kit/references/scripts/migrate-gates.mjs: lines 722 -> 733 (raise)
+  agent-workflow-kit: aggregate lines 124726 -> 124805 -> 124925 -> 124960 (raise)
+```
+
 ## 5.11.0 — the fan-out half: which vehicle carries a sub-task, what a satellite is told, and what its handoff brings back (AD-100)
 
 **A delegated thread could be recorded end to end, and the two questions around it still had no

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow".
 disable-model-invocation: true
 metadata:
-  version: '5.11.0'
+  version: '5.11.2'
 ---
 
 # agent-workflow-kit

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "5.11.0",
+  "version": "5.11.2",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "5.11.0",
+  "version": "5.11.2",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/references/hooks/gate-approve.mjs

@@ -85,7 +85,7 @@
 
 import { readFileSync, realpathSync } from 'node:fs';
 import { join } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
 
 export const HOOK_EVENT_NAME = 'PreToolUse';
 export const BASH_TOOL_NAME = 'Bash';
@@ -555,5 +555,16 @@ export const main = async () => {
   return EXIT_OK;
 };
 
-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) main().then((code) => process.exit(code));

package/references/hooks/state-block-guard.mjs

@@ -37,7 +37,8 @@
 // fields (`decision`, `continue`, `stopReason`, `hookSpecificOutput`) are deliberately never emitted:
 // blocking the stop would re-enter the model on a message already sent to the reader.
 
-import { pathToFileURL } from 'node:url';
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 
 export const HOOK_EVENT_NAME = 'Stop';
 const EXIT_OK = 0;
@@ -419,7 +420,18 @@ export const main = async ({
   return EXIT_OK;
 };
 
+// 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;
+  }
+})();
 // `process.exitCode`, never `process.exit()`: an immediate exit can truncate a pending stdout write
 // to a pipe, and that single warning is the entire product of this hook.
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
 if (isDirectRun) main().then((code) => { process.exitCode = code; });

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/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}`;
@@ -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

@@ -42,9 +42,10 @@
 
 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,
@@ -381,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
@@ -1230,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`);

package/tools/coverage-check.mjs

@@ -23,9 +23,9 @@
 import { lstatSync, readFileSync, realpathSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { join } from 'node:path';
-import { pathToFileURL } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import { computeChangedSurface } from './changed-surface.mjs';
+import { isDirectRun } from './direct-run.mjs';
 import { lcovCoveredMap, uncoveredChangedFromLcov } from './lcov.mjs';
 import {
   computeTreeFingerprint,
@@ -365,8 +365,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)) {
   // The capability is CONSUMED here: snapshot it, then remove it from this process's environment
   // before anything spawns. Every `git` query and every bound-test probe below inherits
   // process.env, so leaving it in place would hand a live attestation context to each of them —

package/tools/delegation.mjs

@@ -10,7 +10,7 @@
 
 import { statSync } from 'node:fs';
 import { join, resolve } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { isDirectRun } from './direct-run.mjs';
 import { validateManifest, VALID } from './manifest/validate.mjs';
 
 // The exact skill name a delegable memory candidate must declare (guards against a wrong-name
@@ -120,5 +120,4 @@ const main = (argv) => {
   console.log(`[delegation] commit gate: ${plan.commitGate} (memory raises its own gate: ${plan.memoryRaisesCommitGate})`);
 };
 
-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));

package/tools/detect-backends.mjs

@@ -21,8 +21,8 @@
 
 import { existsSync, statSync, accessSync, realpathSync, constants } from 'node:fs';
 import { join } from 'node:path';
-import { pathToFileURL } from 'node:url';
 import os from 'node:os';
+import { isDirectRun } from './direct-run.mjs';
 import { validateManifest, UNSUPPORTED, INVALID } from './manifest/validate.mjs';
 
 // Probe states. `unknown` (a wrapped fs error) NEVER counts as present in any readiness rule.
@@ -439,5 +439,4 @@ const main = (_argv, deps = {}) => {
   process.exit(0); // informational, like validate.mjs non-strict — never blocks anything
 };
 
-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));

package/tools/dispatch-record.mjs

@@ -12,7 +12,7 @@
 //
 // The record family (D3, versioned + closed): pre-registration · dispatch · return · fold ·
 // observation · degrade. Fail-closed in BOTH directions — unknown schema, unknown kind, a missing
-// field, a malformed field and an unknown EXTRA field are all refusals (the flow-record.mjs:22-24
+// field, a malformed field and an unknown EXTRA field are all refusals (the flow-record.mjs header's
 // discipline): the per-record canonical digest is the record's identity, so a stray key would fork
 // it.
 //

package/tools/doc-parity.mjs

@@ -19,7 +19,6 @@
 // Read-only: never writes, never commits, never runs a subscription CLI, spawns nothing. Dependency-
 // free, Node >= 22. No side effects on import (the isDirectRun idiom).
 
-import { pathToFileURL } from 'node:url';
 import { EXIT as DOCTOR_EXIT, STATUS as DOCTOR_STATUS, TRUSTED_DIRS as DOCTOR_TRUSTED_DIRS } from './autonomy-doctor.mjs';
 import {
   RECOMMENDATIONS_SECTION_HEADER,
@@ -30,6 +29,7 @@ import {
   VERDICT_SKIPS_TEMPLATE,
   ACKS_FILE,
 } from './recommendations.mjs';
+import { isDirectRun } from './direct-run.mjs';
 import { SKIPPED_READONLY } from './setup-backends.mjs';
 // The parity verdicts that read-only skip may report — a CLOSED set the same two mode docs enumerate.
 import { PARITY } from './refresh-parity.mjs';
@@ -338,8 +338,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/family-registry.mjs

@@ -18,9 +18,10 @@
 
 import { existsSync, statSync, readFileSync, lstatSync } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
-import { pathToFileURL, fileURLToPath } from 'node:url';
+import { fileURLToPath } from 'node:url';
 import os from 'node:os';
 import { resolveDir, detectBackends, findOnPath } from './detect-backends.mjs';
+import { isDirectRun } from './direct-run.mjs';
 // The ONE dependency-free semver (shared with bin/install.mjs) — the bridge freshness probe compares
 // the placed version against the kit-bundled mirror; null-on-unparseable maps to 'unknown' (INV-B).
 import { parseSemver, compareSemver } from './semver-lite.mjs';
@@ -773,5 +774,4 @@ const main = (argv) => {
   console.log(args.surface.mode === 'json' ? JSON.stringify(envelope, null, 2) : render(toViewModel(envelope), args.surface));
 };
 
-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));