@event4u/agent-config 16.0.0 → 16.2.0

package/src/scripts/ci_settle.ts

@@ -237,9 +237,30 @@ export function classifyPoll(stdout: string, stderr: string, status: number | nu
         return { kind: 'pending', total: rows.length, done };
     }
     const bad = new Set(['FAILURE', 'TIMED_OUT', 'CANCELLED', 'ACTION_REQUIRED', 'STARTUP_FAILURE']);
-    const failing = rows
-        .filter((r) => bad.has(String(r.conclusion).toUpperCase()))
-        .map((r) => String(r.name ?? '?'));
+    // A concurrency group that supersedes its own earlier run leaves TWO rows
+    // under one name: the superseded one CANCELLED, the one that counts
+    // SUCCESS. The forge reports that check green; this classifier reported the
+    // whole PR red, because CANCELLED sat in `bad` and nothing looked at the
+    // twin. Measured 2026-10-01 on PR #2135 (`lint commit subjects`), where the
+    // false red cost a run a diagnosis it did not owe.
+    //
+    // The reprieve is deliberately the narrowest one that fixes it: CANCELLED
+    // only, and only when a row of the SAME NAME concluded SUCCESS. A genuine
+    // cancellation — a human stopping a run, a timeout killing one — has no
+    // successful twin and stays failing. Widening this to every bad conclusion,
+    // or to CANCELLED unconditionally, would trade a false red for a false
+    // green, which is the worse error in a tool whose output is acted on.
+    const nameOf = (r: (typeof rows)[number]): string => String(r.name ?? '?');
+    const concl = (r: (typeof rows)[number]): string => String(r.conclusion).toUpperCase();
+    const succeeded = new Set(rows.filter((r) => concl(r) === 'SUCCESS').map(nameOf));
+    const failing = [
+        ...new Set(
+            rows
+                .filter((r) => bad.has(concl(r)))
+                .filter((r) => !(concl(r) === 'CANCELLED' && succeeded.has(nameOf(r))))
+                .map(nameOf),
+        ),
+    ];
     return { kind: 'settled', failing, total: rows.length };
 }
 
@@ -293,25 +314,131 @@ function sleepSync(seconds: number): void {
     });
 }
 
