@event4u/agent-config 14.12.0 → 14.13.0

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

@@ -0,0 +1,328 @@
+/**
+ * `guarded-baseline` — the third machine-readable step state, and its evidence
+ * contract (AI council 2026-08-31, 2/2 convergent: anthropic/claude-sonnet-4-5 +
+ * openai/codex-default, option C).
+ *
+ * A roadmap step whose `verify:` asserts a property of a mechanism that DOES NOT
+ * YET EXIST may not close `[x]` — that overstates the evidence. It keeps the
+ * canonical unchecked box, carries an annotation, and carries a structured
+ * evidence record next to it:
+ *
+ *     - [ ] <!-- roadmap-status: guarded-baseline -->
+ *           **7.3** …step text…
+ *           ```yaml
+ *           guarded_baseline:
+ *             category: future-mechanism
+ *             scope: src/scripts/ai_council/**
+ *             command: npx vitest run tests/scripts/x.test.ts
+ *             red_proof: sabotage run 2026-08-31 — 2 failed
+ *             sabotage_model: added a `--topology` flag to the option table
+ *             recheck_when: src/scripts/ai_council/topology_selector.ts
+ *             discharged_ac: the baseline is pinned and RED-proven
+ *             pending_ac: the constraint under real topology selection
+ *           ```
+ *
+ * BOTH SEATS MADE THE TOOLING A CONDITION OF THE VERDICT — "C is acceptable only
+ * if its tooling lands atomically; otherwise use ordinary `[ ]` with structured
+ * evidence" — so the annotation is worth nothing without the five semantics
+ * below, and they live here rather than duplicated in the two consumers:
+ *
+ *   1. reported separately and NEVER counted as done — the canonical box stays
+ *      `[ ]`, so `count_checkboxes` already excludes it; `reportGuardedBaselines`
+ *      is the separate surface that makes the state visible rather than silent;
+ *   2. `archive_completed_roadmaps` treats it as incomplete and refuses archival;
+ *   3. a `recheck_when` trigger that now RESOLVES in the tree marks the evidence
+ *      STALE — the guard was written against an absence that has since ended;
+ *   4. only verification against the real mechanism permits `[x]`;
+ *   5. a baseline that has not demonstrably gone RED is an ordinary open item —
+ *      hence `red_proof` is mandatory and its absence REJECTS the annotation.
+ *
+ * The two legal categories are the council's own split. An `absence-assertion`
+ * step asserts something directly observable today and MAY close `[x]` once
+ * sabotage-verified; a `future-mechanism` step is what this state exists for. No
+ * third value is accepted and absence is not defaulted: defaulting would silently
+ * promote the strict case into the lax one, which is the overstatement the whole
+ * verdict is against.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** The annotation itself. Tolerant of internal spacing, nothing else. */
+export const GUARDED_BASELINE_RE = /<!--[ \t]*roadmap-status:[ \t]*guarded-baseline[ \t]*-->/;
+
+/** The only two legal `category:` values — see the header on why absence is not a default. */
+export const GUARDED_CATEGORIES: readonly string[] = ['future-mechanism', 'absence-assertion'];
+
+/**
+ * `- [<glyph>] …` at any indent, with `-` or `*`.
+ *
+ * Deliberately neither of the two checkbox patterns already in this directory:
+ * the dashboard's `CHECKBOX_RE` is `g`-sticky and requires trailing whitespace,
+ * and the sweep's `DEFERRED_STEP_RE` pins `[~]`. This one has to CAPTURE the
+ * glyph an annotation sits on — including `[x]` — because refusing that case is
+ * the whole point of the validator below.
+ */
+const ANY_CHECKBOX_RE = /^[ \t]*[-*][ \t]+\[([ xX~-])\]/;
+
+/** A following step or any heading ends the annotated step's span. */
+const SPAN_END_RE = /^[ \t]*[-*][ \t]+\[[ xX~-]\]|^#{1,6}[ \t]/;
+
+const BLOCK_START_RE = /^[ \t]*guarded_baseline:[ \t]*$/;
+const FIELD_RE = /^[ \t]*([a-z_]+):[ \t]*(.*)$/;
+const FENCE_RE = /^[ \t]*(?:```|~~~)/;
+
+/**
+ * A record annotates a STEP, so it is only recognised on a list item.
+ *
+ * Measured, not defensive: without this the very roadmap that SPECIFIES this
+ * state reddened its own dashboard, because its verdict paragraph names the
+ * annotation in prose. Same discipline `parse_blockers` already applies with
+ * `_stripFencedCode` — a documentation example of a shape is not an instance of
+ * it — extended to the two prose forms that actually occur, an inline code span
+ * and a fenced example.
+ */
+const LIST_ITEM_RE = /^[ \t]*[-*][ \t]+/;
+const INLINE_CODE_RE = /`[^`]*`/g;
+
+/** One annotated step, as both consumers need it. */
+export interface GuardedBaselineItem {
+    /** 1-based line of the annotated line, for the messages. */
+    line: number;
+    /** Step text, from the annotated line or its first continuation line. */
+    label: string;
+    /**
+     * The checkbox glyph the annotation actually sits on, or `null` when the
+     * annotation is not on a checkbox line at all. Both non-`' '` and `null` are
+     * rejections — recorded rather than normalised, so the message can say which.
+     */
+    glyph: string | null;
+    /** Did the span carry a `guarded_baseline:` block at all? */
+    hasBlock: boolean;
+    fields: Readonly<Record<string, string>>;
+}
+
+function _label(annotatedLine: string, lines: readonly string[], i: number): string {
+    const own = annotatedLine
+        .replace(ANY_CHECKBOX_RE, '')
+        .replace(GUARDED_BASELINE_RE, '')
+        .replace(/\*\*/g, '')
+        .trim();
+    if (own !== '') {
+        return own;
+    }
+    // The council's mechanical form puts the step text on the NEXT line.
+    for (let j = i + 1; j < lines.length; j++) {
+        const next = (lines[j] as string).trim();
+        if (next === '') {
+            continue;
+        }
+        if (SPAN_END_RE.test(lines[j] as string)) {
+            break;
+        }
+        return next.replace(/\*\*/g, '').trim();
+    }
+    return '(unlabelled)';
+}
+
+/** Every `guarded-baseline`-annotated step in one roadmap, with its evidence block. */
+export function parseGuardedBaselines(text: string): GuardedBaselineItem[] {
+    const lines = text.split('\n');
+    const out: GuardedBaselineItem[] = [];
+    let inFence = false;
+    for (let i = 0; i < lines.length; i++) {
+        const raw = lines[i] as string;
+        if (FENCE_RE.test(raw)) {
+            inFence = !inFence;
+        }
+        // Inside a fence it is an example; inside backticks it is prose; off a
+        // list item it is not a step at all. See LIST_ITEM_RE for the measurement.
+        if (inFence || !LIST_ITEM_RE.test(raw)) {
+            continue;
+        }
+        if (!GUARDED_BASELINE_RE.test(raw.replace(INLINE_CODE_RE, ''))) {
+            continue;
+        }
+        const box = ANY_CHECKBOX_RE.exec(raw);
+        const fields: Record<string, string> = {};
+        let hasBlock = false;
+        for (let j = i + 1; j < lines.length; j++) {
+            const line = lines[j] as string;
+            if (SPAN_END_RE.test(line)) {
+                break; // the next step — this one's span is over
+            }
+            if (FENCE_RE.test(line)) {
+                continue; // a ```yaml wrapper is optional, and not the data
+            }
+            if (!hasBlock) {
+                hasBlock = BLOCK_START_RE.test(line);
+                continue;
+            }
+            const f = FIELD_RE.exec(line);
+            if (f) {
+                fields[f[1] as string] = (f[2] as string).trim();
+            }
+        }
+        out.push({
+            line: i + 1,
+            label: _label(raw, lines, i),
+            glyph: box ? (box[1] as string) : null,
+            hasBlock,
+            fields,
+        });
+    }
+    return out;
+}
+
+/**
+ * Every reason this annotation is REJECTED. Empty means the record is well
+ * formed — never that the acceptance criterion is discharged.
+ */
+export function guardedBaselineProblems(items: readonly GuardedBaselineItem[]): string[] {
+    const problems: string[] = [];
+    for (const it of items) {
+        const at = `line ${it.line} (${it.label})`;
+        if (it.glyph === null) {
+            problems.push(
+                `${at}: the guarded-baseline annotation is not on a checkbox step — ` +
+                    'it is only legal on an unchecked `- [ ]` line',
+            );
+        } else if (it.glyph !== ' ') {
+            problems.push(
+                `${at}: the guarded-baseline annotation sits on \`[${it.glyph}]\` — ` +
+                    'the canonical checkbox stays UNCHECKED; only verification against ' +
+                    'the real mechanism permits `[x]`',
+            );
+        }
+        if (!it.hasBlock) {
+            problems.push(`${at}: carries no adjacent \`guarded_baseline:\` evidence block`);
+        }
+        if ((it.fields['red_proof'] ?? '') === '') {
+            problems.push(
+                `${at}: records no \`red_proof\` — a baseline that has not demonstrably ` +
+                    'gone RED is an ordinary open item, not a guarded one',
+            );
+        }
+        const category = it.fields['category'] ?? '';
+        if (category === '') {
+            problems.push(
+                `${at}: records no \`category\` — one of ${GUARDED_CATEGORIES.join(', ')} ` +
+                    'is required, and absence is not defaulted',
+            );
+        } else if (!GUARDED_CATEGORIES.includes(category)) {
+            problems.push(
+                `${at}: records category \`${category}\`, which is not one of ` +
+                    GUARDED_CATEGORIES.join(', '),
+            );
+        }
+    }
+    return problems;
+}
+
+/**
+ * Which records are STALE, i.e. whose `recheck_when` trigger now resolves in the
+ * tree — the mechanism the baseline was written against has arrived, so the
+ * evidence describes a world that no longer exists.
+ *
+ * HONEST SCOPE. Only a PATH trigger is machine-checkable: a token containing `/`
+ * is resolved against the repo root and stale iff it exists. A bare symbol name
+ * cannot be decided from a path, so it is returned as `unverifiable` rather than
+ * silently reading as "not stale" — an unchecked trigger that looks checked is
+ * the failure this whole state exists to avoid.
+ */
+export function guardedBaselineStaleness(
+    items: readonly GuardedBaselineItem[],
+    repo_root: string,
+): { stale: string[]; unverifiable: string[] } {
+    const stale: string[] = [];
+    const unverifiable: string[] = [];
+    for (const it of items) {
+        const trigger = it.fields['recheck_when'] ?? '';
+        if (trigger === '') {
+            continue;
+        }
+        for (const token of trigger.split(/[\s,]+/).filter((t) => t !== '')) {
+            if (!token.includes('/')) {
+                unverifiable.push(`line ${it.line} (${it.label}): recheck_when \`${token}\``);
+            } else if (fs.existsSync(path.join(repo_root, token))) {
+                stale.push(
+                    `line ${it.line} (${it.label}): recheck_when \`${token}\` now exists — ` +
+                        're-verify against the real mechanism',
+                );
+            }
+        }
+    }
+    return { stale, unverifiable };
+}
+
+/** One roadmap, as the report needs it — structural, so `RoadmapStats` fits as-is. */
+export interface GuardedBaselineHost {
+    readonly rel: string;
+    readonly path: string;
+}
+
+export interface GuardedBaselineReport {
+    /** Dashboard section, appended to the rendered markdown. `''` when nothing is annotated. */
+    section: string;
+    /** Rejections across every roadmap — `--check` must fail on these. */
+    problems: number;
+}
+
+/**
+ * Report every guarded baseline in the estate: a dashboard section, and the
+ * rejections + staleness on stderr. Side-effecting on purpose, and named for it
+ * — the sibling `_warn_merge_gated` does the same, and it keeps the caller at
+ * one line in a file that sits at its size cap.
+ */
+export function reportGuardedBaselines(
+    roadmaps: readonly GuardedBaselineHost[],
+    repo_root: string,
+    write: (s: string) => void = (s) => process.stderr.write(s),
+): GuardedBaselineReport {
+    const rows: string[] = [];
+    let problems = 0;
+    for (const r of roadmaps) {
+        let items: GuardedBaselineItem[];
+        try {
+            items = parseGuardedBaselines(fs.readFileSync(r.path, { encoding: 'utf-8' }));
+        } catch {
+            continue;
+        }
+        if (items.length === 0) {
+            continue;
+        }
+        const bad = guardedBaselineProblems(items);
+        const { stale, unverifiable } = guardedBaselineStaleness(items, repo_root);
+        problems += bad.length;
+        rows.push(
+            `| [${r.rel}](roadmaps/${r.rel}) | ${items.length} | ${stale.length} | ${bad.length} |`,
+        );
+        write(
+            `🛡️   ${r.rel}: ${items.length} guarded-baseline step(s) — RED-proven, ` +
+                'NOT complete, and blocking archival:\n',
+        );
+        for (const it of items) {
+            write(`      - ${it.label}  (category ${it.fields['category'] ?? '—'})\n`);
+        }
+        for (const p of bad) write(`      ❌ ${p}\n`);
+        for (const s of stale) write(`      ⚠️  ${s}\n`);
+        for (const u of unverifiable) write(`      ·  not machine-checkable: ${u}\n`);
+    }
+    if (rows.length === 0) {
+        return { section: '', problems };
+    }
+    return {
+        section:
+            '\n## 🛡️ Guarded baselines — RED-proven, not complete\n\n' +
+            'These steps carry `<!-- roadmap-status: guarded-baseline -->`: an ' +
+            'executable guard exists and has been shown to go RED under a named ' +
+            'sabotage, but the acceptance criterion names a mechanism that does not ' +
+            'exist yet. They are **not** done, they are **not** counted as done, and ' +
+            'they **block archival** until the real mechanism is verified (council ' +
+            '2026-08-31, 2/2 convergent).\n\n' +
+            '| Roadmap | Guarded | Stale | Rejected |\n|---|---:|---:|---:|\n' +
+            rows.join('\n') +
+            '\n',
+        problems,
+    };
+}

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

@@ -0,0 +1,253 @@
+#!/usr/bin/env tsx
+/**
+ * The single sanctioned writer of a roadmap checkbox glyph.
+ *
+ * `road-to-skill-ecosystem-runtime-enforcement` Phase 6. Every mechanism here
+ * exists because of a recorded way a concurrent writer destroys work, and each
+ * one is listed with the failure it closes rather than as a good practice:
+ *
+ *   1. **Advisory lock + atomic rename.** Two writers read, edit and write the
+ *      same file; the second write lands last and the first writer's step is
+ *      gone, with no error to either. A torn write is worse still: a
+ *      half-rewritten plan parses as a plan with fewer steps.
+ *   2. **Anchor on the step's OWN LINE.** A greedy multi-line pattern across a
+ *      multi-entry file is the recorded mechanism by which one substitution
+ *      overwrites later entries — the regex matches from the first step to the
+ *      last and replaces everything between.
+ *   3. **Structural invariant against the LIVE pre-write file.** Asserting the
+ *      step count against an in-memory snapshot confirms what you INTENDED to
+ *      write while destroying what a parallel writer wrote in between. The
+ *      re-read is the whole point: the file is checked at the moment of writing.
+ *   4. **Post-write survival check.** In a concurrent overwrite the loser gets
+ *      no error, so a successful write is not evidence the write survived.
+ *      Grep for the mutated step afterwards and confirm exactly one occurrence.
+ *   5. **Fail closed on ambiguity.** Two roadmaps in scope — one in the working
+ *      directory, one nested — resolve NEITHER and name both. Silently choosing
+ *      is how a step gets flipped in the wrong plan.
+ *
+ * Exit codes: 0 written · 1 refused (ambiguity, invariant, survival) · 2 usage.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+
+/** The four glyphs a roadmap step may carry. */
+export const GLYPHS = ['x', ' ', '~', '-'] as const;
+export type Glyph = (typeof GLYPHS)[number];
+
+/** A lock older than this is treated as abandoned. A crashed writer must not wedge the file. */
+export const LOCK_STALE_MS = 60_000;
+
+export class RoadmapWriteError extends Error {}
+
+/** Every checkbox line in the file, as `[lineIndex, glyph, text]`. */
+export function scanSteps(content: string): { line: number; glyph: string; text: string }[] {
+    const out: { line: number; glyph: string; text: string }[] = [];
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i += 1) {
+        const m = /^(\s*-\s\[)([ x~-])(\]\s?)(.*)$/.exec(lines[i] as string);
+        if (m !== null) out.push({ line: i, glyph: m[2] as string, text: m[4] as string });
+    }
+    return out;
+}
+
+/**
+ * Locate the ONE step whose text starts with `stepId`.
+ *
+ * Refuses on zero and on more than one. A prefix that matches two steps is an
+ * ambiguous address, and picking the first is the same silent-choice failure as
+ * resolving an ambiguous plan.
+ */
+export function findStep(content: string, stepId: string): { line: number; glyph: string; text: string } {
+    const needle = stepId.trim();
+    if (needle === '') throw new RoadmapWriteError('step id is empty');
+    // Match against the raw text AND its bold-stripped form, so `**1.2` and `1.2`
+    // both address the same step. Stripping only ONE side is the bug this shape
+    // replaces: a needle carrying `**` then matched nothing at all.
+    const strip = (t: string): string => t.replace(/^\*\*/, '');
+    const hits = scanSteps(content).filter(
+        (s) => s.text.startsWith(needle) || strip(s.text).startsWith(strip(needle)),
+    );
+    if (hits.length === 0) {
+        throw new RoadmapWriteError(`no step whose text starts with "${needle}"`);
+    }
+    if (hits.length > 1) {
+        throw new RoadmapWriteError(
+            `"${needle}" matches ${String(hits.length)} steps (lines ${hits.map((h) => h.line + 1).join(', ')}) — ` +
+                'refusing rather than picking the first. Give a longer prefix.',
+        );
+    }
+    return hits[0]!;
+}
+
+/**
+ * Rewrite ONE line's glyph. Line-anchored by construction: the function is given
+ * a line index and touches only `lines[index]`, so there is no pattern that can
+ * span entries even in principle.
+ */
+export function setGlyphOnLine(content: string, lineIndex: number, glyph: Glyph): string {
+    const lines = content.split('\n');
+    const line = lines[lineIndex];
+    if (line === undefined) throw new RoadmapWriteError(`line ${String(lineIndex)} is out of range`);
+    const m = /^(\s*-\s\[)([ x~-])(\].*)$/.exec(line);
+    if (m === null) throw new RoadmapWriteError(`line ${String(lineIndex + 1)} is not a checkbox line`);
+    lines[lineIndex] = `${m[1]}${glyph}${m[3]}`;
+    return lines.join('\n');
+}
+
+/** Acquire an advisory lock, or throw. `O_EXCL` is the exclusion; the mtime is the staleness clock. */
+export function acquireLock(file: string, nowMs = Date.now()): string {
+    const lock = `${file}.lock`;
+    try {
+        fs.writeFileSync(lock, `${String(process.pid)}\n`, { flag: 'wx' });
+        return lock;
+    } catch {
+        let age = 0;
+        try {
+            age = nowMs - fs.statSync(lock).mtimeMs;
+        } catch {
+            // The holder released it between our failed create and this stat —
+            // retry once rather than reporting a lock that no longer exists.
+            fs.writeFileSync(lock, `${String(process.pid)}\n`, { flag: 'wx' });
+            return lock;
+        }
+        if (age > LOCK_STALE_MS) {
+            // A crashed writer must not wedge the file forever. Breaking a stale
+            // lock is safe precisely because every write below re-validates the
+            // live file — the lock reduces collisions, it does not carry
+            // correctness on its own.
+            fs.rmSync(lock, { force: true });
+            fs.writeFileSync(lock, `${String(process.pid)}\n`, { flag: 'wx' });
+            return lock;
+        }
+        throw new RoadmapWriteError(
+            `${path.basename(file)} is locked by another writer (${String(Math.round(age / 1000))}s old) — refusing`,
+        );
+    }
+}
+
+export interface SetStepResult {
+    file: string;
+    line: number;
+    from: string;
+    to: Glyph;
+    stepsBefore: number;
+    stepsAfter: number;
+}
+
+/**
+ * Flip one step's glyph, safely.
+ *
+ * The ordering is the contract: lock → RE-READ → locate → invariant → write →
+ * survival check → unlock. The re-read after the lock is what makes the
+ * invariant meaningful; checking a snapshot taken before the lock would confirm
+ * an intention rather than a fact.
+ */
+export function setStep(file: string, stepId: string, glyph: Glyph, nowMs = Date.now()): SetStepResult {
+    const lock = acquireLock(file, nowMs);
+    try {
+        // LIVE read, inside the lock. Any snapshot taken earlier is stale by
+        // definition — a parallel writer may have landed between then and now.
+        const before = fs.readFileSync(file, 'utf8');
+        const stepsBefore = scanSteps(before).length;
+        const target = findStep(before, stepId);
+        const after = setGlyphOnLine(before, target.line, glyph);
+
+        const stepsAfter = scanSteps(after).length;
+        if (stepsAfter !== stepsBefore) {
+            throw new RoadmapWriteError(
+                `structural invariant failed: ${String(stepsBefore)} step(s) before, ${String(stepsAfter)} after. ` +
+                    'A glyph flip may not change the step count — this is the signature of a pattern ' +
+                    'that spanned entries.',
+            );
+        }
+
+        const tmp = `${file}.${String(process.pid)}.tmp`;
+        fs.writeFileSync(tmp, after, 'utf8');
+        fs.renameSync(tmp, file);
+
+        // SURVIVAL, not success. In a concurrent overwrite the loser receives no
+        // error, so the write returning is not evidence the write is on disk.
+        const verify = fs.readFileSync(file, 'utf8');
+        const survivors = scanSteps(verify).filter(
+            (s) => s.line === target.line && s.glyph === glyph && s.text === target.text,
+        );
+        if (survivors.length !== 1) {
+            throw new RoadmapWriteError(
+                `write did not survive: expected exactly 1 occurrence of the mutated step, found ` +
+                    `${String(survivors.length)}. A parallel writer very likely landed after ours.`,
+            );
+        }
+        return { file, line: target.line + 1, from: target.glyph, to: glyph, stepsBefore, stepsAfter };
+    } finally {
+        fs.rmSync(lock, { force: true });
+    }
+}
+
+/**
+ * Resolve the roadmap to write, FAILING CLOSED on ambiguity.
+ *
+ * When the working directory carries an active roadmap and a nested directory
+ * carries its own, neither is resolved and both are named. Choosing silently is
+ * how a step gets flipped in the wrong plan — and the wrong plan's author gets
+ * no signal at all.
+ */
+export function resolvePlan(roots: readonly string[]): string {
+    const found: string[] = [];
+    for (const root of roots) {
+        const dir = path.join(root, 'agents', 'roadmaps');
+        if (!fs.existsSync(dir)) continue;
+        for (const name of fs.readdirSync(dir)) {
+            if (name.endsWith('.md') && name !== 'README.md') found.push(path.join(dir, name));
+        }
+    }
+    if (found.length === 0) throw new RoadmapWriteError('no active roadmap found under any candidate root');
+    if (found.length > 1) {
+        throw new RoadmapWriteError(
+            `ambiguous plan — ${String(found.length)} active roadmaps in scope:\n  ${found.join('\n  ')}\n` +
+                'Refusing to choose. Name the file explicitly with --file.',
+        );
+    }
+    return found[0]!;
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    const usage =
+        'usage: roadmap_set_step --file <roadmap.md> --step <id-prefix> --glyph <x| |~|->\n' +
+        '  Refuses on: an ambiguous step prefix, a changed step count, a write that did not survive.\n';
+    if (argv.includes('-h') || argv.includes('--help')) {
+        process.stdout.write(usage);
+        return 0;
+    }
+    const val = (flag: string): string | null => {
+        const i = argv.indexOf(flag);
+        return i !== -1 && i + 1 < argv.length ? (argv[i + 1] as string) : null;
+    };
+    const file = val('--file');
+    const step = val('--step');
+    const glyph = val('--glyph');
+    if (file === null || step === null || glyph === null || !(GLYPHS as readonly string[]).includes(glyph)) {
+        process.stderr.write(`roadmap_set_step: error: --file, --step and a valid --glyph are required\n${usage}`);
+        return 2;
+    }
+    try {
+        const r = setStep(path.resolve(file), step, glyph as Glyph);
+        process.stdout.write(
+            `✅  ${path.basename(r.file)}:${String(r.line)} [${r.from}] → [${r.to}] · ` +
+                `${String(r.stepsAfter)} step(s) intact\n`,
+        );
+        return 0;
+    } catch (e) {
+        process.stderr.write(`❌  ${e instanceof Error ? e.message : String(e)}\n`);
+        return e instanceof RoadmapWriteError ? 1 : 2;
+    }
+}
+
+/* c8 ignore start */
+if (process.argv[1] !== undefined && pathToFileURL(path.resolve(process.argv[1])).href === pathToFileURL(_HERE).href) {
+    process.exit(main());
+}
+/* c8 ignore stop */

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

@@ -0,0 +1,82 @@
+/**
+ * The parked estate's two integers, for the dashboard header.
+ *
+ * `road-to-inbox-harvest-2026-08-f-owner-decision-queue` Phase 2.3. Split out of
+ * `update_roadmap_progress.ts` rather than left inline, and the reason is
+ * mechanical: that file is past the 1500-line ceiling
+ * `check_source_size_budget` charges, so lines added to it are paid back by
+ * extraction rather than by a baseline bump.
+ *
+ * **Two integers are not an inventory.** No row, no link, nothing to conflict
+ * on — which is exactly the distinction that keeps this clear of the 2026-08-21
+ * council verdict that deleted the hand-maintained index in `stubs/README.md`,
+ * and of `check_no_stub_inventory_table`, which refuses its return.
+ *
+ * The dashboard excludes `stubs/` on purpose and that does not change. What was
+ * missing is that a maintainer had no way to learn a stub had gone unread
+ * without listing the directory.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** Frontmatter block, matching the parent script's own pattern. */
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---[ \t\n\r\f\v]*\n/;
+
+/**
+ * Phrases that mean "a person has to decide this".
+ *
+ * A literal list, never a heuristic: a general "looks like a decision" match
+ * would count every stub that mentions the word, and a count that over-reports
+ * is a count nobody trusts twice. Kept in sync with `stubs_due.ts` by the test
+ * that asserts both readers agree on the same corpus.
+ */
+const OWNER_ROUTING = [
+    'owner-reserved',
+    'owner reserved',
+    'owner: maintainer',
+    'reserved to the owner',
+    'requires owner',
+    'maintainer decision',
+    'owner decision',
+    'owner sign-off',
+    'awaiting the owner',
+];
+
+/**
+ * Count overdue stubs and stubs routing a decision to a person.
+ *
+ * Returns `null` on any failure — a dashboard is not the place to surface a
+ * parse error, and an absent `stubs/` directory in a consumer install is normal
+ * rather than a fault. `today` is a parameter so the count is testable.
+ */
+export function stub_queue_counts(
+    roadmap_root: string,
+    today: string = new Date().toISOString().slice(0, 10),
+): { overdue: number; owner: number } | null {
+    const dir = path.join(roadmap_root, 'stubs');
+    let names: string[];
+    try {
+        names = fs.readdirSync(dir).filter((n) => n.endsWith('.md') && n !== 'README.md');
+    } catch {
+        return null;
+    }
+    if (names.length === 0) return null;
+    let overdue = 0;
+    let owner = 0;
+    for (const n of names) {
+        let source: string;
+        try {
+            source = fs.readFileSync(path.join(dir, n), 'utf-8');
+        } catch {
+            continue;
+        }
+        const fm = FRONTMATTER_RE.exec(source);
+        const due = /^review_by:\s*(\d{4}-\d{2}-\d{2})\s*$/m.exec(fm?.[1] ?? '');
+        // An ABSENT date counts as overdue: the contract requires it, so missing
+        // means nobody scheduled a read — the state the count exists to surface.
+        if (due === null || (due[1] as string) <= today) overdue += 1;
+        const lower = source.toLowerCase();
+        if (OWNER_ROUTING.some((phrase) => lower.includes(phrase))) owner += 1;
+    }
+    return { overdue, owner };
+}