@event4u/agent-config 14.8.0 → 14.10.0

package/src/scripts/lint_adr_sweep_routing.ts

@@ -0,0 +1,365 @@
+#!/usr/bin/env tsx
+/**
+ * CI guard: every candidate row in an ADR evidence sweep carries a route AND a
+ * dated follow-up.
+ *
+ * `road-to-evidence-based-adr-governance` 3.4 asks for exactly this, and the
+ * step was once marked `[x]` on the adjudication pass it DID run rather than on
+ * the half its own `verify:` named — "zero candidate rows without both a route
+ * and a dated follow-up; a lint over sweep artifacts red on a dateless
+ * candidate row". Neither the columns nor the lint existed. That is the
+ * "prose lifecycle enforcement is satisfied by its weakest honest reading"
+ * defect the roadmap cites as its third motivating measurement, so the fix is a
+ * gate rather than another sentence.
+ *
+ * WHAT A CANDIDATE IS. A table row whose disposition cell carries `REVIEW-NOW`
+ * or `SUPERSEDE (candidate)` — the two dispositions that assert the record needs
+ * further action. Every other disposition in the vocabulary is terminal for the
+ * sweep (`KEEP`, `HISTORICAL-ONLY`, …) or names its own mechanism, and a
+ * follow-up requirement on those would be noise.
+ *
+ * WHY A DATE AND NOT A PROMISE. The three accepted follow-up forms are a linked
+ * roadmap step, an ADR draft, or an explicit dated defer on the ADR-134 pattern.
+ * All three are checkable only through the date: without one, a lapse is a
+ * silent extension instead of a compliance finding, which is the property the
+ * step was specified to buy.
+ *
+ * HONEST SCOPE. This gate checks that a route and a date are PRESENT and that
+ * the routing section covers every candidate. It cannot check that the route is
+ * the right venue or that the date is met — the first is a judgement and the
+ * second is a calendar. Read a green run as "every candidate is routed and
+ * dated", never as "every follow-up happened".
+ *
+ * Exit codes: 0 = clean, 1 = violations found, 2 = internal error.
+ *
+ * Usage:
+ *     ./scripts-run src/scripts/lint_adr_sweep_routing
+ *     ./scripts-run src/scripts/lint_adr_sweep_routing --json
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { runGateCli, runSelfTest, type SelfTestCase } from './_lib/gate_self_test.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+let SWEEP_DIR = path.join(REPO_ROOT, 'docs', 'decisions');
+
+/** Test seam, mirroring the sibling roadmap lints. */
+export function _setSweepDirForTest(p: string): void {
+    SWEEP_DIR = p;
+}
+
+/** Sweep artifacts: `adr-evidence-sweep-*.md` under docs/decisions/. */
+const SWEEP_NAME = /^adr-evidence-sweep-.*\.md$/;
+
+const CANDIDATE = /REVIEW-NOW|SUPERSEDE \(candidate\)/;
+const ISO_DATE = /\b\d{4}-\d{2}-\d{2}\b/;
+const ROUTING_HEADING = /^##+\s+Candidate routing\b/;
+const NEXT_HEADING = /^##\s+/;
+
+export interface Violation {
+    file: string;
+    line: number;
+    key: string;
+    msg: string;
+}
+
+/**
+ * The record identity a candidate row and its routing row must agree on.
+ *
+ * Sweep tables label the same record four ways — `208`, `ADR-239`,
+ * `ADR-016 installer-architecture`, `docs/adrs/router/0001 three-tier-routing`
+ * — so a literal string match would report every row as unrouted. Normalising
+ * to the numeric identity is what makes the two sections comparable at all.
+ */
+export function recordKey(cell: string): string | null {
+    const text = cell.replace(/[`*[\]]/g, '').trim();
+    const area = /^docs\/adrs\/([a-z-]+)\/0*(\d+)/.exec(text);
+    if (area) return `${area[1]}/${String(Number(area[2]))}`;
+    const numbered = /^(?:ADR-)?0*(\d{1,4})\b/.exec(text);
+    if (numbered) return `adr/${String(Number(numbered[1]))}`;
+    return null;
+}
+
+function cells(line: string): string[] {
+    return line
+        .replace(/^\||\|$/g, '')
+        .split('|')
+        .map((c) => c.trim());
+}
+
+/** Is this a table body row (not a header or a `|---|` separator)? */
+function isBodyRow(line: string): boolean {
+    return line.startsWith('|') && !/^\|[\s:-]+\|/.test(line);
+}
+
+export interface SweepScan {
+    /** key -> first line number the candidate was seen on */
+    candidates: Map<string, number>;
+    /** key -> { route, followUp, line } */
+    routed: Map<string, { route: string; followUp: string; line: number }>;
+    /** true when the artifact has a `## Candidate routing` section at all */
+    hasRoutingSection: boolean;
+}
+
+export function scanSweep(text: string): SweepScan {
+    const lines = text.split('\n');
+    const candidates = new Map<string, number>();
+    const routed = new Map<string, { route: string; followUp: string; line: number }>();
+    let inRouting = false;
+    let hasRoutingSection = false;
+    let inFence = false;
+
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i] as string;
+        if (/^\s*```/.test(line)) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence) continue;
+
+        if (ROUTING_HEADING.test(line)) {
+            inRouting = true;
+            hasRoutingSection = true;
+            continue;
+        }
+        if (inRouting && NEXT_HEADING.test(line) && !ROUTING_HEADING.test(line)) {
+            inRouting = false;
+        }
+        if (!isBodyRow(line)) continue;
+
+        const c = cells(line);
+        const key = recordKey(c[0] ?? '');
+        if (key === null) continue;
+
+        if (inRouting) {
+            // | Record | Disposition | Route | Dated follow-up |
+            routed.set(key, {
+                route: (c[2] ?? '').trim(),
+                followUp: (c[3] ?? '').trim(),
+                line: i + 1,
+            });
+            continue;
+        }
+        if (CANDIDATE.test(line) && !candidates.has(key)) {
+            candidates.set(key, i + 1);
+        }
+    }
+    return { candidates, routed, hasRoutingSection };
+}
+
+export function lintSweep(rel: string, text: string): [Violation[], number] {
+    const { candidates, routed, hasRoutingSection } = scanSweep(text);
+    const out: Violation[] = [];
+    if (candidates.size > 0 && !hasRoutingSection) {
+        out.push({
+            file: rel,
+            line: 1,
+            key: '—',
+            msg:
+                `${candidates.size} candidate row(s) and no \`## Candidate routing\` section. ` +
+                'Every REVIEW-NOW / SUPERSEDE (candidate) row needs a route and a dated follow-up ' +
+                '(road-to-evidence-based-adr-governance 3.4).',
+        });
+        return [out, candidates.size];
+    }
+    for (const [key, line] of [...candidates].sort((a, b) => a[1] - b[1])) {
+        const row = routed.get(key);
+        if (row === undefined) {
+            out.push({
+                file: rel,
+                line,
+                key,
+                msg: `candidate ${key} has no row in \`## Candidate routing\` — unrouted.`,
+            });
+            continue;
+        }
+        if (row.route === '' || row.route === '—') {
+            out.push({ file: rel, line: row.line, key, msg: `candidate ${key} has an empty route cell.` });
+        }
+        if (!ISO_DATE.test(row.followUp)) {
+            out.push({
+                file: rel,
+                line: row.line,
+                key,
+                msg:
+                    `candidate ${key} carries no YYYY-MM-DD in its follow-up cell — a dateless ` +
+                    'follow-up makes a lapse a silent extension rather than a compliance finding.',
+            });
+        }
+    }
+    return [out, candidates.size];
+}
+
+/** Floors for `--self-test`, declared here so a truncation is a visible diff. */
+const SELF_TEST_MIN_CASES = 6;
+const SELF_TEST_MIN_REJECT = 4;
+
+const SCRIPT_REL = 'src/scripts/lint_adr_sweep_routing.ts';
+
+/**
+ * Build a one-artifact sweep in a temp dir and run the REAL CLI against it.
+ *
+ * The candidate table and the routing table are supplied separately because
+ * every rejection this gate can make is a disagreement between the two.
+ */
+function _selfTestFixture(name: string, candidateRows: string, routingSection: string): number {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), `adr-sweep-${name}-`));
+    const docs = path.join(dir, 'docs', 'decisions');
+    fs.mkdirSync(docs, { recursive: true });
+    fs.writeFileSync(
+        path.join(docs, 'adr-evidence-sweep-fixture.md'),
+        `# fixture\n\n## Tranche dispositions\n\n| ADR | Disposition |\n|---|---|\n${candidateRows}\n${routingSection}\n`,
+        'utf8',
+    );
+    return runGateCli(REPO_ROOT, SCRIPT_REL, ['--dir', docs], dir);
+}
+
+const _GOOD_ROUTING =
+    '## Candidate routing\n\n| Record | Disposition | Route | Dated follow-up |\n|---|---|---|---|\n' +
+    '| ADR-016 | REVIEW-NOW | council | disposition by **2026-10-03** |\n';
+
+function selfTest(): number {
+    const cases: SelfTestCase[] = [
+        {
+            name: 'a candidate with a route and a date is accepted',
+            expect: 'accept',
+            run: () => _selfTestFixture('ok', '| ADR-016 | REVIEW-NOW |', _GOOD_ROUTING),
+        },
+        {
+            name: 'a candidate with no routing section at all is refused',
+            expect: 'reject',
+            run: () => _selfTestFixture('nosection', '| ADR-016 | REVIEW-NOW |', ''),
+        },
+        {
+            name: 'a candidate absent from the routing table is refused',
+            expect: 'reject',
+            run: () =>
+                _selfTestFixture(
+                    'unrouted',
+                    '| ADR-016 | REVIEW-NOW |\n| ADR-044 | REVIEW-NOW |',
+                    _GOOD_ROUTING,
+                ),
+        },
+        {
+            name: 'a dateless follow-up is refused',
+            expect: 'reject',
+            run: () =>
+                _selfTestFixture(
+                    'dateless',
+                    '| ADR-016 | REVIEW-NOW |',
+                    '## Candidate routing\n\n| Record | Disposition | Route | Dated follow-up |\n|---|---|---|---|\n' +
+                        '| ADR-016 | REVIEW-NOW | council | disposition soon |\n',
+                ),
+        },
+        {
+            name: 'an empty route cell is refused',
+            expect: 'reject',
+            run: () =>
+                _selfTestFixture(
+                    'noroute',
+                    '| ADR-016 | REVIEW-NOW |',
+                    '## Candidate routing\n\n| Record | Disposition | Route | Dated follow-up |\n|---|---|---|---|\n' +
+                        '| ADR-016 | REVIEW-NOW | — | disposition by **2026-10-03** |\n',
+                ),
+        },
+        {
+            // The label-shape case. Sweep tables spell the same record four
+            // ways, so a literal match would report every row unrouted; this
+            // pins the normalisation rather than trusting it.
+            name: 'a bare number in the sweep matches an ADR-NNN routing row',
+            expect: 'accept',
+            run: () => _selfTestFixture('bare', '| 016 | SUPERSEDE (candidate) |', _GOOD_ROUTING),
+        },
+    ];
+    return runSelfTest({
+        gate: 'lint_adr_sweep_routing',
+        cases,
+        minCases: SELF_TEST_MIN_CASES,
+        minRejectCases: SELF_TEST_MIN_REJECT,
+    });
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    const json = argv.includes('--json');
+    if (argv.includes('-h') || argv.includes('--help')) {
+        process.stdout.write('usage: lint_adr_sweep_routing [-h] [--json] [--dir DIR] [--self-test]\n');
+        return 0;
+    }
+    if (argv.includes('--self-test')) return selfTest();
+    for (let i = 0; i < argv.length; i += 1) {
+        const a = argv[i] as string;
+        if (a === '--json') continue;
+        if (a === '--dir') {
+            const next = argv[i + 1];
+            if (next === undefined) {
+                process.stderr.write('lint_adr_sweep_routing: --dir requires a path\n');
+                return 2;
+            }
+            SWEEP_DIR = path.resolve(next);
+            i += 1;
+            continue;
+        }
+        process.stderr.write(`lint_adr_sweep_routing: unrecognized argument: ${a}\n`);
+        return 2;
+    }
+
+    let names: string[] = [];
+    try {
+        names = fs.readdirSync(SWEEP_DIR).filter((n) => SWEEP_NAME.test(n)).sort();
+    } catch {
+        names = [];
+    }
+
+    const violations: Violation[] = [];
+    let scanned = 0;
+    for (const name of names) {
+        const abs = path.join(SWEEP_DIR, name);
+        const rel = path.relative(REPO_ROOT, abs).split(path.sep).join('/');
+        const [v, n] = lintSweep(rel, fs.readFileSync(abs, 'utf-8'));
+        violations.push(...v);
+        scanned += n;
+    }
+
+    process.stdout.write(`scanned: ${scanned}\n`);
+    try {
+        assertScanned({
+            gate: 'lint_adr_sweep_routing',
+            scanned,
+            units: 'candidate row(s)',
+            roots: ['docs/decisions'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌ ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
+    if (json) {
+        process.stdout.write(`${JSON.stringify({ violations }, null, 2)}\n`);
+    } else {
+        for (const v of violations) {
+            process.stderr.write(`❌ ${v.file}:${v.line}: ${v.msg}\n`);
+        }
+    }
+    if (violations.length > 0) {
+        process.stderr.write(`lint_adr_sweep_routing: ${violations.length} violation(s)\n`);
+        return 1;
+    }
+    process.stdout.write(
+        `✅ lint_adr_sweep_routing: every candidate row across ${names.length} sweep artifact(s) carries a route and a dated follow-up\n`,
+    );
+    return 0;
+}
+
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    process.exit(main());
+}

package/src/scripts/lint_workflow_security.ts

@@ -17,8 +17,17 @@
  *            permissions: write-all;
  *            npm install / npm ci without --ignore-scripts in a
  *            pull_request_target workflow.
- *   MEDIUM — third-party actions pinned by mutable tag instead of full SHA
- *            (first-party actions/* are skipped).
+ *   MEDIUM — actions pinned by mutable tag instead of full SHA;
+ *            an actions/checkout step that keeps its credential.
+ *
+ * The MEDIUM tier's original wording read "third-party actions … (first-party
+ * actions/* are skipped)". Corrected 2026-08-22: the first-party exemption is
+ * GONE (see the removal note below), so the parenthetical documented an
+ * exemption that no longer exists — a false claim in a tracked artefact, which
+ * is the defect class the change that removed it was written to repair. The
+ * TIERS are untouched; only the description of what MEDIUM covers now matches
+ * the code. Re-tiering the locked model is a separate decision, recorded as
+ * unresolved in agents/evidence/analysis/workflow-security-net-degraded-decision.md.
  *
  * Script-injection detection (regex-based) is intentionally deferred — it
  * requires an AST-aware pass to avoid false positives on quoted / escaped
@@ -53,8 +62,23 @@ function _setAllowlistPathForTest(p: string): void {
 // Triggers that expose the repository token to untrusted pull-request context
 const DANGEROUS_TRIGGERS: ReadonlySet<string> = new Set(['pull_request_target', 'workflow_run']);
 
-// First-party action owners — mutable tags on these are acceptable
-const FIRST_PARTY_OWNERS: ReadonlySet<string> = new Set(['actions', 'github']);
+// REMOVED 2026-08-22 (road-to-ci-supply-chain-integrity 1.4). This was
+// `FIRST_PARTY_OWNERS = {'actions', 'github'}` and it exempted first-party
+// owners from the mutable-tag rule. The premise — "mutable tags on these are
+// acceptable" — is the one a supply-chain rule cannot hold: a first-party tag
+// is still a mutable pointer, and `actions/checkout@v7` moving under the repo
+// is the same class of event as any other owner's tag moving.
+//
+// What it cost, measured before removal: 100 of the 112 unpinned references in
+// this tree were first-party, so the gate saw 12 of 112 defects and reported
+// green on the rest. An exemption sized like that is not an exemption, it is
+// the rule being off.
+//
+// The removal ships in the SAME change as the 112 pins, and in that order:
+// pin first, then lift, so the transition is red-then-green inside one
+// reviewable diff. Reverting the pins locally must make this gate exit
+// non-zero — that is the assertion that the gate can still see the defect,
+// which a green-only check cannot make.
 
 type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
 type JsonObject = { [k: string]: JsonValue };
@@ -262,13 +286,33 @@ function _mutable_third_party_actions(doc: JsonObject, _workflow_name: string):
             if (!uses || !uses.includes('@')) {
                 continue;
             }
+            // `actions/checkout` leaves the repository token in the runner's git
+            // config for the rest of the job unless told not to. Measured before
+            // this rule existed: 0 of 50 checkouts in this tree set the flag, so
+            // every job carried a usable credential it did not need.
+            //
+            // `true` is a legitimate answer — two jobs here push — so the rule
+            // asks for the key to be PRESENT, not for a particular value. An
+            // explicit `true` is a reviewable decision; a missing key is an
+            // ambient one, and only the second is a finding.
+            if (uses.slice(0, uses.indexOf('@')).toLowerCase() === 'actions/checkout') {
+                const withObj = _asObject(stepObj['with'] as JsonValue);
+                const hasKey =
+                    withObj !== null &&
+                    Object.prototype.hasOwnProperty.call(withObj, 'persist-credentials');
+                if (!hasKey) {
+                    findings.push({
+                        severity: 'MEDIUM',
+                        rule: 'persist-credentials',
+                        detail:
+                            'actions/checkout without an explicit persist-credentials — ' +
+                            'the repository token stays in the runner git config for the rest of the job',
+                        location: `job:${job_name}/step:${i + 1}`,
+                    });
+                }
+            }
             const at = uses.indexOf('@');
-            const action_ref = uses.slice(0, at);
             const pin = uses.slice(at + 1);
-            const owner = action_ref.includes('/') ? (action_ref.split('/')[0] as string) : action_ref;
-            if (FIRST_PARTY_OWNERS.has(owner.toLowerCase())) {
-                continue;
-            }
             // A full SHA pin is 40 hex chars; anything else is mutable
             if (pin.length === 40 && [...pin.toLowerCase()].every((c) => '0123456789abcdef'.includes(c))) {
                 continue;
@@ -650,7 +694,6 @@ export {
     ALLOWLIST_PATH,
     ALLOWLIST_CAP,
     DANGEROUS_TRIGGERS,
-    FIRST_PARTY_OWNERS,
     _setWorkflowsDirForTest,
     _setAllowlistPathForTest,
     load_allowlist,

package/src/scripts/lint_workflow_security_allowlist.json

@@ -1,20 +1,4 @@
 {
-  "_comment": "Legitimate workflow security findings. Hard-capped at 20 entries (lint_workflow_security.py ALLOWLIST_CAP). Exceeding the cap signals the linter is wrong, not the content — tighten the heuristic, do not grow this list (autonomous-execution allowlist-growth antipattern). Each entry MUST cite why the finding is acceptable in `reason`.",
-  "findings": [
-    {
-      "workflow": "bench-drift.yml",
-      "rule": "mutable-action-tag",
-      "reason": "marocchino/sticky-pull-request-comment@v2 — sticky PR comment for bench drift reporting; no code execution, output-only action. SHA-pinning tracked in road-to-security-hardening P3."
-    },
-    {
-      "workflow": "skill-lint.yml",
-      "rule": "mutable-action-tag",
-      "reason": "marocchino/sticky-pull-request-comment@v2 — sticky PR comment for skill-lint reporting; same rationale as bench-drift.yml. SHA-pinning tracked in road-to-security-hardening P3."
-    },
-    {
-      "workflow": "cloud-release.yml",
-      "rule": "mutable-action-tag",
-      "reason": "softprops/action-gh-release@v2 — creates GitHub releases; runs only on push to main (not on pull_request_target), no untrusted input. SHA-pinning tracked in road-to-security-hardening P3."
-    }
-  ]
+  "_comment": "Legitimate workflow security findings. Hard-capped at 20 entries (lint_workflow_security.py ALLOWLIST_CAP). Exceeding the cap signals the linter is wrong, not the content \u2014 tighten the heuristic, do not grow this list (autonomous-execution allowlist-growth antipattern). Each entry MUST cite why the finding is acceptable in `reason`. EMPTIED 2026-08-22 (road-to-ci-supply-chain-integrity 0.2). It held three mutable-action-tag exemptions for marocchino/sticky-pull-request-comment and softprops/action-gh-release. All three are now pinned to full commit SHAs, so the findings they excused no longer exist and the entries matched nothing \u2014 lint_workflow_security reports \"0 allowlisted\". The roadmap step asked to REPAIR their `reason` text, each of which closed by naming an archived roadmap phase as the tracker for SHA-pinning; that phase is a git-discipline hook and its file mentions pinning nowhere, so the pointer dangled. Deleting a dead exemption is the honest repair \u2014 rewriting the reason on an entry that excuses nothing would have kept the allowlist looking load-bearing. The dangling pointer is also WHY the three survived: each one read as deferred rather than open. The full trace lives in the archived roadmap's completion note.",
+  "findings": []
 }

package/src/scripts/report_envelope_rate.ts

@@ -0,0 +1,166 @@
+#!/usr/bin/env tsx
+/**
+ * Publish `valid_envelope_rate` — three numbers, never one.
+ *
+ * `road-to-subagent-envelope-adoption` step 1.2: a rate with no denominator is
+ * a claim, not a measurement. So every line carries the rate, the window
+ * bounds, the stop count, AND the path it read — because the ledger is
+ * gitignored and machine-local, so a figure with no path is not reproducible
+ * even in principle.
+ *
+ * Named `report_` and not `check_` deliberately: this publishes a number and
+ * gates nothing. `gate_population.matchesGatePattern` classifies on a
+ * `lint|check|audit|skill|verify_` prefix, and a reporting script wearing a gate
+ * prefix would be required to carry a coverage floor it has no business having.
+ *
+ * ## Rows this counts, and rows it refuses
+ *
+ * Only `subagent_stop` rows carrying a POST-SPLIT `envelope_parse` value. The
+ * retired `absent` value collapsed `no_message` and `no_envelope` into one
+ * bucket, so a rate computed across the boundary would mix two vocabularies and
+ * report a number that is not about either. Rows with `absent` are excluded and
+ * counted separately, so the exclusion is visible rather than silent.
+ *
+ * Exit 0 always: a report that fails is a gate, and this is not one.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+const LEDGER_DIR = path.join(REPO_ROOT, 'agents', 'runtime', 'state', 'subagent-ledger');
+
+export interface RateReport {
+    ledger_paths: string[];
+    stops: number;
+    ok: number;
+    rate: number;
+    window_start: string | null;
+    window_end: string | null;
+    by_verdict: Record<string, number>;
+    excluded_absent: number;
+    by_agent_type: Record<string, number>;
+}
+
+export function computeRate(lines: readonly string[], paths: readonly string[]): RateReport {
+    const by: Record<string, number> = {};
+    const types: Record<string, number> = {};
+    let stops = 0;
+    let absent = 0;
+    let start: string | null = null;
+    let end: string | null = null;
+    for (const line of lines) {
+        let r: Record<string, unknown>;
+        try {
+            r = JSON.parse(line) as Record<string, unknown>;
+        } catch {
+            continue;
+        }
+        if (r['event'] !== 'subagent_stop') continue;
+        const verdict = r['envelope_parse'];
+        if (typeof verdict !== 'string') continue;
+        if (verdict === 'absent') {
+            absent += 1;
+            continue;
+        }
+        stops += 1;
+        by[verdict] = (by[verdict] ?? 0) + 1;
+        const at = typeof r['agent_type'] === 'string' ? r['agent_type'] : '(null)';
+        types[at] = (types[at] ?? 0) + 1;
+        const ts = r['ts'];
+        if (typeof ts === 'string') {
+            if (start === null || ts < start) start = ts;
+            if (end === null || ts > end) end = ts;
+        }
+    }
+    const ok = by['ok'] ?? 0;
+    return {
+        ledger_paths: [...paths],
+        stops,
+        ok,
+        // 0/0 is 0, not NaN: an empty ledger has a rate of zero valid envelopes
+        // and a denominator that says so on the same line.
+        rate: stops === 0 ? 0 : ok / stops,
+        window_start: start,
+        window_end: end,
+        by_verdict: by,
+        excluded_absent: absent,
+        by_agent_type: types,
+    };
+}
+
+function readLedger(dir: string): { lines: string[]; paths: string[] } {
+    let names: string[] = [];
+    try {
+        names = fs.readdirSync(dir).filter((n) => n.endsWith('.jsonl')).sort();
+    } catch {
+        return { lines: [], paths: [] };
+    }
+    const lines: string[] = [];
+    const paths: string[] = [];
+    for (const n of names) {
+        const abs = path.join(dir, n);
+        paths.push(path.relative(REPO_ROOT, abs).split(path.sep).join('/'));
+        lines.push(...fs.readFileSync(abs, 'utf-8').split('\n'));
+    }
+    return { lines, paths };
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    // `--dir` so the report is reproducible against a ledger that is not this
+    // checkout's. The ledger is gitignored and machine-local, so without it the
+    // only readable ledger is the one beside the running copy — and a worktree
+    // has none, which would make the figure unobtainable exactly where the work
+    // happens.
+    const i = argv.indexOf('--dir');
+    const dir = i >= 0 && i + 1 < argv.length ? path.resolve(argv[i + 1] as string) : LEDGER_DIR;
+    const { lines, paths } = readLedger(dir);
+    const r = computeRate(lines, paths);
+    if (argv.includes('--json')) {
+        process.stdout.write(`${JSON.stringify(r, null, 2)}\n`);
+        return 0;
+    }
+    if (r.ledger_paths.length === 0) {
+        // Not a failure, and not a rate either. The ledger is gitignored, so a
+        // clean clone has none — reporting 0 % there would be a number about
+        // nothing.
+        process.stdout.write(
+            `valid_envelope_rate: NO LEDGER at ${dir} — ` +
+                'the ledger is gitignored and machine-local, so this is expected in a fresh ' +
+                'clone and is not a measurement of zero.\n',
+        );
+        return 0;
+    }
+    const pct = (r.rate * 100).toFixed(2);
+    process.stdout.write(
+        `valid_envelope_rate: ${pct}% — ${String(r.ok)} ok of ${String(r.stops)} stops, ` +
+            `window ${r.window_start ?? '?'} → ${r.window_end ?? '?'}, ` +
+            `read from ${r.ledger_paths.join(', ')}\n`,
+    );
+    const verdicts = Object.entries(r.by_verdict)
+        .sort((a, b) => b[1] - a[1])
+        .map(([k, v]) => `${k} ${String(v)}`)
+        .join(' · ');
+    process.stdout.write(`    verdicts: ${verdicts}\n`);
+    process.stdout.write(
+        `    excluded (retired \`absent\` vocabulary): ${String(r.excluded_absent)}\n`,
+    );
+    const comp = Object.entries(r.by_agent_type)
+        .sort((a, b) => b[1] - a[1])
+        .map(([k, v]) => `${k} ${String(v)}`)
+        .join(' · ');
+    process.stdout.write(`    agent-type composition: ${comp}\n`);
+    process.stdout.write(
+        '    CAVEAT: machine-local. This ledger is one machine\'s drain traffic, so the\n' +
+            '    composition above is the shape of THIS traffic and the rate does not\n' +
+            '    generalise. Published with the composition rather than alone, so the limit\n' +
+            '    is readable instead of hidden.\n',
+    );
+    return 0;
+}
+
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    process.exit(main());
+}