session-orchestrator 5.0.0 → 5.2.0

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

@@ -166,6 +166,43 @@
  * both classes stay in `findings`, and either half collapsing to zero is itself
  * pinned by a test.
  *
+ * ## S5 `hand-keyed-learning-subject` — the prose-only DERIVATION
+ *
+ * S1-S4 all ask about a module or a key. S5 asks about a VALUE that prose tells
+ * an LLM to derive: `skills/evolve/references/evolve-analyze-mode.md` says the
+ * `effective-sizing` subject must come from `sizingSubject()` and that nobody may
+ * hand-concatenate it. Nothing enforced that. An analyzer run that writes
+ * `${session_type}-session-sizing` by hand — which is what it did before #1247,
+ * and which the helper's own profile-less branch still returns byte-identically —
+ * silently re-merges a 7-wave `ultradeep` session onto the 5-wave `deep` row, and
+ * no test, gate or checker notices.
+ *
+ * S5 therefore imports the helper (which is also what gives it a MECHANICAL
+ * consumer at all) and re-derives the subject of every written `effective-sizing`
+ * learning from the session record it names, reporting any mismatch. The
+ * comparison is the point: the check cannot drift from the helper, because it IS
+ * the helper.
+ *
+ * ### What it judges, and the measured reason it judges no more than that
+ *
+ * Only a subject already in the canonical `<...>-session-sizing` SHAPE is judged.
+ * Measured 2026-09-13 on this repo's live ledger (6 `effective-sizing` learnings):
+ * exactly ONE is canonically keyed (`deep-session-sizing`, and it is correct); the
+ * other five are free-form sentences (`deep session of 10 small follow-up
+ * issues`, `full-gate-workers-under-host-contention`, …). Judging those would put
+ * this class at 83% on day one — the broken instrument
+ * `.claude/rules/host-resources.md` § HR-101 forbids — and it would be judging
+ * prose STYLE, not a keying defect. A free-form subject cannot COLLIDE two
+ * profiles onto one row, which is the whole bug #1247 fixed.
+ *
+ * A learning whose `source_session` resolves to no session record is skipped and
+ * counted, never reported: the ledger is host-local and append-only, so an old
+ * learning routinely outlives the record it names, and reporting that would be a
+ * finding about ledger retention rather than about keying.
+ *
+ * Both ledger files are gitignored host-local telemetry. Absent → S5 is a silent
+ * no-op (CI sees no ledger), never a tool error.
+ *
  * ## Consumer scope, and why "prose-only" is a finding rather than an error
  *
  * Read sites are counted in `scripts/**` and `hooks/**` (`.mjs`/`.js`/`.cjs`),
@@ -228,7 +265,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';
@@ -331,6 +370,17 @@ const WIRING_DIRS = Object.freeze([
   ['hooks', Object.freeze(['.json', '.sh'])],
 ]);
 
