@event4u/agent-config 9.19.0 → 9.21.0

package/src/scripts/check_cluster_patterns.ts

@@ -31,7 +31,9 @@
  * a few contract rows point at full working commands that merely happen to
  * carry one nested sub-command, and those own no dispatch table.
  *
- * Exit codes: 0 = clean, 1 = pattern violations, 3 = internal error.
+ * Exit codes: 0 = clean, 1 = pattern violations, 3 = internal error (which now
+ * includes a dead scan scope — an unparseable cluster table — reported through
+ * `_lib/scan_scope` so the message names the root).
  */
 
 import * as fs from 'node:fs';
@@ -39,6 +41,7 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { SRC_DOMAINS, command_slug, resolve_logical } from './_lib/agent_src.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 // src/scripts/check_cluster_patterns.ts → two dirs up is the repo root.
@@ -369,10 +372,29 @@ function _relativeToRootOrAbs(p: string): string {
 }
 
 export function main(): number {
+    // The locked-clusters table IS the corpus — every row drives one dispatcher
+    // read. A renamed contract file or a renamed `## Locked clusters` heading
+    // parses zero rows, which used to exit 3 (internal error, advisory at call
+    // sites) rather than fail: a blind gate, not a broken one.
     const rows = load_cluster_table();
-    if (rows.length === 0) {
-        process.stderr.write(`❌  No clusters parsed from ${_relativeToRootOrAbs(CONTRACT)}\n`);
-        return 3;
+    try {
+        assertScanned({
+            gate: 'check_cluster_patterns',
+            scanned: rows.length,
+            units: 'locked-cluster row(s)',
+            roots: [_relativeToRootOrAbs(CONTRACT)],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // Exit 3, not 1: this gate's CLI contract is pinned by its py2ts
+            // port, and an empty table was ALREADY loud here (3 is non-zero, and
+            // the Taskfile fails on any non-zero). Hardening means routing the
+            // check through the shared assertion so the message names the root —
+            // not renumbering an exit code that was never a silent green.
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 3;
+        }
+        throw exc;
     }
 
     const slug_map = build_slug_map();

package/src/scripts/check_command_count_messaging.ts

@@ -8,7 +8,8 @@
  * 1 drift, 1 no-commands-dir via stderr), stdout/stderr split,
  * byte-identical messages, same canonical-count derivation
  * (iter_commands union), same per-file pattern checks in the same order.
- * No behaviour changes.
+ * No behaviour changes — except that the no-commands-dir stderr line now comes
+ * from `_lib/scan_scope` and names the empty roots; the exit code is unchanged.
  *
  * Sources canonical counts from the command frontmatter and fails when any
  * documented number drifts (README hero badge, getting-started browse line;
@@ -20,6 +21,7 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { iter_commands } from './_lib/agent_src.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -62,9 +64,23 @@ function _command_files(): string[] {
 
 function canonical_counts(): [number, number, number] {
     const files = _command_files();
-    if (files.length === 0) {
-        process.stderr.write('❌  no commands/ directory found under any artefact root\n');
-        process.exit(1);
+    try {
+        assertScanned({
+            gate: 'check_command_count_messaging',
+            scanned: files.length,
+            units: 'command file(s)',
+            roots: ['src/domains/*/**/command.md', 'src/agent-src/commands'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            // Exit 1 stays — the documented "no commands dir" code, and the
+            // Taskfile fails on any non-zero, so this was never a silent green.
+            // The assertion replaces a bare "no commands/ directory found" with
+            // a message that names the roots that came back empty.
+            process.stderr.write(`❌  ${exc.message}\n`);
+            process.exit(1);
+        }
+        throw exc;
     }
     let total = 0;
     let shims = 0;

package/src/scripts/check_comparison.ts

@@ -20,6 +20,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 
 import { REPO, pointer_unresolved } from './check_claims.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 export const DATA_REL = 'docs/comparison.yaml';
@@ -71,6 +72,23 @@ export function findErrors(rows: Row[]): string[] {
 export function main(argv: string[] = process.argv.slice(2)): number {
     const quiet = argv.includes('--quiet');
     const rows = loadRows();
+    // `loadRows` returns [] for a missing or rows-less `docs/comparison.yaml`,
+    // so a renamed data file made this gate certify "all our_evidence pointers
+    // resolve" over zero rows — the falsifiability lock passing vacuously.
+    try {
+        assertScanned({
+            gate: 'check_comparison',
+            scanned: rows.length,
+            units: 'comparison row(s)',
+            roots: [DATA_REL],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
     const errs = findErrors(rows);
     if (errs.length > 0) {
         process.stdout.write('❌ comparison-honesty:\n');

package/src/scripts/check_completion_review.ts

@@ -495,10 +495,18 @@ export function parseArtifact(text: string): ParsedArtifact {
         // LABELLED closed fence is illustrative content. A stray fence (bare, or
         // an unclosed opener) skips nothing (see scanFences) — the lines around
         // it are parsed, and the artefact is reported.
-        if (FENCE_RE.test(raw) || fences.fenced.has(i)) {
+        const trimmed = raw.trim();
+        // §2.2 row-liveness rule: fences govern the marker / honest-null / skip
+        // lines, which a fenced illustration may legitimately quote — but NOT
+        // findings rows. Hiding a marker or an honest-null fails CLOSED (the
+        // artefact reads as absent and the gate blocks); hiding a row fails OPEN
+        // (the finding silently ceases to exist). So the one line type whose
+        // concealment is dangerous is the one fences may not conceal, and a row
+        // is live wherever it appears. Only its own Status cell can excuse it.
+        const isCandidateRow = trimmed.startsWith('|');
+        if (FENCE_RE.test(raw) || (fences.fenced.has(i) && !isCandidateRow)) {
             continue;
         }
-        const trimmed = raw.trim();
         // Marker candidates must LOOK like the §2.1 HTML comment: prose that
         // merely mentions the grammar (`the \`completion-review:\` marker …`,
         // or a reviewer note quoting it in backticks — real artefacts in this
@@ -544,6 +552,12 @@ export function parseArtifact(text: string): ParsedArtifact {
             if (first === '#' || second === 'severity') {
                 continue; // header row
             }
+            // §2.2: `example` is the ONE illustrative marker. It is read from the
+            // Status cell of a six-cell row only — a short row cannot excuse
+            // itself, or `malformed-row` would become opt-out.
+            if (cells.length === 6 && (cells[4] ?? '').trim().toLowerCase() === 'example') {
+                continue;
+            }
             // EXACTLY six, per contract §2.2 — not `>= 6`. An over-long row is
             // as malformed as a short one and the surplus is usually the tell:
             // an unescaped `|` inside a cell (the shape §2.2 requires escaping)
@@ -797,8 +811,9 @@ function evaluate(input: EvalInput): Violation[] {
                 detail:
                     `${at}: stray \`\`\` fence — a bare fence delimits no region, and a labelled fence must ` +
                     'be closed. An artefact whose ``` fences do not resolve is malformed (contract §2.2). ' +
-                    'Label the opener (```markdown) and close it, or inline-escape an illustrative ```; ' +
-                    'the lines around a stray fence are still parsed, so any finding row there is validated too.',
+                    'Close the fence, or inline-escape an illustrative ```. NOTE: fences never hide a ' +
+                    'findings row — a row is live wherever it appears, and the ONLY way to mark one ' +
+                    'illustrative is the status `example` in its own Status cell.',
             });
         }
     }

package/src/scripts/check_condensed_paths.ts

@@ -47,6 +47,8 @@ import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import type * as YamlModule from 'yaml';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 // ESM-standard `require` shim. The bare `require` global is present when this
 // module is *imported* (tsx injects it) but absent when the module is the
 // directly-executed CLI entry, so resolve it explicitly here to preserve the
@@ -359,7 +361,26 @@ function main(): number {
     }
     const viols: Violation[] = [];
     const audited: Array<[string, IgnoreEntry]> = [];
-    for (const ruleFile of _globMdSorted(RULES_DIR)) {
+    const ruleFiles = _globMdSorted(RULES_DIR);
+    // The guard above only proves the directory node exists; an empty one still
+    // renders "clean (0 rules, 0 ignore(s) audited)". Exit 3 is the code that
+    // guard already uses for "there was nothing to check" — 1 means violations
+    // were found, which is a different claim.
+    try {
+        assertScanned({
+            gate: 'check_condensed_paths',
+            scanned: ruleFiles.length,
+            units: 'rule file(s)',
+            roots: ['dist/agent-src/rules'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 3;
+        }
+        throw exc;
+    }
+    for (const ruleFile of ruleFiles) {
         const text = fs.readFileSync(ruleFile, 'utf-8');
         const [fm, body] = _split_frontmatter(text);
         const ignores: IgnoreEntry[] = fm !== null ? _parse_ignores(fm) : [];
@@ -383,7 +404,7 @@ function main(): number {
         process.stdout.write(`\n${viols.length} violation(s) in dist/agent-src/rules/\n`);
         return 1;
     }
-    const ruleCount = _globMdSorted(RULES_DIR).length;
+    const ruleCount = ruleFiles.length;
     if (!QUIET) {
         process.stdout.write(
             `✅  condensed-path check clean (${ruleCount} rules, ${audited.length} ignore(s) audited)\n`,

package/src/scripts/check_consumer_scope_flip.ts

@@ -32,6 +32,7 @@ import * as path from 'node:path';
 import { parse as parseYaml } from 'yaml';
 
 import { excludedRuleBasenames, ruleScopeFromSettings } from '../install/rule_scope.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 export const RULES_DIR = 'dist/agent-src/rules';
 export const TEMPLATE = 'src/config/agent-settings.template.yml';
@@ -112,8 +113,26 @@ async function main(): Promise<number> {
     let legacyTok = 0;
     let scopedRules = 0;
     let scopedTok = 0;
-    for (const name of fs.readdirSync(RULES_DIR).sort()) {
-        if (!name.endsWith('.md')) continue;
+    // The shipped rule tree is the corpus the before/after evidence is measured
+    // over. An emptied `dist/agent-src/rules` keeps every verdict vacuously true
+    // — nothing excluded, nothing dropped — so `pass` stays true and the flip
+    // reports as "verified" against a zero-rule baseline (with a NaN delta).
+    const ruleFiles = fs.readdirSync(RULES_DIR).sort().filter((n) => n.endsWith('.md'));
+    try {
+        assertScanned({
+            gate: 'check_consumer_scope_flip',
+            scanned: ruleFiles.length,
+            units: 'projected rule file(s)',
+            roots: [RULES_DIR],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+    for (const name of ruleFiles) {
         const body = fs.readFileSync(path.join(RULES_DIR, name), 'utf-8');
         const tok = gpt_tokens(body).tokens;
         // legacy-all baseline mirrors the 2026-07-08 report: compat exclusion applies on both arms

package/src/scripts/check_council_config_location.ts

@@ -54,6 +54,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.includes('--quiet');
 
 // Agent-facing surfaces where council config must resolve to `.ai-council.yml`.
@@ -318,6 +320,24 @@ function find_path_violations(root: string): string[] {
 
 function main(): number {
     const root = process.cwd();
+    // PATH_CHECK_GLOBS is the superset of both passes, so its resolution is the
+    // whole corpus either check can see. Run from the wrong cwd — or after the
+    // council surfaces move — every glob resolves to nothing and the gate
+    // reports "clean". Exit 1 is its only failure code.
+    try {
+        assertScanned({
+            gate: 'check_council_config_location',
+            scanned: [...iter_files(root, PATH_CHECK_GLOBS)].length,
+            units: 'council-surface file(s)',
+            roots: PATH_CHECK_GLOBS,
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
     const findings = [...find_violations(root), ...find_path_violations(root)];
     if (findings.length) {
         process.stdout.write('❌  Council config-location violations:\n\n');

package/src/scripts/check_council_layout.ts

@@ -19,6 +19,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 AGENTS_ROOT = 'agents';
@@ -88,6 +90,16 @@ function _isFile(p: string): boolean {
 
 function find_violations(root: string): string[] {
     const findings: string[] = [];
+    // `agents/` is resolved relative to the cwd, so a run from anywhere but the
+    // repo root walks nothing and reports a clean layout. Thrown, not returned —
+    // `findings` is the violation channel, and a dead scope is not a violation.
+    const descendants = _isDir(root) ? _rglobAllSorted(root) : [];
+    assertScanned({
+        gate: 'check_council_layout',
+        scanned: descendants.length,
+        units: 'agents/ entries',
+        roots: [AGENTS_ROOT],
+    });
     if (!_isDir(root)) {
         return findings;
     }
@@ -110,7 +122,7 @@ function find_violations(root: string): string[] {
     }
 
     // 2. Council artefacts in non-canonical subdirectories.
-    for (const p of _rglobAllSorted(root)) {
+    for (const p of descendants) {
         if (!_isFile(p) || !is_council_artefact(path.basename(p))) {
             continue;
         }
@@ -144,7 +156,15 @@ function _posix(p: string): string {
 
 function main(argv: readonly string[]): number {
     const quiet = argv.includes('--quiet');
-    const findings = find_violations(AGENTS_ROOT);
+    let findings: string[];
+    try {
+        findings = find_violations(AGENTS_ROOT);
+    } catch (exc) {
+        if (!(exc instanceof DeadScopeError)) throw exc;
+        // Exit 1 is this gate's only failure code.
+        process.stderr.write(`❌  ${exc.message}\n`);
+        return 1;
+    }
     if (findings.length > 0) {
         process.stdout.write('❌  Council layout violations:\n\n');
         for (const f of findings) {

package/src/scripts/check_council_references.ts

@@ -40,6 +40,7 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { artefact_roots, strip_source_prefix } from './_lib/agent_src.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const QUIET = process.argv.includes('--quiet');
 
@@ -284,7 +285,14 @@ function* _iter_files(roots: readonly string[]): Generator<string> {
 
 function main(): number {
     const violations: Array<[string, number, string]> = [];
-    for (const p of _iter_files(_scan_roots())) {
+    const roots = _scan_roots();
+    // Counted before the allowlist filter — the question is what the walk
+    // reached, not what survived it. Every scan root is skipped when absent, so
+    // a relocated `docs/` or `agents/` leaves the linter reporting "no forbidden
+    // references" over an empty corpus. Exit 1 is its only failure code.
+    let scanned = 0;
+    for (const p of _iter_files(roots)) {
+        scanned += 1;
         const rel = p.split(path.sep).join('/');
         if (_is_allowlisted(rel)) {
             continue;
@@ -293,6 +301,20 @@ function main(): number {
             violations.push([p, ln, ref]);
         }
     }
+    try {
+        assertScanned({
+            gate: 'check_council_references',
+            scanned,
+            units: 'durable artefact file(s)',
+            roots,
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stdout.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
 
     if (violations.length === 0) {
         if (!QUIET) {

package/src/scripts/check_dependency_floors.ts

@@ -37,6 +37,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), '..', '..', '..');
 
 /**
@@ -137,9 +139,23 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
         process.stderr.write(`❌  dependency floors: cannot read ${manifestPath}: ${String(err)}\n`);
         return 2;
     }
-    if (Object.keys(dependencies).length === 0) {
-        process.stderr.write('❌  dependency floors: no runtime dependencies found — gate would pass vacuously\n');
-        return 2;
+    // Replaces the ad-hoc "gate would pass vacuously" guard with the shared
+    // assertion — same condition, same exit code (2 = the manifest yielded no
+    // corpus, vs 1 = a floor violates the rule), now counted on the unfiltered
+    // read rather than on what `evaluate` judges.
+    try {
+        assertScanned({
+            gate: 'check_dependency_floors',
+            scanned: Object.keys(dependencies).length,
+            units: 'runtime dependency floor(s)',
+            roots: ['package.json#dependencies'],
+        });
+    } catch (err) {
+        if (err instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${err.message}\n`);
+            return 2;
+        }
+        throw err;
     }
     const errors = evaluate(dependencies);
     if (asJson) {

package/src/scripts/check_discovery_determinism.ts

@@ -19,6 +19,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 _HERE = fileURLToPath(import.meta.url);
 const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 const SCANNER = path.join(ROOT, 'src', 'scripts', 'build_discovery_manifest.ts');
@@ -76,6 +78,30 @@ class ExitError extends Error {}
 function main(): number {
     const a = _normalise(_run());
     const b = _normalise(_run());
+
+    // Determinism over an EMPTY manifest is vacuously true: if the scanner's
+    // artefact roots moved, both runs emit zero artefacts, the two payloads
+    // compare equal, and this gate reports "OK: deterministic" having compared
+    // nothing. Assert the corpus the comparison ran over, not the comparison.
+    // Deletion test: wiping the artefact tree would give 0 — which is blindness
+    // here, never success — so no `allowEmpty`. Exit 1 is this pinned CLI's
+    // only failure code (the scanner-failed path also exits 1, via ExitError).
+    const artefacts = a['artefacts'];
+    try {
+        assertScanned({
+            gate: 'check_discovery_determinism',
+            scanned: Array.isArray(artefacts) ? artefacts.length : 0,
+            units: 'manifest artefact(s)',
+            roots: ['src/scripts/build_discovery_manifest.ts → manifest.artefacts'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
     const sa = _dumps(a);
     const sb = _dumps(b);
     if (sa !== sb) {

package/src/scripts/check_enforcement_coverage.ts

@@ -37,6 +37,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const _HERE = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(_HERE, '..', '..');
 const RULES_DIR = path.join(REPO_ROOT, 'src', 'rules');
@@ -478,6 +480,24 @@ function main(argv: string[]): number {
     }
 
     const rows = collect();
+    // Count every rule read, not the declared subset: with an empty rules dir
+    // the report renders "0/0 rules (0%)" and exits green, and `summarise`
+    // special-cases the zero denominator rather than rejecting it. Exit 2 is
+    // the code the missing-rules-dir guard above already uses for this class.
+    try {
+        assertScanned({
+            gate: 'check_enforcement_coverage',
+            scanned: rows.length,
+            units: 'rule file(s)',
+            roots: ['src/rules'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 2;
+        }
+        throw exc;
+    }
     const summary = summarise(rows);
 
     if (as_json) {

package/src/scripts/check_evaluator_budgets.ts

@@ -40,6 +40,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 BUDGETS_PATH = path.join(REPO_ROOT, 'src', 'config', 'evaluator-budgets.json');
 
@@ -230,6 +232,27 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         return 2;
     }
 
+    // The budget document IS the corpus: every finding below is produced by
+    // iterating it, so a budgets file that parses to no entries reports
+    // "✅ evaluator budgets met (0 metrics)" — green over nothing, the exact
+    // shape this harness exists to end. A missing `budgets` key counts as 0 for
+    // the same reason. Exit 2 (documented internal error — the gate could not
+    // run), never 1, which means a metric actually breached.
+    try {
+        assertScanned({
+            gate: 'check_evaluator_budgets',
+            scanned: Object.keys(budgetsDoc.budgets ?? {}).length,
+            units: 'budgeted metric(s)',
+            roots: ['src/config/evaluator-budgets.json (budgets)'],
+        });
+    } catch (e) {
+        if (e instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${e.message}\n`);
+            return 2;
+        }
+        throw e;
+    }
+
     // The committed record is optional: a fresh checkout before the first
     // nightly has none, and a missing record must not fake a green drift check.
     const recordPath = argValue(argv, '--recorded') ?? path.join(REPO_ROOT, RECORD_REL);

package/src/scripts/check_finding_dispositions.ts

@@ -34,6 +34,8 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 
@@ -235,6 +237,33 @@ function main(argv: readonly string[]): number {
         }
     }
 
+    // Scope declaration, not a scope guard. The ledger is written per release by
+    // `--ingest`, so "no <release>.json" is the normal state of a release whose
+    // self-review reported nothing — the gate's own success line says so. That
+    // makes an absent file indistinguishable from a moved ledger dir here, and
+    // the honest reading is that the corpus count cannot carry that signal: the
+    // durable trigger for an un-ingested finding is `--pr` mode, which compares
+    // the ledger against what the self-review actually reported.
+    try {
+        assertScanned({
+            gate: 'check_finding_dispositions',
+            scanned: ledger.findings.length,
+            units: 'recorded finding(s)',
+            roots: [path.relative(REPO_ROOT, ledgerPath)],
+            allowEmpty:
+                'EMPTY_VALID: zero recorded findings IS the pass state for a release whose '
+                + 'self-review reported none — the ledger file is created on first --ingest, so a '
+                + 'clean release legitimately has no <version>.json. Un-ingested findings are '
+                + 'caught by --pr (unrecorded_findings), never by this count.',
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
     const problems = missing_dispositions(ledger.findings);
     if (pr) {
         const reported = parse_comment_findings(_gh_comment_bodies(pr));