@event4u/agent-config 15.0.0 → 16.1.0

package/src/scripts/release_drill.ts

@@ -26,6 +26,7 @@
  */
 
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
@@ -37,6 +38,8 @@ import {
     Plan,
     SystemExitError,
 } from './release.js';
+import { releaseHoldPreflight } from './_lib/release_holds.js';
+import { die } from './release_publication.js';
 import { DERIVED_MARKER } from './_lib/release_highlights.js';
 import {
     AUGMENT_MARKETPLACE_JSON,
@@ -126,6 +129,33 @@ interface WorldConfig {
      * existed.
      */
     branch_behind_main?: number;
+    /**
+     * Commits `origin/<release-branch>` carries that this checkout does not.
+     *
+     * Sibling of `branch_behind_main`, one ref over: that one fakes `git
+     * rev-list --count HEAD..origin/main`, this one the distance to the
+     * release branch's OWN remote — the divergence a GitHub *Update branch*
+     * press or a concurrent resume run produces.
+     */
+    branch_behind_remote?: number;
+    /**
+     * Commits this checkout carries that `origin/<release-branch>` does not.
+     *
+     * Defaults to 1 so every pre-existing scenario keeps the local-ahead shape
+     * it was written against. Set to 0 together with `branch_behind_remote: 0`
+     * to reach the state where the remote is already AT head and the push must
+     * therefore not be issued at all.
+     */
+    branch_ahead_remote?: number;
+    /**
+     * Whether `origin/<release-branch>` exists at the start of the run.
+     *
+     * Internal state until 2026-09-12 — a scenario could only reach `false`
+     * indirectly, by having the run delete the branch. The remote-position
+     * probe added with `_remote_branch_state` has a never-pushed arm that no
+     * scenario could otherwise enter, so the knob is now declared.
+     */
+    branch_exists_remote?: boolean;
     /**
      * Whether `execute()` is invoked with `--resume`. Defaults to TRUE so every
      * pre-existing scenario keeps the shape it was written against.
@@ -143,6 +173,27 @@ interface WorldConfig {
     merge_fails_hard?: boolean;
     /** PR checks fail (watch exits non-zero) — the release must die. */
     checks_fail?: boolean;
+    /**
+     * Step 7's world — two knobs, because the step asks two questions.
+     *
+     * It VERIFIES: the ledger is produced by the self-review workflow, so the
+     * only things a scenario can vary are whether the file is on the remote
+     * branch and what the disposition gate answers. An earlier version of this
+     * step ingested, and carried four more knobs for run discovery and artifact
+     * download; those went with it when the owner moved the ingest into CI.
+     */
+    ledger_on_branch?: boolean;
+    /**
+     * Whether the ledger is on the TRUNK — the ref the merged path asks.
+     *
+     * Separate from `ledger_on_branch` because the two states worth testing are
+     * exactly the ones a single boolean cannot express: present on the branch
+     * and not on the trunk, and the reverse. Defaults to `ledger_on_branch`, so
+     * every scenario written before this knob keeps its answer.
+     */
+    ledger_on_trunk?: boolean;
+    /** Exit code + streams the disposition gate answers with. */
+    disposition_verdict?: { status: number; stdout: string; stderr: string };
     /**
      * Content `git show <target>:CHANGELOG.md` returns.
      *
@@ -169,7 +220,7 @@ interface WorldConfig {
     changelog?: string;
     /**
      * Content the WORKING-TREE read returns — `read_changelog_text()`, used by
-     * step 5 (PR body) and step 8 (annotated-tag message).
+     * step 5 (PR body) and step 9 (annotated-tag message).
      *
      * Added 2026-09-01 with the publication guard (roadmap § 3.1). `changelog`
      * above only covers `git show <tag>:CHANGELOG.md`; the working tree was
@@ -189,19 +240,20 @@ interface WorldConfig {
      */
     tag_created_unpushed?: boolean;
     /**
-     * The tag is already on the remote, so step 8 skips entirely and step 9 —
+     * The tag is already on the remote, so step 9 skips entirely and step 10 —
      * the GitHub Release body — is the FIRST irreversible transition the run
      * reaches. The only state in which the Release guard can be exercised on
-     * its own, because a marker otherwise stops the run at step 8.
+     * its own, because a marker otherwise stops the run at step 9.
      */
     tag_already_remote?: boolean;
     /**
      * The release PR is ALREADY merged when the run starts — the real
-     * resume-after-merge state, in which steps 1 through 7 skip and step 8 is
-     * the first step that does work.
+     * resume-after-merge state, in which steps 1 through 6 skip, step 7 still
+     * verifies the ledger (on the trunk, since the branch is gone) and step 8
+     * is the first step that does work.
      *
      * Added 2026-09-02 with `guard_release_branch_push`. Before that guard, a
-     * marker scenario could start from scratch and still reach step 8, because
+     * marker scenario could start from scratch and still reach step 9, because
      * nothing between the changelog write and the tag looked at the section.
      * The push guard now stops such a run at step 4 — correctly, and that is
      * the point of it — which makes this knob the only way left to exercise
@@ -297,9 +349,14 @@ class FakeWorld {
     private push_rejections: number;
     private behind_probes: number;
     private branch_behind_main: number;
+    private branch_behind_remote: number;
+    private readonly branch_ahead_remote: number;
     private merge_races_once: boolean;
     private merge_fails_hard: boolean;
     private checks_fail: boolean;
+    private readonly ledger_on_branch: boolean;
+    private readonly ledger_on_trunk: boolean | undefined;
+    private readonly disposition_verdict: { status: number; stdout: string; stderr: string };
     private readonly changelog: string;
     /** Working-tree content; see `WorldConfig.changelog_file`. */
     readonly changelog_file: string;
@@ -316,11 +373,20 @@ class FakeWorld {
         this.tag_remote = cfg.tag_already_remote ?? false;
         this.behind_probes = cfg.behind_probes ?? 0;
         this.branch_behind_main = cfg.branch_behind_main ?? 0;
+        this.branch_exists_remote = cfg.branch_exists_remote ?? true;
+        this.branch_behind_remote = cfg.branch_behind_remote ?? 0;
+        this.branch_ahead_remote = cfg.branch_ahead_remote ?? 1;
         this.merge_races_once = cfg.merge_races_once ?? false;
         this.merge_fails_hard = cfg.merge_fails_hard ?? false;
         this.checks_fail = cfg.checks_fail ?? false;
         this.pr_merged = cfg.pr_already_merged ?? false;
         this.release_verify_fails = cfg.release_verify_fails ?? false;
+        // Defaults keep every pre-2026-09-11 scenario green: the ledger is
+        // already on the branch and the gate is happy, so step 7 is a two-call
+        // no-op and the sequencing scenarios stay about sequencing.
+        this.ledger_on_branch = cfg.ledger_on_branch ?? true;
+        this.ledger_on_trunk = cfg.ledger_on_trunk;
+        this.disposition_verdict = cfg.disposition_verdict ?? { status: 0, stdout: '', stderr: '' };
     }
 
     exec(args: readonly string[]): ExecResult {
@@ -344,6 +410,18 @@ class FakeWorld {
             this.branch_behind_main = 0;
             return OK;
         }
+        if (cmd === `git rev-list --left-right --count HEAD...origin/${this.branch}`) {
+            return {
+                ...OK,
+                stdout: `${String(this.branch_ahead_remote)}\t${String(this.branch_behind_remote)}\n`,
+            };
+        }
+        if (cmd === `git merge --no-edit origin/${this.branch}`) {
+            // A real merge closes the gap, so the re-read sees 0 — the same
+            // reason the origin/main handler above zeroes its own counter.
+            this.branch_behind_remote = 0;
+            return OK;
+        }
         if (cmd === `git rev-parse --verify --quiet refs/heads/${this.branch}`) {
             return this.pr_merged ? { ...OK, status: 1 } : OK;
         }
@@ -483,6 +561,21 @@ class FakeWorld {
             return OK;
         }
 
+        // Step 7 — the findings ledger.
+        if (cmd.startsWith('git cat-file -e ')) {
+            // REF-AWARE, because one boolean for every ref made the two states
+            // that distinguish right from wrong inexpressible: on the branch
+            // but not the trunk, and the reverse. A fourth review named the
+            // merged-path scenario as asserting a string in the argv rather
+            // than the ref that was read.
+            const onTrunk = this.ledger_on_trunk ?? this.ledger_on_branch;
+            const present = cmd.includes('/main:') ? onTrunk : this.ledger_on_branch;
+            return present ? OK : { ...OK, status: 1 };
+        }
+        if (cmd.includes('check_finding_dispositions --release')) {
+            return { ...this.disposition_verdict };
+        }
+
         throw new Error(`FakeWorld: unscripted command: ${cmd}`);
     }
 }
@@ -498,6 +591,16 @@ interface Scenario {
     /** What the scenario proves — printed by the CLI. */
     summary: string;
     config: WorldConfig;
+    /**
+     * Run THIS instead of `execute()`.
+     *
+     * Added for the release-holds scenarios, whose boundary is `preflight()` —
+     * it runs before step 1 and therefore before `execute()`, so a scenario
+     * driving `execute()` could never reach it. Every pre-existing scenario
+     * omits the field and keeps `execute()` byte-identically; the override is
+     * additive and changes nothing it does not set.
+     */
+    run?: () => void;
     /** Whether execute() is expected to complete (vs die/throw). */
     expect_success: boolean;
     /** Extra assertions over the finished world; return failure strings. */
@@ -514,7 +617,270 @@ function _count(world: FakeWorld, needle: string): number {
     return world.calls.filter((c) => c === needle).length;
 }
 
+
+/* ------------------------------------------------------------------ *
+ * Release-holds fixtures (template rule 28, roadmap step 4.3).
+ *
+ * A throwaway tree per scenario, because the assertion is about what the
+ * evaluator READS — a mocked return would assert the mock.
+ * ------------------------------------------------------------------ */
+
+function _holdFixtureRoot(name: string, body: string): string {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), `release-holds-${name}-`));
+    const dir = path.join(root, 'agents', 'roadmaps');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'fixture.md'), body, 'utf8');
+    return root;
+}
+
+function _openHoldBody(channel: string): string {
+    return [
+        '## Phase 1',
+        '- [x] **1.1 opener** <!-- opens-hold: half-wired -->',
+        '      verify: the opener\'s own check',
+        '- [ ] **1.2 clearer** <!-- clears-hold: half-wired -->',
+        '      verify: ./scripts-run src/scripts/check_surface_whole',
+        '',
+        '## Release holds',
+        '',
+        '### hold: half-wired',
+        `- **Channel:** ${channel}`,
+        '- **Opened by:** 1.1',
+        '- **Cleared by:** 1.2',
+        '- **State:** the surface is half wired while this is open.',
+        '- **Why not a guard:** the entry point is reachable and cannot be made inert.',
+        '',
+    ].join('\n');
+}
+
 const SCENARIOS: Record<string, Scenario> = {
+    'release-hold-open-all-refuses-the-cut': {
+        summary:
+            'pre-flight: an open hold with `Channel: all` refuses the cut, naming the roadmap, the hold, its opener, its closer and the closer\'s verify command',
+        config: {},
+        expect_success: false,
+        run: () => {
+            releaseHoldPreflight(_holdFixtureRoot('all', _openHoldBody('all')), die);
+        },
+        verify: (_w, error) => {
+            const f: string[] = [];
+            const msg = error ?? '';
+            // All five fields, asserted individually. A refusal missing any one
+            // of them tells the operator they are stuck rather than what to do,
+            // which is the failure step 4.1 names.
+            for (const field of [
+                'fixture.md',
+                'half-wired',
+                'opened by:  1.1',
+                'cleared by: 1.2',
+                'check_surface_whole',
+            ]) {
+                _expect(msg.includes(field), `the refusal never named \`${field}\`: ${msg}`, f);
+            }
+            for (const way of ['finish the clearing step', '-next.N', 'release line']) {
+                _expect(msg.includes(way), `the refusal never offered \`${way}\`: ${msg}`, f);
+            }
+            return f;
+        },
+    },
+    'release-hold-open-latest-refuses-the-stable-cut': {
+        summary:
+            'pre-flight: an open hold with `Channel: latest` still refuses, because release.ts cuts a bare X.Y.Z and never silently redirects it to a prerelease',
+        config: {},
+        expect_success: false,
+        run: () => {
+            releaseHoldPreflight(_holdFixtureRoot('latest', _openHoldBody('latest')), die);
+        },
+        verify: (_w, error) => {
+            const f: string[] = [];
+            const msg = error ?? '';
+            _expect(msg.includes('half-wired'), `the refusal never named the hold: ${msg}`, f);
+            _expect(
+                msg.includes('channel latest'),
+                `the refusal never showed the hold's own channel: ${msg}`,
+                f,
+            );
+            // The silent-redirect prohibition, asserted as a behaviour rather
+            // than as a grep: the run DIED. A release.ts that quietly converted
+            // this into `-next.N` would have completed.
+            _expect(
+                msg.startsWith('SystemExit('),
+                `the stable cut was not refused — a silent channel redirect: ${msg}`,
+                f,
+            );
+            return f;
+        },
+    },
+    'release-hold-not-evaluable-refuses-the-cut': {
+        summary:
+            'pre-flight: a malformed declaration the evaluator cannot read refuses the cut — there is no path on which "could not evaluate" reads as safe',
+        config: {},
+        expect_success: false,
+        run: () => {
+            // Missing `Why not a guard:`, which rule 28 makes mandatory. The
+            // evaluator can parse the file but not trust the declaration, which
+            // is exactly the not-evaluable row.
+            const body = _openHoldBody('all').replace(
+                /- \*\*Why not a guard:\*\*.*\n/,
+                '',
+            );
+            releaseHoldPreflight(_holdFixtureRoot('bad', body), die);
+        },
+        verify: (_w, error) => {
+            const f: string[] = [];
+            const msg = error ?? '';
+            _expect(
+                msg.startsWith('SystemExit('),
+                `an unreadable declaration did not refuse — it failed OPEN: ${msg}`,
+                f,
+            );
+            _expect(
+                msg.includes('not evaluable'),
+                `the refusal did not say the declaration was unreadable: ${msg}`,
+                f,
+            );
+            _expect(
+                msg.includes('Why not a guard'),
+                `the refusal did not name what was wrong with it: ${msg}`,
+                f,
+            );
+            return f;
+        },
+    },
+
+    'findings-ledger-verified-on-the-remote-branch': {
+        summary:
+            'step 7: the ledger is on the remote branch and the gate passes — the release continues without producing anything',
+        // Step 7 VERIFIES. The ingest lives in the self-review workflow, which
+        // commits the ledger to the release branch; two review rounds showed no
+        // placement inside this script can produce it, because the gate it
+        // anticipates already reds the check step 6 waits on.
+        // `resume: false` is load-bearing, not tidiness. `resume` defaults to
+        // TRUE here, and on a resumed run the PR number is already in hand — so
+        // a scenario that kept the default could not see the `--pr` flag being
+        // dropped, which is exactly the hole this scenario asserts against.
+        config: { ledger_on_branch: true, resume: false },
+        expect_success: true,
+        verify: (w) => {
+            const f: string[] = [];
+            const probe = w.calls.find((c) => c.startsWith('git cat-file -e '));
+            _expect(probe !== undefined, 'the ledger presence was never probed', f);
+            _expect(
+                (probe ?? '').includes('origin/'),
+                `the probe read a local ref, which a failed push makes true: ${probe ?? '(none)'}`,
+                f,
+            );
+            _expect(
+                !w.calls.some((c) => c.includes('--ingest')),
+                'step 7 ingested — that belongs to the workflow now, not the release',
+                f,
+            );
+            _expect(
+                !w.calls.some((c) => c.startsWith('gh run download')),
+                'step 7 downloaded an artifact — the release no longer produces the ledger',
+                f,
+            );
+            // `--pr` is what makes the gate compare the review's own report
+            // against the committed ledger. The PR number used to come only
+            // from the resume-time probe, so on a FIRST run — this scenario —
+            // the flag was silently dropped and the release passed a strictly
+            // weaker check than the one it was trying to pre-satisfy.
+            _expect(
+                w.calls.some(
+                    (c) => c.includes('check_finding_dispositions --release') && c.includes('--pr '),
+                ),
+                'the disposition gate ran without --pr, so an un-ingested finding would pass here',
+                f,
+            );
+            _expect(
+                w.calls.includes(`gh pr merge ${w.branch} --merge --delete-branch`),
+                'the release never reached the merge',
+                f,
+            );
+            return f;
+        },
+    },
+    'findings-ledger-absent-stops-the-release': {
+        summary:
+            'step 7: no ledger on the remote branch — the release STOPS rather than merging and tagging without one',
+        config: { ledger_on_branch: false },
+        expect_success: false,
+        verify: (w, error) => {
+            const f: string[] = [];
+            _expect(
+                (error ?? '').includes('is not on origin/'),
+                `the stop did not name the ref it checked: ${error ?? '(no error)'}`,
+                f,
+            );
+            _expect(
+                !w.calls.includes(`gh pr merge ${w.branch} --merge --delete-branch`),
+                'merged with no ledger — the failure this step exists to end',
+                f,
+            );
+            _expect(!w.tag_remote, 'tagged with no ledger', f);
+            return f;
+        },
+    },
+    'findings-ledger-absent-after-a-hand-merge-still-stops': {
+        summary:
+            'step 7: the PR is already merged and no ledger reached the trunk — the release STOPS instead of tagging a version whose ledger does not exist',
+        // The reachable path to a shipped version with no ledger, and the one
+        // the old code asserted away: the ingest produces nothing, step 7
+        // stops, a human merges the PR, and the resumed run used to print "the
+        // ledger rode in with it" without reading anything.
+        // The two knobs differ on purpose: the ledger IS on the release branch
+        // and is NOT on the trunk. A run that read the branch ref would pass
+        // here, which is the wrong answer — the branch is deleted and the merge
+        // is what decides whether the ledger shipped.
+        config: { pr_already_merged: true, ledger_on_branch: true, ledger_on_trunk: false },
+        expect_success: false,
+        verify: (w, error) => {
+            const f: string[] = [];
+            _expect(
+                (error ?? '').includes('already merged'),
+                `the stop did not name the merged state: ${error ?? '(no error)'}`,
+                f,
+            );
+            _expect(
+                w.calls.some((c) => c.startsWith('git cat-file -e ') && c.includes('/main:')),
+                'the merged path never asked the trunk whether the ledger is there',
+                f,
+            );
+            _expect(!w.tag_remote, 'tagged a version whose findings ledger does not exist', f);
+            return f;
+        },
+    },
+    'findings-ledger-undispositioned-stops-and-shows-why': {
+        summary:
+            'step 7: the disposition gate refuses — the release stops and the operator is shown the gate report, not just its scan line',
+        config: {
+            ledger_on_branch: true,
+            disposition_verdict: {
+                status: 1,
+                stdout: 'scanned: 1',
+                stderr: '- `a1` (critical security: x): no disposition status',
+            },
+        },
+        expect_success: false,
+        verify: (w, error) => {
+            const f: string[] = [];
+            // The defect an independent review reproduced: the stop message
+            // preferred stdout, so the operator saw `scanned: 1` and the entire
+            // per-finding diagnosis — which the gate writes to stderr — was
+            // discarded on the one path where the message has to carry content.
+            _expect(
+                (error ?? '').includes('no disposition status'),
+                `the gate's own diagnosis was swallowed: ${error ?? '(no error)'}`,
+                f,
+            );
+            _expect(
+                !w.calls.includes(`gh pr merge ${w.branch} --merge --delete-branch`),
+                'merged over an undispositioned ledger',
+                f,
+            );
+            return f;
+        },
+    },
     'plain-run-reuses-an-existing-branch': {
         summary:
             'step 1: a PLAIN run (no --resume) over an existing release branch checks it out instead of dying at `git checkout -b`',
@@ -573,6 +939,81 @@ const SCENARIOS: Record<string, Scenario> = {
             return f;
         },
     },
+    'remote-branch-moved-merges-before-push': {
+        summary:
+            'step 4: a release branch that diverged on the remote is merged in BEFORE the push — not after a rejection the local preflight never lets git produce',
+        // Measured 2026-09-12 on 16.0.0. `origin/release/16.0.0` carried five
+        // commits this checkout did not have. `push_release_branch` has a
+        // merge-and-retry for exactly that, keyed on git's rejection wording —
+        // but the local pre-push preflight refused first, with
+        // `check_pr_ci_current`'s own message naming the divergence. git never
+        // printed `[rejected]`, `_is_non_fast_forward` correctly answered
+        // "not the fetch-and-retry case" on the text it was given, and the
+        // recovery was unreachable from the state it was written for.
+        config: { branch_behind_remote: 5 },
+        expect_success: true,
+        verify: (w) => {
+            const f: string[] = [];
+            const merge = w.calls.indexOf(`git merge --no-edit origin/${w.branch}`);
+            const push = w.calls.indexOf(`git push -u origin ${w.branch}`);
+            _expect(merge >= 0, 'the diverged remote branch was never merged in', f);
+            _expect(push >= 0, 'the branch was never pushed', f);
+            // Ordering is the whole point: a merge only AFTER the push means
+            // the reactive path ran, and that path is what the gate pre-empts.
+            _expect(
+                merge >= 0 && push >= 0 && merge < push,
+                'the remote branch was merged after the push, not before it',
+                f,
+            );
+            _expect(
+                _count(w, `git merge --no-edit origin/${w.branch}`) === 1,
+                'merged the remote branch more than once — the probe is not re-read after the merge',
+                f,
+            );
+            return f;
+        },
+    },
+    'remote-already-at-head-skips-the-push': {
+        summary:
+            'step 4: a remote already carrying this commit is not pushed to again — the no-op push still runs the pre-push hook, and the hook refuses',
+        // The second half of the same 16.0.0 failure, and the one no rejection
+        // text can reach. The push had succeeded; a resumed run re-entered
+        // step 4 and pushed again. `git push -u` is idempotent on the network
+        // side, but git runs the pre-push hook BEFORE discovering there is
+        // nothing to send — so the preflight was handed the head this run had
+        // just pushed, found its CI still pending, and killed the release.
+        config: { branch_ahead_remote: 0, branch_behind_remote: 0 },
+        expect_success: true,
+        verify: (w) => {
+            const f: string[] = [];
+            _expect(
+                !w.calls.includes(`git push -u origin ${w.branch}`),
+                'pushed a branch the remote already carries — that push runs the pre-push hook for nothing',
+                f,
+            );
+            return f;
+        },
+    },
+    'unpushed-branch-still-pushes': {
+        summary:
+            'step 4: a branch that was never pushed is pushed, and no distance is probed against a remote ref that does not exist',
+        // The near-miss for the direction the new probe opens: `git rev-list
+        // HEAD...origin/<branch>` against a missing ref is the 9.26.0 shape all
+        // over again — an exit from the recovery masking the real state.
+        // `--exit-code` on the ls-remote probe is what keeps it closed.
+        config: { branch_exists_remote: false },
+        expect_success: true,
+        verify: (w) => {
+            const f: string[] = [];
+            _expect(w.calls.includes(`git push -u origin ${w.branch}`), 'the branch was never pushed', f);
+            _expect(
+                !w.calls.includes(`git rev-list --left-right --count HEAD...origin/${w.branch}`),
+                'probed the distance to a remote ref that does not exist',
+                f,
+            );
+            return f;
+        },
+    },
     'local-gates-refuse-before-push': {
         summary:
             'step 4: a red local release gate stops the run BEFORE the branch is pushed — no branch on origin, no PR, no CI',
@@ -664,7 +1105,7 @@ const SCENARIOS: Record<string, Scenario> = {
     },
     'marker-refuses-before-tag': {
         summary:
-            'step 8: a draft marker in the merged section refuses BEFORE the annotated tag is created',
+            'step 9: a draft marker in the merged section refuses BEFORE the annotated tag is created',
         config: {
             pr_already_merged: true,
             changelog_file: markedChangelogFixture(current_version()),
@@ -691,7 +1132,7 @@ const SCENARIOS: Record<string, Scenario> = {
     },
     'marker-refuses-resumed-tag-push': {
         summary:
-            'step 8 (§ 3.2): a tag created but never pushed is NOT pushed when its section carries the marker',
+            'step 9 (§ 3.2): a tag created but never pushed is NOT pushed when its section carries the marker',
         config: {
             pr_already_merged: true,
             tag_created_unpushed: true,
@@ -720,7 +1161,7 @@ const SCENARIOS: Record<string, Scenario> = {
     },
     'marker-refuses-github-release': {
         summary:
-            'step 9: with the tag already pushed, a marker in the TAGGED section refuses before the Release is created',
+            'step 10: with the tag already pushed, a marker in the TAGGED section refuses before the Release is created',
         config: {
             pr_already_merged: true,
             tag_already_remote: true,
@@ -793,7 +1234,7 @@ const SCENARIOS: Record<string, Scenario> = {
         },
     },
     'behind-then-merge': {
-        summary: 'step 7: head BEHIND main — update branch, re-run checks, merge (9.16.0)',
+        summary: 'step 8: head BEHIND main — update branch, re-run checks, merge (9.16.0)',
         config: { behind_probes: 1 },
         expect_success: true,
         verify: (w, _err) => {
@@ -813,7 +1254,7 @@ const SCENARIOS: Record<string, Scenario> = {
         },
     },
     'merge-race-recovers': {
-        summary: 'step 7: main moves between the CLEAN probe and the merge — retry, not crash',
+        summary: 'step 8: main moves between the CLEAN probe and the merge — retry, not crash',
         config: { merge_races_once: true },
         expect_success: true,
         verify: (w, _err) => {
@@ -828,7 +1269,7 @@ const SCENARIOS: Record<string, Scenario> = {
         },
     },
     'behind-forever-dies': {
-        summary: `step 7: BEHIND persists past ${_MERGE_UPDATE_ROUNDS} update rounds — die with the resume command`,
+        summary: `step 8: BEHIND persists past ${_MERGE_UPDATE_ROUNDS} update rounds — die with the resume command`,
         config: { behind_probes: 99 },
         expect_success: false,
         verify: (w, err) => {
@@ -845,7 +1286,7 @@ const SCENARIOS: Record<string, Scenario> = {
         },
     },
     'merge-fails-hard-surfaces': {
-        summary: 'step 7: a non-BEHIND merge failure surfaces unchanged instead of looping',
+        summary: 'step 8: a non-BEHIND merge failure surfaces unchanged instead of looping',
         config: { merge_fails_hard: true },
         expect_success: false,
         verify: (w, err) => {
@@ -905,10 +1346,14 @@ function run_scenario(name: string): ScenarioOutcome {
     const tree_snapshot = _snapshot_step_2_files();
     _set_exec_override((args) => world.exec(args));
     // The working-tree read, faked for the same reason the command layer is.
-    // Without this the drill's step 8 reads the repository's real CHANGELOG.md.
+    // Without this the drill's step 9 reads the repository's real CHANGELOG.md.
     _set_changelog_reader(() => world.changelog_file);
     try {
-        execute(plan, { wait_for_checks: true, dry_run: false, resume: scenario.config.resume ?? true });
+        if (scenario.run !== undefined) {
+            scenario.run();
+        } else {
+            execute(plan, { wait_for_checks: true, dry_run: false, resume: scenario.config.resume ?? true });
+        }
     } catch (err) {
         if (err instanceof SystemExitError) {
             error = `SystemExit(${err.code}): ${captured.join('')}`;

package/src/scripts/release_env.ts

@@ -98,7 +98,7 @@ const CHANGELOG = path.join(REPO_ROOT, 'CHANGELOG.md');
  * Mirrors `_set_exec_override` in `release_publication.ts`, and exists for the
  * same reason: `execute()` reads `CHANGELOG.md` off disk at two points (the PR
  * body and the annotated-tag message), and the release drill fakes commands
- * but not the filesystem. Before this seam the drill's step 8 read the
+ * but not the filesystem. Before this seam the drill's step 9 read the
  * repository's REAL changelog — whose current section carries four
  * `_auto-derived, rewrite before merge:_` lines at `14.13.0` — so a
  * publication guard added at that call site refused every drill scenario for a