@event4u/agent-config 16.3.0 → 16.4.0

package/src/scripts/report_installed_rule_links.ts

@@ -29,10 +29,12 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import {
     type LinkAuditReport,
+    auditInstalledKindLinks,
     auditInstalledRuleLinks,
     deployPlanFrom,
     rewriteOptionCost,
 } from '../install/installedRuleLinks.js';
+import { loadBaselines } from './_lib/gate_baseline.js';
 import { GLOBAL_DEPLOY_SOURCES } from './install.js';
 
 // ledger-exempt: a REPORTER, not a gate. It has no verdict for a per-target
@@ -73,6 +75,89 @@ export function readings(packageRoot: string, prefixChars: number): HostLinkRead
     return out;
 }
 
+/** Installed artefact kinds `--kinds` can select, in print order. */
+export const LINK_KINDS = ['rules', 'skills', 'commands', 'contexts', 'guidelines'] as const;
+export type LinkKind = (typeof LINK_KINDS)[number];
+
+export interface KindLinkReading {
+    kind: LinkKind | 'non-projected';
+    /** False when the host's plan does not deploy this kind at all. */
+    installed: boolean;
+    links: number;
+    unresolved: number;
+}
+
+/**
+ * One reading per selected kind for one host, plus a final `non-projected` row.
+ *
+ * A link into `docs/` (the ADRs live there) is dead in every install by
+ * construction, so it is taken OUT of its kind's deployable count and summed
+ * into its own row instead — mixing it in would make a kind's number move for a
+ * reason no deploy change can address.
+ */
+export function kindReadings(
+    packageRoot: string,
+    pairs: ReadonlyArray<readonly [string, string]>,
+    kinds: ReadonlyArray<LinkKind>,
+): KindLinkReading[] {
+    const plan = deployPlanFrom(pairs);
+    const out: KindLinkReading[] = [];
+    let npLinks = 0;
+    let npUnresolved = 0;
+    for (const kind of kinds) {
+        const report = auditInstalledKindLinks(plan, packageRoot, `dist/agent-src/${kind}`);
+        if (report === null) {
+            out.push({ kind, installed: false, links: 0, unresolved: 0 });
+            continue;
+        }
+        out.push({
+            kind,
+            installed: true,
+            links: report.audits.length,
+            unresolved: report.audits.length - report.counts.resolved,
+        });
+        npLinks += report.non_projected.length;
+        npUnresolved += report.non_projected.filter((a) => a.verdict !== 'resolved').length;
+    }
+    out.push({ kind: 'non-projected', installed: true, links: npLinks, unresolved: npUnresolved });
+    return out;
+}
+
+/** Key of a kind's recorded count in `src/config/gate-violation-baselines.json`. */
+export function kindBaselineKey(host: string, kind: KindLinkReading['kind']): string {
+    return `report_installed_rule_links:kinds:${host}:${kind}`;
+}
+
+/**
+ * The recorded count for each row, or null where none is recorded.
+ *
+ * Read, never written: the baseline only moves by a reviewed commit, so a new
+ * dead link shows as a live count above it rather than as a quietly raised
+ * number. Nothing here fails on the comparison (D2 — report, never fail).
+ */
+export function recordedBaselines(packageRoot: string, host: string, rows: KindLinkReading[]): (number | null)[] {
+    const { gates } = loadBaselines(packageRoot);
+    return rows.map((r) => gates[kindBaselineKey(host, r.kind)]?.count ?? null);
+}
+
+/** `kind: <name> unresolved <n> of <m>` — the line form the roadmap fixed. */
+export function formatKindLine(r: KindLinkReading, host: string, baseline: number | null = null): string {
+    const name = r.kind === 'non-projected' ? 'non-projected (adr, docs/)' : r.kind;
+    const tail = r.installed ? '' : ` (not installed for ${host})`;
+    const base =
+        baseline === null
+            ? ''
+            : ` [baseline ${String(baseline)}${r.unresolved > baseline ? `, ${String(r.unresolved - baseline)} above it` : ''}]`;
+    return `kind: ${name} unresolved ${String(r.unresolved)} of ${String(r.links)}${tail}${base}`;
+}
+
+function parseKinds(raw: string): LinkKind[] | null {
+    if (raw === 'all') return [...LINK_KINDS];
+    const picked = raw.split(',').map((k) => k.trim());
+    if (picked.length === 0 || picked.some((k) => !(LINK_KINDS as readonly string[]).includes(k))) return null;
+    return LINK_KINDS.filter((k) => picked.includes(k));
+}
+
 function flagValue(flag: string): string | null {
     const argv = process.argv.slice(2);
     const i = argv.indexOf(flag);
@@ -81,9 +166,14 @@ function flagValue(flag: string): string | null {
 
 const USAGE =
     'usage: report_installed_rule_links [--root DIR] [--prefix-chars N] [--json]\n' +
+    '                                   [--kinds all|K[,K...]] [--host HOST]\n' +
     '  --root          package checkout the installer copies FROM (default: cwd)\n' +
     '  --prefix-chars  length of the installed package root, for the rewrite price\n' +
     '                  (default 48, a typical `~/.claude/agent-config` expansion)\n' +
+    '  --kinds         one unresolved count per installed kind instead of the rule\n' +
+    `                  reading: ${LINK_KINDS.join(', ')}, or all; docs/ and ADR\n` +
+    '                  targets are printed as their own row. Reports, never fails.\n' +
+    '  --host          host whose deploy plan --kinds reads (default claude-code)\n' +
     '  --json          machine-readable readings\n';
 
 export function main(): number {
@@ -93,7 +183,7 @@ export function main(): number {
         return 0;
     }
     for (const a of argv) {
-        if (a.startsWith('-') && !['--root', '--prefix-chars', '--json'].includes(a)) {
+        if (a.startsWith('-') && !['--root', '--prefix-chars', '--json', '--kinds', '--host'].includes(a)) {
             process.stderr.write(`unknown argument: ${a}\n${USAGE}`);
             return 2;
         }
@@ -111,6 +201,33 @@ export function main(): number {
         return 1;
     }
 
+    const rawKinds = flagValue('--kinds');
+    if (rawKinds !== null || argv.includes('--kinds')) {
+        const kinds = rawKinds === null ? null : parseKinds(rawKinds);
+        if (kinds === null) {
+            process.stderr.write(`--kinds takes all or a comma list of: ${LINK_KINDS.join(', ')}\n`);
+            return 2;
+        }
+        const host = flagValue('--host') ?? 'claude-code';
+        const pairs = GLOBAL_DEPLOY_SOURCES[host];
+        if (pairs === undefined) {
+            process.stderr.write(`unknown --host ${host}; known: ${Object.keys(GLOBAL_DEPLOY_SOURCES).join(', ')}\n`);
+            return 2;
+        }
+        const kindRows = kindReadings(root, pairs, kinds);
+        const baselines = recordedBaselines(root, host, kindRows);
+        if (argv.includes('--json')) {
+            const rows = kindRows.map((r, i) => ({ ...r, baseline: baselines[i] }));
+            process.stdout.write(`${JSON.stringify({ host, kinds: rows }, null, 2)}\n`);
+            return 0;
+        }
+        process.stdout.write(`installed links per kind, host ${host} (report only; counted since 2026-10-06)\n\n`);
+        kindRows.forEach((r, i) => {
+            process.stdout.write(`  ${formatKindLine(r, host, baselines[i] ?? null)}\n`);
+        });
+        return 0;
+    }
+
     const rows = readings(root, prefixChars);
 
     if (argv.includes('--json')) {

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

@@ -11,8 +11,11 @@
  *     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.
- *   · The `# obligation: line N` frontmatter marker — 107 of 121 rules carry
- *     one and nothing in the tree reads it, so this is its first reader.
+ *   · `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.
@@ -31,6 +34,8 @@ 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.
 
@@ -53,7 +58,8 @@ const REFUSING: ReadonlySet<string> = new Set(['validator', 'validator-local', '
 export interface MechanismRow {
     rule: string;
     tier: string;
-    marker_line: number | null;
+    /** Obligation ids this rule declares, `null` when it declares none (the kernel). */
+    obligations: number | null;
     frequency: string;
     declared: number;
     effective: string;
@@ -65,15 +71,6 @@ export interface MechanismRow {
     restatements: number;
 }
 
-/** `# obligation: line N` inside the frontmatter block. */
-export function markerLine(content: string): number | null {
-    if (!content.startsWith('---')) return null;
-    const end = content.indexOf('\n---', 3);
-    const block = end === -1 ? content : content.slice(0, end);
-    const m = /^#\s*obligation:\s*line\s+(\d+)\s*$/m.exec(block);
-    return m ? Number.parseInt(m[1] as string, 10) : null;
-}
-
 function run(root: string, script: string, args: readonly string[]): string {
     return execFileSync(path.join(root, 'scripts-run'), [script, ...args], {
         cwd: root,
@@ -123,10 +120,11 @@ export function rows(root: string): MechanismRow[] {
         }
     }
 
+    const inventory = fs.existsSync(path.join(root, RULE_OBLIGATIONS_PATH))
+        ? loadRuleObligations(root).rules
+        : {};
     const out: MechanismRow[] = [];
     for (const r of coverage.rules) {
-        const file = path.join(root, 'src', 'rules', `${r.id}.md`);
-        const content = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
         const declared = r.declared ?? [];
         const effective = r.effective ?? 'none';
         const frequency = r.obligation_frequency ?? '—';
@@ -140,7 +138,7 @@ export function rows(root: string): MechanismRow[] {
         out.push({
             rule: r.id,
             tier: r.tier ?? '—',
-            marker_line: markerLine(content),
+            obligations: inventory[r.id]?.obligations.length ?? null,
             frequency,
             declared: declared.length,
             effective,
@@ -155,11 +153,11 @@ export function rows(root: string): MechanismRow[] {
 
 export function renderTable(data: readonly MechanismRow[]): string[] {
     const L: string[] = [];
-    L.push('| Rule | Tier | Marker | Frequency | `enforced_by` | Resolves to | Carried | Slot exists | Restatements |');
+    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.marker_line === null ? '—' : String(r.marker_line)} | ` +
+            `| \`${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)} |`,
         );
@@ -210,7 +208,7 @@ export function main(): number {
             `  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` +
-            `  carry no \`# obligation: line N\` marker: ${String(data.filter((r) => r.marker_line === null).length)}\n`,
+            `  declare no obligation ids: ${String(data.filter((r) => r.obligations === null).length)}\n`,
     );
     return 0;
 }

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 };