@event4u/agent-config 9.19.0 → 9.21.0

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_review_dispositions.ts

@@ -0,0 +1,188 @@
+#!/usr/bin/env tsx
+/**
+ * Archived-review disposition check (contract §2.7 + §2.2).
+ *
+ * Gate R2 selects only artefacts relevant to the CURRENT review scope (§2.6),
+ * and superseded rounds are renamed out of the `*.findings.md` glob on purpose.
+ * The consequence nobody noticed until it bit: **no validator reads archived
+ * round records at all**, so a finding left `open` after it was fixed is caught
+ * by nothing. That is exactly how two fixed findings sat recorded as `open` for
+ * a day in this repo's own corpus.
+ *
+ * This closes that gap with the smallest mechanism that covers the observed
+ * failure: archiving a round asserts the round is CLOSED, so every row in an
+ * archived record must carry a terminal status and a non-empty Reason/Ref.
+ *
+ * Deliberately NOT the disposition index with stable ids that was originally
+ * proposed. That design assumed dispositions live OUTSIDE the round records;
+ * measured across the corpus, they do not — records are terminal in place. An
+ * index would be a second artefact to keep in sync, and therefore a new drift
+ * source, guarding a failure mode that has not occurred. Trigger to revisit: a
+ * disposition that genuinely cannot be recorded in the round record itself.
+ *
+ * Scope: `*-review.md` under the reviews root, excluding `*.findings.md` (those
+ * are live artefacts and belong to `check_completion_review`).
+ *
+ * Reference SHAPE is deliberately NOT checked, and that was a measurement, not
+ * a preference. The first draft resolved a `fixed` ref via `rev-parse` and a
+ * `deferred` ref via a path probe. Run against the real corpus it produced 8
+ * blocks — every one of them a pre-existing archived record whose reference is
+ * prose describing the change, or a carrier named by bare slug. None of the 8
+ * was the failure this gate exists to catch. Archived records are frozen
+ * (§2.7), so a shape rule cannot be satisfied retroactively without editing
+ * them; a gate whose only output is unfixable blocks is the gate that gets
+ * switched off. Trigger to revisit: a review round where an unresolvable
+ * reference actually hid a disposition, on a record written AFTER this gate
+ * shipped and therefore fixable at source.
+ *
+ * Exit codes (contract §6): 0 = pass, 1 = policy violation (including a DEAD
+ * SCAN SCOPE — a gate that read nothing has not passed), 2 = internal error
+ * (the CALLER applies degraded advisory mode). `scanned:` is emitted on EVERY
+ * exit path, exit 2 included.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { DeadScopeError, assertScanned } from './_lib/scan_scope.js';
+import { parseArtifact } from './check_completion_review.js';
+
+const REVIEWS_ROOT = 'agents/evidence/reviews';
+const TERMINAL = new Set(['fixed', 'accepted-risk', 'deferred']);
+
+export interface Violation {
+    kind: string;
+    file: string;
+    detail: string;
+}
+
+/** An archived record: a `*-review.md` that is not a live `*.findings.md`. */
+export function isArchivedRecord(rel: string): boolean {
+    const base = rel.replace(/\\/g, '/').split('/').pop() ?? '';
+    return base.endsWith('-review.md') && !base.endsWith('.findings.md');
+}
+
+export interface CheckOptions {
+    repo: string;
+}
+
+/** Contract §2.7: every row of an archived record is terminal, with its reference. */
+export function checkRecord(rel: string, text: string, _opts: CheckOptions): Violation[] {
+    const violations: Violation[] = [];
+    const parsed = parseArtifact(text);
+    for (const row of parsed.rows) {
+        const where = `row ${row.index} (line ${String(row.line)})`;
+        if (row.status === 'open') {
+            violations.push({
+                kind: 'open-in-archived-record',
+                file: rel,
+                detail:
+                    `${where}: status \`open\` in an ARCHIVED record. Renaming a round out of the ` +
+                    '`*.findings.md` glob asserts it is closed, so every row must already be terminal ' +
+                    '(`fixed` / `accepted-risk` / `deferred`) — contract §2.7.',
+            });
+            continue;
+        }
+        if (!TERMINAL.has(row.status)) {
+            violations.push({
+                kind: 'bad-status',
+                file: rel,
+                detail: `${where}: unknown status \`${row.status}\` — expected fixed / accepted-risk / deferred.`,
+            });
+            continue;
+        }
+        if (row.reasonRef.trim() === '') {
+            violations.push({
+                kind: 'missing-reference',
+                file: rel,
+                detail: `${where}: status \`${row.status}\` requires a Reason/Ref, which is empty.`,
+            });
+        }
+    }
+    return violations;
+}
+
+export function main(argv?: readonly string[]): number {
+    const args = argv ?? process.argv.slice(2);
+    let repo = process.cwd();
+    let root = REVIEWS_ROOT;
+    let quiet = false;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i] as string;
+        if (a === '--repo') repo = args[++i] as string;
+        else if (a === '--reviews-root') root = args[++i] as string;
+        else if (a === '--quiet') quiet = true;
+        else if (a === '-h' || a === '--help') {
+            process.stdout.write('usage: check_review_dispositions [--repo PATH] [--reviews-root PATH] [--quiet]\n');
+            process.stdout.write('scanned: 0\n');
+            return 0;
+        }
+    }
+
+    const abs = path.resolve(repo, root);
+    let files: string[] = [];
+    try {
+        files = fs
+            .readdirSync(abs, { withFileTypes: true })
+            .filter((e) => e.isFile() && isArchivedRecord(e.name))
+            .map((e) => path.join(root, e.name))
+            .sort();
+    } catch {
+        // Absent root: report it as a DEAD SCOPE below rather than a clean pass.
+        files = [];
+    }
+
+    try {
+        assertScanned({
+            gate: 'check_review_dispositions',
+            scanned: files.length,
+            units: 'archived review record(s)',
+            roots: [root],
+        });
+    } catch (exc) {
+        // A dead scan scope is a POLICY violation (exit 1), never an internal
+        // error: exit 2 is warn-and-allow at every call site, so a moved reviews
+        // root would silently degrade this gate to advisory.
+        process.stdout.write('scanned: 0\n');
+        process.stderr.write(`❌  ${exc instanceof DeadScopeError ? exc.message : String(exc)}\n`);
+        return 1;
+    }
+
+    const violations: Violation[] = [];
+    let scanned = 0;
+    try {
+        for (const rel of files) {
+            const text = fs.readFileSync(path.resolve(repo, rel), 'utf-8');
+            scanned += 1;
+            violations.push(...checkRecord(rel, text, { repo }));
+        }
+    } catch (exc) {
+        process.stdout.write(`scanned: ${String(scanned)}\n`);
+        process.stderr.write(
+            `❌  check_review_dispositions: internal error after ${String(scanned)} record(s): ` +
+                `${exc instanceof Error ? exc.message : String(exc)}\n`,
+        );
+        return 2;
+    }
+
+    if (violations.length > 0) {
+        process.stdout.write(`❌  ${String(violations.length)} disposition violation(s):\n\n`);
+        for (const v of violations) {
+            process.stdout.write(`  ${v.kind} — ${v.file}\n    │ ${v.detail}\n`);
+        }
+    } else if (!quiet) {
+        process.stdout.write(`✅  Archived review records all terminal (${String(scanned)} record(s) scanned).\n`);
+    }
+    process.stdout.write(`scanned: ${String(scanned)}\n`);
+    return violations.length > 0 ? 1 : 0;
+}
+
+const _HERE = fileURLToPath(import.meta.url);
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    return import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href || process.argv[1] === _HERE;
+}
+if (_isCliEntry()) {
+    process.exit(main());
+}

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}`);