@event4u/agent-config 15.0.0 → 16.0.0

package/src/scripts/check_finding_dispositions.ts

@@ -103,6 +103,121 @@ export interface Ledger {
     findings: LedgerFinding[];
     /** Why the finding set is empty. Required when it is; see empty_ledger_problem. */
     no_findings_reason?: string;
+    // The six integrity fields, declared rather than swept into an index
+    // signature. An index signature would hold them, and would also disable
+    // excess-property and typo detection on the whole type for every consumer:
+    // under `--strict`, `l.findigs` type-checks against a Ledger carrying one.
+    // The set is known and finite, so it costs six lines to keep the type.
+    review_independence?: string;
+    context_relation?: string;
+    acceptance_status?: string;
+    assurance?: string;
+    reviewers?: string[];
+    coverage?: unknown;
+}
+
+/**
+ * Fields the self-review artifact carries that say how much a ledger's silence
+ * is worth, and which `--ingest` used to drop on the floor.
+ *
+ * `check_review_schema` derives `acceptance_status` and `assurance` from
+ * `review_independence` and fails a ledger whose declarations disagree — so an
+ * ingested ledger missing all three was not merely thinner than a hand-written
+ * one, it could not satisfy the gate that reads it. Every committed ledger from
+ * 14.19.0 onward carries the full set; only the ingest path produced files
+ * without it, which is one of the two reasons nobody could run the ingest and
+ * get a green tree.
+ *
+ * Carried rather than recomputed: the producing run is the only thing that
+ * knows how many reviewers answered and how much of the diff they saw, and a
+ * consumer inferring it from the findings would be inventing the integrity
+ * claim the fields exist to record.
+ */
+export const INTEGRITY_FIELDS = [
+    'review_independence',
+    'context_relation',
+    'acceptance_status',
+    'assurance',
+    'reviewers',
+    'coverage',
+] as const;
+
+/**
+ * Merge a self-review artifact into a ledger: new findings by id, the integrity
+ * fields on first write, and — when the review found nothing — the reason that
+ * makes an empty ledger legible.
+ *
+ * MUTATES AND RETURNS THE SAME OBJECT. Callers must use the returned `ledger`
+ * rather than relying on the mutation; the two are the same reference today and
+ * the signature is what a later reader will trust.
+ *
+ * The integrity fields are written only when the ledger does not already carry
+ * them. A second ingest into a ledger a human has since adjudicated must not
+ * silently restate what the earlier run claimed about independence — the first
+ * producing run is the one whose claim the dispositions were filled against.
+ *
+ * The empty-findings case is the one that used to deadlock a release. A clean
+ * review produces `findings: []`, `empty_ledger_problem` refuses an empty
+ * ledger with no `no_findings_reason`, and the release then stopped demanding
+ * dispositions for zero findings — an instruction nobody can follow. An ingest
+ * knows exactly what a clean review means and writes it, with the coverage
+ * numbers as the checkable part rather than a bare assurance.
+ */
+export function merge_ingest(
+    ledger: Ledger,
+    artifact: Record<string, unknown>,
+): { ledger: Ledger; added: number; carried: string[]; reasoned: boolean } {
+    const known = new Set(ledger.findings.map((f) => f.finding_id));
+    let added = 0;
+    for (const f of (artifact['findings'] as LedgerFinding[] | undefined) ?? []) {
+        if (!known.has(f.finding_id)) {
+            ledger.findings.push(f);
+            added++;
+        }
+    }
+    // Assigned through one `unknown` view rather than per field: the six are a
+    // closed set the type declares, and spelling out six near-identical
+    // if-blocks to satisfy the checker would make the set harder to extend than
+    // the type is to read. The view is local to this loop.
+    const carried: string[] = [];
+    const sink = ledger as unknown as Record<string, unknown>;
+    for (const key of INTEGRITY_FIELDS) {
+        if (sink[key] === undefined && artifact[key] !== undefined) {
+            sink[key] = artifact[key];
+            carried.push(key);
+        }
+    }
+    // Only on an artifact that actually SAYS it found nothing. Without the key
+    // check, any JSON object without a `findings` key reads as an empty finding
+    // set, and the sentence below would assert a review that never happened —
+    // into the permanent record, which is worse than the deadlock it replaces.
+    let reasoned = false;
+    const declaresFindings = Array.isArray(artifact['findings']);
+    if (
+        declaresFindings &&
+        ledger.findings.length === 0 &&
+        (ledger.no_findings_reason ?? '').trim() === ''
+    ) {
+        ledger.no_findings_reason = _clean_review_reason(artifact);
+        reasoned = true;
+    }
+    return { ledger, added, carried, reasoned };
+}
+
+/** The `no_findings_reason` an ingest of a zero-findings artifact writes. */
+function _clean_review_reason(artifact: Record<string, unknown>): string {
+    const cov = artifact['coverage'] as Record<string, unknown> | undefined;
+    const reviewed = cov?.['filesReviewed'];
+    const total = cov?.['filesTotal'];
+    const scope =
+        typeof reviewed === 'number' && typeof total === 'number'
+            ? ` over ${reviewed} of ${total} changed file(s)`
+            : '';
+    return (
+        `The self-review ran and reported no findings${scope}; ingested from its own ` +
+        'artifact by the release, so the empty set is a result rather than an absence. ' +
+        'Check it against the coverage block above and the run that produced it.'
+    );
 }
 
 /** Mirrors self_review_gate.classifyBlocking — security/claim × critical/high. */
