@event4u/agent-config 13.0.0 → 14.0.0

package/dist/agent-src/contexts/execution/subagent-spawn-contract.md

@@ -170,6 +170,35 @@ contingency.
   subagent's output is never auto-persisted into memory — promotion is
   always the human-gated flow (ADR-098 floor). Auto-surface, never
   auto-write.
+- **(f) Return shape — text-only final message, disk copy written first.** Two
+  clauses, and they ride **here**, at spawn, rather than in a reusable agent
+  definition: a delivery duty stated in an agent definition measured 0/2 against
+  1/1 for the identical duty carried in the dispatch prompt (practitioner
+  report, n small), which is the same verbatim-at-spawn discipline as (a)–(e).
+  - **The final message is a single text-only envelope — never end on a tool
+    call.** Measured on host 2.1.229 with a matched control dispatched in the
+    same turn: the arm told to emit its report and then make one final
+    `echo done` call returned **`(no output)`** to its parent after 3 tool uses
+    and 18,242 tokens, while the control ending on assistant text returned the
+    complete report. The work was paid for in full and discarded in full
+    ([`subagent-lifecycle-phase0-return-channel.md`](../../../../agents/evidence/investigations/subagent-lifecycle-phase0-return-channel.md)
+    § F1).
+  - **Write the envelope to the runtime artifact dir before emitting it.** Disk
+    is the durable channel, the message the fast one — same envelope, so the
+    orchestrator still ingests exactly one shape
+    ([response contract § Durable copy](subagent-response-contract.md#durable-copy--the-envelope-on-disk-before-the-message)).
+
+  **No carve-out for verifier dispatches.** An async verifier — a subagent that
+  screenshots, grades, and reports back — rides this identical return channel,
+  and one that grades and never delivers is two operator symptoms in a single
+  run: work that looks endless from the orchestrator's side, and work that
+  finished without returning. Rule (f) binds it like any other worker.
+
+  **Honest scope.** Nothing enforces (f). It is prompt-carried text, so a worker
+  that ignores it fails exactly as before — the clause buys a stated duty and a
+  known-good path to look in, not a guarantee. The deterministic half needs a
+  `subagent_stop` concern that reads the disk copy, which is planned and not
+  shipped.
 
 ## Hand-off worked examples — step N output feeds step N+1
 

package/dist/agent-src/rules/command-suggestion-policy.md

@@ -32,6 +32,39 @@ A suggestion block emits options. It does **not** start a command flow.
 The "run as-is" option is **always present**, **always last**, never
 removed.
 
+### The single HIGH-tier carve-out — a duplicate confirmation, never a skipped one
+
+```
+HIGH TIER REMOVES A SECOND CONFIRMATION. IT NEVER REMOVES THE FIRST.
+A COMMAND THAT WOULD BEGIN ACTING ON ARRIVAL IS NEVER HIGH TIER.
+TWO CANDIDATES ABOVE THE FLOOR IS MEDIUM. A SUBSTRING HIT IS MEDIUM.
+NO DETERMINISTIC UNIQUE SIGNAL → THE BLOCK, ALWAYS.
+```
+
+Added by road-to-user-out-of-the-loop Phase 1. It is narrow on purpose, and the
+narrowness is the argument: the law above exists so the user is never carried
+somewhere they did not choose, and a routed command whose **own** contract
+screen is the next thing they see has not carried them anywhere — it has
+replaced one options block with one basis line and left the real decision
+exactly where it was.
+
+All three conditions in
+[`command-suggestion-flow § Tier matrix`](../contexts/contracts/command-suggestion-flow.md)
+must hold: a deterministic unique signal, no second candidate above the floor,
+and a routed command that shows its own confirmation. Condition 3 is the
+load-bearing one — without it this clause would authorise auto-execution, which
+is the thing the Iron Law forbids and this carve-out does not touch.
+
+Everything else on this page is unchanged. MEDIUM and LOW still emit the block
+with "run as-is" always present and always last; the subordination list below
+still makes suggestion junior to every rule on it; and a Hard-Floor action stays
+gated by [`non-destructive-by-default`](non-destructive-by-default.md) however
+it was reached.
+
+**Honest status:** the kill criterion (>5 % mis-routes over 50 auto-routes
+reverts to block-always) has **no instrument yet**. The rate is unmeasured, not
+low. A mis-route is a reportable defect until it can be counted.
+
 ## Subordination — when to stay silent
 
 The suggestion rule is **junior** to:

package/dist/agent-src/rules/design-review-after-ui-write.md

@@ -14,8 +14,13 @@ triggers:
   - file_pattern: "*.tsx"
   - file_pattern: "*.jsx"
   - file_pattern: "*.blade.php"
-  - keyword: "component"
-  - keyword: "design token"
+  # `keyword: "component"` and `keyword: "design token"` removed 2026-08-17 as an
+  # AUTHORING decision — road-to-mixed-trigger-activation-cost Phase 2, amendment
+  # option (b), narrowed to the two path-dominant per-edit rules. This is the
+  # escape the mixed-triggers guard's own comment names: with no non-path trigger
+  # left the emitter restores `paths:`, so the rule loads on UI file contact
+  # instead of in every session. The obligation is unchanged — it binds when a UI
+  # file is touched, which is the only place a UI edit can happen.
 routes_to:
   - "skill:design-review"
   - "skill:accessibility-auditor"
@@ -24,8 +29,12 @@ packs: [frontend-design]
 enforced_by:
   - "none"
 collision_ok:
-  "component": "a written component is reviewed before it is called done — the write-side half"
-  "design token": "same surface, opposite side: ui-audit-gate inventories tokens before the write, this reviews what the write emitted"
+  # The "component" and "design token" entries were removed with their triggers
+  # (2026-08-17): a collision note for a trigger that no longer exists is an
+  # own-orphan, and `minimal-safe-diff` § Own-orphan cleanup requires the diff that
+  # stopped referencing them to remove them too. The path-keyed notes below are
+  # unchanged, and they still carry the real point: both halves of the UI loop fire
+  # on the same paths.
   "resources/views/": "both halves of one UI loop fire on the same path — audit before, review after; neither substitutes for the other"
   "resources/js/": "both halves of one UI loop fire on the same path — audit before, review after; neither substitutes for the other"
   "components/": "both halves of one UI loop fire on the same path — audit before, review after; neither substitutes for the other"
@@ -109,10 +118,18 @@ design consultation latched this session.
 
 It runs **parallel** to this rule rather than consuming it. Nothing in the tree
 reads this frontmatter at session time; the concern decides what counts as a UI
-surface from `src/scripts/_lib/ui_surface.ts`, and the `keyword:` triggers here
-still have no runtime consumer. A test — not a code path — keeps the two from
-drifting: `ui_rule_triggers.test.ts` asserts every `file_pattern` declared here
-is accepted by that predicate.
+surface from `src/scripts/_lib/ui_surface.ts`. A test — not a code path — keeps
+the two from drifting: `ui_rule_triggers.test.ts` asserts every `file_pattern`
+declared here is accepted by that predicate.
+
+**This rule carries no `keyword:` trigger any more (2026-08-17).** It used to,
+and the observation those keywords had no runtime consumer is what made removing
+them cheap: no host activation surface reads a keyword — Cursor and Windsurf
+activate on `globs` plus the description, Claude on `paths:`. What the keywords
+did do was expensive, and only on Claude: one non-path trigger makes the emitter
+write **no** `paths:` at all, which is why this rule's pre-inventory-and-review
+obligation stood in every session from 12.1.0 until the removal. It is
+path-scoped again — see `road-to-mixed-trigger-activation-cost` Phase 2.
 
 Warn-only, capped at two nudges per session, default-OFF, and bound only in the
 three `platforms:` rows that carry a `pre_tool_use` key — augment, claude,

package/dist/agent-src/rules/ui-audit-gate.md

@@ -14,8 +14,13 @@ triggers:
   - file_pattern: "*.tsx"
   - file_pattern: "*.jsx"
   - file_pattern: "*.blade.php"
-  - keyword: "component"
-  - keyword: "design token"
+  # `keyword: "component"` and `keyword: "design token"` removed 2026-08-17 as an
+  # AUTHORING decision — road-to-mixed-trigger-activation-cost Phase 2, amendment
+  # option (b), narrowed to the two path-dominant per-edit rules. This is the
+  # escape the mixed-triggers guard's own comment names: with no non-path trigger
+  # left the emitter restores `paths:`, so the rule loads on UI file contact
+  # instead of in every session. The obligation is unchanged — an audit is owed
+  # before a component is written, and a component is written in a file.
 routes_to:
   - "skill:existing-ui-audit"
   - "skill:iconography"
@@ -25,8 +30,11 @@ packs: [frontend-design]
 enforced_by:
   - "none"
 collision_ok:
-  "component": "no new component without audit findings — its core subject"
-  "design token": "same surface, opposite side: this inventories tokens before the write, design-review-after-ui-write reviews what the write emitted"
+  # The "component" and "design token" entries were removed with their triggers
+  # (2026-08-17): a collision note for a trigger that no longer exists is an
+  # own-orphan, and `minimal-safe-diff` § Own-orphan cleanup requires the diff that
+  # stopped referencing them to remove them too. The path-keyed notes below are
+  # unchanged — both halves of the UI loop still fire on the same paths.
   "resources/views/": "both halves of one UI loop fire on the same path — audit before, review after; neither substitutes for the other"
   "resources/js/": "both halves of one UI loop fire on the same path — audit before, review after; neither substitutes for the other"
   "components/": "both halves of one UI loop fire on the same path — audit before, review after; neither substitutes for the other"
@@ -114,10 +122,19 @@ consultation latched this session.
 It is a **parallel** mechanism, not a consumer of the triggers above — the
 distinction matters and the earlier wording here got it wrong. The concern
 decides "is this a UI surface" from `src/scripts/_lib/ui_surface.ts`; nothing
-in the tree parses this frontmatter at session time, so the `keyword:` triggers
-still have no runtime consumer at all, and the two sets can drift. What holds
-them together is a test, not a dependency: `ui_rule_triggers.test.ts` asserts
-every `file_pattern` declared here is accepted by that predicate. The predicate
+in the tree parses this frontmatter at session time, and the two sets can drift.
+What holds them together is a test, not a dependency:
+`ui_rule_triggers.test.ts` asserts every `file_pattern` declared here is
+accepted by that predicate.
+
+**This rule carries no `keyword:` trigger any more (2026-08-17).** It used to,
+and the observation those keywords had no runtime consumer is what made removing
+them cheap: no host activation surface reads a keyword — Cursor and Windsurf
+activate on `globs` plus the description, Claude on `paths:`. What the keywords
+did do was expensive, and only on Claude: one non-path trigger makes the emitter
+write **no** `paths:` at all, which is why this rule loaded in every session from
+12.1.0 until the removal. It is path-scoped again, so the obligation now arrives
+on UI file contact — see `road-to-mixed-trigger-activation-cost` Phase 2. The predicate
 is deliberately wider (it also covers `.css`, `.scss`, `.astro`), because a
 measurement denominator and a routing trigger are not the same population.
 

package/dist/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 };