session-orchestrator 5.0.0 → 5.2.0

package/scripts/materialize-wave-scope.mjs

@@ -23,10 +23,11 @@
  */
 
 import { existsSync, readdirSync, readFileSync, unlinkSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
 import { writeJsonAtomicSync } from './lib/io.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 import { isPeerRecordId } from './lib/scope-gate.mjs';
+import { SCOPE_MATERIALIZED_EVENT, scopeDigest } from './lib/scope-echo.mjs';
 import {
   MANIFEST_SESSION_KEYS,
   manifestSessionBinding,
@@ -479,6 +480,83 @@ export function materializeWaveScope(records, {
   return { aggregatePath, perAgentPaths, removedOrphans: removed, retainedOrphans: retained };
 }
 
+/**
+ * Is the SEND-side half of the #1092 chain installed on this platform at all?
+ *
+ * The send-side record only exists because a `PreToolUse` hook with matcher
+ * `Agent` observes the dispatch. `hooks-codex.json` / `hooks-cursor.json` /
+ * `hooks-pi.json` deliberately carry no such entry (those platforms have no
+ * `Agent` dispatch tool — `DOCUMENTED_ASYMMETRIES`), so on them a MISSING
+ * dispatch record is not evidence of a missing injection. Recording the answer
+ * beside the wave is what lets `--verify` tell those two apart later instead of
+ * re-deriving a platform fact from an absence.
+ *
+ * Fail-CLOSED on any read error: an unreadable hooks file means the guard cannot
+ * be shown to be installed, and claiming observability we cannot prove is the
+ * direction that produces false `injection-missing` accusations.
+ *
+ * @param {string} [pluginRoot]
+ * @param {typeof readFileSync} [readFile]
+ * @returns {boolean}
+ */
+export function transportObservable(pluginRoot = resolve(import.meta.dirname, '..'), readFile = readFileSync) {
+  try {
+    const parsed = JSON.parse(readFile(resolve(pluginRoot, 'hooks', 'hooks.json'), 'utf8'));
+    const entries = parsed?.hooks?.PreToolUse;
+    if (!Array.isArray(entries)) return false;
+    return entries.some((entry) => typeof entry?.matcher === 'string'
+      && entry.matcher.split('|').map((m) => m.trim()).includes('Agent'));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * One `orchestrator.wave_dispatch.scope_materialized` record per wave (#1092) —
+ * the DEGRADATION half of the chain.
+ *
+ * It runs here, and not in the hook, precisely because this command runs on
+ * EVERY platform while the hook runs on one. Without it a wave with zero
+ * `scope_checked` records is ambiguous between "the coordinator skipped the
+ * manifest step" (the #1020 failure this whole chain exists for) and "this
+ * platform has no dispatch hook".
+ *
+ * `repoRoot` is the state directory's PARENT, never `process.cwd()`: the state
+ * dir is the artefact this command owns, and a caller invoking it from a
+ * subdirectory (or a test from the repo root against a `$TMPDIR` state dir)
+ * must not write its record into a different repo's ledger.
+ *
+ * Best-effort in both directions and SILENT on failure: the corpus pins
+ * byte-empty stderr on this command's success path
+ * (`tests/integration/wave-scope-producer.test.mjs`), and a telemetry write must
+ * never be the thing that fails a materialization.
+ *
+ * @param {{stateDir: string, wave: number, records: Array<{id: string, files: string[]}>}} params
+ * @returns {Promise<void>}
+ */
+async function emitScopeMaterialized({ stateDir, wave, records }) {
+  try {
+    const repoRoot = dirname(resolve(stateDir));
+    const agentRecords = records.filter((r) => !isPeerRecordId(r.id));
+    const digests = new Set();
+    for (const record of agentRecords) {
+      if (Array.isArray(record.files) && record.files.length > 0) digests.add(scopeDigest(record.files));
+    }
+    const { emitEvent, sessionAttribution } = await import('./lib/events.mjs');
+    await emitEvent(
+      SCOPE_MATERIALIZED_EVENT,
+      {
+        wave,
+        agent_count: agentRecords.length,
+        digest_count: digests.size,
+        transport_observable: transportObservable(),
+        ...sessionAttribution(repoRoot),
+      },
+      { repoRoot },
+    );
+  } catch { /* observability is best-effort — it never fails a materialization */ }
+}
+
 /**
  * @param {string} message
  * @param {number} code
@@ -536,6 +614,12 @@ export function main() {
         ? `${JSON.stringify({ ok: true, aggregatePath, perAgentPaths, removedOrphans, retainedOrphans })}\n`
         : `${aggregatePath}\n`,
     );
+
+    // Fire-and-forget AFTER stdout, so the telemetry append can never reorder or
+    // delay this command's own contract. Node drains the pending append before
+    // exiting because nothing here calls `process.exit()`; the `.catch` keeps an
+    // unhandled rejection from turning observability into an exit code.
+    emitScopeMaterialized({ stateDir: args.stateDir, wave: args.wave, records }).catch(() => {});
   } catch (error) {
     if (error instanceof InputError) {
       fail(error.message, 1);
@@ -549,7 +633,6 @@ export function main() {
   }
 }
 
-const invokedPath = process.argv[1] ? resolve(process.argv[1]) : null;
-if (invokedPath === fileURLToPath(import.meta.url)) {
+if (isMainModule(import.meta.url)) {
   main();
 }

package/scripts/migrate-sessions-jsonl.mjs

@@ -41,6 +41,7 @@
 import { readFileSync, writeFileSync, renameSync, copyFileSync, existsSync } from 'node:fs';
 import { join, dirname, basename } from 'node:path';
 import { validateSession, normalizeSession, ValidationError } from './lib/session-schema.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 const DEFAULT_FILE = '.orchestrator/metrics/sessions.jsonl';
 
@@ -440,7 +441,7 @@ async function main() {
 
 // Run main() only when this file is invoked directly as a CLI, not when imported.
 // Prevents process.exit during test-time imports (#368).
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isMainModule(import.meta.url)) {
   main().catch((err) => {
     process.stderr.write(`migrate-sessions-jsonl: unexpected error: ${err?.stack ?? err}\n`);
     process.exit(2);

package/scripts/migrate-vault-paths.mjs

@@ -50,7 +50,6 @@
 
 import { promises as fs, existsSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
-import { pathToFileURL } from 'node:url';
 import path from 'node:path';
 import os from 'node:os';
 import {
@@ -58,6 +57,7 @@ import {
   VAULT_MIGRATION_RULES_PATH,
 } from './lib/vault-migration-rules.mjs';
 import { parseColumnFlags, CliFlagError } from './lib/cli-flags.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -773,8 +773,7 @@ function emit(opts, rec) {
 // importing the module is never a hard error regardless of how the importer runs.
 // ---------------------------------------------------------------------------
 
-const invokedDirectly =
-  process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
+const invokedDirectly =isMainModule(import.meta.url);
 
 if (invokedDirectly) {
   main().catch((err) => {

package/scripts/release.mjs

@@ -356,7 +356,7 @@ const INTENTIONAL_TEST_ASSET_PATHS = new Set([
   'templates/python-uv/tests/test_sanity.py',
 ]);
 
-// `commands/release.md` quotes the `npm view` OUTPUT that proves the 3.18.0 gap,
+// `skills/release/SKILL.md` quotes the `npm view` OUTPUT that proves the 3.18.0 gap,
 // dated at the line. Bumping it would destroy the evidence it exists to carry —
 // the registry state on that date is the whole point of the paragraph.
 //
@@ -384,7 +384,7 @@ const INTENTIONAL_TEST_ASSET_PATHS = new Set([
 // September 10 campaign snapshot: inputs and receipt reproduce the dated 4.3-planned
 // render made while 4.2.0 was current. Exact files only; neighboring marketing
 // remains checked. Do not bump receipt props without a newly reviewed render.
-export const HISTORY_ALLOWLIST = /^(CHANGELOG\.md|README\.md|CLAUDE\.md|AGENTS\.md|CONTRIBUTING\.md|NOTICE|\.husky\/pre-push|docs\/|tests\/|skills\/npm-publish\/|skills\/architecture\/references\/domain-model\.md|skills\/autopilot\/SKILL\.md|scripts\/release\.mjs|\.orchestrator\/|site\/leaderboard\.json|site\/guide\/index\.html|site\/llms-full\.txt|commands\/release\.md|marketing\/remotion\/(?:README\.md|campaign\.json|render-receipt\.json|src\/ReleaseFilm\.tsx)$)/;
+export const HISTORY_ALLOWLIST = /^(CHANGELOG\.md|README\.md|CLAUDE\.md|AGENTS\.md|CONTRIBUTING\.md|NOTICE|\.husky\/pre-push|docs\/|tests\/|skills\/npm-publish\/|skills\/architecture\/references\/domain-model\.md|skills\/autopilot\/SKILL\.md|scripts\/release\.mjs|\.orchestrator\/|site\/leaderboard\.json|site\/guide\/index\.html|site\/llms-full\.txt|skills\/release\/SKILL\.md|marketing\/remotion\/(?:README\.md|campaign\.json|render-receipt\.json|src\/ReleaseFilm\.tsx)$)/;
 
 /** Pure check over packed-entry lines. Returns violations: {name, line}[]. */
 export function checkLeakage(lines) {
@@ -511,6 +511,49 @@ const LOCKFILE_BASENAMES = new Set(['package-lock.json', 'npm-shrinkwrap.json'])
 /** Code files in which a `//`, `*`, `/*` or `#` line is comment prose, never a version surface. */
 const CODE_COMMENT_EXTENSIONS = new Set(['.mjs', '.js', '.cjs', '.ts', '.sh']);
 
+/** Workflow/CI files in which a SHA-pinned `uses:` carries a third-party version as a trailing comment. */
+const YAML_EXTENSIONS = new Set(['.yml', '.yaml']);
+
+/**
+ * Is this YAML row a SHA-pinned THIRD-PARTY action whose version lives only in the
+ * trailing comment?
+ *
+ * Measured on the 5.1.0 cut (2026-09-13): `.github/workflows/test.yml` carries
+ * `uses: actions/setup-node@a0853c2…  # v5.0.0` twice. That `5.0.0` is setup-node's
+ * version, not ours — the sweep matched it only because our previous release happened
+ * to land on the same number, so the false positive is triggered by COINCIDENCE and
+ * would reappear for any action whose pin equals our next version.
+ *
+ * Expressed as a PREDICATE, like the three classes above, for the reason
+ * `.claude/rules/measurement-discipline.md` records: a per-path allowlist row fixes
+ * this file and leaves the class open for the next workflow.
+ *
+ * Two conditions, both required, so the predicate cannot mask a stale surface of ours:
+ *   1. the line pins a reference with `uses:` BEFORE the comment marker, and
+ *   2. EVERY occurrence of the literal sits AFTER that marker.
+ * A version in the pin itself (`uses: foo@v5.0.0`) fails condition 2 and is still swept.
+ *
+ * NAMED CEILING (BV-004): no SURFACES pattern targets a `.yml`/`.yaml` file today, so a
+ * YAML hit is never our own surface anyway. Revisit trigger: the first version surface
+ * added to a YAML file — then this predicate must also exclude that file's pattern.
+ *
+ * @param {string} content — the matching line's text
+ * @param {string} literal — the previous release literal being swept for
+ * @returns {boolean} true = third-party pin comment, skip the row
+ */
+export function isPinnedActionComment(content, literal) {
+  const hash = content.indexOf('#');
+  if (hash === -1) return false;
+  if (!/\buses:\s*\S/.test(content.slice(0, hash))) return false;
+  const re = versionTokenRegex(literal);
+  let seen = 0;
+  for (let m = re.exec(content); m; m = re.exec(content)) {
+    seen += 1;
+    if (m.index < hash) return false;
+  }
+  return seen > 0;
+}
+
 /**
  * Is this `path:line:content` row version HISTORY rather than a stale surface?
  *
@@ -546,6 +589,7 @@ function isHistoryRow(file, line, content, prevTag) {
   }
   const dot = base.lastIndexOf('.');
   const ext = dot === -1 ? '' : base.slice(dot);
+  if (YAML_EXTENSIONS.has(ext) && isPinnedActionComment(content, prevTag)) return true;
   if (CODE_COMMENT_EXTENSIONS.has(ext)) {
     const trimmed = content.trim();
     if (trimmed.startsWith('//') || trimmed.startsWith('/*') || trimmed.startsWith('*')) return true;
@@ -864,6 +908,11 @@ export function evaluateCiRow(ci) {
  * "we could not read the mirror" is not "the mirror is green" (the fail-closed
  * house rule at the top of this file).
  *
+ * This function only judges the `ci` reading it is handed — it is
+ * `evaluateCiPreflightRows` (the caller, see its own docblock) that fetches
+ * `ci` for the commit actually being released, rather than whichever HEAD the
+ * GitHub mirror itself reports.
+ *
  * @param {string|undefined} repoSpec — `resolveRepoSpec({vcs:'github'})`, undefined when no github remote resolves
  * @param {null | {status?: string, failingJobName?: string, degraded?: string}} ci
  * @returns {{ok: boolean, detail: string}}
@@ -925,6 +974,62 @@ function readPackageVersion(repoRoot) {
   return JSON.parse(readFileSync(join(repoRoot, 'package.json'), 'utf8')).version;
 }
 
+/**
+ * Both CI preflight rows (`ci-green-on-head` + `ci-green-on-head-github`) for
+ * ONE commit — the commit actually about to be released — never whichever
+ * HEAD the queried platform happens to report.
+ *
+ * Before this function existed, neither `checkCiStatus` call below passed
+ * `sha`, so the GitHub branch fell back to `commits/HEAD` — the MIRROR's own
+ * default-branch head, which is the release commit only once `head-pushed-github`
+ * has ALREADY proven `github/main == local HEAD`. A release cut before that
+ * push landed asked GitHub about a commit that was never pushed and could read
+ * green for work GitHub has not seen at all (measured 2026-09-16 for
+ * `3ebf0e9d`). The GitLab branch was already correct by default (`deps.sha ??
+ * getHeadSha(repoRoot)`), so only the two call sites below needed the fix —
+ * see `checkCiStatus`'s own docblock in `ci-status-banner.mjs` for the `sha`
+ * contract (#1332).
+ *
+ * Factored out of `preflight()` as its own async, DI-testable unit:
+ * `checkCiStatus` reaches the network by default, and `preflight()`'s
+ * surrounding checks (git, npm) are not test-doubled, so this is the seam
+ * through which the `sha` wiring can be unit-tested without spinning up a
+ * full fixture release.
+ *
+ * @param {string} repoRoot
+ * @param {string} head - full hex commit id of the commit being released (the
+ *   local HEAD `preflight()` already computed for the remote-parity rows).
+ * @param {{
+ *   skipCi?: boolean,
+ *   checkCiStatus?: Function,
+ *   resolveRepoSpec?: (opts: { repoRoot: string, vcs: 'github' }) => string|undefined,
+ * }} [deps]
+ * @returns {Promise<{ gitlab: {ok: boolean, detail: string}, github: {ok: boolean, detail: string} }>}
+ */
+export async function evaluateCiPreflightRows(repoRoot, head, {
+  skipCi = false,
+  checkCiStatus: checkCiStatusDep,
+  resolveRepoSpec: resolveRepoSpecDep = resolveRepoSpec,
+} = {}) {
+  if (skipCi) {
+    const skipped = { ok: true, detail: 'SKIPPED via --skip-ci' };
+    return { gitlab: skipped, github: skipped };
+  }
+  const checkCiStatusImpl = checkCiStatusDep ?? (await import('./lib/ci-status-banner.mjs')).checkCiStatus;
+
+  const ci = await checkCiStatusImpl({ repoRoot, timeoutMs: 15000, sha: head });
+  const gitlab = evaluateCiRow(ci);
+
+  const githubSpec = resolveRepoSpecDep({ repoRoot, vcs: 'github' });
+  let githubCi = null;
+  if (githubSpec) {
+    githubCi = await checkCiStatusImpl({ repoRoot, vcs: 'github', timeoutMs: 15000, sha: head });
+  }
+  const github = evaluateGithubCiRow(githubSpec, githubCi);
+
+  return { gitlab, github };
+}
+
 async function preflight(repoRoot, target, { skipCi = false } = {}) {
   const checks = [];
   const add = (name, ok, detail = '') => checks.push({ name, ok, detail });
@@ -1054,39 +1159,23 @@ async function preflight(repoRoot, target, { skipCi = false } = {}) {
     add('npm-token-live', false, err.message);
   }
 
-  // 6. CI green on HEAD (the repo's iron session-start rule applies to
-  // releases doubly: local green is not evidence — see .claude/rules).
-  // --skip-ci is refused under --publish upstream in validateFlags(); it can
-  // only reach this branch from --check.
-  if (skipCi) {
-    add('ci-green-on-head', true, 'SKIPPED via --skip-ci');
-  } else {
-    const { checkCiStatus } = await import('./lib/ci-status-banner.mjs');
-    const ci = await checkCiStatus({ repoRoot, timeoutMs: 15000 });
-    const row = evaluateCiRow(ci);
-    add('ci-green-on-head', row.ok, row.detail);
-  }
-
-  // 6b. CI green on the GitHub mirror too. The row above asks the platform
-  // `detectVcsFamily` picks for `origin` (GitLab), whose pipeline is Linux-only;
-  // the macOS matrix leg lives exclusively in `.github/workflows/test.yml`.
-  // `vcs: 'github'` forces the probe onto the mirror without touching the
-  // detection order. The GitHub check-runs path reads `commits/HEAD`, i.e. the
-  // mirror's default-branch head — which is HEAD only because `head-pushed-github`
-  // above proves github/main == local HEAD; that row is this one's precondition,
-  // not a duplicate of it.
-  if (skipCi) {
-    add('ci-green-on-head-github', true, 'SKIPPED via --skip-ci');
-  } else {
-    const githubSpec = resolveRepoSpec({ repoRoot, vcs: 'github' });
-    let githubCi = null;
-    if (githubSpec) {
-      const { checkCiStatus } = await import('./lib/ci-status-banner.mjs');
-      githubCi = await checkCiStatus({ repoRoot, vcs: 'github', timeoutMs: 15000 });
-    }
-    const row = evaluateGithubCiRow(githubSpec, githubCi);
-    add('ci-green-on-head-github', row.ok, row.detail);
-  }
+  // 6/6b. CI green on HEAD, both platforms — judged for the commit actually
+  // being released, never whichever HEAD the queried platform reports (see
+  // evaluateCiPreflightRows's docblock for the `sha`-wiring history, #1332).
+  //
+  // GitLab: the repo's iron session-start rule applies to releases doubly —
+  // local green is not evidence — see .claude/rules. GitHub: this second row
+  // exists because `detectVcsFamily` picks `origin` (GitLab) for the row
+  // above, whose pipeline is Linux-only; the macOS matrix leg lives
+  // exclusively in `.github/workflows/test.yml`. `vcs: 'github'` forces the
+  // probe onto the mirror without touching the detection order.
+  // SELF-DISABLING: a checkout with no `github` remote has no mirror to be
+  // red, so `evaluateGithubCiRow` reports `skipped` rather than red — see its
+  // own docblock. --skip-ci is refused under --publish upstream in
+  // validateFlags(); it can only reach this branch from --check.
+  const ciRows = await evaluateCiPreflightRows(repoRoot, head, { skipCi });
+  add('ci-green-on-head', ciRows.gitlab.ok, ciRows.gitlab.detail);
+  add('ci-green-on-head-github', ciRows.github.ok, ciRows.github.detail);
 
   // 7. Leakage gate over the actual pack file list.
   // `npm_config_loglevel` is INHERITED, and `npm pack --dry-run` writes its whole

package/scripts/relocate-vault-corpus.mjs

@@ -40,7 +40,6 @@
 
 import { promises as fs, existsSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
-import { pathToFileURL } from 'node:url';
 import path from 'node:path';
 import {
   loadVaultRelocationRules,
@@ -55,6 +54,7 @@ import {
 } from './lib/vault-relocation-rules.mjs';
 import { buildBackfillIndex, parseSessionId } from './lib/vault-repo-backfill.mjs';
 import { parseColumnFlags, CliFlagError } from './lib/cli-flags.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -1158,8 +1158,7 @@ async function main() {
 // Entry guard (run only when invoked directly)
 // ---------------------------------------------------------------------------
 
-const invokedDirectly =
-  process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
+const invokedDirectly =isMainModule(import.meta.url);
 
 if (invokedDirectly) {
   main().catch((err) => {

package/scripts/repair-invalid-sessions.mjs

@@ -37,10 +37,10 @@
 import fs from 'node:fs';
 import { parseArgs } from 'node:util';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 
 import { repairLedger, CANONICAL_LEDGER_REL } from './lib/session-record-repair.mjs';
 import { getProjectDir } from './lib/platform.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 const USAGE =
   'Usage: node scripts/repair-invalid-sessions.mjs [--dry-run|--apply] [--json]\n' +
@@ -200,7 +200,7 @@ async function main() {
   process.exit(summary.ok === false ? 3 : 0);
 }
 
-const isDirectRun = process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1];
+const isDirectRun =isMainModule(import.meta.url);
 if (isDirectRun) {
   main().catch((err) => {
     process.stderr.write(`repair-invalid-sessions: unexpected error: ${err?.stack ?? err}\n`);

package/scripts/session-shape.mjs

@@ -42,10 +42,10 @@
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
-import { fileURLToPath } from 'node:url';
 import { resolveInstructionFile } from './lib/common.mjs';
 import { parseSessionConfig } from './lib/config.mjs';
 import { resolveAndRecordSessionShape } from './lib/session-shape.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 const USAGE = [
   'Usage: node scripts/session-shape.mjs --repo-root <path> --session-type <housekeeping|feature|deep>',
@@ -258,7 +258,7 @@ async function main() {
 }
 
 // Entrypoint guard — importing this file must not run it (check-unwired-features S3).
-if (process.argv[1] && resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url))) {
+if (isMainModule(import.meta.url)) {
   main().catch((err) => {
     process.stderr.write(`session-shape: unexpected error: ${err?.stack ?? err}\n`);
     process.exit(EXIT_CONFIG_IO);

package/scripts/site-numbers.mjs

@@ -101,10 +101,11 @@
 import { readFileSync, writeFileSync, readdirSync, existsSync, statSync } from 'node:fs';
 import { join, resolve, relative } from 'node:path';
 import { execFileSync } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
 
 import { writeStdoutLineSync, writeJsonAtomicSync } from './lib/io.mjs';
 import { readCanonicalSessions } from './lib/sessions-canonical.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
+import { slashCommandNames } from './lib/user-invocable-skills.mjs';
 
 /** Machine-readable schema tag for the --json envelope. */
 export const SCHEMA = 'site-numbers/1';
@@ -169,11 +170,37 @@ export function countSkills(root) {
   return n;
 }
 
-/** `ls commands/*.md | wc -l` — same basis as checker.mjs `command-count`. */
+/**
+ * The product's "slash commands" number: `commands/*.md` ∪ skills carrying an
+ * EXPLICIT `user-invocable: true`, deduplicated by name.
+ *
+ * NOT `ls commands/*.md | wc -l` any more, and the change is not cosmetic. After
+ * the 2026-09-16 fold (#1370) `commands/` holds two files — `session` and
+ * `templates-ack`, the only two names a skill cannot carry — while 26 operator-
+ * facing slash commands exist. A command file only ever resolved because a
+ * same-named skill existed, and the twin additionally listed the entry twice in
+ * the `/` picker; the skill frontmatter flag is what makes a slash command a
+ * slash command now. Counting the directory would have reported 2.
+ *
+ * Dedup by name is load-bearing: a name present on BOTH sides is the picker-
+ * duplicate defect (`tests/commands/headless-bare-command-availability.test.mjs`
+ * fails on it), so it must count once here rather than inflate the tile.
+ *
+ * null (→ the tile renders as unmeasured) only when NEITHER `commands/` nor
+ * `skills/` exists — i.e. this is not a plugin tree at all. A tree with one of
+ * the two counts what it has; a missing `commands/` is now the NORMAL state, not
+ * a missing measurement.
+ *
+ * NO divergence from `skills/claude-md-drift-check/checker.mjs` `command-count`:
+ * that checker unions the same user-invocable skills (`checker.mjs:435-446`,
+ * measured 2026-09-17), and both routes reach the same verdict through the same
+ * SSOT — `isUserInvocableValue` in `scripts/lib/user-invocable-skills.mjs`. The
+ * checker stays GENERIC over consumer repos only in the sense that a repo
+ * without `skills/` sees the union collapse to the directory count on its own.
+ */
 export function countCommands(root) {
-  const dir = join(root, 'commands');
-  if (!isDir(dir)) return null;
-  return readdirSync(dir).filter((f) => f.endsWith('.md') && !f.startsWith('.')).length;
+  if (!isDir(join(root, 'commands')) && !isDir(join(root, 'skills'))) return null;
+  return slashCommandNames(root).length;
 }
 
 /**
@@ -400,7 +427,8 @@ export const METRIC_DEFS = Object.freeze([
   {
     id: 'commands',
     provenance: false,
-    source: 'ls commands/*.md | wc -l',
+    source:
+      'ls commands/*.md | wc -l  +  grep -l "^user-invocable: true" skills/*/SKILL.md | wc -l   (union by name — see countCommands)',
     compute: (root) => fmtCount(countCommands(root)),
   },
   {
@@ -1398,11 +1426,7 @@ export function main(argv = process.argv.slice(2), env = {}) {
   return exitCode;
 }
 
-const isMain =
-  typeof process !== 'undefined' &&
-  process.argv[1] !== null &&
-  process.argv[1] !== undefined &&
-  resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url));
+const isMain =isMainModule(import.meta.url);
 
 if (isMain) {
   const argv = process.argv.slice(2);