@event4u/agent-config 16.2.0 → 16.4.0

package/src/scripts/report_module_reach.ts

@@ -0,0 +1,212 @@
+#!/usr/bin/env tsx
+/**
+ * Report — which `_lib` modules does nothing in production call?
+ *
+ * A REPORT, not a gate: it always exits 0. Phase 3 of
+ * `road-to-modules-that-something-calls.md` wires its counts into
+ * `check_gate_reachability`'s own output, reported and not gated, the way
+ * the estate gate already prints its draft-roadmap count.
+ *
+ * ```bash
+ *   report_module_reach                 # human-readable, one line per module
+ *   report_module_reach --markdown      # the four tables, for the evidence page
+ *   report_module_reach --json
+ * ```
+ */
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import * as fs from 'node:fs';
+
+import { analyseModuleReach, groupCounts, type ModuleFact, type ReachGroup } from './_lib/module_reach.js';
+import { assertScanned, reportScanned } from './_lib/scan_scope.js';
+
+const _FILE = fileURLToPath(import.meta.url);
+const REPO = path.resolve(path.dirname(_FILE), '..', '..');
+
+const GROUP_LABEL: Record<ReachGroup, string> = {
+    'contract-test': 'imported by a test under tests/contracts/',
+    'open-or-deferred-step': 'named in an open or deferred step',
+    'named-outside-open-step': 'named in such a roadmap outside any open step',
+    'named-in-none': 'named in no live roadmap',
+};
+
+function humanLine(m: ModuleFact): string {
+    const bits = [
+        `${m.lines}L`,
+        m.namedByProduction ? 'named-by-production' : 'UNREFERENCED',
+        m.reachedByImportOrPath ? 'reached' : 'REACHED-BY-NOTHING',
+        m.hasOwnEntryPoint ? 'has-entry-point' : null,
+        m.registryDeclared.length > 0 ? `registry:[${m.registryDeclared.join(',')}]` : null,
+        m.importingTests.length > 0 ? `tests:${String(m.importingTests.length)}` : 'tests:0',
+        m.group !== null ? `group:${m.group}` : null,
+    ].filter((b): b is string => b !== null);
+    return `  ${m.relPath} — ${bits.join(' · ')}`;
+}
+
+export function human(modules: readonly ModuleFact[]): string {
+    const unreferenced = modules.filter((m) => !m.namedByProduction);
+    const unreached = modules.filter((m) => !m.reachedByImportOrPath);
+    const counts = groupCounts(unreferenced);
+    const lines: string[] = [];
+    lines.push(
+        `module reach: ${String(modules.length)} module(s) under src/scripts/_lib — ` +
+            `${String(unreferenced.length)} unreferenced by name, ${String(unreached.length)} reached by nothing`,
+    );
+    for (const m of modules) lines.push(humanLine(m));
+    lines.push('');
+    lines.push('unreferenced-by-name groups:');
+    for (const g of Object.keys(GROUP_LABEL) as ReachGroup[]) {
+        lines.push(`  ${GROUP_LABEL[g]}: ${String(counts[g])}`);
+    }
+    return lines.join('\n');
+}
+
+function table(modules: readonly ModuleFact[], header: readonly string[], row: (m: ModuleFact) => string[]): string {
+    const lines = [`| ${header.join(' | ')} |`, `|${header.map(() => '---').join('|')}|`];
+    for (const m of modules) lines.push(`| ${row(m).join(' | ')} |`);
+    return lines.join('\n');
+}
+
+export function markdown(modules: readonly ModuleFact[], roadmapsAvailable: boolean): string {
+    const unreferenced = modules.filter((m) => !m.namedByProduction);
+    const unreached = modules.filter((m) => !m.reachedByImportOrPath);
+    const byGroup = (g: ReachGroup): ModuleFact[] => unreferenced.filter((m) => m.group === g);
+
+    const lines: string[] = [];
+    lines.push('<!-- evidence-type: analysis -->');
+    lines.push('# Module reach — 2026-10');
+    lines.push('');
+    lines.push(
+        `Command: \`npx tsx src/scripts/report_module_reach.ts --markdown\`. ` +
+            `${String(modules.length)} module(s) directly under \`src/scripts/_lib/\`, ` +
+            `${String(unreferenced.length)} named in no file outside themselves and their own tests, ` +
+            `${String(unreached.length)} reached by nothing via import edges or run-by-path.`,
+    );
+    lines.push('');
+    if (!roadmapsAvailable) {
+        lines.push('> No `agents/roadmaps/` directory in this checkout — the two roadmap-based groups below are skipped.');
+        lines.push('');
+    }
+
+    lines.push('## Group 1 — imported by a contract test');
+    lines.push('');
+    lines.push(table(byGroup('contract-test'), ['module', 'lines', 'evidence'], (m) => [m.relPath, String(m.lines), m.groupEvidence ?? '']));
+    lines.push('');
+
+    lines.push('## Group 2 — named in an open or deferred step');
+    lines.push('');
+    lines.push(
+        table(byGroup('open-or-deferred-step'), ['module', 'lines', 'evidence'], (m) => [
+            m.relPath,
+            String(m.lines),
+            m.groupEvidence ?? '',
+        ]),
+    );
+    lines.push('');
+
+    lines.push('## Group 3 — named in such a roadmap outside any open step');
+    lines.push('');
+    lines.push(
+        table(byGroup('named-outside-open-step'), ['module', 'lines', 'evidence'], (m) => [
+            m.relPath,
+            String(m.lines),
+            m.groupEvidence ?? '',
+        ]),
+    );
+    lines.push('');
+
+    lines.push('## Group 4 — named in no live roadmap');
+    lines.push('');
+    lines.push(
+        table(byGroup('named-in-none'), ['module', 'lines', 'importing tests'], (m) => [
+            m.relPath,
+            String(m.lines),
+            String(m.importingTests.length),
+        ]),
+    );
+    lines.push('');
+
+    lines.push('## Every module under `_lib` — full facts');
+    lines.push('');
+    lines.push(
+        table(
+            modules,
+            ['module', 'lines', 'importing tests', 'named by production', 'has entry point', 'registry', 'reached'],
+            (m) => [
+                m.relPath,
+                String(m.lines),
+                String(m.importingTests.length),
+                m.namedByProduction ? 'yes' : 'no',
+                m.hasOwnEntryPoint ? 'yes' : 'no',
+                m.registryDeclared.length > 0 ? m.registryDeclared.join(', ') : '—',
+                m.reachedByImportOrPath ? 'yes' : 'no',
+            ],
+        ),
+    );
+    lines.push('');
+
+    // Phase 2.1: one `reading:` line per fourth-group module — never the
+    // whole unreferenced set, which also holds groups 1-3 that Phase 2
+    // explicitly leaves untouched. The content here is a placeholder; the
+    // real verdict (test-carried / helper-never-connected / only-caller-is-
+    // its-own-test) is a judgement call a re-run of this script cannot make,
+    // and is filled in by hand after reading each module and its test.
+    for (const m of byGroup('named-in-none')) {
+        lines.push(`reading: ${m.relPath} — TODO: read the module and its test, then state the verdict`);
+    }
+
+    return lines.join('\n');
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2), root = REPO): number {
+    const { modules, roadmapsAvailable } = analyseModuleReach(root);
+    // One options literal, not three (a second R2 review found it triplicated
+    // across the --json, --markdown and default branches).
+    const scanOpts = {
+        gate: 'report_module_reach',
+        scanned: modules.length,
+        units: 'module(s) under src/scripts/_lib',
+        roots: ['src/scripts/_lib'],
+    };
+    if (argv.includes('--json')) {
+        // No trailing `scanned:` line here — an R2 review found that
+        // `reportScanned` (which PRINTS) made this invalid as a single JSON
+        // document; `check_gate_reachability.ts`'s own `--json` branch already
+        // returns immediately after writing JSON for the same reason. The
+        // scope is still ASSERTED (never silently printed clean from an empty
+        // corpus).
+        assertScanned(scanOpts);
+        process.stdout.write(`${JSON.stringify({ modules, roadmapsAvailable }, null, 2)}\n`);
+    } else if (argv.includes('--markdown')) {
+        // The page is the artifact — no trailing `scanned:` line inside it,
+        // but the scope is still asserted (never silently printed clean from
+        // an empty corpus). The default human mode below is the only one that
+        // still publishes the count per this family's convention.
+        assertScanned(scanOpts);
+        process.stdout.write(`${markdown(modules, roadmapsAvailable)}\n`);
+    } else {
+        // Asserted BEFORE writing, matching the other two branches (an R2
+        // review found the prior "assert after" order here was the one case
+        // that would have printed a human report before a DeadScopeError on
+        // an empty corpus, while --json/--markdown print nothing in that
+        // case) — then printed, since the default mode is the one that still
+        // publishes the count per this family's convention.
+        reportScanned(scanOpts);
+        process.stdout.write(`${human(modules)}\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()) process.exit(main());
+
+export { REPO };

package/src/scripts/report_obligation_mechanism.ts

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+/**
+ * Per rule: is the obligation already carried by a mechanism, and is there a
+ * slot that could carry it?
+ *
+ * Step 1.5 of `road-to-rule-triggers-and-links-that-hold`. It joins three
+ * instruments that already exist and had never been read together:
+ *
+ *   · `check_enforcement_coverage --json` — the only place `enforced_by` and
+ *     `obligation_frequency` are already resolved per rule, including what the
+ *     declaration resolves TO (a wired validator, a bound hook, nothing).
+ *   · `report_obligation_carriers` — how many artifacts restate the same
+ *     obligation, which is a different question from whether one enforces it.
+ *   · `src/config/rule-obligations.json` — the stable obligation ids per rule
+ *     (road-to-enforcement-per-obligation). It replaced the hand-kept
+ *     `# obligation: line N` frontmatter marker this report was the only
+ *     reader of, and whose line numbers had drifted out of the law section on
+ *     half the rules that carried one.
+ *
+ * **Two columns, and conflating them would be the error worth avoiding.**
+ * `carried` is measured: a gate either refuses or it does not.
+ * `slot_exists` is NECESSARY, NEVER SUFFICIENT — it says a host event fires at
+ * the obligation's own frequency, so a carrier could at least be bound. It
+ * does not say the obligation is decidable from what that event sees, which is
+ * the actual question and is not answerable by a join. A rule whose body says
+ * `instruction-only` has usually already answered it in the other direction,
+ * and that answer is reproduced rather than overridden.
+ *
+ * Report only. Moving an obligation out of prose is a per-rule change with its
+ * own review, which this roadmap's scope section says in as many words.
+ */
+import { execFileSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { loadRuleObligations, RULE_OBLIGATIONS_PATH } from './_lib/rule_obligations.js';
+
+// ledger-exempt: a REPORTER, not a gate. Its only non-zero exit says an input
+// instrument could not be run, which is a statement about the walk.
+
+const _HERE = fileURLToPath(import.meta.url);
+
+/** Frequencies a host event is known to fire at — the `slot_exists` test. */
+const EVENT_BOUND_FREQUENCIES: ReadonlySet<string> = new Set([
+    'per-edit',
+    'per-file-write',
+    'per-commit',
+    'per-turn',
+    'per-session',
+    'per-event',
+    'per-task',
+]);
+
+/** Resolutions where something can actually refuse. */
+const REFUSING: ReadonlySet<string> = new Set(['validator', 'validator-local', 'test', 'hook']);
+
+export interface MechanismRow {
+    rule: string;
+    tier: string;
+    /** Obligation ids this rule declares, `null` when it declares none (the kernel). */
+    obligations: number | null;
+    frequency: string;
+    declared: number;
+    effective: string;
+    /** `gate` · `observer` · `declared-gap` · `undeclared`. */
+    carried: string;
+    /** A host event is known to fire at this frequency. Necessary, not sufficient. */
+    slot_exists: boolean;
+    /** Artifacts restating this rule's obligations, per the carrier census. */
+    restatements: number;
+}
+
+function run(root: string, script: string, args: readonly string[]): string {
+    return execFileSync(path.join(root, 'scripts-run'), [script, ...args], {
+        cwd: root,
+        encoding: 'utf8',
+        maxBuffer: 64 * 1024 * 1024,
+        stdio: ['ignore', 'pipe', 'ignore'],
+    });
+}
+
+interface CoverageRule {
+    id: string;
+    tier?: string;
+    declared?: string[];
+    effective?: string;
+    obligation_frequency?: string | null;
+}
+
+export function rows(root: string): MechanismRow[] {
+    const coverage = JSON.parse(run(root, 'src/scripts/check_enforcement_coverage', ['--json'])) as {
+        rules: CoverageRule[];
+    };
+
+    run(root, 'src/scripts/report_obligation_carriers', ['--top', '1']);
+    const carriersPath = path.join(root, 'agents', 'runtime', 'reports', 'obligation-carriers.json');
+    const restatements = new Map<string, number>();
+    if (!fs.existsSync(carriersPath)) {
+        // Not a degradation to absorb: `agents/runtime/` is gitignored, so a
+        // fresh checkout reaches this, and a silent fallback would publish a
+        // uniformly-zero Restatements column with nothing saying it is empty.
+        // Every other input failure in this script exits 1; so does this one.
+        throw new Error(
+            `report_obligation_carriers wrote no census at ${carriersPath} — the ` +
+                'Restatements column would read 0 for every rule without saying so',
+        );
+    }
+    {
+        const census = JSON.parse(fs.readFileSync(carriersPath, 'utf8')) as {
+            rows: { carriers: { path: string; cls: string }[] }[];
+        };
+        for (const r of census.rows) {
+            // A row is one obligation; it counts for every RULE that carries it.
+            for (const c of r.carriers) {
+                if (c.cls !== 'rule') continue;
+                const id = path.basename(c.path, '.md');
+                restatements.set(id, (restatements.get(id) ?? 0) + r.carriers.length - 1);
+            }
+        }
+    }
+
+    const inventory = fs.existsSync(path.join(root, RULE_OBLIGATIONS_PATH))
+        ? loadRuleObligations(root).rules
+        : {};
+    const out: MechanismRow[] = [];
+    for (const r of coverage.rules) {
+        const declared = r.declared ?? [];
+        const effective = r.effective ?? 'none';
+        const frequency = r.obligation_frequency ?? '—';
+
+        let carried: string;
+        if (REFUSING.has(effective)) carried = 'gate';
+        else if (effective === 'observer') carried = 'observer';
+        else if (declared.length > 0) carried = 'declared-gap';
+        else carried = 'undeclared';
+
+        out.push({
+            rule: r.id,
+            tier: r.tier ?? '—',
+            obligations: inventory[r.id]?.obligations.length ?? null,
+            frequency,
+            declared: declared.length,
+            effective,
+            carried,
+            slot_exists: EVENT_BOUND_FREQUENCIES.has(frequency),
+            restatements: restatements.get(r.id) ?? 0,
+        });
+    }
+    out.sort((a, b) => a.rule.localeCompare(b.rule));
+    return out;
+}
+
+export function renderTable(data: readonly MechanismRow[]): string[] {
+    const L: string[] = [];
+    L.push('| Rule | Tier | Obligations | Frequency | `enforced_by` | Resolves to | Carried | Slot exists | Restatements |');
+    L.push('|---|---|---:|---|---:|---|---|---|---:|');
+    for (const r of data) {
+        L.push(
+            `| \`${r.rule}\` | ${r.tier} | ${r.obligations === null ? '—' : String(r.obligations)} | ` +
+                `${r.frequency} | ${String(r.declared)} | \`${r.effective}\` | ${r.carried} | ` +
+                `${r.slot_exists ? 'yes' : 'no'} | ${String(r.restatements)} |`,
+        );
+    }
+    return L;
+}
+
+const USAGE = 'usage: report_obligation_mechanism [--root DIR] [--json | --table]\n';
+
+export function main(): number {
+    const argv = process.argv.slice(2);
+    if (argv.includes('--help') || argv.includes('-h')) {
+        process.stdout.write(USAGE);
+        return 0;
+    }
+    for (const a of argv) {
+        if (a.startsWith('-') && !['--root', '--json', '--table'].includes(a)) {
+            process.stderr.write(`unknown argument: ${a}\n${USAGE}`);
+            return 2;
+        }
+    }
+    const i = argv.indexOf('--root');
+    const root = i >= 0 && i + 1 < argv.length ? (argv[i + 1] as string) : process.cwd();
+
+    let data: MechanismRow[];
+    try {
+        data = rows(root);
+    } catch (e) {
+        process.stderr.write(`could not read an input instrument: ${String(e)}\n`);
+        return 1;
+    }
+
+    if (argv.includes('--json')) {
+        process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+        return 0;
+    }
+    if (argv.includes('--table')) {
+        process.stdout.write(`${renderTable(data).join('\n')}\n`);
+        return 0;
+    }
+
+    const by = (k: string): number => data.filter((r) => r.carried === k).length;
+    const slotNoGate = data.filter((r) => r.carried !== 'gate' && r.slot_exists).length;
+    process.stdout.write(
+        `${String(data.length)} rule(s)\n` +
+            `  carried by a gate that can refuse: ${String(by('gate'))}\n` +
+            `  carried by an observer (fires, never refuses): ${String(by('observer'))}\n` +
+            `  declared gap (the rule says instruction-only / none): ${String(by('declared-gap'))}\n` +
+            `  no enforcement declaration at all: ${String(by('undeclared'))}\n` +
+            `  not gated, but a host event fires at the obligation's frequency: ${String(slotNoGate)}\n` +
+            `  declare no obligation ids: ${String(data.filter((r) => r.obligations === null).length)}\n`,
+    );
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    if (import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) return true;
+    try {
+        return fs.realpathSync(_HERE) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}

package/src/scripts/report_parked_blockers.ts

@@ -0,0 +1,222 @@
+#!/usr/bin/env tsx
+/**
+ * Census of open blockers in parked roadmaps — measures, never gates.
+ *
+ * `lint_roadmap_blockers` and `/roadmap:resolve-blockers` both exclude
+ * the parked directory (`later/`) by a recorded decision ("history rather than
+ * debt"). This report reads exactly that directory so the decision can be
+ * revisited on a number rather than a guess: every `### blocker:` entry whose
+ * `Status:` is not `resolved`, with its file, its raw `Owner:` value and
+ * whether that owner is the owner (maintainer / user / owner — the same set
+ * `lint_roadmap_blockers` treats as a user decision) or a condition an agent
+ * can reach. Separately it lists every blockquote that names an owner
+ * question or owner decision, because such a question is invisible to any
+ * blocker reader even when its directory is in scope.
+ *
+ * The raw `Owner:` value is printed beside its classification: the field is
+ * free text, and a misread must be visible to whoever reads the report.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/report_parked_blockers
+ *   ./scripts-run src/scripts/report_parked_blockers --format json
+ *   ./scripts-run src/scripts/report_parked_blockers --dir <path>
+ *
+ * Exit codes: 0 report emitted · 2 usage error.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { REPO_ROOT, _stripFencedCode } from './lint_roadmap_blockers.js';
+
+type OwnerWait = 'owner' | 'agent';
+
+interface ParkedBlocker {
+    file: string;
+    id: string;
+    status: string;
+    owner: string;
+    wait: OwnerWait;
+}
+
+interface OwnerQuestion {
+    file: string;
+    line: number;
+    text: string;
+    blocker_entries_in_file: number;
+}
+
+interface Census {
+    dir: string;
+    files_scanned: number;
+    files_with_open_blockers: number;
+    blockers: ParkedBlocker[];
+    owner_questions: OwnerQuestion[];
+}
+
+const BLOCKERS_SECTION_RE = /^##[ \t]+Blockers[ \t]*$/im;
+const NEXT_H2_RE = /^##[ \t]+\S/m;
+const BLOCKER_HEADING_RE = /^###[ \t]+blocker:[ \t]*(.+?)[ \t]*$/gim;
+const STATUS_RE = /^-[ \t]*\*\*Status:\*\*[ \t]*(.*)$/im;
+const OWNER_RE = /^-[ \t]*\*\*Owner:\*\*[ \t]*(.*)$/im;
+const OWNER_WAIT_RE = /^(maintainer|user|owner)\b/i;
+const OWNER_QUESTION_RE = /owner[ \t]+(question|decision)/i;
+
+function _classifyOwner(raw: string): OwnerWait {
+    return OWNER_WAIT_RE.test(raw.trim()) ? 'owner' : 'agent';
+}
+
+/** Every blocker entry in one file's `## Blockers` section, open or not. */
+function _blockerEntries(text: string): Array<{ id: string; status: string; owner: string }> {
+    const stripped = _stripFencedCode(text);
+    const sectionMatch = BLOCKERS_SECTION_RE.exec(stripped);
+    if (!sectionMatch) {
+        return [];
+    }
+    const start = sectionMatch.index + sectionMatch[0].length;
+    const rest = stripped.slice(start);
+    const h2 = NEXT_H2_RE.exec(rest);
+    const section = h2 ? rest.slice(0, h2.index) : rest;
+
+    const heads: Array<{ start: number; end: number; id: string }> = [];
+    BLOCKER_HEADING_RE.lastIndex = 0;
+    let hm: RegExpExecArray | null;
+    while ((hm = BLOCKER_HEADING_RE.exec(section)) !== null) {
+        heads.push({ start: hm.index, end: hm.index + hm[0].length, id: (hm[1] as string).trim() });
+        if (hm.index === BLOCKER_HEADING_RE.lastIndex) {
+            BLOCKER_HEADING_RE.lastIndex++;
+        }
+    }
+    return heads.map((cur, i) => {
+        const next = heads[i + 1];
+        const body = section.slice(cur.end, next ? next.start : section.length);
+        return {
+            id: cur.id,
+            status: (STATUS_RE.exec(body)?.[1] ?? '').trim(),
+            owner: (OWNER_RE.exec(body)?.[1] ?? '').trim(),
+        };
+    });
+}
+
+/** Blockquote lines that name an owner question or owner decision. */
+function _ownerQuestionLines(text: string): Array<{ line: number; text: string }> {
+    const out: Array<{ line: number; text: string }> = [];
+    let inFence = false;
+    text.split('\n').forEach((raw, i) => {
+        if (/^[ \t]*```/.test(raw)) {
+            inFence = !inFence;
+            return;
+        }
+        if (!inFence && /^[ \t]*>/.test(raw) && OWNER_QUESTION_RE.test(raw)) {
+            out.push({ line: i + 1, text: raw.trim() });
+        }
+    });
+    return out;
+}
+
+function collect(dir: string, root: string = REPO_ROOT): Census {
+    const files = fs.existsSync(dir)
+        ? fs
+              .readdirSync(dir, { withFileTypes: true })
+              .filter((e) => e.isFile() && e.name.endsWith('.md'))
+              .map((e) => path.join(dir, e.name))
+              .sort()
+        : [];
+    const blockers: ParkedBlocker[] = [];
+    const ownerQuestions: OwnerQuestion[] = [];
+    const filesWithOpen = new Set<string>();
+    for (const abs of files) {
+        const rel = path.relative(root, abs).split(path.sep).join('/');
+        const text = fs.readFileSync(abs, 'utf8');
+        const entries = _blockerEntries(text);
+        for (const e of entries) {
+            if (/^resolved\b/i.test(e.status)) {
+                continue;
+            }
+            filesWithOpen.add(rel);
+            blockers.push({ file: rel, id: e.id, status: e.status, owner: e.owner, wait: _classifyOwner(e.owner) });
+        }
+        for (const q of _ownerQuestionLines(text)) {
+            ownerQuestions.push({ file: rel, line: q.line, text: q.text, blocker_entries_in_file: entries.length });
+        }
+    }
+    return {
+        dir: path.relative(root, dir).split(path.sep).join('/'),
+        files_scanned: files.length,
+        files_with_open_blockers: filesWithOpen.size,
+        blockers,
+        owner_questions: ownerQuestions,
+    };
+}
+
+function format(c: Census): string {
+    const owner = c.blockers.filter((b) => b.wait === 'owner');
+    const agent = c.blockers.filter((b) => b.wait === 'agent');
+    const lines: string[] = [];
+    lines.push(`Parked blockers under ${c.dir}/`);
+    lines.push(
+        `files scanned: ${c.files_scanned} · files with an open blocker: ${c.files_with_open_blockers} · open blockers: ${c.blockers.length} (owner-wait ${owner.length}, agent-wait ${agent.length})`,
+    );
+    for (const [label, group] of [
+        ['owner-wait', owner],
+        ['agent-wait', agent],
+    ] as const) {
+        lines.push('');
+        lines.push(`## ${label} (${group.length})`);
+        for (const b of group) {
+            lines.push(`- ${b.file} · ${b.id} · Owner: ${b.owner || '(none)'} · Status: ${b.status || '(none)'}`);
+        }
+    }
+    lines.push('');
+    lines.push(`## owner questions in blockquotes (${c.owner_questions.length})`);
+    for (const q of c.owner_questions) {
+        lines.push(`- ${q.file}:${q.line} · blocker entries in file: ${q.blocker_entries_in_file} · ${q.text.slice(0, 120)}`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+
+function fail(message: string): never {
+    process.stderr.write(`report_parked_blockers: ${message}\n`);
+    process.exit(2);
+}
+
+function main(argv: string[] = process.argv.slice(2)): number {
+    let fmt: 'text' | 'json' = 'text';
+    let dir = path.join(REPO_ROOT, 'agents', 'roadmaps', 'later');
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === '--format') {
+            const v = argv[i + 1];
+            if (v !== 'text' && v !== 'json') fail(`--format must be 'text' or 'json'`);
+            fmt = v;
+            i += 1;
+        } else if (arg === '--dir') {
+            const v = argv[i + 1];
+            if (v === undefined) fail('--dir requires a value');
+            dir = path.resolve(v);
+            i += 1;
+        } else {
+            fail(`unknown argument: ${arg}`);
+        }
+    }
+    const census = collect(dir);
+    process.stdout.write(fmt === 'json' ? `${JSON.stringify(census, null, 2)}\n` : format(census));
+    return 0;
+}
+
+if (process.argv[1] !== undefined) {
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv1 = fs.realpathSync(path.resolve(process.argv[1]));
+        if (here === argv1) {
+            process.exit(main());
+        }
+    } catch {
+        if (import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+            process.exit(main());
+        }
+    }
+}
+
+export { _classifyOwner, _blockerEntries, _ownerQuestionLines, collect, format, main };
+export type { Census, ParkedBlocker, OwnerQuestion };