@event4u/agent-config 14.6.0 → 14.7.0

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

@@ -22,11 +22,17 @@
  *     instead of one entry.
  *   - **No resolve on failure.** A non-zero exit reports and changes nothing.
  *     A gate marked resolved by a command that failed is worse than an open one.
- *   - **No invented ledger.** Class 1 needs a standing budget, and the shape of
- *     that budget is an OPEN maintainer decision (`b-gate-budget-preauth`).
- *     Until it is taken there is no ledger, so class 1 takes the
- *     render-instead-of-run path — which is the behaviour the blocker itself
- *     prescribes for a missing ledger, not a stub of the decision.
+ *   - **No spend outside the standing budget.** Class 1 runs only under the
+ *     caps `b-gate-budget-preauth` decided (option (a), 2026-08-20): a per-run
+ *     cap AND a rolling-7-day cap, with an append-only receipt as the audit
+ *     surface. No caps configured, no USD estimate in the entry, over either
+ *     cap — every one of those RENDERS instead of running, which is the
+ *     behaviour the blocker itself prescribes for a missing ledger.
+ *   - **No consent from the ledger.** The receipt records CONSUMPTION only.
+ *     `agents/runtime/state/` is agent-writable, so reading an "authorisation"
+ *     out of it would be the agent consenting on the user's behalf — the exact
+ *     threat model the live-trigger-eval terminal abort exists for. `--confirm`
+ *     remains the consent on every class-1 run.
  *   - **No class-3 change.** The class-3 branch executes nothing and writes
  *     nothing, so `agent-config gates` renders a class-3 entry exactly as it did
  *     before this module existed. `--execute` on one returns a one-line notice
@@ -35,8 +41,9 @@
  *     markdown field. Without the flag the command is echoed and refused, so
  *     the operator sees the exact string first — the this-turn, names-the-object
  *     confirmation `non-destructive-by-default` requires. A command carrying a
- *     Hard-Floor action is refused even WITH the flag: class 0 means reversible,
- *     so such an entry is misclassified rather than merely dangerous.
+ *     Hard-Floor action is refused even WITH the flag: classes 0 and 1 are both
+ *     defined as reversible, so such an entry is misclassified rather than
+ *     merely dangerous.
  */
 
 import * as fs from 'node:fs';
@@ -44,15 +51,24 @@ import * as path from 'node:path';
 import { spawnSync } from 'node:child_process';
 
 import { collect, blocker_class, type Blocker } from './update_roadmap_progress.js';
+import {
+    appendGateBudgetReceipt,
+    evaluateGateBudget,
+    GATE_BUDGET_LEDGER_REL,
+    parseBudgetUsd,
+    readGateBudgetCaps,
+    readGateBudgetLedger,
+} from './gate_budget.js';
+import { load_agent_settings } from '../templates/scripts/work_engine/_lib/agent_settings.js';
 
 /**
- * Where a class-1 receipt ledger would live once the budget decision is taken.
+ * Where the class-1 receipt ledger lives.
  *
- * Named here so the absent-ledger branch has something concrete to report, and
- * deliberately NOT created: the path is a consequence of the decision, and
- * writing it now would answer a question that is still the maintainer's.
+ * Kept as a name here because it was already exported, but the definition
+ * moved to `gate_budget.ts` when the budget decision landed — one path, one
+ * builder, so a relocation cannot leave a second joiner behind.
  */
-const LEDGER_REL = path.join('agents', 'runtime', 'state', 'gate-budget-ledger.jsonl');
+const LEDGER_REL = GATE_BUDGET_LEDGER_REL;
 
 type Outcome = 'resolved' | 'failed' | 'rendered' | 'not-found';
 
@@ -260,6 +276,7 @@ function execute(
     }
     const { blocker, file, rel } = found;
     const cls = blocker_class(blocker);
