session-orchestrator 5.0.0 → 5.2.0

package/scripts/lib/validate/check-entry-guard.mjs

@@ -0,0 +1,366 @@
+#!/usr/bin/env node
+/**
+ * check-entry-guard.mjs — census of SYMLINK-FRAGILE ESM entry guards.
+ *
+ * ## The defect class (#1371)
+ *
+ * A module that runs `main()` only when invoked as a CLI compares "the module I
+ * am" against "the script Node was told to run". The two are not the same kind
+ * of path: Node resolves `import.meta.url` to the **realpath**, while
+ * `process.argv[1]` is the path **as typed**. With a symlink anywhere in the
+ * invocation path — a `node_modules/.bin/` shim, a `~/bin` convenience link, a
+ * plugin directory symlinked into `~/.claude/plugins/`, or `/tmp` itself (a
+ * symlink to `/private/tmp` on macOS) — the comparison is false.
+ *
+ * The failure mode is the worst shape a defect can have: `main()` never runs,
+ * nothing is printed, and the process exits 0. Every caller reads that as
+ * success.
+ *
+ * The fix is `isMainModule()` from `scripts/lib/is-main-module.mjs`, which
+ * realpaths BOTH sides. This check is the recurrence guard: it fails the build
+ * when a new hand-written comparison appears.
+ *
+ * ## Oracle
+ *
+ * Over every tracked `.mjs` under `scripts/` + `hooks/` (via `git ls-files`,
+ * so an untracked scratch file is never a finding):
+ *
+ *   1. strip comments (line comments, trailing `//`, and block comments),
+ *   2. split the remainder into statement fragments on `;{}`,
+ *   3. inside each fragment mentioning `process.argv[1]`, apply two oracles:
+ *      a. **comparison form** — take every `===` / `!==` comparison and its two
+ *         operands (bounded to the adjacent `&&` / `||` segment) and FAIL when
+ *         one operand mentions `process.argv[1]` and the other mentions
+ *         `import.meta.url` or `__filename`;
+ *      b. **bare-basename form** — FAIL on `process.argv[1].endsWith('x.mjs')`
+ *         (plus the `?.`, `String(...)` and `(argv[1] || '')` receiver
+ *         variants) against a `.mjs`/`.js`/`.cjs` string literal. This form has
+ *         no comparison operator at all, so oracle (a) never saw it.
+ *   4. In both cases, a fragment wrapping either side in a `realpath*` call is
+ *      the safe idiom and must not be flagged.
+ *
+ * Both oracles are anchored on a SYNTAX shape, which is what keeps prose out of
+ * the census: `scripts/validate-plugin.mjs`,
+ * `scripts/lib/vault-consolidate-fs.mjs`, `hooks/post-edit-import-probe.mjs`
+ * and this file's own header all MENTION a broken idiom inside a comment and
+ * are excluded by step 1 without needing an allowlist entry.
+ * `scripts/lib/baseline-archetypes.mjs` (`await import(process.argv[1])`) is a
+ * deliberate cross-process trick that is neither a comparison nor a basename
+ * test — out of scope for this check.
+ *
+ * `scripts/lib/ecosystem-wizard.mjs` (bare `argv[1].endsWith(...)`) and
+ * `scripts/lib/fetch-baseline.mjs` (a hybrid `===`-plus-`endsWith` guard, which
+ * needed the ALLOWLIST below) were the two hand-written guards this check was
+ * built to catch (#1371); both were fixed to `isMainModule()` in #1378. Oracle
+ * (b) was added afterwards because reverting the FIRST of them was caught by
+ * nothing: the bare form was outside oracle (a) by construction, and neither
+ * file's symlink smoke test reproduced its own regression (a same-named file
+ * behind a symlinked DIRECTORY still ends with the basename). The allowlist is
+ * empty — kept as a frozen mechanism (see its docblock) rather than deleted,
+ * since the next hand-written exception is exactly what would re-populate it.
+ *
+ * `scripts/lib/is-main-module.mjs` itself is excluded: it is the fix, and its
+ * docblock quotes every variant it replaces.
+ *
+ * ## Mode: BLOCKING
+ *
+ * Unlike the WARN-only censuses in validate-plugin (`check-unwired-features`,
+ * `check-learning-provenance`, `check-vcs-repo-flag`), this one blocks. It can
+ * do so honestly because the backlog was drained to zero in the same change
+ * that introduced it — a blocking gate is only dishonest when it is red on
+ * arrival for work nobody intends to do.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { isMainModule } from '../is-main-module.mjs';
+
+/**
+ * Files whose `process.argv[1]` comparison the oracle flags but which are NOT
+ * the defect class. Every entry carries the reason it is exempt; a stale entry
+ * (one the oracle no longer flags) is itself reported, so this list cannot rot
+ * into a silent suppression.
+ *
+ * Empty since #1378: the one entry this list ever carried
+ * (`scripts/lib/fetch-baseline.mjs`, whose hybrid guard's `endsWith(basename)`
+ * fallback made it non-fragile) was removed when that file was fixed to
+ * `isMainModule()` instead of being kept as a hand-verified exception. The
+ * mechanism is retained rather than deleted: the stale-entry check below only
+ * fires for an entry that is PRESENT and no longer flagged, so an empty object
+ * never trips it, and a future hand-written exception can still be recorded
+ * here.
+ *
+ * @type {Record<string, string>}
+ */
+const ALLOWLIST = {};
+
+/** The one module allowed to contain every broken variant: it documents them. */
+const SELF_EXEMPT = 'scripts/lib/is-main-module.mjs';
+
+/**
+ * Remove comments while preserving character offsets (so line numbers survive).
+ *
+ * @param {string} src module source
+ * @returns {string} same length, comment bytes replaced by spaces
+ */
+export function stripComments(src) {
+  const out = src.split('');
+  let i = 0;
+  let mode = 'code';
+  while (i < src.length) {
+    const two = src.slice(i, i + 2);
+    if (mode === 'code') {
+      if (two === '//') mode = 'line';
+      else if (two === '/*') mode = 'block';
+      else if (src[i] === '`' || src[i] === "'" || src[i] === '"') {
+        // Skip OVER the literal to its closing delimiter, leaving the contents
+        // intact. This is load-bearing, not hygiene: the V1 idiom is
+        // \`file://${process.argv[1]}\` and the `//` in `file://` reads as a line
+        // comment to a naive scanner, which blanks the rest of the line and
+        // makes the most common variant of the defect class invisible.
+        const quote = src[i];
+        i++;
+        while (i < src.length && src[i] !== quote) {
+          if (src[i] === '\\') i++;
+          i++;
+        }
+        i++;
+        continue;
+      }
+    }
+    if (mode === 'line') {
+      if (src[i] === '\n') mode = 'code';
+      else out[i] = ' ';
+    } else if (mode === 'block') {
+      if (src[i] !== '\n') out[i] = ' ';
+      if (two === '*/') {
+        out[i] = ' ';
+        out[i + 1] = ' ';
+        i += 2;
+        mode = 'code';
+        continue;
+      }
+    }
+    i++;
+  }
+  return out.join('');
+}
+
+/**
+ * A `.endsWith('<something>.mjs')` call with a module-basename-shaped literal.
+ * Scanned rather than matched in one shot so the RECEIVER can be judged from the
+ * text preceding each hit — a `.endsWith()` on anything other than
+ * `process.argv[1]` is not this defect class.
+ *
+ * The quote characters are spelled `\x27` / `\x22` / `\x60` rather than
+ * literally, and that is load-bearing for THIS file specifically: `stripComments`
+ * below has no notion of a regex literal, so a bare `'` inside one reads as the
+ * start of a string and desynchronises the scanner for the rest of the module —
+ * measured 2026-09-17, a literal-quote version of this regex made the census
+ * report a line-comment 40 lines further down as a finding. Same rule applies to
+ * every regex added to this module.
+ */
+const ENDS_WITH_LITERAL = /endsWith\(\s*([\x27\x22\x60])([^\x27\x22\x60]*)\1\s*\)/g;
+
+/**
+ * The receiver chain, whitespace-stripped, that makes an `.endsWith()` call a
+ * test on the invocation path. Deliberately unanchored at the START so an outer
+ * wrapper (`String(...)`, `path.basename(...)`) still matches; anchored at the
+ * END so only the call immediately downstream of `process.argv[1]` counts.
+ */
+const ARGV_RECEIVER_TAIL = /process\.argv\[1\](?:\|\|\x27\x27|\|\|\x22\x22)?\)*\??\.$/;
+
+/**
+ * Findings for one module body.
+ *
+ * `kind` distinguishes the two oracles: `comparison` is the
+ * `argv[1] === import.meta.url` family, `basename` the bare
+ * `argv[1].endsWith('x.mjs')` family. Both are symlink-fragile; only the remedy
+ * wording differs.
+ *
+ * @param {string} src module source
+ * @returns {Array<{line: number, text: string, kind: 'comparison'|'basename'}>} one per fragile guard
+ */
+export function findFragileGuards(src) {
+  // Template substitutions are rewritten `${x}` → `$(x)` BEFORE the fragment
+  // split: the V1 idiom `import.meta.url === \`file://${process.argv[1]}\`` puts
+  // braces INSIDE the comparison, so splitting on `{}` would tear the statement
+  // in two and the most common variant of the defect class (12 of 50 files at
+  // ca214376) would never be seen. Length is preserved so line numbers survive.
+  const stripped = stripComments(src).replace(/\$\{([^{}]*)\}/g, (_m, inner) => `$(${inner})`);
+  const findings = [];
+  let cursor = 0;
+  for (const fragment of stripped.split(/[;{}]/)) {
+    const fragStart = cursor;
+    cursor += fragment.length + 1;
+    if (!fragment.includes('process.argv[1]')) continue;
+
+    /** @type {(offset: number) => number} 1-based line of an offset in `fragment` */
+    const lineAt = (offset) =>
+      stripped.slice(0, Math.min(fragStart + offset, stripped.length)).split('\n').length;
+
+    if (!/import\.meta\.url|__filename/.test(fragment)) {
+      // Oracle (b): no self-path mention at all, so the comparison oracle below
+      // cannot see this fragment. The bare basename test lives exactly here.
+      if (!/realpath/i.test(fragment)) {
+        ENDS_WITH_LITERAL.lastIndex = 0;
+        let m;
+        while ((m = ENDS_WITH_LITERAL.exec(fragment)) !== null) {
+          if (!/\.(?:mjs|js|cjs)$/.test(m[2])) continue;
+          const receiver = fragment.slice(0, m.index).replace(/\s+/g, '');
+          if (!ARGV_RECEIVER_TAIL.test(receiver)) continue;
+          findings.push({
+            line: lineAt(m.index),
+            text: `process.argv[1]…${m[0]}`,
+            kind: 'basename',
+          });
+          break; // one finding per statement is enough to act on
+        }
+      }
+      continue;
+    }
+
+    const parts = fragment.split(/===|!==/);
+    for (let k = 0; k < parts.length - 1; k++) {
+      const left = parts[k].split(/&&|\|\|/).pop() ?? '';
+      const right = parts[k + 1].split(/&&|\|\|/)[0] ?? '';
+      const mentionsArgv = /process\.argv\[1\]/.test(left) || /process\.argv\[1\]/.test(right);
+      const mentionsSelf =
+        /import\.meta\.url|__filename/.test(left) || /import\.meta\.url|__filename/.test(right);
+      if (!mentionsArgv || !mentionsSelf) continue;
+      if (/realpath/i.test(left) || /realpath/i.test(right)) continue; // the safe idiom
+      const line = lineAt(parts.slice(0, k + 1).join('===').length || 0);
+      findings.push({
+        line,
+        text: `${left.trim()} === ${right.trim()}`.replace(/\s+/g, ' '),
+        kind: 'comparison',
+      });
+      break; // one finding per statement is enough to act on
+    }
+  }
+  return findings;
+}
+
+/**
+ * Tracked `.mjs` files under `scripts/` and `hooks/`.
+ *
+ * @param {string} repoRoot absolute repo root
+ * @returns {string[]} repo-relative POSIX paths
+ */
+function trackedModules(repoRoot) {
+  // Pathspecs are DIRECTORIES, not `scripts/**/*.mjs`: git's wildmatch requires
+  // `**` to consume at least one path component, so a `scripts/**/*.mjs` spec
+  // silently drops every top-level `scripts/*.mjs` AND all of `hooks/*.mjs` —
+  // measured 2026-09-16: 61 files matched vs 176 actually tracked. The extension
+  // filter therefore lives here, where it cannot be wrong about that.
+  //
+  // Re-measured 2026-09-17 (the 61/176 pair no longer reproduces at any scope I
+  // could reconstruct, so it is kept as-dated rather than edited):
+  // `git ls-files -- 'scripts/**/*.mjs' 'hooks/**/*.mjs' | wc -l` → 422 against
+  // `git ls-files -- scripts hooks | grep -c '\.mjs$'` → 508. Direction of the
+  // trap is unchanged; only the magnitude moved.
+  const out = execFileSync('git', ['ls-files', '--', 'scripts', 'hooks'], {
+    cwd: repoRoot,
+    encoding: 'utf8',
+    maxBuffer: 32 * 1024 * 1024,
+  });
+  return out
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l.endsWith('.mjs'));
+}
+
+/**
+ * Run the census.
+ *
+ * @param {string} repoRoot absolute repo root
+ * @returns {Promise<number>} 0 clean · 1 findings · 2 tool error
+ */
+export async function runCheckEntryGuard(repoRoot) {
+  let files;
+  try {
+    files = trackedModules(repoRoot);
+  } catch (err) {
+    console.log(`  FAIL: cannot enumerate tracked modules: ${err.message}`);
+    console.log('');
+    console.log('Results: 0 passed, 1 failed');
+    return 2;
+  }
+
+  let failed = 0;
+  const flagged = new Set();
+  for (const rel of files) {
+    if (rel === SELF_EXEMPT) continue;
+    let body;
+    try {
+      body = readFileSync(path.join(repoRoot, rel), 'utf8');
+    } catch {
+      continue; // deleted between ls-files and read — not this check's business
+    }
+    const findings = findFragileGuards(body);
+    if (findings.length === 0) continue;
+    flagged.add(rel);
+    if (rel in ALLOWLIST) continue;
+    for (const f of findings) {
+      const why =
+        f.kind === 'basename'
+          ? 'a basename test answers "was a file with this name run?", never "was THIS ' +
+            'module run" — it is true for any same-named file (a sibling copy, a ' +
+            'vendored duplicate, a fixture) and resolves no path at all, so main() ' +
+            'fires or stays silent for reasons unrelated to identity'
+          : '`import.meta.url` is the realpath, `process.argv[1]` is the path as typed, ' +
+            'so the guard is false under any symlinked invocation and main() silently ' +
+            'never runs (exit 0, no output)';
+      console.log(
+        `  FAIL: ${rel}:${f.line} — symlink-fragile entry guard \`${f.text}\`: ${why}. ` +
+          'Use `isMainModule(import.meta.url)` from scripts/lib/is-main-module.mjs',
+      );
+      failed++;
+    }
+  }
+
+  const censused = new Set(files);
+  for (const [rel, reason] of Object.entries(ALLOWLIST)) {
+    if (flagged.has(rel)) continue;
+    // Not present at all (a fixture repo, a fork that deleted the file) is not
+    // rot — only an entry whose file IS censused and no longer flagged is.
+    if (!censused.has(rel)) continue;
+    console.log(
+      `  FAIL: ${rel} — stale allowlist entry: the oracle no longer flags this file, ` +
+        `so the exemption (“${reason}”) suppresses nothing. Remove it.`,
+    );
+    failed++;
+  }
+
+  if (failed === 0) {
+    console.log(
+      `  PASS: censused ${files.length} tracked module(s) under scripts/ + hooks/ — ` +
+        `0 symlink-fragile entry guard(s), ${Object.keys(ALLOWLIST).length} allowlisted`,
+    );
+  }
+  console.log('');
+  console.log(`Results: ${failed === 0 ? 1 : 0} passed, ${failed} failed`);
+  return failed === 0 ? 0 : 1;
+}
+
+if (isMainModule(import.meta.url)) {
+  const argv = process.argv.slice(2);
+  const usage =
+    'Usage: check-entry-guard.mjs [<repo-root>]\n' +
+    'Exit: 0 clean · 1 symlink-fragile entry guard(s) found · 2 tool error';
+  if (argv.includes('--help')) {
+    console.log(usage);
+    process.exitCode = 0;
+  } else {
+    const positional = argv.filter((a) => !a.startsWith('--'));
+    const unknown = argv.filter((a) => a.startsWith('--') && a !== '--help');
+    if (unknown.length > 0) {
+      console.error(`Unknown flag(s): ${unknown.join(', ')}\n${usage}`);
+      process.exitCode = 1;
+    } else {
+      process.exitCode = await runCheckEntryGuard(path.resolve(positional[0] ?? process.cwd()));
+    }
+  }
+}

