From 8ae93bc53dde526172c9fd02757b8eda7010f18b Mon Sep 17 00:00:00 2001 From: Danathar Date: Mon, 9 Nov 2026 10:10:48 -0500 Subject: [PATCH] fix(stage): park a fork PR's first red head on a fork guard instead of nudging its author On projectbluefin/utah-packages#972 (2026-11-09) a PR opened from Karibhou's fork at 14:41:50Z failed only its Canary fork guard at 14:42:24Z ("This is expected, not something the author can fix"). At 14:45:32Z the stage pass nudged the author with required-check-failing:Canary and queued relay rework: the fork-guard index had not read that head's annotation yet, and the stage record had never been parked on a guard, so foldForkGuard had nothing to carry. The PR reached 085 only at 14:50:57Z. foldForkGuard now classifies such a head itself when neither the index nor the record knows a guard: it reads the head's red checks' latest runs and their annotations once per head and red set, applies the index's own rule (hgithub.ForkGuardChecksFor), and when every red check is a fork guard the head goes to 085 with no nudge or adoption, and the record keeps the guard for later heads. A head red on anything else stays with its author and is not read again. The latest-run lookup is shared with forkGuardHeldOnHead. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1 Signed-off-by: Danathar --- changelog.d/fixed-fork-guard-first-head.md | 1 + src/docs/adr/0025-central-stage-engine.md | 4 +- .../stage-labels.md | 2 +- .../automerge/automerge_fork_guard_carry.go | 160 ++++++++++++++++-- .../automerge_fork_guard_first_head_test.go | 124 ++++++++++++++ .../automerge/automerge_stage_labels.go | 4 + .../automerge/automerge_stage_sharedci.go | 14 +- 7 files changed, 293 insertions(+), 16 deletions(-) create mode 100644 changelog.d/fixed-fork-guard-first-head.md create mode 100644 src/pkg/github/automerge/automerge_fork_guard_first_head_test.go diff --git a/changelog.d/fixed-fork-guard-first-head.md b/changelog.d/fixed-fork-guard-first-head.md new file mode 100644 index 0000000000..1954f14018 --- /dev/null +++ b/changelog.d/fixed-fork-guard-first-head.md @@ -0,0 +1 @@ +- A fork PR whose only red check is a maintainer-run fork guard (such as a fork-gated Canary) is parked for a maintainer at `stage/085-needs-decision` on its first red head, instead of being sent back to its author first. On projectbluefin/utah-packages#972 (2026-11-09) the PR was opened from a fork at 14:41:50Z, its Canary refused it at 14:42:24Z with "This is expected, not something the author can fix", and at 14:45:32Z the hive nudged the author with `required-check-failing:Canary` and queued relay rework, because neither the fork-guard index (not yet read for that head) nor the stage record (never parked on a guard) knew about it; the PR reached 085 only at 14:50:57Z. The stage pass now reads such a head's own check annotations once, with the index's rule, and records the guard for later heads. A fork head with any other red check still goes to its author. diff --git a/src/docs/adr/0025-central-stage-engine.md b/src/docs/adr/0025-central-stage-engine.md index 48f8082761..093d3ca06c 100644 --- a/src/docs/adr/0025-central-stage-engine.md +++ b/src/docs/adr/0025-central-stage-engine.md @@ -52,9 +52,9 @@ hub read that store and nothing else (`stageStoreOrShared`, `SyncIssueStageLabels` (`src/pkg/github/issue_stage_labels.go:205`, `src/pkg/github/issue_stage_labels.go:337`) from the enumeration bucket. PRs are staged by the automerge engine: each lane calls `recordStage` - (`src/pkg/github/automerge/automerge_stage_labels.go:365`), observations are + (`src/pkg/github/automerge/automerge_stage_labels.go:552`), observations are sorted by `stageLanePrecedence` (self 3 > trusted 2 > contributor 1, - `src/pkg/github/automerge/automerge_stage_labels.go:177`), each is classified + `src/pkg/github/automerge/automerge_stage_labels.go:245`), each is classified by `ClassifyStage` (`src/pkg/stageengine/derive_pr_classify.go:344`) into a ranked opinion (`prstage.RankNone..prstage.RankOwned`, `src/pkg/stageengine/prstage/types.go:145-148`), and diff --git a/src/docs/labels-and-control-signals/stage-labels.md b/src/docs/labels-and-control-signals/stage-labels.md index 314e75b193..9f5fb006fc 100644 --- a/src/docs/labels-and-control-signals/stage-labels.md +++ b/src/docs/labels-and-control-signals/stage-labels.md @@ -406,7 +406,7 @@ used to admit the PR: | `head-changed-since-eval`, `merge-failed`, `merge-queue-required` (the base branch's ruleset only accepts merges through GitHub's merge queue and the transport is a static token that cannot enqueue, so the direct REST merge is refused; with App auth on a repo opted in through `auto_merge.native_merge_queue` these bases are enqueued instead, see [native-merge-queue.md](../native-merge-queue.md); logged as a skip rather than a merge error, [#14018](https://github.com/hivecommons/hive/issues/14018); the self-authored sweep then skips the direct merge on that base for 30 minutes and logs the skip once per PR head, [#14068](https://github.com/hivecommons/hive/issues/14068); the trusted-author, queued and contributor-lane sweeps skip it the same way, sharing one memory of such bases; while a base is remembered the dashboard shows its otherwise-green PRs as a person's to merge, not Merge-eligible; with `auto_merge.require_current_base` on, a head behind such a base is not updated for 24 hours after the last refusal and holds here instead, so the base moving does not reset its review), `required-checks-expected`, `behind`, `updated-branch`, `behind-update-budget-exhausted` (a behind self-authored PR the sweep did not update only because this tick's branch-update budget was spent; retried next tick, waits on the hive, [#12607](https://github.com/hivecommons/hive/issues/12607)), `release-hold*`, `native-merge-queued: queued (position N, STATE)` (the PR was enqueued into GitHub's native merge queue) and the failures `native-merge-queue-read`, `native-merge-queue-enqueue`, `native-merge-queue-method` — and no red check on the head | `100-merge-queue` | | CI red (required or optional check) while the PR is deferred to an open `[shared-ci]` incident (``, the governor's `deferred_incident`) for the same head | `050-review-pending` / `060-reviewed`, reason `shared-ci-incident:`: the base or a shared check is what is red, so the PR is never sent to 070/071/072, never nudged and never stalled. A 072 nudge already posted for the head (the nudge goes out on entering 072, and the incident marker can land minutes later) is edited in place to say it was withdrawn, and the head's nudge count is reset. Once the incident closes the PR stays deferred until the shared-CI rerun sweep has re-run its failed jobs (at most 30 minutes); a head still red after that is handed back as usual, with a fresh nudge. Conflicts and requested changes stay author-facing ([#12606](https://github.com/hivecommons/hive/issues/12606)) | | CI red (required or optional) while **every** failing check on the head is also red on the base branch's tip — the governor's `base_red_checks` / `base_red`, set during CI enrichment when a same-named latest check run on the base ref (meta checks excluded) concluded failure / timed_out / cancelled / action_required / startup_failure / stale **and** the PR's changed files include none of `.github/workflows/*`, `Dockerfile` / `Dockerfile.*` / `*.Dockerfile`, `go.mod` / `go.sum` (a PR touching those plausibly owns the check and stays author-facing; a lookup error or a diff beyond the file-list page budget also stays author-facing) | `050-review-pending` / `060-reviewed`, reason `base-branch-red:,` ("waiting for the base branch's CI to recover (…) — not this PR's fault"): never 070/071/072, never nudged (a 072 nudge already posted for the head is edited in place to say it was withdrawn), never stalled, still not merged (the lane's skip reason is the same token). The fix loop counts no attempt, kicks no fixer, and posts one `` hold comment per head; an escalation the hive itself raised (ledger `label_applied`) over such a head has its `needs-human` removed with the hold wording. The next evaluation after the base goes green re-evaluates the head: a still-red PR is handed back as usual. Conflicts and requested changes stay author-facing (seen on [#13270](https://github.com/hivecommons/hive/pull/13270) and [#13258](https://github.com/hivecommons/hive/pull/13258), 2026-10-20) | -| CI red (required or optional) on a **fork** PR while **every** failing check's annotation says the check refuses forks (case-insensitive `fork pull request(s) cannot`, `maintainer must push this branch`, or `cannot publish` together with `fork` — a fork-publication / fork-secrets guard) | `085-needs-decision`, reason `fork-guard:,`: never 070/071/072, never nudged, never adopted (074) — neither the author nor the hive can turn the check green by pushing to the fork. The entry comment names the check and says a maintainer must push the branch to the repository (or run or approve it for head `` as the repository requires). A new head on the same fork PR (a merge of the base, or the author's push) keeps the guard while the lane's red check is one of the recorded `fork-guard:` checks, so the PR does not drop to 072 and nobody is nudged before the annotation for that head is read. The hive also does not update the branch of a fork head that waits on a fork-guarded check: the run a maintainer dispatches proves one exact head, and a merge of the base would discard it. Once the check is green the guard drops and updates resume before merge. While the PR stays parked across new heads, the entry comment is rewritten in place for each one, so it always names the current head, and it says that a run which passed on an earlier head does not cover this one even when the patch is the same, because a rebase or a merge of the base changes the code the check runs (projectbluefin/utah-packages#917). A same-repo PR with the same message, or a fork PR with any other red check, is handed back as usual ([#14273](https://github.com/hivecommons/hive/issues/14273), projectbluefin/utah-packages#862 and #869) | +| CI red (required or optional) on a **fork** PR while **every** failing check's annotation says the check refuses forks (case-insensitive `fork pull request(s) cannot`, `maintainer must push this branch`, or `cannot publish` together with `fork` — a fork-publication / fork-secrets guard) | `085-needs-decision`, reason `fork-guard:,`: never 070/071/072, never nudged, never adopted (074) — neither the author nor the hive can turn the check green by pushing to the fork. The entry comment names the check and says a maintainer must push the branch to the repository (or run or approve it for head `` as the repository requires). A new head on the same fork PR (a merge of the base, or the author's push) keeps the guard while the lane's red check is one of the recorded `fork-guard:` checks, so the PR does not drop to 072 and nobody is nudged before the annotation for that head is read. A fork PR head that nothing has classified yet (its first red head, or a PR that came to 072 for another reason first) is classified from its own check annotations with the same rule, once per head, before it can be nudged: a head red only on fork-guarded checks goes straight to 085 and the guard is recorded for later heads (projectbluefin/utah-packages#972, where the author was nudged and sent relay rework for a fork-gated Canary five minutes before the annotation was read). The hive also does not update the branch of a fork head that waits on a fork-guarded check: the run a maintainer dispatches proves one exact head, and a merge of the base would discard it. Once the check is green the guard drops and updates resume before merge. While the PR stays parked across new heads, the entry comment is rewritten in place for each one, so it always names the current head, and it says that a run which passed on an earlier head does not cover this one even when the patch is the same, because a rebase or a merge of the base changes the code the check runs (projectbluefin/utah-packages#917). A same-repo PR with the same message, or a fork PR with any other red check, is handed back as usual ([#14273](https://github.com/hivecommons/hive/issues/14273), projectbluefin/utah-packages#862 and #869) | | any **non-required** check on the current head is red, whatever the lane's reason (the lane gates on required checks only, so it still soaks and merges; a reader of the rollup sees ✗). Parking modifiers (`hold`, `needs-human`, admission reasons) still win | `070-fixing` / `071-needs-author` / `072-returned-to-contributor` (by author kind), reason `optional-check-failing:` (the nudge lists every red check); never 080 or 100. A red *required* check is the lane's own `required-check-failing:*` → 070/071/072 ([#12538](https://github.com/hivecommons/hive/issues/12538), seen on [#12457](https://github.com/hivecommons/hive/pull/12457)) | | `label:hold`, `held`, `label:needs-human`, `exempt-label`, `excluded-label:*`, `sentinel`, `human-merge-path*`, `intent-*`, `contributor-lane:workflow-path` / `tests-removed` / `no-reviewer` / `review-off` (a verdict is required but the review swarm is off, so none will be requested) / `reporter-trust-hold`, `workflow-permission` (GitHub refused update-branch or the merge-forward with a 403 because the base changed `.github/workflows/` and the token the hive used lacks the workflows permission; no token the hive holds can push that update, so it is not sent to 070), `fork-workflow-update` (the same update-branch refusal on a fork head: the App is not installed on the fork, so no grant lets it push there), `linked-issue:hold:#N: