@event4u/agent-config 9.20.0 → 9.21.0

package/src/scripts/_lib/roadmap_granularity.ts

@@ -0,0 +1,157 @@
+/**
+ * Bite-sized task-granularity check for structural roadmaps.
+ *
+ * A `complexity: structural` roadmap's task bullets must name real work. A
+ * placeholder in a task bullet — `<something>`, TODO, FIXME, XXX, TBD, `???` —
+ * means the step was filed before it was decided, which is the failure the
+ * bite-sized standard exists to catch.
+ *
+ * ## Why this lives in `_lib/` and not in a gate of its own
+ *
+ * It used to be `src/scripts/check_bite_sized_granularity.ts`: a pure library
+ * with no CLI, no `main`, no exit code, and — measured — no production caller
+ * outside its own test. It was carried over from a retired Python module for
+ * API parity and never wired up, so a real check that no other gate covers ran
+ * nowhere, while the `check_` prefix kept it inside the gate population where
+ * the scan-scope ratchet counted it as a gate that could not assert a scan
+ * scope.
+ *
+ * AI council 2026-08-05 resolved it by folding rather than deleting: the checks
+ * are the only placeholder coverage in the tree (`lint_roadmap_complexity`
+ * covers the complexity tag, the lightweight caps, and the plate/horizon
+ * prohibition, and greps clean for every placeholder pattern), so deleting them
+ * would have discarded live value to reach a count. Folding into the gate that
+ * already owns the roadmap corpus adds no gate script, no CI job, and no
+ * manifest entry, and the population member disappears with the old file.
+ *
+ * ## Inline-code masking (the reason this is not a verbatim move)
+ *
+ * The original patterns matched inside backticked spans, which made CLI
+ * metasyntax a violation. Measured across 22 structural roadmaps, the only hit
+ * in the whole tree was `` `settings set <key> <value>` `` — argument
+ * metasyntax in a code span, on a step that is otherwise fully specified. The
+ * council flagged folding a check with an unaudited hit in an out-of-scope
+ * directory as a time-bomb: it would fire the day the gate's scope widened. So
+ * the fix is precision, not scope-limiting — inline code spans are masked
+ * before matching, the same technique `lint_readme_serial_comma` already uses
+ * on README prose. With masking the count is 0 across every structural roadmap,
+ * `later/` and `stubs/` included, so widening the gate's scope later cannot
+ * surprise anyone.
+ */
+
+/** Placeholder patterns in (kind, regex) order. */
+const PLACEHOLDER_PATTERNS: ReadonlyArray<[string, RegExp]> = [
+    ['angle-placeholder', /<[a-z][a-z0-9 _\-/]*>/i],
+    ['todo', /\bTODO\b/],
+    ['fixme', /\bFIXME\b/],
+    ['xxx', /\bXXX\b/],
+    ['tbd', /\btbd\b/i],
+    ['triple-question', /\?\?\?/],
+];
+
+const COMPLEXITY_PAT = /^complexity:\s*(lightweight|structural)\s*$/m;
+
+const TASK_PREFIXES = ['- [ ]', '- [x]', '- [/]', '- [-]'] as const;
+
+export interface Placeholder {
+    kind: string;
+    line: number;
+    text: string;
+}
+
+export interface GranularityResult {
+    complexity: string | null;
+    gated: boolean;
+    violations: Placeholder[];
+}
+
+function frontmatter(text: string): string {
+    if (!text.startsWith('---\n')) {
+        return '';
+    }
+    const end = text.indexOf('\n---\n', 4);
+    return end !== -1 ? text.slice(4, end) : '';
+}
+
+export function read_complexity(text: string): string | null {
+    const fm = frontmatter(text);
+    if (fm === '') {
+        return null;
+    }
+    const m = COMPLEXITY_PAT.exec(fm);
+    return m ? m[1]! : null;
+}
+
+const ANGLE_PLACEHOLDER = /<[a-z][a-z0-9 _\-/]*>/gi;
+
+/**
+ * Blank inline code spans that are COMMAND TEMPLATES, so CLI argument
+ * metasyntax is not read as an undecided step.
+ *
+ * Blanking every backtick span (the first attempt) was too blunt, and the ported
+ * test corpus proved it: `` `<file>` `` in *"Edit `<file>` and add the new
+ * method"* is a real placeholder — the file is genuinely undecided — while
+ * `` `settings set <key> <value>` `` on a step that goes on to specify
+ * zod-validation, atomicity and key-class refusal is a command signature.
+ *
+ * The discriminator is what else the span holds: strip the placeholders and if
+ * nothing but whitespace is left, the span IS the placeholder (violation); if
+ * real content remains (`settings set`), it is a command template naming its
+ * arguments (masked). Only the angle pattern gets this treatment — a literal
+ * TODO / FIXME / XXX / TBD / `???` in a task bullet is unfinished work wherever
+ * it sits, backticks included.
+ */
+function mask_command_templates(line: string): string {
+    return line.replace(/`[^`]*`/g, (span) => {
+        const withoutPlaceholders = span.slice(1, -1).replace(ANGLE_PLACEHOLDER, '');
+        return withoutPlaceholders.trim() === '' ? span : ' ';
+    });
+}
+
+export function scan_placeholders(text: string): Placeholder[] {
+    const hits: Placeholder[] = [];
+    const lines = text.split('\n');
+    for (let idx = 0; idx < lines.length; idx++) {
+        const line = lines[idx]!;
+        const stripped = line.replace(/^\s+/, '');
+        if (!TASK_PREFIXES.some((p) => stripped.startsWith(p))) {
+            continue;
+        }
+        // Command-template masking applies to the angle pattern ONLY. A literal
+        // TODO / FIXME / XXX / TBD / `???` is unfinished work wherever it sits,
+        // so those patterns read the raw line.
+        const masked = mask_command_templates(line);
+        for (const [kind, pat] of PLACEHOLDER_PATTERNS) {
+            const probe = kind === 'angle-placeholder' ? masked : line;
+            if (pat.test(probe)) {
+                hits.push({ kind, line: idx + 1, text: line.replace(/\s+$/, '') });
+                break;
+            }
+        }
+    }
+    return hits;
+}
+
+/**
+ * Gated only for `complexity: structural`. Violations are empty when the gate
+ * is not active, regardless of placeholder presence.
+ */
+export function check_granularity(text: string): GranularityResult {
+    const complexity = read_complexity(text);
+    const gated = complexity === 'structural';
+    if (!gated) {
+        return { complexity, gated: false, violations: [] };
+    }
+    return { complexity, gated: true, violations: scan_placeholders(text) };
+}
+
+/** One human-readable problem line per violation, for a gate's problem list. */
+export function granularity_problems(text: string): string[] {
+    return check_granularity(text).violations.map(
+        (v) =>
+            `bite-sized granularity: line ${v.line} has a ${v.kind} placeholder in a ` +
+            `task bullet — a structural roadmap's steps name decided work: ${v.text.trim()}`,
+    );
+}
+
+export { PLACEHOLDER_PATTERNS, COMPLEXITY_PAT };

