session-orchestrator 5.2.0 → 5.4.0

package/scripts/lib/validate/check-learnings-shell-writes.mjs

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+/**
+ * Check: no instruction prose tells an agent to write `learnings.jsonl` with a
+ * shell redirect (GitLab #1446 / GitHub #69). BLOCKING.
+ *
+ * ## Why
+ *
+ * The store is gitignored, so a bad write has no VCS restore. The sanctioned
+ * write paths — `scripts/apply-session-learnings.mjs` (session-end, retro) and
+ * `scripts/sweep-expired-learnings.mjs --prune` (`/evolve`) — validate every
+ * record, snapshot `.bak-<ISO>`, and archive what leaves the store. A shell
+ * `>` / `>>` does none of that. The prose producers this change closed, all
+ * measured at ebf63bd1:
+ *
+ *   - `skills/session-end/learning-patterns.md` Phase 3.6 step 4g ("atomic
+ *     rewrite with `>`") — the path that wrote a file PATH into `scope` (GH#69);
+ *   - `skills/plan/mode-retro.md` § 3.3 — an unnamed "Append new patterns to
+ *     `learnings.jsonl`" with no mechanism at all;
+ *   - `.cursor/rules/060-evolve.mdc` — three sites ("Write entire result back
+ *     with `>`", "write all with `>`" twice). None of the three names
+ *     `learnings.jsonl` on its own line, which is why R2 is windowed.
+ *
+ * ## Rules
+ *
+ *   R1 shell redirect  — `>`/`>>` directly in front of a `…learnings.jsonl`
+ *                        target on the same line. The leading boundary (start,
+ *                        whitespace, `|`, `;`, `&`, `(`) is load-bearing:
+ *                        without it 9 of 12 hits were `<state-dir>/…`
+ *                        placeholders. A Markdown blockquote marker (`> ` at
+ *                        line start, outside a fence) is not a redirect and is
+ *                        stripped first; inside a fence it IS a truncation.
+ *   R3 tee             — `tee [-a] …learnings.jsonl` on the same line.
+ *   R2 prose operator  — a backticked `` `>` `` / `` `>>` `` within ±3 lines
+ *                        (WINDOW) of an anchor: `learnings.jsonl`, "the store",
+ *                        "learnings store", "result back", "atomic rewrite".
+ *                        The last two are the retired producers' own wording.
+ *                        An operator inside an ASCII double-quoted span is a
+ *                        quotation of former prose, not an instruction.
+ *
+ * Exempt (per operator): a prohibition keyword (NEVER / do not / FORBIDDEN /
+ * verboten …) BEFORE the operator in the same sentence — a keyword after it
+ * (`… > learnings.jsonl # never run this twice`) or in an earlier sentence
+ * (`Never skip review. Then run: … >> learnings.jsonl`) does not count.
+ * Exempt (whole line): the last sentence of the previous non-empty line states
+ * a prohibition before any operator, an empty-file create (`: > file`), or the
+ * marker `<!-- learnings-write-check: prohibition -->` on the line or the
+ * previous non-empty line. Fenced blocks ARE scanned — a fenced shell snippet
+ * is exactly a shell write.
+ *
+ * @module scripts/lib/validate/check-learnings-shell-writes
+ */
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { enumerateRepoFiles } from './enumerate-repo-files.mjs';
+import { isMainModule } from '../is-main-module.mjs';
+
+/** Instruction corpora that tell an agent what to run. */
+export const SCAN_DIRS = Object.freeze(['skills', 'commands', 'agents', 'docs', '.claude/rules', '.cursor/rules']);
+
+/** Lines on either side of an R2 operator searched for an anchor. */
+const WINDOW = 3;
+
+const MENTION_RE = /learnings\.jsonl/;
+const ANCHOR_RE = /learnings\.jsonl|\b(?:the|learnings) store\b|\bresult back\b|\batomic rewrite\b/i;
+const SHELL_REDIRECT_RE = /(?:^|[\s|;&(])(>{1,2})[ \t]*["'`]?[^\s"'`<>]*learnings\.jsonl\b/dg;
+const TEE_RE = /\btee\b(?:[ \t]+-{1,2}[\w-]+)*[ \t]+["'`]?[^\s"'`|]*learnings\.jsonl\b/g;
+const PROSE_OPERATOR_RE = /`>{1,2}`/g;
+const ANY_OPERATOR_RE = /`>{1,2}`|(?:^|[\s|;&(])>{1,2}|\btee\b/;
+const PROHIBITION_RE = /\b(NEVER|[Nn]ever|DO NOT|[Dd]o not|[Dd]on't|FORBIDDEN|forbidden|verboten)\b/;
+// A sentence ends at `.`/`!`/`?` + whitespace + a capital (markup allowed):
+// `jq . next` and `jq | ... >` are not sentence breaks.
+const SENTENCE_BREAK_RE = /[.!?]\s+(?=[*_`"']*[A-Z])/;
+const EMPTY_CREATE_RE = /^\s*:\s*>/;
+const BLOCKQUOTE_RE = /^\s*(?:>[ \t])+/;
+const FENCE_RE = /^\s*(?:```|~~~)/;
+const MARKER = '<!-- learnings-write-check: prohibition -->';
+
+/** The sentence a position sits in, cut off at that position. */
+function clauseBefore(text, pos) {
+  return text.slice(0, pos).split(SENTENCE_BREAK_RE).pop();
+}
+
+/** True when a prohibition keyword precedes `pos` within its own sentence. */
+function prohibitedBefore(text, pos) {
+  return PROHIBITION_RE.test(clauseBefore(text, pos));
+}
+
+/** True when the last sentence of `line` states a prohibition before any operator. */
+function isProhibitionSentence(line) {
+  const last = line.replace(BLOCKQUOTE_RE, '').trimEnd().split(SENTENCE_BREAK_RE).pop();
+  const k = last.search(PROHIBITION_RE);
+  if (k < 0) return false;
+  const o = last.search(ANY_OPERATOR_RE);
+  return o < 0 || k < o;
+}
+
+/** True when `pos` sits inside an ASCII double-quoted span of `text`. */
+function insideDoubleQuotes(text, pos) {
+  return (text.slice(0, pos).match(/"/g) ?? []).length % 2 === 1;
+}
+
+/**
+ * Every operator on the line as `{rule, pos}`, positions relative to `body`.
+ * R2 candidates are returned only when the ±WINDOW neighbourhood holds an anchor.
+ */
+function operatorsOf(body, lines, i) {
+  const ops = [];
+  if (MENTION_RE.test(body)) {
+    for (const m of body.matchAll(SHELL_REDIRECT_RE)) ops.push({ rule: 'R1', pos: m.indices[1][0] });
+    for (const m of body.matchAll(TEE_RE)) ops.push({ rule: 'R3', pos: m.index });
+  }
+  const prose = [...body.matchAll(PROSE_OPERATOR_RE)];
+  if (prose.length > 0) {
+    const from = Math.max(0, i - WINDOW);
+    const anchored = lines.slice(from, i + WINDOW + 1).some((l) => ANCHOR_RE.test(l));
+    if (anchored) {
+      for (const m of prose) {
+        if (!insideDoubleQuotes(body, m.index)) ops.push({ rule: 'R2', pos: m.index });
+      }
+    }
+  }
+  return ops;
+}
+
+/**
+ * Scan the instruction corpora for shell writes to `learnings.jsonl`.
+ *
+ * @param {{ pluginRoot: string, dirs?: readonly string[] }} opts
+ * @returns {{ ok: boolean, findings: {file: string, line: number, rule: string, text: string}[],
+ *   summary: { filesScanned: number, mentions: number, exempt: number } }}
+ */
+export function scanLearningsShellWrites({ pluginRoot, dirs = SCAN_DIRS }) {
+  const files = enumerateRepoFiles({ repoRoot: pluginRoot, dirs: [...dirs], exts: ['.md', '.mdc'] });
+  const findings = [];
+  let mentions = 0;
+  let exempt = 0;
+  for (const abs of files) {
+    const lines = readFileSync(abs, 'utf8').split('\n');
+    const rel = path.relative(pluginRoot, abs);
+    let inFence = false;
+    let prev = '';
+    lines.forEach((text, i) => {
+      const prevNonEmpty = prev;
+      if (text.trim().length > 0) prev = text;
+      if (FENCE_RE.test(text)) {
+        inFence = !inFence;
+        return;
+      }
+      if (MENTION_RE.test(text)) mentions += 1;
+      const body = inFence ? text : text.replace(BLOCKQUOTE_RE, '');
+      const ops = operatorsOf(body, lines, i);
+      if (ops.length === 0) return;
+      const lineExempt =
+        EMPTY_CREATE_RE.test(body) ||
+        text.includes(MARKER) ||
+        prevNonEmpty.includes(MARKER) ||
+        isProhibitionSentence(prevNonEmpty);
+      const failing = lineExempt ? [] : ops.filter((op) => !prohibitedBefore(body, op.pos));
+      if (failing.length === 0) {
+        exempt += 1;
+        return;
+      }
+      const rule = ['R1', 'R3', 'R2'].find((r) => failing.some((op) => op.rule === r));
+      findings.push({ file: rel, line: i + 1, rule, text: text.trim() });
+    });
+  }
+  return { ok: findings.length === 0, findings, summary: { filesScanned: files.length, mentions, exempt } };
+}
+
+const RULE_TEXT = Object.freeze({
+  R1: 'shell redirect into learnings.jsonl',
+  R2: 'redirect operator near a learnings.jsonl / store-write mention',
+  R3: 'tee into learnings.jsonl',
+});
+
+/**
+ * Run the human-readable validator CLI.
+ *
+ * @param {string} pluginRoot absolute plugin root
+ * @returns {number} 0 = clean, 1 = findings
+ */
+export function runCheckLearningsShellWrites(pluginRoot) {
+  console.log('--- Check: no shell-redirect writes to learnings.jsonl in instruction prose ---');
+  const inspection = scanLearningsShellWrites({ pluginRoot });
+  for (const f of inspection.findings) {
+    console.log(
+      `  FAIL: [${f.rule}] ${f.file}:${f.line} ${RULE_TEXT[f.rule]} — route the write through ` +
+        '`scripts/apply-session-learnings.mjs` or `sweep-expired-learnings.mjs --prune`',
+    );
+  }
+  const s = inspection.summary;
+  if (inspection.ok) {
+    console.log(
+      `  PASS: ${s.mentions} learnings.jsonl mention(s) in ${s.filesScanned} file(s), ` +
+        `${s.exempt} exempt as prohibition`,
+    );
+  }
+  console.log('');
+  console.log(`Results: ${inspection.ok ? 1 : 0} passed, ${inspection.findings.length} failed`);
+  return inspection.ok ? 0 : 1;
+}
+
+if (isMainModule(import.meta.url)) {
+  const args = process.argv.slice(2).filter((arg) => arg !== '--json');
+  const root = path.resolve(args[0] || process.cwd());
+  if (process.argv.includes('--json')) {
+    const inspection = scanLearningsShellWrites({ pluginRoot: root });
+    process.stdout.write(`${JSON.stringify(inspection, null, 2)}\n`);
+    process.exitCode = inspection.ok ? 0 : 1;
+  } else {
+    process.exitCode = runCheckLearningsShellWrites(root);
+  }
+}

package/scripts/lib/validate/check-pi-prompts.mjs

@@ -35,6 +35,7 @@ if (!existsSync(generator)) {
   } else {
     const detail = ((result.stdout ?? '') + (result.stderr ?? '')).trim();
     fail(`pi prompt wrappers are stale${detail ? `: ${detail}` : ''}`);
+    console.log('        Remedy: node scripts/generate-pi-prompts.mjs');
   }
 }
 

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

@@ -60,9 +60,9 @@
 //           Order and duplicates are irrelevant (a glob list is matched
 //           any-of), so the comparison is over the sorted unique set.
 //           NOT flagged: `paths:` alone. It is the form the native
-//           documentation prescribes and the form the primary downstream
-//           consumer uses exclusively (projects-baseline: 26 rule files, all
-//           `paths:`, 0 `globs:` — rule-loader.mjs module doc). The
+//           documentation prescribes, and the primary downstream consumer
+//           (projects-baseline) carries `paths:` on every scoped rule —
+//           measured count: docs/baseline.md. The
 //           `globs:`-is-canonical preference for VENDORED rules is a separate,
 //           warn-level concern already owned by
 //           scripts/lib/validate-vendored-rules.mjs (~:289, issue #742) and is
@@ -330,8 +330,10 @@ for (const name of mdFiles.sort()) {
         '("rules without a paths field are loaded unconditionally and apply to all files" — ' +
         'code.claude.com/docs/en/memory § Path-specific rules). `globs:` is the Cursor field name, so this rule ' +
         'is scoped for rule-loader.mjs and Cursor but loads ALWAYS-ON in Claude Code — a silent instruction-budget ' +
-        'failure (#1108). Add a paths: key carrying the same patterns as globs: (keep globs: — it stays the ' +
-        'canonical form for vendored rules, validate-vendored-rules.mjs #742).',
+        'failure (#1108). Add a paths: key carrying the same patterns as globs:. Under .claude/rules/ paths: is ' +
+        'the canonical scope key (docs/rule-authoring.md) — keep globs: alongside it only if this rule is ALSO ' +
+        'vendored out through rules/, where globs: is the vendored form (#742); otherwise paths: alone is enough ' +
+        'and globs: can be dropped.',
     );
   } else if (!parity.ok && parity.kind === 'divergent') {
     fail(

package/scripts/lib/validate/check-skill-links.mjs

@@ -62,7 +62,15 @@ import { isMainModule } from '../is-main-module.mjs';
  * and 0 checked links today and would NOT by itself have caught that defect — those citations are
  * INLINE-CODE (`` `commands/go.md` ``), which this checker deliberately skips (see DELIBERATE
  * NON-CHECKS). It is a forward guard for the day a real link is authored there, not the catcher
- * for the backticked-citation class; that class has no gate in this repo (recorded, not assumed).
+ * for the backticked-citation class.
+ *
+ * That last clause read "and that class has no gate in this repo" until #1384 P3, when it stopped
+ * being true: `check-skill-script-paths.mjs` — which DOES judge complete inline-code spans against
+ * `MARKDOWN_CITATION_RE` — took the same two roots and `.mdc` into its own `SCAN_DIRS`, and is
+ * blocking via `scripts/validate-plugin.mjs`. Measured 2026-09-18: its corpus went 295 → 329 files
+ * and it reported the `commands/{go,close}.md` class of defect (4 blocking findings on first run).
+ * So the division of labour is: LINKS here, backticked CITATIONS there — neither surface is
+ * ungated.
  */
 export const SCAN_DIRS = Object.freeze(['skills', 'commands', 'agents', '.claude/rules', 'docs', '.cursor/rules']);
 

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);