@event4u/agent-config 14.12.0 → 14.13.0

package/src/scripts/lint_memory_twin_parity.ts

@@ -0,0 +1,335 @@
+#!/usr/bin/env tsx
+/**
+ * Memory-twin parity — the copies may not drift apart again.
+ *
+ * `road-to-memory-twin-reconciliation` Phase 3. Seven scripts exist twice, once
+ * under `src/scripts/` and once under `src/agent-src/templates/scripts/`, and
+ * `package.json:files[]` ships BOTH. Until this gate there was no sync, no drift
+ * check and no parity check between them — so they diverged in both directions
+ * and the divergence was found by a redundancy audit rather than by CI.
+ *
+ * ── What it compares ────────────────────────────────────────────────────────
+ * NON-COMMENT lines only. Block comments, line comments and blank lines are
+ * stripped from both sides before diffing, because the docstring differences
+ * between the copies are known-correct: the template's header explains what a
+ * consumer installed, the dev copy's explains this repository's own tooling.
+ * A gate comparing whole diffs would fire on every unrelated PR — which is
+ * exactly the risk this roadmap's own register names at rank 4.
+ *
+ * ── Two modes, and why not one ──────────────────────────────────────────────
+ * `exact` — the non-comment diff must be EMPTY. This is the real check, and a
+ * twin is put here whenever it can be driven to zero.
+ *
+ * `bounded` — a recorded ceiling on non-comment changed lines, shrink-only. It
+ * exists for the twins that CANNOT reach zero, and the reason is structural
+ * rather than a preference: the installed consumer tree has no `scripts/_lib/`,
+ * so a template script may import node built-ins, `yaml` and its own installed
+ * siblings — nothing else. Every `keep-duplicated` verdict in the config names
+ * which non-installable import forces it.
+ *
+ * **What `bounded` does NOT claim**, stated because a ceiling reads stronger
+ * than it is: it catches GROWTH, not substitution. Replacing one 18-line
+ * divergence with a different 18-line divergence passes. That is the honest
+ * limit of a count, and it is why every twin that can be `exact` is `exact`.
+ *
+ * Exit codes: 0 within verdicts · 1 divergence beyond them · 2 config / IO error.
+ *
+ * Usage:
+ *     ./scripts-run src/scripts/lint_memory_twin_parity
+ *     ./scripts-run src/scripts/lint_memory_twin_parity --format json
+ *     ./scripts-run src/scripts/lint_memory_twin_parity --root <fixture>
+ *     ./scripts-run src/scripts/lint_memory_twin_parity --self-test
+ */
+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, pathToFileURL } from 'node:url';
+
+import { parse as parseYaml } from 'yaml';
+
+import { GateLedger } from './_lib/gate_ledger.js';
+import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
+import { DeadScopeError, assertScanned } from './_lib/scan_scope.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+export const CONFIG_REL = 'src/config/memory-twin-verdicts.yml';
+
+export interface TwinVerdict {
+    file: string;
+    mode: 'exact' | 'bounded';
+    max_changed_lines?: number;
+    verdict: string;
+    reason: string;
+}
+
+export interface TwinConfig {
+    dev_root: string;
+    template_root: string;
+    twins: TwinVerdict[];
+}
+
+export function loadConfig(repoRoot: string): TwinConfig {
+    const raw = fs.readFileSync(path.join(repoRoot, CONFIG_REL), 'utf8');
+    const doc = parseYaml(raw) as Partial<TwinConfig>;
+    if (typeof doc.dev_root !== 'string' || typeof doc.template_root !== 'string' || !Array.isArray(doc.twins)) {
+        throw new Error(`${CONFIG_REL}: dev_root, template_root and twins are all required`);
+    }
+    return { dev_root: doc.dev_root, template_root: doc.template_root, twins: doc.twins };
+}
+
+/**
+ * Strip comments and blank lines.
+ *
+ * Deliberately textual rather than a parse: the gate must not need a TypeScript
+ * compiler to answer "did these two files diverge", and a stripper that is
+ * slightly conservative (a `*` continuation line inside a string would be
+ * dropped) errs toward reporting FEWER differences, which cannot manufacture a
+ * failure. It is the same shape the roadmap's own Phase 1 measurements used.
+ */
+export function stripComments(src: string): string[] {
+    const noBlocks = src.replace(/\/\*[\s\S]*?\*\//g, '');
+    const out: string[] = [];
+    for (const line of noBlocks.split('\n')) {
+        const t = line.trim();
+        if (t === '' || t.startsWith('//') || t.startsWith('*')) continue;
+        out.push(line.replace(/\s+$/, ''));
+    }
+    return out;
+}
+
+/**
+ * Count changed lines between two stripped files.
+ *
+ * A multiset difference, not an LCS diff: a line present N times on one side and
+ * M on the other contributes |N-M|. That makes the number invariant to
+ * reordering, which is what we want — moving a function is not a divergence in
+ * behaviour, and a real divergence changes the line CONTENT.
+ */
+export function changedLineCount(devLines: readonly string[], tplLines: readonly string[]): number {
+    const count = (ls: readonly string[]): Map<string, number> => {
+        const m = new Map<string, number>();
+        for (const l of ls) m.set(l, (m.get(l) ?? 0) + 1);
+        return m;
+    };
+    const a = count(devLines);
+    const b = count(tplLines);
+    let delta = 0;
+    for (const k of new Set([...a.keys(), ...b.keys()])) {
+        delta += Math.abs((a.get(k) ?? 0) - (b.get(k) ?? 0));
+    }
+    return delta;
+}
+
+export interface Finding {
+    file: string;
+    measured: number;
+    allowed: number | 'exact';
+    detail: string;
+}
+
+export interface Report {
+    findings: Finding[];
+    scanned: number;
+    measurements: { file: string; measured: number; mode: string }[];
+}
+
+export function evaluate(repoRoot: string, ledger?: GateLedger): Report {
+    const cfg = loadConfig(repoRoot);
+    const findings: Finding[] = [];
+    const measurements: Report['measurements'] = [];
+    ledger?.plan(cfg.twins.map((t) => t.file));
+
+    for (const twin of cfg.twins) {
+        const dev = path.join(repoRoot, cfg.dev_root, twin.file);
+        const tpl = path.join(repoRoot, cfg.template_root, twin.file);
+        if (!fs.existsSync(dev) || !fs.existsSync(tpl)) {
+            // A declared twin that no longer exists on both sides is a CONFIG
+            // defect, not a silent skip: the verdict is now describing nothing.
+            findings.push({
+                file: twin.file,
+                measured: -1,
+                allowed: twin.mode === 'exact' ? 'exact' : (twin.max_changed_lines ?? 0),
+                detail: `declared twin is missing on one side (dev=${fs.existsSync(dev)}, template=${fs.existsSync(tpl)}) — the verdict describes nothing`,
+            });
+            ledger?.fail(twin.file, 'declared twin missing on one side');
+            continue;
+        }
+        const measured = changedLineCount(
+            stripComments(fs.readFileSync(dev, 'utf8')),
+            stripComments(fs.readFileSync(tpl, 'utf8')),
+        );
+        measurements.push({ file: twin.file, measured, mode: twin.mode });
+
+        if (twin.mode === 'exact') {
+            if (measured !== 0) {
+                findings.push({
+                    file: twin.file,
+                    measured,
+                    allowed: 'exact',
+                    detail: `declared EXACT parity but the copies differ by ${measured} non-comment line(s)`,
+                });
+                ledger?.fail(twin.file, `${measured} line(s) against exact parity`);
+            } else {
+                ledger?.complete(twin.file);
+            }
+            continue;
+        }
+        const cap = twin.max_changed_lines ?? 0;
+        if (measured > cap) {
+            findings.push({
+                file: twin.file,
+                measured,
+                allowed: cap,
+                detail:
+                    `${measured} non-comment changed line(s) against a recorded ceiling of ${cap} — ` +
+                    `${measured - cap} new. The ceiling is shrink-only: reconcile the divergence, or ` +
+                    `record a verdict for it in ${CONFIG_REL}. Raising the number is a defect, not a fix.`,
+            });
+            ledger?.fail(twin.file, `${measured} > ${cap}`);
+        } else {
+            ledger?.complete(twin.file);
+        }
+    }
+    return { findings, scanned: cfg.twins.length, measurements };
+}
+
+export function selfTest(): number {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'twin-selftest-'));
+    const build = (name: string, devBody: string, tplBody: string, cfgTwin: string): string => {
+        const root = path.join(tmp, name);
+        fs.mkdirSync(path.join(root, 'src', 'scripts'), { recursive: true });
+        fs.mkdirSync(path.join(root, 'src', 'agent-src', 'templates', 'scripts'), { recursive: true });
+        fs.mkdirSync(path.join(root, 'src', 'config'), { recursive: true });
+        fs.writeFileSync(path.join(root, 'src', 'scripts', 'twin.ts'), devBody, 'utf8');
+        fs.writeFileSync(path.join(root, 'src', 'agent-src', 'templates', 'scripts', 'twin.ts'), tplBody, 'utf8');
+        fs.writeFileSync(
+            path.join(root, 'src', 'config', 'memory-twin-verdicts.yml'),
+            `schema_version: memory-twin-verdicts-v1\ndev_root: src/scripts\ntemplate_root: src/agent-src/templates/scripts\ntwins:\n${cfgTwin}\n`,
+            'utf8',
+        );
+        return root;
+    };
+    const exactTwin = "  - file: twin.ts\n    mode: exact\n    verdict: dev-side-correct\n    reason: self-test";
+    const run = (root: string): number =>
+        runGateCli(REPO_ROOT, 'src/scripts/lint_memory_twin_parity.ts', ['--root', root, '--quiet'], REPO_ROOT);
+
+    try {
+        return runSelfTest({
+            gate: 'lint_memory_twin_parity',
+            minCases: 4,
+            minRejectCases: 2,
+            cases: [
+                {
+                    name: 'identical copies pass',
+                    expect: 'accept',
+                    run: () => run(build('same', 'const a = 1;\n', 'const a = 1;\n', exactTwin)),
+                },
+                {
+                    // The verify clause's green half: a comment-only plant must NOT red.
+                    name: 'a comment-only divergence passes',
+                    expect: 'accept',
+                    run: () =>
+                        run(build('comment', 'const a = 1;\n', '// template-only note\nconst a = 1;\n', exactTwin)),
+                },
+                {
+                    // The verify clause's red half: one behavioural line must red.
+                    name: 'a one-line behavioural divergence is rejected',
+                    expect: 'reject',
+                    run: () => run(build('drift', 'const a = 1;\n', 'const a = 2;\n', exactTwin)),
+                },
+                {
+                    name: 'a declared twin missing on one side is rejected',
+                    expect: 'reject',
+                    run: () => {
+                        const root = build('missing', 'const a = 1;\n', 'const a = 1;\n', exactTwin);
+                        fs.rmSync(path.join(root, 'src', 'agent-src', 'templates', 'scripts', 'twin.ts'));
+                        return run(root);
+                    },
+                },
+                {
+                    name: 'a bounded twin at its ceiling passes and one line over is rejected',
+                    expect: 'reject',
+                    run: () =>
+                        run(
+                            build(
+                                'bounded',
+                                'const a = 1;\nconst b = 2;\n',
+                                'const a = 9;\nconst b = 8;\n',
+                                '  - file: twin.ts\n    mode: bounded\n    max_changed_lines: 2\n    verdict: keep-duplicated\n    reason: self-test',
+                            ),
+                        ),
+                },
+            ],
+        });
+    } finally {
+        fs.rmSync(tmp, { recursive: true, force: true });
+    }
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    if (argv.includes('-h') || argv.includes('--help')) {
+        process.stdout.write('usage: lint_memory_twin_parity [--format json] [--root DIR] [--quiet] [--self-test]\n');
+        return 0;
+    }
+    if (argv.includes('--self-test')) return selfTest();
+
+    const quiet = argv.includes('--quiet');
+    const asJson = argv.includes('--format') && argv[argv.indexOf('--format') + 1] === 'json';
+    const rootIdx = argv.indexOf('--root');
+    const root = rootIdx !== -1 && rootIdx + 1 < argv.length ? path.resolve(argv[rootIdx + 1] as string) : REPO_ROOT;
+    const isFixture = root !== REPO_ROOT;
+
+    let report: Report;
+    const ledger = isFixture ? undefined : new GateLedger('lint_memory_twin_parity');
+    try {
+        report = evaluate(root, ledger);
+    } catch (e) {
+        process.stderr.write(`❌  lint_memory_twin_parity: ${e instanceof Error ? e.message : String(e)}\n`);
+        return 2;
+    }
+
+    try {
+        assertScanned({
+            gate: 'lint_memory_twin_parity',
+            scanned: report.scanned,
+            units: 'declared twin(s)',
+            roots: [CONFIG_REL],
+        });
+    } catch (e) {
+        if (e instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${e.message}\n`);
+            return 2;
+        }
+        throw e;
+    }
+
+    if (asJson) {
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    }
+    ledger?.report(quiet ? () => undefined : undefined);
+    process.stdout.write(`scanned: ${report.scanned}\n`);
+
+    if (report.findings.length > 0) {
+        for (const f of report.findings) {
+            process.stderr.write(`  🔴 ${f.file}: ${f.detail}\n`);
+        }
+        process.stderr.write(`❌  lint_memory_twin_parity: ${report.findings.length} twin(s) diverged beyond their verdict.\n`);
+        return 1;
+    }
+    if (!quiet) {
+        for (const m of report.measurements) {
+            process.stdout.write(`  · ${m.file.padEnd(26)} ${String(m.measured).padStart(4)} line(s)  [${m.mode}]\n`);
+        }
+        process.stdout.write(`✅  lint_memory_twin_parity: ${report.scanned} twin(s) within their recorded verdicts.\n`);
+    }
+    return 0;
+}
+
+/* c8 ignore start */
+if (process.argv[1] !== undefined && pathToFileURL(path.resolve(process.argv[1])).href === pathToFileURL(_HERE).href) {
+    process.exit(main());
+}
+/* c8 ignore stop */

package/src/scripts/lint_metric_consumers.ts

@@ -0,0 +1,355 @@
+/**
+ * lint_metric_consumers — a metric with no consumer does not land.
+ *
+ * `road-to-experience-loop-broadening` step 0.3, whose rule is quoted from the
+ * roadmap verbatim: *"A metric with no consumer is telemetry decoration and
+ * should not land."* Every entry in `src/config/metric-registry.yml` declares
+ * three things, and this gate refuses one that does not:
+ *
+ * - `consumer` — who reads it;
+ * - `decision` — what it changes;
+ * - `absent` — what fails without it.
+ *
+ * ## Why the third field, when the first two look sufficient
+ *
+ * Because the first two are answerable for a metric nobody needs. "The report
+ * reads it" and "it informs the roadmap" are both true of a number whose
+ * deletion would change nothing, and that is the number this gate exists to
+ * catch. `absent` is the falsifiable one: if the honest answer is *nothing
+ * fails*, the entry cannot be written and the metric should not land.
+ *
+ * The tree's own worked example is the 0.27 % dispatch capture rate — a figure
+ * that existed for months before anyone could say what decision it fed.
+ *
+ * ## What this gate does NOT claim
+ *
+ * It checks SHAPE, not truth. It refuses a missing, empty, or boilerplate
+ * field; it cannot tell a real consumer from a plausible sentence, because that
+ * is a review judgement and no parser has it. The honest statement is that this
+ * makes the OMISSION impossible, not the answer true — and it is written here
+ * rather than left for someone to discover by trusting the gate further than it
+ * goes.
+ *
+ * Exit codes: 0 clean · 1 finding · 2 usage error.
+ *
+ * A CONFIG error — a missing, unparseable or `metrics:`-less registry — exits
+ * **1**, not 2, and the docstring said 2 (R2 finding 6). 1 is right: a registry
+ * the gate cannot read is a finding about the tree, which is what this gate
+ * reports; 2 is reserved for being invoked wrongly. The prose is corrected
+ * rather than the code, because changing the exit code would change what a
+ * caller distinguishes.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { parse as parseYaml } from 'yaml';
+
+import { GateLedger } from './_lib/gate_ledger.js';
+import { runGateCli, runSelfTest, type SelfTestCase } from './_lib/gate_self_test.js';
+import { reportScanned } from './_lib/scan_scope.js';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(HERE, '..', '..');
+const REGISTRY_REL = path.join('src', 'config', 'metric-registry.yml');
+const SELF_REL = path.join('src', 'scripts', 'lint_metric_consumers.ts');
+
+/** The three fields that make a metric landable, and the reason each exists. */
+export const REQUIRED_FIELDS = ['consumer', 'decision', 'absent'] as const;
+export type RequiredField = (typeof REQUIRED_FIELDS)[number];
+
+/** Below this a field is a placeholder rather than an answer. */
+export const MIN_FIELD_CHARS = 20;
+
+/**
+ * Phrases that pass a length check and answer nothing.
+ *
+ * Deliberately short and deliberately literal. A long list would turn this into
+ * a vocabulary filter, which is not what the gate is for — these are the four
+ * shapes that showed up when the registry was seeded, each of which is a way of
+ * writing "I do not know" at sufficient length.
+ */
+export const BOILERPLATE = [
+    'tbd',
+    'todo',
+    'n/a',
+    'not applicable',
+    'to be determined',
+    'unknown',
+    'nothing',
+    'see above',
+] as const;
+
+export interface MetricEntry {
+    readonly id?: unknown;
+    readonly producer?: unknown;
+    readonly consumer?: unknown;
+    readonly decision?: unknown;
+    readonly absent?: unknown;
+}
+
+export interface Finding {
+    readonly id: string;
+    readonly field: string;
+    readonly reason: string;
+}
+
+function normalise(value: unknown): string {
+    return typeof value === 'string' ? value.trim().replace(/\s+/g, ' ') : '';
+}
+
+/** Judge one entry. Pure, so the self-test can drive it with literals. */
+export function findingsFor(entry: MetricEntry, index: number): Finding[] {
+    const out: Finding[] = [];
+    const id = normalise(entry.id) === '' ? `#${String(index + 1)} (no id)` : normalise(entry.id);
+
+    if (normalise(entry.id) === '') {
+        out.push({ id, field: 'id', reason: 'missing — an unnamed metric cannot be cited' });
+    }
+    if (normalise(entry.producer) === '') {
+        out.push({
+            id,
+            field: 'producer',
+            reason: 'missing — without it a reader cannot check the other three against anything',
+        });
+    }
+    for (const field of REQUIRED_FIELDS) {
+        const value = normalise(entry[field]);
+        if (value === '') {
+            out.push({ id, field, reason: 'missing or empty' });
+            continue;
+        }
+        // Matched at a WORD BOUNDARY, not on an exact token or a token plus a
+        // space (R2 finding 1). `TBD:` and `TODO:` are the natural writing
+        // forms of exactly the placeholder class this refuses, and both were
+        // accepted — the filter caught only the one spelling nobody uses.
+        const lower = value.toLowerCase();
+        if (BOILERPLATE.some((b) => lower === b || new RegExp(`^${b}\\b`).test(lower))) {
+            out.push({ id, field, reason: `boilerplate ("${value.slice(0, 40)}") — a placeholder, not an answer` });
+            continue;
+        }
+        if (value.length < MIN_FIELD_CHARS) {
+            out.push({
+                id,
+                field,
+                reason:
+                    `${String(value.length)} chars, below the ${String(MIN_FIELD_CHARS)}-char floor — `
+                    + 'too short to name a consumer, a decision or a consequence',
+            });
+        }
+    }
+    return out;
+}
+
+export interface RegistryRead {
+    readonly entries: readonly MetricEntry[];
+    readonly error: string | null;
+}
+
+export function readRegistry(root: string): RegistryRead {
+    const target = path.join(root, REGISTRY_REL);
+    let raw: string;
+    try {
+        raw = fs.readFileSync(target, 'utf8');
+    } catch {
+        return { entries: [], error: `${REGISTRY_REL} is missing` };
+    }
+    let parsed: unknown;
+    try {
+        parsed = parseYaml(raw);
+    } catch (err) {
+        return { entries: [], error: `${REGISTRY_REL} does not parse: ${(err as Error).message}` };
+    }
+    if (parsed === null || typeof parsed !== 'object') {
+        return { entries: [], error: `${REGISTRY_REL} is not a mapping` };
+    }
+    const metrics = (parsed as { metrics?: unknown }).metrics;
+    if (!Array.isArray(metrics)) {
+        return { entries: [], error: `${REGISTRY_REL} has no \`metrics:\` list` };
+    }
+    return { entries: metrics as MetricEntry[], error: null };
+}
+
+/* -------------------------------------------------------------------------- */
+/* Self-test                                                                   */
+/* -------------------------------------------------------------------------- */
+
+function selfTest(): number {
+    const fixture = (yaml: string): number => {
+        const dir = fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()), 'metric-reg-'));
+        try {
+            const abs = path.join(dir, REGISTRY_REL);
+            fs.mkdirSync(path.dirname(abs), { recursive: true });
+            fs.writeFileSync(abs, yaml);
+            // No `git init` here (R2 finding 7): this gate reads one YAML file
+            // and asks git nothing, so seeding a repo was seven subprocess
+            // spawns buying nothing.
+            return runGateCli(REPO_ROOT, SELF_REL, ['--root', dir], dir);
+        } finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    };
+
+    const complete = `
+metrics:
+  - id: a-real-metric
+    producer: src/scripts/some_gate.ts
+    consumer: the ratchet in check_some_gate, and the maintainer reading its expiry
+    decision: whether a change that raises the count may merge at all
+    absent: the count rises unnoticed and the debt grows with nothing reporting it
+`;
+
+    const cases: SelfTestCase[] = [
+        {
+            name: 'a complete entry is accepted',
+            expect: 'accept',
+            run: () => fixture(complete),
+        },
+        {
+            name: 'a metric with NO consumer is refused — the rule the gate exists for',
+            expect: 'reject',
+            run: () =>
+                fixture(complete.replace(/    consumer: .*\n/, '')),
+        },
+        {
+            name: 'a metric with no `decision` is refused',
+            expect: 'reject',
+            run: () => fixture(complete.replace(/    decision: .*\n/, '')),
+        },
+        {
+            name: 'a metric with no `absent` is refused — the falsifiable field',
+            expect: 'reject',
+            run: () => fixture(complete.replace(/    absent: .*\n/, '')),
+        },
+        {
+            name: 'a BOILERPLATE consumer is refused, not merely a missing one',
+            expect: 'reject',
+            run: () => fixture(complete.replace(/    consumer: .*\n/, '    consumer: TBD\n')),
+        },
+        {
+            // The value must be short AND not boilerplate, or the boilerplate
+            // branch `continue`s past it and MIN_FIELD_CHARS gets no coverage
+            // at all — which is what happened with `nothing much` (R2 finding
+            // 2), while the gate-coverage row and the roadmap's verify clause
+            // both lean on this self-test as the discrimination proof.
+            name: 'a too-short field is refused, on the LENGTH floor rather than the boilerplate list',
+            expect: 'reject',
+            run: () => fixture(complete.replace(/    absent: .*\n/, '    absent: it breaks\n')),
+        },
+        {
+            name: 'an EMPTY registry is refused — a gate that scans nothing exits green',
+            expect: 'reject',
+            run: () => fixture('metrics: []\n'),
+        },
+    ];
+
+    return runSelfTest({
+        gate: 'lint_metric_consumers',
+        cases,
+        minCases: 7,
+        minRejectCases: 5,
+    });
+}
+
+/* -------------------------------------------------------------------------- */
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    if (argv.includes('--self-test')) return selfTest();
+
+    const rootFlag = argv.indexOf('--root');
+    if (rootFlag >= 0 && (argv[rootFlag + 1] === undefined || argv[rootFlag + 1]?.startsWith('--'))) {
+        process.stderr.write('lint_metric_consumers: --root needs a directory\n');
+        return 2;
+    }
+    const root = rootFlag >= 0 ? (argv[rootFlag + 1] as string) : REPO_ROOT;
+    const quiet = argv.includes('--quiet');
+
+    const read = readRegistry(root);
+    if (read.error !== null) {
+        process.stderr.write(`❌  lint_metric_consumers: ${read.error}\n`);
+        return 1;
+    }
+
+    // Publishes AND asserts in one call. No `allowEmpty` reason: an empty
+    // registry is not a clean bill of health here, it is a gate reading nothing
+    // — and this gate's whole subject is numbers that exist without a purpose.
+    try {
+        reportScanned({
+            gate: 'lint_metric_consumers',
+            scanned: read.entries.length,
+            units: 'metric(s)',
+            roots: [REGISTRY_REL],
+        });
+    } catch (err) {
+        process.stderr.write(`❌  ${(err as Error).message}\n`);
+        return 1;
+    }
+
+    // Per-target accounting (R2 finding 4). A NEW gate adopts a ledger or takes
+    // an exemption; this one has a real target population — the registry's
+    // entries — so there is nothing to exempt. The plan is built from the index
+    // rather than from the id, because an entry MISSING its id is one of the
+    // findings, and a ledger keyed on a value that may be absent could not
+    // account for exactly the target that failed.
+    const ledger = new GateLedger('lint_metric_consumers');
+    const targetOf = (i: number): string => `${REGISTRY_REL}#${String(i + 1)}`;
+    ledger.plan(read.entries.map((_e, i) => targetOf(i)));
+
+    const findings: Finding[] = [];
+    const seen = new Set<string>();
+    read.entries.forEach((entry, i) => {
+        // A null or non-object element is a FINDING, not a crash (R2 finding
+        // 5). `metrics: [null]` reached `normalise(entry.id)` and threw an
+        // unhandled TypeError out of a gate whose job is to report.
+        if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+            findings.push({
+                id: `#${String(i + 1)}`,
+                field: '(entry)',
+                reason: 'not a mapping — a metric entry must be a key/value block',
+            });
+            ledger.fail(targetOf(i), 'not a mapping');
+            return;
+        }
+        const before = findings.length;
+        findings.push(...findingsFor(entry, i));
+        const id = normalise(entry.id);
+        if (id !== '' && seen.has(id)) {
+            findings.push({ id, field: 'id', reason: 'duplicate — two entries claim the same metric' });
+        }
+        if (id !== '') seen.add(id);
+        if (findings.length > before) ledger.fail(targetOf(i), findings[before]?.reason ?? 'finding');
+        else ledger.complete(targetOf(i));
+    });
+    ledger.report();
+
+    if (findings.length > 0) {
+        process.stderr.write(
+            `❌  lint_metric_consumers: ${String(findings.length)} finding(s) in ${REGISTRY_REL}\n`,
+        );
+        for (const f of findings) {
+            process.stderr.write(`  · ${f.id} → ${f.field}: ${f.reason}\n`);
+        }
+        process.stderr.write(
+            '\n  A metric with no consumer is telemetry decoration and should not land.\n'
+                + '  `absent` is the falsifiable field: if nothing fails without the metric,\n'
+                + '  the entry cannot honestly be written and the metric should not exist.\n',
+        );
+        return 1;
+    }
+
+    if (!quiet) {
+        process.stdout.write(
+            `✅  lint_metric_consumers: ${String(read.entries.length)} metric(s), each naming a `
+                + 'consumer, a decision and what fails without it.\n',
+        );
+    }
+    return 0;
+}
+
+if (process.argv[1] !== undefined) {
+    const invoked = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (invoked === import.meta.url) {
+        process.exitCode = main();
+    }
+}