package/src/scripts/_lib/scan_scope.ts

@@ -23,6 +23,7 @@
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import process from 'node:process';
 
 /** Raised when a gate's scope is empty — it cannot have checked anything. */
 export class DeadScopeError extends Error {
@@ -49,6 +50,24 @@ export interface ScannedOptions {
      * corpus is a real, expected state (an optional consumer surface that may
      * genuinely be absent) — never to silence a moved root. The string is the
      * reason and is printed, so it is reviewable in a diff.
+     *
+     * **Carry one of the three prefixes below.** A reason a reviewer cannot
+     * classify from the comment alone is how a justified exception becomes an
+     * allowlist of boilerplate (`road-to-gate-hardening-adoption`, AI council
+     * 2026-08-04). The prefix states which kind of emptiness is claimed:
+     *
+     * - `OPTIONAL_INPUT:` — the root belongs to a surface that may legitimately
+     *   be absent in this project (a consumer tree, an opt-in pack).
+     * - `EMPTY_VALID:` — zero units IS the success state (`check_no_todos`: an
+     *   empty tree genuinely has zero TODOs).
+     * - `WATCHLIST_DRIVEN:` — the gate has no corpus at all; it guards named
+     *   files and its scope is asserted by {@link assertWatchlistResolves}.
+     *
+     * The operational test every reason must pass, applied from the comment
+     * alone: **if this gate's scan root were deleted, would the reason still
+     * make sense?** `check_no_todos` → yes. `check_frontmatter_valid` → no; no
+     * docs to validate is blindness, not cleanliness, and that gate must
+     * reclassify rather than claim `allowEmpty`.
      */
     allowEmpty?: string;
 }
@@ -75,6 +94,31 @@ export function assertScanned(opts: ScannedOptions): void {
     );
 }
 
