session-orchestrator 5.1.0 → 5.3.0

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

@@ -104,10 +104,17 @@
 // 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';
+import { maskSource } from '../js-mask.mjs';
+
+// `maskSource` moved to `scripts/lib/js-mask.mjs` (#1388 — three other modules
+// needed the same lexer). `package.json` carries no `exports` map, so every
+// `scripts/lib/**` path is public API: this re-export keeps the OLD import path
+// working for any consumer that already reaches in here.
+export { maskSource } from '../js-mask.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -167,108 +174,6 @@ const NON_CALLEES = new Set([
   'await', 'new', 'do', 'else', 'in', 'of', 'delete', 'void', 'yield', 'import',
 ]);
 
-// ---------------------------------------------------------------------------
-// Source masking — string/template/comment/regex interiors become spaces
-// ---------------------------------------------------------------------------
-
-/**
- * Blank out the INTERIOR of every string literal, template literal, comment and
- * regex literal, preserving byte offsets and newlines. Delimiters are kept so
- * paren/comma balance and identifier boundaries survive.
- *
- * This is what separates CODE from DATA. A test that embeds fixture source in a
- * template literal (this check's own test file does) must not be scanned as
- * though that fixture were its own body — masking makes that structural instead
- * of relying on a self-exemption marker.
- *
- * @param {string} text
- * @returns {string} same-length masked source
- */
-export function maskSource(text) {
-  const out = text.split('');
-  const n = out.length;
-  let i = 0;
-  // Last significant (non-space) char before `i`, used for the regex/division
-  // disambiguation below.
-  let prev = '';
-
-  const blank = (from, to) => {
-    for (let k = from; k < to && k < n; k++) if (out[k] !== '\n') out[k] = ' ';
-  };
-
-  while (i < n) {
-    const c = text[i];
-    const next = text[i + 1];
-
-    // Line comment.
-    if (c === '/' && next === '/') {
-      let j = i;
-      while (j < n && text[j] !== '\n') j++;
-      blank(i, j);
-      i = j;
-      continue;
-    }
-    // Block comment.
-    if (c === '/' && next === '*') {
-      let j = i + 2;
-      while (j < n && !(text[j] === '*' && text[j + 1] === '/')) j++;
-      blank(i, Math.min(j + 2, n));
-      i = Math.min(j + 2, n);
-      continue;
-    }
-    // Single/double-quoted string — keep the quotes, blank the interior.
-    if (c === "'" || c === '"') {
-      let j = i + 1;
-      while (j < n && text[j] !== c) {
-        if (text[j] === '\\') j++;
-        if (text[j] === '\n') break; // unterminated — bail at EOL
-        j++;
-      }
-      blank(i + 1, j);
-      i = Math.min(j + 1, n);
-      prev = c;
-      continue;
-    }
-    // Template literal — blank everything including `${…}` substitutions.
-    if (c === '`') {
-      let j = i + 1;
-      while (j < n && text[j] !== '`') {
-        if (text[j] === '\\') j++;
-        j++;
-      }
-      blank(i + 1, j);
-      i = Math.min(j + 1, n);
-      prev = c;
-      continue;
-    }
-    // Regex literal — only when the previous significant char cannot end an
-    // expression, AND a closing unescaped `/` exists on the SAME line. The
-    // same-line bound keeps a misread division from swallowing the file.
-    if (c === '/' && (prev === '' || '(,=:[!&|?{};+-*%~^<>'.includes(prev))) {
-      let j = i + 1;
-      let inClass = false;
-      let closed = -1;
-      while (j < n && text[j] !== '\n') {
-        if (text[j] === '\\') { j += 2; continue; }
-        if (text[j] === '[') inClass = true;
-        else if (text[j] === ']') inClass = false;
-        else if (text[j] === '/' && !inClass) { closed = j; break; }
-        j++;
-      }
-      if (closed > i) {
-        blank(i + 1, closed);
-        i = closed + 1;
-        prev = '/';
-        continue;
-      }
-    }
-
-    if (!/\s/.test(c)) prev = c;
-    i++;
-  }
-  return out.join('');
-}
-
 // ---------------------------------------------------------------------------
 // Tiny source scanners (offset-aligned against the masked text)
 // ---------------------------------------------------------------------------
