@event4u/agent-config 12.1.0 → 14.0.0

package/dist/ui/index.html

@@ -27,7 +27,7 @@
                 document.documentElement.setAttribute('data-theme', theme);
             })();
         </script>
-      <script type="module" crossorigin src="/assets/index-B0aMJnuz.js"></script>
+      <script type="module" crossorigin src="/assets/index-C1pBRm1f.js"></script>
       <link rel="stylesheet" crossorigin href="/assets/index-jSfMW8_t.css">
     </head>
     <body>

package/docs/guidelines/design-fidelity-mechanics.md

@@ -45,6 +45,27 @@ Two consequences worth stating because they are the ones agents get backwards:
 
 Regression witness: `daf-source-over-screenshot`.
 
+## URL / live-page handover — extraction into files, before the first UI write
+
+```
+A HANDOVER THAT ARRIVES AS A URL IS STILL RUNG 2, NOT RUNG 4.
+EXTRACT THROUGH THE USER'S CONNECTED BROWSER TOOLS INTO FILES
+BEFORE ANY UI WRITE. A SCREENSHOT TAKEN DURING EXTRACTION
+CARRIES QA DUTY ONLY — IT IS NEVER THE THING YOU BUILD FROM.
+```
+
+A published artifact link, a builder's share link, a staging or `localhost`
+page: rung 2 above is reachable, so rung 4 is not the fallback it looks like.
+Extraction lands in the existing `design-system.json` contract under the
+`.claude/design-system/` prefix the rule already routes on — no new artifact
+shape — and the offline `/design-system:import` adapter consumes it. The package
+ships the contract, the adapter and the instructions; it ships no crawler,
+Playwright runtime or font-bundler.
+
+Where the extraction goes, what consumes it, the retrieval order that keeps the
+source alive across sessions, the producer sentence, and the honest coverage
+gap: [`design-handover-extraction`](design-handover-extraction.md).
+
 ## Adopt the code — re-derivation is a deviation
 
 Where the artifact's own markup, CSS, or JS is stack-compatible, **adapting that

package/docs/guidelines/design-handover-extraction.md