@@ -389,32 +504,68 @@ function main(argv: readonly string[]): number {
     const ledgerPath = _ledger_path(dir, release);
 
     if (ingest) {
-        const incoming = parse_ledger(
-            JSON.stringify({
-                schema_version: 1,
-                release,
-                findings: (JSON.parse(fs.readFileSync(ingest, 'utf-8')) as { findings: LedgerFinding[] }).findings,
-            }),
-            ingest,
-        );
+        // Guarded: a truncated or corrupt artifact otherwise exits the child on
+        // an uncaught exception, and the release reports only "command failed"
+        // with no indication that the artifact is the problem.
+        let artifact: Record<string, unknown>;
+        try {
+            artifact = JSON.parse(fs.readFileSync(ingest, 'utf-8')) as Record<string, unknown>;
+        } catch (e) {
+            process.stderr.write(
+                `❌  ${ingest}: not readable as JSON (${e instanceof Error ? e.message : String(e)})\n`,
+            );
+            return 2;
+        }
+        // Run the incoming findings through the parser the committed ledger goes
+        // through, and keep the RESULT rather than discarding it. What that buys
+        // is narrow and worth stating: the parser checks the envelope and that
+        // every entry has a non-empty `finding_id`. It does NOT check severity,
+        // kind or title, so an entry with a bad severity still lands — the
+        // schema gate is what reads those, on the committed file.
+        let incoming: Ledger;
+        try {
+            incoming = parse_ledger(
+                JSON.stringify({
+                    schema_version: 1,
+                    release,
+                    findings: (artifact['findings'] as LedgerFinding[] | undefined) ?? [],
+                }),
+                ingest,
+            );
+        } catch (e) {
+            process.stderr.write(`❌  ${e instanceof Error ? e.message : String(e)}\n`);
+            return 2;
+        }
         let ledger: Ledger = { schema_version: 1, release, findings: [] };
         if (fs.existsSync(ledgerPath)) {
             ledger = parse_ledger(fs.readFileSync(ledgerPath, 'utf-8'), ledgerPath);
         }
-        const known = new Set(ledger.findings.map((f) => f.finding_id));
-        let added = 0;
-        for (const f of incoming.findings) {
-            if (!known.has(f.finding_id)) {
-                ledger.findings.push(f);
-                added++;
-            }
-        }
+        const merged = merge_ingest(ledger, { ...artifact, findings: incoming.findings });
+        ledger = merged.ledger;
+        const { added, carried, reasoned } = merged;
         fs.mkdirSync(path.dirname(ledgerPath), { recursive: true });
         fs.writeFileSync(ledgerPath, JSON.stringify(ledger, null, 2) + '\n');
         process.stdout.write(
             `📥  ingested ${added} new finding(s) into ${path.relative(REPO_ROOT, ledgerPath)} — ` +
                 'fill dispositions before the release validation goes green\n',
         );
+        if (carried.length > 0) {
+            process.stdout.write(`    carried integrity fields: ${carried.join(', ')}\n`);
+        }
+        if (reasoned) {
+            process.stdout.write(
+                '    the review reported nothing — wrote no_findings_reason so the empty ' +
+                    'ledger is a result rather than an absence\n',
+            );
+        }
+        const absent = INTEGRITY_FIELDS.filter((k) => ledger[k] === undefined);
+        if (absent.length > 0) {
+            process.stdout.write(
+                `⚠️   artifact carried no ${absent.join(', ')} — ` +
+                    'check_review_schema derives acceptance_status and assurance from ' +
+                    'review_independence and will red on a ledger that declares neither\n',
+            );
+        }
         return 0;
     }
 

package/src/scripts/check_held_object_arrivals.ts

@@ -0,0 +1,381 @@
+#!/usr/bin/env tsx
+/**
+ * A held object cited as blocking live work carries an arrival count.
+ *
+ * WHAT A HELD OBJECT IS, AND WHAT MAKES ONE VISIBLE
+ * -------------------------------------------------
+ * A stub or a parked roadmap is an argument the estate decided not to run
+ * right now. Every one of them was created by a round that raised its subject.
+ * That first round is the arrival the object already records by existing, so a
+ * held object nobody has raised again owes no counter — there is nothing to
+ * count.
+ *
+ * What changes that is a CITATION: a live roadmap naming the object inside a
+ * blocker, which is the estate saying "this held thing is in the way of work
+ * we are doing now". That is the subject arriving a second time, and from then
+ * on the number is the fact a reader needs. Without it the next round meets a
+ * fresh argument instead of a count, re-derives the same conclusion, and the
+ * recurrence stays invisible — the failure this check exists to notice.
+ *
+ * WHY THE CITER SET IS THE LIVE ESTATE AND NOTHING ELSE
+ * -----------------------------------------------------
+ * Measured before the rule was written, not after. Widening the citers to
+ * every markdown file in the tree fires on 56 of 72 held objects, and widening
+ * only to archived roadmaps and stored review inputs fires on 54 of 66. Both
+ * populations are dominated by records that are historical by construction: an
+ * archived roadmap asserts what was true when it closed, and a stored review
+ * input asserts what a reviewer saw on a scope that no longer exists. Neither
+ * is the estate asking again. A check reading them as live citations reds on
+ * four fifths of its corpus on the day it lands, which is a suppression target
+ * wearing a control's clothes.
+ *
+ * So a citer is an active or parked roadmap, and the citation must sit in that
+ * roadmap's blocker scope rather than anywhere in its prose. Both narrowings
+ * are load-bearing and both were measured.
+ *
+ * ADVISORY BY DEFAULT, AND THE REASON IS RECORDED
+ * -----------------------------------------------
+ * It ships reporting rather than blocking. The false-positive rate over the
+ * live corpus was measured first and is 0 of 4 firings, which would permit
+ * blocking on its own. What forbids it today is that the same reading has the
+ * check red on four live objects the moment it lands, and a gate that arrives
+ * red is a backlog rather than a control. `--enforce` exits non-zero, so the
+ * promotion is a flag rather than an edit, and the condition is written into
+ * the measurement record beside the rate.
+ *
+ * Exit: 0 advisory (always) · with `--enforce`, 1 on any firing · 2 on a
+ * usage error or a dead scope.
+ */
+
+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 } from './_lib/gate_self_test.js';
+import { reportScanned } from './_lib/scan_scope.js';
+
+const _HERE = path.resolve(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+/** Directories whose members are held objects. */
+export const HELD_DIRS = ['agents/roadmaps/stubs', 'agents/roadmaps/later'] as const;
+
+/**
+ * Directories whose roadmaps are live citers.
+ *
+ * The active tree, plus the parked tree because a parked roadmap resumes and
+ * its blockers resume with it. The archived tree is deliberately absent.
+ */
+export const CITER_DIRS = ['agents/roadmaps', 'agents/roadmaps/later'] as const;
+
+/** The line a held object carries once its subject has arrived again. */
+export const ARRIVAL_RE = /^>\s*\*\*Arrivals:\*\*\s*\S/m;
+
+/** A citation of a held object, by file name, inside a citer's prose. */
+const HELD_REF_RE = /(?:stubs|later)\/([a-z0-9][a-z0-9\-.]*\.md)/g;
+
+export interface Finding {
+    /** Repo-relative path of the held object with no counter. */
+    held: string;
+    /** Repo-relative paths of the live citers naming it inside a blocker. */
+    citers: string[];
+}
+
+export interface Result {
+    findings: Finding[];
+    /** Held objects cited inside a live blocker — the population the rate is taken over. */
+    cited: number;
+    /** Held objects found at all, so a collapsed corpus is visible. */
+    held: number;
+    /**
+     * Citer roots that EXIST and could not be read. Neither an empty root nor
+     * an absent one qualifies — both are real estate states. A name here means
+     * the scan could not see where the citations live, and that must never
+     * resolve to "nothing is cited".
+     */
+    deadCiterRoots: string[];
+}
+
+/**
+ * List the markdown directly under `dir`.
+ *
+ * `readable` separates the THREE states an empty list can mean, not two.
+ *
+ * A directory that exists and holds no markdown is a real estate state. So is a
+ * directory that does not exist at all: git cannot track an empty directory, so
+ * "nothing is parked" IS an absent `later/` in a fresh clone. Both are
+ * `readable` — there is nothing to read and that is the answer.
+ *
+ * A directory that exists and cannot be read is the failed measurement, and the
+ * only one that may block. An earlier form of this function collapsed all three
+ * into `[]`, which let a moved citer root report an affirmative clean verdict;
+ * the first repair then over-corrected and folded ABSENT in with unreadable,
+ * turning a fresh clone with nothing parked into a hard exit 2.
+ */
+function listMarkdown(dir: string): { files: string[]; readable: boolean } {
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (e) {
+        const code = (e as NodeJS.ErrnoException).code;
+        // ENOENT/ENOTDIR: nothing is there to read, which is a real state.
+        // Anything else (EACCES, EMFILE, EIO): it is there and we failed.
+        return { files: [], readable: code === 'ENOENT' || code === 'ENOTDIR' };
+    }
+    return {
+        files: entries
+            .filter((e) => e.isFile() && e.name.endsWith('.md'))
+            .map((e) => path.join(dir, e.name))
+            .sort(),
+        readable: true,
+    };
+}
+
+function read(file: string): string {
+    try {
+        return fs.readFileSync(file, 'utf8');
+    } catch {
+        return '';
+    }
+}
+
+/**
+ * Held-object names a citer raises inside its blocker scope.
+ *
+ * Blocker scope opens at a `## Blockers` heading or at any `### blocker:`
+ * heading and closes at the next `## ` heading. A mention in a phase step or a
+ * risk row is the estate referring to the object, not declaring itself blocked
+ * on it, and the two must not read the same.
+ */
+export function blockerCitations(text: string): Set<string> {
+    const out = new Set<string>();
+    let inBlocker = false;
+    let inFence = false;
+    for (const line of text.split('\n')) {
+        // A fenced block is illustration, not structure. Without this the
+        // scanner was fence-blind: a roadmap quoting the blocker shape inside
+        // a code fence opened blocker scope for the rest of its section, and
+        // every held-object mention there counted as a live citation — the
+        // exact discrimination this function exists to make, inverted.
+        if (/^\s*(?:```|~~~)/.test(line)) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence) continue;
+        if (line.startsWith('## ')) inBlocker = line.trim().toLowerCase().startsWith('## blockers');
+        if (line.startsWith('### blocker:')) inBlocker = true;
+        if (!inBlocker) continue;
+        HELD_REF_RE.lastIndex = 0;
+        let m: RegExpExecArray | null;
+        while ((m = HELD_REF_RE.exec(line)) !== null) {
+            const name = m[1];
+            if (name !== undefined) out.add(name);
+        }
+    }
+    return out;
+}
+
+export function scan(root: string): Result {
+    const held = new Map<string, string>();
+    for (const d of HELD_DIRS) {
+        for (const f of listMarkdown(path.join(root, d)).files) held.set(path.basename(f), f);
+    }
+
+    const citerFiles = new Set<string>();
+    const deadCiterRoots: string[] = [];
+    for (const d of CITER_DIRS) {
+        const found = listMarkdown(path.join(root, d));
+        if (!found.readable) deadCiterRoots.push(d);
+        for (const f of found.files) citerFiles.add(f);
+    }
+    // Parked roadmaps are citers AND held objects, so the two sets overlap by
+    // construction. Only SELF-citation is excluded — a file naming itself. A
+    // held object citing a DIFFERENT held object still counts, which is
+    // deliberate and is what the live corpus is made of: all four current
+    // firings have a parked roadmap as the citer. An earlier version of this
+    // comment described a held-cites-held exclusion the code has never
+    // implemented, which would have read the whole firing population as
+    // excluded when auditing the adjudicated rate.
+    const citations = new Map<string, Set<string>>();
+    for (const f of [...citerFiles].sort()) {
+        const self = path.basename(f);
+        for (const name of blockerCitations(read(f))) {
+            if (name === self) continue;
+            if (!held.has(name)) continue;
+            const set = citations.get(name) ?? new Set<string>();
+            set.add(path.relative(root, f));
+            citations.set(name, set);
+        }
+    }
+
+    const findings: Finding[] = [];
+    for (const [name, citers] of [...citations.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+        const file = held.get(name);
+        if (file === undefined) continue;
+        if (ARRIVAL_RE.test(read(file))) continue;
+        findings.push({ held: path.relative(root, file), citers: [...citers].sort() });
+    }
+    return { findings, cited: citations.size, held: held.size, deadCiterRoots };
+}
+
+export function check(root: string, enforce: boolean, write = process.stdout.write.bind(process.stdout)): number {
+    const res = scan(root);
+    // Published before the verdict on every path: a gate that says what it read
+    // only when it passes leaves the coverage census blind exactly when it
+    // matters.
+    reportScanned({
+        gate: 'check_held_object_arrivals',
+        scanned: res.cited,
+        units: 'held object(s) cited inside a live blocker',
+        roots: [...CITER_DIRS],
+        allowEmpty:
+            'EMPTY_VALID: zero held objects cited inside a live blocker is a real and ' +
+            'desirable estate state — nothing is currently blocked on a held argument. Both ' +
+            'the held corpus and every citer root are asserted separately below, so an empty ' +
+            'reading can only mean the estate, never an unread directory.',
+    });
+    if (res.held === 0) {
+        write('❌  no held objects found — the held-object directories are empty or moved.\n');
+        return 2;
+    }
+    // A citer root that EXISTS and cannot be read is a scan that could not see
+    // where the citations live. Reporting that as "nothing is cited" is the
+    // silent-green this gate exists to avoid, so it is a hard 2 on every path
+    // including advisory — the `res.held === 0` guard above does not reach it,
+    // because the held corpus stays readable when only a citer root breaks.
+    // An ABSENT root is not this case and does not reach here: `listMarkdown`
+    // reports ENOENT as readable, because git cannot track an empty directory
+    // and a fresh clone with nothing parked has no `later/` at all.
+    if (res.deadCiterRoots.length > 0) {
+        write(
+            `❌  citer root(s) present but unreadable: ${res.deadCiterRoots.join(', ')}. ` +
+                'This is a failed measurement, not a clean estate.\n',
+        );
+        return 2;
+    }
+    if (res.findings.length === 0) {
+        write(
+            `✅  ${String(res.cited)} held object(s) cited inside a live blocker, all carrying an arrival line ` +
+                `(of ${String(res.held)} held objects).\n`,
+        );
+        return 0;
+    }
+    const label = enforce ? '❌' : '⚠️';
+    write(
+        `${label}  ${String(res.findings.length)} of ${String(res.cited)} held object(s) cited inside a live blocker ` +
+            'carry no arrival line:\n',
+    );
+    for (const f of res.findings) {
+        write(`  · ${f.held}\n`);
+        for (const c of f.citers) write(`      cited by ${c}\n`);
+    }
+    write(
+        '\nEach one is a subject that arrived at least twice — once to create the object, ' +
+            'once in the blocker above. Derive the count with `report_held_object_arrivals ' +
+            '<object> --pattern <subject>` and write the line by hand, with its pattern and ' +
+            'denominator, so the number carries a reason.\n',
+    );
+    if (!enforce) {
+        write('\nAdvisory: exiting 0. `--enforce` turns these into a failure.\n');
+    }
+    return enforce ? 1 : 0;
+}
+
+/**
+ * The check proving it still discriminates.
+ *
+ * The accept cases are the two that a firing-on-everything version would get
+ * wrong: an uncited held object with no counter is a first arrival and owes
+ * nothing, and an object cited outside blocker scope is being referred to
+ * rather than blocked on.
+ */
+function selfTest(): number {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'held-arrivals-selftest-'));
+    const HELD_BODY = '---\ncomplexity: lightweight\n---\n\n# Stub: a held subject\n\nbody\n';
+    const COUNTED_BODY =
+        '---\ncomplexity: lightweight\n---\n\n# Stub: a held subject\n\n' +
+        '> **Arrivals:** 3 — latest `round-b` (2026-01-02); earlier `round-a`.\n\nbody\n';
+
+    const build = (name: string, heldBody: string, citerBody: string): string => {
+        const root = path.join(tmp, name);
+        fs.mkdirSync(path.join(root, 'agents', 'roadmaps', 'stubs'), { recursive: true });
+        fs.mkdirSync(path.join(root, 'agents', 'roadmaps', 'later'), { recursive: true });
+        fs.writeFileSync(path.join(root, 'agents', 'roadmaps', 'stubs', 'road-to-held.md'), heldBody);
+        fs.writeFileSync(path.join(root, 'agents', 'roadmaps', 'road-to-live.md'), citerBody);
+        return root;
+    };
+    const citerWithBlocker =
+        '# Road to live work\n\n## Phase 1\n\n- [ ] 1.1 do a thing\n\n## Blockers\n\n' +
+        '### blocker: the held thing\n- **Status:** open\n- **Blocks:** everything\n' +
+        '- **What to do:** read `stubs/road-to-held.md` and decide.\n';
+    const citerWithoutBlocker =
+        '# Road to live work\n\n## Phase 1\n\n' +
+        '- [ ] 1.1 read `stubs/road-to-held.md` for background, then do a thing\n';
+
+    const run = (root: string, enforce: boolean): number =>
+        runGateCli(
+            REPO_ROOT,
+            'src/scripts/check_held_object_arrivals.ts',
+            enforce ? ['--root', root, '--enforce'] : ['--root', root],
+            root,
+        );
+
+    try {
+        return runSelfTest({
+            gate: 'check_held_object_arrivals',
+            minCases: 5,
+            minRejectCases: 2,
+            cases: [
+                {
+                    name: 'a held object cited inside a blocker with no arrival line is rejected',
+                    expect: 'reject',
+                    run: () => run(build('cited-uncounted', HELD_BODY, citerWithBlocker), true),
+                },
+                {
+                    name: 'an empty held corpus is rejected rather than reported clean',
+                    expect: 'reject',
+                    run: () => {
+                        const root = path.join(tmp, 'dead-scope');
+                        fs.mkdirSync(path.join(root, 'agents', 'roadmaps'), { recursive: true });
+                        return run(root, false);
+                    },
+                },
+                {
+                    name: 'a first-arrival held object with no counter and no citation passes',
+                    expect: 'accept',
+                    run: () => run(build('uncited', HELD_BODY, '# Road to live work\n\n## Phase 1\n\n- [ ] 1.1 x\n'), true),
+                },
+                {
+                    name: 'a held object mentioned outside blocker scope passes',
+                    expect: 'accept',
+                    run: () => run(build('outside-blocker', HELD_BODY, citerWithoutBlocker), true),
+                },
+                {
+                    name: 'a cited held object that carries its arrival line passes',
+                    expect: 'accept',
+                    run: () => run(build('counted', COUNTED_BODY, citerWithBlocker), true),
+                },
+            ],
+        });
+    } finally {
+        fs.rmSync(tmp, { recursive: true, force: true });
+    }
+}
+
+export function main(argv: readonly string[]): number {
+    if (argv.includes('--help') || argv.includes('-h')) {
+        process.stdout.write(
+            'usage: check_held_object_arrivals [--root DIR] [--enforce] [--self-test]\n\n' +
+                '  --enforce   exit 1 on any firing; the default is advisory\n',
+        );
+        return 0;
+    }
+    if (argv.includes('--self-test')) return selfTest();
+    const i = argv.indexOf('--root');
+    return check(i === -1 ? REPO_ROOT : (argv[i + 1] ?? REPO_ROOT), argv.includes('--enforce'));
+}
+
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+    process.exit(main(process.argv.slice(2)));
+}