@event4u/agent-config 9.20.0 → 9.21.0

package/src/scripts/check_gate_paths.ts

@@ -20,7 +20,9 @@
  * synchronous. No behaviour changes.
  *
  * Exit codes: 0 = all enforced targets resolve under the source tree ·
- * 1 = at least one missing / out-of-tree target · 2 = a gate failed to import.
+ * 1 = at least one missing / out-of-tree target · 2 = a gate failed to import
+ * (which now includes a dead scan scope — zero enforced targets across the
+ * whole GATES list — reported through `_lib/scan_scope`).
  */
 
 import { spawnSync } from 'node:child_process';
@@ -28,6 +30,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), '..', '..');
 
@@ -190,6 +194,31 @@ function main(): number {
         process.stderr.write(`❌  check-gate-paths: ${msg}\n`);
         return 2;
     }
+    let total = 0;
+    for (const v of named.values()) {
+        total += v.length;
+    }
+    // The enforced targets ARE the corpus. A per-gate empty GATE_CORE_PATHS is
+    // already exit 2 inside the subprocess, but an emptied GATES list is not:
+    // it yields zero targets, zero failures, and a green "0 enforced target(s)
+    // … resolve" — the path-integrity gate certifying that nothing is enforced.
+    try {
+        assertScanned({
+            gate: 'check_gate_paths',
+            scanned: total,
+            units: 'enforced target(s)',
+            roots: ['src/scripts (GATE_CORE_PATHS of the GATES list)'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // Exit 2, not 1: 1 means "a declared target failed to resolve" (a
+            // finding), while 2 is this file's existing "a gate cannot be
+            // checked" code — which is exactly what an empty target set is.
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 2;
+        }
+        throw exc;
+    }
     const failures = check_paths(named);
     if (failures.length > 0) {
         process.stdout.write(
@@ -202,10 +231,6 @@ function main(): number {
         process.stdout.write('  GATE_CORE_PATHS or the move.\n');
         return 1;
     }
-    let total = 0;
-    for (const v of named.values()) {
-        total += v.length;
-    }
     process.stdout.write(
         `✅  check-gate-paths: ${total} enforced target(s) across ` +
             `${named.size} gate(s) resolve under the source tree.\n`,

package/src/scripts/check_generated_artefact_headers.ts

@@ -15,6 +15,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);
 const REPO_ROOT = path.join(path.dirname(_HERE), '..', '..');
 
@@ -55,6 +57,25 @@ function main(argv?: readonly string[]): number {
     const args = argv ?? process.argv.slice(2);
     const quiet = args.includes('--quiet');
 
+    // Every artefact is skipped when absent, so all three moving at once prints
+    // "✅ All 3 generated artefacts carry the freshness marker" over zero reads.
+    // The per-file skip below stays — a single gitignored artefact is a real
+    // state; none of them existing is a moved root. 1 is the only failure code
+    // this gate has, so "could not run" and "found something" share it.
+    try {
+        assertWatchlistResolves({
+            gate: 'check_generated_artefact_headers',
+            candidates: GENERATED_ARTEFACTS.map((e) => e.path),
+            repoRoot: REPO_ROOT,
+        });
+    } catch (err) {
+        if (err instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${err.message}\n`);
+            return 1;
+        }
+        throw err;
+    }
+
     const errors: string[] = [];
     const warnings: string[] = [];
 

package/src/scripts/check_generator_output_coverage.ts

@@ -18,6 +18,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.join(path.dirname(_HERE), '..', '..');
 
@@ -103,6 +105,27 @@ function main(argv?: readonly string[]): number {
             .filter((l) => Boolean(l) && !l.startsWith('#')),
     );
 
+    // The registry below is the corpus — the manifest and .gitignore are only
+    // what each root is checked AGAINST, and both already fail closed above. An
+    // emptied registry (a refactor that moves the list, a bad merge) leaves the
+    // loop with nothing to classify and prints "✅ All 0 generator output roots
+    // are classified". Exit 2, the code this gate already uses for "a required
+    // input is not there", never 1, which means a root is unclassified.
+    try {
+        assertScanned({
+            gate: 'check_generator_output_coverage',
+            scanned: GENERATOR_OUTPUT_ROOTS.length,
+            units: 'generator output root(s)',
+            roots: ['src/scripts/check_generator_output_coverage.ts (GENERATOR_OUTPUT_ROOTS)'],
+        });
+    } catch (err) {
+        if (err instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${err.message}\n`);
+            return 2;
+        }
+        throw err;
+    }
+
     const unclassified: typeof GENERATOR_OUTPUT_ROOTS[number][] = [];
     for (const entry of GENERATOR_OUTPUT_ROOTS) {
         if (!isClassified(entry.root, manifestPaths, gitignoreLines)) {

package/src/scripts/check_gitignore_freshness.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 REPO_ROOT = path.join(path.dirname(_HERE), '..', '..');
 
@@ -83,6 +85,27 @@ function main(argv?: readonly string[]): number {
     const blockLines = new Set(blockText.split('\n').map((l) => l.trim()).filter(Boolean));
 
     const entries = parseManifest(manifestText);
+    // Counted on the whole parse, not on the consumer-scoped subset the loop
+    // judges: `_isFile` above only proves the manifest exists, and a shape change
+    // that makes `- path:` stop matching yields zero entries, zero missing paths,
+    // and "✅ covers all 0 consumer-scoped ignored paths". Exit 2 (documented
+    // "invalid args or missing file" — the gate could not run), not 1, which
+    // means the block is genuinely missing a path.
+    try {
+        assertScanned({
+            gate: 'check_gitignore_freshness',
+            scanned: entries.length,
+            units: 'manifest entr(y|ies)',
+            roots: ['src/config/agents-paths.yml'],
+        });
+    } catch (err) {
+        if (err instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${err.message}\n`);
+            return 2;
+        }
+        throw err;
+    }
+
     const missing: string[] = [];
 
     for (const e of entries) {

package/src/scripts/check_host_loadability.ts

@@ -16,10 +16,14 @@ import * as path from 'node:path';
 
 import { parse as parseYaml } from 'yaml';
 
-export function check_claude_skills(root: string, errors: string[]): void {
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
+/** @returns how many skill directories were examined. */
+export function check_claude_skills(root: string, errors: string[]): number {
     const dir = path.join(root, '.claude', 'skills');
-    if (!fs.existsSync(dir)) return;
-    for (const name of fs.readdirSync(dir)) {
+    if (!fs.existsSync(dir)) return 0;
+    const names = fs.readdirSync(dir);
+    for (const name of names) {
         const skillMd = path.join(dir, name, 'SKILL.md');
         if (!fs.existsSync(skillMd)) {
             errors.push(`${skillMd}: missing SKILL.md`);
@@ -35,13 +39,17 @@ export function check_claude_skills(root: string, errors: string[]): void {
         else if (meta['name'] !== name) errors.push(`${skillMd}: name '${meta['name']}' != dir '${name}'`);
         if (typeof meta['description'] !== 'string' || !meta['description']) errors.push(`${skillMd}: missing description`);
     }
+    return names.length;
 }
 
-export function check_cursor_rules(root: string, errors: string[]): void {
+/** @returns how many `.mdc` rule files were examined. */
+export function check_cursor_rules(root: string, errors: string[]): number {
     const dir = path.join(root, '.cursor', 'rules');
-    if (!fs.existsSync(dir)) return;
+    if (!fs.existsSync(dir)) return 0;
+    let scanned = 0;
     for (const name of fs.readdirSync(dir)) {
         if (!name.endsWith('.mdc')) continue;
+        scanned += 1;
         const p = path.join(dir, name);
         const src = fs.readFileSync(p, 'utf-8');
         const m = src.match(/^---\n([\s\S]*?)\n---/);
@@ -57,12 +65,22 @@ export function check_cursor_rules(root: string, errors: string[]): void {
         try { parseYaml(lenient); }
         catch (e) { errors.push(`${p}: frontmatter YAML invalid (${(e as Error).message})`); }
     }
+    return scanned;
 }
 
 export function run(root: string): string[] {
     const errors: string[] = [];
-    check_claude_skills(root, errors);
-    check_cursor_rules(root, errors);
+    // Both host trees are generated and gitignored, and each checker returns
+    // early when its tree is absent — so "no malformed artefacts" and "no
+    // artefacts" are the same green. Thrown, not returned: `errors` names
+    // malformed files, and an unprojected tree is not one.
+    const scanned = check_claude_skills(root, errors) + check_cursor_rules(root, errors);
+    assertScanned({
+        gate: 'check_host_loadability',
+        scanned,
+        units: 'host artefact(s)',
+        roots: ['.claude/skills', '.cursor/rules'],
+    });
     return errors;
 }
 
@@ -71,7 +89,15 @@ const isMain = process.argv[1] !== undefined
 if (isMain) {
     const rootIdx = process.argv.indexOf('--root');
     const root = rootIdx !== -1 ? process.argv[rootIdx + 1] ?? '.' : '.';
-    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_installer_import_purity.ts

@@ -59,6 +59,8 @@ import { fileURLToPath } from 'node:url';
 
 import ts from 'typescript';
 
+import { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
+
 const _HERE = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(_HERE, '..', '..');
 
@@ -208,14 +210,6 @@ function parse(file: string): ts.SourceFile | null {
  */
 function auditEntry(entryRel: string, root: string = REPO_ROOT): Finding[] {
     const entryAbs = path.join(root, entryRel);
-    if (!fs.existsSync(entryAbs)) {
-        process.stderr.write(
-            `check-installer-import-purity: entry ${entryRel} does not exist — ` +
-                'update BUNDLE_ENTRIES\n',
-        );
-        process.exitCode = 1;
-        return [];
-    }
     const findings: Finding[] = [];
     const seen = new Set<string>([entryAbs]);
     // BFS so the reported chain is a shortest path — the least confusing one.
@@ -245,6 +239,26 @@ function auditEntry(entryRel: string, root: string = REPO_ROOT): Finding[] {
 }
 
 function main(): number {
+    // BUNDLE_ENTRIES is the whole scan scope — every module examined is reached
+    // from one of them. This REPLACES the per-entry existence guard in
+    // `auditEntry`, which could not fail: it set `process.exitCode = 1` and
+    // returned no findings, and `process.exit(main())` then overwrote that with
+    // main's 0, so a moved entry printed "✅ … reach no module-level
+    // process.exit()". 1 is the only failure code this gate has.
+    try {
+        assertWatchlistResolves({
+            gate: 'check_installer_import_purity',
+            candidates: BUNDLE_ENTRIES,
+            repoRoot: REPO_ROOT,
+        });
+    } catch (err) {
+        if (err instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${err.message}\n`);
+            return 1;
+        }
+        throw err;
+    }
+
     const all: Finding[] = [];
     for (const entry of BUNDLE_ENTRIES) {
         all.push(...auditEntry(entry));

package/src/scripts/check_kernel_prefix_stability.ts

@@ -37,6 +37,8 @@ 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';
+
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 const ROUTER = path.join(REPO_ROOT, 'dist/router.json');
@@ -96,7 +98,17 @@ function _live_prefix(): KernelPrefix | null {
   const router = _readJson(ROUTER);
   if (router === null) return null;
   const ids = kernel_ids(router);
-  if (ids.length === 0) return null;
+  // Scope only — the baseline and the comparison are untouched. An empty kernel
+  // list used to collapse into the same `null` as an unreadable router, so a
+  // router that compiled to zero kernel rules was reported as a missing file;
+  // it is a dead scan scope, and a digest over no bodies is a constant that
+  // would then look byte-stable forever.
+  assertScanned({
+    gate: 'check_kernel_prefix_stability',
+    scanned: ids.length,
+    units: 'kernel rule(s)',
+    roots: ['dist/router.json (kernel)', 'dist/agent-src/rules'],
+  });
   return compute_prefix(ids, (id) => fs.readFileSync(path.join(RULES_DIR, `${id}.md`), 'utf-8'));
 }
 
@@ -118,6 +130,12 @@ function main(argv: string[]): number {
   try {
     current = _live_prefix();
   } catch (e) {
+    // 1 is the documented "file error" code — the gate could not run. 2 is
+    // reserved for drift, i.e. a prefix that was read and did change.
+    if (e instanceof DeadScopeError) {
+      process.stderr.write(`error: ${e.message}\n`);
+      return 1;
+    }
     process.stderr.write(`error: cannot read kernel bodies: ${(e as Error).message}\n`);
     return 1;
   }

package/src/scripts/check_kernel_rule_bundle.ts

@@ -37,6 +37,7 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { KERNEL_RULE_FILENAMES } from './_lib/kernel_rules.js';
 import { runCountedProbe } from './_lib/counted_probe.js';
+import { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
 
 const KERNEL_RULES: ReadonlySet<string> = KERNEL_RULE_FILENAMES;
 
@@ -55,6 +56,8 @@ const KERNEL_RULES: ReadonlySet<string> = KERNEL_RULE_FILENAMES;
  */
 const KERNEL_DIR = 'src/rules';
 const DEFAULT_LABEL = 'bundled-always-rules-acknowledged';
+// src/scripts/check_kernel_rule_bundle.ts → two levels up is the repo root.
+const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
 
 function _git_changed_files(base_ref: string): string[] {
     // Bounded read: a truncated diff would shrink the change set and let the
@@ -188,6 +191,26 @@ function parse_args(argv: readonly string[]): Args {
 export function main(argv?: readonly string[]): number {
     const args = parse_args(argv ?? process.argv.slice(2));
 
+    // This gate has no corpus — it matches changed paths against a fixed set of
+    // 9 kernel rules, so its scope IS that watch list. It has already been
+    // inert once for exactly this reason (see KERNEL_DIR above): a prefix that
+    // no longer exists never matches, and every kernel-rule edit scored
+    // "no kernel rule touched". Exit 3 (internal error) over 1 (bundle
+    // violated) — a phantom watch list means the gate could not run.
+    try {
+        assertWatchlistResolves({
+            gate: 'check_kernel_rule_bundle',
+            candidates: [...KERNEL_RULES].sort().map((name) => `${KERNEL_DIR}/${name}`),
+            repoRoot: REPO,
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 3;
+        }
+        throw exc;
+    }
+
     // Python: args.files or _git_changed_files(...). An empty list from
     // `--files` (no values) is falsy in Python → falls through to git diff.
     const files =

package/src/scripts/check_knowledge_cards.ts

@@ -39,6 +39,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 // byte-faithful for behaviour (the only observable effect is the --global path).
 import * as _kg from './_lib/knowledge_global.js';
 import * as _kgr from './_lib/knowledge_global_redaction.js';
+import { assertScanned } from './_lib/scan_scope.js';
 
 // ROOT = Path(__file__).resolve().parent.parent.parent — src/scripts/ → repo root.
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
@@ -373,6 +374,18 @@ function main(): number {
     }
 
     const cards = _sortedGlobMd(card_dir).filter((p) => path.basename(p).toLowerCase() !== 'readme.md');
+    assertScanned({
+        gate: 'check_knowledge_cards',
+        scanned: cards.length,
+        units: 'knowledge card(s)',
+        roots: [path.relative(ROOT, card_dir) || card_dir],
+        allowEmpty:
+            'OPTIONAL_INPUT: cards are project-authored runtime content under agents/knowledge/ '
+            + '(or a --dir / --global store), never shipped package source. Delete the root and '
+            + 'zero still reads as "this project has captured no cards yet" — which is why both '
+            + 'the missing-dir and empty-dir paths are pinned as exit 0 by the CLI contract '
+            + 'below. A stale root cannot hide here: --dir is caller-supplied per invocation.',
+    });
     if (cards.length === 0) {
         process.stdout.write('No knowledge cards found — nothing to check.\n');
         return 0;

package/src/scripts/check_knowledge_pages.ts

@@ -29,6 +29,8 @@ import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 import YAML from 'yaml';
 
+import { assertScanned } from './_lib/scan_scope.js';
+
 const PROG = 'check_knowledge_pages.ts';
 const PAGE_LINE_BUDGET = 200;
 const CONTESTED_WARN_COUNT = 2;
@@ -135,6 +137,14 @@ function listMarkdownFiles(dirPath: string): string[] {
         .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
 }
 
+/** Pages `lintAll` reads — the corpus, independent of how many warn. */
+function countPages(knowledgeRoot: string): number {
+    return TYPED_DIRS.reduce(
+        (n, dir) => n + listMarkdownFiles(path.join(knowledgeRoot, dir)).length,
+        0,
+    );
+}
+
 export function lintAll(knowledgeRoot: string, today: Date = new Date()): Warning[] {
     const warnings: Warning[] = [];
     for (const dir of TYPED_DIRS) {
@@ -187,6 +197,19 @@ export function main(argv: string[]): number {
 
     const knowledgeRoot = path.join(dir, 'agents', 'knowledge');
     const warnings = lintAll(knowledgeRoot);
+    // Pages read, not warnings emitted — this lint never fails the build, so a
+    // moved root would print "no warnings" indefinitely with nothing behind it.
+    assertScanned({
+        gate: 'check_knowledge_pages',
+        scanned: countPages(knowledgeRoot),
+        units: 'knowledge page(s)',
+        roots: TYPED_DIRS.map((d) => path.join('agents', 'knowledge', d)),
+        allowEmpty:
+            'OPTIONAL_INPUT: the lifecycle-typed pages are project-authored runtime content, '
+            + 'not shipped package source, and the four typed subdirs are created on first '
+            + 'capture. Delete them and zero still reads as "this project has written no '
+            + 'knowledge pages yet" — the state every consumer starts in.',
+    });
 
     if (format === 'json') {
         process.stdout.write(JSON.stringify(warnings, null, 2) + '\n');

package/src/scripts/check_knowledge_sharing.ts

@@ -29,6 +29,8 @@ import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 import YAML from 'yaml';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const PROG = 'check_knowledge_sharing.ts';
 const CREATION_BUDGET_WARN = 5;
 const FRONTMATTER_RE = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n/;
@@ -150,6 +152,31 @@ export function main(argv: string[]): number {
         return 3;
     }
 
+    // Diff-driven: the corpus is whatever is staged, and an empty index is the
+    // normal state of a clean tree — so zero is allowed here. The dangerous
+    // empty (git itself failing) is NOT swallowed: it exits 3 above rather than
+    // reaching this point with an empty list. Exit 3 (internal error) is the
+    // code a dead scope would share, for the same "could not run" reason.
+    try {
+        assertScanned({
+            gate: 'check_knowledge_sharing',
+            scanned: staged.length,
+            units: 'staged path(s)',
+            roots: ['git diff --cached --name-status'],
+            allowEmpty:
+                'EMPTY_VALID: nothing staged means there is no commit to judge — an absent ' +
+                'question, not an empty corpus. Deletion test: deleting agents/knowledge/ ' +
+                'would not produce this zero (the staged deletions would themselves show up ' +
+                'in the diff); only an empty index does, and that is a clean tree.',
+        });
+    } catch (err) {
+        if (err instanceof DeadScopeError) {
+            process.stderr.write(`❌ ${err.message}\n`);
+            return 3;
+        }
+        throw err;
+    }
+
     const { blocked, warnings } = checkSharing(staged, gitStagedContent);
 
     for (const w of warnings) {

package/src/scripts/check_md_language.ts

@@ -20,6 +20,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 // Umlauts and German-only characters.
 const UMLAUT_RE = /[äöüÄÖÜß]/g;
 
@@ -247,6 +249,7 @@ export function main(argv?: readonly string[]): number {
     const args = parse_args(argv ?? process.argv.slice(2));
 
     const all_violations: Violation[] = [];
+    let scanned = 0;
     for (const raw_path of args.paths) {
         if (!_exists(raw_path)) {
             process.stderr.write(`⚠️  Not found: ${raw_path}\n`);
@@ -256,9 +259,30 @@ export function main(argv?: readonly string[]): number {
             process.stderr.write(`⚠️  Skipping non-.md: ${raw_path}\n`);
             continue;
         }
+        scanned += 1;
         all_violations.push(...scan_file(raw_path));
     }
 
+    // The caller expands the path list (`find docs -name '*.md' …`), so a moved
+    // docs tree hands this gate paths that every skip above swallows into a
+    // stderr warning while stdout still reports "No German content detected".
+    // Exit 3 is the documented "internal error" code — the gate could not run;
+    // 1 means it read files and found German in them.
+    try {
+        assertScanned({
+            gate: 'check_md_language',
+            scanned,
+            units: '.md file(s)',
+            roots: [`${String(args.paths.length)} caller-supplied path(s)`],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 3;
+        }
+        throw exc;
+    }
+
     if (args.format === 'json') {
         process.stdout.write(JSON.stringify(all_violations, null, 2) + '\n');
     } else if (all_violations.length === 0) {

package/src/scripts/check_media_deps.ts

@@ -21,6 +21,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 _FILE = fileURLToPath(import.meta.url);
 
 export interface MediaTool {
@@ -71,6 +73,27 @@ export function missingTools(tools: MediaTool[] = MEDIA_TOOLS): MediaTool[] {
 
 export function main(argv: string[] = process.argv.slice(2)): number {
     const quiet = argv.includes('--quiet');
+
+    // The scan scope is the declared tool list, not a directory: an empty
+    // MEDIA_TOOLS probes nothing and still prints the ✅ "all present" line.
+    // Deletion test: emptying the declaration would legitimately yield 0 only
+    // if "no tooling is required", which is never true for a prereq check.
+    // Exit 1 is the only failure code this CLI has, so a dead scope shares it.
+    try {
+        assertScanned({
+            gate: 'check_media_deps',
+            scanned: MEDIA_TOOLS.length,
+            units: 'declared media tool(s)',
+            roots: ['MEDIA_TOOLS (declared in src/scripts/check_media_deps.ts)'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
     const missing = missingTools();
     if (missing.length === 0) {
         if (!quiet) {

package/src/scripts/check_memory.ts

@@ -53,6 +53,8 @@ import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import YAML, { parseDocument } from 'yaml';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 type Severity = 'error' | 'warning' | 'info';
 
 const REQUIRED_KEYS: ReadonlySet<string> = new Set([
@@ -722,11 +724,34 @@ function main(): number {
         }
         return 0;
     }
+    // An ABSENT root stays a pinned exit-0 no-op (the branch above; the memory
+    // tree is an optional surface and `task check-memory` short-circuits it).
+    // A root that EXISTS but walks to zero `*.yml` is the case nothing covered:
+    // entries moved to a subtree this walk does not reach, and the validator
+    // reported "0 error(s)" over an empty read. No `allowEmpty` for that half —
+    // a present-but-unreadable corpus is blindness, not a clean bill of health.
+    // Exit 1 is this gate's only failure code (see `_emit`).
+    const ymls = _rglobYmlSorted(root);
+    try {
+        assertScanned({
+            gate: 'check_memory',
+            scanned: ymls.length,
+            units: 'memory entry file(s)',
+            roots: [`${root}/**/*.yml`],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
     const criticalCounts: Record<string, number> = {};
     for (const key of Object.keys(_TYPE_COUNTS)) {
         delete _TYPE_COUNTS[key];
     }
-    for (const yml of _rglobYmlSorted(root)) {
+    for (const yml of ymls) {
         _validateFile(yml, findings, criticalCounts);
     }
     // Tier-0 inflation warning — soft cap on `priority: critical` per type.

package/src/scripts/check_memory_contradiction.ts

@@ -34,6 +34,7 @@ import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 import YAML from 'yaml';
 
+import { assertScanned } from './_lib/scan_scope.js';
 import { jaccardSimilarity } from './_lib/text_similarity.js';
 
 const PROG = 'check_memory_contradiction.ts';
@@ -234,7 +235,21 @@ function main(argv: string[]): number {
 
     let hit: ContradictionHit | null;
     try {
-        hit = findContradiction(key, body, loadCuratedEntries(path.resolve(memoryRoot), type));
+        const existing = loadCuratedEntries(path.resolve(memoryRoot), type);
+        // Curated entries READ — the corpus every verdict below is decided
+        // against. Zero of them makes "no contradiction" unfalsifiable.
+        assertScanned({
+            gate: 'check_memory_contradiction',
+            scanned: existing.length,
+            units: 'curated entry(ies)',
+            roots: [path.join(memoryRoot, type), path.join(memoryRoot, `${type}.yml`)],
+            allowEmpty:
+                'OPTIONAL_INPUT: the per-type curated store is created by the first '
+                + '/memory promote of that type. Delete it and zero still reads as "nothing '
+                + 'of this type has been curated yet" — a state every consumer starts in, and '
+                + 'one in which no contradiction can exist by definition.',
+        });
+        hit = findContradiction(key, body, existing);
     } catch (exc) {
         process.stderr.write(`${PROG}: internal error: ${String(exc)}\n`);
         return 3;