session-orchestrator 5.2.0 → 5.3.0

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

@@ -11,6 +11,16 @@
  * #1241 adds blocking repo-rooted `.md` paths quoted as complete inline-code
  * spans, with the same annotations and fence handling. Scan roots stay fixed.
  *
+ * ## The runtime-artefact carve-out needs BOTH halves
+ *
+ * A missing citation is excused as a runtime artefact only when it sits under
+ * a harness STATE root ({@link RUNTIME_STATE_PREFIXES}) *and* git ignores it.
+ * The git half alone is not the claim it looks like: `.gitignore` also
+ * declines to track real local documents (`docs/specs/`, `docs/_private/`) and
+ * build output (`coverage/`, `node_modules/`), so "git ignores it" would have
+ * silenced a typo in a `docs/specs/…` citation forever — in the very check
+ * whose subject is "ships in the tarball, target missing".
+ *
  * ## Why
  *
  * Prose is not executed. A skill body that tells the coordinator to run
@@ -98,14 +108,60 @@
  * @module scripts/lib/validate/check-skill-script-paths
  */
 
+import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { enumerateRepoFiles } from './enumerate-repo-files.mjs';
 import { forEachLine } from './markdown-fences.mjs';
 import { isMainModule } from '../is-main-module.mjs';
 
-/** Documentation roots whose prose is treated as a claim about the repo. */
-export const SCAN_DIRS = Object.freeze(['skills', 'commands', 'agents', 'docs']);
+/**
+ * Documentation roots whose prose is treated as a claim about the repo.
+ *
+ * `.claude/rules` and `.cursor/rules` joined in #1384 P3. Both are instruction
+ * corpora loaded by every session, and both cite repo paths in backticks with
+ * exactly the grammar {@link MARKDOWN_CITATION_RE} already judges — but until
+ * this widening neither had a gate. The real incident:
+ * `.cursor/rules/010-session-workflow.mdc` kept citing `commands/go.md` and
+ * `commands/close.md` after `3ebf0e9d` folded those files into their skills,
+ * and that surface SHIPS (npm tarball, symlinked into consumer repos by
+ * `scripts/cursor-install.mjs`). Same widening, mirrored in
+ * `check-skill-links.mjs` § SCAN_DIRS.
+ *
+ * `rules` and `output-styles` joined in #1384 P3 for the same reason one step
+ * further out: both are in `package.json` `files[]`, so both SHIP to every
+ * consumer, and neither had a gate. The census that motivated it (whole-repo
+ * probe, 2026-09-18 @ 20a4cbff) found 6 dangling citations across them —
+ * `output-styles/wave-summary.md` cited `hooks/on-stop.sh` for a file that has
+ * been `.mjs` for two migrations, and `rules/opt-in-stack/*` cited
+ * consumer-side example paths with no marker.
+ *
+ * `CHANGELOG.md` stays OUT, and root files are not a scan root at all: a
+ * changelog cites the paths a release TOUCHED, so a path deleted afterwards is
+ * still a correct historical statement — 88 such hits, all correct by
+ * construction. Annotating them would be noise on every future entry.
+ */
+export const SCAN_DIRS = Object.freeze([
+  'skills',
+  'commands',
+  'agents',
+  'docs',
+  'rules',
+  'output-styles',
+  '.claude/rules',
+  '.cursor/rules',
+]);
+
+/**
+ * Extensions treated as instruction markdown.
+ *
+ * `.mdc` is Cursor's own rule extension and is the ONLY reason `.cursor/rules`
+ * is scannable at all: every file there is `<nnn>-<name>.mdc`, so a `.md`-only
+ * filter would have added the directory to {@link SCAN_DIRS} and enumerated
+ * zero files — a widening that looks live and checks nothing. Same constant,
+ * same reason, as `check-skill-links.mjs` § MD_EXTENSIONS.
+ */
+export const MD_EXTENSIONS = Object.freeze(['.md', '.mdc']);
 
 /**
  * A cited script path. One regex, one alternation, reused for every
@@ -114,8 +170,35 @@ export const SCAN_DIRS = Object.freeze(['skills', 'commands', 'agents', 'docs'])
  * `hooks/**.sh`. `hooks/**.mjs` is deliberately NOT part of this grammar —
  * the `.mjs` half of the citation surface stays exactly `scripts/`, matching
  * every existing annotation and fence-skip test unchanged.
+ *
+ * Ceiling (BV-004, #1390 P2): the match is UNANCHORED on the left, so a path
+ * NESTED under another directory is read from its `scripts/` / `hooks/`
+ * segment onward. `templates/shared/hooks/check-csp-single-source.sh` is judged
+ * as `hooks/check-csp-single-source.sh` — a path nobody cited. That cuts both
+ * ways: a finding names the truncated tail (fail-closed noise), and a nested
+ * path whose tail HAPPENS to exist at the repo root passes although the cited
+ * file is missing (fail-open).
+ *
+ * A lookbehind cannot tell the two readings apart, because the character
+ * before the tail is `/` in both: `templates/shared/hooks/…` is a real
+ * subdirectory, while `$PLUGIN_ROOT/scripts/…`, `${CLAUDE_PLUGIN_ROOT}/…`,
+ * `../../scripts/…` and `…/blob/main/hooks/…` all resolve to the plugin root,
+ * so their tail IS the right repo-rooted path. Only the prefix token's meaning
+ * differs, and the regex cannot evaluate a variable. Measured 2026-09-19 @
+ * 8f6ac022 (prose lines of every SCAN_DIRS file, fences skipped — `forEachLine`
+ * + this regex, the character before each hit): 1505 hits in 351 files, 42
+ * preceded by `/` — 16 variable-rooted, 21 relative, 5 literal, and of those
+ * five exactly ONE is a genuine nested directory (the CSP hook above, in
+ * `rules/opt-in-stack/security-web.md`). A `(?<![\w./}-])` guard would drop 37
+ * correctly-judged citations to fix one.
+ *
+ * Escape hatch until then: the nested citation carries
+ * `<!-- path-check: example -->` (or `planned #<iid>`), which the one live
+ * occurrence already does. Revisit when a second real nested-path citation
+ * appears that the annotation cannot reasonably cover — then the grammar needs
+ * a list of known plugin-root prefixes, not a lookbehind.
  */