-export function main(argv: readonly string[]): number {
-    const positional = argv.filter((a) => !a.startsWith('--'));
-    const pr = positional[0];
-    if (pr === undefined) {
-        process.stderr.write(
-            'usage: ci_settle <pr> [--timeout-min N] [--interval-sec N]\n' +
-                `  default --timeout-min is ${String(FOREGROUND_CEILING_MIN)}, which fits inside one foreground Bash call (600 s cap).\n` +
-                '  a longer wait is a BACKGROUND job, not a bigger number — a foreground call past the cap is killed and reports nothing.\n',
+/** The only flags this waiter honours. Anything else is a caller mistake. */
+const KNOWN_FLAGS = ['--timeout-min', '--interval-sec'] as const;
+
+const USAGE =
+    'usage: ci_settle <pr> [--timeout-min N] [--interval-sec N]\n' +
+    `  default --timeout-min is ${String(FOREGROUND_CEILING_MIN)}, which fits inside one foreground Bash call (600 s cap).\n` +
+    '  a longer wait is a BACKGROUND job, not a bigger number — a foreground call past the cap is killed and reports nothing.\n';
+
+export type ParsedArgs =
+    | { kind: 'ok'; pr: string; timeoutMin: number; intervalSec: number }
+    | { kind: 'usage'; message: string };
+
+/**
+ * Parse argv, REFUSING anything this waiter would not honour.
+ *
+ * Refusal rather than a default is the whole point. The previous parser read
+ * its two knobs with `argv.indexOf(flag)` and filtered positionals on a leading
+ * `--`, so a caller who wrote the near-universal `--timeout 1700` got two
+ * silent substitutions at once: the unknown flag was ignored, and its value —
+ * carrying no dashes — survived as a second positional and was dropped. The
+ * wait then ran for the 9-minute default while the caller believed they had
+ * asked for 28, and the resulting `DID NOT SETTLE` read as a slow CI rather
+ * than as their own typo.
+ *
+ * That is the one failure a waiter must not have. Its entire product is a
+ * verdict somebody will act on, and a verdict produced under arguments the
+ * caller did not actually give is worse than no verdict, because it looks like
+ * one. So every unrecognised flag, every unusable value and every extra
+ * positional is a usage refusal, exit 2 — the code this tool already reserves
+ * for "no verdict is claimed".
+ *
+ * `--flag=value` is accepted beside `--flag value` because it is the other
+ * spelling a caller reaches for, and refusing it would trade one silent
+ * surprise for a noisy one with no safety gained.
+ */
+export function parseArgs(argv: readonly string[]): ParsedArgs {
+    const refuse = (why: string): ParsedArgs => ({ kind: 'usage', message: `ci_settle: ${why}\n${USAGE}` });
+
+    const positional: string[] = [];
+    const given = new Map<string, string>();
+
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] as string;
+        if (!a.startsWith('--')) {
+            positional.push(a);
+            continue;
+        }
+        const eq = a.indexOf('=');
+        const name = eq === -1 ? a : a.slice(0, eq);
+        if (!(KNOWN_FLAGS as readonly string[]).includes(name)) {
+            return refuse(
+                `unknown flag ${name}. This waiter spells its deadline --timeout-min (in MINUTES), not --timeout`,
+            );
+        }
+        if (given.has(name)) return refuse(`${name} given twice`);
+        if (eq !== -1) {
+            given.set(name, a.slice(eq + 1));
+            continue;
+        }
+        const v = argv[i + 1];
+        if (v === undefined || v.startsWith('--')) return refuse(`${name} needs a value`);
+        given.set(name, v);
+        i++;
+    }
+
+    const raw = positional[0];
+    if (raw === undefined) return refuse('no PR number given');
+    if (positional.length > 1) {
+        return refuse(
+            `unexpected argument ${JSON.stringify(positional[1])} — this tool takes exactly one positional, the PR number; ` +
+                'a flag value must follow its own flag',
         );
-        return 2;
     }
-    const num = (flag: string, dflt: number): number => {
-        const i = argv.indexOf(flag);
-        if (i === -1) return dflt;
-        const v = argv[i + 1];
-        const n = v === undefined ? NaN : parseInt(v, 10);
-        return Number.isFinite(n) && n > 0 ? n : dflt;
+
+    // Finding 1 of the 2026-10-01 R2 review: the first version of this guard
+    // validated every OPTIONAL argument and waved the mandatory one through, so
+    // the failure it exists to remove stayed reachable through the front door.
+    // `ci_settle PR-2130` parsed as ok; `gh pr view PR-2130` then exits non-zero
+    // on every poll, each one classifies as unreadable, no streak caps the loop,
+    // and the run spends its entire budget to arrive at `DID NOT SETTLE` — which
+    // is read as a slow CI rather than as the typo it is. A guard that refuses
+    // the arguments a caller may omit and accepts the one they cannot is not a
+    // guard. `#123` and a PR URL are admitted because both are what a caller
+    // copies out of the forge; a branch name is NOT, because this tool's whole
+    // verdict is bound to one head and a branch makes that binding ambiguous.
+    const pr = /^#?[0-9]+$/.test(raw)
+        ? raw.replace(/^#/, '')
+        : (/^https?:\/\/[^\s]*\/pull\/([0-9]+)(?:[/?#].*)?$/.exec(raw)?.[1] ?? null);
+    if (pr === null || pr === '0' || /^0+$/.test(pr)) {
+        return refuse(
+            `${JSON.stringify(raw)} is not a PR number — give the number itself (2130), #2130, or the pull-request URL`,
+        );
+    }
+
+    const num = (flag: string, dflt: number): number | string => {
+        const v = given.get(flag);
+        if (v === undefined) return dflt;
+        const unit = flag === '--timeout-min' ? 'minutes' : 'seconds';
+        if (!/^[0-9]+$/.test(v)) return `${flag} wants a whole number of ${unit}, got ${JSON.stringify(v)}`;
+        const n = parseInt(v, 10);
+        // Finding 2: the parser this replaced guarded with `Number.isFinite`, and
+        // the digits-only test that replaced it does not. A long enough run of
+        // digits parses to Infinity, clears `n > 0`, and makes `deadline`
+        // unreachable — an unbounded wait in a tool whose contract is that it
+        // always returns a stated verdict or a stated non-verdict.
+        if (!Number.isFinite(n)) return `${flag} is too large to be a number of ${unit}`;
+        if (n <= 0) return `${flag} wants a positive number, got ${v}`;
+        return n;
     };
+
     const timeoutMin = num('--timeout-min', FOREGROUND_CEILING_MIN);
+    if (typeof timeoutMin === 'string') return refuse(timeoutMin);
+    const intervalSec = num('--interval-sec', 60);
+    if (typeof intervalSec === 'string') return refuse(intervalSec);
+
+    return { kind: 'ok', pr, timeoutMin, intervalSec };
+}
+
+export function main(argv: readonly string[]): number {
+    const parsed = parseArgs(argv);
+    if (parsed.kind === 'usage') {
+        process.stderr.write(parsed.message);
+        return 2;
+    }
+    const { pr, timeoutMin, intervalSec } = parsed;
     if (timeoutMin > FOREGROUND_CEILING_MIN) {
         // Said once, up front, rather than discovered when the call is killed:
         // a truncated wait produces no line at all, so the warning has to come
@@ -322,7 +449,6 @@ export function main(argv: readonly string[]): number {
                 'the deadline and will report nothing — run it as a background job for a wait this long.\n',
         );
     }
-    const intervalSec = num('--interval-sec', 60);
 
     // Up front, because waiting nine minutes to learn the PR was merged before
     // the wait began is the expensive way to find out.

package/src/scripts/closure_scan.ts

@@ -0,0 +1,447 @@
+#!/usr/bin/env tsx
+/**
+ * The closure detector — finds the open decisions in a plan, and classifies
+ * each one by OWNERSHIP. It never resolves one.
+ *
+ * That boundary is the whole design. A decision dispatcher was killed on
+ * purpose: no TypeScript path routes a decision, and this script adds none.
+ * What it adds is the half that can be mechanical — *which questions are open,
+ * and whose they are* — so the claim "this plan reached execution with twelve
+ * open technical decisions and asked the owner none of them" is falsifiable
+ * rather than a feeling.
+ *
+ * Detector families, each a phrase an author writes when they KNOW something
+ * is open. Deliberately narrow: a detector that fires on ordinary plan prose
+ * turns every producer red at once, and the cheapest repair is then to weaken
+ * it until it finds nothing.
+ *
+ *   `tbd`                      TBD / to be decided / decide later
+ *   `unpicked-alternative`     "either X or Y", "option A … option B"
+ *   `unchecked-assumption`     "assuming", "presumably", "probably fine"
+ *   `missing-verify`           an open step with no `verify:` line
+ *   `unfalsifiable-verify`     a step WITH a `verify:` line whose oracle
+ *                              cannot say no
+ *   `ambiguous-acceptance`     a vague acceptance criterion (improve / clean up
+ *                              / best practices / handle errors properly)
+ *   `contradictory`            "contradicts", "conflicts with", "but also"
+ *   `product-semantics`        two valid user-visible outcomes
+ *   `typed-op`                 an operation from the typed vocabulary
+ *   `spend`                    a ceiling or quota question
+ *
+ * Ownership classification is the output that matters. Six families classify
+ * to a technical class the agent, an independent session, a council or a team
+ * resolves; exactly two reach the owner (`product-semantics` → `product-owned`,
+ * `typed-op` → `destructive-owned`); `spend` reaches nobody — it pauses and
+ * reports (ADR-268 § 8).
+ *
+ * Exit codes: 0 no open decisions · 1 open decisions found · 2 bad argv.
+ * Finding open decisions is the POINT, so `--strict` is what makes exit 1 a
+ * failure for a caller that wants one; the default is a report.
+ *
+ * ONE FAMILY IS A LISTING AND NEVER A GATE. `unfalsifiable-verify` exits 0
+ * unconditionally — under `--strict` too — and that is a property of the
+ * family, not a flag a caller can flip. The reason is the one this script's
+ * own header already records about a detector that fires on ordinary prose,
+ * sharpened by a measurement: on 2026-09-29 the active roadmap tree carried
+ * 230 clauses and 6 machine-decidable expectations — 97.4% of them state no
+ * oracle — so a family promoted to a gate would red all but a handful of
+ * roadmaps at once, and the cheapest repair for a gate that reds on
+ * everything is to weaken it until it finds nothing. The exemption is
+ * narrow: a `tbd` in the same corpus still goes red under `--strict`.
+ *
+ * The figure is the MEASURED one, not the commissioning roadmap's. That
+ * roadmap asserted zero expectations tree-wide; a reading refuted it — six
+ * exist, all six written before the grammar was legal, and three of them are
+ * that roadmap's own verify lines. The producing
+ * command is `./scripts-run src/scripts/roadmap_verify_share`, so the number
+ * above is re-derivable rather than remembered.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+import { parseVerifyClause, type VerifyClause } from './_lib/verify_clause.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const _PROG = 'closure_scan';
+
+export type Kind =
+    | 'tbd'
+    | 'unpicked-alternative'
+    | 'unchecked-assumption'
+    | 'missing-verify'
+    | 'unfalsifiable-verify'
+    | 'ambiguous-acceptance'
+    | 'contradictory'
+    | 'product-semantics'
+    | 'typed-op'
+    | 'spend';
+
+export interface Finding {
+    readonly id: string;
+    readonly line: number;
+    readonly kind: Kind;
+    readonly ownership: string;
+    readonly excerpt: string;
+}
+
+/**
+ * Kind → ownership class. The two owner-routed rows are the whole cost of
+ * closure: everything else is resolved without reaching a person, which is
+ * what "zero owner questions for twelve technical ambiguities" means.
+ */
+export const OWNERSHIP_BY_KIND: Readonly<Record<Kind, string>> = {
+    tbd: 'contested-technical',
+    'unpicked-alternative': 'contested-technical',
+    'unchecked-assumption': 'reversible-technical',
+    'missing-verify': 'deterministic',
+    'unfalsifiable-verify': 'deterministic',
+    'ambiguous-acceptance': 'reversible-technical',
+    contradictory: 'contested-technical',
+    'product-semantics': 'product-owned',
+    'typed-op': 'destructive-owned',
+    spend: 'spend-exhaustion',
+};
+
+/** Classes that reach a person. Everything else closes without an ask. */
+export const OWNER_ROUTED: ReadonlySet<string> = new Set([
+    'product-owned',
+    'business-owned',
+    'destructive-owned',
+]);
+
+/**
+ * Families that report and never gate — `--strict` cannot make these exit 1.
+ *
+ * A set rather than a flag, so the exemption is a property of the family that a
+ * caller cannot accidentally promote. See the header for the measurement that
+ * makes promotion a bad trade today.
+ */
+export const NON_BLOCKING_KINDS: ReadonlySet<Kind> = new Set<Kind>(['unfalsifiable-verify']);
+
+/**
+ * Command heads whose exit status is decided by something other than the
+ * property a step is claiming.
+ *
+ * Deliberately short. `echo`, `true` and `printf` cannot fail at all; `cat`,
+ * `ls`, `pwd` and `date` fail only on a missing path or a broken clock, never
+ * on the CONTENT a step asserts. Anything whose exit code already tracks the
+ * claim — `grep` (1 on no match), a linter, a test runner — is absent on
+ * purpose: including it would turn this listing into a census of every verify
+ * line in the tree, which is step 2.2's instrument, not this one.
+ */
+const FIXED_OUTPUT_HEADS: ReadonlySet<string> = new Set(['echo', 'true', 'printf', 'cat', 'ls', 'pwd', 'date']);
+
+/**
+ * Why this clause's oracle cannot say no — or `null` when it can.
+ *
+ * Three shapes, each one a way of carrying a `verify:` line that reads as
+ * verification and decides nothing.
+ *
+ * THE COUNT IS A LOWER BOUND, and saying so is the point. `scan()` assigns at
+ * most one kind per unit and the line patterns run first, so a step that also
+ * says "assuming", "merge" or "deploy" is claimed by the broader family and
+ * never reaches this one. Measured on 2026-09-29: 12 of 50 candidates were
+ * shadowed that way, so the published listing under-reports by roughly a
+ * quarter. A reader told a number and not told it is a floor would read the
+ * remainder as clean, which is the same mistake as reporting a share off a
+ * corpus nobody scanned.
+ */
+export function unfalsifiableReason(clause: VerifyClause): string | null {
+    if (clause.command === null) {
+        // A MANUAL clause asserting a QUANTITY nothing produced. Narrowed to a
+        // multi-digit number or an explicit `N of`/`N%` shape: a lone digit is
+        // usually a step id or an exit code being discussed, and firing on
+        // those would bury the real ones.
+        const quantity = /\b\d{2,}\b/.test(clause.raw) || /\b\d+\s*(?:%|of\b)/.test(clause.raw);
+        return quantity ? 'a manual clause asserts a quantity nothing here produces' : null;
+    }
+
+    const head = (clause.command.trim().split(/\s+/)[0] ?? '').split('/').pop() ?? '';
+    if (FIXED_OUTPUT_HEADS.has(head) && clause.expect?.kind !== 'regex') {
+        // A regex expectation rescues a fixed-output head: `cat f -> /x/` does
+        // decide something. An exit expectation does not — naming exit 0 on a
+        // command that cannot exit anything else adds a symbol, not an oracle.
+        return `the command head \`${head}\` produces a fixed result, so the clause cannot fail`;
+    }
+
+    if (clause.expect?.kind === 'regex') {
+        try {
+            if (new RegExp(clause.expect.source).test(clause.command)) {
+                return 'the expectation matches the command text, so an echo of the command satisfies it';
+            }
+        } catch {
+            // An expectation that cannot compile never became one upstream.
+        }
+    }
+    return null;
+}
+
+interface Pattern {
+    readonly kind: Kind;
+    readonly re: RegExp;
+}
+
+const LINE_PATTERNS: readonly Pattern[] = [
+    { kind: 'tbd', re: /\bTBD\b/ },
+    { kind: 'tbd', re: /\bto be decided\b/i },
+    { kind: 'tbd', re: /\bdecide later\b/i },
+    { kind: 'unpicked-alternative', re: /\beither\b[^.]{3,80}\bor\b/i },
+    { kind: 'unpicked-alternative', re: /\boption A\b[^.]{0,120}\boption B\b/i },
+    { kind: 'unpicked-alternative', re: /\bwe could (?:either )?\w+[^.]{0,80}\bor\b/i },
+    // "two equal technical strategies" is the canonical unpicked alternative,
+    // and the phrasing an author reaches for when the choice is genuinely open
+    // — it carries no `either`, no `or` and no `option A`.
+    { kind: 'unpicked-alternative', re: /\btwo (?:equal|competing)\b[^.]{0,60}\b(?:strateg|approach|design|option)/i },
+    { kind: 'unchecked-assumption', re: /\bassuming\b/i },
+    { kind: 'unchecked-assumption', re: /\bpresumably\b/i },
+    { kind: 'unchecked-assumption', re: /\bprobably (?:fine|works|ok)\b/i },
+    { kind: 'ambiguous-acceptance', re: /\b(?:improve|optimi[sz]e)\b(?![^.]*\bby\b)/i },
+    { kind: 'ambiguous-acceptance', re: /\bmake it (?:better|cleaner|nicer)\b/i },
+    { kind: 'ambiguous-acceptance', re: /\buse best practices\b/i },
+    { kind: 'ambiguous-acceptance', re: /\bhandle errors properly\b/i },
+    { kind: 'contradictory', re: /\bcontradicts\b/i },
+    { kind: 'contradictory', re: /\bconflicts with\b/i },
+    { kind: 'product-semantics', re: /\buser-visible\b[^.]{0,80}\b(?:or|versus|vs\.?)\b/i },
+    { kind: 'product-semantics', re: /\bwhat the user sees\b/i },
+    { kind: 'product-semantics', re: /\btwo valid (?:user|product) semantics\b/i },
+    { kind: 'typed-op', re: /\b(?:merge|force-push|deploy|publish|purchase|rotate the secret)\b/i },
+    { kind: 'spend', re: /\b(?:over|above|crosses?) the (?:configured )?(?:spend )?ceiling\b/i },
+    { kind: 'spend', re: /\bquota (?:is )?(?:exhausted|gone)\b/i },
+];
+
+const STEP_RE = /^\s*-\s\[[ x~-]\]\s/;
+const OPEN_STEP_RE = /^\s*-\s\[ \]\s/;
+const H2_RE = /^##\s+/;
+const DISCHARGE_H2_RE = /^##\s+(Decisions|Blockers|Kill register|Risk Register)\s*$/;
+const ACCEPTANCE_H2_RE = /^##\s+Acceptance Criteria\s*$/;
+
+function _isFence(line: string): boolean {
+    return /^\s*(```|~~~)/.test(line);
+}
+
+/**
+ * A scan unit: one logical statement, which is NOT one physical line.
+ *
+ * A roadmap step wraps over several lines, and the ambiguity it carries
+ * routinely straddles the wrap ("either newline-delimited JSON / or a single
+ * array"). Matching per line missed exactly those, which are the ones an
+ * author is least likely to notice. A step block is therefore ONE unit, joined
+ * and matched once — which also means one finding per step at most, so a step
+ * carrying two hedges is one open decision rather than two.
+ */
+export interface Unit {
+    /** 1-based line of the unit's first line. */
+    readonly line: number;
+    readonly text: string;
+    /**
+     * The same block with its NEWLINES intact.
+     *
+     * `text` is joined with spaces so a wrapped pattern still matches across
+     * the wrap, and that is right for the line patterns. It is wrong for the
+     * `verify:` clause: with no newline left, "to end of line" means "to end of
+     * the step", so a manual clause inherited every digit in the evidence block
+     * written under it. Measured before this field existed: 46 of 50
+     * `unfalsifiable-verify` hits fired on a quantity the clause never wrote.
+     */
+    readonly blockText: string;
+    readonly inAcceptance: boolean;
+    readonly isOpenStep: boolean;
+    readonly hasVerify: boolean;
+}
+
+export function units(lines: readonly string[]): Unit[] {
+    const out: Unit[] = [];
+    let inFence = false;
+    let inDischarge = false;
+    let inAcceptance = false;
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i] as string;
+        if (_isFence(line)) {
+            inFence = !inFence;
+            i += 1;
+            continue;
+        }
+        if (inFence) {
+            i += 1;
+            continue;
+        }
+        if (H2_RE.test(line)) {
+            inDischarge = DISCHARGE_H2_RE.test(line);
+            inAcceptance = ACCEPTANCE_H2_RE.test(line);
+        }
+        if (inDischarge) {
+            i += 1;
+            continue;
+        }
+        if (STEP_RE.test(line)) {
+            let j = i + 1;
+            while (j < lines.length && !STEP_RE.test(lines[j] as string) && !H2_RE.test(lines[j] as string)) {
+                j += 1;
+            }
+            const block = lines.slice(i, j);
+            out.push({
+                line: i + 1,
+                // Whitespace-normalised: a wrapped step joined with a single
+                // space still carries the next line's indent, so a pattern
+                // written with single spaces stops matching across the wrap —
+                // which is the case this unit exists to catch.
+                text: block.join(' ').replace(/\s+/g, ' '),
+                blockText: block.join('\n'),
+                inAcceptance,
+                isOpenStep: OPEN_STEP_RE.test(line),
+                hasVerify: /(?:^|\s)verify:/m.test(block.join('\n')),
+            });
+            i = j;
+            continue;
+        }
+        out.push({
+            line: i + 1,
+            text: line,
+            blockText: line,
+            inAcceptance,
+            isOpenStep: false,
+            hasVerify: false,
+        });
+        i += 1;
+    }
+    return out;
+}
+
+export function scan(text: string): Finding[] {
+    const lines = text.split('\n');
+    const findings: Finding[] = [];
+
+    for (const u of units(lines)) {
+        if (/<!--\s*closure:\s*ignore\s*-->/.test(u.text)) continue;
+        let matched: Kind | null = null;
+        for (const { kind, re } of LINE_PATTERNS) {
+            if (re.test(u.text)) {
+                matched = kind;
+                break;
+            }
+        }
+        // An open step carries a `verify:` line — a step whose success cannot
+        // be checked is a trigger for a question, not for work. Acceptance
+        // criteria are criteria, not steps: they have their own contract and
+        // carry no verify line by design.
+        if (matched === null && u.isOpenStep && !u.hasVerify && !u.inAcceptance) {
+            matched = 'missing-verify';
+        }
+        // A step that HAS a verify line, whose oracle still cannot say no.
+        // Checked on closed steps too — a `[x]` flipped on a command that
+        // could not fail is the defect in its completed form, and restricting
+        // this to open steps would hide every instance that already landed.
+        if (matched === null && u.hasVerify && !u.inAcceptance) {
+            const clause = parseVerifyClause(u.blockText);
+            if (clause !== null && unfalsifiableReason(clause) !== null) matched = 'unfalsifiable-verify';
+        }
+        if (matched === null) continue;
+        findings.push({
+            id: '',
+            line: u.line,
+            kind: matched,
+            ownership: OWNERSHIP_BY_KIND[matched],
+            excerpt: u.text.trim().replace(/\s+/g, ' ').slice(0, 120),
+        });
+    }
+
+    findings.sort((a, b) => a.line - b.line);
+    return findings.map((f, idx) => ({ ...f, id: `C${String(idx + 1)}` }));
+}
+
+/** The `## Decisions` skeleton — one row per finding, resolution left open. */
+export function renderRows(findings: readonly Finding[]): string {
+    const header = '| ID | ownership | resolved by | decision | evidence | revisit if |';
+    const sep = '|---|---|---|---|---|---|';
+    const rows = findings.map(
+        (f) => `| ${f.id} | ${f.ownership} | <resolver> | <decision> | ${f.kind}:${String(f.line)} | <condition> |`,
+    );
+    return [header, sep, ...rows].join('\n');
+}
+
+export function ownerQuestionCount(findings: readonly Finding[]): number {
+    return findings.filter((f) => OWNER_ROUTED.has(f.ownership)).length;
+}
+
+// --------------------------------------------------------------------------
+// CLI.
+// --------------------------------------------------------------------------
+
+function _usage(): string {
+    return (
+        `usage: ${_PROG} [-h] [--json] [--rows] [--strict] <roadmap.md>\n\n` +
+        `Find and classify the open decisions in a plan. Resolves nothing.\n`
+    );
+}
+
+export function main(argv?: readonly string[]): number {
+    const args = argv ?? process.argv.slice(2);
+    let json = false;
+    let rows = false;
+    let strict = false;
+    const paths: string[] = [];
+    for (const a of args) {
+        if (a === '-h' || a === '--help') {
+            process.stdout.write(_usage());
+            return 0;
+        } else if (a === '--json') json = true;
+        else if (a === '--rows') rows = true;
+        else if (a === '--strict') strict = true;
+        else if (a.startsWith('-')) {
+            process.stderr.write(`${_usage()}${_PROG}: error: unrecognized arguments: ${a}\n`);
+            return 2;
+        } else paths.push(a);
+    }
+    if (paths.length !== 1) {
+        process.stderr.write(`${_usage()}${_PROG}: error: exactly one roadmap path is required\n`);
+        return 2;
+    }
+    const target = path.resolve(paths[0] as string);
+    let text: string;
+    try {
+        text = fs.readFileSync(target, 'utf-8');
+    } catch {
+        process.stderr.write(`${_PROG}: error: cannot read ${paths[0] as string}\n`);
+        return 2;
+    }
+
+    const findings = scan(text);
+    const owner = ownerQuestionCount(findings);
+
+    if (json) {
+        process.stdout.write(
+            JSON.stringify({ findings, open: findings.length, owner_questions: owner }, null, 2) + '\n',
+        );
+    } else if (rows) {
+        process.stdout.write(renderRows(findings) + '\n');
+    } else {
+        process.stdout.write(`open decisions: ${String(findings.length)}\n`);
+        process.stdout.write(`owner questions: ${String(owner)}\n`);
+        for (const f of findings) {
+            process.stdout.write(
+                `  ${f.id}  ${String(f.line).padStart(4)}  ${f.kind.padEnd(20)} ${f.ownership.padEnd(22)} ${f.excerpt}\n`,
+            );
+        }
+    }
+    if (!findings.length) return 0;
+    // `--strict` goes red on the families that gate, never on the listing.
+    const blocking = findings.filter((f) => !NON_BLOCKING_KINDS.has(f.kind));
+    return strict && blocking.length > 0 ? 1 : 0;
+}
+
+function _isCliEntry(): boolean {
+    if (!process.argv[1]) return false;
+    try {
+        return fs.realpathSync(_HERE) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    process.exitCode = main();
+}