@event4u/agent-config 13.0.0 → 14.1.0

package/src/scripts/capture_skill_catalogue.ts

@@ -86,16 +86,27 @@ import {
     parseHostBudgetEvent,
     readObservationLog,
     readProjectedCatalogue,
+    resolveSkillsRoot,
     type HostProjectionRow,
     type ProjectionMode,
     type ProjectionModeCounts,
     type SelectorReport,
 } from './_lib/skill_catalogue.js';
+import {
+    cadenceStatus,
+    formatCadenceStatus,
+    formatPointableBare,
+    joinPointableBare,
+    scopeFlagDecision,
+} from './_lib/skill_catalogue_series.js';
 import { scoped_projection_stats } from './_lib/scoped_projection.js';
 import { iter_skills } from './update_counts.js';
 
-// Re-exported so the CLI module stays the one public name for this tool.
+// Re-exported so the CLI module stays the one public name for this tool —
+// both halves, so the split into a series layer is an internal seam and not a
+// second import path every consumer has to learn.
 export * from './_lib/skill_catalogue.js';
+export * from './_lib/skill_catalogue_series.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 const REPO = path.resolve(path.dirname(_HERE), '..', '..');
@@ -151,6 +162,230 @@ function expandHome(p: string): string {
     return p.startsWith('~/') ? path.join(os.homedir(), p.slice(2)) : p;
 }
 
