@event4u/agent-config 7.5.0 → 8.0.0

package/src/scripts/build_proof.ts

@@ -0,0 +1,214 @@
+#!/usr/bin/env tsx
+/**
+ * Generate docs/proof.md — the public, self-verifying trust surface.
+ *
+ * Market-readiness roadmap Track B / B4. Renders, from real sources, the three
+ * proofs a skeptic can check themselves:
+ *   1. Every markered public claim binds to a resolvable evidence pointer
+ *      (rendered from docs/CLAIMS.md — reuses the check_claims ledger loader).
+ *   2. Honest-null results are published, not hidden (pointer to docs/benchmark.md).
+ *   3. A "verify it yourself" block — the exact commands that reproduce 1 + 2 on
+ *      a fresh checkout.
+ *
+ * **Generated, never hand-maintained** — drift-checked in CI via `--check`, the
+ * same discipline as generate_capabilities_index / generate_cookbook. Output is
+ * deterministic (sorted, no timestamp) so `--check` is stable. A proof page that
+ * could drift from its sources would undermine the very claim it makes.
+ *
+ * Usage:
+ *     ./scripts-run src/scripts/build_proof            # (re)write docs/proof.md
+ *     ./scripts-run src/scripts/build_proof --check    # exit 2 if stale
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { REPO, LEDGER_REL, load_ledger, pointer_unresolved } from './check_claims.js';
+import { collectSkillGaps } from './check_skill_gaps.js';
+import { loadRows as loadComparisonRows } from './check_comparison.js';
+
+const _FILE = fileURLToPath(import.meta.url);
+const OUT_REL = 'docs/proof.md';
+const BENCH_REL = 'docs/benchmark.md';
+
+class ExitCode extends Error {
+    code: number;
+    constructor(code: number) {
+        super(`exit ${code}`);
+        this.code = code;
+    }
+}
+
+function render(): string {
+    const ledger = load_ledger();
+    const entries = [...ledger.values()].sort((a, b) => a.id.localeCompare(b.id));
+    const backed = entries.filter((e) => e.status === 'backed');
+    const unbacked = entries.filter((e) => e.status === 'unbacked');
+
+    const L: string[] = [];
+    L.push('<!-- GENERATED by src/scripts/build_proof.ts — do NOT hand-edit.');
+    L.push('     Drift-checked in CI (`task build-proof-check`). Regenerate with');
+    L.push('     `./scripts-run src/scripts/build_proof` after editing docs/CLAIMS.md. -->');
+    L.push('');
+    L.push('# Proof — verify our claims yourself');
+    L.push('');
+    L.push('We sell falsifiability, so the selling is machine-checked. Every');
+    L.push('public claim binds to resolvable evidence; a skeptic can reproduce');
+    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('## 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)');
+    L.push('');
+    L.push('The recording is of the exact commands in § 5, nothing staged. Its');
+    L.push('commands are re-executed in CI (`.github/workflows/proof-demo.yml`), so a');
+    L.push('demo that showed something broken would turn CI red — the recording');
+    L.push('cannot drift from current behavior.');
+    L.push('');
+    L.push('## 1. Every public claim binds to evidence');
+    L.push('');
+    L.push(`Rendered from [\`${LEDGER_REL}\`](CLAIMS.md). A \`<!-- claim:ID -->\` marker in`);
+    L.push('README/docs must resolve to a `backed` entry here with a resolving');
+    L.push('evidence pointer, or `task check-claims` fails the build.');
+    L.push('');
+    L.push('| Claim | Kind | Evidence | Resolves |');
+    L.push('|---|---|---|---|');
+    for (const e of backed) {
+        const un = pointer_unresolved(e.evidence);
+        const resolves = un ? `❌ ${un}` : '✅';
+        const claim = e.claim.replace(/\|/g, '\\|');
+        const evidence = e.evidence.replace(/\|/g, '\\|');
+        L.push(`| ${claim} | ${e.kind} | \`${evidence}\` | ${resolves} |`);
+    }
+    L.push('');
+    L.push(`**${backed.length} backed claim(s)** — all evidence pointers resolve in CI.`);
+    if (unbacked.length > 0) {
+        L.push('');
+        L.push(`We also publish our **debt**: ${unbacked.length} claim(s) are logged as`);
+        L.push('`unbacked` inventory in the ledger — not yet bound, and therefore not');
+        L.push('allowed to carry a marker in public prose. Hiding them would be the');
+        L.push('opposite of the point.');
+    }
+    L.push('');
+    L.push('## 2. We publish honest nulls');
+    L.push('');
+    if (fs.existsSync(path.join(REPO, BENCH_REL))) {
+        L.push(`Benchmark results — **including the runs where the package changed nothing** —`);
+        L.push(`live in [\`${BENCH_REL}\`](benchmark.md). We do not delete a measured null to`);
+        L.push('make a number look better; the null is the evidence of honesty.');
+    } else {
+        L.push('Benchmark results are published under `docs/` including measured nulls.');
+    }
+    L.push('');
+    L.push('## 3. Known limits (published, witness-tested)');
+    L.push('');
+    const skillGaps = collectSkillGaps();
+    if (skillGaps.length === 0) {
+        L.push('No skill has logged a known-limit `gaps:` entry yet. When one does, it');
+        L.push('appears here with a witness test that reproduces the limitation — the');
+        L.push('transparency surface a headline-benchmark structurally cannot ship.');
+    } else {
+        L.push('Each limitation below is stated by the skill itself and carries a witness');
+        L.push('test that reproduces it. If the limitation is ever fixed, its witness goes');
+        L.push('red — so a "Known limit" can never quietly become false.');
+        L.push('');
+        L.push('| skill | known limit | witness |');
+        L.push('|---|---|---|');
+        for (const sg of skillGaps) {
+            for (const g of sg.gaps) {
+                const desc = g.description.replace(/\|/g, '\\|');
+                L.push(`| \`${sg.skill}\` | ${desc} | [\`${g.witness}\`](../${g.witness}) |`);
+            }
+        }
+    }
+    L.push('');
+    L.push('## 4. What is checkable — us vs. the category');
+    L.push('');
+    const cmpRows = loadComparisonRows();
+    if (cmpRows.length === 0) {
+        L.push('No comparison rows recorded yet.');
+    } else {
+        L.push('This is not a takedown — the point is the last column. For each claim,');
+        L.push('our evidence is a pointer you can resolve on a fresh checkout; the wider');
+        L.push('category is described only by what is publicly observable, never a named');
+        L.push('competitor and never a counter-claim to anyone\'s headline number. A claim');
+        L.push('is "checkable" only when its `our evidence` pointer resolves — CI enforces');
+        L.push('that (`task check-comparison`), so this column can never lie.');
+        L.push('');
+        L.push('| Claim | Our evidence | The category | Checkable? |');
+        L.push('|---|---|---|---|');
+        for (const r of cmpRows) {
+            const claim = r.claim.replace(/\|/g, '\\|');
+            const theirs = r.their_evidence.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(`| ${claim} | ${ours} | ${theirs} | ${r.checkable ? '✅' : '—'} |`);
+        }
+    }
+    L.push('');
+    L.push('## 5. Verify it yourself');
+    L.push('');
+    L.push('On a fresh checkout, reproduce the claims above:');
+    L.push('');
+    L.push('```bash');
+    L.push('task check-claims   # every markered public claim binds to resolvable evidence');
+    L.push('task check-refs     # no broken internal references');
+    L.push('task check-skill-gaps    # every logged known-limit cites a real witness test');
+    L.push('task check-comparison    # every comparison-table "our evidence" pointer resolves');
+    L.push('task build-proof-check   # this page is in sync with its sources');
+    L.push('```');
+    L.push('');
+    L.push('If a claim ever loses its binding, or this page drifts from the ledger,');
+    L.push('CI goes red. Reproducibility is the proof.');
+    L.push('');
+    return L.join('\n');
+}
+
+function main(argv: string[] = process.argv.slice(2)): number {
+    const check = argv.includes('--check');
+    if (argv.includes('-h') || argv.includes('--help')) {
+        process.stdout.write('usage: build_proof [--check]\n');
+        return 0;
+    }
+    const out = render();
+    const outPath = path.join(REPO, OUT_REL);
+    if (check) {
+        const current = fs.existsSync(outPath) ? fs.readFileSync(outPath, 'utf8') : '';
+        if (current !== out) {
+            process.stderr.write(
+                `❌  build_proof: ${OUT_REL} is stale. Run './scripts-run src/scripts/build_proof' and commit.\n`,
+            );
+            return 2;
+        }
+        process.stdout.write(`✅  build_proof: ${OUT_REL} in sync.\n`);
+        return 0;
+    }
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    fs.writeFileSync(outPath, out);
+    process.stdout.write(`✅  build_proof: wrote ${OUT_REL}.\n`);
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    const a = process.argv[1];
+    if (!a) return false;
+    if (a === _FILE || pathToFileURL(path.resolve(a)).href === import.meta.url) return true;
+    try {
+        return fs.realpathSync(a) === fs.realpathSync(_FILE);
+    } catch {
+        return false;
+    }
+}
+if (_isCliEntry()) {
+    try {
+        process.exit(main());
+    } catch (exc) {
+        if (exc instanceof ExitCode) process.exit(exc.code);
+        throw exc;
+    }
+}
+
+export { render, main, OUT_REL };

package/src/scripts/check_always_budget.ts

@@ -46,6 +46,9 @@ const CONCENTRATION_TOP3_PCT = 0.3;
 const KNOWN_CONCENTRATION_BREACHES: Record<string, number> = {
     'language-and-tone.md': 4_174,
     'no-cheap-questions.md': 3_719,
+    // Retired by the concentration-cap recalibration in the budget-SoT PR
+    // (12% mis-fits a 9-rule kernel; direct-answers 12.7% < the recalibrated cap).
+    'direct-answers.md': 3_600,
 };
 const KNOWN_TOP3_CONCENTRATION_CEILING: number | null = 11_300;
 

package/src/scripts/check_augment_description_cap.ts

@@ -14,7 +14,7 @@
  *
  * Why: Augment injects each auto-rule's description into the
  * workspace-guidelines registry stub. Empirical 2026-05-08 budget
- * analysis showed this channel consuming 25 % of the 49,512-char
+ * analysis showed this channel consuming 25 % of the workspace-guidelines
  * ceiling. Capping descriptions guards future drift.
  *
  * Source of truth: `.agent-src.uncondensed/rules/`. The condensed
@@ -114,7 +114,7 @@ export function main(): number {
         process.stderr.write(
             `\n  Guard rationale: each char in an auto-rule description ` +
                 `costs one char in the\n  Augment workspace-guidelines budget ` +
-                `(cap 49,512). Trim to ≤ ${DESC_CAP}.\n`,
+                `(cap: src/config/budgets.yml). Trim to ≤ ${DESC_CAP}.\n`,
         );
         return 1;
     }

package/src/scripts/check_claims.ts

@@ -0,0 +1,270 @@
+#!/usr/bin/env tsx
+/**
+ * Claims-Ledger gate — no public claim without a resolvable evidence binding.
+ *
+ * The mechanical anti-hype guardrail (road-to-final-state-and-market-readiness
+ * Phase 1 / Track B, step B1). Every public-facing claim that carries a
+ * `<!-- claim:<id> -->` marker in README.md or docs/ MUST resolve to a ledger
+ * entry in docs/CLAIMS.md whose `status: backed` and whose `evidence` pointer
+ * resolves. A smuggled unbacked claim (marker without a backed, resolvable
+ * ledger entry) fails the build — so "we sell honesty" is itself machine-checked.
+ *
+ * Non-disruptive by design: only `<!-- claim:ID -->`-**markered** spans are
+ * enforced. Unmarkered prose is never checked, so existing README text does not
+ * retroactively break CI; the ledger tightens as claims are markered over time.
+ * Ledger entries with `status: unbacked` are inventory (documented debt) and do
+ * NOT fail the build — but marking such an entry's claim in prose does.
+ *
+ * Evidence-pointer grammar (v1):
+ *   <repo-path>[:line]        → the repo file exists (line advisory).
+ *   <repo-path>#<substring>   → the file exists AND contains <substring>.
+ *   https://… (YYYY-MM-DD)    → external cite with a dated stamp (not fetched).
+ *
+ * Exit codes: 0 = clean · 2 = unbacked/dangling/missing-entry finding OR usage
+ * error. Success prints to stdout; findings print to stderr.
+ *
+ * Usage:
+ *     ./scripts-run src/scripts/check_claims
+ *     ./scripts-run src/scripts/check_claims --quiet
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _FILE = fileURLToPath(import.meta.url);
+const _HERE = path.dirname(_FILE);
+const REPO = path.resolve(_HERE, '..', '..');
+const LEDGER_REL = 'docs/CLAIMS.md';
+
+/** Surfaces scanned for `<!-- claim:ID -->` markers. */
+const SURFACE_ROOTS = ['README.md', 'docs'];
+
+const CLAIM_MARKER = /<!--\s*claim:([A-Za-z0-9._-]+)\s*-->/g;
+const URL_DATED = /^https?:\/\/\S+\(\d{4}-\d{2}-\d{2}\)\s*$/;
+
+class ExitCode extends Error {
+    code: number;
+    constructor(code: number) {
+        super(`exit ${code}`);
+        this.code = code;
+    }
+}
+
+interface LedgerEntry {
+    id: string;
+    claim: string;
+    kind: string;
+    evidence: string;
+    status: string;
+    last_verified: string;
+}
+
+interface Args {
+    quiet: boolean;
+}
+
+function parse_args(argv: string[]): Args {
+    const out: Args = { quiet: false };
+    for (const a of argv) {
+        if (a === '--quiet') {
+            out.quiet = true;
+        } else if (a === '-h' || a === '--help') {
+            process.stdout.write('usage: check_claims [--quiet]\n');
+            throw new ExitCode(0);
+        } else {
+            process.stderr.write(`❌  check_claims: unrecognized argument: ${a}\n`);
+            throw new ExitCode(2);
+        }
+    }
+    return out;
+}
+
+/** Parse docs/CLAIMS.md — one entry per `### claim: <id>` block. */
+function load_ledger(): Map<string, LedgerEntry> {
+    const ledger = new Map<string, LedgerEntry>();
+    const p = path.join(REPO, LEDGER_REL);
+    if (!fs.existsSync(p)) {
+        return ledger;
+    }
+    const lines = fs.readFileSync(p, 'utf8').split('\n');
+    let cur: Partial<LedgerEntry> & { id?: string } = {};
+    const flush = () => {
+        if (cur.id) {
+            ledger.set(cur.id, {
+                id: cur.id,
+                claim: cur.claim ?? '',
+                kind: cur.kind ?? '',
+                evidence: cur.evidence ?? '',
+                status: cur.status ?? '',
+                last_verified: cur.last_verified ?? '',
+            });
+        }
+        cur = {};
+    };
+    for (const line of lines) {
+        const head = line.match(/^###\s+claim:\s*([A-Za-z0-9._-]+)\s*$/);
+        if (head) {
+            flush();
+            cur = { id: head[1]! };
+            continue;
+        }
+        if (!cur.id) continue;
+        const field = line.match(/^-\s+(claim|kind|evidence|status|last_verified):\s*(.*)$/);
+        if (field) {
+            const key = field[1] as keyof LedgerEntry;
+            (cur as Record<string, string>)[key] = (field[2] ?? '').trim();
+        }
+    }
+    flush();
+    return ledger;
+}
+
+/** Recursively collect .md files under a repo-relative root (file or dir). */
+function collect_md(rel: string): string[] {
+    const abs = path.join(REPO, rel);
+    if (!fs.existsSync(abs)) return [];
+    const st = fs.statSync(abs);
+    if (st.isFile()) return abs.endsWith('.md') ? [abs] : [];
+    const out: string[] = [];
+    for (const name of fs.readdirSync(abs)) {
+        if (name === 'node_modules' || name.startsWith('.')) continue;
+        out.push(...collect_md(path.join(rel, name)));
+    }
+    return out;
+}
+
+/** Find every live `<!-- claim:ID -->` marker across the scanned surfaces.
+ *  Skips the ledger file itself and any marker shown as documentation
+ *  (inside a ``` fenced block or an inline `backtick` span). */
+function scan_markers(): { id: string; file: string }[] {
+    const found: { id: string; file: string }[] = [];
+    const files = new Set<string>();
+    for (const root of SURFACE_ROOTS) {
+        for (const f of collect_md(root)) files.add(f);
+    }
+    for (const f of files) {
+        const rel = path.relative(REPO, f);
+        if (rel === LEDGER_REL) continue; // the ledger documents the syntax
+        let fenced = false;
+        for (const line of fs.readFileSync(f, 'utf8').split('\n')) {
+            if (/^\s*```/.test(line)) {
+                fenced = !fenced;
+                continue;
+            }
+            if (fenced) continue;
+            for (const m of line.matchAll(CLAIM_MARKER)) {
+                const before = line.slice(0, m.index ?? 0);
+                const backticks = (before.match(/`/g) ?? []).length;
+                if (backticks % 2 === 1) continue; // inside an inline-code span
+                found.push({ id: m[1]!, file: rel });
+            }
+        }
+    }
+    return found;
+}
+
+/** Does an evidence pointer resolve? Returns null on success, else a reason. */
+function pointer_unresolved(evidence: string): string | null {
+    const ev = evidence.trim();
+    if (!ev) return 'empty evidence pointer';
+    if (/^https?:\/\//.test(ev)) {
+        return URL_DATED.test(ev) ? null : 'external URL missing a (YYYY-MM-DD) stamp';
+    }
+    // repo-path[:line] or repo-path#substring
+    let target = ev;
+    let needle: string | null = null;
+    const hash = ev.indexOf('#');
+    if (hash !== -1) {
+        target = ev.slice(0, hash);
+        needle = ev.slice(hash + 1);
+    }
+    target = target.replace(/:\d+$/, ''); // strip :line
+    const abs = path.join(REPO, target);
+    if (!fs.existsSync(abs)) return `evidence path not found: ${target}`;
+    if (needle) {
+        const body = fs.readFileSync(abs, 'utf8');
+        if (!body.includes(needle)) return `evidence file lacks '${needle}': ${target}`;
+    }
+    return null;
+}
+
+interface Finding {
+    id: string;
+    file: string;
+    reason: string;
+}
+
+function main(argv: string[] = process.argv.slice(2)): number {
+    const args = parse_args(argv);
+    const ledger = load_ledger();
+    const markers = scan_markers();
+    const findings: Finding[] = [];
+
+    // 1. Every markered claim must map to a backed, resolvable ledger entry.
+    for (const { id, file } of markers) {
+        const entry = ledger.get(id);
+        if (!entry) {
+            findings.push({ id, file, reason: `no ledger entry in ${LEDGER_REL}` });
+            continue;
+        }
+        if (entry.status !== 'backed') {
+            findings.push({ id, file, reason: `ledger status is '${entry.status || 'missing'}', not 'backed'` });
+            continue;
+        }
+        const un = pointer_unresolved(entry.evidence);
+        if (un) findings.push({ id, file, reason: un });
+    }
+
+    // 2. Rot guard: a backed ledger entry whose pointer no longer resolves
+    //    fails even before it is markered (an implementation must not outlive
+    //    its claim, and vice-versa).
+    for (const entry of ledger.values()) {
+        if (entry.status !== 'backed') continue;
+        const un = pointer_unresolved(entry.evidence);
+        if (un) findings.push({ id: entry.id, file: LEDGER_REL, reason: `backed entry has dangling evidence — ${un}` });
+    }
+
+    if (findings.length > 0) {
+        process.stderr.write(`❌  check_claims: ${findings.length} unbacked/dangling claim(s):\n`);
+        for (const f of findings) {
+            process.stderr.write(`    ${f.file} · claim:${f.id} — ${f.reason}\n`);
+        }
+        process.stderr.write(`    → bind the claim in ${LEDGER_REL} (status: backed + a resolvable evidence pointer), or remove the marker.\n`);
+        return 2;
+    }
+
+    if (!args.quiet) {
+        const backed = [...ledger.values()].filter((e) => e.status === 'backed').length;
+        const unbacked = [...ledger.values()].filter((e) => e.status === 'unbacked').length;
+        process.stdout.write(
+            `✅  check_claims: ${markers.length} markered claim(s) bound · ledger ${ledger.size} entries (${backed} backed, ${unbacked} unbacked inventory)\n`,
+        );
+    }
+    return 0;
+}
+
+/** Robust "am I the entry script?" — realpath-compares argv[1] to this file so
+ *  a symlinked invocation path (macOS /var → /private/var under a tmp tree)
+ *  still resolves. Irrelevant under scripts-run (run.ts calls main directly). */
+function _isCliEntry(): boolean {
+    const a = process.argv[1];
+    if (!a) return false;
+    if (a === _FILE || pathToFileURL(path.resolve(a)).href === import.meta.url) return true;
+    try {
+        return fs.realpathSync(a) === fs.realpathSync(_FILE);
+    } catch {
+        return false;
+    }
+}
+if (_isCliEntry()) {
+    try {
+        process.exit(main());
+    } catch (exc) {
+        if (exc instanceof ExitCode) {
+            process.exit(exc.code);
+        }
+        throw exc;
+    }
+}
+
+export { REPO, LEDGER_REL, main, parse_args, load_ledger, scan_markers, pointer_unresolved, ExitCode };

