session-orchestrator 3.24.0 → 4.0.0

package/scripts/lib/validate/check-owner-leakage.mjs

@@ -81,11 +81,12 @@
  *   1 — at least one failure (or usage error / unreadable root)
  */
 
-import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { readFileSync, readdirSync, statSync, existsSync, realpathSync } from 'node:fs';
 import { join, extname, relative, basename, sep, resolve } from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { argv } from 'node:process';
 import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
 // NOTE: the two host-local helper modules (../config/host-paths.mjs and
 // ./confidential-names.mjs) are imported DYNAMICALLY inside
 // getConfidentialNamePatterns(), NOT statically here. This scanner is a
@@ -93,7 +94,9 @@ import { fileURLToPath } from 'node:url';
 // "Reuse the same scanner") — the .husky/pre-commit E2E and any consumer that
 // copies ONLY this file into a fresh tree would otherwise crash at module load
 // with ERR_MODULE_NOT_FOUND, blocking clean commits. Dynamic import lets CP11 go
-// silently inert when the helpers are absent while CP1–CP10 run unchanged.
+// inert (one WARN line, exit unchanged) when the helpers are absent while CP1–CP10
+// run unchanged. That degrade is scoped to ERR_MODULE_NOT_FOUND ALONE (#1244) —
+// every other CP11 load failure fails CLOSED; see getConfidentialNamePatterns().
 
 // ---------------------------------------------------------------------------
 // CLI / import-mode detection (#661)
@@ -103,7 +106,25 @@ import { fileURLToPath } from 'node:url';
 // AND an importable library (the canonicalization helpers are unit-tested in
 // isolation). When imported, the top-level scan + process.exit() must NOT run.
 // `isMain` is true only when this file is the node entry point.
-const isMain = argv[1] !== undefined && resolve(argv[1]) === fileURLToPath(import.meta.url);
+// REALPATH BOTH SIDES (#1244 / same class as the #1153 argv[1] main-guard finding).
+// `fileURLToPath(import.meta.url)` is already canonicalized by Node's ESM loader,
+// so a plain `resolve(argv[1])` comparison silently fails whenever the invocation
+// path traverses a symlink — on macOS every `/tmp/...` path does (`/tmp` →
+// `/private/tmp`). The failure mode is the worst one a security guard has: isMain
+// stays false, runScan() never runs, and the process prints NOTHING and exits 0,
+// i.e. a clean-looking pass that never scanned a byte. realpathSync both sides so
+// the two spellings of the same file compare equal; if realpathSync throws (path
+// gone, permission denied) fall back to the historical comparison.
+function canonicalPath(p) {
+  try {
+    return realpathSync(p);
+  } catch {
+    return p;
+  }
+}
+const isMain =
+  argv[1] !== undefined &&
+  canonicalPath(resolve(argv[1])) === canonicalPath(fileURLToPath(import.meta.url));
 
 // CLI: single positional arg required (only enforced when run directly).
 const pluginRoot = argv[2];
