@event4u/agent-config 14.11.0 → 14.12.0

package/src/scripts/check_estate_count.ts

@@ -152,6 +152,7 @@ import { reportScanned, DeadScopeError } from './_lib/scan_scope.js';
 import { GateLedger } from './_lib/gate_ledger.js';
 import { resolveBaseRef } from './_lib/ratchet_base_ref.js';
 import { materialiseSubtree } from './_lib/base_tree.js';
+import { SKILLS_POSIX, measureSkillEstate } from './_lib/skill_estate.js';
 import { runGateCli, runSelfTest, type SelfTestCase } from './_lib/gate_self_test.js';
 
 const GATE = 'check_estate_count';
@@ -171,11 +172,35 @@ export interface EstateCounts {
     active_roadmaps: number;
     later_roadmaps: number;
     open_blockers: number;
+    /**
+     * Maintained `SKILL.md` files — `lifecycle: deprecated` excluded.
+     *
+     * A FOURTH corpus on the same machinery, added 2026-08-24 on AI council 2/2
+     * over the alternative of a second budget file and a second gate: the
+     * floor-from-the-base-ref machinery is the expensive part and should not be
+     * written twice, and a second ratchet is a second place to forget.
+     */
+    skill_count: number;
+    /**
+     * Exact-BPE tokens across those skills' `description:` fields.
+     *
+     * The second DIMENSION, not a companion figure. A count ratchet alone is
+     * gameable by merging four large skills into one file: the count falls, the
+     * payload a host must carry does not. `0` here means UNRESOLVED, never
+     * "no tokens" — see `tokensExact`.
+     */
+    skill_description_tokens: number;
 }
 
 export type MetricName = keyof EstateCounts;
 
