@event4u/agent-config 9.20.0 → 9.22.0

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;

package/src/scripts/check_memory_proposal.ts

@@ -16,6 +16,8 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import YAML from 'yaml';
 
+import { assertScanned } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 
 // Relative to cwd, mirroring Python `Path("agents/memory/intake")`.
@@ -296,6 +298,19 @@ function _json_dumps_ascii(obj: unknown): string {
 
 function main(argv?: readonly string[]): number {
     const args = parse_args(argv ?? process.argv.slice(2));
+    // Intake FILES walked — the scope both `_find_intake` (record lookup) and
+    // `_count_sibling_paths` (pattern evidence) share.
+    assertScanned({
+        gate: 'check_memory_proposal',
+        scanned: _jsonlFilesSorted().length,
+        units: 'intake signal file(s)',
+        roots: [INTAKE_ROOT],
+        allowEmpty:
+            'OPTIONAL_INPUT: the intake dir is local, gitignored capture written by '
+            + '/memory propose. Delete it and zero still reads as "nothing captured yet". '
+            + 'An empty scope also tightens rather than relaxes this gate: zero sibling '
+            + 'paths forces the future_decisions branch, and --intake-id already fails 1.',
+    });
     let record: Record_;
     let source: string;
     if (args.intake_id !== null) {

package/src/scripts/check_memory_similarity.ts

@@ -22,6 +22,7 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 
+import { assertScanned } from './_lib/scan_scope.js';
 import { findMostSimilar, type Candidate } from './_lib/text_similarity.js';
 
 const PROG = 'check_memory_similarity.ts';
@@ -106,6 +107,21 @@ export function main(argv: string[]): number {
         return 2;
     }
 
+    // The unit is the signal FILES the glob walks, not the type-filtered
+    // candidates: the first entry of a given type legitimately has zero
+    // candidates, so only the unfiltered walk distinguishes that from a root
+    // that moved and turned every proposal into a silent "create".
+    assertScanned({
+        gate: 'check_memory_similarity',
+        scanned: globSignals(intakeRoot).length,
+        units: 'intake signal file(s)',
+        roots: [intakeRoot],
+        allowEmpty:
+            'OPTIONAL_INPUT: intake signals are local, gitignored capture written by '
+            + '/memory propose — never shipped source. Delete the root and zero still reads '
+            + 'as "nothing has been captured in this project yet", which is exactly the '
+            + 'state of the very first proposal. Advisory check: it never blocks a create.',
+    });
     const candidates = loadCandidates(intakeRoot, type);
     const match = findMostSimilar(body, candidates);
 

package/src/scripts/check_module_management_neutral.ts

@@ -27,6 +27,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.resolve(path.dirname(_HERE), '..', '..');
 const SKILL_PATH = path.join(
@@ -55,14 +57,6 @@ const BODY_BANNED_PATTERNS: readonly BannedPattern[] = [
     { re: /App\\\\Modules\\\\/, source: 'App\\\\\\\\Modules\\\\\\\\' },
 ];
 
-function _isFile(p: string): boolean {
-    try {
-        return fs.statSync(p).isFile();
-    } catch {
-        return false;
-    }
-}
-
 /** POSIX relative path of `child` under `root` (mirrors relative_to().as_posix-ish for display). */
 function _relToPosix(child: string, root: string): string {
     return path.relative(root, child).split(path.sep).join('/');
@@ -193,9 +187,23 @@ function _scan_frontmatter(fm: string): string[] {
 }
 
 function main(): number {
-    if (!_isFile(SKILL_PATH)) {
-        process.stderr.write(`error: SKILL.md not found at ${SKILL_PATH}\n`);
-        return 2;
+    // One named file is the entire scan scope, so `_isFile` was this gate's
+    // zero-check; the shared assertion replaces it and names the scope. The
+    // ported message is kept verbatim ahead of it (the py2ts CLI contract pins
+    // it) and exit 2 is unchanged.
+    try {
+        assertWatchlistResolves({
+            gate: 'check_module_management_neutral',
+            candidates: [_relToPosix(SKILL_PATH, REPO_ROOT)],
+            repoRoot: REPO_ROOT,
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`error: SKILL.md not found at ${SKILL_PATH}\n`);
+            process.stderr.write(`   ${exc.message}\n`);
+            return 2;
+        }
+        throw exc;
     }
     const text = fs.readFileSync(SKILL_PATH, 'utf-8');
     const [fm, body] = _split_frontmatter(text);

package/src/scripts/check_no_conflict_markers.ts

@@ -44,6 +44,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);
 // Path(__file__).resolve().parents[2] — repo root, two dirs up from src/scripts.
 const REPO = path.resolve(path.dirname(_HERE), '..', '..');
@@ -174,6 +176,25 @@ function main(argv?: readonly string[]): number {
     const args = parse_args(argv ?? process.argv.slice(2));
 
     const allow = load_allowlist();
+    const tracked = tracked_text_files();
+    // `_git` swallows every failure and returns "", so a run outside a work
+    // tree — or against a repo whose index this process cannot read — walks an
+    // empty file list, finds no markers, and reports the tree clean. The count
+    // the success line already prints was the evidence; nothing asserted on it.
+    try {
+        assertScanned({
+            gate: 'check_no_conflict_markers',
+            scanned: tracked.length,
+            units: 'tracked file(s)',
+            roots: [`${REPO} (git ls-files)`],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
     const unmerged = unmerged_paths();
     const markerHits = scan_markers(allow);
 
@@ -208,7 +229,7 @@ function main(argv?: readonly string[]): number {
     if (!args.quiet) {
         process.stdout.write(
             `✅  check_no_conflict_markers: no conflicted index entries, no markers ` +
-                `(${tracked_text_files().length} tracked files scanned).\n`,
+                `(${tracked.length} tracked files scanned).\n`,
         );
     }
     return 0;

package/src/scripts/check_no_external_sources.ts

@@ -36,6 +36,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);
 // parents[2] of src/scripts/<file> is the repo root.
 const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -272,8 +274,31 @@ function main(argv: readonly string[]): number {
     const patterns: Array<[string, RegExp]> = cfg.deny.map((p) => [p, new RegExp(p, 'i')]);
     const skipGlobs = cfg.skip_paths ?? [];
 
+    // `_tracked_files` raises when git itself fails, but a git that succeeds
+    // with empty output (not a repo, nothing tracked) yields the same empty
+    // loop and the ✅ "no external-source references" line. Not a diff — this
+    // is the whole tracked tree, so zero is never a legitimate state; no
+    // `allowEmpty`. Assert the unfiltered enumeration, before the extension /
+    // skip_paths filters, so a filter change can never mask a dead scope.
+    // Exit 1 is the only failure code this pinned CLI reaches.
+    const tracked = _tracked_files();
+    try {
+        assertScanned({
+            gate: 'check_no_external_sources',
+            scanned: tracked.length,
+            units: 'tracked file(s)',
+            roots: ['git ls-files'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
     const hits: Hit[] = [];
-    for (const rel of _tracked_files()) {
+    for (const rel of tracked) {
         if (_SKIP_EXT.has(_suffixLower(rel))) {
             continue;
         }

package/src/scripts/check_no_local_settings_committed.ts

@@ -21,29 +21,56 @@ 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 _HERE = fileURLToPath(import.meta.url);
 
 const LOCAL_FILE = '.agent-settings.local.yml';
 
-function tracked_local_settings(): string[] {
+/** Every tracked path — the unfiltered corpus the basename match runs over. */
+function _tracked_files(): string[] {
     const res = spawnSync('git', ['ls-files'], { encoding: 'utf-8' });
     // Mirror Python: CalledProcessError (non-zero) or FileNotFoundError
     // (git missing) → return [] (nothing to enforce).
     if (res.error !== undefined || res.status !== 0 || typeof res.stdout !== 'string') {
         return [];
     }
-    const out = res.stdout;
-    return out
-        .split('\n')
-        .filter((line) => line !== '')
-        .filter((line) => {
-            const parts = line.split('/');
-            return parts[parts.length - 1] === LOCAL_FILE;
-        });
+    return res.stdout.split('\n').filter((line) => line !== '');
+}
+
+function _isLocalSettings(line: string): boolean {
+    const parts = line.split('/');
+    return parts[parts.length - 1] === LOCAL_FILE;
+}
+
+function tracked_local_settings(): string[] {
+    return _tracked_files().filter(_isLocalSettings);
 }
 
 function main(): number {
-    const offenders = tracked_local_settings();
+    // Not a diff — `git ls-files` enumerates the WHOLE tracked tree, so zero
+    // lines means git failed or this is not a repo, not "nothing committed".
+    // The swallow above turns both into an empty list, and the gate then prints
+    // the ✅ line. Deletion test: a repo with zero tracked files is never a
+    // legitimate state here, so no `allowEmpty`. Exit 1 is the only failure
+    // code this pinned CLI has.
+    const tracked = _tracked_files();
+    try {
+        assertScanned({
+            gate: 'check_no_local_settings_committed',
+            scanned: tracked.length,
+            units: 'tracked file(s)',
+            roots: ['git ls-files'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
+    const offenders = tracked.filter(_isLocalSettings);
     if (offenders.length === 0) {
         process.stdout.write(`✅  No tracked ${LOCAL_FILE} files.\n`);
         return 0;

package/src/scripts/check_no_new_legacy_path.ts

@@ -46,6 +46,8 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { checkRatchet } from './_lib/gate_baseline.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+import { readStdinText } from './_lib/stdin.js';
 
 const LEGACY = '.agent-src.uncondensed/';
 const EXEMPT: ReadonlySet<string> = new Set([
@@ -263,6 +265,31 @@ export function find_hardcoded_scan_roots(
  * live number, which is the whole point of committing it.
  */
 export function checkHardcodedScanRoots(repoRoot: string = process.cwd()): number {
+    // The scanned unit is script FILES walked, never `findings.length` — this
+    // pass is a downward ratchet, so zero findings is the goal state and can
+    // never distinguish "clean" from "the walk root moved". `_walkScripts`
+    // swallows an unreadable directory, so a relocated `src/scripts/` yields an
+    // empty walk, an actual of 0, a verdict under baseline, and a ✅ — this gate
+    // failing the same way it exists to detect. No `allowEmpty`: a repo with no
+    // scripts under the scan dir is blindness, not cleanliness.
+    // Exit 2 (git/environment failure) over 1 (above baseline) — a dead scope
+    // means the pass could not run; `main` propagates it via Math.max.
+    const walked = [..._walkScripts(path.join(repoRoot, HARDCODED_ROOT_SCAN_DIR))];
+    try {
+        assertScanned({
+            gate: HARDCODED_ROOT_GATE,
+            scanned: walked.length,
+            units: 'script file(s)',
+            roots: [`${HARDCODED_ROOT_SCAN_DIR}/**/*.{ts,mts,mjs}`],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stdout.write(`❌  ${exc.message}\n`);
+            return 2;
+        }
+        throw exc;
+    }
+
     const findings = find_hardcoded_scan_roots(repoRoot);
     const verdict = checkRatchet({
         gate: HARDCODED_ROOT_GATE,
@@ -293,7 +320,9 @@ function main(): number {
     // documented failure the kernel-bundle step sidesteps the same way).
     let offenders: string[];
     if (process.argv.includes('--stdin')) {
-        const stdin = fs.readFileSync(0, 'utf-8') as string;
+        // `readFileSync(0)` crashes with EAGAIN once the diff outgrows the pipe
+        // buffer — this gate's own PR was the first big enough to prove it.
+        const stdin = readStdinText();
         offenders = find_offenders(stdin);
     } else {
         const base = _base();

package/src/scripts/check_one_off_location.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';
+
 // src/scripts/check_one_off_location.ts → two dirs up is the repo root.
 // Mirrors the Python `Path(__file__).resolve().parent.parent.parent`.
 const _HERE = fileURLToPath(import.meta.url);
@@ -73,6 +75,28 @@ function _rglobOneOff(root: string): string[] {
     return out;
 }
 
+/** Files the guard's walk visits under `root` — the scope, not the matches. */
+function _countFilesUnder(root: string): number {
+    let n = 0;
+    const walk = (dir: string): void => {
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const ent of entries) {
+            if (ent.isDirectory()) {
+                walk(path.join(dir, ent.name));
+            } else {
+                n += 1;
+            }
+        }
+    };
+    walk(root);
+    return n;
+}
+
 function _isFile(p: string): boolean {
     try {
         return fs.statSync(p).isFile();
@@ -126,6 +150,25 @@ function parse_args(argv: readonly string[]): Args {
 export function main(argv?: readonly string[]): number {
     const args = parse_args(argv ?? process.argv.slice(2));
 
+    // The unit is every file the walk visits, NOT the `_one_off_*.py` matches:
+    // zero matches is the normal clean state (the archive is empty today), so
+    // only the unfiltered walk can tell "nothing to move" from "nothing read".
+    try {
+        assertScanned({
+            gate: 'check_one_off_location',
+            scanned: _countFilesUnder(SCRIPTS),
+            units: 'file(s)',
+            roots: ['src/scripts'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // 1 = violation (3 is reserved for an internal error below).
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
     let violations: string[];
     try {
         violations = find_violations();