+/**
+ * Host-local telemetry the S5 subject-parity check reads. Both are gitignored
+ * (`.gitignore:55` `.orchestrator/metrics/*.jsonl`), so both are routinely
+ * ABSENT — that is a no-op, not an error. See the header, § S5.
+ */
+const LEARNINGS_REL = path.join('.orchestrator', 'metrics', 'learnings.jsonl');
+const SESSIONS_REL = path.join('.orchestrator', 'metrics', 'sessions.jsonl');
+
+/** The canonical `effective-sizing` subject shape `sizingSubject()` produces. */
+const SIZING_SUBJECT_RE = /-session-sizing$/;
+
 /**
  * The config-parser layer: the files a Session Config key must pass through to
  * become a runtime value. Signal S2 (see header) checks top-level keys against
@@ -372,7 +422,7 @@ const ALLOWLIST = Object.freeze({
  * @typedef {{
  *   kind: 'unwired-config-key' | 'parser-orphan-config-key' | 'allowlist-missing-reason'
  *       | 'allowlist-stale' | 'orphaned-prose-module' | 'unreachable-library-module'
- *       | 'coordinator-invoked-module'
+ *       | 'coordinator-invoked-module' | 'hand-keyed-learning-subject'
  *       | 'tool-error',
  *   key: string,
  *   message: string,
@@ -602,19 +652,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)
   );
 }
 
@@ -840,6 +928,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
@@ -848,7 +940,18 @@ export function collectUnreachableLibraryModules(pluginRoot) {
       // `allowlist-stale` — the check silently blinding itself to exactly the
       // module an operator flagged. Measured 2026-08-28 on the first S4
       // allowlist entry: 52 → 51 unreachable modules plus one bogus stale line.
-      mentions: relative === SELF_REL ? new Set() : mentionedModuleTokens(lines),
+      mentions:
+        relative === SELF_REL
+          ? // This file blinds itself to its own ALLOWLIST literals (above) — but
+            // NOT to its own real imports. Dropping every edge here made a module
+            // this file genuinely `import`s (`learnings/sizing-subject.mjs`, the
+            // S5 check) still read as unreachable, which is the identical
+            // self-blinding the exclusion exists to prevent, in the other
+            // direction. Static import/export lines carry real edges; an
+            // ALLOWLIST key is never one, so scoping the scan to them keeps both
+            // properties.
+            mentionedModuleTokens(lines.filter((line) => /^\s*(?:import|export)\b/.test(line)))
+          : mentionedModuleTokens(lines),
       // Raw text, kept for the QUALIFIED (`dirname/base`) re-check in the
       // root filter below: `mentionedModuleTokens` strips the directory, so
       // a colliding basename can only be disambiguated against the body.
@@ -886,8 +989,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
@@ -923,6 +1033,35 @@ export function collectUnreachableLibraryModules(pluginRoot) {
     );
   });
 
+  // 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
   // document that names both the module AND one of its exported symbols is an
   // order addressed to a reader who will execute it — the same grammar
@@ -936,7 +1075,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('/');
@@ -971,11 +1110,17 @@ export function collectUnreachableLibraryModules(pluginRoot) {
       (token) => token !== module.base && [...unreachableSet].some((rel) => path.basename(rel) === token),
     );
     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',
     });
@@ -985,13 +1130,107 @@ export function collectUnreachableLibraryModules(pluginRoot) {
     findings,
     scanned: {
       modules: modules.length,
-      roots: roots.length,
+      roots: reportableRoots.length,
       unreachable: unreachable.length,
       coordinatorInvoked,
     },
   };
 }
 
+/**
+ * Read a JSONL ledger, skipping blank and unparseable lines.
+ *
+ * A single truncated line (an interrupted append) must not blind the whole
+ * check — the same fail-soft posture the rest of this file takes toward a
+ * missing surface.
+ *
+ * @param {string} file absolute path
+ * @returns {Record<string, unknown>[]}
+ */
+function readJsonl(file) {
+  if (!existsSync(file)) return [];
+  /** @type {Record<string, unknown>[]} */
+  const records = [];
+  for (const line of readFileSync(file, 'utf8').split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed === '') continue;
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (parsed && typeof parsed === 'object') records.push(parsed);
+    } catch {
+      // truncated / partial append — skip the line, keep the census
+    }
+  }
+  return records;
+}
+
+/**
+ * Signal S5 — an `effective-sizing` learning whose subject was hand-written
+ * instead of derived from `sizingSubject()`.
+ *
+ * See the header § S5 for the defect, the deliberate narrowness of what is
+ * judged, and the measured reason a free-form subject is not a finding.
+ *
+ * @param {string} pluginRoot absolute plugin root
+ * @returns {{findings: Finding[], scanned: {judged: number, unattributed: number}}}
+ */
+export function collectHandKeyedLearningSubjects(pluginRoot) {
+  /** @type {Finding[]} */
+  const findings = [];
+  let judged = 0;
+  let unattributed = 0;
+
+  const learnings = readJsonl(path.join(pluginRoot, LEARNINGS_REL));
+  if (learnings.length === 0) return { findings, scanned: { judged, unattributed } };
+
+  // A session record can be addressed by either identity form (see
+  // `.claude/rules/identity-and-locks.md`: raw UUID + semantic id), and a
+  // learning's `source_session` carries whichever the writer had. Index both, so
+  // a resolvable record is never mis-counted as unattributed.
+  /** @type {Map<string, Record<string, unknown>>} */
+  const sessionsById = new Map();
+  for (const record of readJsonl(path.join(pluginRoot, SESSIONS_REL))) {
+    for (const field of ['session_id', 'semantic_session_id']) {
+      const id = record[field];
+      if (typeof id === 'string' && id !== '' && !sessionsById.has(id)) sessionsById.set(id, record);
+    }
+  }
+
+  for (const learning of learnings) {
+    if (learning.type !== 'effective-sizing') continue;
+    const subject = learning.subject;
+    if (typeof subject !== 'string' || !SIZING_SUBJECT_RE.test(subject)) continue;
+
+    const sourceSession = typeof learning.source_session === 'string' ? learning.source_session : '';
+    const record = sessionsById.get(sourceSession);
+    if (!record) {
+      unattributed += 1;
+      continue;
+    }
+
+    judged += 1;
+    const expected = sizingSubject({
+      session_type: record.session_type,
+      session_profile: record.session_profile,
+    });
+    if (subject === expected) continue;
+
+    findings.push({
+      kind: 'hand-keyed-learning-subject',
+      key: typeof learning.id === 'string' ? learning.id : subject,
+      message:
+        `effective-sizing learning keyed '${subject}', but sizingSubject() derives '${expected}' from ` +
+        `${sourceSession} (session_type=${String(record.session_type)}, session_profile=` +
+        `${record.session_profile === undefined ? 'absent' : String(record.session_profile)}) — the ` +
+        'subject was hand-concatenated instead of derived via ' +
+        'scripts/lib/learnings/sizing-subject.mjs, so two session shapes can silently share one row ' +
+        '(GitLab #1247); re-key the learning and derive via the helper',
+    });
+  }
+
+  return { findings, scanned: { judged, unattributed } };
+}
+
 /**
  * Run the full census.
  *
@@ -1000,7 +1239,8 @@ export function collectUnreachableLibraryModules(pluginRoot) {
  *   ok: boolean,
  *   summary: {declaredKeys: number, consumerFiles: number, unwired: number, allowlisted: number,
  *             orphanedModules: number, unreachableModules: number,
- *             coordinatorInvokedModules: number},
+ *             coordinatorInvokedModules: number, handKeyedSubjects: number,
+ *             judgedSubjects: number},
  *   sourcesScanned: string[],
  *   findings: Finding[],
  *   toolError: boolean,
@@ -1019,6 +1259,8 @@ export function inspectUnwiredFeatures(pluginRoot) {
       orphanedModules: 0,
       unreachableModules: 0,
       coordinatorInvokedModules: 0,
+      handKeyedSubjects: 0,
+      judgedSubjects: 0,
     },
     /** @type {string[]} */
     sourcesScanned: [],