-export const METRICS: readonly MetricName[] = ['active_roadmaps', 'later_roadmaps', 'open_blockers'];
+export const METRICS: readonly MetricName[] = [
+    'active_roadmaps',
+    'later_roadmaps',
+    'open_blockers',
+    'skill_count',
+    'skill_description_tokens',
+];
 
 export interface EstateBudget {
     /**
@@ -247,6 +272,16 @@ export interface EstateVerdict {
     authorisedGrowth: GrowthFinding[];
     /** The claims found in this change's diff, with their reasons. */
     claims: GrowthClaim[];
+    /**
+     * Metrics dropped from the compare, each with its reason.
+     *
+     * Never empty-and-silent: a skill metric drops when the base ref carries no
+     * `src/skills` (an old tag, a shallow clone) or when the tokeniser resolved
+     * on one side and not the other. Comparing an exact reading against a proxy
+     * one would move the number by more than the growth this gate exists to
+     * catch, so the metric is stated unavailable rather than guessed.
+     */
+    skippedMetrics: { metric: MetricName; reason: string }[];
     /** `null` when the diff half could not run; the reason is printed either way. */
     offsets: OffsetLedger | null;
     offsetSkipReason: string | null;
@@ -342,13 +377,26 @@ export function countEstate(repoRoot: string): EstateCounts {
     const stats = collect(roadmapRoot);
     const openOf = (rows: readonly { open_blockers: readonly unknown[] }[]): number =>
         rows.reduce((n, r) => n + r.open_blockers.length, 0);
+    const skills = measureSkillEstate(repoRoot);
     return {
         active_roadmaps: stats.length,
         later_roadmaps: countIn(roadmapRoot, 'later'),
         open_blockers: openOf(stats) + openOf(laterRoadmaps(roadmapRoot)),
+        skill_count: skills.skill_count,
+        // 0 stands for unresolved. `skillTokensExact` below is what the caller
+        // reads to tell that apart from a genuinely empty corpus, and the
+        // verdict skips the metric rather than comparing an exact reading
+        // against a proxy one — they differ by more than the growth a ratchet
+        // is trying to catch.
+        skill_description_tokens: skills.skill_description_tokens ?? 0,
     };
 }
 
+/** Did the tokeniser resolve under `root`? A ratchet must not mix the two modes. */
+export function skillTokensExact(root: string): boolean {
+    return measureSkillEstate(root).skill_description_tokens !== null;
+}
+
 /** `agents/roadmaps/<name>.md` — the active top level, never a subdirectory. */
 function isActiveTopLevel(rel: string): boolean {
     const norm = rel.split(path.sep).join('/');
@@ -506,19 +554,57 @@ export function evaluate(
     // property, and unlike a number nobody has to remember to update it.
     let floor: EstateCounts | null = null;
     let floorSkipReason: string | null = null;
+    /** Set when the base ref carries no `src/skills` — the skill metrics drop. */
+    let skillFloorSkipReason: string | null = null;
+    /** Set when either side's tokeniser did not resolve — that ONE metric drops. */
+    let skillTokenSkipReason: string | null = null;
+    if (!skillTokensExact(repoRoot)) {
+        skillTokenSkipReason =
+            'the tokeniser did not resolve at HEAD; an exact reading may not be compared ' +
+            'against a proxy one';
+    }
     if (baseRef === null || baseRef === undefined) {
         floorSkipReason =
             'no base ref resolved (no origin/main, no merge-commit parent) — the floor cannot be measured';
     } else {
         const base = materialiseSubtree(repoRoot, baseRef, ROADMAPS_POSIX);
+        // TWO subtrees, because the estate now spans two corpora and the floor
+        // must be measured on the base ref's own tree for BOTH. Materialised
+        // separately rather than widening the first call: `materialiseSubtree`
+        // takes one prefix, and the roadmap tree must stay readable even when
+        // the skills read fails (a `src/skills`-less base ref is a real state —
+        // an old tag, a shallow clone), in which case the skill metrics skip and
+        // the roadmap metrics still ratchet.
+        const baseSkills = materialiseSubtree(repoRoot, baseRef, SKILLS_POSIX);
         try {
             if (base.error !== null || base.files === 0) {
                 floorSkipReason = `could not read ${ROADMAPS_POSIX} at ${baseRef} — ${base.error ?? 'no files'}`;
             } else {
-                floor = countEstate(base.root);
+                const roadmapFloor = countEstate(base.root);
+                if (baseSkills.error !== null || baseSkills.files === 0) {
+                    // Roadmap floor stands; the skill floor is stated as
+                    // unavailable and its metrics are dropped from the compare.
+                    floor = roadmapFloor;
+                    skillFloorSkipReason =
+                        `could not read ${SKILLS_POSIX} at ${baseRef} — ` +
+                        `${baseSkills.error ?? 'no files'}`;
+                } else {
+                    const s = measureSkillEstate(baseSkills.root);
+                    floor = {
+                        ...roadmapFloor,
+                        skill_count: s.skill_count,
+                        skill_description_tokens: s.skill_description_tokens ?? 0,
+                    };
+                    if (s.skill_description_tokens === null) {
+                        skillTokenSkipReason =
+                            `the tokeniser did not resolve at ${baseRef}; an exact reading may ` +
+                            'not be compared against a proxy one';
+                    }
+                }
             }
         } finally {
             fs.rmSync(base.root, { recursive: true, force: true });
+            fs.rmSync(baseSkills.root, { recursive: true, force: true });
         }
     }
 
@@ -571,11 +657,32 @@ export function evaluate(
         active_roadmaps: offsets?.exempt.length ?? 0,
         later_roadmaps: offsets?.parked.length ?? 0,
         open_blockers: 0,
+        // The skill corpus gets NO allowance, and that is the whole point of the
+        // metric: the defect it addresses is a corpus that grew +8 in one release
+        // with nothing objecting. An addition takes the `estate_growth_exempt`
+        // claim path — a recorded reason in the diff — or it fails.
+        skill_count: 0,
+        skill_description_tokens: 0,
+    };
+
+    /** Metrics dropped from the compare, with the reason, never silently. */
+    const skippedMetrics: { metric: MetricName; reason: string }[] = [];
+    const skipMetric = (metric: MetricName): boolean => {
+        if (skillFloorSkipReason !== null && (metric === 'skill_count' || metric === 'skill_description_tokens')) {
+            skippedMetrics.push({ metric, reason: skillFloorSkipReason });
+            return true;
+        }
+        if (skillTokenSkipReason !== null && metric === 'skill_description_tokens') {
+            skippedMetrics.push({ metric, reason: skillTokenSkipReason });
+            return true;
+        }
+        return false;
     };
 
     const over: GrowthFinding[] = [];
     if (floor !== null) {
         for (const metric of METRICS) {
+            if (skipMetric(metric)) continue;
             const live = counts[metric];
             const allowed = floor[metric] + allowance[metric];
             if (live > allowed) {
@@ -596,6 +703,7 @@ export function evaluate(
         growth,
         authorisedGrowth,
         claims,
+        skippedMetrics,
         offsets,
         offsetSkipReason,
         unpaid,
@@ -1010,8 +1118,12 @@ export function main(argv: string[] = process.argv.slice(2)): number {
 
     for (const g of verdict.growth) {
         const allow = g.allowance > 0 ? ` (+${String(g.allowance)} allowed here)` : '';
+        // Two corpora share this gate, so the line names which one grew. It used
+        // to say "the roadmap estate" unconditionally, which was already the
+        // wrong noun for `skill_count` the moment that metric landed.
+        const corpus = g.metric.startsWith('skill_') ? 'the skill estate' : 'the roadmap estate';
         process.stderr.write(
-            `❌  the roadmap estate grew: ${g.metric} ${String(g.floor)} → ${String(g.live)}${allow}.\n` +
+            `❌  ${corpus} grew: ${g.metric} ${String(g.floor)} → ${String(g.live)}${allow}.\n` +
                 `    The floor is the measurement at ${verdict.floorRef ?? 'the base ref'}, not a number in a\n` +
                 '    config — so there is no number to edit and nothing to walk. The estate does not\n' +
                 '    walk down by itself, which is the defect this ratchet exists for. Either close,\n' +
@@ -1022,6 +1134,13 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         );
     }
 
+    // A dropped metric is REPORTED, never silent: a reader must be able to tell
+    // "within its ratchet" from "within the ratchet of the metrics that could be
+    // measured". This is the same distinction the floor-skip reason above keeps.
+    for (const s of verdict.skippedMetrics) {
+        process.stdout.write(`  ⏭️  ${s.metric} not compared — ${s.reason}\n`);
+    }
+
     if (verdict.unpaid > 0 && verdict.offsets !== null) {
         process.stderr.write(
             `❌  ${String(verdict.unpaid)} new active roadmap(s) with no offset in the same change.\n` +

package/src/scripts/check_preamble_payload_budget.ts

@@ -91,19 +91,46 @@ export function measureDeterministicPayload(
     ];
 }
 
-export function evaluate(repoRoot?: string, budgetFile?: string): BudgetVerdict {
+/**
+ * A caller-supplied ceiling, and the one direction it may go.
+ *
+ * road-to-standing-payload-truth 1.1 arms this gate in CI behind a GRACE ceiling
+ * equal to the 2026-08-24 measurement, because HEAD is 28.4 % over the design
+ * ceiling and blocking at the design number would fail every pull request from
+ * the moment the workflow lands — nobody can shed 30,566 tokens inside the PR
+ * that arms the gate.
+ *
+ * **An override may only be LOOSER than the design ceiling, and it is refused if
+ * it is tighter.** That sounds backwards for one line and is the whole point: a
+ * tighter override would let a caller silently *lower* the bar this file owns,
+ * which is the config-weakening shape in reverse — the design ceiling stays the
+ * authority, and the override is a dated, expiring concession recorded in
+ * `ci_delivery`. Tightening happens by lowering `baseline_tokens`, in the file,
+ * with a reason, where a reviewer sees it.
+ */
+export function evaluate(repoRoot?: string, budgetFile?: string, overrideCeiling?: number): BudgetVerdict {
     const budget = readBudget(budgetFile);
     const buckets = measureDeterministicPayload(repoRoot);
     const measured = buckets.reduce((sum, b) => sum + b.tokens, 0);
-    const ceiling = Math.round(budget.baseline_tokens * (1 + budget.headroom_pct / 100));
+    const design = Math.round(budget.baseline_tokens * (1 + budget.headroom_pct / 100));
+    const ceiling =
+        overrideCeiling !== undefined && Number.isFinite(overrideCeiling) && overrideCeiling > design
+            ? overrideCeiling
+            : design;
     return { measured, baseline: budget.baseline_tokens, ceiling, withinBudget: measured <= ceiling, buckets };
 }
 
 export function main(argv: string[] = process.argv.slice(2)): number {
     const json = argv.includes('--format=json') || argv.includes('--json');
+    // `--ceiling <n>`: the grace ceiling the CI step reads out of
+    // `ci_delivery.grace_ceiling`. Read from the budget file there, never written
+    // in the workflow, so the number has exactly one home. A non-numeric or
+    // tighter-than-design value is IGNORED rather than honoured — see `evaluate`.
+    const ci = argv.indexOf('--ceiling');
+    const override = ci !== -1 && argv[ci + 1] !== undefined ? Number(argv[ci + 1]) : undefined;
     let verdict: BudgetVerdict;
     try {
-        verdict = evaluate();
+        verdict = evaluate(undefined, undefined, override);
     } catch (err) {
         process.stderr.write(`❌  preamble-payload budget: ${(err as Error).message}\n`);
         return 2;

package/src/scripts/check_routing_coverage.ts

@@ -0,0 +1,352 @@
+#!/usr/bin/env tsx
+/**
+ * `check_routing_coverage` — two coverage ratchets, one per routed scope.
+ *
+ * `road-to-routing-assurance` Phase 0.3. Coverage ratio = corpus cases / routed
+ * units, per scope, seeded at the measured current value. **CI fails only on a
+ * DECREASE** — the same COUNT-ratchet disposition `lint_trigger_precision.ts`
+ * already uses, and for the same reason: the number is a property of the estate,
+ * so a rise is somebody's work and a fall is somebody's omission.
+ *
+ * TWO scopes, never one aggregate, because the aggregate hides the finding:
+ *
+ *   rules  94 / 105 = 0.895   deterministic corpus, gating
+ *   skills 76 / 299 = 0.254   advisory live harness only
+ *
+ * The rules surface is ~90 % covered by a corpus that can fail a PR. The skills
+ * surface — the one production actually routes on — is 25 %, covered only by a
+ * harness that is "advisory only, never gating" (`rule_trigger_eval.ts:4`). One
+ * blended figure would read as ~46 % and describe neither.
+ *
+ * WHY A RATIO AND NOT A COUNT: the denominator moves. Adding 8 skills without
+ * adding corpus cases lowers coverage while every count rises, and a count
+ * ratchet would call that progress.
+ *
+ * Exit codes: 0 = at or above seed · 1 = a scope fell · 2 = dead scope.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+import { GateLedger } from './_lib/gate_ledger.js';
+import { type SelfTestCase, runGateCli, runSelfTest } from './_lib/gate_self_test.js';
+import { DeadScopeError, reportScanned } from './_lib/scan_scope.js';
+
+const HERE = fileURLToPath(import.meta.url);
+const REAL_REPO_ROOT = path.resolve(path.dirname(HERE), '..', '..');
+/**
+ * Scan root. The env override exists for `--self-test`, which drives the REAL
+ * CLI against a synthetic tree — an in-process call would skip the argv parsing
+ * and the entry guard, and a gate resolving its root from `import.meta.url`
+ * reads the live checkout whatever the cwd, so every fixture would be green for
+ * the wrong reason.
+ */
+const REPO_ROOT = process.env['CHECK_ROUTING_COVERAGE_ROOT'] ?? REAL_REPO_ROOT;
+export const SEED_REL = 'src/config/routing-coverage-seed.json';
+
+export type Scope = 'rules' | 'skills';
+
+export interface ScopeReading {
+    scope: Scope;
+    cases: number;
+    units: number;
+    ratio: number;
+}
+
+export interface Seed {
+    rules: number;
+    skills: number;
+}
+
+/** Routed rules = every tier-1 and tier-2 entry in the compiled router. */
+export function measureRules(root: string): ScopeReading {
+    const routerPath = path.join(root, 'dist', 'router.json');
+    let doc: { tier_1?: { id: string }[]; tier_2?: { id: string }[] };
+    try {
+        doc = JSON.parse(fs.readFileSync(routerPath, 'utf-8')) as typeof doc;
+    } catch {
+        throw new DeadScopeError(
+            'check_routing_coverage',
+            'dist/router.json is unreadable — the routed-rule denominator cannot be measured, ' +
+                'and a missing router is not a coverage of zero.',
+        );
+    }
+    const ids = new Set([...(doc.tier_1 ?? []), ...(doc.tier_2 ?? [])].map((r) => r.id));
+    const dir = path.join(root, 'tests', 'eval', 'routing-matrix');
+    let files: string[];
+    try {
+        files = fs.readdirSync(dir);
+    } catch {
+        files = [];
+    }
+    const stems = new Set(
+        files.filter((f) => /\.ya?ml$/.test(f)).map((f) => f.replace(/\.ya?ml$/, '')),
+    );
+    // Intersection, not the file count: a fixture naming no routed rule covers
+    // nothing, and counting it would let the ratio rise on dead files.
+    let covered = 0;
+    for (const s of stems) if (ids.has(s)) covered += 1;
+    return { scope: 'rules', cases: covered, units: ids.size, ratio: ids.size === 0 ? 0 : covered / ids.size };
+}
+
+/** Routed skills = every SKILL.md; a case = that skill's `evals/triggers.json`. */
+export function measureSkills(root: string): ScopeReading {
+    const base = path.join(root, 'src', 'skills');
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(base, { withFileTypes: true });
+    } catch {
+        throw new DeadScopeError(
+            'check_routing_coverage',
+            'src/skills is unreadable — the routed-skill denominator cannot be measured.',
+        );
+    }
+    let units = 0;
+    let cases = 0;
+    for (const e of entries) {
+        if (!e.isDirectory()) continue;
+        if (!fs.existsSync(path.join(base, e.name, 'SKILL.md'))) continue;
+        units += 1;
+        if (fs.existsSync(path.join(base, e.name, 'evals', 'triggers.json'))) cases += 1;
+    }
+    return { scope: 'skills', cases, units, ratio: units === 0 ? 0 : cases / units };
+}
+
+export function readSeed(root: string): Seed {
+    const p = path.join(root, SEED_REL);
+    let raw: string;
+    try {
+        raw = fs.readFileSync(p, 'utf-8');
+    } catch {
+        throw new DeadScopeError(
+            'check_routing_coverage',
+            `${SEED_REL} is missing — a ratchet with no seed passes every tree.`,
+        );
+    }
+    const doc = JSON.parse(raw) as { seed?: Partial<Seed> };
+    const s = doc.seed ?? {};
+    if (typeof s.rules !== 'number' || typeof s.skills !== 'number') {
+        throw new DeadScopeError(
+            'check_routing_coverage',
+            `${SEED_REL} carries no numeric seed for both scopes.`,
+        );
+    }
+    return { rules: s.rules, skills: s.skills };
+}
+
+export interface Verdict {
+    readings: ScopeReading[];
+    seed: Seed;
+    fallen: Scope[];
+    ledger: GateLedger;
+}
+
+/**
+ * Compare against the seed.
+ *
+ * Rounded to four decimals before comparing: an un-rounded float makes a ratio
+ * that did not change fail on a representation difference, which is a red the
+ * contributor cannot act on.
+ */
+/**
+ * The comparison precision, shared by the verdict AND the display.
+ *
+ * Exported because the first version rounded only inside `evaluate` and printed
+ * the raw float: rules read 0.895238… against a seed of 0.8952 and rendered `↑`,
+ * skills read 0.254180… against 0.2542 and rendered `❌`, while the summary line
+ * correctly said green. A gate whose rows contradict its verdict is worse than
+ * one that is simply wrong, because the reader cannot tell which half to trust.
+ */
+export function r4(n: number): number {
+    return Math.round(n * 10_000) / 10_000;
+}
+
+export function evaluate(root = REPO_ROOT): Verdict {
+    const seed = readSeed(root);
+    const readings = [measureRules(root), measureSkills(root)];
+    // The ledger's target is the SCOPE, not the individual unit: this gate's
+    // verdict is per scope, so a ledger over 404 units would report 404 rows
+    // no one can act on while hiding which of the two actually fell.
+    const ledger = new GateLedger('check_routing_coverage');
+    ledger.plan(readings.map((r) => r.scope));
+    const fallen: Scope[] = [];
+    for (const r of readings) {
+        if (r4(r.ratio) < r4(seed[r.scope])) {
+            fallen.push(r.scope);
+            ledger.fail(
+                r.scope,
+                `${r.ratio.toFixed(4)} < seed ${seed[r.scope].toFixed(4)} ` +
+                    `(${String(r.cases)}/${String(r.units)})`,
+            );
+        } else {
+            ledger.complete(r.scope);
+        }
+    }
+    return { readings, seed, fallen, ledger };
+}
+
+/**
+ * Build a synthetic tree with `r` routed rules of which `rc` carry a fixture,
+ * and `s` routed skills of which `sc` carry a triggers file, plus a seed.
+ *
+ * A REALISTIC corpus rather than a minimal one: both scopes are always
+ * populated, because the gate reports two scopes and a fixture that leaves one
+ * empty would red for the empty scope no matter what the case under test does.
+ */
+function selfTestRoot(
+    tmp: string,
+    spec: { r: number; rc: number; s: number; sc: number; seed?: Partial<Seed> | null },
+): string {
+    const root = fs.mkdtempSync(path.join(tmp, 'repo-'));
+    const ids: { id: string }[] = [];
+    const mdir = path.join(root, 'tests', 'eval', 'routing-matrix');
+    fs.mkdirSync(mdir, { recursive: true });
+    fs.mkdirSync(path.join(root, 'dist'), { recursive: true });
+    for (let i = 0; i < spec.r; i += 1) {
+        ids.push({ id: `st-rule-${String(i)}` });
+        if (i < spec.rc) fs.writeFileSync(path.join(mdir, `st-rule-${String(i)}.yaml`), 'cases: []\n');
+    }
+    fs.writeFileSync(
+        path.join(root, 'dist', 'router.json'),
+        JSON.stringify({ tier_1: ids.slice(0, 1), tier_2: ids.slice(1) }),
+    );
+    for (let i = 0; i < spec.s; i += 1) {
+        const d = path.join(root, 'src', 'skills', `st-skill-${String(i)}`);
+        fs.mkdirSync(d, { recursive: true });
+        fs.writeFileSync(path.join(d, 'SKILL.md'), '---\nname: st\n---\n');
+        if (i < spec.sc) {
+            fs.mkdirSync(path.join(d, 'evals'), { recursive: true });
+            fs.writeFileSync(path.join(d, 'evals', 'triggers.json'), '[]\n');
+        }
+    }
+    if (spec.seed !== null) {
+        fs.mkdirSync(path.join(root, path.dirname(SEED_REL)), { recursive: true });
+        fs.writeFileSync(
+            path.join(root, SEED_REL),
+            JSON.stringify({ seed: spec.seed ?? { rules: spec.rc / spec.r, skills: spec.sc / spec.s } }),
+        );
+    }
+    return root;
+}
+
+export function selfTest(): number {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'crc-selftest-'));
+    const run = (root: string): number => {
+        process.env['CHECK_ROUTING_COVERAGE_ROOT'] = root;
+        try {
+            return runGateCli(REAL_REPO_ROOT, 'src/scripts/check_routing_coverage.ts', [], root);
+        } finally {
+            delete process.env['CHECK_ROUTING_COVERAGE_ROOT'];
+        }
+    };
+    const cases: SelfTestCase[] = [
+        {
+            name: 'a tree exactly at seed on both scopes is accepted',
+            expect: 'accept',
+            run: () => run(selfTestRoot(tmp, { r: 10, rc: 8, s: 10, sc: 5 })),
+        },
+        {
+            name: 'a tree ABOVE seed on both scopes is accepted',
+            expect: 'accept',
+            run: () =>
+                run(selfTestRoot(tmp, { r: 10, rc: 9, s: 10, sc: 6, seed: { rules: 0.8, skills: 0.5 } })),
+        },
+        {
+            name: 'a removed rules corpus case is rejected',
+            expect: 'reject',
+            run: () =>
+                run(selfTestRoot(tmp, { r: 10, rc: 7, s: 10, sc: 5, seed: { rules: 0.8, skills: 0.5 } })),
+        },
+        {
+            name: 'a removed skills corpus case is rejected',
+            expect: 'reject',
+            run: () =>
+                run(selfTestRoot(tmp, { r: 10, rc: 8, s: 10, sc: 4, seed: { rules: 0.8, skills: 0.5 } })),
+        },
+        {
+            name: 'ADDING routed units with no corpus cases is rejected — the count-ratchet blind spot',
+            expect: 'reject',
+            run: () =>
+                run(selfTestRoot(tmp, { r: 10, rc: 8, s: 12, sc: 5, seed: { rules: 0.8, skills: 0.5 } })),
+        },
+        {
+            name: 'a missing seed exits non-zero rather than passing every tree',
+            expect: 'reject',
+            run: () => run(selfTestRoot(tmp, { r: 10, rc: 8, s: 10, sc: 5, seed: null })),
+        },
+        {
+            name: 'an unreadable router exits non-zero rather than reporting coverage of zero',
+            expect: 'reject',
+            run: () => {
+                const root = selfTestRoot(tmp, { r: 10, rc: 8, s: 10, sc: 5 });
+                fs.writeFileSync(path.join(root, 'dist', 'router.json'), 'not json');
+                return run(root);
+            },
+        },
+    ];
+    try {
+        return runSelfTest({
+            gate: 'check_routing_coverage',
+            cases,
+            minCases: 7,
+            minRejectCases: 5,
+        });
+    } finally {
+        fs.rmSync(tmp, { recursive: true, force: true });
+    }
+}
+
+export function main(argv: string[] = process.argv.slice(2), root = REPO_ROOT): number {
+    if (argv.includes('--self-test')) return selfTest();
+    let v: Verdict;
+    try {
+        v = evaluate(root);
+        reportScanned({
+            gate: 'check_routing_coverage',
+            scanned: v.readings.reduce((n, r) => n + r.units, 0),
+            units: 'routed unit(s)',
+            roots: ['dist/router.json', 'src/skills'],
+        });
+    } catch (e) {
+        if (e instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${e.message}\n`);
+            return 2;
+        }
+        throw e;
+    }
+    v.ledger.report(argv.includes('--quiet') ? () => undefined : process.stdout.write.bind(process.stdout));
+    if (argv.includes('--json')) {
+        process.stdout.write(`${JSON.stringify(v, null, 2)}\n`);
+        return v.fallen.length > 0 ? 1 : 0;
+    }
+    for (const r of v.readings) {
+        const seed = v.seed[r.scope];
+        // Same rounding as the verdict, deliberately: see r4's own comment.
+        const mark = r4(r.ratio) < r4(seed) ? '❌' : r4(r.ratio) > r4(seed) ? '↑' : '=';
+        process.stdout.write(
+            `  ${mark} ${r.scope.padEnd(6)} ${String(r.cases).padStart(4)} / ${String(r.units).padEnd(4)} = ` +
+                `${r.ratio.toFixed(4)}  (seed ${seed.toFixed(4)})\n`,
+        );
+    }
+    if (v.fallen.length === 0) {
+        process.stdout.write('✅  routing coverage at or above seed in both scopes.\n');
+        return 0;
+    }
+    for (const s of v.fallen) {
+        const r = v.readings.find((x) => x.scope === s)!;
+        process.stderr.write(
+            `❌  ${s} coverage fell: ${r.ratio.toFixed(4)} < seed ${v.seed[s].toFixed(4)} ` +
+                `(${String(r.cases)} case(s) over ${String(r.units)} routed unit(s)).\n` +
+                '    A ratio falls two ways and the fix differs: a corpus case was removed ' +
+                '(restore it), or units were added without cases (add them). Lowering the seed ' +
+                `in ${SEED_REL} is a defect, not a fix.\n`,
+        );
+    }
+    return 1;
+}
+
+if (path.resolve(process.argv[1] ?? '') === path.resolve(HERE)) {
+    process.exit(main());
+}