session-orchestrator 3.24.0 → 4.0.1

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
@@ -656,7 +751,7 @@ function redactSpans(line, patterns) {
  * be called only from runScan() — NOT at module top-level. This module is
  * dual-mode (CLI entry point AND importable library, `isMain` guard); a top-level
  * fs read would fire on every library import (e.g. pseudonym-map.mjs importing
- * isOwnerLeakySegment). loadConfidentialNames caches per path, so calling this
+ * isOwnerLeakySegment). inspectConfidentialNames caches per path, so calling this
  * once per scan reads the file at most once.
  *
  * STANDALONE-SAFE: the two host-local helper modules are DYNAMICALLY imported
@@ -667,23 +762,198 @@ 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 {
-    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 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 [];
+    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 degrade is documented — but it
+      // must not swallow a CP11 that the operator DID configure (GitLab #1262).
+      // No helper resolved here, so the only configuration signal still readable
+      // is the raw env var: a literal mirror of ENV_KEYS['confidential-names-file']
+      // in scripts/lib/config/host-paths.mjs, which cannot be imported on this
+      // branch by construction.
+      //
+      // LIMIT (named, not hidden): an owner.yaml-configured names file is
+      // STRUCTURALLY undetectable in a standalone copy — resolveOwnerYamlPath()
+      // lives in the very module chain that failed to resolve, so there is no way
+      // to learn that owner.yaml even exists, let alone what it configures. Only
+      // the env route can fail closed here; the owner.yaml route degrades inert.
+      const envNamesPath = process.env.SO_CONFIDENTIAL_NAMES_FILE;
+      if (typeof envNamesPath === 'string' && envNamesPath.trim() !== '') {
+        return {
+          patterns: [],
+          disabledReason:
+            'CP11 configured via SO_CONFIDENTIAL_NAMES_FILE but the confidential-names helpers are not resolvable (standalone copy) — failing closed',
+        };
+      }
+      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 } = helpers.hostPaths;
+    const { inspectConfidentialNames } = helpers.confidentialNames;
+    const { resolveOwnerYamlPath } = helpers.ownerYaml;
+
+    // ONE owner.yaml load. Since #1251 loadHostPaths() passes the loader's own
+    // health (source / reason / droppedSections) straight through, so the
+    // env>owner.yaml>default precedence and the load's diagnosis come from the
+    // same read — no second loadOwnerConfig() call to recover what was discarded.
+    const hostCtx = loadHostPaths();
+
+    // FAIL-CLOSED on an unknowable load (LOW-2). `loadHostPaths` has its own
+    // defensive catch that swallows a THROWING owner loader and returns
+    // `{ ownerConfig: undefined, env, source: undefined, reason: undefined }`.
+    // Without this branch that shape resolves `namesPath` to '' , fires no
+    // reason branch, and returns `{ patterns: [] }` — a silent PASS.
+    // Only the throw produces all-undefined: `loadOwnerConfig` returns
+    // `{ config: getDefaults(), source: 'defaults', errors: [] }` for a
+    // genuinely ABSENT owner.yaml (owner-yaml.mjs:587-590) and `source:
+    // 'defaults'` with a `reason` for every read/parse failure — so a missing
+    // file keeps taking the normal path below. Latent today (the loader
+    // returns on every error path), load-bearing if that ever changes.
+    if (
+      hostCtx.ownerConfig === undefined &&
+      hostCtx.source === undefined &&
+      hostCtx.reason === undefined
+    ) {
+      return {
+        patterns: [],
+        disabledReason:
+          'CP11 could not determine whether a confidential-names file is configured (owner config loader failed) — failing closed',
+      };
+    }
+
+    const namesPath = resolveHostPath('confidential-names-file', '', hostCtx);
+
+    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 (hostCtx.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 (hostCtx.reason === 'unparseable') {
+          return {
+            patterns: [],
+            disabledReason:
+              'owner.yaml exists but could not be parsed, so a configured confidential-names-file cannot be resolved',
+          };
+        }
+        if (hostCtx.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. Since #1250 the loader REPORTS the class it
+    // used to collapse into `null`, so the verdict reads straight off `status` —
+    // no second read of the file to re-derive it. Only `[]` ('empty') is an
+    // operator choice (inactive, silent); 'missing'/'malformed'/'all-dropped'
+    // mean a configured guard cannot run, which is (c) and fails closed. The
+    // reasons carry no path (see above). `inspectConfidentialNames` is the
+    // discriminated entry point; `loadConfidentialNames` keeps its 4.0.0
+    // `string[] | null` shape for external deep-importers and cannot express
+    // this distinction.
+    const { status, names } = inspectConfidentialNames({ namesPath });
+    if (status === 'missing') {
+      return { patterns: [], disabledReason: 'a confidential-names-file is configured but does not exist' };
+    }
+    if (status === 'malformed') {
+      return {
+        patterns: [],
+        disabledReason: 'the configured confidential-names-file is unreadable or not a JSON array of names',
+      };
+    }
+    if (status === 'all-dropped') {
+      // W4 finding F3 (fail-open): the file listed entries and validation rejected
+      // every one of them (non-strings, blanks, over-long). That is a CORRUPTED
+      // list, not the `[]` opt-out — CP11 would run with zero patterns and report
+      // the clean verdict it never earned. Same class as 'malformed'.
+      return {
+        patterns: [],
+        disabledReason:
+          'every entry in the configured confidential-names-file was rejected as invalid or oversized',
+      };
+    }
+    if (status !== 'ok') return { patterns: [] }; // 'empty' — the operator's `[]` opt-out.
+    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'})` };
   }
 }
 