-const CITATION_RE = /scripts\/[a-zA-Z0-9_/-]*\.(?:mjs|sh)|hooks\/[a-zA-Z0-9_/-]*\.sh/g;
+const CITATION_RE =/scripts\/[a-zA-Z0-9_/-]*\.(?:mjs|sh)|hooks\/[a-zA-Z0-9_/-]*\.sh/g;
 
 /**
  * A complete inline-code span, including spans delimited by multiple backticks.
@@ -166,6 +249,107 @@ export function isPlaceholderCitation(citedPath) {
   return PLACEHOLDER_FRAGMENTS.some((fragment) => lower.includes(fragment));
 }
 
+/**
+ * The per-harness STATE roots. A missing citation may be excused as a runtime
+ * artefact ONLY from inside one of these — and only when git also ignores it
+ * (see {@link isRuntimeArtifact}).
+ *
+ * Each is a harness's own session-state directory: `.orchestrator/` (this
+ * plugin's ledgers, locks and metrics), plus the four harness mirrors that
+ * carry a per-session `STATE.md` / `wave-scope.json` / `filescopes/` —
+ * `.claude/`, `.codex/`, `.cursor/` (all three gitignored file-by-file in this
+ * repo's `.gitignore`) and `.pi/` (`skills/_shared/platform-tools.md` § Pi;
+ * absent from this checkout, listed so the Pi harness is covered wherever the
+ * plugin is installed).
+ *
+ * Ceiling (BV-004): exactly these five prefixes, and ONLY in conjunction with
+ * the git test. `.gitignore` here also declines to track real, hand-authored
+ * documents that simply do not ship (`docs/specs/`, `docs/_private/`) and
+ * whole build outputs (`coverage/`, `node_modules/`) — a typo in a
+ * `docs/specs/…` citation is a defect this check exists to catch, so those
+ * must keep REPORTING. Revisit when a harness adds a sixth state root, or
+ * when a state root stops being a dot-directory at the repo root.
+ */
+export const RUNTIME_STATE_PREFIXES = Object.freeze([
+  '.orchestrator/',
+  '.claude/',
+  '.codex/',
+  '.cursor/',
+  '.pi/',
+]);
+
+/**
+ * Does `citedPath` live under a harness state root?
+ *
+ * Necessary but NOT sufficient for the runtime-artefact carve-out — the git
+ * test in {@link gitIgnoredPaths} is the second half. `.claude/rules/x.md` is
+ * under a state root and TRACKED, so it still reports.
+ *
+ * @param {string} citedPath repo-relative POSIX path
+ * @returns {boolean}
+ */
+export function isRuntimeStatePath(citedPath) {
+  return RUNTIME_STATE_PREFIXES.some((prefix) => citedPath.startsWith(prefix));
+}
+
+/**
+ * Which of `candidates` git IGNORES — one half of the runtime-artefact test
+ * (the other is {@link isRuntimeStatePath}).
+ *
+ * The rules corpora widened into by #1384 P3 cite paths that never exist in a
+ * checkout and are not supposed to: `.cursor/STATE.md`, `.orchestrator/…`
+ * ledgers, per-session state files. Rather than a hand-kept name list (which
+ * would rot the moment a new ledger is added, and which nothing measures), the
+ * test is MECHANICAL and matches the repo's own definition: a path the
+ * repository declines to track, which does not exist, is by construction
+ * written at runtime — so there is nothing for a citation gate to catch.
+ *
+ * That predicate alone is too wide, which is why the prefix half exists: "git
+ * ignores it" and "it is written at runtime" are not the same claim. Measured
+ * 2026-09-18, `gitIgnoredPaths` matched `docs/specs/foo.md`,
+ * `docs/_private/x.md`, `coverage/report.md` and `node_modules/x/y.mjs` just
+ * as readily as `.orchestrator/metrics/events.jsonl` — real local documents
+ * whose dead citations this check must still report.
+ *
+ * ONE `git check-ignore --stdin` for the whole run, never one per path: the
+ * corpus carries hundreds of citations and a per-path spawn would dominate the
+ * check's runtime.
+ *
+ * Fails OPEN toward REPORTING (the safe direction here): a missing `git`, a
+ * non-git root, or exit 128 yields an empty set, so every absent citation is
+ * still reported and no real defect is suppressed by a tooling failure. Exit 1
+ * means "none of them are ignored" and is NOT an error.
+ *
+ * @param {string} repoRoot absolute repo root
+ * @param {string[]} candidates repo-relative POSIX paths (already known absent)
+ * @returns {Set<string>} the subset git ignores
+ */
+export function gitIgnoredPaths(repoRoot, candidates) {
+  const unique = [...new Set(candidates)].filter((p) => p.length > 0 && !p.includes('\n'));
+  if (unique.length === 0) return new Set();
+  let stdout;
+  try {
+    stdout = execFileSync('git', ['check-ignore', '--stdin'], {
+      cwd: repoRoot,
+      input: `${unique.join('\n')}\n`,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'ignore'],
+      maxBuffer: 8 * 1024 * 1024,
+    });
+  } catch (error) {
+    // Exit 1 = nothing matched, and git still wrote (empty) stdout. Anything
+    // else (128, ENOENT, non-git root) leaves `stdout` undefined → empty set.
+    if (error?.status !== 1) return new Set();
+    stdout = typeof error.stdout === 'string' ? error.stdout : '';
+  }
+  return new Set(
+    String(stdout)
+      .split('\n')
+      .map((line) => line.trim())
+      .filter(Boolean),
+  );
+}
+
 /** The annotation marker, in any of its three classes. */
 const ANNOTATION_RE = /<!--\s*path-check:\s*([^>]*?)\s*-->/;
 
