From d624510b6de79b8b101310d3431b0610adb376f9 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sun, 6 Sep 2026 02:27:28 +0900 Subject: [PATCH] docs(scheduler): describe the pre-review refresh hold; correct the discarded-check figures docs/org-required-workflow-rollout.md described only the post-approval update-branch posture; the pre-review refresh (now held while current-head checks are in flight, #1937) is stated next to it. CHANGELOG's "22/28" and "21/30" counted phantom check-runs created and cancelled in the same instant; the evidence actually discarded per push was 10 and 11. Refs #1935 Co-Authored-By: Claude Fable 5.1 --- CHANGELOG.md | 1 + docs/org-required-workflow-rollout.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 46d599a320..4e8614b581 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,7 @@ ### Scheduler holds pre-review branch updates while checks are in flight +- Correction to the figures below: "22/28" and "21/30" count every check-run cancelled at the push; check-runs for jobs behind `needs:` are created and cancelled in the same instant, so the evidence actually discarded per push was 10 (#1926) and 11 (#1484). `docs/org-required-workflow-rollout.md` now describes the pre-review refresh and its in-flight hold alongside the post-approval `update-branch` posture. - `inspect_pr` now decides `wait` instead of `update_branch` when a behind, unreviewed head still has queued or running check runs (`has_in_flight_check_runs`, built on the existing `latest_check_runs`/`running_check_state`). Under a saturated runner queue each PR's own delayed `pull_request_target` scheduler run merged `main` into the head before review dispatch, cancelling every queued check on the old head (22/28 on #1926, 21/30 on #1484) and requeueing the PR at the back, so no head ever completed its checks: 76 of the 77 PRs merged into this repository since 2026-09-04 had 0/12 required contexts satisfied at merge time. The hold has no age cap on purpose -- a check that never finishes keeps the head in place instead of restarting that loop, and the update resumes once every newest check run is terminal. `CLAUDE.md` now describes both update paths. Tracked in #1935. ### CodeQL scan dispatch matrix serialisation diff --git a/docs/org-required-workflow-rollout.md b/docs/org-required-workflow-rollout.md index 88f6cc4deb..26af5fa971 100644 --- a/docs/org-required-workflow-rollout.md +++ b/docs/org-required-workflow-rollout.md @@ -207,7 +207,7 @@ The central `.github/workflows/pr-review-merge-scheduler.yml` is now part of the - Fork posture: fork or external-head PRs remain reviewable, but the scheduler does not direct-merge them and does not enable auto-merge for them. A maintainer must make the final merge decision after same-head OpenCode approval, same-head Strix evidence, required checks, and unresolved-thread checks are clean. - Branch freshness posture: the scheduler also runs after protected base-branch pushes to `main`, `develop`, or `master`, because those pushes can create the GitHub UI state where reviews are satisfied, auto-merge is enabled, checks are stale or failed, and the PR shows `Update branch` without a PR `synchronize` event. - Auto-merge posture: `auto_merge_enabled` PR events trigger the scheduler so an already stale branch is refreshed immediately after native auto-merge is turned on instead of waiting for the periodic schedule. If the same PR is already mergeable, the scheduler attempts the guarded direct merge immediately. -- Automation boundary: current-head failed checks and `ACTION_REQUIRED` checks are reported before branch updates, so an update attempt does not hide the concrete reason a PR cannot merge. `update-branch` handles approved `BEHIND` PRs and already queued auto-merge PRs only when there is no current-head failed or action-required check to diagnose first. `DIRTY` or `CONFLICTING` PRs still require author or maintainer conflict resolution guidance; current-head approved conflicts may keep or queue native GitHub auto-merge as a wait state while the conflict is repaired, but the scheduler must not treat queued auto-merge as a conflict resolver. +- Automation boundary: current-head failed checks and `ACTION_REQUIRED` checks are reported before branch updates, so an update attempt does not hide the concrete reason a PR cannot merge. `update-branch` handles approved `BEHIND` PRs and already queued auto-merge PRs only when there is no current-head failed or action-required check to diagnose first. Before review dispatch, an unapproved `BEHIND` PR is also refreshed so the review sees the current base -- but only when no current-head check run is still queued or running; while checks are in flight the scheduler decides `wait` instead of discarding that evidence (#1935, #1937). `DIRTY` or `CONFLICTING` PRs still require author or maintainer conflict resolution guidance; current-head approved conflicts may keep or queue native GitHub auto-merge as a wait state while the conflict is repaired, but the scheduler must not treat queued auto-merge as a conflict resolver. - Retry posture: before retrying OpenCode, the scheduler force-cancels older active OpenCode runs for the same PR number and a previous head SHA. It does not automatically cancel Strix runs because security evidence should not be silently discarded by force-push churn. Do not centralize the scheduler by running a `.github` scheduled job against other repositories with the `.github` repository token. That would either fail permission checks or use the wrong mutation actor. The central path is a required workflow executed in each target repository context.