@@ -839,6 +1109,10 @@ function isAllowlisted(relPath, line) {
     'site/index.html',
     'site/impressum/index.html',
     'site/datenschutz/index.html',
+    // The German landing page (2026-09-07 redesign) carries the same publisher
+    // identity (JSON-LD @id + footer rel="author") as site/index.html. Exact
+    // path, never a site/de/ prefix — site/guide/index.html stays outside.
+    'site/de/index.html',
   ]);
   const inAllowlistedFile = ALLOWLISTED_URL_PATHS.has(norm);
 
@@ -945,7 +1219,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 +1380,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,193 @@
+#!/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.
+ *
+ * `docs/` joined the list in #1258 after the annotate-before-widen step the sibling
+ * `check-skill-script-paths.mjs` ran for #1208: a read-only re-scan (`dirs: ['docs']`,
+ * 2026-09-07) returned 92 files / 111 relative links / 8 findings — six of them GitLab
+ * `-/issues/N` renderer links now carved out by `SKIP_TARGET`, two of them genuinely dangling
+ * links to PRDs that had been archived to the private Meta-Vault. Both classes were resolved
+ * before the widening, so the widening itself lands at 0 findings.
+ */
+export const SCAN_DIRS = Object.freeze(['skills', 'commands', 'agents', '.claude/rules', 'docs']);
+
+/** 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']);
+
+/**
+ * Targets this checker never resolves against the filesystem.
+ *
+ * The `-/issues/N` · `-/merge_requests/N` branch is a GitLab RENDERER convention, not a link
+ * defect: `../../../-/issues/174` is how a doc nested two levels deep points at the project's
+ * issue tracker, and GitLab resolves it correctly in its own Markdown view. It leaves the repo
+ * by construction, so a filesystem checker can only ever call it dangling. Measured 2026-09-07:
+ * 6 of the 8 `docs/` findings were exactly this shape, all in `docs/owner-config-schema.md`.
+ *
+ * The branch is anchored at BOTH ends. Left-unanchored it would still be a carve-out, but
+ * right-unanchored it swallowed every path that merely PASSES THROUGH such a segment —
+ * `docs/-/issues/12/../../secrets.md` is a genuinely dangling link and was SKIPped. The
+ * optional trailing `#note_123` is kept because GitLab issue links legitimately carry one.
+ */
+const SKIP_TARGET = /^(https?:|mailto:|#|\/)|(^|\/)-\/(issues|merge_requests)\/\d+(#[\w-]*)?$/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.
+ *
+ * @param {string} repoRoot
+ * @param {{dirs?: readonly string[]}} [options] `dirs` defaults to {@link SCAN_DIRS}; it exists so
+ *   an annotate-before-widen dry-run over a candidate surface needs no re-implementation of this
+ *   predicate (same shape as `scanSkillScriptPaths({ dirs })`).
+ * @returns {string[]} repo-relative paths, sorted for stable output
+ */
+export function listMarkdown(repoRoot, { dirs = SCAN_DIRS } = {}) {
+  const out = [];
+  for (const dir of 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();
+}
+
+/**
+ * @param {string} [repoRoot]
+ * @param {{dirs?: readonly string[]}} [options] `dirs` defaults to {@link SCAN_DIRS} — see
+ *   {@link listMarkdown}.
+ * @returns {{ok: boolean, checked: number, files: number, findings: Array<{file: string, line: number, target: string}>}}
+ */
+export function checkSkillLinks(repoRoot = process.cwd(), { dirs = SCAN_DIRS } = {}) {
+  const findings = [];
+  let checked = 0;
+  const files = listMarkdown(repoRoot, { dirs });
+
+  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();