+    const repoRoot = path.dirname(path.dirname(roadmapRoot));
 
     if (cls === '3') {
         // Byte-identical to today by construction: nothing is executed and
@@ -273,28 +290,32 @@ function execute(
     if (cls === '2') {
         return { outcome: 'rendered', report: consentLine(blocker), code: 0 };
     }
+    // Class 1 runs under the standing budget decided by `b-gate-budget-preauth`
+    // option (a): a per-run cap AND a rolling-7-day cap, with an append-only
+    // receipt as the audit surface. Every refusal path RENDERS rather than
+    // running — the blocker's own prescription for a missing ledger,
+    // generalised to every way the budget can say no. The `--confirm`
+    // requirement below is untouched: the caps bound the size of an authorised
+    // spend, they never supply the authorisation.
+    let budgeted: { estimateUsd: number } | null = null;
     if (cls === '1') {
-        const ledger = path.join(path.dirname(path.dirname(roadmapRoot)), LEDGER_REL);
-        if (!fs.existsSync(ledger)) {
-            // The blocker's own prescription for a missing ledger: render the
-            // consent line INSTEAD of running. Not a degraded mode — the
-            // budget shape is an open decision and this is what open means.
+        const verdict = evaluateGateBudget({
+            caps: readGateBudgetCaps(load_agent_settings({ cwd: repoRoot })),
+            records: readGateBudgetLedger(repoRoot),
+            estimateUsd: parseBudgetUsd(blocker.budget),
+            now,
+        });
+        if (!verdict.ok) {
             return {
                 outcome: 'rendered',
                 report: consentLine(
                     blocker,
-                    'class 1 with no budget ledger, so it renders instead of running',
+                    `class 1 and ${verdict.detail}, so it renders instead of running`,
                 ),
                 code: 0,
             };
         }
-        return {
-            outcome: 'rendered',
-            report:
-                `${id} is class 1 and a ledger exists at ${LEDGER_REL}, but spend execution ` +
-                'is gated on `b-gate-budget-preauth`, which is open. Rendering instead of running.\n',
-            code: 0,
-        };
+        budgeted = { estimateUsd: verdict.estimateUsd };
     }
 
     const command = commandOf(blocker);
@@ -304,7 +325,7 @@ function execute(
         // and guessing a command here is the one thing that must not happen.
         return {
             outcome: 'failed',
-            report: `${id} is class 0 but carries no **Run:** command. Nothing was executed.\n`,
+            report: `${id} is class ${cls} but carries no **Run:** command. Nothing was executed.\n`,
             code: 1,
         };
     }
@@ -318,9 +339,9 @@ function execute(
         return {
             outcome: 'failed',
             report:
-                `${id} is class 0 but its **Run:** command contains \`${floor}\`, which is a ` +
-                'Hard-Floor action under non-destructive-by-default. Class 0 means ' +
-                'deterministic, free and REVERSIBLE, so this entry is misclassified. ' +
+                `${id} is class ${cls} but its **Run:** command contains \`${floor}\`, which is a ` +
+                'Hard-Floor action under non-destructive-by-default. Classes 0 and 1 are ' +
+                'both defined as REVERSIBLE, so this entry is misclassified. ' +
                 'Nothing was executed; re-author the class.\n',
             code: 1,
         };
@@ -333,7 +354,7 @@ function execute(
         return {
             outcome: 'rendered',
             report:
-                `${id} is class 0 and would run, from the repo root:\n\n` +
+                `${id} is class ${cls} and would run, from the repo root:\n\n` +
                 `    ${command}\n\n` +
                 'Nothing has been executed. Re-run with `--confirm` to execute it and ' +
                 'record the evidence at the blocker.\n',
@@ -344,7 +365,7 @@ function execute(
     const r = spawnSync(command, {
         shell: true,
         encoding: 'utf-8',
-        cwd: path.dirname(path.dirname(roadmapRoot)),
+        cwd: repoRoot,
         timeout: 120_000,
     });
     const output = `${r.stdout ?? ''}${r.stderr ?? ''}`;
@@ -367,6 +388,22 @@ function execute(
             code: 1,
         };
     }
+    if (budgeted !== null) {
+        // Written BEFORE the file rewrite: an unreceipted spend is invisible to
+        // the rolling cap, and the cap failing open is the one way this
+        // mechanism could become a blank cheque. `actual_usd` is null because
+        // nothing on this path observes the provider's billed amount — the
+        // estimate is what the cap compared against and what it records.
+        appendGateBudgetReceipt(repoRoot, {
+            kind: 'consumption',
+            blocker: id,
+            authorization: 'confirm-flag',
+            estimated_usd: budgeted.estimateUsd,
+            actual_usd: null,
+            at: now.toISOString(),
+            single_use: true,
+        });
+    }
     const when = today(now);
     if (!appendEvidence(file, id, command, output, when)) {
         return {
@@ -382,6 +419,10 @@ function execute(
         report:
             `${id} resolved. Ran \`${command}\` (exit 0); evidence appended in ${rel} ` +
             `and the status flipped to resolved ${when}.\n` +
+            (budgeted === null
+                ? ''
+                : `Receipt appended to ${LEDGER_REL} ` +
+                  `($${budgeted.estimateUsd.toFixed(2)} estimated).\n`) +
             // The dashboard is derived from the file this just rewrote, so it
             // is now stale. Saying so is the same follow-up `renderResumed`
             // already prints for its own file-move suggestion.

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

@@ -427,13 +427,83 @@ export function sheetQuestion(b: Blocker): { text: string; source: 'question' |
  * none is recorded it says so and names what the reader must supply, so
  * regenerating the sheet cannot silently overwrite an answer with a guess.
  */
-function renderSheet(entries: readonly Entry[], now: Date): string {
+/**
+ * The recorded answer to the consolidated decision sheet.
+ *
+ * The sheet is DERIVED, so an answer written into it is lost on the next run —
+ * the file says so in its own header. But `road-to-estate-drawdown` blocker
+ * `b-consolidated-decision-sheet` resolves only when "the sheet records which
+ * option was used", and a derived file cannot carry that by being edited. So the
+ * option lives in a NON-derived sibling and the sheet reads it, which keeps the
+ * sheet deterministic and still lets it state the answer.
+ *
+ * Read, never written, and absent is a first-class answer: no marker means the
+ * sheet renders exactly as before, so this is additive to every existing caller.
+ */
+interface SheetAnswer {
+    option: string;
+    answered: string;
+    authority: string;
+}
+
+const SHEET_ANSWER_REL = path.join('agents', 'decisions', 'consolidated-decision-sheet-answer.md');
+
+/**
+ * One line, three fields, all required — a partial marker is treated as absent
+ * rather than rendered half-filled, because a header that named an option with
+ * no date or authority would be less honest than one that says nothing.
+ */
+const SHEET_ANSWER_RE =
+    /<!--\s*sheet-answer:\s*(.+?)\s*\|\s*answered:\s*(\d{4}-\d{2}-\d{2})\s*\|\s*authority:\s*(\S+)\s*-->/;
+
+export function readSheetAnswer(repoRoot: string): SheetAnswer | null {
+    const file = path.join(repoRoot, SHEET_ANSWER_REL);
+    let text: string;
+    try {
+        text = fs.readFileSync(file, 'utf8');
+    } catch {
+        return null;
+    }
+    const m = SHEET_ANSWER_RE.exec(text);
+    if (m === null) {
+        return null;
+    }
+    return {
+        option: (m[1] as string).trim(),
+        answered: (m[2] as string).trim(),
+        authority: (m[3] as string).trim(),
+    };
+}
+
+/** The header block naming the recorded answer, or nothing when none is recorded. */
+function answerBanner(answer: SheetAnswer | null): string[] {
+    if (answer === null) {
+        return [];
+    }
+    return [
+        '>',
+        `> **ANSWERED ${answer.answered} — ${answer.option}.**`,
+        `> Recorded in \`${SHEET_ANSWER_REL}\` (not derived);`,
+        `> authority \`${answer.authority}\`.`,
+        '> The rows below are the ones still OPEN: an answered',
+        '> row stays here until the work its own entry names is done, so this is a work',
+        '> queue and not a count of unanswered questions.',
+    ];
+}
+
+function renderSheet(
+    entries: readonly Entry[],
+    now: Date,
+    answer: SheetAnswer | null = null,
+): string {
     const mine = entries.filter((e) => needsUser(e.blocker.owner));
     const stamp = now.toISOString().slice(0, 10);
     if (mine.length === 0) {
+        const banner = answerBanner(answer);
         return (
             `# Consolidated decision sheet — nothing owned by you (${stamp})\n\n` +
-            'No open blocker in the active roadmap tree carries `Owner: user`. Nothing to answer.\n'
+            'No open blocker in the active roadmap tree carries `Owner: user`. Nothing to answer.\n' +
+            (banner.length === 0 ? '' : '\n' + banner.slice(1).join('\n') + '\n')
         );
     }
 
@@ -461,6 +531,7 @@ function renderSheet(entries: readonly Entry[], now: Date): string {
         '> This file is DERIVED — every line above and below comes from the roadmaps themselves,',
         '> so regenerating is deterministic and an answer written into this file would be lost.',
         '> Answers go back into each roadmap at its own blocker; the agent does that.',
+        ...answerBanner(answer),
         '',
         '| # | Decision | Roadmap | Unblocks | Default source |',
         '|---:|---|---|---:|---|',
@@ -847,7 +918,7 @@ function main(argv?: readonly string[]): number {
     const resumed = reply || sheet ? [] : probeLater(roadmapRoot, repoRoot);
     process.stdout.write(
         sheet
-            ? renderSheet(entries, new Date())
+            ? renderSheet(entries, new Date(), readSheetAnswer(repoRoot))
             : reply
               ? renderReply(entries)
               : json

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

@@ -32,8 +32,12 @@
  *
  * 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 --archive    # rewrite + archive completed
  *   node node_modules/.bin/tsx .augment/scripts/update_roadmap_progress.ts --check      # CI: exit 1 if stale
  *
+ * `--archive` is opt-in and `--check` refuses it; the full contract, the
+ * council record and the sweep spawner live in `archival_sweep.ts`.
+ *
  * --- Parity notes (ADR-200) ---
  *
  * - Python `round()` is banker's rounding (round-half-to-even). Percentages and
@@ -59,6 +63,7 @@ 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 { run_archival_sweep } from './archival_sweep.js';
 import type * as YamlModule from 'yaml';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -280,12 +285,21 @@ 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);
+/**
+ * The NAME half of the candidate test. Split out because the parked inventory
+ * reads `later/` on purpose and `is_roadmap_candidate` rejects any path carrying
+ * an excluded component — `later` included. Sharing this half keeps
+ * `later/README.md` excluded from both sides by one rule rather than two.
+ */
+function is_roadmap_name(name: string): boolean {
     if (EXCLUDE_NAMES.has(name)) {
         return false;
     }
-    if (EXCLUDE_PREFIXES.some((pre) => name.startsWith(pre))) {
+    return !EXCLUDE_PREFIXES.some((pre) => name.startsWith(pre));
+}
+
+function is_roadmap_candidate(p: string): boolean {
+    if (!is_roadmap_name(path.basename(p))) {
         return false;
     }
     // path.parts — every component of the path; exclude if any is an excluded dir.
@@ -741,6 +755,140 @@ function collect(roadmap_root: string): RoadmapStats[] {
     return results;
 }
 
+/** One parked roadmap, as the inventory needs it. */
+interface ParkedRoadmap {
+    rel: string;
+    resume: string | null;
+    /** Only the linter's looser marker matched — CI passes, the cell cannot quote. */
+    unlabelled: boolean;
+    /** Open blockers still carried by the parked file. */
+    open_blockers: number;
+    /** Of those, the ones whose owner is the user. */
+    needs_user: number;
+}
+
+/**
+ * A line that STATES when the roadmap comes back. Two tiers exist because
+ * `lint_roadmap_later_disposition` accepts a bare `trigger`, which is too loose to
+ * quote from — measured over the live tree it matched a `Source:` path containing
+ * `mixed-trigger-cleanup`, producing cells that were wrong rather than short.
+ */
+const RESUME_STATEMENT = /\b(blocked until|resume when|resume-when|blocked-until)\b/i;
+
+/**
+ * The linter's looser vocabulary. A file matching only this DOES carry a resume
+ * condition as far as CI is concerned, so reporting it as missing would make the
+ * dashboard contradict a gate that already passed.
+ */
+const RESUME_LOOSE = /\btrigger\b/i;
+
+/**
+ * Parked roadmaps, with the resume condition each one records.
+ *
+ * A view over existing data, NOT a new governance mechanism: nothing here gates,
+ * counts toward a ratchet, or changes what `collect()` scans. It exists because
+ * `later/` is excluded from `collect()` and from `/roadmap:process-*` — correct,
+ * parked work is not backlog — and that exclusion had no counterweight, so a
+ * roadmap moved there left the dashboard entirely.
+ */
+function collect_parked(roadmap_root: string): ParkedRoadmap[] {
+    const dir = path.join(roadmap_root, 'later');
+    let names: string[];
+    try {
+        names = fs.readdirSync(dir).sort();
+    } catch {
+        return [];
+    }
+    const out: ParkedRoadmap[] = [];
+    for (const name of names) {
+        const full = path.join(dir, name);
+        // The NAME half only: the full predicate rejects every path under `later`.
+        if (!_isFile(full) || !is_roadmap_name(name)) {
+            continue;
+        }
+        let text: string;
+        try {
+            text = fs.readFileSync(full, { encoding: 'utf-8' });
+        } catch {
+            continue;
+        }
+        if (is_draft(parse_frontmatter(text))) {
+            continue;
+        }
+        const cell = resume_cell(text);
+        // Parked blockers are still open blockers — counting them here is what stops
+        // this section becoming the surface where a park reads as a resolution.
+        const open = parse_blockers(text).filter((b) => !blocker_is_resolved(b));
+        out.push({
+            rel: name,
+            resume: cell.stated,
+            unlabelled: cell.unlabelled,
+            open_blockers: open.length,
+            needs_user: open.filter((b) => blocker_needs_user(b.owner)).length,
+        });
+    }
+    return out;
+}
+
+/**
+ * What brings a parked roadmap back, as one table cell. Both fields false means the
+ * file records nothing — said outright, because an empty cell reads as "nothing to
+ * wait for".
+ *
+ * The PARAGRAPH is joined, not the matched line: roadmap prose wraps at ~80
+ * columns, and quoting one line ended 39 of 52 cells mid-clause. A cell stopping at
+ * "the pair for" is not a shorter sentence, it is a different claim.
+ *
+ * Both tiers are tested over the SAME lines. Testing the loose one whole-file while
+ * the strict one ran per line made `unlabelled` fire on any file using the word
+ * "trigger" anywhere.
+ */
+function resume_cell(text: string): { stated: string | null; unlabelled: boolean } {
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const raw = lines[i] as string;
+        if (!RESUME_STATEMENT.test(raw)) {
+            continue;
+        }
+        const parts: string[] = [raw];
+        // Continuation lines of the same paragraph: non-blank, and not the start of
+        // a new block (list item, heading, fence, table row).
+        for (let j = i + 1; j < lines.length; j++) {
+            const next = (lines[j] as string).replace(/^\s*>\s?/, '').trim();
+            if (next === '' || /^([-*+]\s|#{1,6}\s|```|\||>\s*$)/.test(next)) {
+                break;
+            }
+            parts.push(next);
+        }
+        const joined = cell_text(parts.join(' '));
+        if (joined === '') {
+            continue;
+        }
+        return { stated: joined, unlabelled: false };
+    }
+    return { stated: null, unlabelled: lines.some((l) => RESUME_LOOSE.test(l)) };
+}
+
+/**
+ * One roadmap sentence, safe between two pipes. ORDER IS LOAD-BEARING: truncate
+ * before escaping, because cutting an escaped string severs a `\|` and leaves a
+ * dangling backslash. HTML comments are removed, not escaped — a `<!--` reaching a
+ * cell comments out the rest of the document, and one already did.
+ */
+function cell_text(raw: string): string {
+    let out = raw
+        .replace(/^\s*>\s?/, '')
+        .replace(/<!--[\s\S]*?-->/g, '')
+        .replace(/<!--|-->/g, '')
+        .replace(/\*\*/g, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+    if (out.length > 200) {
+        out = `${out.slice(0, 197).trimEnd()}...`;
+    }
+    return out.replace(/\|/g, '\\|');
+}
+
 function unarchived_complete(roadmaps: RoadmapStats[]): RoadmapStats[] {
     return roadmaps.filter((r) => r.total_active > 0 && r.open_ === 0 && r.deferred === 0);
 }
@@ -812,7 +960,7 @@ function collect_bundles(repo_root: string): Bundle[] {
     return out;
 }
 
-function render(roadmaps: RoadmapStats[], bundles: Bundle[] | null = null): string {
+function render(roadmaps: RoadmapStats[], bundles: Bundle[] | null, roadmap_root: string): 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;
@@ -836,6 +984,7 @@ function render(roadmaps: RoadmapStats[], bundles: Bundle[] | null = null): stri
         '[skipped/](roadmaps/skipped/) · [later/](roadmaps/later/)' +
         (total_open_blockers > 0
             ? ` · **${total_open_blockers}** open blocker${total_open_blockers !== 1 ? 's' : ''}` +
+              ' in the active tree' +
               (user_open_blockers > 0
                   ? `, **${user_open_blockers}** need you → \`agent-config gates\``
                   : '')
@@ -939,6 +1088,58 @@ function render(roadmaps: RoadmapStats[], bundles: Bundle[] | null = null): stri
     });
     lines.push('');
     lines.push('---\n');
+
+    // Listed under the active table so the two are read together. Parked work
+    // carries no counts here; what a reader needs is what brings it back.
+    const parked = collect_parked(roadmap_root);
+    if (parked.length > 0) {
+        lines.push(
+            `## Parked — \`later/\` (${parked.length} roadmap` +
+                `${parked.length !== 1 ? 's' : ''}, not active backlog)\n`,
+        );
+        lines.push(
+            '> Excluded from the table above and from `/roadmap:process-*` by ' +
+                'design. Listed here so a resume condition is visible without ' +
+                'opening the file.\n',
+        );
+        const parked_open = parked.reduce((n, r) => n + r.open_blockers, 0);
+        const parked_user = parked.reduce((n, r) => n + r.needs_user, 0);
+        if (parked_open > 0) {
+            lines.push(
+                `> Carrying **${parked_open}** open blocker` +
+                    `${parked_open !== 1 ? 's' : ''}` +
+                    (parked_user > 0 ? `, **${parked_user}** owned by you` : '') +
+                    ' — parking resolves nothing, so these are NOT in the ' +
+                    'active-tree count above.\n',
+            );
+        }
+        lines.push('| Roadmap | Open blockers | Resume when |');
+        lines.push('|---|---:|---|');
+        for (const r of parked) {
+            const cell =
+                r.resume ??
+                (r.unlabelled
+                    ? '_condition present but unlabelled — see file_'
+                    : '_no resume line recorded_');
+            const blockers =
+                r.open_blockers === 0
+                    ? '0'
+                    : `${r.open_blockers}${r.needs_user > 0 ? ` (${r.needs_user} you)` : ''}`;
+            // `<!-- ref-ignore -->` per row — a correctness fix, not a suppression. A
+            // resume condition NAMES WHAT DOES NOT EXIST YET ("when `x.md` exists" is
+            // the commonest shape in `later/`), so checking these quoted paths as live
+            // references fires the gate on correct content. It fired immediately. The
+            // authoritative copy of each path is the roadmap file; this table quotes
+            // it, and that gate does not walk `later/` either way.
+            lines.push(
+                `| [${r.rel}](roadmaps/later/${r.rel}) | ${blockers} | ${cell} |` +
+                    ' <!-- ref-ignore -->',
+            );
+        }
+        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`);
@@ -1013,16 +1214,18 @@ class ArgparseExit extends Error {
 const _PROG = 'update_roadmap_progress.py';
 
 function _usage(): string {
-    return `usage: ${_PROG} [-h] [--check] [--repo-root REPO_ROOT]\n`;
+    return `usage: ${_PROG} [-h] [--check] [--archive | --no-archive] [--repo-root REPO_ROOT]\n`;
 }
 
 interface Args {
     check: boolean;
+    archive: boolean;
     repo_root: string;
 }
 
 function _parseArgs(argv: readonly string[]): Args {
     let check = false;
+    let archive = false;
     let repo_root = process.cwd();
     const emitError = (msg: string): never => {
         process.stderr.write(_usage());
@@ -1038,6 +1241,12 @@ function _parseArgs(argv: readonly string[]): Args {
         } else if (tok === '--check') {
             check = true;
             i += 1;
+        } else if (tok === '--archive') {
+            archive = true;
+            i += 1;
+        } else if (tok === '--no-archive') {
+            archive = false;
+            i += 1;
         } else if (tok === '--repo-root') {
             const val = argv[i + 1];
             if (val === undefined) {
@@ -1052,7 +1261,13 @@ function _parseArgs(argv: readonly string[]): Args {
             emitError(`unrecognized arguments: ${tok}`);
         }
     }
-    return { check, repo_root };
+    if (check && archive) {
+        // A gate that mutates the tree it is checking cannot be trusted by CI
+        // (council 2026-08-20, both seats). Refuse the combination outright
+        // rather than silently letting one win.
+        emitError('argument --archive: not allowed with --check');
+    }
+    return { check, archive, repo_root };
 }
 
 /**
@@ -1094,8 +1309,31 @@ function main(argv?: readonly string[]): number {
         process.stdout.write(`ℹ️  No roadmaps directory at ${roadmap_root} — nothing to do.\n`);
         return 0;
     }
+    // Archive before rendering, so the dashboard describes the tree the sweep
+    // leaves behind rather than the one it found. `--check` never archives: a
+    // gate that mutates the tree it is checking cannot be trusted by CI.
+    let sweep_out = '';
+    if (!args.check && args.archive && unarchived_complete(collect(roadmap_root)).length > 0) {
+        const swept = run_archival_sweep(repo_root);
+        sweep_out = swept.stdout;
+        if (swept.stderr) {
+            process.stderr.write(swept.stderr);
+        }
+        if (!swept.ok) {
+            // A half-finished sweep leaves the tree in a shape the dashboard
+            // would describe as if it were intentional. Report and stop before
+            // writing (council 2026-08-20: "archival failures must prevent
+            // dashboard rendering so partially updated state is not presented
+            // as current").
+            process.stderr.write(
+                '❌  The archival sweep failed — dashboard NOT regenerated. ' +
+                    'Fix the tree, then re-run.\n',
+            );
+            return 1;
+        }
+    }
     const roadmaps = collect(roadmap_root);
-    const new_text = render(roadmaps, collect_bundles(repo_root));
+    const new_text = render(roadmaps, collect_bundles(repo_root), roadmap_root);
     const current = fs.existsSync(target) ? fs.readFileSync(target, { encoding: 'utf-8' }) : '';
     const complete = unarchived_complete(roadmaps);
     const pending = pending_iron_law_3(roadmaps);
@@ -1166,7 +1404,13 @@ function main(argv?: readonly string[]): number {
             `${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 (sweep_out) {
+        process.stdout.write(sweep_out);
+    }
     if (complete.length) {
+        // Whatever survived the sweep is complete but NOT archivable — the
+        // sweep already said why on stderr (an open blocker outlives its
+        // steps). Without `--archive` this is every complete roadmap.
         process.stderr.write(
             '⚠️   Completed roadmaps not yet archived — move to ' +
                 '`agents/roadmaps/archive/`:\n',