@@ -0,0 +1,87 @@
+# Design Handover — URL / live-page extraction
+
+> Where a URL handover gets extracted to, what consumes it, and in what order it is read back
+
+_Split out of [`design-fidelity-mechanics`](design-fidelity-mechanics.md) § URL / live-page handover, which carries the obligation surface and routes here. The split is the per-file depth ceiling doing its job: the mechanics file sat at 14.2k of its 16k budget, and compressing this material to fit would have cost the parts that make it actionable._
+
+```
+A HANDOVER THAT ARRIVES AS A URL IS STILL RUNG 2, NOT RUNG 4.
+EXTRACT THROUGH THE USER'S CONNECTED BROWSER TOOLS INTO FILES
+BEFORE ANY UI WRITE. A SCREENSHOT TAKEN DURING EXTRACTION
+CARRIES QA DUTY ONLY — IT IS NEVER THE THING YOU BUILD FROM.
+```
+
+When the artifact is handed over as a **URL** rather than a file — a published
+artifact link, a builder's share link, a staging or `localhost` page — rung 2 of
+the [data-basis ladder](design-fidelity-mechanics.md#data-basis-ladder) is
+reachable and rung 4 is not the fallback it looks like. Pull the DOM,
+stylesheets, scripts and assets through the browser tools the user has
+connected, and land them as files first.
+
+## Where the extraction lands
+
+Into `design-system.json` under `.claude/design-system/` — the `path_prefix` the
+`design-fidelity` rule already routes on. That file is an **existing contract**,
+specified in
+[`design-system-json.md`](../../src/skills/design-system-capture/references/design-system-json.md);
+this guideline defines no format of its own. Raw source files land beside it,
+and screenshots taken while extracting land in a references directory next to
+them.
+
+## What consumes it
+
+[`/design-system:import`](../../src/domains/engineering-base/design-system/import/command.md)
+runs the extraction output through the three-lane adapter
+(`native` / `dtcg` / `dembrandt`) into the contract shape, then hands it to
+`design-system-capture`'s per-field import. The adapter is **offline** — it
+reads a file and writes the contract shape; it never fetches, crawls, or
+launches a browser.
+
+## The lock boundary — stated here because this is where an agent would cross it
+
+The package ships the contract, the adapter, and the instructions. It does
+**not** ship the crawler, the Playwright runtime, or a font-bundler. Extraction
+runs through the user's own connected tooling, and its output is *observed, not
+authoritative*: every field is confirmed by the human, and a value conflicting
+with a registered brand token is flagged rather than applied
+(`brand-source-of-truth`).
+
+## Retrieval order — so the source survives the session
+
+Check in this order and stop at the first hit. The point is that the next
+session reads a file instead of re-screenshotting the same page.
+
+| # | Source | Why it ranks here |
+|---|---|---|
+| 1 | The project's own `design-system.json` | Already confirmed by a human in an earlier session — the only rung whose values someone signed off on |
+| 2 | A previous extraction artifact under `.claude/design-system/` | Observed and file-backed; re-reading it costs nothing and re-extracting may drift |
+| 3 | The live page | Authoritative for *today's* page, but only reachable while it is up and the tooling is connected |
+
+**Persistence is not restated here.** Skip-if-exists unless explicitly forced,
+and never silently discarding a prior confirmed decision, are owned by
+[`/design-system:generate`](../../src/domains/engineering-base/design-system/generate/command.md)
+— *"never overwrite a confirmed `DESIGN.md`"*, *"Never persist silently."* This
+guideline states the order; that command states what happens on a collision, and
+stating it twice is how the two drift apart.
+
+## The producer sentence
+
+The documented easy path is a connected extractor MCP, attached once and reused.
+Where none is available, the manual Chrome-DevTools-MCP channel is the fallback,
+and where neither is reachable the handover degrades to rung 3 or 4 — which the
+ladder requires you to **name**, not to pass off as a source-based build.
+
+## Coverage — stated honestly
+
+No fixture scores this class yet. `daf-source-over-screenshot` scores the rung
+choice on an *attached* artifact, not a URL handover, and it is itself recorded
+as SKIPPED on 2026-08-13 for want of a page-reaching capture primitive. Closing
+the gap needs a fixture whose host actually has one; claiming a regression
+witness before then would be the fabrication this package's evidence discipline
+exists to prevent.
+
+## See also
+
+- [`design-fidelity-mechanics`](design-fidelity-mechanics.md) — the data-basis ladder this operationalises, and the adopt-the-code duty that governs what you do with the extracted source.
+- [`design-fidelity`](../../src/rules/design-fidelity.md) — the rule; a provided artifact is the spec.
+- [`design-system-capture`](../../src/skills/design-system-capture/SKILL.md) — the per-field import the adapter hands off to.

package/docs/guidelines/prompt-templates.md

@@ -138,9 +138,32 @@ Given an existing good output, reconstruct the prompt that would
 produce it. Used to mine prompts from public LLM artifacts. Not a
 shaping template — a forensic one.
 
+## Viral-prompt anti-patterns — what this catalogue deliberately omits
+
+Prompt collections that circulate socially optimise for looking impressive
+on the way in, not for what the target model can act on. None of the
+templates above encodes the three patterns below, and that is a decision
+rather than an oversight — a template is a slot structure, and these three
+are slots the model cannot fill honestly.
+
+| Anti-pattern | Why no template carries it |
+|---|---|
+| **Grandiose persona** — "world's foremost", "legendary", "10× expert" | Every template's role slot takes a *capability* (`RTF` Role, `CRISPE` Capacity, `CO-STAR` Style). A superlative is not a capability: it spends tokens and changes nothing the model does. |
+| **Presupposed canon** — "the 7 laws of X", "the standard X framework", for a body of knowledge that may not exist | A presupposition in the context slot is answered by confabulation, and the invented canon inherits the authority of the frame. `Few-Shot` exists precisely so that a real pattern is *shown* rather than asserted. |
+| **Scope stuffing** — analysis *and* strategy *and* copy *and* a checklist in one prompt | Each template has one Expectation / Objective / Format slot by construction. Four deliverables in one prompt produce four shallow ones; split them, or name the primary. |
+
+The catalogue's own position: a template earns its place by making a
+request *checkable*, not by making it sound authoritative. Where a rough
+prompt carries one of these three, the
+[`prompt-optimizer`](../../.agent-src.uncondensed/skills/prompt-optimizer/SKILL.md)
+strips it in its de-inflation sub-step before any template is picked —
+and strips nothing else, because everything outside these three is a
+requirement the author meant. This section is own analysis; it records a
+decision about this catalogue rather than adopting an outside claim.
+
 ## Rejection note
 
-Upstream `nidhinjs/prompt-master` claims that only five techniques
+An external prompt-collection claims that only five techniques
 are "safe" for production prompting:
 
 - few-shot

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@event4u/agent-config",
     "mcpName": "io.github.event4u-app/agent-config",
-    "version": "12.1.0",
+    "version": "14.0.0",
     "description": "Governed skills, rules and commands for AI coding tools (Claude Code, Cursor, Windsurf, Copilot) — every claim machine-checked, including \"zero runtime daemon\".",
     "license": "MIT",
     "private": false,

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

@@ -403,6 +403,38 @@ 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/`
+ * 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
+ * than by remembering.
+ *
+ * `build_archive_index` is package-internal (`src/scripts/`), while this sweep
+ * is projected into consumer installs that carry no such script. Absent
+ * builder → nothing to regenerate, and that is a normal consumer state, not a
+ * failure. The spawn is best-effort for the same reason `_regen_dashboard` is:
+ * a sweep that archived correctly must not report failure because a
+ * regeneration could not run.
+ */
+function _regen_archive_index(root: string, dry_run: boolean): void {
+    if (dry_run) {
+        return;
+    }
+    const script = path.join(root, 'src', 'scripts', 'build_archive_index.ts');
+    if (!_isFile(script)) {
+        return;
+    }
+    _runTwin(root, script);
+    for (const rel of ['agents/roadmaps/archive/INDEX.md', 'agents/roadmaps/archive/index.json']) {
+        if (_isFile(path.join(root, rel))) {
+            _run(['git', 'add', '--', rel], root);
+        }
+    }
+}
+
 /** Spawn the dashboard generator twin (tsx) with cwd=root, mirroring `[sys.executable, script]`. */
 function _runTwin(root: string, script: string): void {
     // Python uses `sys.executable` — the interpreter already running this
@@ -491,6 +523,7 @@ function main(argv?: readonly string[]): number {
         return 0;
     }
     _regen_dashboard(root, ns.dry_run);
+    _regen_archive_index(root, ns.dry_run);
     const verb = ns.dry_run ? 'Would archive' : 'Archived';
     for (const rec of archived) {
         process.stdout.write(

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

@@ -0,0 +1,395 @@
+/**
+ * `agent-config gates --execute <id>` — the acting half of the gate layer.
+ *
+ * `gates` renders decisions. This resolves the ones that were never decisions:
+ * a class-0 gate is a command whose OUTPUT IS THE UNBLOCK, and leaving it for a
+ * human to type is the couriering `road-to-gate-autonomy` exists to remove.
+ *
+ * ## Deliberately thin, on the sweep's own number
+ *
+ * Step 1.2 pre-registered that at least 40 % of open blockers would be class 0
+ * or 1 and measured **24.5 %** (`agents/evidence/analysis/gate-class-sweep-2026-08-17.md`).
+ * The roadmap's honest-null clause then fixes this module's size: it ships for
+ * the six class-0 entries and the render path, and it is not the lever that
+ * drains the estate. Building a general execution engine against a premise the
+ * evidence weakened would be the over-build the null exists to prevent.
+ *
+ * ## What it will not do
+ *
+ *   - **No sweep.** One blocker per invocation, named explicitly. A blanket
+ *     `--execute` over the estate would run N authored commands on one keypress,
+ *     and the blast radius of a misclassification would be the whole tree
+ *     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 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
+ *     and points back at that renderer; it does not call it.
+ *   - **No run without `--confirm`.** `Run:` is arbitrary shell read out of a
+ *     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.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+import { collect, blocker_class, type Blocker } from './update_roadmap_progress.js';
+
+/**
+ * Where a class-1 receipt ledger would live once the budget decision is taken.
+ *
+ * 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.
+ */
+const LEDGER_REL = path.join('agents', 'runtime', 'state', 'gate-budget-ledger.jsonl');
+
+type Outcome = 'resolved' | 'failed' | 'rendered' | 'not-found';
+
+interface ExecuteResult {
+    outcome: Outcome;
+    /** Human-facing report — always populated, always the whole answer. */
+    report: string;
+    /** Exit code for the CLI: 0 unless the gate was named and could not run. */
+    code: number;
+}
+
+interface Located {
+    blocker: Blocker;
+    /** Absolute path of the roadmap holding it. */
+    file: string;
+    rel: string;
+}
+
+function locate(roadmapRoot: string, id: string): Located | null {
+    for (const r of collect(roadmapRoot)) {
+        for (const b of r.open_blockers) {
+            if (b.id === id) {
+                // `r.path` is the absolute path the collector already resolved.
+                // Rebuilding it from `basename(r.rel)` discarded the directory,
+                // so a roadmap in any subdirectory the collector does not
+                // exclude was either written to a same-named top-level file or
+                // threw — and either way AFTER the authored command had run.
+                return { blocker: b, file: r.path, rel: r.rel };
+            }
+        }
+    }
+    return null;
+}
+
+/**
+ * Commands a class-0 gate may never carry, whatever the entry claims.
+ *
+ * Class 0 is defined as deterministic, free and **reversible**. A command that
+ * pushes, merges, deploys, or deletes is none of those, so its presence is a
+ * misclassification — and the right answer to a misclassification is refusal,
+ * not a confirmation prompt that makes the operator the last line of defence.
+ * These are Hard-Floor actions under `non-destructive-by-default`, which no
+ * setting, roadmap or flag lifts.
+ *
+ * A denylist is the wrong shape for a *security boundary* and the right shape
+ * for a *classification check*, which is what this is: the tree's roadmap files
+ * are reviewed content, so this catches the authoring mistake rather than an
+ * attacker. The blast-radius control is `--confirm` below, not this list.
+ */
+const HARD_FLOOR_RE =
+    /(^|[;&|]\s*)(git\s+(?:push|merge|reset\s+--hard|rebase)\b|gh\s+(?:pr\s+merge|release)\b|terraform\s+apply\b|kubectl\s+apply\b|npm\s+publish\b|rm\s+-[rRf]+|DROP\s+TABLE\b|TRUNCATE\b)/i;
+
+function hardFloorReason(command: string): string | null {
+    const m = HARD_FLOOR_RE.exec(command);
+    return m ? (m[2] as string).trim() : null;
+}
+
+/** Strip the backticks an authored `Run:` field carries. */
+function commandOf(b: Blocker): string {
+    const raw = b.run.trim();
+    const fenced = /^`([^`]+)`$/.exec(raw);
+    return (fenced ? (fenced[1] as string) : raw).trim();
+}
+
+/**
+ * The class-2 consent line — one question, its recommendation, its default.
+ *
+ * This is a FEED, not a surface: `road-to-user-out-of-the-loop` Phase 1 owns
+ * the decision sheet, and this roadmap only hands it a line. Keeping the shape
+ * to one line is the contract — a class-2 gate that cannot state a one-line
+ * question and a default is reclassified to 3, never verbosified.
+ */
+function consentLine(b: Blocker, why?: string): string {
+    const head = why ? `${b.id} — ${why}` : b.id;
+    const rec = b.recommendation.trim();
+    const q = b.question.trim();
+    const lines = [`CONSENT · ${head}`];
+    // An entry with no `Question:` has no question, and borrowing `Blocks:`
+    // silently put a "what this holds up" sentence in the "what is being
+    // decided" slot — two different facts. Say which one is on screen.
+    lines.push(
+        q !== ''
+            ? `  Question:       ${q}`
+            : `  Question:       (none authored — this is the Blocks line) ${b.blocks.trim()}`,
+    );
+    lines.push(
+        `  Recommendation: ${rec || '(none recorded — ask for one before deciding)'}`,
+    );
+    // The default is derived, not constant: an entry carrying a recommendation
+    // has one, an entry without one has nothing to default TO, and printing
+    // the same sentence for both told the reader nothing either way.
+    lines.push(
+        rec !== ''
+            ? '  Default if you say nothing: the recommendation above is NOT applied; the gate stays open.'
+            : '  Default if you say nothing: the gate stays open, and no recommendation exists to fall back on.',
+    );
+    // Risk 5 of the roadmap, made observable rather than merely written down:
+    // the defect being fixed is reading load, and a mechanism that emits
+    // paragraphs recreates it under a new name. The remedy the taxonomy names
+    // is reclassification to 3, never a longer line — so the overflow is
+    // reported at the entry rather than silently rendered.
+    if (rec.length > PARAGRAPH_CHARS) {
+        lines.push(
+            `  note: this recommendation is ${rec.length} chars — a class-2 gate that ` +
+                'cannot state a one-line question and a default is reclassified to 3, ' +
+                'not verbosified.',
+        );
+    }
+    return lines.join('\n') + '\n';
+}
+
+/**
+ * Where "one line" stops being one line.
+ *
+ * A stated default, not a measured optimum: two full terminal lines at the 78
+ * column the rest of this command wraps to. *Revisit-if* a real decision sheet
+ * lands and its own width contradicts this.
+ */
+const PARAGRAPH_CHARS = 156;
+
+/**
+ * Append the run's evidence under the blocker and flip its status.
+ *
+ * In-file, at the blocker, which is the done-note discipline every phase in
+ * this tree already uses — an unblock recorded anywhere else is an unblock the
+ * next reader of the roadmap cannot see.
+ */
+function appendEvidence(file: string, id: string, command: string, output: string, when: string): boolean {
+    const text = fs.readFileSync(file, 'utf-8');
+    // The id is regex-escaped: ids are parsed with `(.+?)`, so a metacharacter
+    // is legal in the tree and an unescaped interpolation threw an uncaught
+    // SyntaxError — after the authored command had already run.
+    const head = new RegExp(`^###[ \\t]+blocker:[ \\t]*${escapeRe(id)}[ \\t]*$`, 'im');
+    const m = head.exec(text);
+    if (!m) {
+        return false;
+    }
+    const bodyStart = m.index + m[0].length;
+    // The body ends at the next blocker OR the next `##` section. Bounding it
+    // only at the next `### blocker:` made the LAST blocker's body run to the
+    // end of the file — the common shape, since `## Blockers` is followed by
+    // `## Risk Register` — so the evidence bullet landed after the risk table
+    // instead of under the blocker, which is the opposite of what this
+    // function's whole point is.
+    const rest = text.slice(bodyStart);
+    const nextHead = /^###[ \t]+blocker:/im.exec(rest);
+    const nextSection = /^##[ \t]+\S/m.exec(rest);
+    const ends = [nextHead?.index, nextSection?.index].filter((i): i is number => i !== undefined);
+    const bodyEnd = ends.length ? bodyStart + Math.min(...ends) : text.length;
+    const body = text.slice(bodyStart, bodyEnd);
+
+    const statusRe = /^-[ \t]*\*\*Status:\*\*[ \t]*.*$/im;
+    if (!statusRe.test(body)) {
+        return false;
+    }
+    const firstLine = output.split(/\r?\n/).find((l) => l.trim() !== '') ?? '(no output)';
+    const flipped = body.replace(
+        statusRe,
+        `- **Status:** resolved ${when} — class-0 auto-run`,
+    );
+    const evidence =
+        `- **Unblock evidence (${when}):** ran \`${command}\` — exit 0. ` +
+        `First line of output: ${firstLine.trim()}\n`;
+    const withEvidence = flipped.replace(/\s*$/, '\n') + evidence;
+    fs.writeFileSync(file, text.slice(0, bodyStart) + withEvidence + text.slice(bodyEnd), 'utf-8');
+    return true;
+}
+
+/** `YYYY-MM-DD` for the evidence note. Injected so tests are deterministic. */
+function today(now: Date): string {
+    return now.toISOString().slice(0, 10);
+}
+
+function escapeRe(s: string): string {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+interface ExecuteOptions {
+    /**
+     * Actually run the class-0 command.
+     *
+     * Default false, and that default is the control. `Run:` is an arbitrary
+     * shell string read out of a markdown file; without this flag the command
+     * is ECHOED and refused, so the operator sees exactly what would run before
+     * anything runs. `non-destructive-by-default` requires the confirmation to
+     * be this-turn and to name the exact object, and the echoed command is that
+     * object.
+     */
+    confirm?: boolean;
+}
+
+function execute(
+    roadmapRoot: string,
+    id: string,
+    now: Date,
+    opts: ExecuteOptions = {},
+): ExecuteResult {
+    const found = locate(roadmapRoot, id);
+    if (!found) {
+        return {
+            outcome: 'not-found',
+            report: `No open blocker with id '${id}'. Run \`agent-config gates --all\` for the list.\n`,
+            code: 1,
+        };
+    }
+    const { blocker, file, rel } = found;
+    const cls = blocker_class(blocker);
+
+    if (cls === '3') {
+        // Byte-identical to today by construction: nothing is executed and
+        // nothing is written. The gate is rendered by the caller.
+        return {
+            outcome: 'rendered',
+            report: `${id} is class 3 — human-only. Nothing to execute; see \`agent-config gates\`.\n`,
+            code: 0,
+        };
+    }
+    if (cls === '2') {
+        return { outcome: 'rendered', report: consentLine(blocker), code: 0 };
+    }
+    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.
+            return {
+                outcome: 'rendered',
+                report: consentLine(
+                    blocker,
+                    'class 1 with no budget ledger, 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,
+        };
+    }
+
+    const command = commandOf(blocker);
+    if (command === '') {
+        // Unreachable through a linted tree — `lint_roadmap_blockers` fails a
+        // class-0 entry with no `Run:` — but reachable through an unlinted one,
+        // 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`,
+            code: 1,
+        };
+    }
+
+    const floor = hardFloorReason(command);
+    if (floor !== null) {
+        // Refused outright, not offered for confirmation. Class 0 is defined
+        // as reversible; a push, merge, deploy or delete is not, so this is a
+        // misclassified entry and the fix is to re-author the class — making
+        // the operator wave it through would move a Hard Floor onto a keypress.
+        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. ' +
+                'Nothing was executed; re-author the class.\n',
+            code: 1,
+        };
+    }
+
+    if (opts.confirm !== true) {
+        // Echo-before-run. The command is arbitrary shell read out of a
+        // markdown field, so the operator sees the exact string before it runs
+        // and the confirmation is this-turn rather than implied by the id.
+        return {
+            outcome: 'rendered',
+            report:
+                `${id} is class 0 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',
+            code: 0,
+        };
+    }
+
+    const r = spawnSync(command, {
+        shell: true,
+        encoding: 'utf-8',
+        cwd: path.dirname(path.dirname(roadmapRoot)),
+        timeout: 120_000,
+    });
+    const output = `${r.stdout ?? ''}${r.stderr ?? ''}`;
+    if (r.error !== undefined || r.status !== 0) {
+        // `r.error` is read, not just the status: a spawn failure or a
+        // maxBuffer overflow leaves status null with empty output, and
+        // "exited null" with no diagnostic is illegible on the one path in
+        // this command that writes.
+        const why =
+            r.error !== undefined
+                ? `could not run (${r.error.message})`
+                : `exited ${r.status ?? 'null'}`;
+        return {
+            outcome: 'failed',
+            report:
+                `${id}: \`${command}\` ${why}. The gate is unchanged — ` +
+                'a blocker resolved by a failed command is worse than an open one.\n' +
+                output.split(/\r?\n/).slice(0, 10).join('\n') +
+                '\n',
+            code: 1,
+        };
+    }
+    const when = today(now);
+    if (!appendEvidence(file, id, command, output, when)) {
+        return {
+            outcome: 'failed',
+            report:
+                `${id}: \`${command}\` succeeded, but its entry in ${rel} could not be ` +
+                'rewritten (no Status field found). Nothing was changed.\n',
+            code: 1,
+        };
+    }
+    return {
+        outcome: 'resolved',
+        report:
+            `${id} resolved. Ran \`${command}\` (exit 0); evidence appended in ${rel} ` +
+            `and the status flipped to resolved ${when}.\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.
+            'Run `agent-config roadmap:progress` — the dashboard is derived from the ' +
+            'file this rewrote and is now stale.\n',
+        code: 0,
+    };
+}
+
+export { execute, consentLine, commandOf, locate, appendEvidence, LEDGER_REL };
+export type { ExecuteResult, Outcome };