@@ -274,10 +458,20 @@ export function scanSkillScriptPaths({ pluginRoot, dirs = SCAN_DIRS, strictSh =
     existing: 0,
     annotated: 0,
     placeholders: 0,
+    runtimeArtifacts: 0,
     findings: 0,
     warnings: 0,
   };
 
+  /**
+   * Citations that are absent AND unannotated — judged only after the corpus
+   * loop, when the single `git check-ignore` call can separate a dead
+   * reference from a path written at runtime.
+   *
+   * @type {{file: string, citation: {line: number, path: string}}[]}
+   */
+  const pending = [];
+
   /** @type {string[]} */
   let files;
   try {
@@ -290,7 +484,7 @@ export function scanSkillScriptPaths({ pluginRoot, dirs = SCAN_DIRS, strictSh =
     // honours `.gitignore`, so the #1143 exposure a bare `readdirSync` walk
     // would reintroduce (a worktree under `.claude/worktrees/`, gitignored
     // `docs/specs/*.md`) stays closed — see that module's header.
-    files = enumerateRepoFiles({ repoRoot: pluginRoot, dirs, exts: ['.md'] });
+    files = enumerateRepoFiles({ repoRoot: pluginRoot, dirs, exts: MD_EXTENSIONS });
   } catch (error) {
     findings.push({
       kind: 'tool-error',
@@ -389,30 +583,48 @@ export function scanSkillScriptPaths({ pluginRoot, dirs = SCAN_DIRS, strictSh =
       }
       if (marker && !marker.ok) continue; // already reported as bad-annotation
 
-      // `.mjs` and `.md` are blocking.
-      // `.sh` is advisory (`warn`) unless the caller opted into `strictSh`.
-      const isSh = path.extname(citation.path) === '.sh';
-      const severity = isSh && !strictSh ? 'warn' : 'fail';
-      if (severity === 'warn') summary.warnings += 1;
-      findings.push({
-        kind: 'missing-path',
-        file: relative,
-        line: citation.line,
-        path: citation.path,
-        annotation: null,
-        message:
-          (isSh
-            ? severity === 'warn'
-              ? `\`${citation.path}\` does not exist (advisory — .sh citations do not block ` +
-                'validate-plugin until re-run with --strict-sh; see #1187) — '
-              : `\`${citation.path}\` does not exist (--strict-sh) — `
-            : `\`${citation.path}\` does not exist — `) +
-          'create it, fix the path, or annotate the citation with ' +
-          '`<!-- path-check: planned #<iid> | historical | example -->` on this line or the ' +
-          'line directly above',
-        severity,
-      });
+      // Deferred, not reported yet: the runtime-artefact test below needs ONE
+      // `git check-ignore` for the whole corpus, not one per citation.
+      pending.push({ file: relative, citation });
+    }
+  }
+
+  // BOTH halves, never one: under a harness state root AND untracked by git.
+  // Only state-root candidates are even offered to git, so the subprocess
+  // shrinks to the paths that could possibly qualify.
+  const ignored = gitIgnoredPaths(
+    pluginRoot,
+    pending.map((p) => p.citation.path).filter(isRuntimeStatePath),
+  );
+
+  for (const { file: relative, citation } of pending) {
+    if (isRuntimeStatePath(citation.path) && ignored.has(citation.path)) {
+      summary.runtimeArtifacts += 1;
+      continue;
     }
+    // `.mjs` and `.md` are blocking.
+    // `.sh` is advisory (`warn`) unless the caller opted into `strictSh`.
+    const isSh = path.extname(citation.path) === '.sh';
+    const severity = isSh && !strictSh ? 'warn' : 'fail';
+    if (severity === 'warn') summary.warnings += 1;
+    findings.push({
+      kind: 'missing-path',
+      file: relative,
+      line: citation.line,
+      path: citation.path,
+      annotation: null,
+      message:
+        (isSh
+          ? severity === 'warn'
+            ? `\`${citation.path}\` does not exist (advisory — .sh citations do not block ` +
+              'validate-plugin until re-run with --strict-sh; see #1187) — '
+            : `\`${citation.path}\` does not exist (--strict-sh) — `
+          : `\`${citation.path}\` does not exist — `) +
+        'create it, fix the path, or annotate the citation with ' +
+        '`<!-- path-check: planned #<iid> | historical | example -->` on this line or the ' +
+        'line directly above',
+      severity,
+    });
   }
 
   findings.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);

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

@@ -111,6 +111,7 @@
 import { readFileSync, readdirSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { isMainModule } from '../is-main-module.mjs';
+import { maskSource } from '../js-mask.mjs';
 
 /** Only this directory is scanned — a mutation in `scripts/` is production intent. */
 const SCAN_DIR = 'tests';
@@ -487,43 +488,24 @@ export function insideStringLiteral(body, index) {
  * "no cwd" measured as a cwd. `inCommentLine` cannot serve here: it answers a
  * question about a whole LINE, while this one runs inside a call expression.
  *
+ * Delegates to the shared lexer {@link maskSource} in `keepLiterals` mode
+ * (#1388). The hand-rolled walker this replaced had no REGEX-LITERAL branch,
+ * so a call tail carrying one — measured 2026-09-18:
+ * `wrapperHasCwd(", undefined, { env: /\/*$/.source, cwd: dir }")` — read the
+ * regex's `/*` as a block-comment opener, swallowed the rest of the tail and
+ * returned `false`: a false alarm from this check.
+ *
+ * One behavioural difference the callers must honour: `maskSource` blanks a
+ * comment to SPACES (length-preserving) where this function used to collapse
+ * it to a single space. {@link wrapperHasCwd} judges its second positional
+ * textually against `second !== ''`, so that difference was checked rather
+ * than assumed — see the measurement recorded at that test.
+ *
  * @param {string} text
- * @returns {string} same length semantics, comments blanked to one space
+ * @returns {string} same length, comment bytes blanked to spaces
  */
 export function stripComments(text) {
-  let out = '';
-  /** @type {string|null} */
-  let quote = null;
-  for (let i = 0; i < text.length; i += 1) {
-    const ch = text[i];
-    if (quote !== null) {
-      out += ch;
-      if (ch === '\\') {
-        out += text[i + 1] ?? '';
-        i += 1;
-      } else if (ch === quote) quote = null;
-      continue;
-    }
-    if (ch === "'" || ch === '"' || ch === '`') {
-      quote = ch;
-      out += ch;
-      continue;
-    }
-    if (ch === '/' && text[i + 1] === '*') {
-      const end = text.indexOf('*/', i + 2);
-      i = end === -1 ? text.length : end + 1;
-      out += ' ';
-      continue;
-    }
-    if (ch === '/' && text[i + 1] === '/') {
-      const end = text.indexOf('\n', i);
-      i = end === -1 ? text.length : end - 1;
-      out += ' ';
-      continue;
-    }
-    out += ch;
-  }
-  return out;
+  return maskSource(text, { keepLiterals: true });
 }
 
 /**
@@ -549,6 +531,14 @@ export function wrapperHasCwd(tail) {
   const clean = stripComments(tail);
   const m = /^\s*,\s*/.exec(clean);
   if (m) {
+    // NO `.trim()` here, and that is measured rather than assumed (#1388): the
+    // shared lexer blanks a comment to SPACES where the local stripper used to
+    // delete it, so a comment-only tail LOOKS like it would arrive as truthy
+    // whitespace. It cannot — the `\s*` above is greedy and consumes every
+    // blanked byte, leaving `second === ''`. Measured 2026-09-18 over
+    // `, /* no cwd */`, `, /* a */ /* b */`, `,\n // note\n`,
+    // `, /* x */ undefined`, `, undefined /* y */`: all `false`, `, /* c */ dir`
+    // → `true`. A `.trim()` would be dead code; the case is pinned by a test.
     const second = clean.slice(m[0].length);
     if (second !== '' && !/^(?:undefined|null)\b/.test(second) && !/^,/.test(second)) return true;
   }

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

@@ -108,6 +108,13 @@ 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)
 // ---------------------------------------------------------------------------