@event4u/agent-config 9.7.0 → 9.8.0

package/src/scripts/build_proof.ts

@@ -41,6 +41,105 @@ class ExitCode extends Error {
     }
 }
 
+/**
+ * The prevented-failure table.
+ *
+ * Every row names a **failure mode that is prevented**, never a feature. That
+ * constraint is the whole discipline: "cross-platform" is a feature and says
+ * nothing; "the same rules do not silently differ between the agent you run
+ * today and the one you switch to" names what goes wrong without it.
+ *
+ * Every row cites a ledger claim, and `backs` is not decoration — a cited id
+ * that is missing or not `backed` throws, so the table cannot outlive its
+ * evidence. This is the guard against the failure it was modelled on: the
+ * reference ships an equivalent table whose headline efficiency figure appears
+ * only there, an order of magnitude below the cheapest scenario in its own
+ * generated benchmark. A number with nowhere to resolve is exactly what this
+ * ledger exists to catch, so the table is held to the ledger's own bar.
+ *
+ * A row with no resolving claim ships WITHOUT a number rather than with an
+ * approximate one.
+ */
+export const PREVENTED_FAILURES: { failure: string; mechanism: string; backs: string }[] = [
+    {
+        failure: 'A rule says MUST, and nothing anywhere enforces it — so the rule reads as a guarantee while being honour-system.',
+        mechanism:
+            'Each rule declares `enforced_by:`, and the check **resolves** it: a validator reachable from no taskfile, workflow, or hook manifest counts as unwired, not as covered. Undeclared counts as uncovered.',
+        backs: 'enforcement-coverage-resolved',
+    },
+    {
+        failure:
+            'A shipped artefact carries a hidden-Unicode or instruction-smuggling payload, and reaches consumers because only the source tree was scanned.',
+        mechanism:
+            'Source **and** the condensed projection are scanned in CI; a finding blocks the release before publish, not merely the merge.',
+        backs: 'shipped-artifacts-hidden-instruction-scanned',
+    },
+    {
+        failure:
+            'A count in public prose drifts from the source, and the marketing number quietly stops being true.',
+        mechanism:
+            'Counts are generated from source and drift-checked; the build fails on a count-shaped prose mention that disagrees, or on two different numbers for the same artefact kind.',
+        backs: 'skill-count',
+    },
+    {
+        failure:
+            'A host-coverage claim understates or overstates what actually works — for months, on the one surface everybody reads.',
+        mechanism: 'The number is pinned by a test over real detection, and the test is re-run as the claim evidence.',
+        backs: 'host-agent-count',
+    },
+    {
+        failure:
+            'A non-coding domain skill implies proven correctness it never had, because it was forged on a different domain and never checked against one.',
+        mechanism:
+            'Domain skills are labelled unvalidated until they pass a sourced domain-truth fixture, and the validated count is ratcheted so it cannot quietly fall.',
+        backs: 'domain-soundness-scoped',
+    },
+    {
+        failure:
+            'Behavioural-eval coverage regresses as skills are added, and the suite looks healthy because only the absolute number is reported.',
+        mechanism: 'Coverage is measured per tier and ratcheted in CI, so it can only rise; the gap is published rather than implied away.',
+        backs: 'eval-coverage-ratcheted',
+    },
+];
+
+export function renderPreventedFailures(ledger: ReturnType<typeof load_ledger>): string {
+    const L: string[] = [];
+    L.push('## What this prevents');
+    L.push('');
+    L.push('Each row is a failure mode, not a feature — and each cites the ledger');
+    L.push('claim that backs it. A row whose claim stopped resolving would fail this');
+    L.push('page\'s own generator, so the table cannot outlive its evidence.');
+    L.push('');
+    L.push('| Failure this prevents | How | Backed by |');
+    L.push('|---|---|---|');
+    for (const row of PREVENTED_FAILURES) {
+        const entry = ledger.get(row.backs);
+        if (!entry) {
+            throw new Error(
+                `build_proof: prevented-failure row cites claim '${row.backs}', which has no ledger entry. ` +
+                    'Bind it in docs/CLAIMS.md or drop the row — the table may not carry an unbacked cell.',
+            );
+        }
+        if (entry.status !== 'backed') {
+            throw new Error(
+                `build_proof: prevented-failure row cites claim '${row.backs}', whose ledger status is ` +
+                    `'${entry.status}', not 'backed'. The table may not carry an unbacked cell.`,
+            );
+        }
+        const reverifies = entry.evidence.trim().startsWith('exec:') ? ' ⟳' : '';
+        L.push(
+            `| ${row.failure.replace(/\|/g, '\\|')} | ${row.mechanism.replace(/\|/g, '\\|')} | ` +
+                `[\`${row.backs}\`](CLAIMS.md)${reverifies} |`,
+        );
+    }
+    L.push('');
+    L.push('⟳ — the claim carries `exec:` evidence: CI re-runs the command and');
+    L.push('compares its exit code, so a stale row turns the build red rather than');
+    L.push('ageing quietly into marketing.');
+    L.push('');
+    return L.join('\n');
+}
+
 function render(): string {
     const ledger = load_ledger();
     const entries = [...ledger.values()].sort((a, b) => a.id.localeCompare(b.id));
@@ -59,6 +158,7 @@ function render(): string {
     L.push('every check below on a fresh checkout. This page is itself generated');
     L.push('from those sources and fails CI if it drifts.');
     L.push('');
+    L.push(renderPreventedFailures(ledger));
     L.push('## See it run (< 60s, real output)');
     L.push('');
     L.push('![The trust surface running green — every "verify it yourself" command below, recorded from a real run](media/proof-demo.gif)');
@@ -86,6 +186,39 @@ function render(): string {
     L.push('');
     L.push(`**${backed.length} backed claim(s)** — all evidence pointers resolve in CI.`);
     L.push('');
+
+    // Re-verifiable vs. merely-resolving. The distinction is the point: a
+    // pointer proves an artefact exists, not that the claim is still true. Any
+    // page that reported only the backed total would hide exactly the gap this
+    // ledger was built to expose.
+    const execBacked = backed.filter((e) => e.evidence.trim().startsWith('exec:'));
+    const pointerOnly = backed.filter((e) => !e.evidence.trim().startsWith('exec:'));
+    L.push('### How many of those re-derive themselves');
+    L.push('');
+    L.push(`**${execBacked.length} of ${backed.length}** backed claims carry \`exec:\` evidence —`);
+    L.push('CI re-runs the command and compares its exit code to the claim, so a');
+    L.push('stale one turns the build red. The other');
+    L.push(`**${pointerOnly.length}** rest on a pointer: CI checks that the artefact`);
+    L.push('exists and contains what it should, which cannot distinguish a live');
+    L.push('claim from one whose producer nobody has run in months.');
+    L.push('');
+    L.push('That residue is not an oversight, and it is listed rather than rounded');
+    L.push('away. A claim can only re-derive itself when a deterministic command');
+    L.push("carries the verdict in its exit code. These cannot, for the reasons");
+    L.push('given:');
+    L.push('');
+    L.push('| Claim | Why it cannot re-execute |');
+    L.push('|---|---|');
+    for (const e of pointerOnly) {
+        const ev = e.evidence.trim();
+        const why = /^https?:\/\//.test(ev)
+            ? 'external cite — CI does not fetch the network'
+            : /benchmark|bench\/|results-/.test(ev)
+              ? 'benchmark output — regenerating it needs paid or stochastic model calls no CI job can re-derive'
+              : 'prose or contract artefact — no exit code carries the verdict';
+        L.push(`| ${e.claim.replace(/\|/g, '\\|').slice(0, 110)} | ${why} |`);
+    }
+    L.push('');
     L.push('Artefact counts in public prose (skills, commands, governed rules,');
     L.push('guidelines, personas) are **generated from source and CI-drift-checked**:');
     L.push('`update_counts.ts` writes the numbers, `check_artefact_count_messaging.ts`');
@@ -224,6 +357,35 @@ function render(): string {
             L.push(`| ${claim} | ${ours} | ${theirs} | ${r.checkable ? '✅' : '—'} |`);
         }
     }
+
+    // Second lens on the SAME rows: what each one prevents, for a reader who has
+    // not asked "compared to what". Membership is a data property — a row appears
+    // here iff it carries a `failure_mode` — so nobody curates a short-list that
+    // then drifts from the table above. The pointer is the same pointer, resolved
+    // by the same gate, so no cell reaches this view unbound.
+    const fmRows = cmpRows.filter((r) => (r.failure_mode ?? '').trim() !== '');
+    if (fmRows.length > 0) {
+        L.push('');
+        L.push('### What each one prevents');
+        L.push('');
+        L.push('The same rows, read as failure modes rather than as comparisons. Each names');
+        L.push('something that goes wrong without the control and carries the identical');
+        L.push('resolvable pointer — a projection of the table above, not a second list to');
+        L.push('keep in sync.');
+        L.push('');
+        L.push('| Without it | The control | Evidence |');
+        L.push('|---|---|---|');
+        for (const r of fmRows) {
+            const fm = (r.failure_mode ?? '').replace(/\|/g, '\\|').trim();
+            const claim = r.claim.replace(/\|/g, '\\|');
+            const filePart = (r.our_evidence.split('#')[0] ?? r.our_evidence).split(':')[0] ?? r.our_evidence;
+            const ours = pointer_unresolved(r.our_evidence) === null
+                ? `[\`${r.our_evidence}\`](../${filePart})`
+                : `\`${r.our_evidence}\``;
+            L.push(`| ${fm} | ${claim} | ${ours} |`);
+        }
+    }
+
     L.push('');
     L.push('## 5. Verify it yourself');
     L.push('');

package/src/scripts/check_adr_frontmatter.ts

@@ -0,0 +1,195 @@
+#!/usr/bin/env tsx
+/**
+ * ADR frontmatter gate — and the `review_trigger` field that makes a decision
+ * revisitable on purpose rather than by archaeology.
+ *
+ * Two findings drive this. First, ADR frontmatter was **entirely unvalidated**:
+ * `validate_frontmatter.ts` covers skills, rules, commands, and personas, and
+ * nothing covered `docs/decisions/`. That is why `review_date` drifted into 11
+ * ADRs and back out again with nobody noticing.
+ *
+ * Second, of 128 ADRs, zero named the condition under which they should be
+ * reconsidered — while `decision-record` SKILL § step 4 already *mandates* a
+ * "Revisit-if" line and `decision-revisit-gate` already treats an ADR as a lock
+ * that must be re-openable. The doctrine was canon; the template just never
+ * emitted a slot for it, so 33 authors wrote it in prose and it stayed
+ * unfindable. This is a missing field, not a missing idea.
+ *
+ * `review_trigger` is a named CONDITION, never a date. "Review annually" is
+ * ignored by everyone and rots into ceremony; "when a second consumer reports a
+ * preservation surprise" fires exactly when it should.
+ *
+ * Grandfathering is by authorship date, not an allowlist: ADRs dated before the
+ * switch warn, ADRs dated on or after it fail. No list to maintain and no
+ * exemption to forget — a retrofit of 128 files would be busywork that teaches
+ * nobody anything.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/check_adr_frontmatter          # gate
+ *   ./scripts-run src/scripts/check_adr_frontmatter --json
+ *
+ * Exit codes: 0 ok (warnings allowed) · 1 violation · 2 usage/env error.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(_HERE, '..', '..');
+const ADR_DIR = path.join(REPO_ROOT, 'docs', 'decisions');
+
+/**
+ * Grandfathering switch. ADRs dated before this warn on a missing
+ * `review_trigger`; ADRs dated on or after it fail.
+ */
+export const REVIEW_TRIGGER_SINCE = '2026-07-25';
+
+/** Fields every ADR must carry — the shape that already exists in practice. */
+const REQUIRED = ['adr', 'status', 'date', 'decision'] as const;
+
+const ALLOWED_STATUS = new Set([
+    'accepted',
+    'proposed',
+    'superseded',
+    'rejected',
+    'deprecated',
+    'draft',
+]);
+
+export interface AdrFinding {
+    file: string;
+    level: 'error' | 'warn';
+    message: string;
+}
+
+export function parse_frontmatter(text: string): Record<string, string> | null {
+    if (!text.startsWith('---\n')) return null;
+    const end = text.indexOf('\n---\n', 4);
+    if (end === -1) return null;
+    const out: Record<string, string> = {};
+    let key: string | null = null;
+    for (const raw of text.slice(4, end).split('\n')) {
+        const line = raw.replace(/\s+$/, '');
+        if (!line || line.trimStart().startsWith('#')) continue;
+        // Continuation of a folded/indented value.
+        if (/^\s/.test(line) && key) {
+            out[key] = `${out[key]} ${line.trim()}`.trim();
+            continue;
+        }
+        const idx = line.indexOf(':');
+        if (idx === -1) continue;
+        key = line.slice(0, idx).trim();
+        out[key] = line
+            .slice(idx + 1)
+            .trim()
+            .replace(/^["'](.*)["']$/, '$1');
+    }
+    return out;
+}
+
+/** A trigger must name a condition. A bare cadence is the failure mode. */
+export function trigger_is_meaningful(value: string): boolean {
+    const v = value.trim();
+    if (v.length < 20) return false;
+    // "annually" / "every 6 months" / a bare date is a calendar, not a condition.
+    if (/^(annually|yearly|quarterly|monthly|every\s+\d+\s+\w+|\d{4}-\d{2}-\d{2})\.?$/i.test(v)) {
+        return false;
+    }
+    return true;
+}
+
+export function check(dir: string = ADR_DIR): AdrFinding[] {
+    const findings: AdrFinding[] = [];
+    if (!fs.existsSync(dir)) return findings;
+
+    for (const name of fs.readdirSync(dir).sort()) {
+        if (!/^ADR-.*\.md$/.test(name)) continue;
+        const rel = path.relative(REPO_ROOT, path.join(dir, name));
+        const fm = parse_frontmatter(fs.readFileSync(path.join(dir, name), 'utf-8'));
+
+        if (fm === null) {
+            findings.push({ file: rel, level: 'error', message: 'no YAML frontmatter block' });
+            continue;
+        }
+        for (const req of REQUIRED) {
+            if (!fm[req]) findings.push({ file: rel, level: 'error', message: `missing \`${req}\`` });
+        }
+        if (fm['status'] && !ALLOWED_STATUS.has(fm['status'])) {
+            findings.push({
+                file: rel,
+                level: 'error',
+                message: `status \`${fm['status']}\` is not one of: ${[...ALLOWED_STATUS].sort().join(', ')}`,
+            });
+        }
+
+        const date = fm['date'] ?? '';
+        const grandfathered = date !== '' && date < REVIEW_TRIGGER_SINCE;
+        const trigger = fm['review_trigger'];
+
+        if (!trigger) {
+            findings.push({
+                file: rel,
+                level: grandfathered ? 'warn' : 'error',
+                message: grandfathered
+                    ? `no \`review_trigger\` (grandfathered — dated ${date}, before ${REVIEW_TRIGGER_SINCE})`
+                    : `missing \`review_trigger\` — name the CONDITION that would reopen this decision`,
+            });
+        } else if (!trigger_is_meaningful(trigger)) {
+            findings.push({
+                file: rel,
+                level: grandfathered ? 'warn' : 'error',
+                message: `\`review_trigger\` is a cadence, not a condition: "${trigger}". A calendar review is ignored; an event fires.`,
+            });
+        }
+    }
+    return findings;
+}
+
+function main(argv: string[]): number {
+    const as_json = argv.includes('--json');
+    const findings = check();
+
+    if (as_json) {
+        process.stdout.write(JSON.stringify({ findings }, null, 2) + '\n');
+        return 0;
+    }
+
+    const errors = findings.filter((f) => f.level === 'error');
+    const warns = findings.filter((f) => f.level === 'warn');
+    const total = fs.existsSync(ADR_DIR)
+        ? fs.readdirSync(ADR_DIR).filter((f) => /^ADR-.*\.md$/.test(f)).length
+        : 0;
+
+    process.stdout.write(
+        `ADR frontmatter: ${total} ADR(s) · ${errors.length} error(s) · ` +
+            `${warns.length} grandfathered without a revisit condition\n`,
+    );
+    for (const e of errors) process.stderr.write(`    ❌ ${e.file}: ${e.message}\n`);
+
+    if (errors.length > 0) {
+        process.stderr.write(
+            `\n❌  check_adr_frontmatter: ${errors.length} error(s). ` +
+                `ADRs dated ${REVIEW_TRIGGER_SINCE} or later must name a \`review_trigger\`.\n`,
+        );
+        return 1;
+    }
+    process.stdout.write('✅  check_adr_frontmatter: no errors\n');
+    return 0;
+}
+
+// Main-guard (realpath-compared, mirrors the repo convention).
+if (process.argv[1] !== undefined) {
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv1 = fs.realpathSync(path.resolve(process.argv[1]));
+        if (here === argv1) {
+            process.exit(main(process.argv.slice(2)));
+        }
+    } catch {
+        const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+        if (import.meta.url === argvUrl) {
+            process.exit(main(process.argv.slice(2)));
+        }
+    }
+}

package/src/scripts/check_artefact_count_messaging.ts

@@ -53,6 +53,10 @@ export const SURFACES: readonly string[] = [
     'docs/featured-skills.md',
     'docs/featured-commands.md',
     'docs/proof.md',
+    // Public submission text: the block here described version 3.2.0 with a
+    // "4929 tests" figure while the package reached 9.7.0, because nothing
+    // watched this file. Added 2026-07-25 so a hand-typed count here fails CI.
+    'docs/distribution/registries.md',
     'site/src/content/docs/index.mdx',
     'site/src/content/docs/claims.md',
 ];

package/src/scripts/check_backstop_debt.ts

@@ -0,0 +1,200 @@
+#!/usr/bin/env tsx
+/**
+ * Debt ratchet for rule backstops that are red on arrival.
+ *
+ * Wiring the `enforced_by:` validators into CI (`rule-backstops.yml`) surfaced
+ * something the coverage number could not: **five of them were already failing**,
+ * and had been, invisibly, because no workflow ran them. A rule declared a
+ * backstop; the backstop existed; the backstop was red; nothing said so.
+ *
+ * Those failures are pre-existing debt, not regressions from the wiring change,
+ * and fixing eleven framework-leakage spots plus eighteen source-confidentiality
+ * hits is a different piece of work with a different reviewer. Folding them in
+ * would make one PR unreviewable and would mix "make the gate run" with "clean up
+ * what the gate found".
+ *
+ * So the established pattern applies — the one the decision-homing work already
+ * uses and the council endorsed: **baseline the legacy, enforce the boundary.**
+ * Each gate's current finding count is committed. The count may fall freely; it
+ * may not rise. New violations fail, existing debt is visible and counted, and
+ * nothing is silently tolerated.
+ *
+ * What this deliberately is NOT: a `continue-on-error` step. That is a WARN
+ * wearing a gate's clothes, and removing exactly that confusion is why this
+ * workflow exists.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/check_backstop_debt            # ratchet (CI)
+ *   ./scripts-run src/scripts/check_backstop_debt --write-baseline
+ *   ./scripts-run src/scripts/check_backstop_debt --json
+ *
+ * Exit codes: 0 held or improved · 1 a count rose · 2 usage/env error.
+ */
+
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(_HERE, '..', '..');
+const BASELINE = path.join(REPO_ROOT, 'internal', 'reports', 'rule-backstop-debt.json');
+
+export interface Gate {
+    /** Script stem under `src/scripts/`. */
+    script: string;
+    /** The rule whose `enforced_by:` names it — so a reader knows what is unguarded. */
+    rule: string;
+    /**
+     * Extracts the finding count from the gate's own output.
+     *
+     * Explicit per gate rather than a shared heuristic: these five print their
+     * totals in five different shapes, and a regex that guesses would silently
+     * read 0 the day a gate changes its wording — turning a rising count into a
+     * passing build, which is the failure mode this file exists to prevent.
+     */
+    count: RegExp;
+}
+
+export const GATES: readonly Gate[] = [
+    { script: 'lint_framework_leakage', rule: 'framework-neutrality-in-generic-skills', count: /^(\d+) hits across \d+ files/m },
+    { script: 'check_no_roadmap_refs', rule: 'no-roadmap-references', count: /Found (\d+) roadmap reference\(s\)/ },
+    { script: 'check_council_references', rule: 'no-roadmap-references', count: /(\d+) forbidden council reference\(s\)/ },
+    { script: 'check_no_external_sources', rule: 'source-confidentiality', count: /(\d+) external-source reference\(s\)/ },
+    { script: 'check_token_optimizer_freshness', rule: 'token-optimizer-maintenance', count: /(\d+) drift signal\(s\)/ },
+];
+
+export interface Measured {
+    script: string;
+    rule: string;
+    findings: number;
+    exit_code: number;
+    /** True when the gate ran but its count pattern did not match — never read as 0. */
+    unparsed: boolean;
+}
+
+export function measure(gate: Gate, repo: string = REPO_ROOT): Measured {
+    const r = spawnSync('./scripts-run', [`src/scripts/${gate.script}`], {
+        cwd: repo,
+        encoding: 'utf-8',
+        env: { ...process.env, NO_COLOR: '1' },
+    });
+    const out = `${r.stdout ?? ''}\n${r.stderr ?? ''}`;
+    const m = gate.count.exec(out);
+    // A clean gate legitimately prints no total. Only treat a MISSING count as
+    // unparsed when the gate actually failed — otherwise a green run reads as
+    // broken instrumentation.
+    const failed = (r.status ?? 0) !== 0;
+    return {
+        script: gate.script,
+        rule: gate.rule,
+        findings: m ? Number(m[1]) : 0,
+        exit_code: r.status ?? 0,
+        unparsed: failed && m === null,
+    };
+}
+
+function main(argv: string[]): number {
+    const as_json = argv.includes('--json');
+    const write = argv.includes('--write-baseline');
+
+    const measured = GATES.map((g) => measure(g));
+
+    if (as_json) {
+        process.stdout.write(JSON.stringify({ gates: measured }, null, 2) + '\n');
+        return 0;
+    }
+
+    if (write) {
+        fs.mkdirSync(path.dirname(BASELINE), { recursive: true });
+        fs.writeFileSync(
+            BASELINE,
+            JSON.stringify(
+                {
+                    _doc:
+                        'Pre-existing findings in rule backstops that were red when they were first ' +
+                        'wired into CI — they had been failing invisibly because no workflow ran them. ' +
+                        'Counts may FALL freely; a rise fails the build. This is debt made visible, ' +
+                        'not debt tolerated: every number here is a rule whose declared backstop is ' +
+                        'currently not clean. Regenerate with --write-baseline only when the change ' +
+                        'is deliberate.',
+                    gates: Object.fromEntries(measured.map((m) => [m.script, { rule: m.rule, findings: m.findings }])),
+                    total: measured.reduce((a, m) => a + m.findings, 0),
+                },
+                null,
+                2,
+            ) + '\n',
+        );
+        process.stdout.write(`✅  wrote baseline → ${path.relative(REPO_ROOT, BASELINE)}\n`);
+        return 0;
+    }
+
+    if (!fs.existsSync(BASELINE)) {
+        process.stderr.write(
+            `❌  check_backstop_debt: no baseline at ${path.relative(REPO_ROOT, BASELINE)}; run --write-baseline\n`,
+        );
+        return 2;
+    }
+    const base = JSON.parse(fs.readFileSync(BASELINE, 'utf-8')).gates as Record<string, { findings: number }>;
+
+    const regressions: string[] = [];
+    const improvements: string[] = [];
+    for (const m of measured) {
+        if (m.unparsed) {
+            regressions.push(
+                `${m.script}: failed (exit ${m.exit_code}) but its finding count could not be read — ` +
+                    `the count pattern no longer matches its output. Fix the pattern; do not assume 0.`,
+            );
+            continue;
+        }
+        const was = base[m.script]?.findings;
+        if (was === undefined) {
+            regressions.push(`${m.script}: not in the baseline — add it with --write-baseline`);
+            continue;
+        }
+        if (m.findings > was) {
+            regressions.push(`${m.script} (${m.rule}): findings rose ${was} → ${m.findings}`);
+        } else if (m.findings < was) {
+            improvements.push(`${m.script} (${m.rule}): ${was} → ${m.findings}`);
+        }
+    }
+
+    const total = measured.reduce((a, m) => a + m.findings, 0);
+    process.stdout.write(
+        `rule-backstop debt · ${total} finding(s) across ${measured.filter((m) => m.findings > 0).length} red gate(s)\n`,
+    );
+    for (const m of measured) {
+        if (m.findings > 0) process.stdout.write(`  · ${m.script} (${m.rule}): ${m.findings}\n`);
+    }
+    for (const i of improvements) process.stdout.write(`  ✅ improved — ${i}\n`);
+
+    if (regressions.length > 0) {
+        process.stderr.write('❌  rule-backstop debt ratchet:\n');
+        for (const r of regressions) process.stderr.write(`    · ${r}\n`);
+        process.stderr.write(
+            '    These gates are already failing on pre-existing debt; the ratchet only forbids ADDING to it.\n',
+        );
+        return 1;
+    }
+    if (improvements.length > 0) {
+        process.stdout.write('    Baseline is now loose — regenerate with --write-baseline to lock the improvement.\n');
+    }
+    process.stdout.write('✅  rule-backstop debt ratchet holds\n');
+    return 0;
+}
+
+// Main-guard (realpath-compared, mirrors the repo convention).
+if (process.argv[1] !== undefined) {
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv1 = fs.realpathSync(path.resolve(process.argv[1]));
+        if (here === argv1) {
+            process.exit(main(process.argv.slice(2)));
+        }
+    } catch {
+        const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+        if (import.meta.url === argvUrl) {
+            process.exit(main(process.argv.slice(2)));
+        }
+    }
+}