@event4u/agent-config 8.3.0 → 8.4.1

package/src/agent-src/scripts/update_roadmap_progress.ts

@@ -0,0 +1,1087 @@
+#!/usr/bin/env tsx
+/**
+ * Generate `agents/roadmaps-progress.md` — aggregated progress across open roadmaps.
+ *
+ * TypeScript twin of `src/agent-src/scripts/update_roadmap_progress.py`
+ * (ADR-200, Python→TypeScript migration). The `.augment`-projected copy of this
+ * script is what CI runs as `--check`, so byte-parity is load-bearing: the
+ * rendered dashboard markdown, the `--check` stale comparison, the stderr
+ * warnings, and the exit codes all mirror the Python original EXACTLY. The
+ * public surface (`collect`, `parse_roadmap`, `RoadmapStats`-shaped objects with
+ * `.rel` / `.open_` / `.deferred` / `total_active`, …) is preserved so
+ * `archive_completed_roadmaps` can consume it the same way Python does. snake_case
+ * is kept on the public surface.
+ *
+ * Scans every roadmap under `agents/roadmaps/` (excluding `archive/`, `skipped/`,
+ * `template.md`, `README.md`, `open-questions*.md`), counts checkbox states per
+ * phase, and writes a dashboard at `agents/roadmaps-progress.md` (outside the
+ * `roadmaps/` folder to keep it clean) with:
+ *
+ *   - Overall progress (open-roadmap count, steps done, %)
+ *   - A summary table of every open roadmap
+ *   - Per-roadmap phase breakdown
+ *
+ * Checkbox states:
+ *   [x]  done      [ ]  open      [~]  deferred      [-]  cancelled
+ *
+ * Percentage = done / (done + open). Deferred and cancelled do not count towards
+ * "open" (they are explicit decisions).
+ *
+ * `[~]` deferred items carry plans the user intends to revisit later. They
+ * block silent auto-archive per `roadmap-progress-sync` Iron Law 3.
+ *
+ * Invocation (from project root):
+ *   node node_modules/.bin/tsx .augment/scripts/update_roadmap_progress.ts              # rewrite
+ *   node node_modules/.bin/tsx .augment/scripts/update_roadmap_progress.ts --check      # CI: exit 1 if stale
+ *
+ * --- Parity notes (ADR-200) ---
+ *
+ * - Python `round()` is banker's rounding (round-half-to-even). Percentages and
+ *   the progress bar use it, so `_pyRound` replicates it — a naïve `Math.round`
+ *   would drift on exact-half values (e.g. 12.5 → 12, not 13).
+ * - The Python `re` patterns (MULTILINE / DOTALL) are translated 1:1; `\s` in
+ *   the checkbox/phase classes maps to Python's `\s` (`[ \t\n\r\f\v]`), and the
+ *   Unicode em-dash `—` is preserved in the phase separator class.
+ * - `sorted(roadmap_root.rglob("*.md"))` → component-wise sort over a recursive
+ *   `.md` walk (only files; symlinked dirs are followed like pathlib).
+ * - `collect_bundles` does `import yaml` lazily and returns `[]` on ImportError
+ *   or a malformed registry → `createRequire('yaml')` in a try/catch, same
+ *   graceful-degradation contract. PyYAML 1.1 semantics via the `yaml` package.
+ * - JSON is not emitted; the only structured output is the markdown dashboard
+ *   built with `"\n".join(lines) + "\n"`.
+ * - `Path.read_text(encoding="utf-8")` → `fs.readFileSync(p, "utf-8")`.
+ * - `process.exitCode` is set; `process.exit()` is never called. argparse
+ *   usage errors throw `ArgparseExit(2)`; `-h`/`--help` throws `ArgparseExit(0)`.
+ */
+
+import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import type * as YamlModule from 'yaml';
+
+const _HERE = fileURLToPath(import.meta.url);
+const _require = createRequire(import.meta.url);
+
+// CHECKBOX_RE = re.compile(r"^\s*[-*]\s+\[([ xX~\-])\]\s", re.MULTILINE)
+const CHECKBOX_RE = /^[ \t\n\r\f\v]*[-*][ \t\n\r\f\v]+\[([ xX~\-])\][ \t\n\r\f\v]/gm;
+// PHASE_RE (MULTILINE) — H2/H3 "Phase <id>" with optional separator + name.
+const PHASE_RE =
+    /^(#{2,3})[ \t\n\r\f\v]+Phase[ \t\n\r\f\v]+(\d+[a-z]?|[IVX]+|[A-Z](?:\d+)?)(?:[\s:—\-]+([\s\S]*?))?[ \t\f\v\r]*$/gm;
+// TITLE_RE = re.compile(r"^#\s+(?:Roadmap:\s*)?(.+?)\s*$", re.MULTILINE)
+const TITLE_RE = /^#[ \t\n\r\f\v]+(?:Roadmap:[ \t\n\r\f\v]*)?(.+?)[ \t\f\v\r]*$/m;
+const EXCLUDE_NAMES: ReadonlySet<string> = new Set([
+    'template.md',
+    'README.md',
+    'progress.md',
+    'roadmaps-progress.md',
+]);
+const EXCLUDE_PREFIXES: readonly string[] = ['open-questions'];
+const EXCLUDE_DIRS: ReadonlySet<string> = new Set(['archive', 'skipped', 'stubs', 'later']);
+
+// FRONTMATTER_RE = re.compile(r"\A---\n(.*?)\n---\s*\n", re.DOTALL)
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---[ \t\n\r\f\v]*\n/;
+const DRAFT_VALUES: ReadonlySet<string> = new Set(['draft']);
+
+const MERGE_GATED_RE = /merge-gated/i;
+// PR_NUM_RE = re.compile(r"pr\s*[=#:]?\s*#?\s*(\d+)", re.IGNORECASE)
+const PR_NUM_RE = /pr[ \t\n\r\f\v]*[=#:]?[ \t\n\r\f\v]*#?[ \t\n\r\f\v]*(\d+)/gi;
+
+/** Python `round()` — round-half-to-even (banker's rounding). */
+function _pyRound(x: number): number {
+    const floor = Math.floor(x);
+    const diff = x - floor;
+    if (diff < 0.5) return floor;
+    if (diff > 0.5) return floor + 1;
+    // Exact half → round to even.
+    return floor % 2 === 0 ? floor : floor + 1;
+}
+
+class PhaseStats {
+    id: string;
+    name: string;
+    done: number;
+    open_: number;
+    deferred: number;
+    cancelled: number;
+    merge_gated: number;
+    merge_gated_prs: number[];
+
+    constructor(
+        id: string,
+        name: string,
+        done = 0,
+        open_ = 0,
+        deferred = 0,
+        cancelled = 0,
+        merge_gated = 0,
+        merge_gated_prs: number[] = [],
+    ) {
+        this.id = id;
+        this.name = name;
+        this.done = done;
+        this.open_ = open_;
+        this.deferred = deferred;
+        this.cancelled = cancelled;
+        this.merge_gated = merge_gated;
+        this.merge_gated_prs = merge_gated_prs;
+    }
+
+    get total_active(): number {
+        return this.done + this.open_;
+    }
+
+    get total_all(): number {
+        return this.done + this.open_ + this.deferred + this.cancelled;
+    }
+
+    get percent(): number {
+        return this.total_active ? _pyRound((this.done * 100) / this.total_active) : 0;
+    }
+
+    get state(): string {
+        if (this.total_active === 0 && (this.deferred || this.cancelled)) {
+            return '⏭️ skipped';
+        }
+        if (this.total_active === 0) {
+            return '⬜ empty';
+        }
+        if (this.done === 0) {
+            return '⬜ not started';
+        }
+        if (this.open_ === 0) {
+            return '✅ done';
+        }
+        return '🟡 in progress';
+    }
+}
+
+class RoadmapStats {
+    path: string;
+    rel: string;
+    title: string;
+    phases: PhaseStats[];
+    blockers: Blocker[];
+
+    constructor(
+        p: string,
+        rel: string,
+        title: string,
+        phases: PhaseStats[] = [],
+        blockers: Blocker[] = [],
+    ) {
+        this.path = p;
+        this.rel = rel;
+        this.title = title;
+        this.phases = phases;
+        this.blockers = blockers;
+    }
+
+    get open_blockers(): Blocker[] {
+        return this.blockers.filter((b) => b.status !== 'resolved');
+    }
+
+    get resolved_blockers(): Blocker[] {
+        return this.blockers.filter((b) => b.status === 'resolved');
+    }
+
+    get done(): number {
+        return this.phases.reduce((s, p) => s + p.done, 0);
+    }
+
+    get open_(): number {
+        return this.phases.reduce((s, p) => s + p.open_, 0);
+    }
+
+    get deferred(): number {
+        return this.phases.reduce((s, p) => s + p.deferred, 0);
+    }
+
+    get cancelled(): number {
+        return this.phases.reduce((s, p) => s + p.cancelled, 0);
+    }
+
+    get merge_gated(): number {
+        return this.phases.reduce((s, p) => s + p.merge_gated, 0);
+    }
+
+    get merge_gated_prs(): number[] {
+        const seen: number[] = [];
+        for (const p of this.phases) {
+            for (const n of p.merge_gated_prs) {
+                if (!seen.includes(n)) {
+                    seen.push(n);
+                }
+            }
+        }
+        return seen;
+    }
+
+    get total_active(): number {
+        return this.done + this.open_;
+    }
+
+    get total_all(): number {
+        return this.done + this.open_ + this.deferred + this.cancelled;
+    }
+
+    get percent(): number {
+        return this.total_active ? _pyRound((this.done * 100) / this.total_active) : 0;
+    }
+}
+
+/** `str.strip()` over Python whitespace (space/tab/nl/cr/ff/vt). */
+function _strip(s: string): string {
+    return s.replace(/^[ \t\n\r\f\v]+/, '').replace(/[ \t\n\r\f\v]+$/, '');
+}
+
+/** `str.splitlines()` — split on Python's line boundaries (no trailing empty). */
+function _splitlines(s: string): string[] {
+    if (s === '') return [];
+    // Python splitlines splits on \n, \r, \r\n (and a few more, but markdown
+    // here is plain \n / \r\n). Mirror that set; drop the trailing empty.
+    const parts = s.split(/\r\n|[\n\r\x0b\x0c\x1c\x1d\x1e\x85\u2028\u2029]/);
+    if (parts.length && parts[parts.length - 1] === '') {
+        parts.pop();
+    }
+    return parts;
+}
+
+function parse_frontmatter(text: string): Record<string, string> {
+    const m = FRONTMATTER_RE.exec(text);
+    if (!m) {
+        return {};
+    }
+    const fm: Record<string, string> = {};
+    for (const line of _splitlines(m[1] as string)) {
+        const stripped = _strip(line);
+        if (!stripped || stripped.startsWith('#') || !line.includes(':')) {
+            continue;
+        }
+        // line.partition(":") — split on first colon.
+        const idx = line.indexOf(':');
+        const key = line.slice(0, idx);
+        const value = line.slice(idx + 1);
+        fm[_strip(key)] = _stripQuotes(_strip(value));
+    }
+    return fm;
+}
+
+/** value.strip().strip('"').strip("'") — Python's chained one-char strips. */
+function _stripQuotes(s: string): string {
+    let out = s.replace(/^"+/, '').replace(/"+$/, '');
+    out = out.replace(/^'+/, '').replace(/'+$/, '');
+    return out;
+}
+
+function is_draft(fm: Record<string, string>): boolean {
+    return DRAFT_VALUES.has((fm['status'] ?? '').toLowerCase());
+}
+
+function is_roadmap_candidate(p: string): boolean {
+    const name = path.basename(p);
+    if (EXCLUDE_NAMES.has(name)) {
+        return false;
+    }
+    if (EXCLUDE_PREFIXES.some((pre) => name.startsWith(pre))) {
+        return false;
+    }
+    // path.parts — every component of the path; exclude if any is an excluded dir.
+    const parts = p.split(path.sep).filter((s) => s !== '');
+    if (parts.some((part) => EXCLUDE_DIRS.has(part))) {
+        return false;
+    }
+    return true;
+}
+
+type CheckboxCounts = [number, number, number, number, number, number[]];
+
+function count_checkboxes(text: string): CheckboxCounts {
+    let done = 0;
+    let open_ = 0;
+    let deferred = 0;
+    let cancelled = 0;
+    let merge_gated = 0;
+    const prs: number[] = [];
+    const matches: Array<{ start: number; group1: string }> = [];
+    CHECKBOX_RE.lastIndex = 0;
+    let m: RegExpExecArray | null;
+    while ((m = CHECKBOX_RE.exec(text)) !== null) {
+        matches.push({ start: m.index, group1: m[1] as string });
+        if (m.index === CHECKBOX_RE.lastIndex) {
+            CHECKBOX_RE.lastIndex++;
+        }
+    }
+    for (let i = 0; i < matches.length; i++) {
+        const c = (matches[i] as { start: number; group1: string }).group1.toLowerCase();
+        if (c === 'x') {
+            done += 1;
+        } else if (c === ' ') {
+            open_ += 1;
+            const span_end =
+                i + 1 < matches.length ? (matches[i + 1] as { start: number }).start : text.length;
+            const span = text.slice((matches[i] as { start: number }).start, span_end);
+            if (MERGE_GATED_RE.test(span)) {
+                merge_gated += 1;
+                PR_NUM_RE.lastIndex = 0;
+                let pm: RegExpExecArray | null;
+                while ((pm = PR_NUM_RE.exec(span)) !== null) {
+                    prs.push(parseInt(pm[1] as string, 10));
+                }
+            }
+        } else if (c === '~') {
+            deferred += 1;
+        } else if (c === '-') {
+            cancelled += 1;
+        }
+    }
+    return [done, open_, deferred, cancelled, merge_gated, prs];
+}
+
+interface Blocker {
+    id: string;
+    status: string;
+    owner: string;
+    blocks: string;
+    todo: string[];
+    resolvedWhen: string;
+}
+
+// Strip fenced code blocks before blocker detection — a roadmap that shows the
+// `## Blockers` shape as a documentation example (fenced, indented or not)
+// must not be mistaken for a live blocker on that roadmap.
+const FENCED_CODE_RE = /^[ \t]*```[^\n]*\n[\s\S]*?^[ \t]*```[ \t]*$/gm;
+const BLOCKERS_SECTION_RE = /^##[ \t]+Blockers[ \t]*$/im;
+const BLOCKER_HEADING_RE = /^###[ \t]+blocker:[ \t]*(.+?)[ \t]*$/gim;
+const NEXT_H2_RE = /^##[ \t]+\S/m;
+const LEGACY_BLOCKED_UNTIL_RE = /^>[ \t]*Blocked until:?[ \t]*(.+)$/im;
+
+function _stripFencedCode(text: string): string {
+    return text.replace(FENCED_CODE_RE, (m) => '\n'.repeat(_splitlines(m).length));
+}
+
+const BLOCKER_FIELD_RE = /^-[ \t]*\*\*(Status|Owner|Blocks|Resolved when|What to do):\*\*/i;
+
+/** Strip an inline `<!-- comment -->` and trim. */
+function _stripComment(s: string): string {
+    return _strip(s.replace(/<!--[\s\S]*?-->/g, ''));
+}
+
+/**
+ * `- **Label:** value` → trimmed `value`, joined with any wrapped
+ * continuation lines (non-bulleted text under the same field, e.g. a long
+ * "Blocks" sentence spanning two lines) up to the next `- **Field:**`
+ * marker, blank line, or heading.
+ */
+function _blockerField(slice: string, label: string): string | null {
+    const lines = _splitlines(slice);
+    const re = new RegExp(`^-[ \\t]*\\*\\*${label}:\\*\\*[ \\t]*(.*)$`, 'i');
+    const startIdx = lines.findIndex((l) => re.test(_strip(l)));
+    if (startIdx === -1) {
+        return null;
+    }
+    const m = re.exec(_strip(lines[startIdx] as string));
+    const parts: string[] = [];
+    const first = _stripComment((m?.[1] as string) ?? '');
+    if (first) {
+        parts.push(first);
+    }
+    for (let i = startIdx + 1; i < lines.length; i++) {
+        const trimmed = _strip(lines[i] as string);
+        if (trimmed === '' || BLOCKER_FIELD_RE.test(trimmed) || trimmed.startsWith('#')) {
+            break;
+        }
+        parts.push(_stripComment(trimmed));
+    }
+    return parts.length ? parts.join(' ') : null;
+}
+
+/** Lines under `- **What to do:**` up to the next `- **Field:**` marker. */
+function _blockerTodo(slice: string): string[] {
+    const lines = _splitlines(slice);
+    const startIdx = lines.findIndex((l) => /^-[ \t]*\*\*What to do:\*\*/i.test(_strip(l)));
+    if (startIdx === -1) {
+        return [];
+    }
+    const out: string[] = [];
+    for (let i = startIdx + 1; i < lines.length; i++) {
+        const trimmed = _strip(lines[i] as string);
+        if (BLOCKER_FIELD_RE.test(trimmed) || trimmed.startsWith('#')) {
+            break;
+        }
+        if (trimmed !== '') {
+            out.push(trimmed);
+        }
+    }
+    return out;
+}
+
+function parse_blockers(raw_text: string): Blocker[] {
+    const text = _stripFencedCode(raw_text);
+    const blockers: Blocker[] = [];
+    const sectionMatch = BLOCKERS_SECTION_RE.exec(text);
+    if (sectionMatch) {
+        const sectionStart = sectionMatch.index + sectionMatch[0].length;
+        const rest = text.slice(sectionStart);
+        const h2 = NEXT_H2_RE.exec(rest);
+        const sectionEnd = h2 ? sectionStart + h2.index : text.length;
+        const section = text.slice(sectionStart, sectionEnd);
+        BLOCKER_HEADING_RE.lastIndex = 0;
+        const heads: Array<{ start: number; end: number; id: string }> = [];
+        let hm: RegExpExecArray | null;
+        while ((hm = BLOCKER_HEADING_RE.exec(section)) !== null) {
+            heads.push({
+                start: hm.index,
+                end: hm.index + hm[0].length,
+                id: _strip(hm[1] as string),
+            });
+            if (hm.index === BLOCKER_HEADING_RE.lastIndex) {
+                BLOCKER_HEADING_RE.lastIndex++;
+            }
+        }
+        for (let i = 0; i < heads.length; i++) {
+            const cur = heads[i] as { start: number; end: number; id: string };
+            const bodyEnd =
+                i + 1 < heads.length ? (heads[i + 1] as { start: number }).start : section.length;
+            const body = section.slice(cur.end, bodyEnd);
+            blockers.push({
+                id: cur.id,
+                status: (_blockerField(body, 'Status') ?? 'open').toLowerCase(),
+                owner: _blockerField(body, 'Owner') ?? 'user',
+                blocks: _blockerField(body, 'Blocks') ?? '(unspecified)',
+                todo: _blockerTodo(body),
+                resolvedWhen: _blockerField(body, 'Resolved when') ?? '(unspecified)',
+            });
+        }
+    }
+    const legacyMatch = LEGACY_BLOCKED_UNTIL_RE.exec(text);
+    if (legacyMatch) {
+        blockers.push({
+            id: 'legacy',
+            status: 'open',
+            owner: 'user',
+            blocks: 'entire roadmap',
+            todo: [_strip(legacyMatch[1] as string)],
+            resolvedWhen: 'condition described above clears',
+        });
+    }
+    return blockers;
+}
+
+function parse_roadmap(p: string, roadmap_root: string): RoadmapStats | null {
+    const text = fs.readFileSync(p, { encoding: 'utf-8' });
+    const phase_matches: Array<{ start: number; end: number; g2: string; g3: string | undefined }> =
+        [];
+    PHASE_RE.lastIndex = 0;
+    let pm: RegExpExecArray | null;
+    while ((pm = PHASE_RE.exec(text)) !== null) {
+        phase_matches.push({
+            start: pm.index,
+            end: pm.index + pm[0].length,
+            g2: pm[2] as string,
+            g3: pm[3],
+        });
+        if (pm.index === PHASE_RE.lastIndex) {
+            PHASE_RE.lastIndex++;
+        }
+    }
+    if (phase_matches.length === 0) {
+        return null; // not a roadmap — no ## Phase headings
+    }
+    const title_match = TITLE_RE.exec(text);
+    const title = title_match ? _strip(title_match[1] as string) : _stem(p);
+    const rel = _relPosix(roadmap_root, p);
+    const stats = new RoadmapStats(p, rel, title, [], parse_blockers(text));
+    for (let i = 0; i < phase_matches.length; i++) {
+        const cur = phase_matches[i] as { start: number; end: number; g2: string; g3: string | undefined };
+        const start = cur.end;
+        const end = i + 1 < phase_matches.length ? (phase_matches[i + 1] as { start: number }).start : text.length;
+        const [d, o, df, c, mg, prs] = count_checkboxes(text.slice(start, end));
+        const phase_id = cur.g2;
+        const name = _strip(cur.g3 ?? '') || `Phase ${phase_id}`;
+        stats.phases.push(new PhaseStats(phase_id, name, d, o, df, c, mg, prs));
+    }
+    return stats;
+}
+
+/** Path.stem — filename without final suffix. */
+function _stem(p: string): string {
+    const base = path.basename(p);
+    const dot = base.lastIndexOf('.');
+    return dot > 0 ? base.slice(0, dot) : base;
+}
+
+/** str(path.relative_to(root)) — POSIX-separated relative path. */
+function _relPosix(root: string, p: string): string {
+    return path.relative(root, p).split(path.sep).join('/');
+}
+
+/** Deterministic anchor slug for a roadmap's blocker section — explicit
+ * anchors (rather than GitHub's auto heading-slug) survive `.md` / brackets. */
+function _blockerAnchor(rel: string): string {
+    const stem = rel.endsWith('.md') ? rel.slice(0, -3) : rel;
+    return (
+        'blockers-' +
+        stem
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, '-')
+            .replace(/^-+|-+$/g, '')
+    );
+}
+
+function bar(pct: number, width = 10): string {
+    const filled = _pyRound((pct * width) / 100);
+    return '█'.repeat(filled) + '░'.repeat(width - filled);
+}
+
+/** sorted(roadmap_root.rglob("*.md")) — recursive, component-wise sort, files. */
+function _rglobMdSorted(root: string): string[] {
+    const out: string[] = [];
+    const walk = (dir: string): void => {
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const ent of entries) {
+            const full = path.join(dir, ent.name);
+            if (ent.isDirectory()) {
+                walk(full);
+            } else if (ent.isSymbolicLink() && _isDir(full)) {
+                walk(full);
+            } else if (ent.name.endsWith('.md')) {
+                out.push(full);
+            }
+        }
+    };
+    walk(root);
+    out.sort();
+    return out;
+}
+
+function _isDir(p: string): boolean {
+    try {
+        return fs.statSync(p).isDirectory();
+    } catch {
+        return false;
+    }
+}
+
+function _isFile(p: string): boolean {
+    try {
+        return fs.statSync(p).isFile();
+    } catch {
+        return false;
+    }
+}
+
+function collect(roadmap_root: string): RoadmapStats[] {
+    const results: RoadmapStats[] = [];
+    for (const p of _rglobMdSorted(roadmap_root)) {
+        if (!_isFile(p) || !is_roadmap_candidate(p)) {
+            continue;
+        }
+        const text = fs.readFileSync(p, { encoding: 'utf-8' });
+        if (is_draft(parse_frontmatter(text))) {
+            continue;
+        }
+        const stats = parse_roadmap(p, roadmap_root);
+        if (stats) {
+            results.push(stats);
+        }
+    }
+    return results;
+}
+
+function unarchived_complete(roadmaps: RoadmapStats[]): RoadmapStats[] {
+    return roadmaps.filter((r) => r.total_active > 0 && r.open_ === 0 && r.deferred === 0);
+}
+
+function merge_gated_pending(roadmaps: RoadmapStats[]): RoadmapStats[] {
+    return roadmaps.filter((r) => r.open_ > 0 && r.merge_gated === r.open_);
+}
+
+function pending_iron_law_3(roadmaps: RoadmapStats[]): RoadmapStats[] {
+    return roadmaps.filter((r) => r.total_active > 0 && r.open_ === 0 && r.deferred > 0);
+}
+
+interface Bundle {
+    slug: string;
+    tickets: number;
+    status: string;
+    roadmap: string;
+}
+
+function collect_bundles(repo_root: string): Bundle[] {
+    const reg = path.join(repo_root, 'agents', 'tickets', '_registry.yml');
+    if (!fs.existsSync(reg)) {
+        return [];
+    }
+    let YAML: typeof YamlModule;
+    try {
+        YAML = _require('yaml') as typeof YamlModule;
+    } catch {
+        return [];
+    }
+    let data: unknown;
+    try {
+        // yaml.safe_load(...) or {} — PyYAML 1.1 semantics; graceful on malformed.
+        data = YAML.parse(fs.readFileSync(reg, { encoding: 'utf-8' }), { version: '1.1' }) ?? {};
+    } catch {
+        return [];
+    }
+    const out: Bundle[] = [];
+    const bundles =
+        data && typeof data === 'object' && !Array.isArray(data)
+            ? ((data as Record<string, unknown>)['bundles'] ?? null)
+            : null;
+    const bundleMap =
+        bundles && typeof bundles === 'object' && !Array.isArray(bundles)
+            ? (bundles as Record<string, unknown>)
+            : {};
+    for (const slug of Object.keys(bundleMap).sort()) {
+        const metaRaw = bundleMap[slug];
+        const meta =
+            metaRaw && typeof metaRaw === 'object' && !Array.isArray(metaRaw)
+                ? (metaRaw as Record<string, unknown>)
+                : {};
+        const bdir = path.join(repo_root, 'agents', 'tickets', slug);
+        let n = 0;
+        if (_isDir(bdir)) {
+            try {
+                n = fs.readdirSync(bdir).filter((f) => f.startsWith('T-') && f.endsWith('.md')).length;
+            } catch {
+                n = 0;
+            }
+        }
+        out.push({
+            slug,
+            tickets: n,
+            status: (meta['status'] as string) ?? '?',
+            roadmap: (meta['source_roadmap'] as string) ?? '',
+        });
+    }
+    return out;
+}
+
+function render(roadmaps: RoadmapStats[], bundles: Bundle[] | null = null): string {
+    const total_done = roadmaps.reduce((s, r) => s + r.done, 0);
+    const total_active = roadmaps.reduce((s, r) => s + r.total_active, 0);
+    const overall_pct = total_active ? _pyRound((total_done * 100) / total_active) : 0;
+    const pending = pending_iron_law_3(roadmaps);
+    const gated = merge_gated_pending(roadmaps);
+    const total_open_blockers = roadmaps.reduce((s, r) => s + r.open_blockers.length, 0);
+    const lines: string[] = [];
+    lines.push('# Roadmap Progress\n');
+    const header_meta =
+        `> ${roadmaps.length} open roadmap` +
+        `${roadmaps.length !== 1 ? 's' : ''}` +
+        ' · [roadmaps/](roadmaps/) · [archive/](roadmaps/archive/) · ' +
+        '[skipped/](roadmaps/skipped/) · [later/](roadmaps/later/)' +
+        (total_open_blockers > 0
+            ? ` · **${total_open_blockers}** open blocker${total_open_blockers !== 1 ? 's' : ''}`
+            : '') +
+        '\n';
+    lines.push(
+        // Honest provenance (road-to-roadmap-archival-robustness, gap C): name a
+        // regen path that exists in EVERY install, not a hardcoded
+        // `.augment/scripts/...` that a script-less / non-Augment consumer does
+        // not have. `task roadmap-progress` covers Taskfile projects; the bare
+        // script name covers the rest.
+        '> Auto-generated — do not edit. Regenerate with `task roadmap-progress` ' +
+            'or by running the `update_roadmap_progress` script for your install; ' +
+            'rewritten on every roadmap create / execute / completion change ' +
+            '(timestamp lives in git history).\n>\n' +
+            header_meta,
+    );
+    lines.push('## Overall\n');
+    lines.push(`**${total_done} / ${total_active} steps done · ${overall_pct}%**\n`);
+    lines.push('```text\n' + bar(overall_pct, 40) + `   ${overall_pct}%\n` + '```\n');
+    if (pending.length) {
+        lines.push('## ⚠️ Iron Law 3 — unresolved deferred items\n');
+        lines.push(
+            'These roadmaps have `count_open == 0` but carry `[~]` deferred ' +
+                'items. Per `roadmap-progress-sync` Iron Law 3 they do NOT ' +
+                'auto-archive — the user must resolve the deferrals first ' +
+                '(spawn follow-up, restore, or cancel). See ' +
+                '[`roadmap-management § 4b`](../packages/core/.agent-src.uncondensed/skills/roadmap-management/SKILL.md).\n',
+        );
+        lines.push('| Roadmap | Done | Deferred | Cancelled |');
+        lines.push('|---|---:|---:|---:|');
+        for (const r of pending) {
+            lines.push(
+                `| [${r.rel}](roadmaps/${r.rel}) | ${r.done} | ` + `${r.deferred} | ${r.cancelled} |`,
+            );
+        }
+        lines.push('');
+    }
+    if (gated.length) {
+        lines.push('## ⏳ Merge-gated — pending post-merge archival\n');
+        lines.push(
+            'Every open item in these roadmaps is `merge-gated`: held open ' +
+                'on purpose while a closing PR is in flight, so inbound ' +
+                'references keep resolving until the file archives. **The moment ' +
+                'the gating PR merges**, flip the merge-gated box → `[x]`, ' +
+                '`git mv` the roadmap to `archive/`, migrate inbound refs, and ' +
+                'regenerate this dashboard — all in the same response (per ' +
+                '`roadmap-progress-sync` Iron Law 1). Do NOT leave it lingering ' +
+                'at < 100%.\n',
+        );
+        lines.push('| Roadmap | Done | Merge-gated open | Gating PR |');
+        lines.push('|---|---:|---:|---|');
+        for (const r of gated) {
+            const prs = r.merge_gated_prs.map((n) => `#${n}`).join(', ') || '—';
+            lines.push(
+                `| [${r.rel}](roadmaps/${r.rel}) | ${r.done} | ` + `${r.merge_gated} | ${prs} |`,
+            );
+        }
+        lines.push('');
+    }
+    const unarchived = unarchived_complete(roadmaps);
+    if (unarchived.length) {
+        // Non-CI backstop (road-to-roadmap-archival-robustness, gap C): a
+        // persistent dashboard banner makes "completed but unarchived" visible
+        // without the CI `--check` gate — the consumer sees it on every regen.
+        lines.push('## ✅ Completed — pending archival\n');
+        lines.push(
+            'These roadmaps are **complete** (`count_open == 0`, ' +
+                '`count_deferred == 0`) but still sit in the active tree. They ' +
+                'should be in `agents/roadmaps/archive/`. Run the archival sweep ' +
+                '`archive_completed_roadmaps --all` (untracked-safe), or follow the ' +
+                'manual fallback documented in the `roadmap-management` skill, then ' +
+                'regenerate this dashboard.\n',
+        );
+        lines.push('| Roadmap | Done | Total |');
+        lines.push('|---|---:|---:|');
+        for (const r of unarchived) {
+            lines.push(`| [${r.rel}](roadmaps/${r.rel}) | ${r.done} | ${r.total_active} |`);
+        }
+        lines.push('');
+    }
+    if (roadmaps.length === 0) {
+        lines.push('_No open roadmaps._\n');
+        return lines.join('\n') + '\n';
+    }
+    lines.push('## Open roadmaps\n');
+    lines.push(
+        '| # | Roadmap | Phases | Steps | Open | Done | Deferred | Cancelled | Blocker | Progress |',
+    );
+    lines.push('|---|---|---:|---:|---:|---:|---:|---:|---:|---|');
+    roadmaps.forEach((r, idx) => {
+        const i = idx + 1;
+        const openBlockers = r.open_blockers.length;
+        const blockerCell =
+            openBlockers > 0 ? `[${openBlockers}](#${_blockerAnchor(r.rel)})` : '0';
+        lines.push(
+            `| ${i} | [${r.rel}](roadmaps/${r.rel}) | ${r.phases.length} | ${r.total_all} | ` +
+                `${r.open_} | ${r.done} | ${r.deferred} | ${r.cancelled} | ${blockerCell} | ` +
+                `${bar(r.percent)} ${r.percent}% |`,
+        );
+    });
+    lines.push('');
+    lines.push('---\n');
+    lines.push('## Per-roadmap phase breakdown\n');
+    for (const r of roadmaps) {
+        lines.push(`### [${r.rel}](roadmaps/${r.rel})\n`);
+        lines.push(`**${r.title}** — ${r.done} / ${r.total_active} done (${r.percent}%)\n`);
+        lines.push('| # | Phase | State | Open | Done | Deferred | Cancelled | % |');
+        lines.push('|---|---|---|---:|---:|---:|---:|---:|');
+        for (const p of r.phases) {
+            lines.push(
+                `| ${p.id} | ${p.name} | ${p.state} | ${p.open_} | ${p.done} | ` +
+                    `${p.deferred} | ${p.cancelled} | ${p.percent}% |`,
+            );
+        }
+        lines.push('');
+        const openBlockers = r.open_blockers;
+        if (openBlockers.length) {
+            lines.push(`<a id="${_blockerAnchor(r.rel)}"></a>`);
+            lines.push('**Blockers**\n');
+            for (const b of openBlockers) {
+                lines.push(`- **${b.id}** (owner: ${b.owner}) — blocks ${b.blocks}`);
+                lines.push('  - **What to do:**');
+                for (const step of b.todo) {
+                    lines.push(`    ${step}`);
+                }
+                lines.push(`  - **Resolved when:** ${b.resolvedWhen}`);
+            }
+            const resolvedCount = r.resolved_blockers.length;
+            if (resolvedCount > 0) {
+                lines.push(
+                    `\n_${resolvedCount} blocker${resolvedCount !== 1 ? 's' : ''} resolved._`,
+                );
+            }
+            lines.push('');
+        }
+    }
+    if (bundles && bundles.length) {
+        lines.push('---\n');
+        lines.push('## Ticket bundles\n');
+        lines.push(
+            'Materialised ticket bundles under [`agents/tickets/`](tickets/) ' +
+                '(via `/roadmap:materialize`), counted from ' +
+                '`agents/tickets/_registry.yml`.\n',
+        );
+        lines.push('| Bundle | Tickets | Status | Source roadmap |');
+        lines.push('|---|---:|---|---|');
+        for (const b of bundles) {
+            lines.push(
+                `| ${b.slug} | ${b.tickets} | ${b.status} | ` + `${b.roadmap} |`,
+            );
+        }
+        lines.push('');
+    }
+    return lines.join('\n') + '\n';
+}
+
+// --- argparse parity ---------------------------------------------------------
+
+class ArgparseExit extends Error {
+    code: number;
+    constructor(code: number) {
+        super(`ArgparseExit(${code})`);
+        this.name = 'ArgparseExit';
+        this.code = code;
+    }
+}
+
+const _PROG = 'update_roadmap_progress.py';
+
+function _usage(): string {
+    return `usage: ${_PROG} [-h] [--check] [--repo-root REPO_ROOT]\n`;
+}
+
+interface Args {
+    check: boolean;
+    repo_root: string;
+}
+
+function _parseArgs(argv: readonly string[]): Args {
+    let check = false;
+    let repo_root = process.cwd();
+    const emitError = (msg: string): never => {
+        process.stderr.write(_usage());
+        process.stderr.write(`${_PROG}: error: ${msg}\n`);
+        throw new ArgparseExit(2);
+    };
+    let i = 0;
+    while (i < argv.length) {
+        const tok = argv[i] as string;
+        if (tok === '-h' || tok === '--help') {
+            process.stdout.write(_usage());
+            throw new ArgparseExit(0);
+        } else if (tok === '--check') {
+            check = true;
+            i += 1;
+        } else if (tok === '--repo-root') {
+            const val = argv[i + 1];
+            if (val === undefined) {
+                emitError('argument --repo-root: expected one argument');
+            }
+            repo_root = val as string;
+            i += 2;
+        } else if (tok.startsWith('--repo-root=')) {
+            repo_root = tok.slice('--repo-root='.length);
+            i += 1;
+        } else {
+            emitError(`unrecognized arguments: ${tok}`);
+        }
+    }
+    return { check, repo_root };
+}
+
+/**
+ * When the default cwd carries no `agents/roadmaps/`, fall back to the git
+ * toplevel — hook and IDE invocations often run from a subdirectory, and a
+ * cwd-only resolution silently skipped the dashboard there. An explicit
+ * `--repo-root` always wins; a cwd that has the directory is used as-is
+ * (monorepo sub-project support).
+ */
+function _fallback_git_toplevel(repo_root: string): string {
+    try {
+        const r = spawnSync('git', ['rev-parse', '--show-toplevel'], {
+            cwd: repo_root,
+            encoding: 'utf-8',
+            timeout: 10_000,
+        });
+        const top = (r.stdout || '').trim();
+        if (r.status === 0 && top !== '' && _isDir(path.join(top, 'agents', 'roadmaps'))) {
+            return top;
+        }
+    } catch {
+        /* not a git repo / git missing — keep the cwd default */
+    }
+    return repo_root;
+}
+
+function main(argv?: readonly string[]): number {
+    const args = _parseArgs(argv ?? process.argv.slice(2));
+    let repo_root = args.repo_root;
+    if (repo_root === process.cwd() && !_isDir(path.join(repo_root, 'agents', 'roadmaps'))) {
+        repo_root = _fallback_git_toplevel(repo_root);
+    }
+    const roadmap_root = path.join(repo_root, 'agents', 'roadmaps');
+    const target = path.join(repo_root, 'agents', 'roadmaps-progress.md');
+    if (!_isDir(roadmap_root)) {
+        if (args.check) {
+            return 0;
+        }
+        process.stdout.write(`ℹ️  No roadmaps directory at ${roadmap_root} — nothing to do.\n`);
+        return 0;
+    }
+    const roadmaps = collect(roadmap_root);
+    const new_text = render(roadmaps, collect_bundles(repo_root));
+    const current = fs.existsSync(target) ? fs.readFileSync(target, { encoding: 'utf-8' }) : '';
+    const complete = unarchived_complete(roadmaps);
+    const pending = pending_iron_law_3(roadmaps);
+    const gated = merge_gated_pending(roadmaps);
+
+    const _relToRepo = (p: string): string => _relPosix(repo_root, p);
+
+    const _warn_merge_gated = (): void => {
+        process.stderr.write(
+            '⏳  Merge-gated roadmaps (every open item gated on a PR) — ' +
+                'flip + archive the moment the gating PR merges ' +
+                '(`roadmap-progress-sync` Iron Law 1):\n',
+        );
+        for (const r of gated) {
+            const prs = r.merge_gated_prs.map((n) => `#${n}`).join(', ') || 'PR unknown';
+            process.stderr.write(
+                `      - ${r.rel}  (${r.done}/${r.total_active} done · ` +
+                    `${r.merge_gated} merge-gated · ${prs})\n`,
+            );
+        }
+    };
+
+    if (args.check) {
+        const stale = current !== new_text;
+        if (stale) {
+            process.stderr.write(
+                `❌  ${_relToRepo(target)} is stale. ` +
+                    'Run `node node_modules/.bin/tsx .augment/scripts/update_roadmap_progress.ts` ' +
+                    'to regenerate (or `task roadmap-progress` in Taskfile ' +
+                    'projects).\n',
+            );
+        }
+        if (complete.length) {
+            process.stderr.write(
+                '❌  Completed roadmaps are still in `agents/roadmaps/` — ' +
+                    'move them to `agents/roadmaps/archive/` (per the ' +
+                    '`roadmap-progress-sync` rule):\n',
+            );
+            for (const r of complete) {
+                process.stderr.write(`      - ${r.rel}  (${r.done}/${r.total_active} done)\n`);
+            }
+        }
+        if (pending.length) {
+            process.stderr.write(
+                '❌  Iron Law 3 — roadmaps with unresolved `[~]` deferred ' +
+                    'items must NOT auto-archive. Resolve via `roadmap-management § 4b` ' +
+                    '(spawn follow-up, restore, or cancel):\n',
+            );
+            for (const r of pending) {
+                process.stderr.write(
+                    `      - ${r.rel}  (${r.done}/${r.total_active} done · ` +
+                        `${r.deferred} deferred)\n`,
+                );
+            }
+        }
+        if (gated.length) {
+            _warn_merge_gated();
+        }
+        if (stale || complete.length || pending.length) {
+            return 1;
+        }
+        process.stdout.write(`✅  ${_relToRepo(target)} is up to date.\n`);
+        return 0;
+    }
+    fs.writeFileSync(target, new_text, { encoding: 'utf-8' });
+    process.stdout.write(
+        `✅  Wrote ${_relToRepo(target)} · ` +
+            `${roadmaps.length} roadmap(s) · ` +
+            `${roadmaps.reduce((s, r) => s + r.done, 0)}/${roadmaps.reduce((s, r) => s + r.total_active, 0)} steps done.\n`,
+    );
+    if (complete.length) {
+        process.stderr.write(
+            '⚠️   Completed roadmaps not yet archived — move to ' +
+                '`agents/roadmaps/archive/`:\n',
+        );
+        for (const r of complete) {
+            process.stderr.write(`      - ${r.rel}\n`);
+        }
+    }
+    if (pending.length) {
+        process.stderr.write(
+            '⚠️   Iron Law 3 — roadmaps with unresolved `[~]` deferred items. ' +
+                'Surface them and ask the user (`roadmap-management § 4b`) ' +
+                'before any archive:\n',
+        );
+        for (const r of pending) {
+            process.stderr.write(`      - ${r.rel}  (${r.deferred} deferred)\n`);
+        }
+    }
+    if (gated.length) {
+        _warn_merge_gated();
+    }
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    // A symlinked invocation (e.g. via `.augment/scripts` → `dist/agent-src/scripts`,
+    // or macOS /var → /private/var temp dirs) makes the raw URLs differ:
+    // import.meta.url is the resolved real path while argv[1] keeps the symlink
+    // path. Compare realpaths so the entry guard still fires (without this the
+    // dashboard regen silently no-ops when run through the symlink).
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    try {
+        process.exitCode = main();
+    } catch (exc) {
+        if (exc instanceof ArgparseExit) {
+            process.exitCode = exc.code;
+        } else {
+            throw exc;
+        }
+    }
+}
+
+export {
+    PhaseStats,
+    RoadmapStats,
+    CHECKBOX_RE,
+    PHASE_RE,
+    TITLE_RE,
+    FRONTMATTER_RE,
+    parse_frontmatter,
+    is_draft,
+    is_roadmap_candidate,
+    count_checkboxes,
+    parse_blockers,
+    parse_roadmap,
+    bar,
+    collect,
+    unarchived_complete,
+    merge_gated_pending,
+    pending_iron_law_3,
+    collect_bundles,
+    render,
+    main,
+    _pyRound,
+};
+export type { Bundle, Blocker };