@event4u/agent-config 9.20.0 → 9.21.0

package/src/scripts/audit_skill_descriptions.ts

@@ -25,6 +25,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';
 
 export const MIN_LENGTH = 150;
 // Mirrors scripts/skill_linter.py `description_too_long` threshold.
@@ -386,6 +387,24 @@ export function main(argv: string[] | null = null): number {
     for (const r of roots) {
         findings.push(...collect_findings(r));
     }
+    // The roots check above only proves a `skills/` DIRECTORY exists; roots that
+    // hold no SKILL.md still render "Audited 0 skills … ✅ All descriptions look
+    // reasonable." Exit 2 is this gate's only failure code, and it already
+    // covers the sibling "no skills/ directories found" case.
+    try {
+        assertScanned({
+            gate: 'audit_skill_descriptions',
+            scanned: findings.length,
+            units: 'SKILL.md file(s)',
+            roots,
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`error: ${exc.message}\n`);
+            return 2;
+        }
+        throw exc;
+    }
     if (args.json) {
         process.stdout.write(pyJsonDumpsIndent2(findings.map(_asdict)) + '\n');
     } else {

package/src/scripts/{verify_before_complete_hook.ts → before_complete_hook.ts}

@@ -2,9 +2,22 @@
 /**
  * Platform-agnostic hook for the `verify-before-complete` rule.
  *
- * Ported from the retired Python `src/scripts/verify_before_complete_hook.py` (ADR-200 —
- * Python→TS migration, Phase 6 / hooks). Public API mirrors the Python
- * module exactly (snake_case kept deliberately — fidelity over TS idiom).
+ * Named `before_complete_hook`, not `verify_before_complete_hook`: `verify_` is
+ * one of the gate-shaped prefixes in `_lib/gate_population.ts`, so the old name
+ * put an observability hook into the gate population, where the scan-scope
+ * ratchet counted it as a gate that cannot assert a scan scope (it scans no
+ * corpus — its only inputs are its stdin envelope and the state file it writes).
+ * AI council 2026-08-05 rejected the alternative of excluding `_hook.ts` in the
+ * population filter as population-shrinking: `.d.ts` / `.test.ts` are excluded
+ * because the language and the test runner make them structurally
+ * non-executable, whereas "a hook never blocks" is an operational property you
+ * can only learn by reading `hook_manifest.yaml` — and manifest-driven
+ * classification was already rejected once. Renaming keeps classification
+ * structural and needs no exclusion rule.
+ *
+ * Ported from the retired Python `src/scripts/verify_before_complete_hook.py`
+ * (ADR-200 — Python→TS migration, Phase 6 / hooks). Public API mirrors the
+ * Python module exactly (snake_case kept deliberately — fidelity over TS idiom).
  *
  * Records observable evidence that a verification command (tests, quality
  * tools, build) ran. The rule body cites the resulting state file as the

package/src/scripts/check_adr_frontmatter.ts

@@ -35,6 +35,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 = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(_HERE, '..', '..');
 const ADR_DIR = path.join(REPO_ROOT, 'docs', 'decisions');
@@ -149,6 +151,27 @@ export function check(dir: string = ADR_DIR): AdrFinding[] {
 function main(argv: string[]): number {
     const as_json = argv.includes('--json');
     const findings = check();
+    const total = fs.existsSync(ADR_DIR)
+        ? fs.readdirSync(ADR_DIR).filter((f) => /^ADR-.*\.md$/.test(f)).length
+        : 0;
+
+    // `check()` returns findings, never a count, so a moved `docs/decisions/`
+    // yields an empty list — reported as "0 ADR(s) · 0 error(s)" and green.
+    // Exit 1 is the violation code; 2 stays reserved for usage/env errors.
+    try {
+        assertScanned({
+            gate: 'check_adr_frontmatter',
+            scanned: total,
+            units: 'ADR file(s)',
+            roots: ['docs/decisions'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
 
     if (as_json) {
         process.stdout.write(JSON.stringify({ findings }, null, 2) + '\n');
@@ -157,9 +180,6 @@ function main(argv: string[]): number {
 
     const errors = findings.filter((f) => f.level === 'error');
     const warns = findings.filter((f) => f.level === 'warn');
-    const total = fs.existsSync(ADR_DIR)
-        ? fs.readdirSync(ADR_DIR).filter((f) => /^ADR-.*\.md$/.test(f)).length
-        : 0;
 
     process.stdout.write(
         `ADR frontmatter: ${total} ADR(s) · ${errors.length} error(s) · ` +

package/src/scripts/check_always_budget.ts

@@ -29,6 +29,8 @@ import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import YAML from 'yaml';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 // src/scripts/check_always_budget.ts → parents[2] is the repo root
 // (mirrors the Python module's Path(__file__).resolve().parents[2]).
 const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
@@ -552,6 +554,28 @@ function main(): number {
         return 3;
     }
 
+    // The scanned unit is every projected rule, not the `type: always` subset the
+    // budget is measured over: `isDir` above catches a MISSING projection, but a
+    // present-and-empty one (a sync that produced no rules) reaches here, and
+    // "no always-rules" cannot distinguish that from a tree whose rules are all
+    // `type: auto`. Exit 3 stays — this file's documented internal-error code,
+    // already used for the empty case, and the Taskfile fails on any non-zero, so
+    // this was never a silent green.
+    try {
+        assertScanned({
+            gate: 'check_always_budget',
+            scanned: allRules().length,
+            units: 'projected rule file(s)',
+            roots: [path.relative(REPO_ROOT, RULES_DIR)],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 3;
+        }
+        throw exc;
+    }
+
     const rules = allwaysRules();
     if (rules.length === 0) {
         process.stderr.write(`❌  no always-rules found under ${RULES_DIR}\n`);

package/src/scripts/check_artefact_checksums.ts

@@ -33,6 +33,7 @@ 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';
 import {
     apply_schema_defaults,
     load_schema,
@@ -153,6 +154,16 @@ function _check(manifestPath: string): [number, string[]] {
     const artefacts = Array.isArray(manifest['artefacts'])
         ? (manifest['artefacts'] as Json[])
         : [];
+    // A readable manifest with an empty (or non-array) `artefacts` reports
+    // "0 artefact checksums verified" and exits green — the drift this gate
+    // exists to catch would be invisible in exactly the case where the
+    // generator produced nothing.
+    assertScanned({
+        gate: 'check_artefact_checksums',
+        scanned: artefacts.length,
+        units: 'manifest artefact(s)',
+        roots: [manifestPath],
+    });
     for (const artRaw of artefacts) {
         const art = (artRaw ?? {}) as JsonObject;
         const rel = art['path'];
@@ -238,7 +249,19 @@ function parse_args(argv: readonly string[]): ParsedArgs {
 function main(argv: readonly string[]): number {
     const args = parse_args(argv);
 
-    const [code, errors] = _check(args.manifest);
+    let code: number;
+    let errors: string[];
+    try {
+        [code, errors] = _check(args.manifest);
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // 1 is this gate's only non-zero code, and it already covers the
+            // sibling could-not-run case (`manifest not found`).
+            process.stderr.write(`error: ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
     if (code !== 0) {
         for (const e of errors.slice(0, 20)) {
             process.stderr.write(`error: ${e}\n`);

package/src/scripts/check_artefact_count_messaging.ts

@@ -32,6 +32,7 @@ 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';
 import { canonical_counts } from './check_command_count_messaging.js';
 import { count, TARGETS } from './update_counts.js';
 
@@ -253,6 +254,25 @@ export function anchor_coverage_gaps(root: string = ROOT): CoverageGap[] {
 
 export function main(argv: readonly string[] = process.argv.slice(2)): number {
     const QUIET = argv.includes('--quiet');
+    // This gate walks no tree — it guards a hand-maintained surface list, and
+    // every missing entry is skipped with a warning so nothing hard-breaks on a
+    // doc rename. That tolerance is also the failure mode: a repo-wide docs
+    // move leaves every surface "skipped" and the gate reporting all counts in
+    // sync. Deleting these paths must fail, never quieten, the gate.
+    try {
+        assertWatchlistResolves({
+            gate: 'check_artefact_count_messaging',
+            candidates: [...SURFACES, ...STRUCTURED_SURFACES.map((s) => s.file)],
+            repoRoot: ROOT,
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // 1 is this gate's only non-zero code.
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
     const expected: Record<string, number> = {};
     for (const [kind] of KIND_PATTERNS) {
         expected[kind] = canonical_for(kind);

package/src/scripts/check_augmentignore.ts

@@ -24,6 +24,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 QUIET = process.argv.slice(2).includes('--quiet');
 
 const STALE_DAYS = 90;
@@ -33,15 +35,6 @@ const MIN_USEFUL_LINES = 5;
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 
-function _exists(p: string): boolean {
-    try {
-        fs.statSync(p);
-        return true;
-    } catch {
-        return false;
-    }
-}
-
 function _emit(notes: readonly string[]): void {
     if (notes.length === 0) {
         if (!QUIET) {
@@ -60,12 +53,26 @@ function check(): number {
     const target = path.join(REPO_ROOT, '.augmentignore');
     const notes: string[] = [];
 
-    if (!_exists(target)) {
-        notes.push(
-            '⚠️  .augmentignore is missing — run `/optimize augmentignore` to scaffold it.',
-        );
-        _emit(notes);
-        return 0;
+    // The whole scan scope is this one file, so its absence IS the dead-scope
+    // case. It used to surface as a scaffolding hint on stdout, which reads the
+    // same whether the file was never written or the root moved. The exit code
+    // stays 0 because "always exits 0" is this file's pinned contract (advisory,
+    // not a gate) — there is no failure code to choose between.
+    try {
+        assertWatchlistResolves({
+            gate: 'check_augmentignore',
+            candidates: ['.augmentignore'],
+            repoRoot: REPO_ROOT,
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(
+                `⚠️  ${exc.message}\n` +
+                    '    Run `/optimize augmentignore` to scaffold it.\n',
+            );
+            return 0;
+        }
+        throw exc;
     }
 
     const mtimeMs = fs.statSync(target).mtimeMs;

package/src/scripts/check_backstop_debt.ts

@@ -45,6 +45,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 _HERE = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(_HERE, '..', '..');
 const BASELINE = path.join(REPO_ROOT, 'internal', 'reports', 'rule-backstop-debt.json');
@@ -107,6 +109,26 @@ function main(argv: string[]): number {
     const as_json = argv.includes('--json');
     const write = argv.includes('--write-baseline');
 
+    // This file owns no corpus — it ratchets five NAMED gates, so its scope is
+    // that list. A renamed or deleted gate script still spawns, fails, and lands
+    // in `unparsed`, whose message sends the reader to fix a regex that is not
+    // the problem. Asserted before `--write-baseline` too: a baseline anchored
+    // over phantom gates is a ratchet that can never rise. Exit 2 (usage / env
+    // error) rather than 1 — the ratchet could not run, no count rose.
+    try {
+        assertWatchlistResolves({
+            gate: 'check_backstop_debt',
+            candidates: GATES.map((g) => `src/scripts/${g.script}.ts`),
+            repoRoot: REPO_ROOT,
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 2;
+        }
+        throw exc;
+    }
+
     const measured = GATES.map((g) => measure(g));
 
     if (as_json) {

package/src/scripts/check_beta_review_markers.ts

@@ -19,6 +19,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 CONTRACTS_DIR = 'docs/contracts';
@@ -191,9 +193,28 @@ function main(): number {
     const args = parse_args(process.argv.slice(2));
     const todayOrdinal = _todayOrdinal();
     const violations: Violation[] = [];
-    for (const p of _globMdSorted(path.join(ROOT, CONTRACTS_DIR))) {
+    const contracts = _globMdSorted(path.join(ROOT, CONTRACTS_DIR));
+    for (const p of contracts) {
         violations.push(...check_one(p, todayOrdinal));
     }
+    // Count every contract read, not the `stability: beta` subset: over a moved
+    // `docs/contracts/` "no beta contracts" and "no contracts at all" produce
+    // the same clean line, and only the second is a dead gate. Exit 1 is the
+    // violation code; 3 stays reserved for the internal-error handler below.
+    try {
+        assertScanned({
+            gate: 'check_beta_review_markers',
+            scanned: contracts.length,
+            units: 'contract file(s)',
+            roots: [CONTRACTS_DIR],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
     if (args.json) {
         process.stdout.write(JSON.stringify({ violations }, null, 2) + '\n');
     } else {

package/src/scripts/check_bridge_derivation.ts

@@ -25,6 +25,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.join(path.dirname(_HERE), '..', '..');
 
@@ -135,6 +137,17 @@ export function run(repoRoot: string): string[] {
     const before: Record<string, Record<string, string>> = {};
     for (const r of roots) before[r] = snapshot_tree(r);
 
+    // Both legs are diffs over these snapshots: with no bridge trees on disk
+    // there is nothing to diff and nothing to validate, and the check reports a
+    // fixpoint it never tested. Thrown, not returned — `errors` is the drift
+    // channel, and a dead scope is not drift.
+    assertScanned({
+        gate: 'check_bridge_derivation',
+        scanned: Object.values(before).reduce((n, snap) => n + Object.keys(snap).length, 0),
+        units: 'bridge entries',
+        roots: BRIDGE_ROOTS,
+    });
+
     // Regenerate in a child process so MODULE_STATE resolves exactly as the
     // real pipeline does (no partial in-process state). `--generate-tools`
     // covers the host trees; `--project-augment` covers `.augment` (it is
@@ -162,7 +175,15 @@ const isMain = process.argv[1] !== undefined && path.resolve(process.argv[1]) ==
 if (isMain) {
     const idx = process.argv.indexOf('--root');
     const root = idx !== -1 ? (process.argv[idx + 1] ?? REPO_ROOT) : REPO_ROOT;
-    const errors = run(root);
+    let errors: string[];
+    try {
+        errors = run(root);
+    } catch (exc) {
+        if (!(exc instanceof DeadScopeError)) throw exc;
+        // Exit 1 is this gate's only failure code.
+        process.stderr.write(`❌  ${exc.message}\n`);
+        process.exit(1);
+    }
     if (errors.length > 0) {
         for (const e of errors) process.stderr.write(`❌  ${e}\n`);
         process.exit(1);

package/src/scripts/check_bundle_path_leakage.ts

@@ -57,6 +57,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 REPO = path.resolve(path.dirname(_HERE), '..', '..');
 
@@ -290,6 +292,30 @@ function parse_args(argv: readonly string[]): Options {
 function main(argv: readonly string[] = process.argv.slice(2)): number {
     const opts = parse_args(argv);
     const targets = opts.files.length > 0 ? opts.files : tracked_bundle_files();
+
+    // `git ls-files <untracked-root>` returns nothing, by design (BUNDLE_ROOTS
+    // lists roots that may not be tracked yet). That tolerance is also the
+    // failure mode: if `dist/install/` stopped being force-included, every root
+    // resolves empty and the gate prints "0 tracked bundle file(s) scanned"
+    // with exit 0. Deletion test: a repo that ships an install bundle always
+    // tracks at least one bundle file, so 0 is never success here.
+    // Exit 2 (usage/env) over 1 (leak found) — a dead scope means the gate
+    // could not run, not that it found a leak.
+    try {
+        assertScanned({
+            gate: 'check_bundle_path_leakage',
+            scanned: targets.length,
+            units: 'bundle file(s)',
+            roots: opts.files.length > 0 ? ['<explicit file arguments>'] : BUNDLE_ROOTS,
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 2;
+        }
+        throw exc;
+    }
+
     const hits = scan_files(targets);
 
     if (hits.length > 0) {

package/src/scripts/check_ci_strict_superset.ts

@@ -38,6 +38,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 REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 const TASKFILE = path.join(REPO_ROOT, 'Taskfile.yml');
@@ -117,9 +119,25 @@ export function main(): number {
         (e) => !e.startsWith('- defer:') && e !== '- task: _ci-start' && e !== '- task: _ci-end',
     );
 
-    if (gateEntries.length === 0) {
-        process.stderr.write('❌  check_ci_strict_superset: `ci-strict` has no gate entries.\n');
-        return 1;
+    // Replaces the ad-hoc `gateEntries.length === 0` guard. Exit 2, not the 1 it
+    // returned: a task list with nothing in it means the gate could not verify
+    // the invariant — the documented meaning of 2, and what the two
+    // missing-task branches above already return — not that the invariant is
+    // violated. Counted after the wrapper filter on purpose: a `ci-strict` made
+    // of nothing but `_ci-start`/`_ci-end` is just as dead a scope.
+    try {
+        assertScanned({
+            gate: 'check_ci_strict_superset',
+            scanned: gateEntries.length,
+            units: 'ci-strict gate entr(y|ies)',
+            roots: ['Taskfile.yml (ci-strict.cmds)'],
+        });
+    } catch (err) {
+        if (err instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${err.message}\n`);
+            return 2;
+        }
+        throw err;
     }
 
     if (gateEntries[0] !== DELEGATION) {

package/src/scripts/check_claims.ts

@@ -44,6 +44,7 @@ import {
     parse_exec_pointer,
     run_exec_evidence,
 } from './_lib/exec_evidence.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _FILE = fileURLToPath(import.meta.url);
 const _HERE = path.dirname(_FILE);
@@ -271,6 +272,27 @@ interface Finding {
 function main(argv: string[] = process.argv.slice(2)): number {
     const args = parse_args(argv);
     const ledger = load_ledger();
+    // The ledger is the corpus both passes depend on: markers resolve against
+    // it and the rot guard walks it. `load_ledger` returns an empty map for a
+    // missing docs/CLAIMS.md, and with no ledger there is nothing to declare
+    // dangling — so a moved ledger would print "0 markered claim(s) bound ·
+    // ledger 0 entries" and certify the anti-hype guardrail over nothing.
+    // Marker count is deliberately not the unit: a surface tree with zero
+    // markers is a legitimate state, an absent ledger never is.
+    try {
+        assertScanned({
+            gate: 'check_claims',
+            scanned: ledger.size,
+            units: 'ledger entry(s)',
+            roots: [LEDGER_REL],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 2;
+        }
+        throw exc;
+    }
     const markers = scan_markers();
     const findings: Finding[] = [];
 

package/src/scripts/check_cli_registry_budget_sync.ts

@@ -27,12 +27,20 @@ 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 _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 
-const REGISTRY_PATH = path.join(REPO_ROOT, 'src/cli/registry.ts');
-const BUDGETS_PATH = path.join(REPO_ROOT, 'src/config/evaluator-budgets.json');
-const RECORD_PATH = path.join(REPO_ROOT, 'agents/evidence/metrics/evaluator-measurements.json');
+/** The gate's entire scan scope: three named inputs, repo-relative. */
+const INPUTS = [
+    'src/cli/registry.ts',
+    'src/config/evaluator-budgets.json',
+    'agents/evidence/metrics/evaluator-measurements.json',
+] as const;
+const [REGISTRY_PATH, BUDGETS_PATH, RECORD_PATH] = INPUTS.map((rel) =>
+    path.join(REPO_ROOT, rel),
+) as [string, string, string];
 
 const METRIC = 'cli_help_command_count';
 
@@ -105,6 +113,27 @@ function _read_json(p: string): Record<string, unknown> {
 }
 
 function main(): number {
+    // No corpus to walk — the scope is the watch list above. The reads below
+    // already fail closed, but they surface an ENOENT for whichever path is read
+    // first; this names all three, and it keeps the `scanned:` line derived from
+    // what actually resolved instead of the literal 3 it used to print. Exit 2
+    // is the same fail-closed code those reads use: a gate that cannot read its
+    // inputs must not certify them.
+    let resolved: string[];
+    try {
+        resolved = assertWatchlistResolves({
+            gate: 'check_cli_registry_budget_sync',
+            candidates: INPUTS,
+            repoRoot: REPO_ROOT,
+        });
+    } catch (err) {
+        if (err instanceof DeadScopeError) {
+            process.stderr.write(`ERROR: ${err.message}\n`);
+            return 2;
+        }
+        throw err;
+    }
+
     let registrySource: string;
     let budgetsDoc: Record<string, unknown>;
     let recordDoc: Record<string, unknown>;
@@ -128,7 +157,7 @@ function main(): number {
         recorded: measurements?.[METRIC],
     });
 
-    process.stdout.write('scanned: 3\n');
+    process.stdout.write(`scanned: ${String(resolved.length)}\n`);
     if (findings.length > 0) {
         for (const f of findings) {
             process.stdout.write(`❌  ${METRIC} out of sync: ${f}\n`);

package/src/scripts/check_cluster_patterns.ts

@@ -31,7 +31,9 @@
  * a few contract rows point at full working commands that merely happen to
  * carry one nested sub-command, and those own no dispatch table.
  *
- * Exit codes: 0 = clean, 1 = pattern violations, 3 = internal error.
+ * Exit codes: 0 = clean, 1 = pattern violations, 3 = internal error (which now
+ * includes a dead scan scope — an unparseable cluster table — reported through
+ * `_lib/scan_scope` so the message names the root).
  */
 
 import * as fs from 'node:fs';
@@ -39,6 +41,7 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { SRC_DOMAINS, command_slug, resolve_logical } from './_lib/agent_src.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 // src/scripts/check_cluster_patterns.ts → two dirs up is the repo root.
@@ -369,10 +372,29 @@ function _relativeToRootOrAbs(p: string): string {
 }
 
 export function main(): number {
+    // The locked-clusters table IS the corpus — every row drives one dispatcher
+    // read. A renamed contract file or a renamed `## Locked clusters` heading
+    // parses zero rows, which used to exit 3 (internal error, advisory at call
+    // sites) rather than fail: a blind gate, not a broken one.
     const rows = load_cluster_table();
-    if (rows.length === 0) {
-        process.stderr.write(`❌  No clusters parsed from ${_relativeToRootOrAbs(CONTRACT)}\n`);
-        return 3;
+    try {
+        assertScanned({
+            gate: 'check_cluster_patterns',
+            scanned: rows.length,
+            units: 'locked-cluster row(s)',
+            roots: [_relativeToRootOrAbs(CONTRACT)],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // Exit 3, not 1: this gate's CLI contract is pinned by its py2ts
+            // port, and an empty table was ALREADY loud here (3 is non-zero, and
+            // the Taskfile fails on any non-zero). Hardening means routing the
+            // check through the shared assertion so the message names the root —
+            // not renumbering an exit code that was never a silent green.
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 3;
+        }
+        throw exc;
     }
 
     const slug_map = build_slug_map();