+/**
+ * `--today <ISO>` for a deterministic run, else the machine's own date.
+ *
+ * Range-checked by round-trip, not by shape alone. `2026-13-45` matches the
+ * pattern and then parses to `NaN`, which reaches `cadenceStatus` and makes
+ * every host report `stamp unparseable (<the record's date>)` — a diagnostic
+ * blaming the corpus for an operator typo.
+ */
+function argToday(): string {
+    const explicit = argValue('--today');
+    if (explicit) {
+        const parsed = new Date(`${explicit}T00:00:00Z`);
+        if (
+            !/^\d{4}-\d{2}-\d{2}$/.test(explicit) ||
+            Number.isNaN(parsed.getTime()) ||
+            parsed.toISOString().slice(0, 10) !== explicit
+        ) {
+            throw new Error(`--today must be a real ISO date (YYYY-MM-DD), got: ${explicit}`);
+        }
+        return explicit;
+    }
+    return new Date().toISOString().slice(0, 10);
+}
+
+/**
+ * `--cadence` — is an observation due on any host, and how far is the corpus?
+ *
+ * The recurring half of the capture. It reports and prints the next command; it
+ * never records anything itself. Two reasons, both deliberate: recording is what
+ * `--host-event --record` and `--observed --record` already do, and a mode that
+ * both decides freshness AND writes a record could refresh a series with a
+ * reading nobody took.
+ *
+ * The asymmetry between the hosts is printed rather than smoothed over. The
+ * codex round is one shell pipeline and can be scheduled; the claude round needs
+ * an agent to read its own delivered context, which no scheduler can do.
+ */
+function runCadenceMode(): number {
+    const today = argToday();
+    const records = readObservationLog(path.join(REPO, OBSERVATION_LOG));
+    const rows = cadenceStatus(records, today);
+
+    if (process.argv.includes('--json')) {
+        process.stdout.write(
+            `${JSON.stringify(
+                {
+                    today,
+                    // `daysSince` is NaN when a record's stamp is unparseable, and
+                    // `JSON.stringify(NaN)` emits `null` — indistinguishable from an
+                    // absent field to a machine consumer. This module states every
+                    // other absence explicitly, so this one is stated too.
+                    hosts: rows.map((row) => ({
+                        ...row,
+                        daysSince: Number.isNaN(row.daysSince) ? null : row.daysSince,
+                        daysSinceKnown: !Number.isNaN(row.daysSince),
+                    })),
+                },
+                null,
+                2,
+            )}\n`,
+        );
+        return 0;
+    }
+
+    process.stdout.write(`${formatCadenceStatus(rows, today)}\n`);
+
+    if (rows.length === 0) {
+        // The one state in which every host is maximally overdue is the state
+        // with no host to name: `cadenceStatus` only knows hosts it has already
+        // seen. Saying so beats printing a "next round" header over nothing.
+        process.stdout.write(
+            '\nno host is known yet, so no next command can be named — the corpus has never been\n' +
+                'written to. Take a first observation on any host, then this mode has a series to keep current.\n',
+        );
+        return 0;
+    }
+
+    const due = rows.filter((row) => row.due);
+    if (due.length === 0) return 0;
+
+    // ONE walk, hoisted: `projectionModeCounts` parses the frontmatter of every
+    // skill in the tree, and the counts are a property of the package, not of
+    // the host being reported — calling it per due host walked the tree twice
+    // for a value that cannot differ, against its own docstring.
+    const counts = projectionModeCounts();
+
+    process.stdout.write('\nnext round — run what is due:\n\n');
+    for (const row of due) {
+        const scopeFlag = projectionModeFlagFor(row.host, counts);
+        // Keyed on the HOST, never on the latest record's source. Only codex is
+        // known to publish a parseable budget event, and `row.source` comes from
+        // a single headline record whose same-date tie `_supersedes` breaks on
+        // `dropped_count` — a self-report record has none, so one same-date
+        // host-event row could flip a self-report host onto the codex pipeline
+        // and record codex's truncation under another host's name.
+        if (row.host === 'codex') {
+            process.stdout.write(
+                `  # ${row.host} — deterministic, read off the host's own JSON channel\n` +
+                    `  codex exec --json --skip-git-repo-check "reply with exactly: OK" \\\n` +
+                    `    | agent-config exec capture_skill_catalogue \\\n` +
+                    `        --host-event - --host ${row.host} --host-root ~/.${row.host} \\\n` +
+                    `        ${scopeFlag.flag}--record --observed-at ${today}\n` +
+                    `${scopeFlag.note}\n`,
+            );
+            continue;
+        }
+        process.stdout.write(
+            `  # ${row.host} — self-report; only an agent reading its own context can produce it.\n` +
+                `  # Write the entries seen bare and the ones seen described, one name per line, to\n` +
+                `  #   agents/evidence/metrics/skill-catalogue/${today}-${row.host}-{bare,described}.txt\n` +
+                `  agent-config exec capture_skill_catalogue \\\n` +
+                `      --observed agents/evidence/metrics/skill-catalogue/${today}-${row.host}-bare.txt \\\n` +
+                `      --described agents/evidence/metrics/skill-catalogue/${today}-${row.host}-described.txt \\\n` +
+                `      --host ${row.host} ${scopeFlag.flag}--record --observed-at ${today}\n` +
+                `${scopeFlag.note}\n`,
+        );
+    }
+    return 0;
+}
+
+/**
+ * The `--projection-mode` flag for one host's round, MEASURED off its installed
+ * root — or omitted, with the reason, when the root carries neither mode count.
+ *
+ * Printing `--projection-mode <scoped|legacy-all>` as a placeholder invites the
+ * operator to pick one, and on an `indeterminate` root either pick is a label
+ * nobody measured. Measured 2026-08-18 on this machine: `~/.codex` holds 297
+ * skills against a scoped projection of 219 and a legacy-all of 290 — it matches
+ * neither, because it is a stale install rather than a broken one. So the honest
+ * output for that root is no flag and a stated reason, which keeps the record's
+ * absent-scope field meaning "not determinable" instead of "not asked".
+ */
+function projectionModeFlagFor(host: string, counts: ProjectionModeCounts): { flag: string; note: string } {
+    const root = expandHome(`~/.${host}`);
+    const exists = fs.existsSync(root);
+    const decision = scopeFlagDecision(
+        root,
+        exists,
+        exists ? classifyHostProjection(measureCatalogueVolume(host, root), counts) : null,
+    );
+    const wrapped = decision.reason
+        .split(/(?<=\.) (?=[A-Z])/)
+        .map((part) => `  #   ${part}`)
+        .join('\n');
+    return decision.mode === null
+        ? { flag: '', note: `  #   no --projection-mode:\n${wrapped}\n` }
+        : { flag: `--projection-mode ${decision.mode} `, note: `${wrapped}\n` };
+}
+
+/**
+ * `--pointable-bare` — the D-4 join: host truth against disk truth.
+ *
+ * Intersects the bare names of every per-entry observation with the catalogue
+ * the runtime ranker reads, and publishes how many skills the ranker can name
+ * while the model never received their description.
+ *
+ * `--catalogue-root` is honoured here, through the SAME resolver the main path
+ * uses. Two resolvers over one catalogue is how the ranker and the tool that
+ * reports on it start reading different trees — `resolveSkillsRoot`'s own
+ * docstring names that hazard — and silently ignoring the flag in one mode is
+ * exactly that split inside a single invocation.
+ */
+function runPointableBareMode(): number {
+    const explicitRoot = argValue('--catalogue-root');
+    const rankerRoot = explicitRoot ? resolveCatalogueRoot(explicitRoot) : resolveSkillsRoot(REPO);
+    if (rankerRoot === null) {
+        process.stderr.write(
+            '❌  no catalogue root resolved for the ranker — tried ' +
+                `${DEFAULT_CATALOGUE_ROOTS.join(', ')} under ${REPO}.\n` +
+                '    An empty catalogue is never a clean join: it would report 0 pointable\n' +
+                '    entries because nothing was read, not because nothing diverged.\n',
+        );
+        return 1;
+    }
+    const catalogueNames = readProjectedCatalogue(rankerRoot).map((entry) => entry.name);
+    // The guard the error text above already promised, and did not have. A
+    // present-but-empty or half-generated projection resolves fine — the
+    // resolver returns the first EXISTING directory, not the first non-empty
+    // one — and then every row scores 0 pointable off a catalogue nobody read,
+    // printing a clean D-4 verdict. That is the zero-inferred-from-silence this
+    // module's header forbids outright, and the sibling path guards it the same
+    // way.
+    if (catalogueNames.length === 0) {
+        process.stderr.write(
+            `❌  the ranker catalogue at ${rankerRoot} holds no entries.\n` +
+                '    An empty catalogue is never a clean join: every observation would score 0\n' +
+                '    pointable because nothing was read, not because nothing diverged.\n',
+        );
+        return 1;
+    }
+    const records = readObservationLog(path.join(REPO, OBSERVATION_LOG));
+    const join = joinPointableBare(records, catalogueNames);
+
+    if (process.argv.includes('--json')) {
+        process.stdout.write(
+            `${JSON.stringify(
+                {
+                    ranker_catalogue_root: path.relative(REPO, rankerRoot) || rankerRoot,
+                    ranker_catalogue_entries: catalogueNames.length,
+                    // The disk side carries the same scope discipline the host
+                    // side does: `pointableBare` grows with a stale-large root,
+                    // so which projection the join ran against is recorded
+                    // rather than left to the entry count to imply.
+                    ranker_catalogue_projection: classifyHostProjection(
+                        measureCatalogueVolume('ranker', rankerRoot),
+                        projectionModeCounts(),
+                    ).matches,
+                    skipped_non_per_entry: join.skippedNonPerEntry,
+                    skipped_malformed: join.skippedMalformed,
+                    observations: join.rows,
+                },
+                null,
+                2,
+            )}\n`,
+        );
+        return 0;
+    }
+
+    process.stdout.write(
+        `${formatPointableBare(join, path.relative(REPO, rankerRoot) || rankerRoot, catalogueNames.length)}\n`,
+    );
+    return 0;
+}
+
 /**
  * `--limits` — publish the per-host picture: what each host was measured to
  * deliver, and whether the observed hosts truncate the same way.
@@ -196,14 +431,19 @@ function runLimitsMode(): number {
  * same pair of numbers in one run. Each host is reported on its own row: no
  * host's count is ever used to say anything about another's.
  */
