@event4u/agent-config 12.1.0 → 14.0.0

package/src/scripts/capture_skill_catalogue.ts

@@ -75,19 +75,38 @@ import {
     OBSERVATION_LOG,
     analyzeSelector,
     buildHostEventRecord,
+    buildNoTruncationRecord,
     buildObservationRecord,
+    classifyHostProjection,
     formatPerHostVerdicts,
+    formatProjectionModes,
     formatReport,
     knownHostLimits,
     measureCatalogueVolume,
     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), '..', '..');
@@ -114,11 +133,259 @@ function argValue(flag: string): string | null {
     return process.argv[index + 1]!;
 }
 
+/** Every occurrence of a repeatable flag, in argv order. */
+function argValues(flag: string): string[] {
+    const out: string[] = [];
+    for (let i = 0; i < process.argv.length - 1; i += 1) {
+        if (process.argv[i] === flag) out.push(process.argv[i + 1]!);
+    }
+    return out;
+}
+
+/**
+ * `--projection-mode <scoped|legacy-all>`, validated against the closed enum.
+ *
+ * Returns `undefined` when the flag is absent — which the record schema reads
+ * as "not captured", never as `legacy-all`. An unrecognised value throws
+ * rather than falling back: a typo silently recorded as the wrong mode is the
+ * failure this whole module refuses elsewhere.
+ */
+function argProjectionMode(): ProjectionMode | undefined {
+    const raw = argValue('--projection-mode');
+    if (raw === null) return undefined;
+    if (raw === 'scoped' || raw === 'legacy-all') return raw;
+    throw new Error(`--projection-mode must be scoped or legacy-all, got: ${raw}`);
+}
+
 /** `~` expanded against the current user's home. */
 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.
@@ -151,6 +418,52 @@ function runLimitsMode(): number {
     return 0;
 }
 
+/**
+ * `--projection-modes` — the two modes side by side, as a MEASUREMENT.
+ *
+ * It reads no setting, writes no setting, and recommends no default. The
+ * scoped-projection default and its migration notice are owned by a different
+ * roadmap and were decided on 2026-08-15; this mode exists so the size of the
+ * difference is a published number instead of an intuition, and it deliberately
+ * offers no flag that would change anything.
+ *
+ * `--host-root` is repeatable, so several installed hosts are read against the
+ * 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.
+ */
+/** The package's two projection-mode counts, one walk. Shared by both modes. */
+function projectionModeCounts(): ProjectionModeCounts {
+    const stats = scoped_projection_stats(REPO, iter_skills());
+    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')) {
+        const root = expandHome(rootArg);
+        if (!fs.existsSync(root)) {
+            process.stderr.write(`❌  host root does not exist: ${root}\n`);
+            return 1;
+        }
+        const host = path.basename(root).replace(/^\./, '');
+        rows.push(classifyHostProjection(measureCatalogueVolume(host, root), counts));
+    }
+
+    if (process.argv.includes('--json')) {
+        process.stdout.write(`${JSON.stringify({ counts, hosts: rows }, null, 2)}\n`);
+        return 0;
+    }
+    process.stdout.write(`${formatProjectionModes(counts, rows)}\n`);
+    return 0;
+}
+
 /** `--volume <host-root>` — the projection half for one host, byte-accurate. */
 function runVolumeMode(rootArg: string): number {
     const root = expandHome(rootArg);
@@ -213,8 +526,32 @@ function runHostEventMode(source: string): number {
             return 1;
         }
         process.stdout.write(
-            `host: ${host}\noffered: ${volume.artefacts}\ndropped: 0 (asserted — no budget event in the stream)\n`,
+            `host: ${host}\noffered: ${volume.artefacts} (${volume.skillEntries} skills + ${volume.commandEntries} commands)\n` +
+                `dropped: 0 (asserted — no budget event in the stream)\n` +
+                'descriptions stripped: no — the host published nothing to strip.\n',
         );
+        if (process.argv.includes('--record')) {
+            const stampedAt = argValue('--observed-at');
+            if (!stampedAt) {
+                process.stderr.write('❌  --record requires --observed-at <ISO date>\n');
+                return 1;
+            }
+            const logPath = path.join(REPO, OBSERVATION_LOG);
+            fs.mkdirSync(path.dirname(logPath), { recursive: true });
+            fs.appendFileSync(
+                logPath,
+                `${JSON.stringify(
+                    buildNoTruncationRecord(
+                        host,
+                        stampedAt,
+                        volume.artefacts,
+                        volume.skillEntries,
+                        argProjectionMode(),
+                    ),
+                )}\n`,
+            );
+            process.stdout.write(`recorded → ${OBSERVATION_LOG}\n`);
+        }
         return 0;
     }
 
@@ -238,7 +575,14 @@ function runHostEventMode(source: string): number {
         }
         const logPath = path.join(REPO, OBSERVATION_LOG);
         fs.mkdirSync(path.dirname(logPath), { recursive: true });
-        const record = buildHostEventRecord(host, stampedAt, volume.artefacts, event, volume.skillEntries);
+        const record = buildHostEventRecord(
+            host,
+            stampedAt,
+            volume.artefacts,
+            event,
+            volume.skillEntries,
+            argProjectionMode(),
+        );
         fs.appendFileSync(logPath, `${JSON.stringify(record)}\n`);
         process.stdout.write(`recorded → ${OBSERVATION_LOG}\n`);
     }
@@ -246,7 +590,10 @@ 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();
 
     const volumeRoot = argValue('--volume');
     if (volumeRoot) return runVolumeMode(volumeRoot);
@@ -320,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 };