@event4u/agent-config 9.20.0 → 9.21.0

package/src/scripts/check_public_links.ts

@@ -22,6 +22,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 const PUBLIC_FILES = ['README.md', 'AGENTS.md', 'docs/architecture.md'] as const;
@@ -269,6 +271,23 @@ function main(): number {
     const args = parse_args(process.argv.slice(2));
 
     const contracts = collect_contracts();
+    // Every verdict below is decided against this map: an empty contracts dir
+    // turns "no stability violations" into "nothing was ever compared".
+    try {
+        assertScanned({
+            gate: 'check_public_links',
+            scanned: contracts.size,
+            units: 'contract file(s)',
+            roots: [CONTRACTS_DIR],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // 1 = violations found (2 is argparse, 3 internal error).
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
     if (args.list) {
         for (const [p, lvl] of contracts) {
             const label = lvl ?? '(no frontmatter)';

package/src/scripts/check_quality_regression.ts

@@ -51,6 +51,7 @@ import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { wilcoxon } from './bench_ab_v2_stats.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -299,6 +300,24 @@ function main(argv: string[]): number {
   }
 
   const results = Array.isArray(report.results) ? report.results : [];
+  // A MISSING report is the documented inert path and already returned above. A
+  // report that exists and carries no pairs is a different thing entirely — a
+  // truncated or half-written judge run — yet it aggregates to `no-data` and
+  // exits 0 outside flip-gate mode, i.e. reads as "quality held" on zero data.
+  try {
+    assertScanned({
+      gate: 'check_quality_regression',
+      scanned: results.length,
+      units: 'judged pair(s)',
+      roots: [path.relative(REPO_ROOT, reportPath)],
+    });
+  } catch (e) {
+    if (e instanceof DeadScopeError) {
+      process.stderr.write(`error: ${e.message}\n`);
+      return 1; // the gate's file-error code — the report is present but unusable
+    }
+    throw e;
+  }
   const thr = typeof report.threshold === 'number' ? report.threshold : threshold;
   const agg = aggregate(results, thr);
 

package/src/scripts/check_reach_channels.ts

@@ -53,6 +53,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { parse as parseYaml } from 'yaml';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 import { SchemaError, validate, type YamlValue } from './validate_frontmatter.js';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -305,6 +306,27 @@ export function check_probe_cmd_binding(registry: unknown): SchemaError[] {
     return findings;
 }
 
+/**
+ * Backends declared across every channel — the units the schema rules and the
+ * `probe_cmd-binding` rule actually judge. Same deliberate shape-tolerance as
+ * `check_probe_cmd_binding`: anything unreadable is skipped, so the number is
+ * "entries a rule could be applied to", never "entries that passed".
+ */
+function count_backends(registry: unknown): number {
+    const root =
+        registry !== null && typeof registry === 'object' && !Array.isArray(registry)
+            ? (registry as Record<string, unknown>)
+            : null;
+    const channels = Array.isArray(root?.['channels']) ? (root['channels'] as unknown[]) : [];
+    return channels.reduce<number>((total, rawChannel) => {
+        if (rawChannel === null || typeof rawChannel !== 'object' || Array.isArray(rawChannel)) {
+            return total;
+        }
+        const backends = (rawChannel as Record<string, unknown>)['backends'];
+        return total + (Array.isArray(backends) ? backends.length : 0);
+    }, 0);
+}
+
 /**
  * Validate one registry file against the schema.
  *
@@ -376,6 +398,28 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         return 1;
     }
 
+    // Reaching a CLEAN verdict over zero backends means the SCHEMA stopped
+    // constraining, not that the registry is empty: `minItems: 1` sits on both
+    // `channels` and `backends`, so an empty registry is an error-severity
+    // finding and returned above. A gutted or repointed schema is therefore
+    // the only way to arrive here with nothing scanned — and it would print ✅
+    // over a file no rule was applied to. Exit 3 is the could-not-run class
+    // `RegistryLoadError` already uses; 1 asserts real violations were found.
+    try {
+        assertScanned({
+            gate: 'check_reach_channels',
+            scanned: count_backends(load_registry(targetPath)),
+            units: 'backend(s)',
+            roots: [relTarget],
+        });
+    } catch (err) {
+        if (err instanceof DeadScopeError || err instanceof RegistryLoadError) {
+            process.stderr.write(`❌  check_reach_channels: ${err.message}\n`);
+            return 3;
+        }
+        throw err;
+    }
+
     if (!quiet) {
         process.stdout.write(`✅  ${relTarget}: schema-valid (reach channel registry).\n`);
     }

package/src/scripts/check_reach_staleness.ts

@@ -51,6 +51,7 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 import { RegistryLoadError, load_registry } from './check_reach_channels.js';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -313,8 +314,16 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     const relTarget = path.relative(ROOT, registryPath) || registryPath;
 
     let findings: StalenessFinding[];
+    let channelCount: number;
     try {
         findings = run_checks({ registryPath, today });
+        // `load_registry` already refuses a missing / unparseable file (exit 3),
+        // but a registry that PARSES with no `channels:` list is the blind case:
+        // `extract_channels` is defensive by contract and returns [], so every
+        // per-channel check iterates nothing and the gate prints the ✅ line.
+        // Re-reading the (small) YAML keeps run_checks / extract_channels — both
+        // exported and pinned by fixtures — untouched.
+        channelCount = extract_channels(load_registry(registryPath)).length;
     } catch (err) {
         if (err instanceof RegistryLoadError) {
             process.stderr.write(`❌  check_reach_staleness: ${err.message}\n`);
@@ -323,6 +332,24 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         throw err;
     }
 
+    // No `allowEmpty`: a registry with zero channels is a registry this gate
+    // cannot judge, and it reads exactly like a clean one. Exit 3 (unusable
+    // input) over 1 (violations) — a dead scope means the gate could not run.
+    try {
+        assertScanned({
+            gate: 'check_reach_staleness',
+            scanned: channelCount,
+            units: 'channel(s)',
+            roots: [`${path.relative(ROOT, registryPath) || registryPath} → channels[]`],
+        });
+    } catch (err) {
+        if (err instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${err.message}\n`);
+            return 3;
+        }
+        throw err;
+    }
+
     if (findings.length > 0) {
         process.stdout.write(`❌  ${relTarget}: ${findings.length} staleness violation(s):\n`);
         for (const finding of findings) {

package/src/scripts/check_release_adjacent_health.ts

@@ -18,7 +18,14 @@
  * Exit codes: 0 all green/absent · 1 durably-red workflow(s) · 2 usage/env.
  */
 
+import * as path from 'node:path';
 import { argv, env, exit } from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+import { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
+
+// src/scripts/check_release_adjacent_health.ts → two levels up is the repo root.
+const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
 
 const WATCHED = [
     'publish-npm.yml',
@@ -71,6 +78,27 @@ async function main(): Promise<number> {
         return 2;
     }
 
+    // The scope is the watch list itself. A renamed or deleted workflow answers
+    // 404 → the loop logs "no completed runs (or workflow absent) — skipping"
+    // and continues, so a fully stale WATCHED list still prints "✅ healthy" —
+    // the same silent-tripwire failure this gate exists to detect. Checking the
+    // names against `.github/workflows/` catches the rename locally, before the
+    // API can launder it into a skip. Exit 2 (usage/env) over 1 (durably red):
+    // a phantom watch list means the tripwire could not run.
+    try {
+        assertWatchlistResolves({
+            gate: 'check_release_adjacent_health',
+            candidates: WATCHED.map((wf) => `.github/workflows/${wf}`),
+            repoRoot: REPO,
+        });
+    } catch (err) {
+        if (err instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${err.message}\n`);
+            return 2;
+        }
+        throw err;
+    }
+
     // Tag/release-triggered workflows have no branch association — query
     // without the branch filter for those; branch-scoped for PR/push ones.
     const branchless = new Set(['publish-npm.yml', 'deploy-mcp-worker.yml', 'release.yml']);

package/src/scripts/check_release_highlights.ts

@@ -47,6 +47,7 @@ import {
     stale_draft_labels,
 } from './_lib/release_highlights.js';
 import { extract_changelog_section } from './_lib/release_material.js';
+import { assertScanned, assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -142,6 +143,23 @@ function main(argv: readonly string[]): number {
             return 2;
         }
     }
+    // The changelog is the curated half of the comparison and it is read
+    // unconditionally below; a moved or renamed file would otherwise surface as
+    // an ENOENT stack trace rather than a gate verdict. Exit 2 is this gate's
+    // could-not-run code (same as a missing section); 1 means a contradiction.
+    try {
+        assertWatchlistResolves({
+            gate: 'check_release_highlights',
+            candidates: [path.relative(REPO_ROOT, path.resolve(changelogPath))],
+            repoRoot: REPO_ROOT,
+        });
+    } catch (err) {
+        if (err instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${err.message}\n`);
+            return 2;
+        }
+        throw err;
+    }
     const section = extract_changelog_section(fs.readFileSync(changelogPath, 'utf-8'), version);
     if (!section) {
         process.stderr.write(`CHANGELOG carries no section for ${version}\n`);
@@ -159,6 +177,22 @@ function main(argv: readonly string[]): number {
         process.stderr.write(`${(err as Error).message}\n`);
         return 2;
     }
+    // Every derived category comes from this span, so an empty one makes the
+    // contradiction check pass over nothing.
+    assertScanned({
+        gate: 'check_release_highlights',
+        scanned: span.length,
+        units: 'span commit(s)',
+        roots: [`git log ${from}..${to}`],
+        allowEmpty:
+            'EMPTY_VALID: git already answered for the range — a from..to it could not read ' +
+            'throws in collect_span_commits above and exits 2, so reaching here with zero ' +
+            'commits means git read the range successfully and it is genuinely empty. ' +
+            '"Empty span with _none_ everywhere is green" is a pre-registered fixture of this ' +
+            'gate, not a scope failure: with no commits there is no evidence a curated `_none_` ' +
+            'could contradict. Deleting the scan root is not the same state — that is the ' +
+            'throwing branch, not this one.',
+    });
     // A generator-derived line that nobody rewrote is a prose gap, never a
     // contradiction: the line's evidence is true, it is just unpolished. Warn
     // so the omission is visible, and keep the exit code owned solely by the

package/src/scripts/check_release_includes_discovery.ts

@@ -20,6 +20,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 // src/scripts/check_release_includes_discovery.ts → two dirs up is repo root.
 // Mirrors Python `Path(__file__).resolve().parents[2]`.
@@ -68,17 +70,34 @@ function main(): number {
         data !== null && typeof data === 'object'
             ? (data as Record<string, unknown>)['artefacts']
             : undefined;
-    if (!Array.isArray(artefacts) || artefacts.length === 0) {
-        return _die(
-            `${_rel(MANIFEST)} carries no artefacts — discovery` +
-                ' scanner produced an empty manifest.',
-        );
+    // The empty-manifest check IS this gate's scan-scope assertion: a manifest
+    // listing nothing means the discovery scanner walked a dead root, and
+    // shipping it would tell every consumer the package has no artefacts.
+    const artefact_count = Array.isArray(artefacts) ? artefacts.length : 0;
+    try {
+        assertScanned({
+            gate: 'check_release_includes_discovery',
+            scanned: artefact_count,
+            units: 'artefact(s)',
+            roots: [_rel(MANIFEST)],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // 1 is this gate's only failure code, and the wording below is the
+            // pinned py2ts message — so the DeadScopeError text is not
+            // substituted for it.
+            return _die(
+                `${_rel(MANIFEST)} carries no artefacts — discovery` +
+                    ' scanner produced an empty manifest.',
+            );
+        }
+        throw exc;
     }
     if (!_isFile(SUMMARY)) {
         return _die(`${_rel(SUMMARY)} is missing.`);
     }
     process.stdout.write(
-        `check-release-discovery: OK (${artefacts.length} artefacts in` +
+        `check-release-discovery: OK (${artefact_count} artefacts in` +
             ` ${_rel(MANIFEST)})\n`,
     );
     return 0;

package/src/scripts/check_release_pr_shape.ts

@@ -20,6 +20,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 
 const ALLOWLIST_GLOBS = [
@@ -127,7 +129,22 @@ function _gh_diff_files(pr: string): string[] {
 }
 
 function check(files: readonly string[]): number {
-    if (files.length === 0) {
+    // This gate already refused an empty diff by hand; routing that refusal
+    // through the shared primitive keeps the behaviour (pinned stdout line,
+    // exit 1) while making the scope assertion explicit. No `allowEmpty`: a
+    // release PR that touches nothing is the failure, not a clean state — and
+    // an empty `gh pr diff` (bad PR number, auth failure) reads identically.
+    try {
+        assertScanned({
+            gate: 'check_release_pr_shape',
+            scanned: files.length,
+            units: 'changed file(s)',
+            roots: ['gh pr diff --name-only <pr> | --files <list>'],
+        });
+    } catch (exc) {
+        if (!(exc instanceof DeadScopeError)) {
+            throw exc;
+        }
         process.stdout.write(
             'OUT-OF-SHAPE: empty diff — release PR must touch at least one file.\n',
         );

package/src/scripts/check_release_published.ts

@@ -26,6 +26,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
+
 const SEMVER_RE = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/;
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -131,6 +133,25 @@ const _hooks: Hooks = {
 function main(argv: readonly string[] = [], hooks: Hooks = _hooks): number {
     const args = parse_args(argv);
 
+    // This gate walks no tree: one named file supplies BOTH sides of every
+    // invariant — the version the git tag must match and the package name npm
+    // is queried for. A repointed PACKAGE_JSON constant is the whole failure
+    // surface, so the watch list is the scope assertion. Exit 3 (internal
+    // error — the gate could not run), never 1, which asserts real drift.
+    try {
+        assertWatchlistResolves({
+            gate: 'check_release_published',
+            candidates: [path.relative(REPO_ROOT, PACKAGE_JSON)],
+            repoRoot: REPO_ROOT,
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 3;
+        }
+        throw exc;
+    }
+
     let version: string;
     try {
         version = hooks._package_version();

package/src/scripts/check_release_surface_equality.ts

@@ -28,6 +28,7 @@ import {
     strip_pr_wrapper,
     surface_divergence,
 } from './_lib/release_material.js';
+import { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -102,6 +103,27 @@ function main(argv: readonly string[]): number {
         ) as Record<string, unknown>;
         version = String(pkg['version']);
     }
+    // The changelog is this gate's one fixed named input — the other surface is
+    // either fetched over the network (`--pr`) or a caller-supplied fixture. It
+    // is read unguarded below, so a moved or renamed CHANGELOG would surface as
+    // an ENOENT stack trace rather than a verdict. Listed alone on purpose: a
+    // watch list passes as soon as ANY candidate resolves, so pairing it with
+    // `--body-file` would let an existing fixture mask an absent changelog.
+    // Exit 2 — this gate's usage/extraction class — never 1, which asserts
+    // the two surfaces genuinely diverged.
+    try {
+        assertWatchlistResolves({
+            gate: 'check_release_surface_equality',
+            candidates: [path.relative(REPO_ROOT, path.resolve(changelogPath))],
+            repoRoot: REPO_ROOT,
+        });
+    } catch (err) {
+        if (err instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${err.message}\n`);
+            return 2;
+        }
+        throw err;
+    }
     const prBody = pr !== null ? _pr_body(pr) : fs.readFileSync(bodyFile!, 'utf-8');
     const changelogText = fs.readFileSync(changelogPath, 'utf-8');
     const result = check_surface_equality({ prBody, changelogText, version });

package/src/scripts/check_release_trunk_sync.ts

@@ -21,6 +21,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertScanned } from './_lib/scan_scope.js';
+
 const RELEASE_BRANCH_RE = /^release\/(\d+)\.(\d+)\.(\d+)$/;
 const SEMVER_TAG_RE = /^(\d+)\.(\d+)\.(\d+)$/;
 const BOOTSTRAP_FILE = 'docs/contracts/release-trunk-sync.bootstrap';
@@ -137,6 +139,23 @@ function main(): number {
     }
     const m = RELEASE_BRANCH_RE.exec(branch);
     if (!m) {
+        // Declared no-op, not a silent one. The gate's other empty states —
+        // no semver tags, no tag reachable from main — are NOT swallowed
+        // either: each prints its own `::warning::… skipped` line below, and
+        // that wording is the pinned py2ts contract, so neither is converted
+        // into a DeadScopeError here.
+        assertScanned({
+            gate: 'check_release_trunk_sync',
+            scanned: 0,
+            units: 'release-prep branch(es)',
+            roots: ['git rev-parse --abbrev-ref HEAD'],
+            allowEmpty:
+                'OPTIONAL_INPUT: the checked-out branch is not release/X.Y.Z, so there is no ' +
+                'target version to compare main against — an absent question, not an empty ' +
+                'corpus. Deletion test: wiping every git ref would not produce this branch; ' +
+                'the input read here is the branch NAME, it was read successfully, and a ' +
+                'branch that could not be read exits at the detached-HEAD warning above.',
+        });
         return 0; // non-release branch class — gate is a no-op
     }
     const target: SemVer = [Number(m[1]), Number(m[2]), Number(m[3])];

package/src/scripts/check_reply_consistency.ts

@@ -45,6 +45,7 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { artefact_roots } from './_lib/agent_src.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -269,8 +270,10 @@ export function cmd_scan_dir(root: string): number {
         roots = [root];
     }
     const violations: Array<[string, number, string]> = [];
+    let scanned = 0;
     for (const r of roots) {
         for (const md of _rglobMdSorted(r)) {
+            scanned += 1;
             const text = fs.readFileSync(md, 'utf-8');
             const lines = _splitlines(text);
             for (let idx = 0; idx < lines.length; idx++) {
@@ -282,6 +285,25 @@ export function cmd_scan_dir(root: string): number {
             }
         }
     }
+    // The CI invocation points at the retired `.agent-src.uncondensed` root and
+    // relies on the fallback above; an EMPTY leftover of that directory still
+    // passes `_isDir`, so the fallback never fires and the sweep reads nothing.
+    try {
+        assertScanned({
+            gate: 'check_reply_consistency',
+            scanned,
+            units: 'markdown file(s)',
+            roots: roots.map((r) => _relToPosixOrAbs(r, ROOT)),
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // 1 = usage/IO error, as for the unresolvable-root case above
+            // (2 is reserved for findings).
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
     if (violations.length > 0) {
         for (const [p, line, snippet] of violations) {
             process.stderr.write(`  🔴 ${p}:${String(line)} — inline-tag — ${snippet}\n`);

package/src/scripts/check_roadmap_trackable.ts

@@ -29,6 +29,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const QUIET = process.argv.slice(2).includes('--quiet');
 
 const ROADMAP_ROOT = 'agents/roadmaps';
@@ -224,6 +226,24 @@ function main(): number {
         process.stderr.write(`❌  ${ROADMAP_ROOT} not found — run from project root.\n`);
         return 1;
     }
+    // The dir check above cannot see an existing-but-empty tree, and the unit
+    // has to be the unfiltered walk: "0 active roadmaps" is a real success
+    // state (everything archived), while 0 `.md` under the root never is.
+    try {
+        assertScanned({
+            gate: 'check_roadmap_trackable',
+            scanned: _rglobMdSorted(ROADMAP_ROOT).length,
+            units: 'markdown file(s)',
+            roots: [ROADMAP_ROOT],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // 1 is this gate's only failure code (0 clean / 1 violation).
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
     const findings: string[] = [];
     for (const p of find_active_roadmaps(ROADMAP_ROOT)) {
         findings.push(...violations_for(p));

package/src/scripts/check_role_doc_links.ts

@@ -17,6 +17,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 const DOCS_DIR = path.join(ROOT, 'docs');
@@ -159,6 +161,27 @@ function main(argv?: readonly string[]): number {
         }
     }
 
+    // `scan` exits 2 when a role doc is missing outright, but a doc that still
+    // exists and has lost every internal link — rewritten to external URLs, or
+    // the how-to section moved elsewhere — leaves `checked` at 0 and prints
+    // "0 links OK across 2 files", which is indistinguishable from a pass.
+    try {
+        assertScanned({
+            gate: 'check_role_doc_links',
+            scanned: checked,
+            units: 'internal link(s)',
+            roots: ROLE_DOCS.map((d) => _relTo(d)),
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // 2 is this gate's existing scope-failure code (missing role doc);
+            // 1 means "broken links", which is not what happened here.
+            process.stderr.write(`${exc.message}\n`);
+            return 2;
+        }
+        throw exc;
+    }
+
     if (failures.length > 0) {
         process.stderr.write('Broken links in role docs:\n');
         for (const [doc, line_no, url] of failures) {

package/src/scripts/check_rule_invariants.ts

@@ -33,6 +33,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertWatchlistResolves } from './_lib/scan_scope.js';
+
 // src/scripts/check_rule_invariants.ts → two dirs up is the repo root.
 const _HERE = fileURLToPath(import.meta.url);
 const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -247,6 +249,18 @@ function main(): number {
             return mutationSelftest(args.root);
         }
         const entries = loadEntries(args.root);
+        // This guard has no corpus to walk — it byte-pins fragments of named
+        // kernel rules, so its scope IS that watch list. An emptied
+        // invariants.json yields no candidates at all and this prints
+        // "All 0 kernel rule invariants present in src + dist"; a wholesale
+        // move of `src/rules/` + `dist/agent-src/rules/` leaves it watching
+        // phantoms. DeadScopeError lands in the catch below → stderr + exit 3,
+        // the could-not-run code; 1 means a clause was genuinely lost.
+        assertWatchlistResolves({
+            gate: 'check_rule_invariants',
+            candidates: entries.flatMap((e) => [e.file, e.dist]),
+            repoRoot: args.root,
+        });
         const invariantCount = entries.reduce((n, e) => n + e.strings.length, 0);
         const misses = scan(args.root);
         process.stdout.write(formatText(misses, invariantCount) + '\n');