-function runProjectionModesMode(): number {
+/** The package's two projection-mode counts, one walk. Shared by both modes. */
+function projectionModeCounts(): ProjectionModeCounts {
     const stats = scoped_projection_stats(REPO, iter_skills());
-    const counts: ProjectionModeCounts = {
+    return {
         scoped: stats.projected,
         legacyAll: stats.total,
         prunedUnderScoped: stats.pruned,
         activePacks: stats.active_packs,
     };
+}
+
+function runProjectionModesMode(): number {
+    const counts = projectionModeCounts();
 
     const rows: HostProjectionRow[] = [];
     for (const rootArg of argValues('--host-root')) {
@@ -350,6 +590,8 @@ function runHostEventMode(source: string): number {
 }
 
 function main(): number {
+    if (process.argv.includes('--cadence')) return runCadenceMode();
+    if (process.argv.includes('--pointable-bare')) return runPointableBareMode();
     if (process.argv.includes('--limits')) return runLimitsMode();
     if (process.argv.includes('--projection-modes')) return runProjectionModesMode();
 
@@ -425,9 +667,27 @@ function main(): number {
         }
         const logPath = path.join(REPO, OBSERVATION_LOG);
         fs.mkdirSync(path.dirname(logPath), { recursive: true });
+        const projectionMode = argProjectionMode();
+        if (projectionMode === undefined) {
+            // A WARNING, not a refusal. Recording without the scope is a
+            // legitimate reading — the record type says absence is not
+            // `legacy-all` and a consumer comparing modes skips it — so
+            // rejecting it would refuse an observation to protect a
+            // comparison. But an unscoped record is silently incomparable,
+            // which is the failure this line exists to make loud.
+            process.stdout.write(
+                '\n⚠️  no --projection-mode given: this record will carry no projection scope.\n' +
+                    '    Absence is NOT `legacy-all` — a mode comparison skips a record that\n' +
+                    '    carries none, so the observation stays outside that series. Pass\n' +
+                    '    --projection-mode <scoped|legacy-all> to keep it comparable.\n',
+            );
+        }
         fs.appendFileSync(
             logPath,
-            `${JSON.stringify(buildObservationRecord(report, host, stampedAt))}\n`,
+            // The catalogue root IS the skill tree, so every projected entry is
+            // a skill: the count is file-measured, not derived from the
+            // artefact total the way a host root's would be.
+            `${JSON.stringify(buildObservationRecord(report, host, stampedAt, projected.length, projectionMode))}\n`,
         );
         process.stdout.write(`\nrecorded → ${OBSERVATION_LOG}\n`);
     }

package/src/scripts/check_evaluator_schema.ts

@@ -0,0 +1,249 @@
+#!/usr/bin/env tsx
+/**
+ * Gate — every registered evaluator emits output conforming to
+ * `evaluator-output.schema.json`, over recorded verifier fixtures.
+ *
+ * Ships in the SAME change as the schema on purpose: the estate's standing
+ * constraint is that a convention without a machine backstop is dead text, so a
+ * schema landing without its check would be exactly the failure the roadmap's
+ * Risk-Register rank-5 names.
+ *
+ * WHY FIXTURES RATHER THAN LIVE RUNS. The adapters are pure functions from a
+ * verifier's captured `{stdout, stderr, exitCode}` to the contract shape, so the
+ * mapping — the part that can be wrong — is fully exercised without re-running
+ * three verifiers CI already runs once. Running them here would double their CI
+ * cost to test code that never touches them. `--live` re-records nothing and is
+ * not offered: a fixture that drifts from its verifier is caught by that
+ * verifier's own gate changing shape, which is a review event, not a silent one.
+ *
+ * The corpus is (evaluator x fixture) pairs, and it includes deliberately RED
+ * and DEGRADED fixtures — a gate that only ever sees green output cannot tell a
+ * working mapping from one that hardcodes success.
+ *
+ * Exit codes:
+ *   0 — every pair conforms and every expectation holds
+ *   1 — one or more pairs violate the schema or their expected reading
+ *   2 — the gate could not run (fixture directory missing or empty)
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import * as os from 'node:os';
+
+import { EVALUATORS, validateEvaluatorOutput, type RawRun } from './_lib/evaluator_contract.js';
+import { GateLedger } from './_lib/gate_ledger.js';
+import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+const FIXTURE_DIR = path.join(process.cwd(), 'tests', 'fixtures', 'evaluator-output');
+
+/** What each fixture flavour must read as, so a green-only corpus cannot pass. */
+const EXPECTED: Readonly<Record<string, { pass: boolean; metric_state: string }>> = {
+    green: { pass: true, metric_state: 'present' },
+    red: { pass: false, metric_state: 'present' },
+    degraded: { pass: true, metric_state: 'unreadable' },
+};
+
+function readRun(name: string, flavour: string): RawRun | null {
+    const base = path.join(FIXTURE_DIR, `${name}.${flavour}`);
+    if (!fs.existsSync(`${base}.stdout`)) return null;
+    return {
+        stdout: fs.readFileSync(`${base}.stdout`, 'utf-8'),
+        stderr: fs.existsSync(`${base}.stderr`) ? fs.readFileSync(`${base}.stderr`, 'utf-8') : '',
+        exitCode: fs.existsSync(`${base}.exit`)
+            ? Number(fs.readFileSync(`${base}.exit`, 'utf-8').trim())
+            : 0,
+    };
+}
+
+/**
+ * `--self-test` — prove, from the shipped binary, that the rejections still fire.
+ *
+ * Each case builds a throwaway tree holding only a fixture directory and runs
+ * this gate against it with `cwd` pointing there, so the cases exercise the CLI
+ * a contributor actually invokes rather than an imported function.
+ */
+function selfTest(): number {
+    const mk = (files: Record<string, string>): string => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ces-selftest-'));
+        const dir = path.join(root, 'tests', 'fixtures', 'evaluator-output');
+        fs.mkdirSync(dir, { recursive: true });
+        for (const [rel, body] of Object.entries(files)) {
+            fs.writeFileSync(path.join(dir, rel), body, 'utf-8');
+        }
+        return root;
+    };
+    const run = (root: string): number =>
+        runGateCli(REPO_ROOT, 'src/scripts/check_evaluator_schema.ts', ['--quiet'], root);
+
+    const GREEN_FM = '\n== Frontmatter schema: 437 artefacts, 0 failing, 0 with warnings ==\n';
+
+    return runSelfTest({
+        gate: 'check_evaluator_schema',
+        minCases: 4,
+        minRejectCases: 3,
+        cases: [
+            {
+                name: 'a conformant green fixture passes',
+                expect: 'accept',
+                run: () =>
+                    run(
+                        mk({
+                            'validate_frontmatter.green.stdout': GREEN_FM,
+                            'validate_frontmatter.green.exit': '0\n',
+                        }),
+                    ),
+            },
+            {
+                name: 'a green fixture with no parseable count is rejected — unreadable is not present',
+                expect: 'reject',
+                run: () =>
+                    run(
+                        mk({
+                            'validate_frontmatter.green.stdout': 'done, nothing to report\n',
+                            'validate_frontmatter.green.exit': '0\n',
+                        }),
+                    ),
+            },
+            {
+                name: 'a red fixture that exits 0 is rejected — pass must follow the exit code',
+                expect: 'reject',
+                run: () =>
+                    run(
+                        mk({
+                            'validate_frontmatter.red.stdout':
+                                '\n== Frontmatter schema: 437 artefacts, 3 failing, 0 with warnings ==\n',
+                            'validate_frontmatter.red.exit': '0\n',
+                        }),
+                    ),
+            },
+            {
+                name: 'an empty fixture directory is rejected — a gate that scanned nothing has verified nothing',
+                expect: 'reject',
+                run: () => run(mk({})),
+            },
+        ],
+    });
+}
+
+function main(argv?: readonly string[]): number {
+    const args = argv ?? process.argv.slice(2);
+    if (args.includes('--self-test')) return selfTest();
+    const quiet = args.includes('--quiet');
+    const problems: string[] = [];
+    let scanned = 0;
+
+    if (!fs.existsSync(FIXTURE_DIR)) {
+        process.stderr.write(
+            `❌  check_evaluator_schema: fixture directory absent (${FIXTURE_DIR}) — the gate cannot run\n`,
+        );
+        return 2;
+    }
+
+    // Every (evaluator x flavour) pair is PLANNED before the loop, so a pair
+    // that falls through without a terminal outcome is a finalize() throw rather
+    // than a silently smaller denominator. A missing fixture is a real skip with
+    // a named reason, never an invisible `continue`.
+    const ledger = new GateLedger('check_evaluator_schema');
+    const flavours = Object.keys(EXPECTED);
+    ledger.plan(EVALUATORS.flatMap((a) => flavours.map((f) => `${a.name}.${f}`)));
+
+    for (const adapter of EVALUATORS) {
+        for (const flavour of flavours) {
+            const pair = `${adapter.name}.${flavour}`;
+            const raw = readRun(adapter.name, flavour);
+            if (raw === null) {
+                ledger.skip(pair, 'no_applicable_files');
+                continue;
+            }
+            scanned += 1;
+
+            let out;
+            try {
+                out = adapter.parse(raw);
+            } catch (exc) {
+                problems.push(`${pair}: adapter threw — ${String(exc)}`);
+                ledger.fail(pair, 'adapter threw');
+                continue;
+            }
+            const before = problems.length;
+
+            for (const v of validateEvaluatorOutput(out)) {
+                problems.push(`${pair}: schema — ${v}`);
+            }
+
+            const want = EXPECTED[flavour]!;
+            if (out.pass !== want.pass) {
+                problems.push(`${pair}: pass is ${out.pass}, fixture asserts ${want.pass}`);
+            }
+            if (out.metric_state !== want.metric_state) {
+                problems.push(
+                    `${pair}: metric_state is ${String(out.metric_state)}, fixture asserts ${want.metric_state}`,
+                );
+            }
+            // The higher-is-better invariant is the one a consumer relies on
+            // without checking, so it is asserted rather than documented.
+            if (out.metric_state === 'present' && out.direction === 'minimize') {
+                if (out.score !== -(out.metric ?? NaN)) {
+                    problems.push(
+                        `${pair}: score ${out.score} is not the negation of metric ${String(out.metric)}`,
+                    );
+                }
+            }
+
+            if (problems.length > before) {
+                ledger.fail(pair, `${String(problems.length - before)} violation(s)`);
+            } else {
+                ledger.complete(pair);
+            }
+        }
+    }
+
+    ledger.finalize();
+
+    if (scanned === 0) {
+        process.stderr.write(
+            `❌  check_evaluator_schema: 0 evaluator/fixture pairs found — a gate that scanned nothing has not verified anything\n`,
+        );
+        return 2;
+    }
+
+    process.stderr.write(`scanned: ${scanned}\n`);
+
+    if (problems.length > 0) {
+        process.stdout.write(
+            `❌  check_evaluator_schema: ${problems.length} violation(s) across ${scanned} pair(s)\n\n`,
+        );
+        for (const p of problems) process.stdout.write(`  ${p}\n`);
+        process.stdout.write(`\nContract: docs/contracts/evaluator-output.md\n`);
+        return 1;
+    }
+
+    if (!quiet) {
+        process.stdout.write(
+            `✅  check_evaluator_schema: ${scanned} evaluator/fixture pair(s) conform, ${EVALUATORS.length} evaluator(s) registered.\n`,
+        );
+    }
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    if (import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) return true;
+    try {
+        return (
+            fs.realpathSync(fileURLToPath(import.meta.url)) ===
+            fs.realpathSync(path.resolve(process.argv[1]))
+        );
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    process.exit(main());
+}
+
+export { main };

package/src/scripts/check_gate_coverage.ts

@@ -50,6 +50,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import * as yaml from 'js-yaml';
 import { checkRatchet } from './_lib/gate_baseline.js';
+import { GateLedger, type GateSkipReason } from './_lib/gate_ledger.js';
 import { runCountedProbe } from './_lib/counted_probe.js';
 import { listGateScripts } from './_lib/gate_population.js';
 import { describeOutcome, namesEstateInvalidatingError } from './_lib/gate_result.js';
@@ -187,6 +188,59 @@ export function parse_scanned(output: string): number | null {
   return m === null ? null : Number(m[1]);
 }
 
+/**
+ * Map a gate verdict onto its ledger outcome.
+ *
+ * Extracted and exported so the mapping can be PINNED — it was inline, and the
+ * completion review's three sharpest findings were all mis-mappings that a
+ * discrimination test would have caught in one line each.
+ *
+ * The split is INSPECTED vs NOT INSPECTED, never pass vs fail. `fail` counts
+ * into the ledger's `scanned=` (`report()` sets `checked = completed + failed`),
+ * so a target that could not be READ must never land there — that inflates the
+ * exact number the library exists to make trustworthy. This file's own comment
+ * already says a gate that could not MEASURE "is not a gate that found
+ * violations, and it is not a gate that passed either"; this agrees with it.
+ */
+export function ledgerOutcomeFor(
+  verdict: GateResult['verdict'],
+): 'complete' | 'fail' | GateSkipReason {
+  switch (verdict) {
+    case 'pending':
+      return 'disabled_by_configuration';
+    case 'unavailable':
+      // NOT `missing_credentials`. The only manifest row carrying
+      // `unavailable_exit` is unavailable for an unbuilt `site/dist`, and the
+      // skip sentence IS the audit surface — naming a credential would send the
+      // reader hunting an unset token instead of running the build.
+      return 'no_applicable_files';
+    case 'crashed':
+      // NOT `dead_scan_root` — a gate that threw has no dead root, and the skip
+      // sentence would send the reader to check a scan path that is fine. The
+      // vocabulary was extended rather than approximated, same reasoning as the
+      // `unavailable` case above.
+      return 'check_did_not_run';
+    case 'estate_invalid':
+      // Nothing was read here either. `crashed` still reds the build through
+      // this gate's own filter and `estate_invalid` deliberately does not, but
+      // neither belongs in the inspected count.
+      return 'dead_scan_root';
+    case 'silent':
+    case 'below_floor':
+      return 'fail';
+    case 'ok':
+      return 'complete';
+    default: {
+      // Exhaustiveness guard. A `Verdict` member added later must be classified
+      // deliberately: without this, a new member would silently count as
+      // INSPECTED and both the switch and its test would stay green —
+      // re-creating the over-report this function was extracted to pin.
+      const unhandled: never = verdict;
+      throw new Error(`ledgerOutcomeFor: unhandled verdict ${String(unhandled)}`);
+    }
+  }
+}
+
 /** Classify one gate's run against its declared floor. Pure — testable without
  * spawning anything. */
 export function classify(
@@ -323,6 +377,31 @@ export function main(argv: readonly string[]): number {
     return 0;
   }
 
+  // Per-target accounting over the manifest rows. The gate that audits gate
+  // coverage was itself unaudited.
+  //
+  // Stated precisely, because the obvious justification overstates it: this gate
+  // ALREADY prints counted `pending N · unavailable N` warnings, so those two
+  // classes were not invisible. What the ledger adds is that they are expressed
+  // in the estate-wide vocabulary every other adopter uses, so a reader
+  // comparing gates does not have to learn this one's private status names — and
+  // that `crashed` and `estate_invalid`, which had no counted line at all, stop
+  // being counted as inspected.
+  //
+  // Note the two numbers this produces in one run: the ledger's `scanned=` (what
+  // was inspected) and the contract line `scanned:` (manifest rows read). They
+  // differ by the skips and that is correct, but only the latter is what
+  // `SCANNED_RE` parses.
+  const ledger = new GateLedger('check_gate_coverage');
+  // Deduplicated on purpose. `load_manifest` does not check id uniqueness, and a
+  // copy-pasted row with a forgotten rename would otherwise make `plan()` throw
+  // an uncaught LedgerUsageError — surfacing a manifest mistake as a stack trace
+  // and Node's exit 1, which this file's own contract reads as "a gate is blind,
+  // collapsed, or silent" rather than as the exit 2 a malformed manifest earns.
+  // The duplicate still runs twice and still prints twice; only the accounting
+  // refuses to double-count it.
+  ledger.plan([...new Set(specs.map((s) => s.id))]);
+
   const results = specs.map((s) => {
     if (spec_is_pending(s)) {
       const { scanned, crashed } = probe_pending(s);
@@ -332,6 +411,20 @@ export function main(argv: readonly string[]): number {
     return classify(s, scanned, crashed, exit_code, output);
   });
 
+  // `recorded` pairs with the deduplicated plan above: a duplicated manifest id
+  // must be accounted once, and recording it twice would raise the same
+  // LedgerUsageError the dedupe exists to avoid.
+  const recorded = new Set<string>();
+  for (const r of results) {
+    if (recorded.has(r.id)) continue;
+    recorded.add(r.id);
+    const outcome = ledgerOutcomeFor(r.verdict);
+    if (outcome === 'complete') ledger.complete(r.id);
+    else if (outcome === 'fail') ledger.fail(r.id, r.message);
+    else ledger.skip(r.id, outcome);
+  }
+  ledger.report();
+
   if (wantJson) {
     process.stdout.write(`${JSON.stringify({ generated_by: 'check_gate_coverage', results }, null, 2)}\n`);
   } else {