@event4u/agent-config 14.18.0 → 14.19.0

package/src/scripts/check_beta_review_markers.ts

@@ -63,28 +63,34 @@ interface LapsedBaseline {
     contracts: string[];
 }
 
-let _baselineCache: Set<string> | null = null;
+// Keyed by root: an unkeyed cache returns the REPO baseline for a fixture root
+// whenever the repo was read first, which silently judges a fixture against
+// production data and is invisible in the result.
+const _baselineCache = new Map<string, Set<string>>();
 
 export function loadLapsedBaseline(root: string = ROOT): Set<string> {
-    if (_baselineCache !== null) {
-        return _baselineCache;
+    const hit = _baselineCache.get(root);
+    if (hit !== undefined) {
+        return hit;
     }
     const p = path.join(root, BASELINE_REL);
     if (!fs.existsSync(p)) {
         // The baseline reaching zero is the SUCCESS state: the file is deleted
         // in the same change that flips the severity. An absent file therefore
         // means "no inherited debt", i.e. every lapse is fresh and errors.
-        _baselineCache = new Set<string>();
-        return _baselineCache;
+        const empty = new Set<string>();
+        _baselineCache.set(root, empty);
+        return empty;
     }
     const parsed = JSON.parse(fs.readFileSync(p, 'utf-8')) as LapsedBaseline;
-    _baselineCache = new Set(parsed.contracts);
-    return _baselineCache;
+    const loaded = new Set(parsed.contracts);
+    _baselineCache.set(root, loaded);
+    return loaded;
 }
 
 /** Test seam — the module-level cache would otherwise outlive a fixture. */
 export function _resetLapsedBaseline(): void {
-    _baselineCache = null;
+    _baselineCache.clear();
 }
 
 /**
@@ -115,12 +121,43 @@ const SUPERSEDED_RE = /^superseded-by:\s*\S+\s*$/m;
 
 const MAX_REVIEW_WINDOW_DAYS = 90;
 
+/**
+ * Forward horizon for the upcoming-lapse report.
+ *
+ * The gate reports a contract on the day it lapses, which is the day it is
+ * already too late to decide anything: a FRESH lapse errors, and every pull
+ * request in the repository reds until someone edits a contract under time
+ * pressure. The horizon names the set that is ABOUT to enter that branch.
+ *
+ * The number is bounded on both sides: too wide and the report names most of
+ * the forward-dated corpus on every run, which is the same as naming none; too
+ * narrow and it arrives after the decision needed to be made.
+ */
+const HORIZON_DAYS = 14;
+
 interface Violation {
     file: string;
     reason: string;
     severity: 'error' | 'warning';
 }
 
+/**
+ * A contract whose window closes within {@link HORIZON_DAYS} and which is NOT
+ * in the frozen baseline — i.e. one that will enter the ERROR branch, not the
+ * inherited-warning one.
+ *
+ * Deliberately NOT a {@link Violation}: it carries no severity and never moves
+ * the exit code. A third severity class printed into the same stream as the 84
+ * standing warnings is the way this work changes nothing (risk 1 on the
+ * roadmap's own register), so the horizon is a separate, clearly-labelled
+ * section and the exit code stays a function of real violations alone.
+ */
+interface Upcoming {
+    file: string;
+    date: string;
+    daysOut: number;
+}
+
 function _exists(p: string): boolean {
     try {
         fs.statSync(p);
@@ -184,7 +221,7 @@ function _ordinalToISO(ordinal: number): string {
     return `${y}-${m}-${d}`;
 }
 
-function check_one(p: string, todayOrdinal: number): Violation[] {
+function check_one(p: string, todayOrdinal: number, root: string = ROOT): Violation[] {
     const fm = read_frontmatter(p);
     if (fm === null) {
         return [];
@@ -199,7 +236,7 @@ function check_one(p: string, todayOrdinal: number): Violation[] {
         ['superseded-by', SUPERSEDED_RE.test(fm)],
     ];
     const setMarkers = markers.filter(([, present]) => present).map(([name]) => name);
-    const rel = _relPosix(p, ROOT);
+    const rel = _relPosix(p, root);
     if (setMarkers.length === 0) {
         return [
             {
@@ -231,7 +268,7 @@ function check_one(p: string, todayOrdinal: number): Violation[] {
         // bound because a lapsed date can never also exceed the forward window,
         // so the order is a readability choice rather than a precedence one.
         if (reviewOrdinal < todayOrdinal) {
-            const inherited = loadLapsedBaseline().has(rel);
+            const inherited = loadLapsedBaseline(root).has(rel);
             const age = todayOrdinal - reviewOrdinal;
             return [
                 {
@@ -263,6 +300,34 @@ function check_one(p: string, todayOrdinal: number): Violation[] {
     return [];
 }
 
+/**
+ * The upcoming-lapse finding for one contract, or `null`.
+ *
+ * Baselined contracts are excluded EXPLICITLY rather than by relying on the
+ * fact that a baselined contract is already lapsed and so cannot also carry a
+ * future date. That implication holds today and is not a property anything
+ * enforces; a guard that is merely vacuous cannot be distinguished from a
+ * guard that is absent, and the difference shows up the first time a baseline
+ * entry is re-dated forward.
+ */
+export function upcoming_one(
+    p: string,
+    todayOrdinal: number,
+    horizonDays: number = HORIZON_DAYS,
+    root: string = ROOT,
+): Upcoming | null {
+    const fm = read_frontmatter(p);
+    if (fm === null || !/^stability:\s*beta\s*$/m.test(fm)) return null;
+    const km = KEEP_RE.exec(fm);
+    if (!km) return null;
+    const rel = _relPosix(p, root);
+    if (loadLapsedBaseline(root).has(rel)) return null;
+    const [ry, rm, rd] = _parseISODate(km[1]!);
+    const reviewOrdinal = _dateOrdinal(ry, rm, rd);
+    const daysOut = reviewOrdinal - todayOrdinal;
+    if (daysOut < 0 || daysOut > horizonDays) return null;
+    return { file: rel, date: _ordinalToISO(reviewOrdinal), daysOut };
+}
 
 /**
  * STABILITY.md's own re-audit condition, as a command instead of as prose.
@@ -302,10 +367,16 @@ interface ParsedArgs {
     trigger: boolean;
     /** Fixture root, for `--self-test`. A fixture is never judged against the repo baseline. */
     root: string | null;
+    horizon: number;
 }
 
 function parse_args(argv: readonly string[]): ParsedArgs {
-    const args: ParsedArgs = { json: false, trigger: false, root: null };
+    const args: ParsedArgs = {
+        json: false,
+        trigger: false,
+        root: null,
+        horizon: HORIZON_DAYS,
+    };
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i] as string;
         if (arg === '--json') {
@@ -313,14 +384,27 @@ function parse_args(argv: readonly string[]): ParsedArgs {
         } else if (arg === '--root') {
             args.root = argv[i + 1] ?? null;
             i += 1;
+        } else if (arg === '--horizon') {
+            const raw = argv[i + 1] ?? '';
+            const n = Number.parseInt(raw, 10);
+            if (!/^\d+$/.test(raw) || Number.isNaN(n)) {
+                process.stderr.write(
+                    `check_beta_review_markers: error: --horizon needs a non-negative integer, got: ${raw || '(nothing)'}\n`,
+                );
+                process.exit(2);
+            }
+            args.horizon = n;
+            i += 1;
         } else if (arg === '--trigger') {
             args.trigger = true;
         } else if (arg === '-h' || arg === '--help') {
             process.stdout.write(
-                'usage: check_beta_review_markers [-h] [--json] [--trigger]\n' +
+                'usage: check_beta_review_markers [-h] [--json] [--trigger] [--horizon N]\n' +
                     '  --trigger  print the lapsed percentage and whether STABILITY.md\n' +
                     '             re-audit condition (>= 25 %) has fired. Reports; never fails.\n' +
-                    '  --root DIR judge a fixture tree instead of the repo (self-test seam).\n',
+                    '  --root DIR judge a fixture tree instead of the repo (self-test seam).\n' +
+                    `  --horizon N  days ahead to report upcoming fresh lapses (default ${String(HORIZON_DAYS)}).\n` +
+                    '             Advisory: never changes the exit code.\n',
             );
             process.exit(0);
         } else {
@@ -400,11 +484,15 @@ function main(): number {
     const scanRoot = args.root ?? ROOT;
     const contracts = _globMdSorted(path.join(scanRoot, CONTRACTS_DIR));
     let betaContracts = 0;
+    const upcoming: Upcoming[] = [];
     for (const p of contracts) {
         const fm = read_frontmatter(p);
         if (fm !== null && /^stability:\s*beta\s*$/m.test(fm)) betaContracts += 1;
-        violations.push(...check_one(p, todayOrdinal));
+        violations.push(...check_one(p, todayOrdinal, scanRoot));
+        const due = upcoming_one(p, todayOrdinal, args.horizon, scanRoot);
+        if (due !== null) upcoming.push(due);
     }
+    upcoming.sort((a, b) => a.daysOut - b.daysOut || a.file.localeCompare(b.file));
     // Count every contract read, not the `stability: beta` subset: over a moved
     // `docs/contracts/` "no beta contracts" and "no contracts at all" produce
     // the same clean line, and only the second is a dead gate. Exit 1 is the
@@ -446,7 +534,9 @@ function main(): number {
         return 0;
     }
     if (args.json) {
-        process.stdout.write(JSON.stringify({ violations }, null, 2) + '\n');
+        process.stdout.write(
+            JSON.stringify({ violations, upcoming, horizonDays: args.horizon }, null, 2) + '\n',
+        );
     } else {
         if (violations.length === 0) {
             process.stdout.write('✅  All beta contracts carry a valid review marker.\n');
@@ -455,7 +545,39 @@ function main(): number {
                 const icon = v.severity === 'error' ? '❌' : '⚠️ ';
                 process.stdout.write(`${icon}  ${v.file}: ${v.reason}\n`);
             }
-            process.stdout.write(`\n${violations.length} violation(s).\n`);
+            // Both counts, and the relationship between them, because a
+            // violation count alone cannot answer "how many contracts is this".
+            // Today they are equal — check_one returns at most one finding per
+            // contract — and printing only one of them hides the fact that it
+            // is the size of the decision, not just the size of the output.
+            const distinct = new Set(violations.map((v) => v.file)).size;
+            const baselineSize = loadLapsedBaseline(scanRoot).size;
+            const reportedInherited = violations.filter((v) =>
+                loadLapsedBaseline(scanRoot).has(v.file),
+            ).length;
+            process.stdout.write(
+                `\n${String(violations.length)} violation(s) across ` +
+                    `${String(distinct)} distinct contract(s) — one line per finding, so the ` +
+                    'two differ only where a contract carries more than one.\n',
+            );
+            process.stdout.write(
+                `Frozen baseline: ${String(baselineSize)} entries · ` +
+                    `${String(reportedInherited)} still reported as lapsed · ` +
+                    `${String(baselineSize - reportedInherited)} inert ` +
+                    '(left the lapsed set by promotion, supersession, or re-dating).\n',
+            );
+        }
+        if (upcoming.length > 0) {
+            process.stdout.write(
+                `\nUpcoming FRESH lapses within ${String(args.horizon)} day(s) — advisory, ` +
+                    'exit code unchanged. These are absent from the frozen baseline, so each\n' +
+                    'becomes an ERROR on its date rather than an inherited warning:\n',
+            );
+            for (const u of upcoming) {
+                process.stdout.write(
+                    `   ${u.file}: keep-beta-until=${u.date} in ${String(u.daysOut)} day(s) [fresh]\n`,
+                );
+            }
         }
     }
     return violations.some((v) => v.severity === 'error') ? 1 : 0;
@@ -495,9 +617,11 @@ if (_isCliEntry() || process.argv[1] === _HERE) {
 
 export {
     type Violation,
+    type Upcoming,
     ROOT,
     CONTRACTS_DIR,
     MAX_REVIEW_WINDOW_DAYS,
+    HORIZON_DAYS,
     read_frontmatter,
     check_one,
     main,

package/src/scripts/check_enforcement_coverage.ts

@@ -118,7 +118,7 @@ export interface RuleCoverage {
     /**
      * Carrier period per hook-capable platform — never a single scalar.
      *
-     * A scalar is wrong twice over: copilot has no hook surface at all, so a
+     * A scalar is wrong twice over: this package binds nothing on copilot, so a
      * weakest-platform collapse turns one platform property into a finding on
      * every hook-carried rule; and cline maps `stop` from `TaskCancel`, so the
      * same slot means per-turn on six platforms and per-interruption there. Both

package/src/scripts/check_enforcement_denominator.ts

@@ -39,9 +39,26 @@
  * Escape hatch: `<!-- enforcement-count-ok: <reason> -->` on the line, reason
  * mandatory. A bare marker stays a finding.
  *
+ * THE SECOND HALF — the projection owes the split. Exempting the generated file
+ * settles WHERE the number may be published; it says nothing about whether the
+ * published number is readable. `undeclared` quoted bare reads as a backlog
+ * somebody forgot to wire, and for nine of them that is not what it is:
+ * `block_kernel_rule_writes` refuses an `enforced_by` write on a kernel rule
+ * with no agent-accessible override, so those cannot declare one at all. The
+ * resolver has always computed `kernel_denied`; the published line dropped it
+ * and appended the word `yet`, promising a future that does not exist for that
+ * nine. So a line in the sanctioned projection that states an `undeclared`
+ * figure without its kernel-denied split is the SAME class of failure as a
+ * hand-written count elsewhere: a figure the reader cannot resolve.
+ *
+ * This deliberately does NOT check the split's value, for the same reason the
+ * first half does not check the count's — the resolver is the only source, and
+ * a value comparison here would be a second place the number lives.
+ *
  * Exit codes:
- *   0 — no hand-written enforcement count in the published corpus
- *   1 — at least one (or a marker with no reason)
+ *   0 — no hand-written enforcement count in the published corpus, and every
+ *       published `undeclared` figure carries its kernel-denied split
+ *   1 — at least one (or a marker with no reason, or a split-less figure)
  *   2 — the gate could not run (dead scan scope, bad args)
  */
 import * as fs from 'node:fs';
@@ -57,8 +74,8 @@ const _HERE = fileURLToPath(import.meta.url);
 const DEFAULT_ROOT = path.join(path.dirname(_HERE), '..', '..');
 const SELF = 'src/scripts/check_enforcement_denominator.ts';
 
-const SELF_TEST_MIN_CASES = 7;
-const SELF_TEST_MIN_REJECT = 3;
+const SELF_TEST_MIN_CASES = 10;
+const SELF_TEST_MIN_REJECT = 5;
 
 /** Roots walked, repo-relative. */
 const SCAN_ROOTS = ['docs', 'README.md'] as const;
@@ -82,6 +99,19 @@ const MARKER = 'enforcement-count-ok:';
 const ENFORCEMENT_KEYWORDS =
     /undeclared|enforced_by|enforcement coverage|carry a backstop|backstop that fails/;
 
+/**
+ * Shapes that state the `undeclared` figure itself. Narrower than
+ * {@link COUNT_SHAPES} on purpose: this is the ONE figure whose split is
+ * load-bearing, and a wider net would demand the split beside `blocking`.
+ */
+const UNDECLARED_FIGURE_SHAPES: readonly RegExp[] = [
+    /\b\d+\s+undeclared\b/i,
+    /\bundeclared\s+rules?\s*\(\s*\d+/i,
+];
+
+/** The split that makes the figure readable. Presence is checked, never value. */
+const SPLIT_TOKEN = /kernel[-_]denied/i;
+
 const COUNT_SHAPES: readonly RegExp[] = [
     /\b\d+\s+of\s+\d+\s+(?:governed\s+)?rules?\b/,
     /\b\d+\s+(?:governed\s+)?rules?\b/,
@@ -93,8 +123,12 @@ export interface Finding {
     file: string;
     line: number;
     excerpt: string;
-    /** `raw` — an unmarked count. `bare-marker` — a marker with no reason. */
-    kind: 'raw' | 'bare-marker';
+    /**
+     * `raw` — an unmarked count. `bare-marker` — a marker with no reason.
+     * `missing-split` — the projection states `undeclared` without its
+     * kernel-denied split.
+     */
+    kind: 'raw' | 'bare-marker' | 'missing-split';
 }
 
 function markerOn(line: string): 'none' | 'bare' | 'reasoned' {
@@ -123,6 +157,30 @@ export function scanText(relPath: string, text: string): Finding[] {
     return out;
 }
 
+/**
+ * The projection's own obligation: every line stating an `undeclared` figure
+ * carries the kernel-denied split. Run INSTEAD of {@link scanText} on a
+ * generated file — that file is allowed to state the number, and is the only
+ * one that owes the split.
+ */
+export function scanGenerated(relPath: string, text: string): Finding[] {
+    const out: Finding[] = [];
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i] ?? '';
+        if (!UNDECLARED_FIGURE_SHAPES.some((re) => re.test(line))) continue;
+        if (SPLIT_TOKEN.test(line)) continue;
+        if (markerOn(line) === 'reasoned') continue;
+        out.push({
+            file: relPath,
+            line: i + 1,
+            excerpt: line.trim().slice(0, 120),
+            kind: 'missing-split',
+        });
+    }
+    return out;
+}
+
 /** `true` when the file declares itself generated — i.e. it IS the projection. */
 export function isGenerated(text: string): boolean {
     return text.split('\n', GENERATED_HEAD_LINES).join('\n').includes(GENERATED_MARKER);
@@ -177,7 +235,13 @@ export function check(root: string): { code: number; findings: Finding[]; scanne
         for (const rel of files) {
             const text = fs.readFileSync(path.join(root, rel), 'utf-8');
             if (isGenerated(text)) {
-                ledger.complete(rel);
+                const split = scanGenerated(rel, text);
+                if (split.length > 0) {
+                    findings.push(...split);
+                    ledger.fail(rel, `${String(split.length)} undeclared figure(s) without the split`);
+                } else {
+                    ledger.complete(rel);
+                }
                 continue;
             }
             const found = scanText(rel, text);
@@ -259,8 +323,21 @@ export function selfTest(): number {
                 }),
         },
         {
-            name: "accepts the resolver's own generated projection",
+            name: "accepts the resolver's own generated projection when it carries the split",
             expect: 'accept',
+            run: () =>
+                run({
+                    'docs/proof.md':
+                        `<!-- ${GENERATED_MARKER} src/scripts/build_proof.ts -->\n\n` +
+                        '120 rules · 15 blocking · 86 undeclared — of which 9 kernel-denied.\n',
+                }),
+        },
+        {
+            // DENIAL POLARITY for the split half. Same file, same exemption, the
+            // split removed: the projection is allowed to state the number and is
+            // still a finding when it states it bare.
+            name: 'rejects the generated projection when the kernel-denied split is removed',
+            expect: 'reject',
             run: () =>
                 run({
                     'docs/proof.md':
@@ -268,6 +345,26 @@ export function selfTest(): number {
                         '120 rules · 15 blocking · 86 undeclared (no enforced_by yet).\n',
                 }),
         },
+        {
+            name: 'rejects a bare "Undeclared rules (N)" restatement in the projection',
+            expect: 'reject',
+            run: () =>
+                run({
+                    'docs/proof.md':
+                        `<!-- ${GENERATED_MARKER} src/scripts/build_proof.ts -->\n\n` +
+                        'Undeclared rules (86) carry no row.\n',
+                }),
+        },
+        {
+            name: 'accepts a generated line about enforcement that states no undeclared figure',
+            expect: 'accept',
+            run: () =>
+                run({
+                    'docs/proof.md':
+                        `<!-- ${GENERATED_MARKER} src/scripts/build_proof.ts -->\n\n` +
+                        '120 rules · 15 blocking · the resolver prints its own frame.\n',
+                }),
+        },
         {
             name: 'accepts a dated ADR record (docs/decisions/ is excluded)',
             expect: 'accept',
@@ -318,12 +415,25 @@ export function main(argv?: readonly string[]): number {
     if (code === 2) return 2;
 
     if (findings.length > 0) {
-        process.stdout.write('❌  hand-written enforcement count(s) in a published doc:\n\n');
+        process.stdout.write('❌  unresolvable enforcement figure(s) in a published doc:\n\n');
         for (const f of findings) {
             const why =
-                f.kind === 'bare-marker' ? `\`${MARKER}\` with no reason` : 'hand-written count';
+                f.kind === 'bare-marker'
+                    ? `\`${MARKER}\` with no reason`
+                    : f.kind === 'missing-split'
+                      ? 'published `undeclared` figure with no kernel-denied split'
+                      : 'hand-written count';
             process.stdout.write(`  ${f.file}:${String(f.line)} — ${why}\n      ${f.excerpt}\n`);
         }
+        if (findings.some((f) => f.kind === 'missing-split')) {
+            process.stdout.write(
+                '\nThe projection may state the `undeclared` figure — it is the only surface\n' +
+                    'that may — but not bare. Nine of those rules are kernel-denied:\n' +
+                    '`block_kernel_rule_writes` refuses an `enforced_by` write with no\n' +
+                    'agent-accessible override, so for them there is no *yet*. Print\n' +
+                    "`summary.kernel_denied` on the same line (`build_proof.ts` § 4b does).\n",
+            );
+        }
         process.stdout.write(
             '\nExactly one enforcement denominator is quotable, and it comes from\n' +
                 '`check_enforcement_coverage` — which resolves rather than counts, and prints\n' +
@@ -362,4 +472,4 @@ if (_isCliEntry() || process.argv[1] === _HERE) {
     process.exit(main());
 }
 
-export { SCAN_ROOTS, EXCLUDED_PREFIXES, MARKER };
+export { SCAN_ROOTS, EXCLUDED_PREFIXES, MARKER, SPLIT_TOKEN, UNDECLARED_FIGURE_SHAPES };

package/src/scripts/check_finding_dispositions.ts

@@ -50,12 +50,22 @@
  * not override either, so in CI the local tag list is EMPTY. See releaseStatus
  * for the asymmetry and the remote fallback.
  *
+ * AN EMPTY LEDGER MUST SAY WHY IT IS EMPTY. The released/unreleased split above
+ * closed the missing-file half; it left the other half open, because
+ * `findings: []` still passed while asserting nothing. A writer could satisfy
+ * the gate by creating an empty file, which is the same silence wearing the
+ * shape of a record. `no_findings_reason` is now required whenever the file
+ * exists and the array is empty — see empty_ledger_problem for what the reason
+ * has to distinguish.
+ *
  * A future reader changing allowEmpty below is the person this is addressed to:
- * the EMPTY_VALID waiver still covers a ledger that exists and is empty, and an
- * unreleased version. It no longer covers a released version with no ledger.
+ * the EMPTY_VALID waiver now covers only an EXPLAINED empty ledger and an
+ * unreleased version. It covers neither a released version with no ledger nor an
+ * empty ledger with no reason.
  *
  * Exit codes: 0 complete · 1 missing/incomplete dispositions (an absent ledger
- * for a RELEASED version is one of them) · 2 usage error, schema error, or an
+ * for a RELEASED version and an unexplained empty ledger are both among them) ·
+ * 2 usage error, schema error, or an
  * undeterminable release status. Deliberately NOT fail-open: this script never calls a model;
  * a broken ledger file is a hard error, not a neutral skip.
  */
@@ -65,7 +75,7 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 
-import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+import { DeadScopeError, reportScanned } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -91,6 +101,8 @@ export interface Ledger {
     schema_version: number;
     release: string;
     findings: LedgerFinding[];
+    /** Why the finding set is empty. Required when it is; see empty_ledger_problem. */
+    no_findings_reason?: string;
 }
 
 /** Mirrors self_review_gate.classifyBlocking — security/claim × critical/high. */
@@ -136,6 +148,36 @@ export function missing_dispositions(findings: readonly LedgerFinding[]): string
     return problems;
 }
 
+/**
+ * An empty finding set must say why it is empty.
+ *
+ * `findings: []` and a missing file made the same claim to every reader — "nothing
+ * to disposition" — and only one of them is evidence. Worse, they collapse two
+ * states that differ entirely: a review that ran and reported nothing, and a review
+ * that never ran at all. The reason field is what forces the writer to pick one and
+ * makes the pick falsifiable, so a fabricated empty ledger has to assert something
+ * a reader can check rather than merely occupy the path the gate looks at.
+ *
+ * Applies ONLY to a ledger file that exists. An absent ledger on an unreleased
+ * version is the normal in-flight state and has nothing to carry a reason.
+ */
+export function empty_ledger_problem(
+    ledger: Pick<Ledger, 'findings' | 'no_findings_reason'>,
+): string | null {
+    if (ledger.findings.length > 0) {
+        return null;
+    }
+    if ((ledger.no_findings_reason ?? '').trim() !== '') {
+        return null;
+    }
+    return (
+        'the ledger exists with an empty `findings` array and no `no_findings_reason`. '
+        + 'An unexplained empty ledger is indistinguishable from an absent one — state '
+        + 'whether the review ran and reported nothing, or did not run, and how a reader '
+        + 'can check that.'
+    );
+}
+
 export type ReleaseStatus = 'released' | 'unreleased' | 'undeterminable';
 export type RemoteReleaseAnswer = 'released' | 'unreleased' | 'unavailable';
 
@@ -410,6 +452,19 @@ function main(argv: readonly string[]): number {
         }
     }
 
+    // An existing ledger that records nothing must say why. Checked here rather
+    // than in the schema because the requirement is conditional on the finding
+    // count, which the repo's Draft-07 subset validator cannot express.
+    if (fs.existsSync(ledgerPath)) {
+        const emptyProblem = empty_ledger_problem(ledger);
+        if (emptyProblem !== null) {
+            process.stderr.write(
+                `❌  ${path.relative(REPO_ROOT, ledgerPath)}: ${emptyProblem}\n`,
+            );
+            return 1;
+        }
+    }
+
     // 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
@@ -418,7 +473,7 @@ function main(argv: readonly string[]): number {
     // durable trigger for an un-ingested finding is `--pr` mode, which compares
     // the ledger against what the self-review actually reported.
     try {
-        assertScanned({
+        reportScanned({
             gate: 'check_finding_dispositions',
             scanned: ledger.findings.length,
             units: 'recorded finding(s)',
@@ -426,11 +481,13 @@ function main(argv: readonly string[]): number {
             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. NARROWED: this no longer '
+                + 'clean release legitimately has no <version>.json. NARROWED TWICE: it no longer '
                 + 'covers a RELEASED version with no ledger, which returns 1 above on the '
-                + 'released/unreleased split; the waiver now covers an empty-but-present ledger '
-                + 'and an unreleased version. Un-ingested findings on an in-flight release are '
-                + 'caught by --pr (unrecorded_findings), never by this count.',
+                + 'released/unreleased split, and it no longer covers an empty ledger that does '
+                + 'not say why it is empty, which returns 1 above via empty_ledger_problem. What '
+                + 'remains is an EXPLAINED empty ledger and an unreleased version. Un-ingested '
+                + 'findings on an in-flight release are caught by --pr (unrecorded_findings), '
+                + 'never by this count.',
         });
     } catch (exc) {
         if (exc instanceof DeadScopeError) {