session-orchestrator 5.0.0 → 5.2.0

package/scripts/lib/sunset/walker.mjs

@@ -39,9 +39,10 @@
 
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
 import { normalizeSkillInvocation } from '../skill-invocations-schema.mjs';
 import { normalizeSkillJudgment } from '../skill-judgments-schema.mjs';
+import { isMainModule } from '../is-main-module.mjs';
+import { userInvocableSkills } from '../user-invocable-skills.mjs';
 
 // ---------------------------------------------------------------------------
 // Named threshold constants
@@ -602,6 +603,16 @@ export function staticReferenceScan(repoRoot, { kind, name }) {
  * Parse commands/*.md for the skill each command invokes. Recognises the
  * conventional `skills/<name>/SKILL.md` reference inside a command file.
  *
+ * NOTE since the 2026-09-16 command→skill fold (#1370): this linkage now covers
+ * almost nothing. `commands/` holds two files (`session`, `templates-ack`), so
+ * `skillToCommands` is near-empty by construction — the operator entry point for
+ * every other slash command is an explicit `user-invocable: true` in the skill's
+ * own frontmatter, not a command file pointing at it. `runSunsetWalk` therefore
+ * threads that flag alongside this linkage, and `classifyItem` treats the two as
+ * equivalent evidence of "an operator can invoke this directly". Without that, 26
+ * live slash commands would have been demoted the day their command file was
+ * deleted, for a reason that is a rename, not a disuse signal.
+ *
  * @param {string} repoRoot
  * @returns {{commandToSkill: Map<string,string|null>, skillToCommands: Map<string,string[]>}}
  */
@@ -772,6 +783,11 @@ export function classifyItem({
   const strictRefs = staticRefs.strictRefs;
   const nonBoilerplateRefs = staticRefs.nonBoilerplateRefs;
   const invokedByCommands = linkage?.invokedByCommands ?? [];
+  // #1370 fold: an explicit `user-invocable: true` in SKILL.md frontmatter is the
+  // post-fold form of "an operator invokes this directly" — the same evidence a
+  // command file used to carry. Default false so older callers/tests that do not
+  // thread it behave exactly as before.
+  const userInvocable = linkage?.userInvocable === true;
   const invokesSkill = linkage?.invokesSkill ?? null;
   // When a command invokes a skill, the caller passes whether that skill is
   // present on disk. Default-true so callers that don't thread the surface set
@@ -786,6 +802,7 @@ export function classifyItem({
     proseRefs,
     nonBoilerplateRefs,
     invokedByCommands,
+    userInvocable,
     invokesSkill,
     invokedSkillExists,
     lowConfidence,
@@ -842,6 +859,10 @@ export function classifyItem({
     active = true;
     reasons.push(`skill invoked by command(s): ${invokedByCommands.join(', ')}`);
   }
+  if (kind === 'skill' && userInvocable) {
+    active = true;
+    reasons.push('skill is an operator-facing slash command (user-invocable: true)');
+  }
   if (kind === 'command' && invokesSkill && invokedSkillExists) {
     active = true;
     reasons.push(`command invokes live skill: ${invokesSkill}`);
@@ -878,7 +899,10 @@ export function classifyItem({
 
   // --- Demote (near-zero) — skills & commands (agents handled above) ---------
   const lonelySkill =
-    kind === 'skill' && nonBoilerplateRefs <= 1 && invokedByCommands.length === 0;
+    kind === 'skill' &&
+    nonBoilerplateRefs <= 1 &&
+    invokedByCommands.length === 0 &&
+    !userInvocable;
   const lonelyCommand =
     kind === 'command' && !invokesSkill && nonBoilerplateRefs <= 1;
   if (lonelySkill || lonelyCommand) {
@@ -942,6 +966,9 @@ export function runSunsetWalk(repoRoot, opts = {}) {
   // classification below behaves byte-for-byte identically to the L1-only path.
   const skillJudgments = readSkillJudgmentCounts(judgmentsPath, { windowDays, now: nowMs });
   const linkage = commandSkillLinkage(repoRoot);
+  // Post-#1370 replacement for the command→skill linkage as an operator-entry
+  // signal (see commandSkillLinkage's note). Read once per walk, not per skill.
+  const userInvocableSet = new Set(userInvocableSkills(repoRoot));
   const coverageDays = dispatch.coverageDays;
   const lowConfidence = coverageDays < windowDays;
 
@@ -967,7 +994,7 @@ export function runSunsetWalk(repoRoot, opts = {}) {
           name,
           dispatch: skillDispatch,
           static: staticRefs,
-          linkage: { invokedByCommands },
+          linkage: { invokedByCommands, userInvocable: userInvocableSet.has(name) },
           windowDays,
           coverageDays,
           judge,
@@ -1192,7 +1219,7 @@ function main(argv) {
 }
 
 // Import-safe main-guard.
-if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+if (isMainModule(import.meta.url)) {
   const code = main(process.argv.slice(2));
   process.exit(code);
 }

package/scripts/lib/tests-src-ratio.mjs

@@ -76,9 +76,9 @@
 import { readFileSync, existsSync, statSync } from 'node:fs';
 import { join, isAbsolute, relative, resolve } from 'node:path';
 import { execFileSync } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
 
 import { writeStdoutLineSync } from './io.mjs';
+import { isMainModule } from './is-main-module.mjs';
 
 // ---------------------------------------------------------------------------
 // The definition — the part that must never be re-derived by hand
@@ -475,10 +475,6 @@ function main() {
   process.exit(args.check && !result.withinCorridor ? 1 : 0);
 }
 
-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) main();

package/scripts/lib/tmux-layout/telemetry-stats.mjs

@@ -14,6 +14,7 @@
  */
 
 import { readFileSync, existsSync } from 'node:fs';
+import { isMainModule } from '../is-main-module.mjs';
 
 const EVENTS_PATH = '.orchestrator/metrics/events.jsonl';
 
@@ -93,7 +94,7 @@ export function computeStats(events) {
 }
 
 // CLI entry-point — emit stats as JSON to stdout when run directly
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isMainModule(import.meta.url)) {
   const events = readTmuxEvents();
   const stats = computeStats(events);
   console.log(JSON.stringify(stats, null, 2));

package/scripts/lib/user-invocable-skills.mjs

@@ -0,0 +1,185 @@
+/**
+ * scripts/lib/user-invocable-skills.mjs
+ *
+ * ONE definition of "this skill is an operator-facing slash command".
+ *
+ * Since the #1370 command→skill fold (2026-09-16) `commands/` holds only the two
+ * names that cannot be a skill (`session`, `templates-ack` — see
+ * `tests/commands/headless-bare-command-availability.test.mjs` for the measured
+ * mechanism). Every other slash command IS a skill, marked by an EXPLICIT
+ * `user-invocable: true` in its SKILL.md frontmatter. Consumers that used to
+ * count or link `commands/*.md` therefore need the union:
+ *
+ *   commands/*.md  ∪  skills with explicit `user-invocable: true`
+ *
+ * This module exists so that union has one implementation rather than one per
+ * consumer (site-numbers tile, sunset walker linkage, the guard tests). It is
+ * deliberately tiny and dependency-free: `scripts/lib/sunset/walker.mjs` imports it,
+ * and the walker sits in the hook import graph, which must load WITHOUT
+ * node_modules (GH#62/#63) — so no `js-yaml` here; the frontmatter parser is the
+ * repo's own `parseAgentFrontmatter`, already in that graph.
+ *
+ * PARSED, never line-matched: `.claude/rules/test-hygiene.md` records that a
+ * line-regex frontmatter reader is blind to unparseable YAML and mis-measures
+ * block scalars. A SKILL.md whose frontmatter does not parse is treated as NOT
+ * user-invocable — fail-closed, and loud where it matters because such a file
+ * already fails `check-skills`/`validate-plugin`.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { parseAgentFrontmatter } from './agent-frontmatter.mjs';
+
+/**
+ * YAML 1.1 boolean lookalikes that YAML 1.2 / js-yaml's CORE_SCHEMA (what
+ * `generate-codex-skills` parses with) reads as PLAIN STRINGS, not as `true`.
+ * They are therefore NOT user-invocable here either — but silently demoting a
+ * skill on one of them is the #1370 defect class, so each one gets a WARN.
+ */
+const TRUTHY_LOOKALIKE = /^(?:yes|y|on|t|1)$/i;
+
+/**
+ * Strip a trailing `#` comment, honouring quotes: `true # note` is the same
+ * declaration as `true`, but `"a # b"` carries the hash as content.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function stripTrailingComment(text) {
+  let quote = null;
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i];
+    if (quote) {
+      if (ch === quote) quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      continue;
+    }
+    // A `#` opens a YAML comment only at the start or after whitespace.
+    if (ch === '#' && (i === 0 || /\s/.test(text[i - 1]))) return text.slice(0, i);
+  }
+  return text;
+}
+
+/**
+ * Normalise a raw frontmatter scalar to the token a YAML parser would see:
+ * trim, drop a trailing comment, drop one layer of matching surrounding quotes.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function normaliseScalar(text) {
+  let out = stripTrailingComment(text).trim();
+  if (out.length >= 2 && (out[0] === '"' || out[0] === "'") && out[out.length - 1] === out[0]) {
+    out = out.slice(1, -1).trim();
+  }
+  return out;
+}
+
+/**
+ * THE one normaliser for `user-invocable` — the marker "this skill is an
+ * operator-facing slash command". Every generator (Cursor, Pi, Codex) and every
+ * counter (site-numbers tile, drift-check `command-count`, the guard tests) must
+ * route through this function; four private re-implementations disagreeing on a
+ * quoted value is the defect this replaces.
+ *
+ * Explicit-true only. `undefined` (flag absent) is NOT user-invocable: the whole
+ * point of the marker is that it is written down, so a skill that forgot it is a
+ * defect to surface, not a default to guess.
+ *
+ * Accepted: the boolean `true`, and a string that normalises to `true`
+ * case-insensitively — so `"true"`, `'true'`, `True`, `true # note` and
+ * `true ` (trailing space, invisible in an editor) all read as the same
+ * declaration. Trailing-whitespace tolerance is load-bearing rather than
+ * cosmetic: without it a stray space silently demotes a skill out of the
+ * generated adapters with no diagnostic anywhere.
+ *
+ * REJECTED: `yes` / `y` / `on` / `t` / `1`. Those are YAML 1.1 booleans; under
+ * YAML 1.2 — which is what js-yaml's CORE_SCHEMA in `generate-codex-skills`
+ * applies — they are plain strings, and this predicate follows the parser rather
+ * than inventing a fifth dialect. Because the demotion is the surprising half,
+ * each one emits exactly one stderr WARN naming the file.
+ *
+ * @param {unknown} value the raw frontmatter value
+ * @param {string} [file] path named in the WARN when a truthy-looking value is demoted
+ * @returns {boolean}
+ */
+export function isUserInvocableValue(value, file) {
+  if (value === true) return true;
+  if (typeof value !== 'string') return false;
+  const token = normaliseScalar(value);
+  if (token.toLowerCase() === 'true') return true;
+  if (TRUTHY_LOOKALIKE.test(token)) {
+    const where = file ? `${file}: ` : '';
+    process.stderr.write(
+      `WARN ${where}user-invocable: ${JSON.stringify(value)} is NOT a slash-command marker — `
+        + 'only `true` is (YAML 1.2 reads yes/on/1 as strings). Write `user-invocable: true`.\n',
+    );
+  }
+  return false;
+}
+
+/**
+ * Parse a SKILL.md's YAML frontmatter. Returns `null` when there is no
+ * frontmatter block or it does not parse.
+ *
+ * @param {string} content
+ * @returns {Record<string, unknown>|null}
+ */
+export function parseSkillFrontmatter(content) {
+  if (typeof content !== 'string') return null;
+  const parsed = parseAgentFrontmatter(content);
+  return parsed.ok ? parsed.frontmatter : null;
+}
+
+/**
+ * Names of skills carrying an explicit `user-invocable: true`, sorted.
+ *
+ * @param {string} repoRoot plugin root (the directory holding `skills/`)
+ * @returns {string[]}
+ */
+export function userInvocableSkills(repoRoot) {
+  const dir = path.join(repoRoot, 'skills');
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) return [];
+  const names = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+    const file = path.join(dir, entry.name, 'SKILL.md');
+    if (!existsSync(file) || !statSync(file).isFile()) continue;
+    let fm;
+    try {
+      fm = parseSkillFrontmatter(readFileSync(file, 'utf8'));
+    } catch {
+      continue;
+    }
+    if (fm && isUserInvocableValue(fm['user-invocable'], file)) names.push(entry.name);
+  }
+  return names.sort();
+}
+
+/** Names of `commands/*.md` files (without the extension), sorted. */
+export function commandFileNames(repoRoot) {
+  const dir = path.join(repoRoot, 'commands');
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) return [];
+  return readdirSync(dir)
+    .filter((f) => f.endsWith('.md') && !f.startsWith('.'))
+    .map((f) => f.replace(/\.md$/, ''))
+    .sort();
+}
+
+/**
+ * The product's "slash commands" set: `commands/*.md` ∪ explicitly
+ * user-invocable skills, deduplicated by NAME.
+ *
+ * Dedup is load-bearing rather than defensive: a name present as BOTH is the
+ * picker-duplicate bug (the body runs, and the entry lists twice), so it must
+ * count once here and go red in the guard test — never inflate the number.
+ *
+ * @param {string} repoRoot
+ * @returns {string[]} sorted unique names
+ */
+export function slashCommandNames(repoRoot) {
+  return [...new Set([...commandFileNames(repoRoot), ...userInvocableSkills(repoRoot)])].sort();
+}

package/scripts/lib/validate/check-banner-parity.mjs

@@ -46,8 +46,8 @@
 import { execFileSync } from 'node:child_process';
 import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
 import { HISTORICAL_GUARD_BANNER } from '../historical-guard.mjs';
+import { isMainModule } from '../is-main-module.mjs';
 
 /** Directories whose markdown quotes the banner as coordinator-facing prose. */
 const SCAN_DIRS = Object.freeze(['skills', 'commands']);
@@ -365,7 +365,7 @@ export function runCheckBannerParity(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-cursor-adapter.mjs

@@ -6,11 +6,11 @@
 import { spawnSync } from 'node:child_process';
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { join, relative } from 'node:path';
-import { pathToFileURL } from 'node:url';
 
 import yaml from 'js-yaml';
 
 import { CURSOR_TO_CANONICAL_EVENT } from '../cursor-hook-bridge.mjs';
+import { isMainModule } from '../is-main-module.mjs';
 
 /** agentskills.io caps a skill/command description at 1024 characters. */
 const DESCRIPTION_MAX = 1024;
@@ -259,6 +259,6 @@ function runCli(pluginRoot) {
 }
 
 // Direct invocation only — importing this module must not run the CLI.
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (isMainModule(import.meta.url)) {
   runCli(process.argv[2]);
 }

package/scripts/lib/validate/check-dead-bridge.mjs

@@ -22,12 +22,12 @@
 // or process.exit — the isMain guard at the bottom is the only side-effecting
 // path. The Quality wave imports runCheckDeadBridge directly for unit tests.
 
-import { pathToFileURL } from 'node:url';
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { DETECTORS } from './dead-bridge-detectors.mjs';
 import * as corpus from './dead-bridge-corpus.mjs';
 import { listRepoFiles } from './repo-files.mjs';
+import { isMainModule } from '../is-main-module.mjs';
 
 const DEFAULT_EXTS = ['.mjs', '.md'];
 
@@ -191,7 +191,7 @@ export function runCheckDeadBridge(pluginRoot) {
 
 // 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 pluginRoot = process.argv[2];
   if (!pluginRoot) {

package/scripts/lib/validate/check-doc-cli-commands.mjs

@@ -65,9 +65,9 @@
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { pathToFileURL } from 'node:url';
 import { listRepoFiles } from './repo-files.mjs';
 import { SHELL_LANGS, forEachLine } from './markdown-fences.mjs';
+import { isMainModule } from '../is-main-module.mjs';
 
 /** Directories walked for documentation. Mirrors check-vcs-repo-flag.mjs. */
 const SCAN_DIRS = Object.freeze([
@@ -461,7 +461,7 @@ export function runCheckDocCliCommands(pluginRoot) {
   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).filter((arg) => arg !== '--json');
   const root = path.resolve(args[0] || process.cwd());