@@ -568,8 +589,10 @@ function escapeRegex(s) {
 // its cases red (#974).
 //
 // The dynamic-import degrade used by getConfidentialNamePatterns() is NOT
-// available here. That helper degrades to `[]` — CP11 goes inert, CP1–CP10 keep
-// running, nothing leaks. A failed REDACTION has the opposite failure direction:
+// available here. That helper degrades to `[]` for the standalone-copy case alone
+// — CP11 goes inert, CP1–CP10 keep running, nothing leaks (every OTHER load
+// failure there is now a counted FAIL, #1244). A failed REDACTION has the opposite
+// failure direction:
 // it prints confidential names verbatim into a PUBLIC GitHub-Actions log, which
 // is precisely the exposure this function exists to prevent (Fix 1 below). The
 // redaction sink must be unconditionally present, so it lives inline.
@@ -645,6 +668,78 @@ function redactSpans(line, patterns) {
   return out;
 }
 
+/**
+ * The THREE modules getConfidentialNamePatterns() imports directly, as absolute
+ * URLs resolved against THIS file. Used only to classify an ERR_MODULE_NOT_FOUND:
+ * `err.url` carries the URL of the module that could not be found (measured on
+ * Node 24 — a relative specifier yields `url`, a bare package specifier yields
+ * none), so a miss on one of these three is the standalone single-file copy,
+ * while a miss anywhere DEEPER (a transitive of an in-tree helper, or a bare
+ * package) is a broken install that must fail CLOSED rather than go inert.
+ */
+const CP11_DIRECT_SIBLING_URLS = new Set(
+  ['../config/host-paths.mjs', './confidential-names.mjs', '../owner-yaml.mjs'].map(
+    (spec) => new URL(spec, import.meta.url).href,
+  ),
+);
+
+/**
+ * True when an ERR_MODULE_NOT_FOUND names one of this scanner's own three DIRECT
+ * helper imports — i.e. the documented standalone-vendoring shape. False for a
+ * transitive relative module or a bare package (no `err.url` at all), which is a
+ * broken in-tree install: CP11 then fails closed instead of silently returning
+ * zero patterns while names ARE configured.
+ *
+ * @param {{ url?: string }} err
+ * @returns {boolean}
+ */
+function isMissingDirectSibling(err) {
+  return typeof err?.url === 'string' && CP11_DIRECT_SIBLING_URLS.has(err.url);
+}
+
+/**
+ * Was `paths.confidential-names-file` actually written into owner.yaml?
+ *
+ * WHY THIS RE-READS THE FILE. `loadOwnerConfig()` reports an invalid OPTIONAL
+ * section only as `droppedSections: [{ section: 'paths', errors }]` and replaces
+ * `config.paths` with the DEFAULTS — the raw keys of the dropped section are not
+ * recoverable from its return value, and its `errors[]` name a key only for the
+ * per-key `paths.<key> must be a string` case (a `paths: 42` shape names none).
+ * So the one question CP11's verdict turns on — did the operator configure a
+ * names file AT ALL — has no answer in the loader's contract today. Re-parsing
+ * the file for that single key is the minimal derivation; widening the loader's
+ * return shape would touch every one of its callers.
+ *
+ * Only reached when the YAML already parsed once inside loadOwnerConfig (the
+ * dropped-section branch implies that), so `js-yaml` is resolvable here; 'unknown'
+ * is the defensive residue and makes the caller fail closed.
+ *
+ * Returns a CLASS, never the value: the configured path is host-local and this
+ * scanner's output is captured by a PUBLIC CI mirror (see the no-path rule above).
+ *
+ * @param {string} ownerYamlPath
+ * @returns {'configured'|'absent'|'unknown'}
+ */
+function rawConfidentialNamesKeyState(ownerYamlPath) {
+  let parsed;
+  try {
+    const yaml = createRequire(import.meta.url)('js-yaml');
+    parsed = yaml.load(readFileSync(ownerYamlPath, 'utf8'));
+  } catch {
+    return 'unknown';
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return 'unknown';
+  const paths = parsed.paths;
+  // `paths:` absent, null, or not a mapping at all → the key cannot be in there.
+  if (paths === null || typeof paths !== 'object' || Array.isArray(paths)) return 'absent';
+  const value = paths['confidential-names-file'];
+  if (value === undefined || value === null) return 'absent';
+  // A non-string (or empty-string) value is still an ATTEMPT to configure CP11 —
+  // except '' , which is the schema's documented "no override" spelling.
+  if (typeof value === 'string' && value.trim() === '') return 'absent';
+  return 'configured';
+}
+
 /**
  * CP11: build word-boundary, case-insensitive regexes from the host-local
  * confidential-names list (#728a). Mirrors CP6_PATTERNS (private slugs), but the
@@ -667,24 +762,167 @@ function redactSpans(line, patterns) {
  * with ERR_MODULE_NOT_FOUND. When the helpers are unresolvable (or throw), CP11
  * degrades to inert ([] patterns) and CP1–CP10 run unchanged.
  *
- * @returns {Promise<RegExp[]>} one regex per configured name, or [] when
- *   unconfigured / unusable / unresolvable (standalone copy).
+ * FAIL CLOSED WHEN CP11 WAS EXPECTED (GitLab #1244). The single bare
+ * `try { … } catch { return [] }` this function used to be conflated three
+ * outcomes that must not share a verdict, and printed `PASS` for all three:
+ *   (a) the helpers are unresolvable — the STANDALONE single-file copy. The
+ *       intended degrade, and the ONLY one: inert + one WARN line, exit unchanged.
+ *   (b) CP11 is not configured at all (no names file, no env) — the ~99% default:
+ *       inactive, silent, PASS. Unchanged. This INCLUDES an owner.yaml whose
+ *       `paths:` section was dropped as invalid for some OTHER key (the #1244
+ *       fix over-reached here and failed every commit on such a host): the raw
+ *       key is re-read (rawConfidentialNamesKeyState) and, when absent, CP11 is
+ *       INACTIVE — one WARN naming the dropped section, no FAIL, exit unchanged.
+ *   (c) CP11 IS configured — env set, a names file resolved, or the raw
+ *       `paths.confidential-names-file` key present in a `paths:` section that
+ *       was dropped as invalid — or its configuration is unknowable because
+ *       owner.yaml exists but cannot be parsed (e.g. `js-yaml` missing) — and
+ *       could not be loaded. Previously indistinguishable from (b): the scanner matched
+ *       nothing and printed `PASS: no owner-privacy leakage found`. A guard that
+ *       cannot run must say so and FAIL, never report the clean verdict it did
+ *       not earn — so this returns a `disabledReason` that runScan turns into a
+ *       `CP11 DISABLED` stderr line plus a counted FAIL (exit 1).
+ *
+ * The reason strings deliberately carry NO PATH. This scanner's stdout+stderr are
+ * captured by a PUBLIC GitHub-Actions mirror, and the confidential-names path is
+ * host-local — echoing it there would leak the very `/Users/<name>/…` shape CP1
+ * exists to block. The operator knows their own path; the CLASS of failure is what
+ * this line has to convey.
+ *
+ * @returns {Promise<{ patterns: RegExp[], disabledReason?: string, inertWarn?: string }>}
  */
 async function getConfidentialNamePatterns() {
+  let helpers;
+  try {
+    helpers = {
+      hostPaths: await import('../config/host-paths.mjs'),
+      confidentialNames: await import('./confidential-names.mjs'),
+      // Already a transitive dependency (host-paths.mjs imports it statically), so
+      // this adds no file to the standalone-copy chain the husky E2E mirrors.
+      ownerYaml: await import('../owner-yaml.mjs'),
+    };
+  } catch (err) {
+    if (err?.code === 'ERR_MODULE_NOT_FOUND' && isMissingDirectSibling(err)) {
+      // (a) standalone single-file vendoring — the documented degrade.
+      return {
+        patterns: [],
+        inertWarn: 'CP11 inert — confidential-names helpers not resolvable (standalone copy)',
+      };
+    }
+    // Any OTHER import failure is a broken in-tree install, not the vendoring case.
+    return { patterns: [], disabledReason: `confidential-names helpers failed to load (${err?.name ?? 'Error'})` };
+  }
+
   try {
-    const { loadHostPaths, resolveHostPath } = await import('../config/host-paths.mjs');
-    const { loadConfidentialNames } = await import('./confidential-names.mjs');
-    const ctx = loadHostPaths();
-    const namesPath = resolveHostPath('confidential-names-file', '', ctx);
+    const { loadHostPaths, resolveHostPath } = helpers.hostPaths;
+    const { loadConfidentialNames } = helpers.confidentialNames;
+    const { loadOwnerConfig, resolveOwnerYamlPath } = helpers.ownerYaml;
+
+    // Load owner.yaml ONCE and hand the same result to loadHostPaths, so the
+    // env>owner.yaml>default precedence is unchanged while the load's own health
+    // (reason / droppedSections) stays visible here.
+    const owner = loadOwnerConfig();
+    const namesPath = resolveHostPath('confidential-names-file', '', loadHostPaths({ ownerLoader: () => owner }));
+
+    if (typeof namesPath !== 'string' || namesPath.trim() === '') {
+      // Nothing resolves a names file. That is either (b) — genuinely
+      // unconfigured — or a state in which the answer is UNKNOWABLE because the
+      // owner.yaml that would carry it could not be read. Unknowable is (c).
+      if (existsSync(resolveOwnerYamlPath())) {
+        if (owner.reason === 'yaml-parser-missing') {
+          return {
+            patterns: [],
+            disabledReason:
+              "owner.yaml exists but 'js-yaml' is not installed, so a configured confidential-names-file cannot be resolved (run 'npm install')",
+          };
+        }
+        if (owner.reason === 'unparseable') {
+          return {
+            patterns: [],
+            disabledReason:
+              'owner.yaml exists but could not be parsed, so a configured confidential-names-file cannot be resolved',
+          };
+        }
+        if (owner.droppedSections?.some((d) => d.section === 'paths')) {
+          // The paths: section was replaced by its default because SOME key in it
+          // is invalid — which says nothing yet about whether CP11 was configured.
+          // Re-read the RAW file for that one key (the loader does not expose it on
+          // this branch; see rawConfidentialNamesKeyState) and only then decide.
+          const rawKey = rawConfidentialNamesKeyState(resolveOwnerYamlPath());
+          if (rawKey === 'configured') {
+            return {
+              patterns: [],
+              disabledReason:
+                'owner.yaml has an invalid paths: section, so a configured confidential-names-file cannot be resolved',
+            };
+          }
+          if (rawKey === 'unknown') {
+            return {
+              patterns: [],
+              disabledReason:
+                'owner.yaml has an invalid paths: section and could not be re-read, so a configured confidential-names-file cannot be ruled out',
+            };
+          }
+          // 'absent' — CP11 was never configured here. Inactive, not disabled:
+          // ONE WARN naming the dropped section, no FAIL, exit unchanged.
+          return {
+            patterns: [],
+            inertWarn:
+              'CP11 inactive — owner.yaml\'s paths: section was dropped as invalid, but it configures no confidential-names-file',
+          };
+        }
+      }
+      return { patterns: [] }; // (b) the ~99% default — inactive, silent.
+    }
+
+    // A names file IS configured. loadConfidentialNames() returns null for BOTH
+    // "unusable" and "deliberately empty list", so classify the file first — an
+    // empty list is an operator choice (inactive, silent), a missing/malformed
+    // one is (c).
+    const unusable = classifyNamesFile(namesPath);
+    if (unusable) return { patterns: [], disabledReason: unusable };
+
     const names = loadConfidentialNames({ namesPath });
-    if (!names) return [];
-    return names.map((name) => new RegExp(`\\b${escapeRegex(name)}\\b`, 'i'));
-  } catch {
-    // Helper modules absent (standalone single-file vendoring) or a config read
-    // failure — CP11 goes silently inert; the CP1–CP10 rules need none of these
-    // modules and continue to enforce the scan.
-    return [];
+    if (!names) return { patterns: [] }; // readable, well-formed, zero usable entries.
+    return { patterns: names.map((name) => new RegExp(`\\b${escapeRegex(name)}\\b`, 'i')) };
+  } catch (err) {
+    // The helpers resolved but something below threw. CP11 cannot run — fail closed.
+    return { patterns: [], disabledReason: `confidential-names resolution failed (${err?.name ?? 'Error'})` };
+  }
+}
+
+/**
+ * Classify a CONFIGURED confidential-names file as usable or not.
+ *
+ * `loadConfidentialNames()` collapses "file missing / unreadable / malformed /
+ * not an array" and "well-formed but empty" into one `null` return, which is
+ * exactly the distinction CP11's fail-closed verdict turns on. Rather than widen
+ * that module's contract (it has four other consumers of its `null`), this reads
+ * the file once more for classification only. It never returns file CONTENT — the
+ * reason string carries the error CLASS alone, matching the confidential-names
+ * privacy invariant and the no-path rule above.
+ *
+ * @param {string} namesPath
+ * @returns {string|null} a reason string when unusable, null when usable.
+ */
+function classifyNamesFile(namesPath) {
+  let raw;
+  try {
+    if (!existsSync(namesPath)) {
+      return 'a confidential-names-file is configured but does not exist';
+    }
+    raw = readFileSync(namesPath, 'utf8');
+  } catch (err) {
+    return `the configured confidential-names-file is unreadable (${err?.name ?? 'Error'})`;
+  }
+  try {
+    if (!Array.isArray(JSON.parse(raw))) {
+      return 'the configured confidential-names-file is not a JSON array';
+    }
+  } catch (err) {
+    return `the configured confidential-names-file contains malformed JSON (${err?.name ?? 'Error'})`;
   }
+  return null;
 }
 
 // ---------------------------------------------------------------------------
@@ -945,7 +1183,24 @@ const scanFiles = textFiles.filter((f) => {
 // unresolvable (standalone single-file copy) → the CP11 block below is a no-op.
 // Awaited once, before the per-line loop, because the helpers are now dynamically
 // imported (standalone-safe) — CP1–CP10 behaviour is unchanged.
-const cp11Patterns = await getConfidentialNamePatterns();
+//
+// #1244: a CP11 that was EXPECTED but could not load is a DISABLED guard, not a
+// clean scan — it is announced on stderr and counted as a FAIL so the run exits
+// non-zero. CP1–CP10 still run to completion either way: a disabled CP11 must not
+// suppress the findings the other ten rules can still make.
+const cp11 = await getConfidentialNamePatterns();
+const cp11Patterns = cp11.patterns;
+if (cp11.inertWarn) {
+  console.error(`WARN: ${cp11.inertWarn}`);
+}
+if (cp11.disabledReason) {
+  console.error(`CP11 DISABLED: ${cp11.disabledReason}`);
+  // Shaped like the per-file FAIL lines (`<where> — <CPn label>: <content>`) so the
+  // report's `— CPn` attribution parser sees CP11 here too; `<scan-wide>` stands in
+  // for the file position because a disabled guard is a property of the RUN, not of
+  // any one file. The reason carries no path (see getConfidentialNamePatterns).
+  fail(`<scan-wide> — CP11 (guard disabled): ${cp11.disabledReason}`);
+}
 
 /** @type {Array<{relPath: string, lineNum: number, pattern: string, lineContent: string}>} */
 const violations = [];
@@ -1089,7 +1344,13 @@ for (const filePath of scanFiles) {
 // The spec does not say to deduplicate, so keep as-is.
 
 if (violations.length === 0) {
-  pass(`no owner-privacy leakage found across ${scanFiles.length} scanned files`);
+  // #1244: only claim the clean verdict the run actually earned. With CP11
+  // disabled, ten of eleven rules ran — say that instead of "no leakage found".
+  if (cp11.disabledReason) {
+    console.log(`  (CP1–CP10 found no leakage across ${scanFiles.length} scanned files; CP11 did not run)`);
+  } else {
+    pass(`no owner-privacy leakage found across ${scanFiles.length} scanned files`);
+  }
 } else {
   for (const v of violations) {
     // Choke-point redaction (Fix 1 + Fix 2): scrub every configured confidential

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

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+/**
+ * check-skill-links.mjs — every relative markdown link under an instruction surface must resolve.
+ *
+ * WHY THIS EXISTS (measured 2026-09-06, session main-2026-09-06-deep-1):
+ * The #1157 `references/` splits moved 16 phase blocks out of three oversized skill bodies and
+ * verified each move with a sha256 of the moved block plus a full-reconstruction hash. That method
+ * proves the CONTENT is unchanged — and is blind by construction to the one defect class a move
+ * creates: a relative link whose correctness depends on the file's DEPTH in the tree.
+ *
+ * Three links broke and no gate saw it. The worst was
+ * `skills/session-end/references/phase-3-documentation-updates.md` → `./phase-3-6-tail.md`, which is
+ * the dispatcher for the six session-end tail phases (memory proposals, expired-learnings sweep,
+ * auto-dream, skill judge, auto-dialectic, reconciliation). From inside `references/` that path
+ * resolves one directory too deep; the target sits a level up. A coordinator following the prose
+ * would have found nothing there and silently skipped the tail.
+ *
+ * The existing neighbours cannot cover this: `check-skill-script-paths.mjs` scans only
+ * `scripts/**.mjs|.sh` and `hooks/**.sh` TARGETS, and `claude-md-drift-check` counts dead script
+ * citations, not intra-surface markdown links. Different predicate, different blind spot.
+ *
+ * WHAT IT CHECKS
+ *   For every `.md` under the scanned surfaces, every inline link `[text](target)` whose target is
+ *   relative (not http(s):, not mailto:, not `#anchor`, not an absolute path) must exist on disk,
+ *   resolved against the LINKING FILE's own directory. A `#fragment` suffix is stripped before the
+ *   existence check — anchors are out of scope (no heading index here); the path half is not.
+ *
+ * DELIBERATE NON-CHECKS
+ *   - Link text, anchors, and http(s) reachability (a network check in a validator is a flake).
+ *   - Reference-style links and bare `<...>` autolinks: not used by this repo's instruction files
+ *     (measured: 0 occurrences). If one appears, this checker stays silent rather than guessing —
+ *     recorded here so the gap is known rather than assumed absent.
+ *   - Fenced code blocks AND inline-code spans are skipped: a path inside an example command or
+ *     inside backticks is illustrative, not a link. The inline-code carve-out is not cosmetic —
+ *     `skills/memory-cleanup/SKILL.md:163` documents the MEMORY.md index FORMAT as
+ *     `` `- [Title](file.md) — hook` ``, and without it that literal template is the checker's
+ *     only "finding", i.e. the guard's first act would be to demand a doc be made wrong.
+ *
+ * Exit 0 = every relative link resolves. Exit 1 = at least one does not; each is printed as
+ * `file:line target` so it can be fixed without a search.
+ */
+
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, dirname, resolve, relative, sep } from 'node:path';
+
+/** Surfaces whose markdown is instruction, i.e. read and acted on. */
+export const SCAN_DIRS = Object.freeze(['skills', 'commands', 'agents', '.claude/rules']);
+
+/** Path segments that end the walk: vendored or machine-owned trees, never instruction. */
+export const PRUNE_DIRS = new Set(['node_modules', '.git', 'coverage', 'dist', '.pnpm']);
+
+const SKIP_TARGET = /^(https?:|mailto:|#|\/)/i;
+const LINK_RE = /\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+const INLINE_CODE_RE = /(`+)[^`]*?\1/g;
+
+/**
+ * Blank out inline-code spans, preserving column count so a reported line number still lines up.
+ * A `[x](y)` inside backticks is quoted TEXT, not a link — see DELIBERATE NON-CHECKS above.
+ */
+function stripInlineCode(line) {
+  return line.replace(INLINE_CODE_RE, (m) => ' '.repeat(m.length));
+}
+
+/** Does the path exist? A stat error (ENOENT, ELOOP, EACCES) is a non-resolving link, not a crash. */
+function statOk(abs) {
+  try { statSync(abs); return true; } catch { return false; }
+}
+
+/** Lines inside fenced code blocks — a path in an example is not a link. */
+function fencedLineNumbers(text) {
+  const fenced = new Set();
+  let inFence = false;
+  text.split('\n').forEach((line, i) => {
+    if (/^\s*(```|~~~)/.test(line)) { inFence = !inFence; fenced.add(i + 1); return; }
+    if (inFence) fenced.add(i + 1);
+  });
+  return fenced;
+}
+
+/**
+ * Markdown files under the scanned surfaces, enumerated from the FILESYSTEM.
+ *
+ * Deliberately not `git ls-files`: that lists tracked files only, so a brand-new instruction file
+ * — the exact moment a split or a new skill lands — is invisible to the sweep until it is staged,
+ * and the check would report clean on the tree that carries the defect. This repo has the incident
+ * on record (`.claude/rules/measurement-discipline.md` § "A `git grep` drift sweep cannot see
+ * untracked files": a release sweep passed, then failed after the commit, from the same working
+ * tree with no edit in between). The cost of the filesystem walk is that a gitignored `.md` under
+ * these four directories would also be checked — there are none, and one would be a finding worth
+ * seeing anyway.
+ *
+ * @returns {string[]} repo-relative paths, sorted for stable output
+ */
+export function listMarkdown(repoRoot) {
+  const out = [];
+  for (const dir of SCAN_DIRS) {
+    const abs = join(repoRoot, dir);
+    let entries;
+    try { entries = readdirSync(abs, { recursive: true, withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      if (!e.isFile() || !e.name.endsWith('.md')) continue;
+      // parentPath is absolute; make the record repo-relative with POSIX separators.
+      const rel = relative(repoRoot, join(e.parentPath ?? abs, e.name));
+      const posix = sep === '/' ? rel : rel.split(sep).join('/');
+      // Vendored trees are not an instruction surface: `skills/vault-sync/node_modules/` is real
+      // and its bundled READMEs link into their own upstream repo layout, which is not ours to fix.
+      if (posix.split('/').some((s) => PRUNE_DIRS.has(s))) continue;
+      out.push(posix);
+    }
+  }
+  return out.sort();
+}
+
+/**
+ * @returns {{ok: boolean, checked: number, files: number, findings: Array<{file: string, line: number, target: string}>}}
+ */
+export function checkSkillLinks(repoRoot = process.cwd()) {
+  const findings = [];
+  let checked = 0;
+  const files = listMarkdown(repoRoot);
+
+  for (const rel of files) {
+    const abs = join(repoRoot, rel);
+    let text;
+    try { text = readFileSync(abs, 'utf8'); } catch { continue; }
+    const fenced = fencedLineNumbers(text);
+    const baseDir = dirname(abs);
+
+    text.split('\n').forEach((line, idx) => {
+      const lineNo = idx + 1;
+      if (fenced.has(lineNo)) return;
+      for (const m of stripInlineCode(line).matchAll(LINK_RE)) {
+        const raw = m[1];
+        if (!raw || SKIP_TARGET.test(raw)) continue;
+        const target = raw.split('#')[0];
+        if (!target) continue; // pure fragment
+        checked += 1;
+        const resolved = resolve(baseDir, target);
+        // Never let a link escape the repo: an out-of-tree target is a finding, not a pass.
+        const inside = !relative(repoRoot, resolved).startsWith('..');
+        if (!inside || !statOk(resolved)) findings.push({ file: rel, line: lineNo, target: raw });
+      }
+    });
+  }
+
+  return { ok: findings.length === 0, checked, files: files.length, findings };
+}
+
+function main() {
+  const repoRoot = process.argv[2] ? resolve(process.argv[2]) : process.cwd();
+  const { ok, checked, files, findings } = checkSkillLinks(repoRoot);
+  if (!ok) {
+    for (const f of findings) {
+      process.stderr.write(`  FAIL: ${f.file}:${f.line} → ${f.target} — relative link does not resolve from this file's directory\n`);
+    }
+    process.stderr.write(`Results: ${findings.length} unresolved relative link(s) in ${files} markdown file(s) under ${SCAN_DIRS.join(', ')}\n`);
+    process.exit(1);
+  }
+  // Two-space indent: validate-plugin.mjs tallies on /^ {2}(PASS|FAIL):/m.
+  process.stdout.write(`  PASS: ${checked} relative link(s) in ${files} markdown file(s) resolve\n`);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) main();

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

@@ -1,10 +1,13 @@
 #!/usr/bin/env node
 /**
- * Check: every `scripts/**.mjs` path cited in `skills/`, `commands/` and
- * `agents/` either EXISTS or is annotated as deliberately absent (#1176).
- * Extended (#1187) to also cite `scripts/**.sh` and `hooks/**.sh` — see
- * "## Mode: BLOCKING for `.mjs`, ADVISORY for `.sh`" below for why that half
- * is advisory, not blocking.
+ * Check: every `scripts/**.mjs` path cited in `skills/`, `commands/`,
+ * `agents/` and `docs/` either EXISTS or is annotated as deliberately absent
+ * (#1176). Extended (#1187) to also cite `scripts/**.sh` and `hooks/**.sh` —
+ * see "## Mode: BLOCKING for `.mjs`, ADVISORY for `.sh`" below for why that
+ * half is advisory, not blocking. `docs/` joined `SCAN_DIRS` in #1208, after
+ * the 22 dead paths it carried at the time (9 `.mjs`, all ADR/reference
+ * prose) were annotated — see that section below for the census and why
+ * widening the scan root had to wait for the annotation pass, not precede it.
  *
  * ## Why
  *
@@ -12,8 +15,8 @@
  * `node scripts/lib/auto-commit.mjs` costs an operator a failed command and a
  * re-derivation of what the file was supposed to do — and nothing in the
  * corpus notices, because a markdown file compiles under every gate. Measured
- * 2026-09-02 @ c3ab480: 237 distinct citations across the three scan roots,
- * 7 of them dead.
+ * 2026-09-02 @ c3ab480: 237 distinct citations across the (then three) scan
+ * roots, 7 of them dead.
  *
  * ## Fences are skipped, and that is most of the answer
  *
@@ -58,27 +61,37 @@
  * The `.sh` half of the citation grammar (below) does not get that same
  * severity by default. A #1176 repo-wide grep (`scripts/hooks` prose across
  * `skills/commands/agents/docs/hooks`) found 27 distinct `.sh` citations, 21
- * dead — but only ONE of those 27 sits inside this checker's three scan roots
- * (`skills/contract-version-bump/SKILL.md:134`, itself arguably a
- * cross-repo path — see the dry-run note at `scanSkillScriptPaths`'s
- * `strictSh` option). The other 26 live in `docs/`, which this checker does
- * NOT scan and — per this same paragraph's own evidence — MUST NOT start
- * scanning as a side effect of the `.sh` extension: `docs/adr/*.md` alone
- * carries 7 dead `.mjs` citations of its own (all historical/planned ADR
- * prose, e.g. `scripts/lib/tool-adapter.mjs`, `scripts/lib/auto-commit.mjs`),
- * none annotated, all outside this task's edit scope. Widening `SCAN_DIRS` to
- * `docs` would turn those 7 into new BLOCKING findings on a doc surface
- * nobody triaged — the opposite of "the `.mjs` behaviour stays exactly as
- * today". So `SCAN_DIRS` stays `['skills', 'commands', 'agents']`; the wider
- * `docs`/`hooks` prose census is a follow-up for whoever owns those files,
- * not a silent scope change here.
+ * dead — but at the time only ONE of those 27 sat inside this checker's
+ * (then three) scan roots (`skills/contract-version-bump/SKILL.md:134`,
+ * itself arguably a cross-repo path — see the dry-run note at
+ * `scanSkillScriptPaths`'s `strictSh` option). The other 26 lived in `docs/`,
+ * which this checker did not yet scan.
+ *
+ * #1208 closed that gap in two steps, annotation before widening rather than
+ * the reverse: first, a `dirs: ['docs']` re-scan (530 citations, 66 files)
+ * found 50 findings — 22 unique dead paths (9 `.mjs`, 15 `.sh`) across
+ * 24 (file, path) pairs, concentrated in `docs/adr/*.md` (ADR prose citing
+ * not-yet-built modules like `scripts/lib/tool-adapter.mjs`) and
+ * `docs/changelog/v2.md` (23 `.sh` citations to the pre-`.mjs`-migration
+ * shell scripts, #218/#317 — historical by construction). Every one of the
+ * 22 was annotated (`planned #<iid>` for the ADR gaps, `historical` for the
+ * changelog, `example` for the one illustrative path in
+ * `docs/scope-collision-guard.md`) — zero of them were real defects. Only
+ * then did `SCAN_DIRS` gain `'docs'`, so the widening added zero new
+ * BLOCKING findings on arrival (re-verify: `scanSkillScriptPaths({
+ * pluginRoot, dirs: ['docs'] })` → `ok: true`, `findings: 0`). The wider
+ * `hooks/` `.sh` prose census (26 of the 27 `.sh` citations above are outside
+ * `SCAN_DIRS` even now, since `hooks/` prose itself is not a scanned root)
+ * remains a follow-up for whoever owns those files.
  *
  * A `.sh` finding is therefore `WARN:` by default (visible, never blocking —
  * `ok` and the CLI exit code ignore `severity: 'warn'` findings) and only
  * becomes `FAIL:`/blocking under the `--strict-sh` CLI flag (or
  * `strictSh: true` for `scanSkillScriptPaths()` callers) — flip that default
  * once the dead `.sh` citations this checker CAN see are fixed by their doc
- * owner (BV-004 revisit trigger).
+ * owner (BV-004 revisit trigger). `--strict-sh` gained a validate-plugin run
+ * surface in #1208 (advisory, non-blocking — see `scripts/validate-plugin.mjs`
+ * near its `check-skill-script-paths.mjs` call).
  *
  * @module scripts/lib/validate/check-skill-script-paths
  */
@@ -86,11 +99,11 @@
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { listRepoFiles } from './repo-files.mjs';
+import { enumerateRepoFiles } from './enumerate-repo-files.mjs';
 import { forEachLine } from './markdown-fences.mjs';
 
 /** Documentation roots whose prose is treated as a claim about the repo. */
-export const SCAN_DIRS = Object.freeze(['skills', 'commands', 'agents']);
+export const SCAN_DIRS = Object.freeze(['skills', 'commands', 'agents', 'docs']);
 
 /**
  * A cited script path. One regex, one alternation, reused for every
@@ -246,10 +259,16 @@ export function scanSkillScriptPaths({ pluginRoot, dirs = SCAN_DIRS, strictSh =
   /** @type {string[]} */
   let files;
   try {
-    // The git index, never a `readdirSync` walk (#1143): a walk cannot see
-    // `.gitignore`, so a worktree under `.claude/worktrees/` or any ignored
-    // artefact would enter this census as if it were repository documentation.
-    files = listRepoFiles(pluginRoot, { dirs, exts: ['.md'] });
+    // The population is "exists in this repo, tracked or not" (#1248) — NOT
+    // "is versioned". A doc that cites a dead script is a defect the moment it
+    // is written; the bare git index cannot see it until it is staged, so the
+    // check reported clean on the exact tree carrying the bug (measured: an
+    // untracked `skills/zz-probe/SKILL.md` → `1 passed, 0 failed` before
+    // `git add -A`, `0 passed, 1 failed` after). `enumerateRepoFiles` still
+    // 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'] });
   } catch (error) {
     findings.push({
       kind: 'tool-error',

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

@@ -302,8 +302,6 @@ const ALLOWLIST = Object.freeze({
     'prose-only consumer — skills/wave-executor/wave-loop.md gates the per-wave commit step on this key; the commit itself is a coordinator action, not a script',
   'instruction-budget':
     'dedicated reader outside the parser layer — scripts/lib/instruction-budget-guard.mjs parses this block itself (S2 exemption only; S1 evidence is real)',
-  webhooks:
-    'dedicated reader outside the parser layer — scripts/lib/webhook-url.mjs resolves these URLs env-first (S2 exemption only; S1 evidence is real)',
 });
 
 /**