@event4u/agent-config 14.23.0 → 16.0.0

package/src/scripts/release.ts

@@ -30,21 +30,21 @@
  *     3. Confirm           — show preview, ask once (skippable with --yes;
  *                            `--ci` always needs --yes — CI has no terminal).
  *     4. Branch + bump     — create `release/X.Y.Z`, update package.json,
- *                            .claude-plugin/marketplace.json, CHANGELOG.md,
- *                            then run `task release-prepare` so pack
- *                            manifests and tool projections pick up the
- *                            new version (otherwise the PR's own consistency
- *                            check fails — see PR #226 post-mortem).
+ *                            marketplace.json and CHANGELOG.md, then run
+ *                            `task release-prepare` so pack manifests and tool
+ *                            projections pick up the new version (skip it and
+ *                            the PR's own consistency check fails — PR #226).
  *     5. Commit + push     — `release: X.Y.Z`, push branch, open PR.
  *     6. Wait for CI       — `gh pr checks --watch` (skippable with --no-wait).
- *     7. Merge             — `gh pr merge --merge --delete-branch`.
- *     8. Tag main          — fast-forward main, tag the merge commit, push
- *                            the tag (triggers publish-npm.yml — except
- *                            under `--ci`, see step 9).
- *     9. GitHub Release     — `gh release create X.Y.Z --notes <changelog>`;
- *                            under `--ci`, also dispatches
- *                            release-guard.yml + publish-npm.yml +
- *                            cloud-release.yml explicitly.
+ *     7. Findings ledger   — VERIFY it is on the branch and dispositioned, and
+ *                            STOP otherwise; `self-review-gate.yml` builds it.
+ *     8. Merge             — `gh pr merge --merge --delete-branch`.
+ *     9. Tag main          — fast-forward main, tag the merge commit, push the
+ *                            tag (triggers publish-npm.yml, except under --ci).
+ *    10. GitHub Release    — `gh release create X.Y.Z --notes <changelog>`; under
+ *                            `--ci`, also dispatches release-guard.yml,
+ *                            publish-npm.yml and cloud-release.yml explicitly.
+ *    11. Cleanup           — delete the merged release branch, local + remote.
  *
  * Idempotency: pass `--resume` to recover from a partial failure. Each
  * step then probes existing state (branch, commit, PR, tag, GitHub
@@ -128,6 +128,8 @@ import {
 } from './_lib/release_highlights.js';
 import { canPrompt, promptLine } from './_lib/tty_prompt.js';
 import { preflightPosition } from './_lib/release_position.js';
+import { settleFindingsLedger } from './_lib/release_findings_ingest.js';
+import { TAG_TRIGGERED_WORKFLOWS, dispatchTagWorkflows } from './_lib/release_tag_dispatch.js';
 import {
     RELEASE_HEAD_DEFAULT,
     extract_changelog_section,
@@ -858,7 +860,7 @@ function preflight(target: string, opts: { resume?: boolean; ci?: boolean } = {}
     // The local-in-sync-with-origin check only applies to main; if we're
     // already on the release branch in resume mode, the relevant invariant
     // is "main hasn't moved beyond what release/X.Y.Z branched off", which
-    // `git pull --ff-only` enforces in step 8 anyway.
+    // `git pull --ff-only` enforces in step 9 anyway.
     if (branch === MAIN_BRANCH) {
         const local = git(['rev-parse', 'HEAD'], { capture: true });
         const remote = git(['rev-parse', `${REMOTE}/${MAIN_BRANCH}`], { capture: true });
@@ -972,7 +974,7 @@ export function confirmGate(target: string, yes: boolean): ConfirmVerdict {
     return { proceed: true };
 }
 
-// ─── orchestration ────────────────────────────────────────────────────────────
+// Orchestration.
 
 function _step(n: number, total: number, msg: string): void {
     process.stdout.write(`[${n}/${total}] ${msg}\n`);
@@ -988,7 +990,7 @@ function execute(
     const ci = opts.ci ?? false;
 
     const branch = `release/${plan.target}`;
-    const total = 10;
+    const total = 11;
 
     if (dry_run) {
         process.stdout.write('(dry-run) no git/gh mutations will be performed.\n');
@@ -1000,12 +1002,12 @@ function execute(
     const pr_state = pr_info ? pr_info['state'] : undefined;
     const pr_merged = pr_state === 'MERGED';
 
-    // ─── 1. branch ──────────────────────────────────────────────────────────
+    // Step 1 — branch
     checkout_release_branch(branch, pr_merged, (m) => {
         _step(1, total, m);
     });
 
-    // ─── 1b. era split (optional, separate commit) ─────────────────────────
+    // Step 1b — era split (optional, separate commit)
     // Lands as `chore(changelog): split era ...` BEFORE the release commit
     // so the split is reviewable on its own and the release commit only
     // touches the bump + new entry. Idempotent: archive already on disk
@@ -1038,7 +1040,7 @@ function execute(
         }
     }
 
-    // ─── 2. file mutations ──────────────────────────────────────────────────
+    // Step 2 — file mutations
     if (pr_merged) {
         _step(2, total, 'PR already merged — skip file bumps');
     } else {
@@ -1074,7 +1076,7 @@ function execute(
 
     guard_release_curation(plan.target, pr_merged);
 
-    // ─── 3. commit ──────────────────────────────────────────────────────────
+    // Step 3 — commit
     if (pr_merged) {
         _step(3, total, 'PR already merged — skip commit');
     } else {
@@ -1110,7 +1112,7 @@ function execute(
         // `git push -u` is naturally idempotent — it prints "Everything
         // up-to-date" when remote already matches. push_release_branch
         // additionally absorbs a remote that moved under us.
-        // Not a `_step`: a second `[4/10]` makes the cited evidence anchors ambiguous.
+        // Not a `_step`: a second `[4/11]` makes the cited evidence anchors ambiguous.
         process.stdout.write('        · verifying release gates locally (`task release:verify -- --cheap`)\n');
         run(local_release_gate_argv());
 
@@ -1147,7 +1149,7 @@ function execute(
             '--title', `release: ${plan.target}`, '--body', pr_body]);
     }
 
-    // ─── 6. wait for checks ─────────────────────────────────────────────────
+    // Step 6 — wait for checks
     if (pr_merged) {
         _step(6, total, 'PR already merged — skip checks wait');
     } else if (wait_for_checks) {
@@ -1157,17 +1159,23 @@ function execute(
         _step(6, total, 'Skip waiting for checks (--no-wait)');
     }
 
-    // ─── 7. merge ───────────────────────────────────────────────────────────
+    // Step 7 — the findings ledger: verify, never produce; the module says why.
+    settleFindingsLedger({
+        run, die, repoRoot: REPO_ROOT, remote: REMOTE, trunk: MAIN_BRANCH,
+        step: (m) => { _step(7, total, m); }, write: (s) => process.stdout.write(s),
+        resolvePr: () => Number((pr_info ?? _pr_for_branch(branch))?.['number'] ?? NaN) || null,
+    }, plan.target, branch, pr_merged);
+    // Step 8 — merge
     if (pr_merged) {
-        _step(7, total, `PR #${pr_info!['number']} already merged — skip`);
+        _step(8, total, `PR #${pr_info!['number']} already merged — skip`);
     } else {
-        _step(7, total, 'Merge pull request (merge commit) and delete branch');
+        _step(8, total, 'Merge pull request (merge commit) and delete branch');
         merge_release_pr(branch, wait_for_checks);
     }
 
-    // ─── 8. tag main + push tag ─────────────────────────────────────────────
+    // Step 9 — tag main + push tag
     // Always idempotent — even outside resume mode this prevents a mid-flight
-    // crash on step 9 from leaving a half-tagged release that subsequent
+    // crash on step 10 from leaving a half-tagged release that subsequent
     // `task release` invocations can't recover from without `--resume`.
     if (git(['rev-parse', '--abbrev-ref', 'HEAD'], { capture: true }) !== MAIN_BRANCH) {
         run(['git', 'checkout', MAIN_BRANCH]);
@@ -1176,29 +1184,29 @@ function execute(
 
     if (_tag_exists_local(plan.target)) {
         if (_tag_exists_remote(plan.target)) {
-            _step(8, total, `Tag ${plan.target} already on ${REMOTE} — skip`);
+            _step(9, total, `Tag ${plan.target} already on ${REMOTE} — skip`);
         } else {
-            _step(8, total, `Tag ${plan.target} exists locally — push only`);
+            _step(9, total, `Tag ${plan.target} exists locally — push only`);
             guard_publication(plan.target, 'tag push (resumed)');
             _push_tag(plan.target);
         }
     } else {
         // Sequencing is load-bearing (release-truth Phase 1, council
-        // 2026-08-03): merge FIRST (step 7), pull main (above), THEN derive
+        // 2026-08-03): merge FIRST (step 8), pull main (above), THEN derive
         // the tag message from the MERGED changelog — tagging before the
         // merge would read a section that does not exist yet. The annotated
         // tag replaces the previous lightweight one so tag metadata is a
         // fourth surface carrying the same single-source content.
-        _step(8, total, `Tag merge commit (annotated, from merged CHANGELOG) and push ${plan.target}`);
+        _step(9, total, `Tag merge commit (annotated, from merged CHANGELOG) and push ${plan.target}`);
         create_and_push_annotated_tag(plan.target);
     }
 
-    // ─── 9. GitHub Release ──────────────────────────────────────────────────
+    // Step 10 — GitHub Release
     if (_release_exists(plan.target)) {
-        _step(9, total, `GitHub Release ${plan.target} already exists — skip`);
+        _step(10, total, `GitHub Release ${plan.target} already exists — skip`);
     } else {
         _step(
-            9,
+            10,
             total,
             ci
                 ? 'Create GitHub Release (tag push under GITHUB_TOKEN triggers nothing — dispatching next)'
@@ -1223,7 +1231,7 @@ function execute(
         guard_publication(plan.target, 'GitHub Release notes');
         gh(['release', 'create', plan.target, '--title', plan.target, '--notes', notes]);
 
-        // ─── 9b. dispatch-chain the tag-triggered workflows (--ci only) ──────
+        // Step 10b — dispatch-chain the tag-triggered workflows (--ci only)
         // release-guard.yml, publish-npm.yml, and cloud-release.yml all
         // trigger on `push: tags: [0-9]+.[0-9]+.[0-9]+`, but a tag pushed
         // with the default GITHUB_TOKEN does NOT fire other workflows
@@ -1234,41 +1242,21 @@ function execute(
         // branch above), so a --resume re-run never re-dispatches a
         // publish that already happened.
         if (ci) {
-            _step(9, total, 'Dispatch release-guard.yml + publish-npm.yml + cloud-release.yml for the tag');
-            // NON-FATAL by design. By this point the release is already complete
-            // — the tag is pushed and the GitHub Release is created above, and
-            // npm publish runs asynchronously. These explicit dispatches are a
-            // FALLBACK for a tag pushed with the default GITHUB_TOKEN, which does
-            // NOT fire tag-triggered workflows (GitHub's recursion guard). When
-            // the tag was pushed with a PAT (RELEASE_PR_TOKEN), those three
-            // workflows already fired on the push and this dispatch is redundant.
-            // Dispatching via the API additionally needs the token's
-            // `actions:write` scope; a 403 here (scope missing) must NOT mark an
-            // already-shipped release as failed — warn and continue.
-            for (const wf of ['release-guard.yml', 'publish-npm.yml', 'cloud-release.yml']) {
-                const r = run(['gh', 'workflow', 'run', wf, '--ref', MAIN_BRANCH, '-f', `tag=${plan.target}`], {
-                    check: false,
-                });
-                if (r.returncode !== 0) {
-                    process.stderr.write(
-                        `⚠️  Could not dispatch ${wf} (exit ${r.returncode}) — the release ${plan.target} is ` +
-                            `already complete (tag + GitHub Release created; npm publishes async). If the tag was ` +
-                            `pushed with a PAT, ${wf} already fired on the tag push. If you rely on the explicit ` +
-                            `dispatch, grant RELEASE_PR_TOKEN the "Actions: read and write" scope (fine-grained PAT) ` +
-                            `or the "workflow" scope (classic PAT).\n`,
-                    );
-                }
-            }
+            _step(10, total, `Dispatch ${TAG_TRIGGERED_WORKFLOWS.join(' + ')} for the tag`);
+            dispatchTagWorkflows(
+                { run, warn: (s) => process.stderr.write(s), trunk: MAIN_BRANCH },
+                plan.target,
+            );
         }
     }
 
-    // ─── 10. delete the merged release branch (local + remote) ───────────────
+    // Step 11 — delete the merged release branch (local + remote)
     // Branch hygiene: a merged-but-undeleted release/X.Y.Z is what made
     // `--resume` mis-detect an old version. Delete it now so it can never
     // accumulate. Idempotent — skips whatever is already gone. Never touches
     // `main` or any tag.
     if (dry_run) {
-        _step(10, total, `Would delete merged branch ${branch} (local + remote)`);
+        _step(11, total, `Would delete merged branch ${branch} (local + remote)`);
     } else {
         const deleted: string[] = [];
         if (
@@ -1283,7 +1271,7 @@ function execute(
             deleted.push('remote');
         }
         const where = deleted.length > 0 ? deleted.join(' + ') : 'already gone';
-        _step(10, total, `Delete merged branch ${branch} (${where})`);
+        _step(11, total, `Delete merged branch ${branch} (${where})`);
     }
 
     process.stdout.write('\n');
@@ -1292,7 +1280,7 @@ function execute(
     process.stdout.write('   npm publish runs asynchronously via publish-npm.yml on the tag.\n');
 }
 
-// ─── entrypoint ───────────────────────────────────────────────────────────────
+// Entrypoint.
 
 /** Mirror of `argparse.Namespace` for this CLI. */
 interface Args {

package/src/scripts/release_drill.ts

@@ -143,6 +143,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 +190,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 +210,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
@@ -300,6 +322,9 @@ class FakeWorld {
     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;
@@ -321,6 +346,12 @@ class FakeWorld {
         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 {
@@ -483,6 +514,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}`);
     }
 }
@@ -515,6 +561,139 @@ function _count(world: FakeWorld, needle: string): number {
 }
 
 const SCENARIOS: Record<string, Scenario> = {
+    '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`',
@@ -664,7 +843,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 +870,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 +899,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 +972,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 +992,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 +1007,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 +1024,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,7 +1084,7 @@ 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 });

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

package/src/scripts/release_publication.ts

@@ -956,7 +956,7 @@ function _remote_tag_commit(tag: string): string | null {
 
 /**
  * Push a tag, tolerating exactly ONE failure: the concurrent-release race.
- * `_tag_exists_remote` in step 8 is a live check, but between it and this
+ * `_tag_exists_remote` in step 9 is a live check, but between it and this
  * push a parallel `task release` run can land the same tag (measured
  * 2026-08-09, 9.28.0). When the remote tag already points at the same commit
  * as the local one, the repository IS in the desired state — continue. Any