@event4u/agent-config 9.20.0 → 9.21.0

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

package/src/scripts/check_originality_freshness.ts

@@ -19,6 +19,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
+import { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
 import { main as runOriginality } from './lint_originality.js';
 
 const REPO_ROOT = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..', '..');
@@ -136,9 +137,32 @@ export function main(): number {
         );
         return 0;
     }
-    const { drifted, missing } = checkFreshness();
     const rel = (f: string): string => path.relative(REPO_ROOT, f);
 
+    // `REPORTS` is the entire scope. One of the two absent is a real state the
+    // `missing` branch below reports; BOTH absent is the reports directory
+    // having moved, and the sweep would then WRITE two files, call them missing,
+    // and delete them again — a warning about the wrong thing. Exit stays 0:
+    // this surface is an advisory by design and has no failure code.
+    try {
+        assertWatchlistResolves({
+            gate: 'check_originality_freshness',
+            candidates: REPORTS.map(rel),
+            repoRoot: REPO_ROOT,
+        });
+    } catch (err) {
+        if (err instanceof DeadScopeError) {
+            process.stderr.write(
+                `⚠️  ${err.message}\n` +
+                    '    Run `./scripts-run src/scripts/lint_originality` and commit the result.\n',
+            );
+            return 0;
+        }
+        throw err;
+    }
+
+    const { drifted, missing } = checkFreshness();
+
     if (missing.length > 0) {
         process.stdout.write(
             `⚠️  originality report is not committed yet: ${missing.map(rel).join(', ')}\n` +

package/src/scripts/check_overlay_cascade_subdirs.ts

@@ -30,6 +30,7 @@ import {
     CASCADE_ELIGIBLE_KINDS,
     USER_GLOBAL_OVERLAY_KINDS,
 } from './_lib/agents_overlay.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 // src/scripts/check_overlay_cascade_subdirs.ts → two dirs up is the repo root.
@@ -96,6 +97,26 @@ export function main(): number {
     }
     const text = fs.readFileSync(DOCS_PATH, 'utf-8');
     const parsed = _parse_doc_table(text);
+    // The doc side of this comparison is a table PARSE, so a restructured,
+    // renamed, or reformatted table yields zero rows while the file still
+    // exists — and the set comparison then reports drift against phantoms, or
+    // nothing at all once both lists are empty. Exit 3, not 1: an unreadable
+    // table means the gate could not run, which is the same class as the
+    // `not found` path above; 1 is reserved for real code↔docs drift.
+    try {
+        assertScanned({
+            gate: 'check_overlay_cascade_subdirs',
+            scanned: parsed.all_kinds.size,
+            units: 'overlay table row(s)',
+            roots: ['docs/customization.md'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 3;
+        }
+        throw exc;
+    }
     const doc_cascade = parsed.cascade_yes;
     const doc_user_global = parsed.user_global_yes;
 

package/src/scripts/check_pack_size.ts

@@ -27,6 +27,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const REPO_ROOT = path.resolve(fileURLToPath(import.meta.url), '..', '..', '..');
 const BUDGET_PATH = path.join(REPO_ROOT, 'src', 'config', 'pack-size-budget.json');
 const SKILL_PREFIX = 'dist/agent-src/skills/';
@@ -176,6 +178,26 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
         process.stderr.write(`❌  pack size: npm pack failed: ${String(err)}\n`);
         return 2;
     }
+    // The pack manifest IS the corpus. `evaluate` refuses a vacuous per-skill
+    // share, but the packed-size arm has no such floor: an empty payload — a
+    // botched `files[]`, a pack that resolved nothing — measures 0 MB and sits
+    // comfortably under every budget.
+    try {
+        assertScanned({
+            gate: 'check_pack_size',
+            scanned: pack.files.length,
+            units: 'packed file(s)',
+            roots: ['npm pack --dry-run payload (package.json files[])'],
+        });
+    } catch (err) {
+        if (err instanceof DeadScopeError) {
+            // 2, not 1: the documented meaning of 1 is "over budget", and an
+            // empty manifest is unreadable input, not a budget violation.
+            process.stderr.write(`❌  pack size: ${err.message}\n`);
+            return 2;
+        }
+        throw err;
+    }
 
     const errors = evaluate(budget, pack);
     const { perSkill, total } = skillBytes(pack.files);

package/src/scripts/check_preamble_payload_budget.ts

@@ -23,6 +23,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 import { censusClaudeMdHierarchy, censusRuleDir, censusSkillsCatalog } from './preamble_byte_census.js';
 
 const HERE = path.dirname(new URL(import.meta.url).pathname);
@@ -40,7 +41,7 @@ export interface BudgetVerdict {
     baseline: number;
     ceiling: number;
     withinBudget: boolean;
-    buckets: Array<{ name: string; tokens: number }>;
+    buckets: Array<{ name: string; tokens: number; files: number }>;
 }
 
 function tokens(chars: number): number {
@@ -65,7 +66,7 @@ export function readBudget(file: string = BUDGET_FILE): Budget {
 /** Measure only what the repo tree determines — no `~`, no transcripts, no network. */
 export function measureDeterministicPayload(
     repoRoot: string = REPO_ROOT,
-): Array<{ name: string; tokens: number }> {
+): Array<{ name: string; tokens: number; files: number }> {
     const projectRules = censusRuleDir(path.join(repoRoot, 'dist', 'agent-src', 'rules'));
     const skills = censusSkillsCatalog(path.join(repoRoot, 'dist', 'agent-src', 'skills'));
     // Only the PROJECT half of the CLAUDE.md hierarchy is deterministic — the
@@ -73,10 +74,20 @@ export function measureDeterministicPayload(
     const claudeMd = censusClaudeMdHierarchy(repoRoot, path.join(repoRoot, '.no-such-home'));
     const projectClaudeMdChars =
         claudeMd.project_claude_md_chars + claudeMd.project_claude_local_md_chars;
+    // `files` carries the count of sources each census actually read. A token
+    // total cannot tell "the root moved" from "the payload is genuinely tiny",
+    // so the scope assertion in `main` needs the count, not the bytes.
+    const claudeMdFiles =
+        (claudeMd.project_claude_md_present ? 1 : 0) +
+        (claudeMd.project_claude_local_md_present ? 1 : 0);
     return [
-        { name: 'project-scope rules', tokens: tokens(projectRules.chars) },
-        { name: 'preloaded skills catalog', tokens: tokens(skills.chars) },
-        { name: 'CLAUDE.md hierarchy (project only)', tokens: tokens(projectClaudeMdChars) },
+        { name: 'project-scope rules', tokens: tokens(projectRules.chars), files: projectRules.files },
+        { name: 'preloaded skills catalog', tokens: tokens(skills.chars), files: skills.skills },
+        {
+            name: 'CLAUDE.md hierarchy (project only)',
+            tokens: tokens(projectClaudeMdChars),
+            files: claudeMdFiles,
+        },
     ];
 }
 
@@ -98,6 +109,25 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         return 2;
     }
 
+    // A ratchet over a measurement of nothing always passes: move
+    // `dist/agent-src/` and every census returns zero, which is trivially under
+    // any ceiling. Exit 2 (misuse / unreadable budget — the could-not-run
+    // code), never 1, which asserts the payload actually grew.
+    try {
+        assertScanned({
+            gate: 'check_preamble_payload_budget',
+            scanned: verdict.buckets.reduce((n, b) => n + b.files, 0),
+            units: 'payload source file(s)',
+            roots: ['dist/agent-src/rules', 'dist/agent-src/skills', 'CLAUDE.md'],
+        });
+    } catch (err) {
+        if (err instanceof DeadScopeError) {
+            process.stderr.write(`❌  preamble-payload budget: ${err.message}\n`);
+            return 2;
+        }
+        throw err;
+    }
+
     if (json) {
         process.stdout.write(JSON.stringify(verdict, null, 2) + '\n');
         return verdict.withinBudget ? 0 : 1;

package/src/scripts/check_proposal.ts

@@ -37,6 +37,8 @@ import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 type Severity = 'error' | 'warning';
 
 const REQUIRED_FRONTMATTER: ReadonlySet<string> = new Set([
@@ -456,7 +458,28 @@ function main(): number {
         process.stderr.write(`error: ${p} not found\n`);
         return 3;
     }
-    const findings = _runChecks(fs.readFileSync(p, 'utf-8'), p);
+    const text = fs.readFileSync(p, 'utf-8');
+    // No corpus walk: this gate's scope is the single document named on argv.
+    // The unit is therefore the content lines actually read — every check below
+    // is a search over this text, so a zero-byte target makes the negative ones
+    // ("no TODO/TBD markers") vacuously true against nothing.
+    try {
+        assertScanned({
+            gate: 'check_proposal',
+            scanned: text.split('\n').filter((l) => l.trim() !== '').length,
+            units: 'content line(s)',
+            roots: [p],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // 1 = gate failure, which is what an unusable proposal already
+            // returns today (3 is reserved for the not-found path above).
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+    const findings = _runChecks(text, p);
     const errors = findings.filter((f) => f.severity === 'error');
     if (args.format === 'json') {
         process.stdout.write(

package/src/scripts/check_public_catalog_links.ts

@@ -26,6 +26,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 _HERE = fileURLToPath(import.meta.url);
@@ -117,6 +119,10 @@ function main(): number {
     const missing: Array<[number, string]> = [];
     const unshipped: Array<[number, string]> = [];
 
+    // Counted BEFORE any filtering — external hrefs and anchors included — so
+    // the number answers "did the catalog still carry links", not "how many
+    // survived the checks".
+    let links_seen = 0;
     const lines = _splitlines(text);
     for (let i = 0; i < lines.length; i++) {
         const lineno = i + 1;
@@ -124,6 +130,7 @@ function main(): number {
         LINK_RE.lastIndex = 0;
         let m: RegExpExecArray | null;
         while ((m = LINK_RE.exec(line)) !== null) {
+            links_seen += 1;
             const href = m[1]!;
             if (href.includes(FORBIDDEN_PREFIX)) {
                 forbidden.push([lineno, href]);
@@ -143,6 +150,26 @@ function main(): number {
         }
     }
 
+    // The catalog is generated. A renderer that stops emitting links leaves a
+    // file that still exists and still parses, so the three violation buckets
+    // stay empty and this reports "all links resolve" over no links at all.
+    // Exit 1 is the only failure code here, and it already carries the
+    // could-not-run meaning (the missing-catalog path above returns it too).
+    try {
+        assertScanned({
+            gate: 'check_public_catalog_links',
+            scanned: links_seen,
+            units: 'markdown link(s)',
+            roots: ['docs/catalog.md'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stdout.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
     const total_violations = forbidden.length + missing.length + unshipped.length;
     if (total_violations === 0) {
         if (!QUIET) {