+/**
+ * Assert a corpus gate's scope AND publish the count it just validated.
+ *
+ * The two halves of scope hardening drifted apart in practice: 14 gates emit
+ * the machine-readable `scanned:` line the coverage guard reads, 12 assert
+ * their scope, and only 8 do both. A gate that publishes a number it never
+ * asserted can print `scanned: 0` and exit green; a gate that asserts without
+ * publishing is invisible to `check_gate_coverage`. Splitting the two also
+ * lets the published number drift from the number that was validated — the
+ * invented-count failure that is mechanically undetectable downstream.
+ *
+ * One call closes both: the emitted number is, by construction, the number the
+ * assertion just accepted. Use this for any gate that should also carry a floor
+ * in `src/config/gate-coverage.yml`; plain {@link assertScanned} stays correct
+ * for a gate that only needs its scope guarded.
+ *
+ * The line goes to stdout unconditionally — a count only visible without
+ * `--quiet` is not a count, since CI passes `--quiet` (the `lint_handoffs`
+ * lesson, preserved here so no caller has to rediscover it).
+ */
+export function reportScanned(opts: ScannedOptions, write = process.stdout.write.bind(process.stdout)): void {
+    assertScanned(opts);
+    write(`scanned: ${String(opts.scanned)}\n`);
+}
+
 export interface WatchlistOptions {
     /** Gate name, for the error message. */
     gate: string;

package/src/scripts/_lib/stdin.ts

@@ -0,0 +1,82 @@
+/**
+ * Read piped stdin completely — including payloads larger than the pipe buffer.
+ *
+ * WHY THIS EXISTS (measured 2026-08-04, PR "take the unhardened-gate count from
+ * 189 to 4"): the CI step
+ *
+ *     gh pr diff "$PR" | ./scripts-run src/scripts/check_no_new_legacy_path --stdin
+ *
+ * crashed with `EAGAIN: resource temporarily unavailable, read` at
+ * `fs.readFileSync(0)`. Not flaky — **reproducible on that PR and green on every
+ * PR before it.** A pipe holds ~64 KB; while the diff fit, the single read
+ * returned everything. That PR's diff is ~6,400 lines, so the writer is still
+ * filling the pipe when the reader arrives, and Node leaves the inherited fd 0
+ * in non-blocking mode: the read fails instead of waiting.
+ *
+ * A size-dependent gate failure is the same family of defect this suite's
+ * scan-scope work exists to kill — the gate works on the changes small enough
+ * not to matter and breaks on the ones big enough to. And the sibling
+ * workaround is worse than the crash: `check_release_pr_shape` wraps the same
+ * call in `catch { data = '' }`, so an oversized diff there reads as an empty
+ * one and the gate passes over nothing.
+ *
+ * So: retry on EAGAIN rather than swallow it, and never substitute an empty
+ * string for a failed read. A caller that gets `''` here got a genuinely empty
+ * stdin.
+ */
+import * as fs from 'node:fs';
+
+const CHUNK = 64 * 1024;
+/** Sleep between EAGAIN retries. Synchronous — these are sync CLI entry points. */
+const RETRY_SLEEP_MS = 5;
+/**
+ * Total patience before giving up, in retries. At 5 ms this is ~10 s, which is
+ * far beyond any `gh pr diff` and still terminates rather than spinning forever
+ * if fd 0 is a pipe nobody ever writes to.
+ */
+const MAX_RETRIES = 2000;
+
+/** Sleep without a busy loop, in synchronous code. */
+function _sleepSync(ms: number): void {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/**
+ * Read all of fd 0 as UTF-8.
+ *
+ * @throws the underlying error for anything that is not EAGAIN, and after
+ *         {@link MAX_RETRIES} consecutive EAGAINs — a caller must not be able to
+ *         mistake a failed read for empty input.
+ */
+export function readStdinText(fd = 0): string {
+    const chunks: Buffer[] = [];
+    const buf = Buffer.alloc(CHUNK);
+    let retries = 0;
+    for (;;) {
+        let read: number;
+        try {
+            read = fs.readSync(fd, buf, 0, CHUNK, null);
+            retries = 0;
+        } catch (exc) {
+            const code = (exc as NodeJS.ErrnoException).code;
+            if (code === 'EAGAIN') {
+                retries += 1;
+                if (retries > MAX_RETRIES) {
+                    throw new Error(
+                        `readStdinText: stdin stayed unreadable across ${String(MAX_RETRIES)} retries ` +
+                            `(~${String((MAX_RETRIES * RETRY_SLEEP_MS) / 1000)}s). Refusing to report an ` +
+                            'empty read as empty input.',
+                    );
+                }
+                _sleepSync(RETRY_SLEEP_MS);
+                continue;
+            }
+            // EOF is how some platforms end a pipe read rather than returning 0.
+            if (code === 'EOF') break;
+            throw exc;
+        }
+        if (read === 0) break;
+        chunks.push(Buffer.from(buf.subarray(0, read)));
+    }
+    return Buffer.concat(chunks).toString('utf-8');
+}

package/src/scripts/audit_adr_coverage.ts

@@ -22,6 +22,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);
 
 // src/scripts/audit_adr_coverage.ts → parents[2] of the .py file is repo root.
@@ -251,14 +253,40 @@ export function render_area_readme(area: string, meta: AreaMeta, adrs: AdrEntry[
     return lines.join('\n') + '\n';
 }
 
+/**
+ * A vanished `docs/adrs/` makes every area report zero ADRs — "missing
+ * bootstrap" across the board, which both modes treat as a warning and exit 0.
+ * Exit 1 is the hard-failure code (`cmd_check`); 2 is reserved for argparse
+ * usage errors.
+ */
+function _dead_adr_scope(scanned: number): number | null {
+    try {
+        assertScanned({
+            gate: 'audit_adr_coverage',
+            scanned,
+            units: 'ADR file(s)',
+            roots: ['docs/adrs'],
+        });
+        return null;
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌ ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+}
+
 export function cmd_report(): number {
     process.stdout.write('## ADR coverage report\n');
     process.stdout.write('\n');
     process.stdout.write('| Area | Contract | ADRs | README | Status |\n');
     process.stdout.write('|---|---|---:|:---:|---|\n');
     let missingBootstrap = 0;
+    let totalAdrs = 0;
     for (const [area, meta] of Object.entries(AREAS)) {
         const [adrs] = scan_area(area);
+        totalAdrs += adrs.length;
         const readme = _exists(path.join(ADR_ROOT, area, 'README.md')) ? '✅' : '—';
         const contractPresent = _exists(_contract_path(meta));
         const status = adrs.length > 0 ? 'ok' : 'missing bootstrap';
@@ -268,6 +296,10 @@ export function cmd_report(): number {
         const contractCell = contractPresent ? meta.contract : `_${meta.contract}_ (no contract)`;
         process.stdout.write(`| \`${area}\` | ${contractCell} | ${adrs.length} | ${readme} | ${status} |\n`);
     }
+    const dead = _dead_adr_scope(totalAdrs);
+    if (dead !== null) {
+        return dead;
+    }
     process.stdout.write('\n');
     process.stdout.write(
         `BASELINE: ${Object.keys(AREAS).length} canonical areas · ${missingBootstrap} missing bootstrap ADR(s)\n`,
@@ -278,6 +310,7 @@ export function cmd_report(): number {
 export function cmd_check(): number {
     let hard = 0;
     let warn = 0;
+    let totalAdrs = 0;
     for (const dir of unlistedAreaDirs(ADR_ROOT)) {
         process.stderr.write(
             `❌ ${dir}/: area directory exists on disk but is absent from AREAS — it is not audited at all. ` +
@@ -287,6 +320,7 @@ export function cmd_check(): number {
     }
     for (const [area, meta] of Object.entries(AREAS)) {
         const [adrs, errs] = scan_area(area);
+        totalAdrs += adrs.length;
         for (const e of errs) {
             process.stderr.write(`❌ ${e}\n`);
             hard += 1;
@@ -300,6 +334,10 @@ export function cmd_check(): number {
             warn += 1;
         }
     }
+    const dead = _dead_adr_scope(totalAdrs);
+    if (dead !== null) {
+        return dead;
+    }
     process.stdout.write(`BASELINE: ${hard} hard fail(s) · ${warn} warn(s)\n`);
     return hard ? 1 : 0;
 }

package/src/scripts/audit_auto_rules.ts

@@ -28,6 +28,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 
 import { artefact_roots } from './_lib/agent_src.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 // src/scripts/audit_auto_rules.py → parent.parent.parent == repo root.
@@ -404,9 +405,22 @@ function _ruleToJson(r: RuleEntry): Record<string, Json> {
 }
 
 export function main(): number {
-    if (_src_rule_paths().length === 0) {
-        process.stderr.write("❌  No source rules found under any artefact root's rules/\n");
-        return 1;
+    // The scanned unit is every source rule, not the `type: auto` subset
+    // `collect()` keeps: over a vanished rules/ tree "no auto-rules" still reads
+    // true, and the budget report would be regenerated with rule_count 0.
+    try {
+        assertScanned({
+            gate: 'audit_auto_rules',
+            scanned: _src_rule_paths().length,
+            units: 'source rule file(s)',
+            roots: artefact_roots().map((r) => `${_relPosix(r, REPO_ROOT) || '.'}/rules`),
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
     }
     const rules = collect();
     fs.mkdirSync(REPORT_DIR, { recursive: true });

package/src/scripts/audit_command_surface.ts

@@ -27,6 +27,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 
 import { SRC_DOMAINS } from './_lib/agent_src.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 
@@ -974,8 +975,50 @@ export function grown_packs(baseline: string, commands: Command[]): Map<string,
     return grew;
 }
 
+/**
+ * Scope guard shared by all three modes.
+ *
+ * `_rglobMdSorted` yields nothing for a root that does not exist, and every
+ * mode's verdict is a comparison over the collected commands — so a moved
+ * `src/domains` leaves the per-pack budget trivially satisfied, the overlap
+ * scan pair-less, and the surface report regenerated with `total: 0`. Only
+ * `main`'s `_exists(args.root)` guard covered that, and it does not see a
+ * present-but-command-less tree.
+ *
+ * @returns the exit code to return, or null when the scope is live.
+ */
+function _dead_scope(commands: readonly Command[], roots: readonly string[]): number | null {
+    try {
+        assertScanned({
+            gate: 'audit_command_surface',
+            scanned: commands.length,
+            units: 'command file(s)',
+            roots,
+        });
+        return null;
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // Exit 2 — this file's existing "the root is not usable" code
+            // (`error: <root> does not exist`), not 1, which means a pack
+            // exceeded its budget.
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 2;
+        }
+        throw exc;
+    }
+}
+
+/** Repo-relative form of the roots `collect_all` walks, for the scope message. */
+function _command_roots_rel(): string[] {
+    return _command_roots().map((r) => _relPosix(r, REPO_ROOT));
+}
+
 export function check_new_budget(baseline: string, quiet: boolean): number {
     const commands = collect_all();
+    const dead = _dead_scope(commands, _command_roots_rel());
+    if (dead !== null) {
+        return dead;
+    }
     const audit = build_budget_audit(commands, load_size_classes());
     const byPack = new Map<string, PackEntry>();
     for (const p of audit.packs) {
@@ -1155,6 +1198,10 @@ export function main(argv: string[] | null = null): number {
 
     if (args.budget) {
         const commands = collect_all();
+        const dead = _dead_scope(commands, _command_roots_rel());
+        if (dead !== null) {
+            return dead;
+        }
         const audit = build_budget_audit(commands, load_size_classes());
         fs.writeFileSync(OUT_BUDGET_JSON, _jsonDumpsIndent2(audit), 'utf-8');
         fs.writeFileSync(OUT_BUDGET_MD, render_budget_md(audit), 'utf-8');
@@ -1177,6 +1224,10 @@ export function main(argv: string[] | null = null): number {
     }
 
     const commands = collect(args.root);
+    const dead = _dead_scope(commands, [_relPosix(args.root, REPO_ROOT)]);
+    if (dead !== null) {
+        return dead;
+    }
     const pairs = find_overlap_pairs(commands);
 
     fs.writeFileSync(

package/src/scripts/audit_initial_context.ts

@@ -32,6 +32,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 
 import * as token_count from './_lib/token_count.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 import { SRC_AGENT, SRC_DOMAINS } from './_lib/agent_src.js';
 import * as projectThinRules from './project_thin_rules.js';
 
@@ -304,14 +305,30 @@ function _catalog(globPat: string): Measure {
     return m;
 }
 
+const CATALOG_GLOBS = {
+    skills_projected: '.claude/skills/*/SKILL.md',
+    skills_core_source: 'src/skills/*/SKILL.md',
+    commands_core_source: 'src/domains/*/**/command.md',
+} as const;
+
 export function description_catalog(): Record<string, Measure> {
     return {
-        skills_projected: _catalog('.claude/skills/*/SKILL.md'),
-        skills_core_source: _catalog('src/skills/*/SKILL.md'),
-        commands_core_source: _catalog('src/domains/*/**/command.md'),
+        skills_projected: _catalog(CATALOG_GLOBS.skills_projected),
+        skills_core_source: _catalog(CATALOG_GLOBS.skills_core_source),
+        commands_core_source: _catalog(CATALOG_GLOBS.commands_core_source),
     };
 }
 
+/**
+ * Files the catalogs glob — counted UNFILTERED, unlike the `entries` the
+ * measurement keeps (only those carrying a description). A vanished skills or
+ * commands tree must read as zero files, not as "nothing declares a
+ * description", which is indistinguishable from a clean tree at zero tokens.
+ */
+function catalog_file_count(): number {
+    return Object.values(CATALOG_GLOBS).reduce((n, pat) => n + _glob(pat).length, 0);
+}
+
 interface LongestRule {
     id: string;
     tokens_gpt: number;
@@ -700,6 +717,25 @@ function parse_args(argv: string[]): ParsedArgs {
 export function main(argv: string[] | null = null): number {
     const args = parse_args(argv ?? process.argv.slice(2));
 
+    // Every budget in BUDGETS is a token count over these catalogs: an empty
+    // catalog measures zero tokens and passes every cap, so the surface has to
+    // be proved non-empty before the caps mean anything. Exit 1 is the gate's
+    // failure code (`--fail-if-over-budget`); 2 is reserved for usage errors.
+    try {
+        assertScanned({
+            gate: 'audit_initial_context',
+            scanned: catalog_file_count(),
+            units: 'catalog file(s)',
+            roots: Object.values(CATALOG_GLOBS),
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
     const data = build();
 
     if (args.fail_if_over_budget) {

package/src/scripts/audit_mcp_tools.ts

@@ -21,6 +21,8 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 
 // src/scripts/audit_mcp_tools.ts → parent.parent.parent of the .py file = repo root.
@@ -228,6 +230,29 @@ function parse_args(argv: string[]): ParsedArgs {
 export function main(argv: string[] | null = null): number {
     const args = parse_args(argv ?? process.argv.slice(2));
 
+    // This generator walks no tree — it reads two named sources, and
+    // `_index_handlers` / `_index_catalog_lines` swallow a read failure as an
+    // empty index, so a moved `tools.ts` renders every tool `_stub-only_`
+    // rather than reporting that half the input vanished.
+    try {
+        assertWatchlistResolves({
+            gate: 'audit_mcp_tools',
+            candidates: [
+                path.posix.join('src', 'scripts', 'mcp_server', 'consumer_tool_catalog.json'),
+                path.posix.join('src', 'scripts', 'mcp_server', 'tools.ts'),
+            ],
+            repoRoot: ROOT,
+        });
+    } catch (e) {
+        if (e instanceof DeadScopeError) {
+            // 2 (the usage / could-not-run code) over 1, which this CLI
+            // documents as "the inventory drifted from the generator".
+            process.stderr.write(`❌ ${e.message}\n`);
+            return 2;
+        }
+        throw e;
+    }
+
     const catalog = JSON.parse(fs.readFileSync(CATALOG, 'utf-8')) as Catalog;
     const handlers = _index_handlers();
     const cat_lines = _index_catalog_lines();

package/src/scripts/audit_overlap.ts

@@ -28,6 +28,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);
 // src/scripts/audit_overlap.ts → parents[2] is the repo root (mirrors
 // `Path(__file__).resolve().parent.parent.parent` in the .py).
@@ -381,7 +383,28 @@ export function main(): number {
         return 1;
     }
     const data = JSON.parse(fs.readFileSync(AUDIT_JSON, 'utf-8')) as { rules: RuleEntry[] };
-    const pairs = analyse(data.rules);
+    // The existence check above does not cover a present-but-ruleless input:
+    // an upstream `audit_auto_rules` that itself scanned nothing yields a
+    // "0 pairs flagged" report, which is the answer a real clean run gives.
+    // The unit is the rules read, never the pairs flagged.
+    const rules = Array.isArray(data.rules) ? data.rules : [];
+    try {
+        assertScanned({
+            gate: 'audit_overlap',
+            scanned: rules.length,
+            units: 'rule(s)',
+            roots: ['agents/reports/auto-rules-audit.json'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // 1 is this gate's only non-zero code — same one the missing-input
+            // path uses, and for the same reason: it could not run.
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+    const pairs = analyse(rules);
     // Build the JSON payload with the two `round(x, 3)` fields wrapped as
     // PyFloat so 0.0 / 0.5 / 1.0 render with a trailing `.0` like json.dumps.
     const pairsJson: Json = pairs.map(