@sabaiway/agent-workflow-kit 5.11.0 → 5.11.1

package/CHANGELOG.md

@@ -4,6 +4,67 @@ 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.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.1'
 ---
 
 # 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.1",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "5.11.0",
+  "version": "5.11.1",
   "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/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));

package/tools/flow-adoption-mint.mjs

@@ -0,0 +1,70 @@
+// flow-adoption-mint.mjs — the adoption mint (#58): the frontmatter planId reader and mintAdoption,
+// which binds a plan's chain identity to {frontmatter planId, plan content digest} and lands the
+// chain's FIRST record. Split out of flow-store.mjs unchanged (baseline-practices tranche 2); the
+// facade re-exports both names.
+//
+// The plan file is READ, never written. Imports run ONE way: this leaf mints through the store's
+// ONE append door (flow-append.mjs) and never reaches the flow-store.mjs facade or its sibling mint
+// leaf — the one-line sha256Hex below is a deliberate copy rather than a sideways import.
+
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { FLOW_SCHEMA_VERSION, CHAIN_KIND, canonicalFlowDigest } from './flow-record.mjs';
+import { resolveBase, computeTreeFingerprint } from './core-evidence.mjs';
+import { flowStoreStop, resolveFlowStorePath, readFlowStore, deriveFlowOwner } from './flow-store-read.mjs';
+import { appendFlowRecord } from './flow-append.mjs';
+
+const stop = flowStoreStop;
+const sha256Hex = (bytes) => createHash('sha256').update(bytes).digest('hex');
+
+const PLAN_ID_FRONTMATTER_HINT = 'planId: <your-stable-plan-id>';
+
+// Identity binds only a CLOSED leading frontmatter block — an unterminated block never yields an
+// id; CRLF is normalized per line so line endings never fork chain identity.
+export const readPlanFrontmatterId = (text) => {
+  const lines = text.split('\n').map((line) => line.replace(/\r$/, ''));
+  if (lines[0]?.trim() !== '---') return null;
+  const close = lines.findIndex((line, i) => i > 0 && line.trim() === '---');
+  if (close === -1) return null;
+  for (const line of lines.slice(1, close)) {
+    const m = /^planId:[ \t]*(\S+)[ \t]*$/.exec(line);
+    if (m) return m[1];
+  }
+  return null;
+};
+
+export const mintAdoption = ({ cwd = process.cwd(), env = process.env, deps = {}, planPath, planLabel, cycle = 1, commitEpoch = 0, timestamp = new Date().toISOString() } = {}) => {
+  const owner = deriveFlowOwner(cwd);
+  if (owner == null) throw stop('not inside a git work tree — the adoption mint derives the owning worktree and the tree fingerprint from git (fail closed)');
+  let planBytes;
+  try {
+    planBytes = readFileSync(resolve(cwd, planPath));
+  } catch (err) {
+    throw stop(`cannot read the plan file ${planPath} (${(err && err.code) || (err && err.message) || err}) — the adoption mint READS an existing plan file (fail closed)`);
+  }
+  const planId = readPlanFrontmatterId(planBytes.toString('utf8'));
+  if (planId == null) {
+    throw stop(`the plan file ${planPath} carries no frontmatter planId — plan filenames are never chain identity. Add this line inside a leading "---" frontmatter block:\n${PLAN_ID_FRONTMATTER_HINT}\nand re-run; the plan file is never written by this mint (fail closed)`);
+  }
+  const planDigest = sha256Hex(planBytes);
+  // A pre-append read purely for the NAMED refusal: the locked append would refuse a second
+  // adoption anyway, but only this comparison can surface whether the plan content still matches.
+  const resolved = resolveFlowStorePath(cwd, env);
+  const adopted = resolved == null ? undefined : readFlowStore(resolved).records
+    .find((r) => r.kind === CHAIN_KIND && r.purpose === 'adoption' && r.planId === planId);
+  if (adopted !== undefined) {
+    throw stop(adopted.planDigest === planDigest
+      ? `plan "${planId}" is already adopted (content digest unchanged — a rename never resets chain identity); adoption is only ever the chain's first record`
+      : `plan "${planId}" is already adopted and the plan file content no longer matches its adoption record (recorded ${adopted.planDigest.slice(0, 12)}…, current ${planDigest.slice(0, 12)}…) — re-adopting edited plan content is refused; the digest mismatch is surfaced, never silent`);
+  }
+  const fingerprint = computeTreeFingerprint(cwd);
+  if (fingerprint == null) throw stop('cannot compute the tree fingerprint — the adoption record binds {base, fingerprint} (fail closed)');
+  const record = {
+    schema: FLOW_SCHEMA_VERSION, kind: CHAIN_KIND, purpose: 'adoption', planId, cycle, round: 0,
+    commitEpoch, owner, base: resolveBase(cwd), timestamp, stepId: null, fingerprint,
+    planLabel: planLabel ?? planId, createdAt: timestamp, planDigest,
+  };
+  const { writtenPath } = appendFlowRecord({ cwd, record, env, deps });
+  return { writtenPath, record, digest: canonicalFlowDigest(record) };
+};