@event4u/agent-config 9.20.0 → 9.22.0

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

package/src/scripts/check_secret_leak.ts

@@ -37,6 +37,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 { scanText, type SecretFinding } from './_lib/secret_detector.js';
 
 const _HERE = path.dirname(fileURLToPath(import.meta.url));
@@ -253,6 +254,52 @@ function _stderr(s: string): void {
 export function main(argv?: readonly string[]): number {
     const args = parseArgs(argv ?? process.argv.slice(2));
     const mode: Mode = args.paths.length > 0 ? 'explicit' : args.all ? 'all' : 'diff';
+
+    // Scope assertion, deliberately here and not inside `scanRepo`: that export
+    // is called directly by tests and other callers against arbitrary roots, and
+    // a secret gate is the last place to widen a throw. The cost is one extra
+    // `resolveFiles` (a `git ls-files` / `git diff`); the file reads are not
+    // repeated. Assert the RESOLVED set, before the exclude/binary filters —
+    // those legitimately drop everything (a diff touching only `tests/`), so
+    // filtering to zero is not the same signal as resolving to zero.
+    // Exit 2 (usage/env) over 1 (leak found) — a dead scope means the gate could
+    // not run. `resolveFiles` already hard-throws on an unresolvable base, so
+    // that case never arrives here as a quiet zero; a non-DeadScopeError is
+    // re-thrown untouched to preserve it.
+    try {
+        const targets = resolveFiles(REPO_ROOT, mode, { explicit: args.paths, base: args.base });
+        assertScanned({
+            gate: 'check_secret_leak',
+            scanned: targets.length,
+            units: 'candidate file(s)',
+            roots:
+                mode === 'all'
+                    ? ['git ls-files']
+                    : mode === 'explicit'
+                      ? ['<explicit path arguments>']
+                      : [`git diff --name-only --diff-filter=ACMR ${args.base ?? 'origin/main'}`, 'git ls-files --others --exclude-standard'],
+            // `all` and `explicit` carry no reason: zero tracked files, or zero
+            // named paths, is blindness in a repo that has content.
+            ...(mode === 'diff'
+                ? {
+                      allowEmpty:
+                          'EMPTY_VALID: shift-left mode scans what the change introduces, and a ' +
+                          'branch identical to its base with no untracked files introduces nothing ' +
+                          '— an absent question, not an empty corpus. Deletion test: wiping the ' +
+                          'tracked tree would show up here as changed paths, and an unresolvable ' +
+                          'base (the dangerous zero, which shallow CI produces) already throws in ' +
+                          'resolveFiles above rather than reaching this line.',
+                  }
+                : {}),
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            _stderr(`❌  ${exc.message}\n`);
+            return 2;
+        }
+        throw exc;
+    }
+
     const hits = scanRepo(REPO_ROOT, mode, { explicit: args.paths, base: args.base });
 
     if (args.json) {

package/src/scripts/check_skill_gaps.ts

@@ -16,6 +16,8 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 export const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 const SKILLS_DIR = path.join(ROOT, 'src', 'skills');
@@ -76,8 +78,38 @@ export function findBrokenPointers(entries: SkillGaps[], root: string = ROOT): s
     return errs;
 }
 
+/** SKILL.md files under `skillsDir` — the corpus `collectSkillGaps` reads. */
+function countSkillFiles(skillsDir: string = SKILLS_DIR): number {
+    try {
+        return fs
+            .readdirSync(skillsDir)
+            .filter((name) => fs.existsSync(path.join(skillsDir, name, 'SKILL.md'))).length;
+    } catch {
+        // A missing root counts zero, which the caller's assertion turns into a
+        // loud failure — never a silent "no gaps to check".
+        return 0;
+    }
+}
+
 export function main(argv: string[] = process.argv.slice(2)): number {
     const quiet = argv.includes('--quiet');
+    // The scanned unit is every SKILL.md, not the subset declaring `gaps:` —
+    // asserting on the declaration count would read a vanished skills tree as
+    // "no gaps declared" and stay green, the exact blindness this guards.
+    try {
+        assertScanned({
+            gate: 'check_skill_gaps',
+            scanned: countSkillFiles(),
+            units: 'SKILL.md file(s)',
+            roots: ['src/skills'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
     const entries = collectSkillGaps();
     const errs = findBrokenPointers(entries);
     if (errs.length > 0) {

package/src/scripts/check_skill_requires.ts

@@ -19,6 +19,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import YAML from 'yaml';
 
 import { ROOT, iter_artefacts } from './_lib/agent_src.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 import { parse_frontmatter } from './validate_frontmatter.js';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -107,6 +108,24 @@ function _set_hooks_for_test(overrides: Partial<typeof _hooks>): void {
 function main(): number {
     const closure = _hooks.load_pack_closure();
     const skills = _hooks.collect_skills();
+    // The unit is every parsed SKILL.md, not the subset declaring
+    // `requires_skills:` — over a vanished skills tree "0 composition edges"
+    // is indistinguishable from a suite that legitimately declares none.
+    try {
+        assertScanned({
+            gate: 'check_skill_requires',
+            scanned: Object.keys(skills).length,
+            units: 'SKILL.md file(s)',
+            roots: ['src/agent-src', 'src/skills', 'src/rules'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // 1 is this gate's only failure code (0 clean / 1 violations).
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
     const errors: string[] = [];
 
     for (const skill_id of Object.keys(skills).sort()) {

package/src/scripts/check_source_pointer_freshness.ts

@@ -36,6 +36,8 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 // parents[2] of src/scripts/<file> is the repo root.
 const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -142,6 +144,24 @@ function main(argv: readonly string[]): number {
         return _selftest();
     }
     const asJson = argv.includes('--json');
+    // Scope is the allowlist itself — there is no tree to walk. An emptied
+    // AUTHORING_FILES scans nothing and reports "No retired source-of-truth
+    // pointers" forever, which is the one result this gate must never produce
+    // by accident. Exit 2 (the usage / self-test class, i.e. the gate could
+    // not run), never 1 — 1 asserts a retired pointer was actually found.
+    try {
+        assertWatchlistResolves({
+            gate: 'check_source_pointer_freshness',
+            candidates: AUTHORING_FILES,
+            repoRoot: ROOT,
+        });
+    } catch (err) {
+        if (err instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${err.message}\n`);
+            return 2;
+        }
+        throw err;
+    }
     const hits: Hit[] = [];
     for (const rel of AUTHORING_FILES) {
         hits.push(..._scanFile(rel));

package/src/scripts/check_structural_breaking.ts

@@ -30,6 +30,8 @@ import * as path from 'node:path';
 import * as fs from 'node:fs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const QUIET = process.argv.includes('--quiet');
 // src/scripts/check_structural_breaking.ts → three levels up is the repo root
 // (Python: Path(__file__).resolve().parent.parent.parent).
@@ -91,12 +93,37 @@ function main(): number {
         return 0; // no trunk to diff against (e.g. shallow CI) → no-op
     }
     const names = _git('diff', '--name-status', `${base}...HEAD`);
-    if (names.trim() === '') {
+    const changed = _splitlines(names);
+    // Replaces the bare `names.trim() === ''` early return: a branch identical
+    // to trunk genuinely changes nothing, so zero is allowed — but it now says
+    // so through the shared primitive instead of a silent `return 0`.
+    // Exit 1 is this pinned CLI's only failure code.
+    try {
+        assertScanned({
+            gate: 'check_structural_breaking',
+            scanned: changed.length,
+            units: 'changed path(s)',
+            roots: [`git diff --name-status ${BASE_REF}...HEAD`],
+            allowEmpty:
+                'EMPTY_VALID: a branch with no diff against trunk has no structural change to ' +
+                'judge — an absent question, not an empty corpus. Deletion test: deleting the ' +
+                'watched artifact trees would show up here as D lines (the very break this gate ' +
+                'reports), so a wiped tree cannot produce this zero. An unresolvable base does ' +
+                'not reach here either — it exits at the no-trunk no-op above.',
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌ ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+    if (changed.length === 0) {
         return 0; // nothing changed vs trunk
     }
 
     const breaks: string[] = [];
-    for (const line of _splitlines(names)) {
+    for (const line of changed) {
         const parts = line.split('\t');
         const status = parts[0]!;
         if (status.startsWith('D') && ARTIFACT_RE.test(parts[1]!)) {

package/src/scripts/check_surface_tiers.ts

@@ -37,6 +37,8 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
 const SCRIPTS = path.join(ROOT, 'src', 'scripts');
 const REGISTRY = path.join(SCRIPTS, 'surface-tiers.yml');
@@ -105,6 +107,20 @@ function check_exhaustive(clusters: Map<string, string>): string[] {
     return errors;
 }
 
+/** Cluster dirs on disk under SCRIPTS — the corpus `check_exhaustive` classifies. */
+function _count_cluster_dirs(): number {
+    let children: fs.Dirent[];
+    try {
+        children = fs.readdirSync(SCRIPTS, { withFileTypes: true });
+    } catch {
+        // A missing root counts zero; the caller's assertion makes that loud.
+        return 0;
+    }
+    return children.filter(
+        (c) => !_IGNORE_DIRS.has(c.name) && _isDir(path.join(SCRIPTS, c.name)),
+    ).length;
+}
+
 function _module_tier(
     dotted: string,
     clusters: Map<string, string>,
@@ -527,6 +543,24 @@ function main(argv?: readonly string[]): number {
         args.skip_imports || envSkip === '1' || envSkip === 'true' || envSkip === 'yes';
 
     const { clusters, lab_modules } = _load_registry();
+    // The unit is the cluster dirs found on disk, not `clusters.size` (the
+    // registry's own entries): over a vanished src/scripts/ every registry
+    // entry goes unchallenged and both assertions are trivially clean.
+    try {
+        assertScanned({
+            gate: 'check_surface_tiers',
+            scanned: _count_cluster_dirs(),
+            units: 'cluster dir(s)',
+            roots: ['src/scripts'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // 1 = violation(s); 2 is reserved for argparse usage errors.
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
     const errors = check_exhaustive(clusters);
     if (skip_imports) {
         process.stdout.write('surface-tiers: import boundary check SKIPPED (kill-switch).\n');

package/src/scripts/check_template_pin_drift.ts

@@ -27,6 +27,7 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { resolve_logical } from './_lib/agent_src.js';
+import { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 // Python `Path(__file__).resolve().parents[2]` — two dirs up from src/scripts.
@@ -159,8 +160,29 @@ function main(argv: readonly string[] = []): number {
         return 1;
     }
 
+    // Scope is two named templates, one of them resolved through
+    // `resolve_logical` — a resolver returning a path under an artefact root
+    // that no longer exists is exactly how this comparison ends up with
+    // nothing to compare. Exit 1: it is this gate's only failure code, and it
+    // already carries the could-not-run meaning (a missing template file is
+    // reported as a failure below); 2 is reserved for CLI misuse.
+    const templates = _template_files();
+    try {
+        assertWatchlistResolves({
+            gate: 'check_template_pin_drift',
+            candidates: templates.map((p) => path.relative(REPO_ROOT, p)),
+            repoRoot: REPO_ROOT,
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  check_template_pin_drift: ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
     const failures: string[] = [];
-    for (const template of _template_files()) {
+    for (const template of templates) {
         const rel = _relToPosixOrAbs(template, REPO_ROOT);
         if (!_isFile(template)) {
             failures.push(`missing template file: ${rel}`);

package/src/scripts/check_test_coverage_diff.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 } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 
 // Injectable for tests (monkeypatch parity): REPO_ROOT, _git_name_status,
@@ -177,7 +179,21 @@ function parse_args(argv: readonly string[]): ParsedArgs {
 
 function main(argv?: readonly string[]): number {
     const opts = parse_args(argv ?? process.argv.slice(2));
-    const changed = _hooks.git_name_status(_resolve_base_ref(opts.base_ref));
+    const base_ref = _resolve_base_ref(opts.base_ref);
+    const changed = _hooks.git_name_status(base_ref);
+    assertScanned({
+        gate: 'check_test_coverage_diff',
+        scanned: changed.length,
+        units: 'changed path(s)',
+        roots: [`git diff --name-status ${base_ref}...HEAD`],
+        allowEmpty:
+            'EMPTY_VALID: a diff with no changed paths adds no gate, so there is nothing for a ' +
+            'coverage forcing-function to warn about. Deletion test: a deleted worktree cannot ' +
+            'produce this state — an UNREADABLE range is a different case and is not silent, ' +
+            '`_git_name_status` prints `⚠️  coverage-diff: git diff failed (…); skipping.` to ' +
+            'stderr before returning empty. The exit code is 0 either way by pinned contract ' +
+            '(warn-only this phase), so this assertion declares the scope rather than gating it.',
+    });
     const [warnings, suppressed] = evaluate(changed, _hooks.pragma_reason_from_tree);
     if (warnings.length > 0) {
         process.stdout.write(

package/src/scripts/check_token_optimizer_freshness.ts

@@ -20,6 +20,7 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { resolve_logical, strip_source_prefix } from './_lib/agent_src.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -150,9 +151,23 @@ function main(): number {
     }
     const text = fs.readFileSync(SKILL, 'utf-8');
     const rows = parse_catalog(text);
-    if (rows.length === 0) {
-        process.stderr.write('ERROR: token-optimizer SKILL.md has no parseable catalog rows\n');
-        return 1;
+    // Supersedes the hand-rolled "no parseable catalog rows" guard: same exit
+    // code and stream, but the shared assertion names the root, so a renamed
+    // `## Catalog` heading or a moved SKILL.md reports as a dead scope instead
+    // of a bare ERROR line.
+    try {
+        assertScanned({
+            gate: 'check_token_optimizer_freshness',
+            scanned: rows.length,
+            units: 'catalog row(s)',
+            roots: [path.relative(REPO_ROOT, SKILL)],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`ERROR: ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
     }
     const allErrs: string[] = [];
     let checked = 0;