@event4u/agent-config 9.20.0 → 9.22.0

package/src/scripts/lint_showcase_sessions.ts

@@ -22,6 +22,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 = fileURLToPath(import.meta.url);
 // src/scripts/lint_showcase_sessions.ts → parent.parent.parent is the repo root.
 const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -174,9 +176,23 @@ function _validate_session(slug: string): string[] {
 }
 
 function main(): number {
-    if (!_isFile(SHOWCASE_MD)) {
-        process.stderr.write(`❌  ${_relTo(SHOWCASE_MD, ROOT)} not found\n`);
-        return 1;
+    // There is no corpus to count — "0 referenced, 0 on disk" is the shipped
+    // state and a legitimate pass. The one thing that must resolve is the
+    // manifest both rules are derived from: with showcase.md gone there are no
+    // references, so no missing file and no orphan can ever be reported.
+    // Supersedes the previous bare `_isFile` check, same exit code.
+    try {
+        assertWatchlistResolves({
+            gate: 'lint_showcase_sessions',
+            candidates: [_relTo(SHOWCASE_MD, ROOT)],
+            repoRoot: ROOT,
+        });
+    } catch (e) {
+        if (e instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${e.message}\n`);
+            return 1;
+        }
+        throw e;
     }
 
     const text = fs.readFileSync(SHOWCASE_MD, 'utf-8');

package/src/scripts/lint_skill_descriptions.ts

@@ -61,6 +61,7 @@ import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 
 import { OVERLAP_THRESHOLD, _cosine, collect } from './audit_skill_overlap.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 import { parse_frontmatter } from './skill_overlap.js';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -289,6 +290,24 @@ function main(argv: string[]): number {
         }
     }
 
+    // `skillMds` yields nothing for a root that does not exist, so a moved
+    // `src/skills` would report "no description defects" over zero skills —
+    // routing quality certified against an empty corpus.
+    try {
+        assertScanned({
+            gate: 'lint_skill_descriptions',
+            scanned,
+            units: 'skill(s)',
+            roots: [path.relative(REPO, args.root) || args.root],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
     if (args.json) {
         fs.mkdirSync(path.dirname(args.json), { recursive: true });
         fs.writeFileSync(args.json, JSON.stringify({ scanned, violations }, null, 2) + '\n');

package/src/scripts/lint_skill_frontmatter_safety.ts

@@ -27,6 +27,7 @@ import * as fs from 'node:fs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import * as sl from './_lib/security_lint.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 export const CHECK = 'dangerous-frontmatter';
 
@@ -258,12 +259,35 @@ export function main(argv: readonly string[] | null = null): number {
 
     const findings: sl.Finding[] = [];
     const roots = ['src/skills', 'src/agent-src', 'src/domains'];
+    let scanned = 0;
     for (const sf of sl.iter_corpus(roots, ['.md'])) {
+        scanned += 1;
         for (const h of _scan(sf)) {
             findings.push(h);
         }
     }
 
+    // `iter_corpus` skips a root that does not exist, so all three moving at
+    // once yields zero files and a clean report — the quietest possible failure
+    // for a security lint. `scanned` counts files READ, never findings: zero
+    // findings over 900 files is the success state, zero files is blindness.
+    // Exit 1 = "this gate is not clean" (reds the build); 2 stays the argv
+    // usage code that `parse_args` owns.
+    try {
+        assertScanned({
+            gate: 'lint_skill_frontmatter_safety',
+            scanned,
+            units: 'markdown file(s)',
+            roots,
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
     if (args.json) {
         const payload = sl.py_json_dumps_indent2(findings.map((f) => f.toDict()));
         process.stdout.write(payload + '\n');

package/src/scripts/lint_skill_originality.ts

@@ -55,6 +55,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 { jaccard, parse_frontmatter, tokenize } from './skill_overlap.js';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -257,9 +258,23 @@ function main(argv?: readonly string[]): number {
     const args = parse_args(argv ?? process.argv.slice(2));
 
     const skills = load_skills(SKILLS);
-    if (skills.length === 0) {
-        process.stderr.write(`no skills under ${SKILLS}\n`);
-        return 1;
+    try {
+        assertScanned({
+            gate: 'lint_skill_originality',
+            scanned: skills.length,
+            units: 'skill(s)',
+            roots: ['src/skills'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // The `no skills under <root>` line is part of the pinned CLI
+            // contract, so it stays first; the assertion's named-root detail
+            // follows it rather than replacing it.
+            process.stderr.write(`no skills under ${SKILLS}\n`);
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
     }
     const allow = load_allowlist();
     const findings = analyse(skills, allow);

package/src/scripts/lint_skill_scripts_readonly.ts

@@ -28,6 +28,8 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 const REPO = path.resolve(path.dirname(_HERE), '..', '..');
 const DEFAULT_SKILLS = path.join(REPO, 'src', 'skills');
@@ -127,6 +129,24 @@ function main(argv: string[]): number {
         violations.push({ rel, detail: 'contains a content-mutation primitive but no write-gating flag (--writable/--apply/--write/--out/--fix) and is not allowlisted' });
     }
 
+    // `scanned` is the script files read, which is also the number the success
+    // line publishes; a `--root` that resolves to nothing would otherwise
+    // report every script gated while having opened none.
+    try {
+        assertScanned({
+            gate: 'lint_skill_scripts_readonly',
+            scanned,
+            units: 'skill script(s)',
+            roots: [args.root === DEFAULT_SKILLS ? 'src/skills' : args.root],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
     if (violations.length > 0) {
         process.stderr.write(`❌  lint_skill_scripts_readonly: ${violations.length} ungated write(s):\n`);
         for (const v of violations) process.stderr.write(`   ${v.rel} — ${v.detail}\n`);

package/src/scripts/lint_skill_tools.ts

@@ -1,161 +1,71 @@
 #!/usr/bin/env tsx
 /**
- * Block D · D1 meta-linter for `scripts/skill_tools/*.py`.
+ * Block D · D1 meta-linter for `src/scripts/skill_tools/*.ts` (ADR-006).
  *
- * Ported from the retired Python `src/scripts/lint_skill_tools.py` (ADR-200,
- * Phase 4 / Wave 4b). The CLI contract is pinned — `--json`
- * / `--quiet` / `--tools-dir` flags, exit codes (0 clean, 1 violations,
- * 2 usage / missing-dir), stdout split (JSON or human), byte-identical
- * violation strings, same glob + sort order, same `_SAMPLE`/`__main__`
- * detection.
+ * ## Why this gate changed shape (2026-08-05)
  *
- * the retired Python implementation parses each tool with `ast` to find imports and
- * syntax errors. We replicate the import discovery with a focused
- * Python-import line scanner (handles `import a, b.c`, `from x.y import z`,
- * relative `from . import x`). It covers the real tools and the test
- * fixtures; an `import`/`from` keyword appearing as the first token of a
- * line inside a multi-line string literal would be a false positive the
- * `ast` walk avoids — flagged as a divergence candidate, not observed in
- * the corpus.
+ * ADR-006 piloted these tools in Python and this gate enforced five invariants
+ * over `skill_tools/*.py`. ADR-200 migrated the corpus to `.ts` without
+ * mentioning ADR-006, so the glob matched nothing: for ~7 weeks the gate printed
+ * `✅ scripts/skill_tools/ — all tools clean.` over **zero** tools on every CI
+ * run, and nobody noticed that two ADR-006 invariants had quietly gone unmet on
+ * the TS surface (`--help` in 0 of 6 files; `_SAMPLE` in 3 of 5).
  *
- * No behaviour changes.
+ * Repointing the glob and keeping all five checks was measured and rejected: the
+ * TS ports are 2.4–4.0× their Python originals (92–142 LOC → 253–470), so the
+ * 200-LOC cap reds 5 of 5 tools, and the only way to green it is raising the cap
+ * to ≥ 470 — threshold-lowering, which this gate's own ratchet exists to
+ * prevent. AI council 2026-08-05 resolved it as extract-the-checkable:
+ *
+ * - **KEPT** (pure regex over filename + text, no analyser): `snake_case_verb_noun`
+ *   naming, a registered `--json` flag, and an embedded `_SAMPLE` or CLI-entry guard.
+ * - **DROPPED, recorded in ADR-006's Status**: the 200-LOC cap (cannot pass
+ *   without weakening its own threshold); the `argparse` import and
+ *   `add_help=False` checks (no TypeScript analogue); and the stdlib-only import
+ *   scan (a Python `ast`-shaped scanner — re-implementing it for TS specifiers
+ *   would be a new analyser, not a port, and the council drew that line
+ *   explicitly for the sibling `lint_workspace_boundary` decision).
+ *
+ * The gate now asserts its scan scope, so an emptied or moved corpus fails
+ * loudly instead of certifying nothing. No `allowEmpty`: "no tools" must never
+ * read as "all tools clean" again.
+ *
+ * CLI contract unchanged — `--json` / `--quiet` / `--tools-dir`, exit codes
+ * (0 clean, 1 violations, 2 usage / missing-dir / dead scope), stdout split.
  */
 
 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/lint_skill_tools.ts → parents[2] is the repo root.
 const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 const TOOLS_DIR = path.join(ROOT, 'src', 'scripts', 'skill_tools');
-const NAME_RE = /^[a-z][a-z0-9]*(?:_[a-z0-9]+)+\.py$/;
-const SIZE_CAP = 200;
-
-const STDLIB: ReadonlySet<string> = new Set([
-    '__future__', 'abc', 'argparse', 'ast', 'base64', 'collections', 'configparser',
-    'contextlib', 'copy', 'csv', 'dataclasses', 'datetime', 'decimal', 'difflib',
-    'enum', 'errno', 'fnmatch', 'functools', 'glob', 'gzip', 'hashlib', 'heapq',
-    'html', 'http', 'importlib', 'inspect', 'io', 'ipaddress', 'itertools', 'json',
-    'logging', 'math', 'mimetypes', 'os', 'pathlib', 'pickle', 'platform', 'posixpath',
-    'pprint', 'queue', 'random', 're', 'shlex', 'shutil', 'signal', 'socket',
-    'sqlite3', 'ssl', 'stat', 'string', 'struct', 'subprocess', 'sys', 'tempfile',
-    'textwrap', 'threading', 'time', 'tomllib', 'traceback', 'types', 'typing',
-    'unicodedata', 'unittest', 'urllib', 'uuid', 'venv', 'warnings', 'weakref',
-    'xml', 'zipfile', 'zlib',
-]);
-const PROJECT_PACKAGES: ReadonlySet<string> = new Set(['scripts', 'skill_tools']);
-
-interface ParsedImport {
-    kind: 'import';
-    modules: string[]; // dotted module names from `import a, b.c as d`
-}
-interface ParsedFromImport {
-    kind: 'from';
-    module: string | null; // None for `from . import x` (level > 0)
-    level: number;
-}
-type ImportNode = ParsedImport | ParsedFromImport;
-
-/**
- * Scan a Python source for top-of-line `import` / `from … import` statements.
- * Mirrors what `ast.walk` surfaces for `Import` / `ImportFrom` nodes (the
- * linter only reads `.names`, `.module`, `.level`). Continuation lines inside
- * a parenthesised `from x import (...)` do not affect the module name (which
- * sits before `import` on the opening line), so they need no special handling.
- */
-function _parse_imports(text: string): ImportNode[] {
-    const out: ImportNode[] = [];
-    for (const raw of text.split('\n')) {
-        const stripped = raw.replace(/^[ \t]+/, '');
-        const importMatch = /^import\s+(.+)$/.exec(stripped);
-        if (importMatch) {
-            const rest = importMatch[1]!.replace(/#.*$/, '');
-            const modules: string[] = [];
-            for (const part of rest.split(',')) {
-                // `a.b.c as d` → dotted name is the token before `as`.
-                const name = part.trim().split(/\s+as\s+/)[0]!.trim();
-                if (name) {
-                    modules.push(name);
-                }
-            }
-            out.push({ kind: 'import', modules });
-            continue;
-        }
-        const fromMatch = /^from\s+(\.*)([A-Za-z0-9_.]*)\s+import\b/.exec(stripped);
-        if (fromMatch) {
-            const dots = fromMatch[1]!;
-            const mod = fromMatch[2]!;
-            const level = dots.length;
-            // ast: `from . import x` → module is None when no dotted name follows.
-            const module = mod === '' ? null : mod;
-            out.push({ kind: 'from', module, level });
-            continue;
-        }
-    }
-    return out;
-}
+const NAME_RE = /^[a-z][a-z0-9]*(?:_[a-z0-9]+)+\.ts$/;
 
 function _violations_for(p: string): string[] {
     const out: string[] = [];
     const name = path.basename(p);
     if (!NAME_RE.test(name)) {
-        out.push(`naming: \`${name}\` is not snake_case_verb_noun.py`);
+        out.push(`naming: \`${name}\` is not snake_case_verb_noun.ts`);
     }
 
     const text = fs.readFileSync(p, 'utf-8');
-    let loc = 0;
-    for (const ln of text.split('\n')) {
-        if (ln.trim() && !ln.replace(/^[ \t]+/, '').startsWith('#')) {
-            loc += 1;
-        }
-    }
-    if (loc > SIZE_CAP) {
-        out.push(`size: ${loc} LOC > ${SIZE_CAP} cap`);
-    }
-
-    // Imports — flag any non-stdlib, non-project top-level module + record argparse.
-    const imported = new Set<string>();
-    for (const node of _parse_imports(text)) {
-        if (node.kind === 'import') {
-            for (const dotted of node.modules) {
-                const root = dotted.split('.')[0]!;
-                imported.add(root);
-                if (!STDLIB.has(root) && !PROJECT_PACKAGES.has(root)) {
-                    out.push(`stdlib-only: imports \`${dotted}\` (third-party)`);
-                }
-            }
-        } else {
-            if (node.module === null || node.level > 0) {
-                continue; // relative imports — package-internal
-            }
-            const root = node.module.split('.')[0]!;
-            imported.add(root);
-            if (!STDLIB.has(root) && !PROJECT_PACKAGES.has(root)) {
-                out.push(`stdlib-only: imports from \`${node.module}\` (third-party)`);
-            }
-        }
-    }
 
-    // CLI flags — confirm argparse is imported and `--json` is registered.
-    const hasArgparse = imported.has('argparse');
-    const hasJsonFlag = /['"]--json['"]/.test(text);
-    if (!hasArgparse) {
-        out.push('cli: no `argparse` import detected');
-    }
-    if (!hasJsonFlag) {
+    // Machine-readable output — the tool must register a `--json` flag.
+    if (!/['"]--json['"]/.test(text)) {
         out.push('cli: missing `--json` flag');
     }
-    if (/add_help\s*=\s*False/.test(text)) {
-        out.push('cli: `add_help=False` disables --help');
-    }
 
-    // Embedded sample data — `_SAMPLE` constant or a `__main__` block.
-    const hasSample = /^_SAMPLE\s*[:=]/m.test(text);
-    const hasMain =
-        text.includes('__name__ == "__main__"') || text.includes("__name__ == '__main__'");
-    if (!(hasSample || hasMain)) {
-        out.push('sample: no `_SAMPLE` constant or `__main__` block');
+    // Embedded sample data — an exported-or-bare `_SAMPLE` constant, or the
+    // CLI-entry guard that replaced Python's `__main__` block.
+    const hasSample = /^\s*(?:export\s+)?(?:const|let)?\s*_SAMPLE\s*[:=]/m.test(text);
+    const hasEntry = text.includes('import.meta.url');
+    if (!(hasSample || hasEntry)) {
+        out.push('sample: no `_SAMPLE` constant or CLI-entry guard');
     }
 
     return out;
@@ -191,8 +101,8 @@ function lint(toolsDir: string): [number, Record<string, string[]>] {
     } catch {
         entries = [];
     }
-    const pyFiles = entries
-        .filter((n) => n.endsWith('.py'))
+    const toolFiles = entries
+        .filter((n) => n.endsWith('.ts') && !n.endsWith('.d.ts') && !n.endsWith('.test.ts'))
         .map((n) => path.join(resolved, n))
         .filter((p) => {
             try {
@@ -202,10 +112,14 @@ function lint(toolsDir: string): [number, Record<string, string[]>] {
             }
         })
         .sort();
-    for (const p of pyFiles) {
-        if (path.basename(p) === '__init__.py') {
+    let linted = 0;
+    for (const p of toolFiles) {
+        // `index.ts` is the package marker — the `__init__.py` analogue. It is a
+        // re-export barrel, not a tool, so the per-tool invariants do not apply.
+        if (path.basename(p) === 'index.ts') {
             continue;
         }
+        linted += 1;
         const viols = _violations_for(p);
         if (viols.length > 0) {
             // Mirror Python's `str(path.relative_to(ROOT))` with ValueError fallback.
@@ -213,9 +127,24 @@ function lint(toolsDir: string): [number, Record<string, string[]>] {
             findings[key] = viols;
         }
     }
+    _lintedCount = linted;
     return [Object.keys(findings).length > 0 ? 1 : 0, findings];
 }
 
+/**
+ * Tools actually inspected by the last `lint()` call.
+ *
+ * Kept out of `lint()`'s return value on purpose: 13 unit tests drive `lint()`
+ * directly and assert its `[code, findings]` shape, and the scan-scope assertion
+ * must fire once per process in `main()` — not inside a function the tests call
+ * with temp dirs, where an empty fixture is legitimate.
+ */
+let _lintedCount = 0;
+
+export function lintedCount(): number {
+    return _lintedCount;
+}
+
 function _print_human(findings: Record<string, string[]>): void {
     if (Object.keys(findings).length === 0) {
         process.stdout.write('✅  scripts/skill_tools/ — all tools clean.\n');
@@ -292,6 +221,25 @@ function main(argv?: readonly string[]): number {
     const args = parse_args(argv ?? process.argv.slice(2));
 
     const [code, findings] = lint(args.toolsDir);
+    // Scan-scope assertion. Deliberately after `lint()` (which computes the
+    // count) and before the report, so a moved or emptied corpus fails loudly
+    // instead of printing "all tools clean" over zero tools — which is exactly
+    // what this gate did for ~7 weeks after ADR-200 deleted its `.py` corpus.
+    // No `allowEmpty`: an empty tools dir here is blindness, not success.
+    try {
+        assertScanned({
+            gate: 'lint_skill_tools',
+            scanned: lintedCount(),
+            units: 'tool(s)',
+            roots: ['src/scripts/skill_tools'],
+        });
+    } catch (e) {
+        if (e instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${e.message}\n`);
+            return 2; // the gate's existing "internal / usage" code
+        }
+        throw e;
+    }
     if (args.json) {
         process.stdout.write(_json_dumps_ascii({ exit_code: code, findings }));
         process.stdout.write('\n');
@@ -327,13 +275,4 @@ if (_isCliEntry() || process.argv[1] === _HERE) {
     process.exit(main());
 }
 
-export {
-    ROOT,
-    TOOLS_DIR,
-    NAME_RE,
-    SIZE_CAP,
-    STDLIB,
-    PROJECT_PACKAGES,
-    lint,
-    main,
-};
+export { ROOT, TOOLS_DIR, NAME_RE, lint, main };

package/src/scripts/lint_spawn_payload.ts

@@ -41,6 +41,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, '..', '..');
 
@@ -204,9 +206,14 @@ function scanMarkdownTranscript(filePath: string, repoRoot: string): Finding[] {
 
 function scanRepo(repoRoot: string): Finding[] {
     const findings: Finding[] = [];
+    // Counted before the `*spawn*.json` / spawn-context filters: those decide
+    // what is JUDGED, and both are legitimately zero on a clean tree. Only the
+    // walk itself distinguishes "no spawn payloads" from "no files read".
+    let scanned = 0;
 
     const fixturesDir = path.join(repoRoot, 'tests', 'fixtures');
     for (const f of walkFiles(fixturesDir)) {
+        scanned += 1;
         if (f.endsWith('.json') && /spawn/i.test(path.basename(f))) {
             findings.push(...scanJsonFixture(f, repoRoot));
         }
@@ -216,11 +223,18 @@ function scanRepo(repoRoot: string): Finding[] {
     if (fs.existsSync(transcriptsDir)) {
         for (const entry of fs.readdirSync(transcriptsDir, { withFileTypes: true })) {
             if (entry.isFile() && entry.name.endsWith('.md')) {
+                scanned += 1;
                 findings.push(...scanMarkdownTranscript(path.join(transcriptsDir, entry.name), repoRoot));
             }
         }
     }
 
+    assertScanned({
+        gate: 'lint_spawn_payload',
+        scanned,
+        units: 'fixture / transcript file(s)',
+        roots: ['tests/fixtures', 'tests/reasoning-layer-eval/golden-transcripts'],
+    });
     return findings;
 }
 
@@ -234,7 +248,19 @@ function parseArgs(argv: readonly string[]): { strict: boolean; quiet: boolean }
 function main(argv?: readonly string[], repoRootOverride?: string): number {
     const args = parseArgs(argv ?? process.argv.slice(2));
     const root = repoRootOverride ?? REPO_ROOT;
-    const findings = scanRepo(root);
+    let findings: Finding[];
+    try {
+        findings = scanRepo(root);
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // 2 is this gate's only non-zero code. Returning it without
+            // `--strict` is deliberate: warn-only governs FINDINGS, and a dead
+            // scope means there were none to warn about.
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 2;
+        }
+        throw exc;
+    }
 
     if (!args.quiet) {
         for (const f of findings) {

package/src/scripts/lint_store_boundary.ts

@@ -29,6 +29,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 export const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 
@@ -113,6 +115,23 @@ export function main(argv: string[] = process.argv.slice(2)): number {
             return 2;
         }
     }
+    // SCAN_FILES is a hand-maintained watch list and `scanFile` swallows a read
+    // error, so a renamed or moved index module drops out of scope silently and
+    // the gate reports "clean" over the files it can no longer read. Exit 3 is
+    // the "this gate could not run" code; 1 stays "violations found".
+    try {
+        assertWatchlistResolves({
+            gate: 'lint_store_boundary',
+            candidates: SCAN_FILES,
+            repoRoot: root,
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 3;
+        }
+        throw exc;
+    }
     let violations: Violation[];
     try {
         violations = run(root);

package/src/scripts/lint_subagent_determinism.ts

@@ -24,6 +24,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 { parse_frontmatter } from './validate_frontmatter.js';
 
 const QUIET = process.argv.includes('--quiet');
@@ -47,7 +48,28 @@ function main(dir: string = SUBAGENT_DIR): number {
     const findings: string[] = [];
     const namesSeen = new Map<string, string>();
 
-    for (const file of _listSubagents(dir)) {
+    const files = _listSubagents(dir);
+    // The unit is every `.md` walked, not `namesSeen` — that map only grows on
+    // units that already passed the stem-match, so it reads 0 both for a moved
+    // root and for a corpus where every unit is broken.
+    try {
+        assertScanned({
+            gate: 'lint_subagent_determinism',
+            scanned: files.length,
+            units: 'subagent file(s)',
+            roots: [dir],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // 1 is this gate's only non-zero code; here it means "could not
+            // run", not "found a determinism violation".
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
+    for (const file of files) {
         const rel = path.relative(REPO, file);
         const stem = path.basename(file, '.md');
         const text = fs.readFileSync(file, 'utf-8');

package/src/scripts/lint_supported_tools_matrix.ts

@@ -12,6 +12,7 @@ import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { lint_matrix } from './_lib/tool_adapter_registry.js';
+import { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.join(path.dirname(_HERE), '..', '..');
@@ -25,6 +26,23 @@ const isMain = process.argv[1] !== undefined && path.resolve(process.argv[1]) ==
 if (isMain) {
     const idx = process.argv.indexOf('--readme');
     const readmePath = idx !== -1 ? (process.argv[idx + 1] ?? '') : path.join(REPO_ROOT, 'README.md');
+    // The whole README leg of this gate is one named file. A moved README turns
+    // `run()` into an ENOENT stack trace, which reads as a crash rather than as
+    // a gate whose scope died — name the scope first. Exit 1 is the gate's only
+    // failure code; here it means "could not run", not "found drift".
+    try {
+        assertWatchlistResolves({
+            gate: 'lint_supported_tools_matrix',
+            candidates: [path.relative(REPO_ROOT, path.resolve(readmePath))],
+            repoRoot: REPO_ROOT,
+        });
+    } catch (e) {
+        if (e instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${e.message}\n`);
+            process.exit(1);
+        }
+        throw e;
+    }
     const errors = run(readmePath);
     if (errors.length > 0) {
         for (const e of errors) process.stderr.write(`❌  ${e}\n`);