package/scripts/lib/validate/check-guard-requires-parity.mjs

@@ -14,8 +14,8 @@
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
 import { parse } from '@babel/parser';
+import { isMainModule } from '../is-main-module.mjs';
 
 const HOOKS_RELATIVE_DIR = 'hooks';
 const MODULE_RELATIVE_PREFIX = 'scripts/lib';
@@ -1137,7 +1137,7 @@ export function runCheckGuardRequiresParity(pluginRoot) {
   return inspection.toolError ? 2 : 1;
 }
 
-const isMain = import.meta.url === pathToFileURL(process.argv[1] || '').href;
+const isMain =isMainModule(import.meta.url);
 if (isMain) {
   const pluginRoot = process.argv[2];
   if (!pluginRoot) {

package/scripts/lib/validate/check-hooks-emit-event-guard.mjs

@@ -79,9 +79,9 @@
 
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
 import { parse } from '@babel/parser';
 import { listRepoFiles } from './repo-files.mjs';
+import { isMainModule } from '../is-main-module.mjs';
 
 // ---------------------------------------------------------------------------
 // Baseline — Map<key, reason>, keyed on
@@ -359,7 +359,7 @@ export function runCheckHooksEmitEventGuard(repoRoot, options) {
   return failCount > 0 ? 1 : 0;
 }
 
-const isMain = import.meta.url === pathToFileURL(process.argv[1] || '').href;
+const isMain =isMainModule(import.meta.url);
 if (isMain) {
   const root = process.argv[2];
   if (!root) {

package/scripts/lib/validate/check-learning-provenance.mjs

@@ -126,7 +126,6 @@
 
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
 import { readLearnings } from '../learnings/io.mjs';
 // THE shared key derivation. This check resolves a rule's STAMPED
 // `learning-key` against keys it derives from the store, so it is the one place
@@ -134,6 +133,7 @@ import { readLearnings } from '../learnings/io.mjs';
 // finding — it must derive the key with the emitter's function, not a copy of
 // the emitter's formula.
 import { learningKeyOf } from '../learnings/kebab.mjs';
+import { isMainModule } from '../is-main-module.mjs';
 
 /** Directory holding the rule corpus, relative to the plugin root. */
 const RULES_REL = path.join('.claude', 'rules');
@@ -475,7 +475,7 @@ export async function runCheckLearningProvenance(pluginRoot) {
   return 0;
 }
 
-const isMain = import.meta.url === pathToFileURL(process.argv[1] || '').href;
+const isMain =isMainModule(import.meta.url);
 if (isMain) {
   const argv = process.argv.slice(2);
   const flags = new Set(argv.filter((a) => a.startsWith('--')));

package/scripts/lib/validate/check-skill-links.mjs

@@ -20,7 +20,7 @@
  * citations, not intra-surface markdown links. Different predicate, different blind spot.
  *
  * WHAT IT CHECKS
- *   For every `.md` under the scanned surfaces, every inline link `[text](target)` whose target is
+ *   For every `.md`/`.mdc` under the scanned surfaces, every inline link `[text](target)` whose target is
  *   relative (not http(s):, not mailto:, not `#anchor`, not an absolute path) must exist on disk,
  *   resolved against the LINKING FILE's own directory. A `#fragment` suffix is stripped before the
  *   existence check — anchors are out of scope (no heading index here); the path half is not.
@@ -42,6 +42,7 @@
 
 import { readFileSync, readdirSync, statSync } from 'node:fs';
 import { join, dirname, resolve, relative, sep } from 'node:path';
+import { isMainModule } from '../is-main-module.mjs';
 
 /**
  * Surfaces whose markdown is instruction, i.e. read and acted on.
@@ -52,8 +53,28 @@ import { join, dirname, resolve, relative, sep } from 'node:path';
  * `-/issues/N` renderer links now carved out by `SKIP_TARGET`, two of them genuinely dangling
  * links to PRDs that had been archived to the private Meta-Vault. Both classes were resolved
  * before the widening, so the widening itself lands at 0 findings.
+ *
+ * `.cursor/rules` joined in the 3ebf0e9d fix-pass, with its yield stated honestly: that surface
+ * ships in the npm tarball and is symlinked into consumer repos by `scripts/cursor-install.mjs`,
+ * and it carried two citations of `commands/{go,close}.md` after those files were folded into
+ * their skills. Measured 2026-09-17: `.cursor/rules/*.mdc` contain ZERO `[text](target)` links
+ * (`grep -rnoE '\[[^]]*\]\([^)]+\)' .cursor/rules/` → no matches), so the widening adds 9 files
+ * and 0 checked links today and would NOT by itself have caught that defect — those citations are
+ * INLINE-CODE (`` `commands/go.md` ``), which this checker deliberately skips (see DELIBERATE
+ * NON-CHECKS). It is a forward guard for the day a real link is authored there, not the catcher
+ * for the backticked-citation class; that class has no gate in this repo (recorded, not assumed).
+ */
+export const SCAN_DIRS = Object.freeze(['skills', 'commands', 'agents', '.claude/rules', 'docs', '.cursor/rules']);
+
+/**
+ * File extensions this checker treats as instruction markdown.
+ *
+ * `.mdc` is Cursor's own rule extension and is the ONLY reason `.cursor/rules`
+ * is scannable at all: every file there is `<nnn>-<name>.mdc`, so a `.md`-only
+ * filter would have added the directory to {@link SCAN_DIRS} and enumerated
+ * zero files — a widening that looks live and checks nothing.
  */
-export const SCAN_DIRS = Object.freeze(['skills', 'commands', 'agents', '.claude/rules', 'docs']);
+export const MD_EXTENSIONS = Object.freeze(['.md', '.mdc']);
 
 /** Path segments that end the walk: vendored or machine-owned trees, never instruction. */
 export const PRUNE_DIRS = new Set(['node_modules', '.git', 'coverage', 'dist', '.pnpm']);
@@ -108,8 +129,8 @@ function fencedLineNumbers(text) {
  * and the check would report clean on the tree that carries the defect. This repo has the incident
  * on record (`.claude/rules/measurement-discipline.md` § "A `git grep` drift sweep cannot see
  * untracked files": a release sweep passed, then failed after the commit, from the same working
- * tree with no edit in between). The cost of the filesystem walk is that a gitignored `.md` under
- * these four directories would also be checked — there are none, and one would be a finding worth
+ * tree with no edit in between). The cost of the filesystem walk is that a gitignored markdown file
+ * under these directories would also be checked — there are none, and one would be a finding worth
  * seeing anyway.
  *
  * @param {string} repoRoot
@@ -125,7 +146,7 @@ export function listMarkdown(repoRoot, { dirs = SCAN_DIRS } = {}) {
     let entries;
     try { entries = readdirSync(abs, { recursive: true, withFileTypes: true }); } catch { continue; }
     for (const e of entries) {
-      if (!e.isFile() || !e.name.endsWith('.md')) continue;
+      if (!e.isFile() || !MD_EXTENSIONS.some((ext) => e.name.endsWith(ext))) continue;
       // parentPath is absolute; make the record repo-relative with POSIX separators.
       const rel = relative(repoRoot, join(e.parentPath ?? abs, e.name));
       const posix = sep === '/' ? rel : rel.split(sep).join('/');
@@ -190,4 +211,4 @@ function main() {
   process.stdout.write(`  PASS: ${checked} relative link(s) in ${files} markdown file(s) resolve\n`);
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) main();
+if (isMainModule(import.meta.url)) main();

package/scripts/lib/validate/check-skill-script-paths.mjs

@@ -100,9 +100,9 @@
 
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
 import { enumerateRepoFiles } from './enumerate-repo-files.mjs';
 import { forEachLine } from './markdown-fences.mjs';
+import { isMainModule } from '../is-main-module.mjs';
 
 /** Documentation roots whose prose is treated as a claim about the repo. */
 export const SCAN_DIRS = Object.freeze(['skills', 'commands', 'agents', 'docs']);
@@ -461,7 +461,7 @@ export function runCheckSkillScriptPaths(pluginRoot, { strictSh = false } = {})
   return inspection.ok ? 0 : 1;
 }
 
-const isMain = import.meta.url === pathToFileURL(process.argv[1] || '').href;
+const isMain =isMainModule(import.meta.url);
 if (isMain) {
   const strictSh = process.argv.includes('--strict-sh');
   const args = process.argv.slice(2).filter((arg) => arg !== '--json' && arg !== '--strict-sh');

package/scripts/lib/validate/check-test-git-config-target.mjs

@@ -110,7 +110,7 @@
 
 import { readFileSync, readdirSync, statSync } from 'node:fs';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { isMainModule } from '../is-main-module.mjs';
 
 /** Only this directory is scanned — a mutation in `scripts/` is production intent. */
 const SCAN_DIR = 'tests';
@@ -810,7 +810,7 @@ export function runCheckTestGitConfigTarget(pluginRoot) {
   return 0;
 }
 
-const isMain = import.meta.url === pathToFileURL(process.argv[1] || '').href;
+const isMain =isMainModule(import.meta.url);
 if (isMain) {
   const argv = process.argv.slice(2);
   const flags = new Set(argv.filter((a) => a.startsWith('--')));

package/scripts/lib/validate/check-unicode-safety.mjs

@@ -35,7 +35,7 @@
 import { readFileSync, readdirSync, statSync, existsSync, writeFileSync } from 'node:fs';
 import { join, extname, relative, sep } from 'node:path';
 import { execFileSync } from 'node:child_process';
-import { pathToFileURL } from 'node:url';
+import { isMainModule } from '../is-main-module.mjs';
 
 // ---------------------------------------------------------------------------
 // File enumeration — git ls-files primary, recursive fs walk fallback.
@@ -535,7 +535,7 @@ export function runCheckUnicodeSafety(pluginRoot, opts = {}) {
 
 // CLI entry — only when executed directly, never on import (keeps the exports
 // safe to import from tests without triggering process.exit).
-const isMain = import.meta.url === pathToFileURL(process.argv[1] || '').href;
+const isMain =isMainModule(import.meta.url);
 if (isMain) {
   const args = process.argv.slice(2);
   const flags = new Set(args.filter((a) => a.startsWith('--')));

package/scripts/lib/validate/check-untracked-test-deps.mjs

@@ -104,10 +104,10 @@
 // Import-safety: importing this module MUST NOT execute anything — the isMain
 // guard at the bottom is the only side-effecting path.
 
-import { pathToFileURL } from 'node:url';
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
+import { isMainModule } from '../is-main-module.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -938,7 +938,7 @@ export function runCheckUntrackedTestDeps(repoRoot) {
   return findings.length > 0 ? 1 : 0;
 }
 
-const isMain = import.meta.url === pathToFileURL(process.argv[1] || '').href;
+const isMain =isMainModule(import.meta.url);
 if (isMain) {
   const root = process.argv[2];
   if (!root) {