package/src/scripts/check_comparison.ts

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+/**
+ * B7 — the falsifiability lock for the comparison-honesty table.
+ *
+ * Every `rows[].our_evidence` in `docs/comparison.yaml` must resolve to a real
+ * pointer (file / file#substring / file:line / dated URL) — reusing the
+ * check_claims resolver — and every `checkable: true` row must carry a resolving
+ * `our_evidence`. So the proof page's comparison table can never claim
+ * "checkable ✓" against a pointer that does not exist. Read-only; exit 0 clean /
+ * 1 on any unresolved pointer or malformed row.
+ *
+ * We assert only OUR side. `their_evidence` is prose about the publicly-
+ * observable category (no named source — check_no_external_sources guards that);
+ * we never counter-claim a competitor number, so there is nothing to verify on
+ * their side beyond "it is uncheckable", which is the point.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { parse as parseYaml } from 'yaml';
+
+import { REPO, pointer_unresolved } from './check_claims.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+export const DATA_REL = 'docs/comparison.yaml';
+
+export interface Row {
+    claim: string;
+    our_evidence: string;
+    their_evidence: string;
+    checkable: boolean;
+}
+
+export function loadRows(repo: string = REPO): Row[] {
+    const p = path.join(repo, DATA_REL);
+    if (!fs.existsSync(p)) return [];
+    const data = parseYaml(fs.readFileSync(p, 'utf-8')) as { rows?: Row[] } | null;
+    return Array.isArray(data?.rows) ? (data!.rows as Row[]) : [];
+}
+
+export function findErrors(rows: Row[]): string[] {
+    const errs: string[] = [];
+    rows.forEach((r, i) => {
+        if (typeof r?.claim !== 'string' || !r.claim.trim()) errs.push(`row[${i}]: missing/empty claim`);
+        if (typeof r?.their_evidence !== 'string' || !r.their_evidence.trim()) {
+            errs.push(`row[${i}]: missing/empty their_evidence`);
+        }
+        if (typeof r?.checkable !== 'boolean') errs.push(`row[${i}]: checkable must be a boolean`);
+        if (typeof r?.our_evidence !== 'string' || !r.our_evidence.trim()) {
+            errs.push(`row[${i}]: missing/empty our_evidence`);
+            return;
+        }
+        const bad = pointer_unresolved(r.our_evidence);
+        if (bad !== null) errs.push(`row[${i}] (${r.claim.slice(0, 40)}…): our_evidence ${bad}: ${r.our_evidence}`);
+    });
+    return errs;
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    const quiet = argv.includes('--quiet');
+    const rows = loadRows();
+    const errs = findErrors(rows);
+    if (errs.length > 0) {
+        process.stdout.write('❌ comparison-honesty:\n');
+        for (const e of errs.sort()) process.stdout.write(`  - ${e}\n`);
+        return 1;
+    }
+    if (!quiet) {
+        const checkable = rows.filter((r) => r.checkable).length;
+        process.stdout.write(
+            `✅  comparison-honesty: ${rows.length} row(s), ${checkable} checkable, all our_evidence pointers resolve.\n`,
+        );
+    }
+    return 0;
+}
+
+const _isCli =
+    process.argv[1] !== undefined && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+if (_isCli) process.exit(main());