@@ -938,7 +843,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) {

package/scripts/lib/validate/check-unwired-features.mjs

@@ -53,6 +53,30 @@
  * a rule that only cites live instances loses its explanation the moment it works.
  * If you need a CURRENT S2 hit, run the checker; do not assume this one.
  *
+ *   S6 `parser-only-config-key`  — the key IS read, but the ONLY file that
+ *                                   reads it is its own block parser
+ *                                   `scripts/lib/config/<root>.mjs`.
+ *
+ * S6 is the mirror image of S2, and it exists because S1 counts the PARSER as a
+ * consumer: `CONSUMER_DIRS` is `scripts/` + `hooks/`, and every block parser
+ * lives under `scripts/lib/config/`. A key its parser resolves and nothing else
+ * reads is `compact-nudge` wearing a value object. Measured 2026-09-22 on this
+ * tree: `reaper.max-hook-latency-ms` and `reaper.false-alarm-window` both passed
+ * S1 on `scripts/lib/config/reaper.mjs` alone while `scripts/lib/orphan-reaper.mjs`
+ * used same-named HARDCODED defaults and never saw the parsed value.
+ *
+ * Why the signal is this narrow — one read file, and it is the key's OWN parser.
+ * The blunt rule ("the parser layer never counts") was measured first and
+ * REJECTED: it flips 102 of 263 declared keys to unwired, because the ordinary
+ * shape here is a consumer that reads the camelCase FIELD (`cfg.driftCheck.mode`)
+ * while this census matches the kebab TOKEN. 102 of 263 is the broken instrument
+ * `.claude/rules/host-resources.md` HR-101 forbids. The narrow rule reports 32 —
+ * a backlog, printed as an aggregate like S4 and enumerated under `--list`.
+ *
+ * S6 carries no camelCase fallback ON PURPOSE: adding one re-hides both reaper
+ * keys, whose camelCase names exist in `orphan-reaper.mjs` as that module's own
+ * defaults. A name is not a read.
+ *
  * S2 applies to TOP-LEVEL keys only — a nested key reaches code through its
  * parent — and its premise is structural: every Session Config key has to pass
  * through the parser layer to become a value. Measured 2026-08-08: 84 of 89
@@ -265,9 +289,9 @@
 
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
 
 import { sizingSubject } from '../learnings/sizing-subject.mjs';
+import { isMainModule } from '../is-main-module.mjs';
 
 /** Documented config surface — every `yaml` fence in this file is a declaration. */
 const TEMPLATE_REL = 'docs/session-config-template.md';
@@ -393,6 +417,29 @@ const PARSER_PATHS = Object.freeze([
   path.join('scripts', 'parse-config.mjs'),
 ]);
 
+/**
+ * The per-block parser directory: `scripts/lib/config/<block>.mjs` turns ONE
+ * Session Config block's YAML into a value object and does nothing else.
+ *
+ * Signal S6 below is about this directory specifically, which is why it is not
+ * folded into {@link PARSER_PATHS}.
+ */
+const BLOCK_PARSER_DIR = path.join('scripts', 'lib', 'config');
+
+/**
+ * The key's OWN block parser, by convention `scripts/lib/config/<root>.mjs`.
+ *
+ * Deliberately an exact name match and not "anything under the parser dir": a
+ * sibling block's parser reading the key is still a second file, and S6 only
+ * fires when there is exactly ONE reader and it is the key's own.
+ *
+ * @param {string} root top-level key of the block
+ * @returns {string} plugin-root-relative path
+ */
+function ownBlockParserPath(root) {
+  return path.join(BLOCK_PARSER_DIR, `${root}.mjs`);
+}
+
 /**
  * Declared-but-unread keys accepted on purpose. Key = full dotted path (S1/S2)
  * or module path relative to the plugin root (S4), value = REASON naming the
@@ -420,7 +467,8 @@ const ALLOWLIST = Object.freeze({
 
 /**
  * @typedef {{
- *   kind: 'unwired-config-key' | 'parser-orphan-config-key' | 'allowlist-missing-reason'
+ *   kind: 'unwired-config-key' | 'parser-orphan-config-key' | 'parser-only-config-key'
+ *       | 'allowlist-missing-reason'
  *       | 'allowlist-stale' | 'orphaned-prose-module' | 'unreachable-library-module'
  *       | 'coordinator-invoked-module' | 'hand-keyed-learning-subject'
  *       | 'tool-error',
@@ -652,19 +700,57 @@ export function collectExportedSymbols(body) {
   return [...names];
 }
 
+/**
+ * Re-export targets of a barrel: the specifiers of its `export * from '…'`
+ * (and `export * as ns from '…'`) lines.
+ *
+ * `collectExportedSymbols` cannot see these — a star re-export names no symbol —
+ * so a PURE barrel reads as `exports: []`. That does not merely hide the barrel:
+ * the S4 population predicate below requires at least one export, so the barrel
+ * never enters `unreachable` at all, and is therefore unavailable as the CLUSTER
+ * ROOT of the module it re-exports. The target is then reported as its own root.
+ *
+ * Measured 2026-09-16 on the live tree: `scripts/lib/worktree.mjs` is exactly
+ * `export * from './worktree/index.mjs';`, its only importers (`workspace.mjs`,
+ * `worktree-freshness.mjs`) are themselves unreachable — yet S4 reported
+ * `scripts/lib/worktree/index.mjs`, an interior file, instead of the cluster.
+ *
+ * Only the POPULATION is affected. Edge propagation already works: the BFS walks
+ * `mentions`, and a star re-export line is not a comment, so a barrel that IS
+ * reachable already marks its target reachable (measured the same day:
+ * `worktree.mjs` carries `index.mjs` in `mentions`).
+ *
+ * Anchored at column 0 like the export-symbol grammar above, so a docblock line
+ * (`* export * from …`) and an indented string never count.
+ *
+ * @param {string} body module source
+ * @returns {string[]} re-exported module specifiers, as written
+ */
+export function collectReExportTargets(body) {
+  return [
+    ...body.matchAll(/^export\s+\*(?:\s+as\s+[A-Za-z0-9_$]+)?\s+from\s+['"]([^'"]+)['"]/gm),
+  ].map((match) => match[1]);
+}
+
 /**
  * Whether a module is a CLI entrypoint rather than a library.
  *
  * An entrypoint is invoked by path (npm script, hook wiring, CI job), so having
  * no importer is its normal state and says nothing about being wired.
  *
+ * `isMainModule(` is part of the grammar because the #1371 sweep replaced ~50
+ * hand-written `process.argv[1] === import.meta.url` guards with the shared
+ * `scripts/lib/is-main-module.mjs` predicate. Without this alternative a swept
+ * CLI matches none of the other branches and silently reclassifies as a library
+ * candidate, so S4 reports it as an `unreachable-library-module` root.
+ *
  * @param {string} body module source
  * @returns {boolean}
  */
 export function isCliEntrypoint(body) {
   return (
     body.startsWith('#!') ||
-    /import\.meta\.url\s*===|require\.main\s*===\s*module|process\.argv\[1\]/.test(body)
+    /import\.meta\.url\s*===|require\.main\s*===\s*module|process\.argv\[1\]|isMainModule\(/.test(body)
   );
 }
 
@@ -845,7 +931,9 @@ function mentionedModuleTokens(lines) {
  *    switched off. Revisit if a real module-resolver (import-specifier resolution
  *    relative to the importing file) becomes cheap, or if a collided basename is
  *    ever confirmed to mask a true positive. The `coordinator-invoked-module`
- *    DOWNGRADE is exempt, and since #1293 so is the CLUSTER-ROOT filter: in both
+ *    DOWNGRADE is exempt, and since #1293 so is the CLUSTER-ROOT filter (since
+ *    #1298 its predicate also drives the "drags N" count, which had collapsed
+ *    two dragged `index.mjs` into one): in both
  *    a colliding basename must be named with its `dirname/base` suffix, because
  *    those matches move a module OUT of the reportable class and would otherwise
  *    hide a true unreachable sibling. Measured cost of leaving the root filter
@@ -890,6 +978,10 @@ export function collectUnreachableLibraryModules(pluginRoot) {
       edgeOnly,
       entrypoint: isCliEntrypoint(body),
       exports: collectExportedSymbols(body),
+      // Star re-exports name no symbol, so `exports` is empty for a pure
+      // barrel — see collectReExportTargets for why that silently promoted an
+      // interior module to a root.
+      reExports: collectReExportTargets(body),
       // This file contributes NO edges — the S4 counterpart of the SELF_REL
       // exclusion the S1/S2 corpus already applies, and for the identical
       // reason. Every S4 `ALLOWLIST` key is a module path written here as a
@@ -947,8 +1039,15 @@ export function collectUnreachableLibraryModules(pluginRoot) {
     }
   }
 
+  // A module with NO public surface at all is not a finding — nothing can be
+  // wired to it. A pure `export * from` barrel HAS a surface (everything its
+  // target exports), so it belongs in the population: otherwise it cannot be
+  // the cluster root of the module it re-exports (collectReExportTargets).
   const unreachable = modules.filter(
-    (module) => !reachable.has(module.relative) && !module.entrypoint && module.exports.length > 0,
+    (module) =>
+      !reachable.has(module.relative) &&
+      !module.entrypoint &&
+      (module.exports.length > 0 || module.reExports.length > 0),
   );
   const unreachableSet = new Set(unreachable.map((module) => module.relative));
   // Basename census, shared by the root filter below and the downgrade half
@@ -965,23 +1064,69 @@ export function collectUnreachableLibraryModules(pluginRoot) {
   const basenameCount = new Map();
   for (const module of modules) basenameCount.set(module.base, (basenameCount.get(module.base) ?? 0) + 1);
 
-  const roots = unreachable.filter((module) => {
-    // A bare-basename mention only suppresses when the basename is UNIQUE
-    // (see the census above). When it collides, the mentioning module must name
-    // the `dirname/base` form in its body — otherwise ONE unreachable module
-    // mentioning bare `index.mjs` masks EVERY differently-pathed `index.mjs`
-    // root at once (#1293: `locks/index.mjs` + `worktree/index.mjs` were masked
-    // by a third unreachable module until that module was deleted for an
-    // unrelated reason).
-    const ambiguous = (basenameCount.get(module.base) ?? 0) > 1;
-    const qualified = module.relative.split(path.sep).slice(-2).join('/');
-    const qualifiedRe = ambiguous ? tokenMatcher(qualified) : null;
-    return !unreachable.some(
-      (other) =>
-        other.relative !== module.relative &&
-        other.mentions.has(module.base) &&
-        (qualifiedRe === null || qualifiedRe.test(other.rawBody)),
-    );
+  // One `dirname/base` matcher per unreachable module whose basename collides,
+  // built once: `references` below runs per (mentioner, target) pair.
+  /** @type {Map<string, RegExp>} */
+  const qualifiedMatchers = new Map();
+  for (const module of unreachable) {
+    if ((basenameCount.get(module.base) ?? 0) < 2) continue;
+    qualifiedMatchers.set(module.relative, tokenMatcher(module.relative.split(path.sep).slice(-2).join('/')));
+  }
+  /**
+   * Does `mentioner` reference the unreachable module `target`? A bare-basename
+   * mention only counts when the basename is UNIQUE (see the census above).
+   * When it collides, the mentioning module must name the `dirname/base` form
+   * in its body — otherwise ONE unreachable module mentioning bare `index.mjs`
+   * references EVERY differently-pathed `index.mjs` at once (#1293:
+   * `locks/index.mjs` + `worktree/index.mjs` were masked as roots by a third
+   * unreachable module until that module was deleted for an unrelated reason).
+   *
+   * The ONE predicate for both consumers — the cluster-root filter and the drag
+   * count of the finding message — so the two cannot disagree about who
+   * references whom. They did (#1298): the drag count compared bare basenames,
+   * so a root importing `a/index.mjs` AND `b/index.mjs` read "drags 1".
+   *
+   * @param {(typeof modules)[number]} mentioner
+   * @param {(typeof modules)[number]} target an `unreachable` module
+   * @returns {boolean}
+   */
+  const references = (mentioner, target) => {
+    if (!mentioner.mentions.has(target.base)) return false;
+    const qualifiedRe = qualifiedMatchers.get(target.relative);
+    return qualifiedRe === undefined || qualifiedRe.test(mentioner.rawBody);
+  };
+
+  const roots = unreachable.filter(
+    (module) => !unreachable.some((other) => other.relative !== module.relative && references(other, module)),
+  );
+
+  // A pure `export *` barrel enters the population above so it can HEAD its own
+  // cluster, but reporting it needs one more condition. S3 already exempts this
+  // exact shape by name (`autopilot-telemetry.mjs`, condition 4): a star
+  // re-export has zero NAMED symbols, so every "does prose name one of its
+  // exports?" test is vacuously FALSE — including S4's own coordinator-invoked
+  // downgrade below, which iterates `module.exports`. A reported pure barrel
+  // could therefore never be downgraded, only allowlisted: a finding with no
+  // legitimate exit. The category split is the barrel's TARGET. A barrel over a
+  // module that is itself unreachable heads a genuinely dead cluster and is
+  // reported; a barrel over LIVE code is a backward-compat shim, which is a
+  // different (and much weaker) finding than "nothing can reach this feature".
+  // Measured 2026-09-16: without this split `scripts/lib/autopilot-telemetry.mjs`
+  // — `export * from './autopilot/telemetry.mjs'`, target reachable, sole
+  // importer a test — became a new permanent WARN.
+  // Ceiling: a dead shim over live code is now invisible to S4 as well as to S3.
+  // Revisit if a stale back-compat shim is ever confirmed to have outlived its
+  // last importer unnoticed — that wants its own check, not a looser S4.
+  const reportableRoots = roots.filter((module) => {
+    if (module.exports.length > 0) return true;
+    return module.reExports.some((spec) => {
+      if (!spec.startsWith('.')) {
+        // Aliased/bare specifier: fall back to the basename granularity this
+        // file already documents as its named residual.
+        return [...unreachableSet].some((rel) => path.basename(rel) === path.basename(spec));
+      }
+      return unreachableSet.has(path.normalize(path.join(path.dirname(module.relative), spec)));
+    });
   });
 
   // Category split (see § Category split in the doc block above): an INSTRUCTION
@@ -997,7 +1142,7 @@ export function collectUnreachableLibraryModules(pluginRoot) {
     .map((file) => ({ relative: path.relative(pluginRoot, file), body: readFileSync(file, 'utf8') }));
 
   let coordinatorInvoked = 0;
-  const findings = roots.map((module) => {
+  const findings = reportableRoots.map((module) => {
     // Docs write POSIX separators regardless of host; `path.relative` does not.
     const relativePosix = module.relative.split(path.sep).join('/');
     const qualified = relativePosix.split('/').slice(-2).join('/');
@@ -1028,15 +1173,22 @@ export function collectUnreachableLibraryModules(pluginRoot) {
           'architecture. Re-check only if that instruction is ever removed',
       });
     }
-    const dragged = [...module.mentions].filter(
-      (token) => token !== module.base && [...unreachableSet].some((rel) => path.basename(rel) === token),
-    );
+    // Counted per MODULE through the root filter's own predicate, never per
+    // basename token: `mentions` is a Set of basenames, so two dragged
+    // `index.mjs` files would collapse into one (#1298).
+    const dragged = unreachable.filter((other) => other.relative !== module.relative && references(module, other));
     const tail = dragged.length > 0 ? `, and drags ${dragged.length} further unreachable module(s)` : '';
+    // A pure barrel reports its re-export surface; naming "0 symbol(s)" there
+    // would read as a checker bug rather than as the barrel it is.
+    const surface =
+      module.exports.length > 0
+        ? `exports ${module.exports.length} symbol(s) (${module.exports.slice(0, 3).join(', ')})`
+        : `re-exports ${module.reExports.length} module(s) (${module.reExports.slice(0, 3).join(', ')})`;
     return /** @type {Finding} */ ({
       kind: 'unreachable-library-module',
       key: module.relative,
       message:
-        `exports ${module.exports.length} symbol(s) (${module.exports.slice(0, 3).join(', ')}) but no hook, ` +
+        `${surface} but no hook, ` +
         `npm script, CI job or husky stage reaches it — transitively${tail}. No instruction surface names ` +
         'one of its exports either: wire it, delete it, or allowlist it with a reason',
     });
@@ -1046,7 +1198,7 @@ export function collectUnreachableLibraryModules(pluginRoot) {
     findings,
     scanned: {
       modules: modules.length,
-      roots: roots.length,
+      roots: reportableRoots.length,
       unreachable: unreachable.length,
       coordinatorInvoked,
     },
@@ -1175,6 +1327,7 @@ export function inspectUnwiredFeatures(pluginRoot) {
       orphanedModules: 0,
       unreachableModules: 0,
       coordinatorInvokedModules: 0,
+      parserOnly: 0,
       handKeyedSubjects: 0,
       judgedSubjects: 0,
     },
@@ -1234,7 +1387,7 @@ export function inspectUnwiredFeatures(pluginRoot) {
 
   for (const key of [...declared.keys.keys()].sort()) {
     const meta = /** @type {DeclaredKey} */ (declared.keys.get(key));
-    const { code, comment } = countReadSites(meta, corpus);
+    const { code, comment, files: readFiles } = countReadSites(meta, corpus);
 
     /** @type {Finding | null} */
     let issue = null;
@@ -1247,6 +1400,21 @@ export function inspectUnwiredFeatures(pluginRoot) {
           `declared in ${meta.sources.join(' + ')} but no .mjs under ${CONSUMER_DIRS.join('/ or ')}/ ` +
           `reads it${commentNote} — wire it, delete it, or allowlist it with a reason`,
       };
+    } else if (readFiles.length === 1 && readFiles[0] === ownBlockParserPath(meta.root)) {
+      // S6 — the ONLY file that reads this key is the parser that produced it.
+      // A parser is not a consumer: it turns YAML into a field nobody then
+      // reads, which is `compact-nudge` wearing a value object. Measured
+      // 2026-09-22: `reaper.max-hook-latency-ms` and `reaper.false-alarm-window`
+      // both passed S1 on the strength of `scripts/lib/config/reaper.mjs`
+      // alone, while `orphan-reaper.mjs` used its OWN hardcoded defaults of the
+      // same name and never received the parsed value.
+      issue = {
+        kind: 'parser-only-config-key',
+        key,
+        message:
+          `read only by its own block parser (${readFiles[0]}) — a parser is not a consumer; ` +
+          'nothing outside the config layer reads the parsed value',
+      };
     } else if (key === meta.root && !tokenMatcher(key).test(parserBody)) {
       issue = {
         kind: 'parser-orphan-config-key',
@@ -1272,7 +1440,8 @@ export function inspectUnwiredFeatures(pluginRoot) {
       continue;
     }
 
-    result.summary.unwired += 1;
+    if (issue.kind === 'parser-only-config-key') result.summary.parserOnly += 1;
+    else result.summary.unwired += 1;
     findings.push(issue);
   }
 
@@ -1342,6 +1511,7 @@ export function runCheckUnwiredFeatures(pluginRoot, { list = false } = {}) {
     consumerFiles,
     unwired,
     allowlisted,
+    parserOnly,
     orphanedModules,
     unreachableModules,
     coordinatorInvokedModules,
@@ -1361,8 +1531,16 @@ export function runCheckUnwiredFeatures(pluginRoot, { list = false } = {}) {
   // architecture — an instruction surface tells an LLM to call the module.
   // Measured 2026-09-07: 46 of the 52 findings the single S4 class carried.
   // Printing 46 WARN lines for the design is the broken instrument HR-101 forbids.
-  const DEFERRED = Object.freeze(['unreachable-library-module', 'coordinator-invoked-module']);
+  //
+  // `parser-only-config-key` (S6) is deferred on the S4 terms too: 32 findings
+  // on the live tree is a backlog to work down, not a per-run alarm.
+  const DEFERRED = Object.freeze([
+    'unreachable-library-module',
+    'coordinator-invoked-module',
+    'parser-only-config-key',
+  ]);
   const s4 = inspection.findings.filter((item) => item.kind === 'unreachable-library-module');
+  const s6 = inspection.findings.filter((item) => item.kind === 'parser-only-config-key');
   for (const item of inspection.findings) {
     if (!list && DEFERRED.includes(item.kind)) continue;
     console.log(`  WARN: [${item.kind}] ${item.key} — ${item.message}`);
@@ -1381,10 +1559,19 @@ export function runCheckUnwiredFeatures(pluginRoot, { list = false } = {}) {
     );
   }
 
+  if (!list && s6.length > 0) {
+    console.log(
+      `  WARN: [parser-only-config-key] ${s6.length} declared key(s) whose only reader is their own ` +
+        `block parser — e.g. ${s6.slice(0, 3).map((item) => item.key).join(', ')}. ` +
+        'Re-run with --list for the full census.',
+    );
+  }
+
   console.log(
     `  PASS: censused ${declaredKeys} declared key(s) from ${inspection.sourcesScanned.join(' + ') || '(no source)'} ` +
       `against ${consumerFiles} consumer file(s) — ${unwired} unwired, ${allowlisted} allowlisted, ` +
-      `${orphanedModules} prose-orphaned module(s), ${unreachableModules} unreachable module(s), ` +
+      `${parserOnly} parser-only, ${orphanedModules} prose-orphaned module(s), ` +
+      `${unreachableModules} unreachable module(s), ` +
       `${coordinatorInvokedModules} coordinator-invoked module(s), ${handKeyedSubjects} hand-keyed ` +
       `learning subject(s) of ${judgedSubjects} judged`,
   );
@@ -1393,7 +1580,7 @@ export function runCheckUnwiredFeatures(pluginRoot, { list = false } = {}) {
   return 0;
 }
 
-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 pluginRoot = args.find((arg) => !arg.startsWith('-'));

package/scripts/lib/validate/check-validator-registration.mjs

@@ -51,15 +51,21 @@
  * skill body) and nowhere in the three RUN surfaces above still reports
  * UNREGISTERED — being documented is not being run. REVISIT if a fourth run
  * surface (a new CI job file, a different git hook) is ever added: extend
- * `RUN_SURFACES`, do not special-case it here. The comment stripper's own
- * quote-tracking is a single flat state — an escaped quote (`\"`) inside a
- * double-quoted string is not honoured, and a template-literal's `${...}`
- * interpolation is not walked separately. Both failure directions lean
- * toward treating MORE text as "inside a string" than a real parser would,
- * which can only make the stripper MISS a comment (false "still
- * registered"), never manufacture a false UNREGISTERED — the direction this
- * checker's own false-positive history (the paragraph above) already
- * measured as the live hazard.
+ * `RUN_SURFACES`, do not special-case it here.
+ *
+ * THE "NEVER A FALSE UNREGISTERED" CLAIM WAS FALSE (#1388, measured
+ * 2026-09-18 @ 20a4cbff). This header used to argue that the hand-rolled
+ * stripper could only ever MISS a comment, never manufacture a false
+ * UNREGISTERED. It had no regex-literal branch, so
+ * `const re = /\/*$/;` in `scripts/validate-plugin.mjs` opened a BLOCK
+ * COMMENT at the regex's `/*` and swallowed every `runCheck(...)` line below
+ * it — precisely a false UNREGISTERED, for every checker registered after
+ * that point. The `.mjs` surface is therefore lexed by the shared
+ * `maskSource` (`scripts/lib/js-mask.mjs`), which recognises regex literals;
+ * only the `#`-comment shell/YAML surfaces (`.husky/pre-commit`,
+ * `.gitlab-ci.yml`) still use the small local walker, whose flat
+ * quote-tracking ceiling (no `\"` escape handling, no `${...}` walk) is
+ * real but bounded to those two files.
  *
  * Usage: check-validator-registration.mjs <repo-root>
  * Output: `  PASS: …` / `  FAIL: …` lines (two leading spaces), then
@@ -72,8 +78,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 { isMainModule } from '../is-main-module.mjs';
+import { maskSource } from '../js-mask.mjs';
 
 /** Marker line inside a checker's own header — declares deliberate CLI-only status. */
 export const STANDALONE_MARKER = /^\s*\/\/\s*registration:\s*standalone\b(?:\s+(.*))?$/m;
@@ -113,11 +120,28 @@ function commentStyleForSurface(rel) {
  * truncating the line early. See the header NAMED CEILING for what this
  * quote-tracking deliberately does not attempt.
  *
+ * The JS style (`//` + `/* *\/`) is delegated to the shared lexer
+ * {@link maskSource} in `keepLiterals` mode — it is the only one of the three
+ * RUN_SURFACES that can contain a REGEX LITERAL, and a stripper without a
+ * regex branch reads `/\/*$/` as a block-comment opener and swallows every
+ * registration below it (#1388, see the header). `maskSource` blanks comment
+ * bytes to SPACES rather than deleting them, which is strictly safer for the
+ * substring match below: deletion could splice two fragments into a basename
+ * that was never written. The `#` style stays local — `maskSource` models
+ * JavaScript, not sh/YAML.
+ *
  * @param {string} text
  * @param {{lineComment: string, blockComment: boolean, quoteChars: string[]}} style
- * @returns {string}
+ * @returns {string} TWO comment models behind one signature, and they differ in
+ * shape: the JS style (`//` + `/* *\/`, delegated to {@link maskSource})
+ * returns a string of the SAME LENGTH as `text`, with comment bytes blanked to
+ * spaces; the `#` style (sh/YAML, the local walker) returns a SHORTER string,
+ * with the comment text deleted to end-of-line (the newline itself is kept).
+ * Only the substring match below is common to both — do not rely on offsets
+ * surviving the `#` style.
  */
 export function stripComments(text, { lineComment, blockComment, quoteChars }) {
+  if (lineComment === '//' && blockComment) return maskSource(text, { keepLiterals: true });
   let out = '';
   let i = 0;
   let inQuote = null;
@@ -243,7 +267,7 @@ export function runCheckValidatorRegistration(repoRoot) {
   return fail > 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-vcs-repo-flag.mjs

@@ -193,8 +193,8 @@
 
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
 import { SHELL_LANGS, forEachLine } from './markdown-fences.mjs';
+import { isMainModule } from '../is-main-module.mjs';
 
 /** Directories whose content is scanned. Root-level `*.md` is added separately. */
 const SCAN_DIRS = Object.freeze([
@@ -906,7 +906,7 @@ export function runCheckVcsRepoFlag(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('--')));