@event4u/agent-config 14.12.0 → 14.14.0

package/dist/agent-src/scripts/archive_completed_roadmaps.ts

@@ -12,8 +12,8 @@
  * `urp.collect()` completion criterion, and exit code 0. snake_case kept.
  *
  * A roadmap that has reached `count_open == 0` and `count_deferred == 0` is
- * **complete**. This sweep moves it to `agents/roadmaps/archive/`, rewrites
- * inbound references (`agents/roadmaps/<x>.md` → `agents/roadmaps/archive/<x>.md`)
+ * **complete**. This sweep moves it to `agents/roadmaps/archive/`, rewrites code-comment-allow provenance-comment -- the sweep's own operand
+ * inbound references (`agents/roadmaps/<x>.md` → `agents/roadmaps/archive/<x>.md`) code-comment-allow provenance-comment -- the rewrite this sweep performs
  * across tracked files so links never break, and regenerates the dashboard.
  *
  * It replaces the old **merge-gate** (keep one item open + a manual post-merge
@@ -59,6 +59,7 @@ import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { collect } from './update_roadmap_progress.js';
+import { guardedBaselineProblems, parseGuardedBaselines } from './guarded_baseline.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 
@@ -135,7 +136,7 @@ function _branch_touched_paths(root: string, base: string): Set<string> | null {
  *
  * Two classes, and the second is why this predicate exists at all:
  *
- * - `agents/evidence/**` — a committed record of what was true, or of what a
+ * - `agents/evidence/**` — a committed record of what was true, or of what a code-comment-allow provenance-comment -- the predicate's operand set
  *   reviewer was shown, at one point in time. Retroactively editing it makes it
  *   claim something that did not happen, which is the failure
  *   `evaluator-independence` exists to prevent ("the prompt ships with the
@@ -144,8 +145,8 @@ function _branch_touched_paths(root: string, base: string): Set<string> | null {
  *   the payload. Rewriting them detaches the patch from the commit it records
  *   AND makes `git apply` target a path the diff never created.
  *
- * Measured 2026-08-11: archiving one roadmap rewrote four frozen artefacts
- * under `agents/evidence/reviews/`, including the `diff.patch` headers of a
+ * Measured 2026-08-11: archiving one roadmap rewrote four frozen artifacts
+ * under `agents/evidence/reviews/`, including the `diff.patch` headers of a code-comment-allow provenance-comment -- names what the predicate protects
  * recorded review input. Nothing caught it — the sweep reported it as
  * "4 ref(s) migrated", which reads like success.
  */
@@ -311,7 +312,202 @@ interface ArchiveRecord {
     refs_migrated: string[];
 }
 
-/** Archive every complete active roadmap (count_open==0, count_deferred==0). */
+
+/** One `[~]` step and whatever resolution annotation follows it. */
+export interface DeferredItem {
+    /** The step text, trimmed, for the operator message. */
+    text: string;
+    /** `carried-to` / `merged-into`, or `null` when no annotation was found. */
+    kind: 'carried-to' | 'merged-into' | null;
+    /** Destination roadmap slug, or `null`. */
+    destination: string | null;
+}
+
+/**
+ * `<!-- deferred-resolution: carried-to=<slug> -->` — the resolved-deferral
+ * annotation. `merged-into=<slug>` is the second accepted form.
+ */
+const DEFERRED_RESOLUTION_RE = /<!--\s*deferred-resolution:\s*(carried-to|merged-into)\s*=\s*([A-Za-z0-9._-]+)\s*-->/;
+
+/** `- [~] …` — a deferred step, at any indent, with `-` or `*`. */
+const DEFERRED_STEP_RE = /^[ \t]*[-*][ \t]+\[~\][ \t]*(.*)$/;
+/** Any other checkbox, or a heading — where a step's block ends. */
+const BLOCK_END_RE = /^[ \t]*[-*][ \t]+\[[ xX~-]\]|^#{1,6}[ \t]/;
+
+/** Escape a string for literal use inside a `RegExp`. */
+function _escapeRe(v: string): string {
+    return v.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Does this frontmatter declare a `relates:` row naming `slug`?
+ *
+ * Structured, not textual: the slug has to appear as a `- slug: <name>` row or a
+ * bare `- <name>` item inside the `relates:` block, which is a declaration the
+ * author made deliberately. A mention anywhere else in the file does not count.
+ */
+export function _relatesTo(text: string, slug: string): boolean {
+    const lines = text.split('\n');
+    const start = lines.findIndex((l) => /^relates:/.test(l));
+    if (start === -1) return false;
+    const re = new RegExp(`^\\s*-\\s*(slug:\\s*)?${_escapeRe(slug)}\\s*$`);
+    for (let i = start + 1; i < lines.length; i++) {
+        const line = lines[i] as string;
+        if (/^\S/.test(line)) break;
+        if (re.test(line)) return true;
+    }
+    return false;
+}
+
+/** Every `[~]` step in a roadmap, with the annotation that follows it (if any). */
+export function parseDeferredItems(text: string): DeferredItem[] {
+    const lines = text.split('\n');
+    const out: DeferredItem[] = [];
+    for (let i = 0; i < lines.length; i++) {
+        const m = DEFERRED_STEP_RE.exec(lines[i] as string);
+        if (m === null) continue;
+        // The annotation may sit on the step line itself or anywhere in the
+        // step's continuation block, which ends at the next checkbox or heading.
+        let block = lines[i] as string;
+        for (let j = i + 1; j < lines.length; j++) {
+            if (BLOCK_END_RE.test(lines[j] as string)) break;
+            block += '\n' + (lines[j] as string);
+        }
+        const a = DEFERRED_RESOLUTION_RE.exec(block);
+        out.push({
+            text: (m[1] ?? '').trim().slice(0, 120),
+            kind: a === null ? null : (a[1] as 'carried-to' | 'merged-into'),
+            destination: a === null ? null : (a[2] as string),
+        });
+    }
+    return out;
+}
+
+/**
+ * Decide whether a roadmap's `[~]` items are RESOLVED, per the AI council of
+ * 2026-08-27 (2 seats, convergent on option (c)).
+ *
+ * Iron Law 3 says a deferral must be resolved before archival, and the
+ * preservation test routes four dispositions to the council — but three of them
+ * (carry to a follow-up, merge into existing work, restore to open) leave the
+ * `[~]` glyph in place, and this sweep used to require `deferred === 0`
+ * unconditionally. So a genuinely UNEXECUTABLE item — one needing elapsed time
+ * rather than effort — had no council-reachable path to an archived roadmap, and
+ * the only glyph that cleared the gate was `[-]`, which is owner-reserved AND
+ * pinned to mean "won't happen at all". Using it for a carried item would make
+ * cancellation and transfer indistinguishable to every later reader.
+ *
+ * **Fail-closed at every step**, which is the condition both seats attached to
+ * their verdict: a bare `[~]` blocks, a malformed annotation blocks, a
+ * destination that does not exist blocks, a destination that is itself archived
+ * or skipped blocks, and a missing back-link blocks. The annotation is cheap to
+ * write and must therefore be expensive to satisfy.
+ *
+ * NOT checked, and named rather than implied: that the destination's copy of the
+ * criterion is faithful. Both seats asked for stable item identity over verbatim
+ * text matching, and neither a text match nor an id exists today — the back-link
+ * plus the source-slug mention is the strongest link this sweep can verify
+ * without inventing an identity scheme. The reviewer of the carry still reads it.
+ *
+ * @returns `problems` empty ⇒ every deferral is resolved and archival may proceed.
+ */
+export function deferralProblems(
+    root: string,
+    rel: string,
+    text: string,
+    /**
+     * Slugs this same sweep is about to archive. A destination in this set is
+     * about to become dead, so accepting it would leave the carried item with no
+     * live receiver — the exact loss the annotation exists to prevent, produced
+     * by the mechanism meant to prevent it. Found by an independent review, with
+     * two reproducers: a roadmap naming ITSELF as destination, and two roadmaps
+     * both complete in one run where the parent carries to the child.
+     *
+     * Optional so the unit tests can call this with one roadmap in view; the
+     * sweep always passes the real set.
+     */
+    alsoArchiving: ReadonlySet<string> = new Set(),
+): string[] {
+    const sourceSlug = rel.replace(/\.md$/, '');
+    const problems: string[] = [];
+    for (const item of parseDeferredItems(text)) {
+        const label = item.text === '' ? '(unnamed step)' : item.text;
+        if (item.kind === null || item.destination === null) {
+            problems.push(
+                `deferred step ${JSON.stringify(label)} carries no ` +
+                    '`<!-- deferred-resolution: carried-to=<slug> -->` annotation',
+            );
+            continue;
+        }
+        // Active or parked are both live. Archived and skipped are not: carrying
+        // an item into a dead roadmap is the silent loss the annotation exists
+        // to prevent, and it is exactly the "broken promise" case one seat asked
+        // to be detectable.
+        const candidates = [
+            path.join(root, 'agents', 'roadmaps', `${item.destination}.md`),
+            path.join(root, 'agents', 'roadmaps', 'later', `${item.destination}.md`),
+        ];
+        // Self-reference is never a carry. It passes every other check — the
+        // file exists, and a `parent_roadmap:` naming itself would satisfy the
+        // back-link — and then the sweep archives it, so the destination is dead
+        // the moment the source is.
+        if (item.destination === sourceSlug) {
+            problems.push(
+                `deferred step ${JSON.stringify(label)} names its OWN roadmap as the destination — ` +
+                    'a carry needs a different receiver, or the item is not carried at all',
+            );
+            continue;
+        }
+        if (alsoArchiving.has(item.destination)) {
+            problems.push(
+                `destination \`${item.destination}\` is being archived by this same sweep, so it would be ` +
+                    'dead the moment the carry lands — archive it first and re-run, or carry to a roadmap that stays active',
+            );
+            continue;
+        }
+        const found = candidates.find((c) => fs.existsSync(c));
+        if (found === undefined) {
+            const dead = ['archive', 'skipped'].find((d) =>
+                fs.existsSync(path.join(root, 'agents', 'roadmaps', d, `${item.destination ?? ''}.md`)),
+            );
+            problems.push(
+                dead === undefined
+                    ? `deferred step ${JSON.stringify(label)} names destination \`${item.destination}\`, which does not exist`
+                    : `deferred step ${JSON.stringify(label)} names destination \`${item.destination}\`, which is in \`${dead}/\` — a dead roadmap cannot receive a carried item`,
+            );
+            continue;
+        }
+        const destText = fs.readFileSync(found, 'utf-8');
+        // ESCAPED. The slug was interpolated raw, so `road.parent` matched
+        // `roadXparent` and a slug containing `[` or `(` made `new RegExp` THROW
+        // and abort the whole sweep — in a function whose entire contract is
+        // failing closed. Found by an independent review; both seats named it.
+        const backlink = new RegExp(`^parent_roadmap:[ \t]*${_escapeRe(sourceSlug)}[ \t]*$`, 'm');
+        if (item.kind === 'carried-to' && !backlink.test(destText)) {
+            problems.push(
+                `destination \`${item.destination}\` carries no \`parent_roadmap: ${sourceSlug}\` back-link — ` +
+                    'the link must be verifiable from both ends',
+            );
+            continue;
+        }
+        // A STRUCTURED link, not a substring. `destText.includes(sourceSlug)` was
+        // satisfied by any incidental mention — a filename, an example, an HTML
+        // comment — so `merged-into` proved nothing about a merge. Both review
+        // seats called it trivially spoofable. The link now has to be a
+        // frontmatter declaration: a `relates:` row naming the source, or a
+        // `parent_roadmap:` back-link. Prose cannot satisfy it.
+        if (item.kind === 'merged-into' && !backlink.test(destText) && !_relatesTo(destText, sourceSlug)) {
+            problems.push(
+                `destination \`${item.destination}\` carries no structured link back to \`${sourceSlug}\` — ` +
+                    'add a `relates:` row naming it (with a `relation:`) or a `parent_roadmap:` line. A mention ' +
+                    'in prose is not a link: it is satisfied by a filename or an example.',
+            );
+        }
+    }
+    return problems;
+}
+
+/** Archive every complete active roadmap: no open steps, and every `[~]` resolved. */
 function archive_completed(
     root: string,
     opts: { changed_only: boolean; base: string; dry_run: boolean },
@@ -331,11 +527,59 @@ function archive_completed(
         return [];
     }
 
+    // Every slug this sweep will consider archiving, computed BEFORE any of them
+    // is judged. Without it, a deferral carried to another roadmap that is also
+    // complete passes validation and then loses its receiver in the same run.
+    const sweepSet = new Set(
+        collect(roadmap_root)
+            .filter((s2) => s2.open_ === 0)
+            .map((s2) => s2.rel.replace(/\.md$/, '')),
+    );
+
     const archived: ArchiveRecord[] = [];
     for (const stats of collect(roadmap_root)) {
-        if (stats.open_ !== 0 || stats.deferred !== 0) {
+        // `guarded-baseline` is INCOMPLETE by construction (council 2026-08-31,
+        // 2/2 convergent) — checked BEFORE the open-step test on purpose. A
+        // well-formed record keeps its box `[ ]` and would be skipped silently as
+        // "not complete", which is the right verdict reached for the wrong reason
+        // and invisible in a sweep that only reports what it moved; a MALFORMED
+        // one on `[x]` would otherwise archive with an annotation claiming the
+        // opposite. Both are named here instead.
+        const guarded = parseGuardedBaselines(
+            fs.readFileSync(path.join(roadmap_root, stats.rel), 'utf-8'),
+        );
+        if (guarded.length > 0) {
+            process.stderr.write(
+                `  ⚠️  ${stats.rel}: ${guarded.length} guarded-baseline step(s) — ` +
+                    'not archived. Verify against the real mechanism, then flip to ' +
+                    '`[x]`.\n',
+            );
+            for (const p of guardedBaselineProblems(guarded)) {
+                process.stderr.write(`        · ${p}\n`);
+            }
+            continue;
+        }
+        if (stats.open_ !== 0) {
             continue; // not complete
         }
+        // A `[~]` no longer blocks unconditionally: it blocks unless it carries a
+        // validated resolution annotation. See `deferralProblems` for why, and
+        // for every way that check fails closed.
+        if (stats.deferred !== 0) {
+            const abs = path.join(roadmap_root, stats.rel);
+            // The source's own slug is removed: it is trivially in `sweepSet`,
+            // and self-reference is reported by its own, clearer message.
+            const others = new Set(sweepSet);
+            others.delete(stats.rel.replace(/\.md$/, ''));
+            const problems = deferralProblems(root, stats.rel, fs.readFileSync(abs, 'utf-8'), others);
+            if (problems.length > 0) {
+                process.stderr.write(
+                    `  ⚠️  ${stats.rel}: ${problems.length} unresolved deferral(s) — not archived.\n`,
+                );
+                for (const p of problems) process.stderr.write(`        · ${p}\n`);
+                continue;
+            }
+        }
         // An unresolved blocker outlives its steps. Closing every box does not
         // answer a question the roadmap raised for a human, and archiving on
         // step-count alone is how `b-highlights-mechanism` left the active tree
@@ -410,7 +654,7 @@ function _regen_dashboard(root: string, dry_run: boolean): void {
 /**
  * Rebuild the archive index after a move, when the builder is present.
  *
- * The sweep is the one operation that changes what `agents/roadmaps/archive/`
+ * The sweep is the one operation that changes what `agents/roadmaps/archive/` code-comment-allow provenance-comment -- the directory this function writes
  * contains, so it is the one operation that can leave the generated index
  * stale — and the drift gate on that index runs in the same PR the sweep runs
  * in. Regenerating here keeps the two from disagreeing by construction rather

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

@@ -0,0 +1,343 @@
+/**
+ * `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 a record carrying ONLY symbol tokens 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.
+ *
+ * A record whose trigger carries AT LEAST ONE path token is decided by that
+ * path and is NOT reported as unverifiable, even when a companion symbol token
+ * sits beside it. Reporting it would be the mirror of the failure above: a
+ * checked trigger that looks unchecked. Measured 2026-09-01 — three of the four
+ * lines the dashboard printed as "not machine-checkable" carried a path token
+ * and were therefore already decidable, which is noise that trains a reader to
+ * skip the section where the one genuinely undecidable trigger also lives.
+ */
+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;
+        }
+        const tokens = trigger.split(/[\s,]+/).filter((t) => t !== '');
+        const paths = tokens.filter((t) => t.includes('/'));
+        for (const token of paths) {
+            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',
+                );
+            }
+        }
+        if (paths.length > 0) {
+            continue;
+        }
+        for (const token of tokens) {
+            unverifiable.push(`line ${it.line} (${it.label}): recheck_when \`${token}\``);
+        }
+    }
+    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,
+    };
+}