@event4u/agent-config 9.15.0 → 9.17.0

package/src/scripts/release.ts

@@ -118,6 +118,12 @@ import {
     perform_split,
     plan_split,
 } from './_lib/changelog_eras.js';
+import {
+    extract_changelog_section,
+    pr_body_from_section,
+    release_notes_from_section,
+    tag_message_from_section,
+} from './_lib/release_material.js';
 
 // `__doc__.splitlines()[0]` in `_parse_args` — the argparse description. Kept
 // as a referenceable constant so the first docstring line is preserved exactly.
@@ -517,6 +523,22 @@ interface RunResult {
  * stderr so release preflight failures are diagnosable without re-running with
  * a debugger.
  */
+/**
+ * Drill/test seam — when set, every external command run() would spawn is
+ * answered by this function instead. The check/die/CalledProcessError
+ * semantics of run() still apply to the simulated result, so the drill
+ * exercises the REAL error paths of the orchestration (release_drill.ts).
+ */
+type ExecOverride = (args: readonly string[]) => {
+    status: number;
+    stdout: string;
+    stderr: string;
+};
+let _exec_override: ExecOverride | null = null;
+function _set_exec_override(fn: ExecOverride | null): void {
+    _exec_override = fn;
+}
+
 function run(
     args: readonly string[],
     opts: { check?: boolean; capture?: boolean; cwd?: string | null } = {},
@@ -526,13 +548,15 @@ function run(
     const cwd = opts.cwd ?? REPO_ROOT;
 
     const [cmd, ...rest] = args;
-    const res = spawnSync(cmd as string, rest, {
-        cwd,
-        encoding: 'utf-8',
-        // capture_output=True → pipe; else inherit so child writes straight to
-        // this process's stdout/stderr (text mode, matching subprocess text=True).
-        stdio: capture ? ['ignore', 'pipe', 'pipe'] : ['inherit', 'inherit', 'inherit'],
-    });
+    const res = _exec_override
+        ? { ..._exec_override(args), error: undefined as Error | undefined }
+        : spawnSync(cmd as string, rest, {
+              cwd,
+              encoding: 'utf-8',
+              // capture_output=True → pipe; else inherit so child writes straight to
+              // this process's stdout/stderr (text mode, matching subprocess text=True).
+              stdio: capture ? ['ignore', 'pipe', 'pipe'] : ['inherit', 'inherit', 'inherit'],
+          });
 
     if (res.error) {
         // FileNotFoundError analogue (ENOENT) and other spawn failures — Python
@@ -619,6 +643,31 @@ export function _failed_checks_report(names: readonly string[]): string {
             'empty (docs/contracts/release-pr-gating.md § Mid-release fixes).',
         );
     }
+    if (names.includes('PR body equals CHANGELOG entry')) {
+        lines.push(
+            '',
+            'Surface equality: the PR body drifted from the CHANGELOG entry. A',
+            'resume run refreshes it from the branch head (release-truth Phase 1);',
+            'never hand-edit the PR body away from the changelog section.',
+        );
+    }
+    if (names.includes('Curated highlights plausible against the span')) {
+        lines.push(
+            '',
+            'Highlights: a curated `_none_` field contradicts the release span.',
+            'Fill the curated head in CHANGELOG.md on the release branch — the',
+            'gate output lists the deriving commits (release-truth Phase 2).',
+        );
+    }
+    if (names.includes('Blocking review findings dispositioned')) {
+        lines.push(
+            '',
+            'Dispositions: a blocking/high self-review finding has no committed',
+            'disposition. Ingest + adjudicate it in',
+            'agents/evidence/release-findings/<version>.json (release-truth Phase 3):',
+            '  ./scripts-run src/scripts/check_finding_dispositions --ingest <findings.json>',
+        );
+    }
     lines.push('', 'After fixing, resume with: task release -- --resume --yes', '');
     return lines.join('\n');
 }
@@ -634,22 +683,25 @@ export function _failed_checks_report(names: readonly string[]): string {
  * A short grace period gives GitHub time to register workflow runs on a
  * freshly-pushed branch.
  */
-function watch_pr_checks(): void {
-    // time.sleep(5) — blocking grace period. Never reached on any test path.
-    const until = Date.now() + 5000;
-    while (Date.now() < until) {
-        // busy-wait stand-in for time.sleep(5) without an event-loop yield.
+function watch_pr_checks(branch: string): void {
+    if (_exec_override === null) {
+        // time.sleep(5) — blocking grace period for GitHub to register runs
+        // on a freshly-pushed branch. Skipped under the drill seam: there is
+        // no GitHub to wait for, and 5s per simulated wait adds up.
+        const until = Date.now() + 5000;
+        while (Date.now() < until) {
+            // busy-wait stand-in for time.sleep(5) without an event-loop yield.
+        }
     }
-    const proc = spawnSync('gh', ['pr', 'checks', '--watch'], {
-        cwd: REPO_ROOT,
-        encoding: 'utf-8',
-        stdio: ['ignore', 'pipe', 'pipe'],
+    // The branch is passed explicitly — `gh` inferring the PR from HEAD
+    // resolved to `main` mid-run once (2026-08-03, 9.16.0 resume) and the
+    // whole release died on "no pull requests found for branch main".
+    const proc = run(['gh', 'pr', 'checks', branch, '--watch'], {
+        check: false,
+        capture: true,
     });
-    if (proc.error) {
-        throw proc.error;
-    }
     const output = ((proc.stdout || '') + (proc.stderr || '')).trim();
-    const returncode = proc.status ?? 0;
+    const returncode = proc.returncode;
     if (returncode === 0) {
         if (output) {
             process.stdout.write(output + '\n');
@@ -667,10 +719,9 @@ function watch_pr_checks(): void {
     if (output) {
         process.stderr.write(output + '\n');
     }
-    const summary = spawnSync('gh', ['pr', 'checks', '--json', 'name,bucket'], {
-        cwd: REPO_ROOT,
-        encoding: 'utf-8',
-        stdio: ['ignore', 'pipe', 'pipe'],
+    const summary = run(['gh', 'pr', 'checks', branch, '--json', 'name,bucket'], {
+        check: false,
+        capture: true,
     });
     const report = _failed_checks_report(_failed_check_names(summary.stdout ?? ''));
     if (report) {
@@ -679,6 +730,139 @@ function watch_pr_checks(): void {
     die(`PR checks failed (exit ${returncode})`);
 }
 
+/**
+ * Push the release branch, integrating a remote that moved under us.
+ *
+ * A GitHub-side "Update branch" click (or a concurrent resume run) advances
+ * `origin/<branch>` while the local ref stays behind; a bare `git push` is
+ * then rejected with "fetch first" and the whole release run dies (measured
+ * 2026-08-03, 9.15.0). Same-branch commits are never ours to drop, so the
+ * recovery is merge-and-retry, never force-push.
+ */
+function push_release_branch(branch: string): void {
+    const first = run(['git', 'push', '-u', REMOTE, branch], { check: false });
+    if (first.returncode === 0) {
+        return;
+    }
+    process.stdout.write(`↻  ${REMOTE}/${branch} moved — integrating and retrying push\n`);
+    run(['git', 'fetch', REMOTE, branch]);
+    run(['git', 'merge', '--no-edit', `${REMOTE}/${branch}`]);
+    run(['git', 'push', '-u', REMOTE, branch]);
+}
+
+/** mergeStateStatus of the branch's PR ('' when the probe fails). */
+function _pr_merge_state(branch: string): string {
+    const r = run(
+        ['gh', 'pr', 'view', branch, '--json', 'mergeStateStatus', '--jq', '.mergeStateStatus'],
+        {
+            check: false,
+            capture: true,
+        },
+    );
+    return r.returncode === 0 ? r.stdout.trim() : '';
+}
+
+/**
+ * Bound on update-and-retry rounds in merge_release_pr. Three is deliberate:
+ * main receiving unrelated merges three times inside one checks-wait window
+ * means the queue is hot and a human should decide, not a loop.
+ */
+const _MERGE_UPDATE_ROUNDS = 3;
+
+/**
+ * Merge the release PR, absorbing a moving base branch.
+ *
+ * Branch protection requires the head to be up to date with `main`, and
+ * `main` moves constantly (dependabot, unrelated merges) — so between the
+ * checks-wait and the merge the PR routinely flips to BEHIND and a bare
+ * `gh pr merge` dies with "the head branch is not up to date with the base
+ * branch" (measured 2026-08-03, 9.16.0). Recovery is mechanical and safe by
+ * construction: merging `origin/main` into `release/X.Y.Z` makes the fix
+ * files identical on both sides, so the release-PR diff stays inside the
+ * version-bump allowlist (docs/contracts/release-pr-gating.md § Mid-release
+ * fixes) — do it here instead of aborting the run.
+ */
+/**
+ * Re-derive the release-PR body from the CHANGELOG section at the current
+ * release-branch head and push it to the PR (release-truth Phase 1: one
+ * final source — late commits and maintainer edits on the branch must reach
+ * the PR body instead of leaving it frozen at plan time). Best-effort sync
+ * of the local branch first; a no-op when the derived body is unchanged.
+ */
+function _target_from_branch(branch: string): string {
+    return branch.replace(/^release\//u, '');
+}
+
+function _refresh_pr_body_from_head(branch: string, target: string): void {
+    run(['git', 'pull', '--ff-only', REMOTE, branch], { check: false });
+    const changelog = fs.readFileSync(CHANGELOG, 'utf-8');
+    const section = extract_changelog_section(changelog, target);
+    if (!section) {
+        die(`CHANGELOG.md at ${branch} head carries no section for ${target} — cannot derive PR body`);
+    }
+    const capped = _cap_body(section!.body, GH_PR_BODY_LIMIT - 200, '`CHANGELOG.md` in this PR');
+    const body = pr_body_from_section(capped, target);
+    const live = run(['gh', 'pr', 'view', branch, '--json', 'body', '-q', '.body'], {
+        check: false,
+        capture: true,
+    });
+    if (live.returncode === 0 && live.stdout.replace(/\r\n/gu, '\n').trim() === body.trim()) {
+        return;
+    }
+    run(['gh', 'pr', 'edit', branch, '--body', body]);
+}
+
+function merge_release_pr(branch: string, wait_for_checks: boolean): void {
+    if (git(['rev-parse', '--abbrev-ref', 'HEAD'], { capture: true }) !== branch) {
+        run(['git', 'checkout', branch]);
+    }
+    for (let round = 0; round <= _MERGE_UPDATE_ROUNDS; round++) {
+        // One final generation step at the final head: every merge attempt
+        // first re-derives the PR body from the branch-head CHANGELOG, so
+        // update rounds and maintainer edits can never desynchronize it.
+        _refresh_pr_body_from_head(branch, _target_from_branch(branch));
+        if (_pr_merge_state(branch) !== 'BEHIND') {
+            const merged = run(['gh', 'pr', 'merge', branch, '--merge', '--delete-branch'], {
+                check: false,
+            });
+            if (merged.returncode === 0) {
+                return;
+            }
+            if (_pr_merge_state(branch) !== 'BEHIND') {
+                // Not the moving-base failure — surface it unchanged.
+                throw new CalledProcessError(merged.returncode, [
+                    'gh',
+                    'pr',
+                    'merge',
+                    branch,
+                    '--merge',
+                    '--delete-branch',
+                ]);
+            }
+            // BEHIND appeared between the probe and the merge — fall through
+            // to the update below.
+        }
+        if (round === _MERGE_UPDATE_ROUNDS) {
+            break;
+        }
+        process.stdout.write(
+            `↻  head behind ${MAIN_BRANCH} (update round ${round + 1}/${_MERGE_UPDATE_ROUNDS}) — ` +
+                `merging ${REMOTE}/${MAIN_BRANCH} into ${branch} and re-running checks\n`,
+        );
+        run(['git', 'fetch', REMOTE, MAIN_BRANCH]);
+        run(['git', 'merge', '--no-edit', `${REMOTE}/${MAIN_BRANCH}`]);
+        push_release_branch(branch);
+        if (wait_for_checks) {
+            watch_pr_checks(branch);
+        }
+    }
+    die(
+        `release PR is still behind ${MAIN_BRANCH} after ${_MERGE_UPDATE_ROUNDS} update round(s) — ` +
+            `${MAIN_BRANCH} is moving faster than the checks complete. ` +
+            'Re-run when the queue quiets down: task release -- --resume --yes',
+    );
+}
+
 function have(bin: string): boolean {
     const res = spawnSync('which', [bin], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
     if (res.error) {
@@ -1596,27 +1780,37 @@ function execute(
         _step(4, total, 'PR already merged — skip push');
     } else {
         // `git push -u` is naturally idempotent — it prints "Everything
-        // up-to-date" when remote already matches. No probe needed.
+        // up-to-date" when remote already matches. push_release_branch
+        // additionally absorbs a remote that moved under us.
         _step(4, total, `Push ${branch} to ${REMOTE}`);
-        run(['git', 'push', '-u', REMOTE, branch]);
+        push_release_branch(branch);
     }
 
     // ─── 5. PR ──────────────────────────────────────────────────────────────
     if (pr_merged) {
         _step(5, total, `PR #${pr_info!['number']} already merged — skip`);
     } else if (resume && pr_state === 'OPEN') {
-        _step(5, total, `PR already open: ${pr_info!['url']}`);
+        // One final source: a resumed run re-derives the body from the
+        // branch-head CHANGELOG instead of leaving the plan-time snapshot —
+        // this was the 9.14.0 test-count desync (resume re-rendered from a
+        // later HEAD while the changelog kept the branch's entry).
+        _step(5, total, `PR already open: ${pr_info!['url']} — refresh body from branch head`);
+        _refresh_pr_body_from_head(branch, plan.target);
     } else {
         _step(5, total, 'Open pull request');
+        // Derive the PR body from the CHANGELOG section step 2 just wrote —
+        // the file is the single source; the in-memory plan is only its
+        // author (release-truth Phase 1).
+        const section = extract_changelog_section(fs.readFileSync(CHANGELOG, 'utf-8'), plan.target);
+        if (!section) {
+            die(`CHANGELOG.md carries no section for ${plan.target} — cannot derive PR body`);
+        }
         const pr_changelog = _cap_body(
-            plan.changelog_body,
+            section!.body,
             GH_PR_BODY_LIMIT - 200, // leave room for the prefix + footer
             '`CHANGELOG.md` in this PR',
         );
-        const pr_body =
-            `Release ${plan.target}.\n\n` +
-            `${pr_changelog}\n\n` +
-            'Created by `scripts/release.py`.';
+        const pr_body = pr_body_from_section(pr_changelog, plan.target);
         run([
             'gh',
             'pr',
@@ -1637,7 +1831,7 @@ function execute(
         _step(6, total, 'PR already merged — skip checks wait');
     } else if (wait_for_checks) {
         _step(6, total, 'Wait for PR checks');
-        watch_pr_checks();
+        watch_pr_checks(branch);
     } else {
         _step(6, total, 'Skip waiting for checks (--no-wait)');
     }
@@ -1647,7 +1841,7 @@ function execute(
         _step(7, total, `PR #${pr_info!['number']} already merged — skip`);
     } else {
         _step(7, total, 'Merge pull request (merge commit) and delete branch');
-        run(['gh', 'pr', 'merge', '--merge', '--delete-branch']);
+        merge_release_pr(branch, wait_for_checks);
     }
 
     // ─── 8. tag main + push tag ─────────────────────────────────────────────
@@ -1667,8 +1861,21 @@ function execute(
             run(['git', 'push', REMOTE, plan.target]);
         }
     } else {
-        _step(8, total, `Tag merge commit and push ${plan.target}`);
-        run(['git', 'tag', plan.target]);
+        // Sequencing is load-bearing (release-truth Phase 1, council
+        // 2026-08-03): merge FIRST (step 7), 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}`);
+        const merged = extract_changelog_section(fs.readFileSync(CHANGELOG, 'utf-8'), plan.target);
+        if (!merged) {
+            die(
+                `CHANGELOG.md on ${MAIN_BRANCH} carries no section for ${plan.target} — ` +
+                    'refusing to tag a release whose changelog entry is missing',
+            );
+        }
+        run(['git', 'tag', '-a', plan.target, '-m', tag_message_from_section(merged!.body, plan.target)]);
         run(['git', 'push', REMOTE, plan.target]);
     }
 
@@ -1683,8 +1890,19 @@ function execute(
                 ? 'Create GitHub Release (tag push under GITHUB_TOKEN triggers nothing — dispatching next)'
                 : 'Create GitHub Release (triggers publish-npm on the tag)',
         );
+        // One final source: the notes come from the CHANGELOG as recorded AT
+        // THE TAG — never from the plan-time render (whose scope can differ
+        // from the merged content; that was the 9.14.0 desync).
+        const tagged_changelog = git(['show', `${plan.target}:CHANGELOG.md`], { capture: true });
+        const tagged_section = extract_changelog_section(tagged_changelog, plan.target);
+        if (!tagged_section) {
+            die(
+                `CHANGELOG.md at tag ${plan.target} carries no section for ${plan.target} — ` +
+                    'refusing to publish release notes from a different source',
+            );
+        }
         const notes = _cap_body(
-            plan.changelog_body || `Release ${plan.target}`,
+            release_notes_from_section(tagged_section!.body, plan.target),
             GH_RELEASE_NOTES_LIMIT,
             '`CHANGELOG.md`',
         );
@@ -2260,5 +2478,14 @@ export {
     SEMVER_RE,
     _RELEASE_BRANCH_RE,
     MODULE_DOC_FIRST_LINE,
+    // Drill seam (release_drill.ts) — the step machinery under a simulated
+    // git/gh world, so orchestration bugs surface in vitest, not mid-release.
+    execute,
+    _set_exec_override,
+    push_release_branch,
+    merge_release_pr,
+    watch_pr_checks,
+    _pr_merge_state,
+    _MERGE_UPDATE_ROUNDS,
 };
 export type { Args };