@@ -1036,6 +1278,8 @@ export function inspectUnwiredFeatures(pluginRoot) {
   let orphans;
   /** @type {ReturnType<typeof collectUnreachableLibraryModules>} */
   let unreachable;
+  /** @type {ReturnType<typeof collectHandKeyedLearningSubjects>} */
+  let handKeyed;
   try {
     declared = collectDeclaredKeys(pluginRoot);
     corpus = CONSUMER_DIRS.flatMap((dir) => walkCode(path.join(pluginRoot, dir)))
@@ -1054,6 +1298,7 @@ export function inspectUnwiredFeatures(pluginRoot) {
       .join('\n');
     orphans = collectOrphanedProseModules(pluginRoot);
     unreachable = collectUnreachableLibraryModules(pluginRoot);
+    handKeyed = collectHandKeyedLearningSubjects(pluginRoot);
   } catch (error) {
     result.toolError = true;
     findings.push({
@@ -1134,6 +1379,13 @@ export function inspectUnwiredFeatures(pluginRoot) {
     findings.push(finding);
   }
 
+  // S5 — a written learning subject that prose said must come from the helper,
+  // and did not. Not allowlistable: the fix is to re-key the record, and an
+  // exemption would preserve exactly the collision #1247 removed.
+  result.summary.handKeyedSubjects = handKeyed.findings.length;
+  result.summary.judgedSubjects = handKeyed.scanned.judged;
+  findings.push(...handKeyed.findings);
+
   for (const key of Object.keys(ALLOWLIST).sort()) {
     if (flagged.has(key)) continue;
     findings.push({
@@ -1177,6 +1429,8 @@ export function runCheckUnwiredFeatures(pluginRoot, { list = false } = {}) {
     orphanedModules,
     unreachableModules,
     coordinatorInvokedModules,
+    handKeyedSubjects,
+    judgedSubjects,
   } = inspection.summary;
 
   // S4 is a BACKLOG, not a per-run alarm: 50 findings on the live tree against
@@ -1215,14 +1469,15 @@ export function runCheckUnwiredFeatures(pluginRoot, { list = false } = {}) {
     `  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), ` +
-      `${coordinatorInvokedModules} coordinator-invoked module(s)`,
+      `${coordinatorInvokedModules} coordinator-invoked module(s), ${handKeyedSubjects} hand-keyed ` +
+      `learning subject(s) of ${judgedSubjects} judged`,
   );
   console.log('');
   console.log('Results: 1 passed, 0 failed');
   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

@@ -72,8 +72,8 @@
 
 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';
 
 /** 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;
@@ -243,7 +243,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('--')));

package/scripts/lib/validate-vendored-rules.mjs

@@ -6,9 +6,12 @@
  * Catches vendoring bugs that are invisible at the source-of-truth layer but
  * become live footguns once synced into a target repo:
  *
- *   - `paths:` frontmatter — `rule-loader.mjs` only understands `globs:`; a
- *     `paths:` key is silently ignored, so the rule loads as always-on
- *     instead of the intended glob-scoped subset.
+ *   - `paths:` frontmatter in a `rules/` LIBRARY SOURCE — a vendoring-
+ *     CONVENTION gate, not a loader-compatibility one. Since #795
+ *     `rule-loader.mjs` accepts `paths:` as an alias for `globs:`, so such a
+ *     rule IS glob-scoped; `globs:` stays the canonical form for a rule
+ *     vendored out through the library (#742). See § Scope below — this probe
+ *     never judges a repo's own consolidated `.claude/rules/` files.
  *   - Missing provenance header — `rules-sync.mjs` detects "plugin-owned vs.
  *     local override" purely by checking whether the first line starts with
  *     `PLUGIN_HEADER_PREFIX`. A source file missing that header gets
@@ -31,6 +34,25 @@
  * module imports the already-exported `parseGlobsFrontmatter` from
  * `rule-loader.mjs` directly.
  *
+ * ## Scope: the `rules/` fleet library, never a repo's own `.claude/rules/`
+ *
+ * Every production caller feeds this module SOURCE files from the plugin's
+ * fleet library: `syncRules()` (`rules-sync.mjs`) validates
+ * `<pluginRoot>/rules/<relPath>` for each entry listed in `rules/_index.md`
+ * BEFORE writing the vendored copy into a consumer's `.claude/rules/` — the
+ * written target is never read back through the gate. The CLI's `--dir` is
+ * operator-supplied and means that same library.
+ *
+ * This is load-bearing for `paths-frontmatter`: a repo's own CONSOLIDATED rules
+ * under `.claude/rules/` are `paths:`-canonical by design, because Claude
+ * Code's native loader reads ONLY `paths:` and treats a rule without it as
+ * always-on (`validate/check-rules.mjs` #1108; `docs/rule-authoring.md`
+ * § Consolidated rules point 3). Measured 2026-09-16 in this repo: 10
+ * path-scoped rule files there, 9 of them `paths:`-only. Pointing `--dir` at
+ * such a tree would emit findings that, if obeyed, UNDO that consolidation —
+ * which is also why `check-rules.mjs` deliberately does not duplicate this
+ * probe for `.claude/rules/`.
+ *
  * @module validate-vendored-rules
  */
 
@@ -40,6 +62,7 @@ import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
 import { createRequire } from 'node:module';
 import { parseGlobsFrontmatter } from './rule-loader.mjs';
+import { isMainModule } from './is-main-module.mjs';
 
 // Mirrors rules-sync.mjs's exported PLUGIN_HEADER_PREFIX (rules-sync.mjs
 // line ~13). NOT imported from there on purpose: rules-sync.mjs imports
@@ -478,10 +501,17 @@ export function validateRuleContent({ content, relPath, targetRoot = null, requi
         // `paths:`-only rule IS glob-scoped. The probe itself stays: it enforces the canonical
         // vendoring form, which is a convention gate, not a loader-compatibility gate. That
         // intent survives #795 and is the subject of the #742 fleet canonicalisation sweep.
+        // SCOPE (2026-09-16): this fires only over `rules/` library sources — the module doc's
+        // § Scope section names every caller. Do NOT re-point it at a repo's own
+        // `.claude/rules/`: those consolidated files are `paths:`-canonical and obeying this
+        // remedy there would undo the consolidation (docs/rule-authoring.md point 3).
         message:
           `${relPath}: frontmatter declares a top-level 'paths:' key. It is a recognized alias ` +
           `for 'globs:' (issue #795), so the rule does load glob-scoped — but 'globs:' is the ` +
-          `canonical form for vendored rules. Migrate to 'globs:' (see issue #742).`,
+          `canonical form for a rule VENDORED OUT through the plugin's rules/ library, which is ` +
+          `this probe's only population. Migrate to 'globs:' (see issue #742). This does NOT ` +
+          `apply to a repo's own consolidated .claude/rules/ files — those are paths:-canonical ` +
+          `(Claude Code's native loader reads only 'paths:') and this gate never scans them.`,
         line: lineWithinFrontmatter(fm.startLine, fm.body, pathsMatch.index),
       });
     }
@@ -652,11 +682,7 @@ export function validateRulesDir({ dir, targetRoot = null, requireProvenance = f
 
 const __filename = fileURLToPath(import.meta.url);
 
-const isMain =
-  typeof process !== 'undefined' &&
-  process.argv[1] !== null &&
-  process.argv[1] !== undefined &&
-  resolve(process.argv[1]) === resolve(__filename);
+const isMain =isMainModule(import.meta.url);
 
 /**
  * @param {{ ok: boolean, files: Array<{ file: string, violations: RuleViolation[] }>, errorCount: number, warnCount: number }} result

package/scripts/lib/wave-transcript-tail.mjs

@@ -55,12 +55,12 @@ import {
 } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, relative, isAbsolute } from 'node:path';
-import { pathToFileURL } from 'node:url';
 
 import { emitEvent, sessionAttribution } from './events.mjs';
 import { tryAcquireFileLock, releaseFileLock } from './file-lock.mjs';
 import { readLock, isLockLive } from './session-lock.mjs';
 import { resolveSubagentSidecar } from '../../hooks/_lib/subagent-paths.mjs';
+import { isMainModule } from './is-main-module.mjs';
 
 const DEFAULT_INTERVAL_S = 2;
 const EVENTS_FILE_REL = '.orchestrator/metrics/events.jsonl';
@@ -998,6 +998,6 @@ function main() {
 
 // Run only when executed as a script — importing for unit tests must not parse
 // vitest's argv and exit 1.
-if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (isMainModule(import.meta.url)) {
   main();
 }

package/scripts/lock-reaper.mjs

@@ -22,6 +22,7 @@
  */
 
 import { reapStaleLocks } from './lib/lock-reaper.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 // ---------------------------------------------------------------------------
 // Human-readable output
@@ -175,7 +176,7 @@ EXIT CODES
 // CLI guard — prevents execution during test-time imports.
 // ---------------------------------------------------------------------------
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isMainModule(import.meta.url)) {
   main()
     .then((code) => process.exit(code))
     .catch((err) => {