diff --git a/changelog.d/changed-19279-merge-churn-ci-maintainer.md b/changelog.d/changed-19279-merge-churn-ci-maintainer.md new file mode 100644 index 0000000000..36b2070a76 --- /dev/null +++ b/changelog.d/changed-19279-merge-churn-ci-maintainer.md @@ -0,0 +1 @@ +- Agents no longer refresh pull requests that are merely behind their base. The ci-maintainer and quality prompts dropped "update the branch immediately when a merged change touches the same files", and the scanner no longer calls `update_pull_request_branch` on a PR that is only behind: on repositories using the current-base gate (`auto_merge.require_current_base`) the merge lane is the one preparation owner, and every extra refresh reran all of CI, cancelled the run in flight and restarted preparation. Agents now touch a behind branch only to repair a real conflict. `ci-maintainer-full` also gains a standing Merge Churn goal: a weekly bead with App refreshes per merged PR, runs cancelled by refreshes, release cadence and approval-to-merge latency, and one issue per repository while any named threshold (documented in `src/docs/hive-merge.md`) is crossed (#19279). diff --git a/src/docs/hive-merge.md b/src/docs/hive-merge.md index 72d71874cd..4bebd0061e 100644 --- a/src/docs/hive-merge.md +++ b/src/docs/hive-merge.md @@ -631,6 +631,38 @@ cannot stop external writers and does not relax strict current-base checks. Deploying the changed hive binary activates the policy; no agent, memory, review, CI, hold or authorization setting needs changing. +### Agents leave merely-behind PRs to the owner; ci-maintainer measures churn + +The preparation owner above is the only thing that refreshes a PR that is +merely behind. Agent prompts say so: the ci-maintainer and quality lanes +(item 4 of "CI Throughput and Merge Order" in every +`src/pkg/policies/defaults/ci-maintainer*.md` and `quality*.md` variant) and +the scanner's conflict section in `scanner-full.md` no longer call +`update-branch` / `update_pull_request_branch` on a PR that is only behind, +even when it touches the files of a change that just merged. A refresh by +anyone else reruns every pull_request workflow and cancels the run in +flight, which sends the owner back to the start. Agents touch a behind +branch only to repair a real conflict (`CONFLICTING` / `DIRTY`, or +`git merge-tree` exit 1), and the shared-baseline helper's `MERGE_BASE` +repair of a red check still applies. When an agent cannot tell whether the +gate applies to a repository it assumes it does; where the gate is off, the +merge train already updates overlapping siblings. `TestPoliciesDoNotRefreshMerelyBehindPRs` +in `src/pkg/policies/ci_throughput_test.go` keeps the old instructions out. + +`ci-maintainer-full.md` also carries a standing **Merge Churn** goal: once a +week it measures the primary repository's last 7 days (at most the 100 most +recently merged PRs), writes one `merge churn: week of ` bead, and +keeps one open `[ci-maintainer] Merge churn over threshold in ` +issue while any threshold is crossed (a comment per new week, closed after a +full week back under every threshold). + +| Measure | Name | Over threshold when | +| --- | --- | --- | +| App base refreshes per merged PR | `refreshes_per_merged_pr` | mean above 1.5 | +| pull_request runs cancelled on a head a refresh replaced | `refresh_cancelled_run_share` | above 20% of the week's pull_request runs | +| Releases published per day | `release_merges_per_day` | above 6 | +| Latest approving review to merge | `approval_to_merge_median` / `approval_to_merge_p90` | median above 4h or p90 above 24h | + ### CI reporting reconciliation An unfinished required check is not green merely because its Actions workflow diff --git a/src/pkg/policies/ci_throughput_test.go b/src/pkg/policies/ci_throughput_test.go index 3577073331..bff2d6c872 100644 --- a/src/pkg/policies/ci_throughput_test.go +++ b/src/pkg/policies/ci_throughput_test.go @@ -34,6 +34,8 @@ func TestCIPoliciesRequireThroughputAndMergeOrder(t *testing.T) { []byte("git merge-tree --write-tree --name-only"), []byte(""), []byte("update-branch"), + []byte("defer to the preparation owner"), + []byte("auto_merge.require_current_base"), []byte("cancel-in-progress"), []byte("cache: false"), []byte("Never add path"), @@ -64,3 +66,65 @@ func TestCIPoliciesRequireThroughputAndMergeOrder(t *testing.T) { }) } } + +// Agents must not refresh a PR that is merely behind its base: on +// current-base repositories the merge lane is the one preparation owner, and +// every extra refresh reruns all of CI and cancels the run in flight. The +// old "update immediately" and "simply behind main" instructions must not +// come back in any variant. +func TestPoliciesDoNotRefreshMerelyBehindPRs(t *testing.T) { + t.Parallel() + + banned := [][]byte{ + []byte("should be updated immediately"), + []byte("conflicts when the PR branch is simply behind main"), + } + entries, err := DefaultPolicies.ReadDir("defaults") + if err != nil { + t.Fatalf("read embedded policies: %v", err) + } + for _, entry := range entries { + name := entry.Name() + embedded, err := DefaultPolicies.ReadFile(path.Join("defaults", name)) + if err != nil { + t.Fatalf("read embedded policy %s: %v", name, err) + } + for _, phrase := range banned { + if bytes.Contains(embedded, phrase) { + t.Errorf("%s tells agents to refresh a merely-behind PR again (%q)", name, phrase) + } + } + } + + scanner, err := DefaultPolicies.ReadFile(path.Join("defaults", "scanner-full.md")) + if err != nil { + t.Fatalf("read scanner-full.md: %v", err) + } + if !bytes.Contains(scanner, []byte("Do NOT call MCP `update_pull_request_branch` on it")) { + t.Error("scanner-full.md no longer tells the scanner to leave merely-behind PRs to the preparation owner") + } +} + +// ci-maintainer-full carries the standing merge-churn goal: four weekly +// measurements, named thresholds, and one issue per repository. +func TestCIMaintainerFullTracksMergeChurn(t *testing.T) { + t.Parallel() + + policy, err := DefaultPolicies.ReadFile(path.Join("defaults", "ci-maintainer-full.md")) + if err != nil { + t.Fatalf("read ci-maintainer-full.md: %v", err) + } + for _, marker := range []string{ + "## Merge Churn (standing goal)", + "`refreshes_per_merged_pr`", + "`refresh_cancelled_run_share`", + "`release_merges_per_day`", + "`approval_to_merge_median`", + "merge churn: week of", + "[ci-maintainer] Merge churn over threshold in", + } { + if !bytes.Contains(policy, []byte(marker)) { + t.Errorf("ci-maintainer-full.md is missing merge-churn marker %q", marker) + } + } +} diff --git a/src/pkg/policies/defaults/ci-maintainer-advisory.md b/src/pkg/policies/defaults/ci-maintainer-advisory.md index aaa11e1eba..ef10a91b7e 100644 --- a/src/pkg/policies/defaults/ci-maintainer-advisory.md +++ b/src/pkg/policies/defaults/ci-maintainer-advisory.md @@ -39,10 +39,24 @@ test problem. Check these before diagnosing any single PR: say so on the PR once and prefer the order that rebases the smaller diff. Use a sticky comment (edit the existing one, marker ``) rather than a new comment each run. -4. **Behind the base.** After the base branch moves, a PR that touches the - same files as the merged change should be updated immediately - (`gh api -X PUT repos//pulls//update-branch`), not left to - turn red later. A `422` means it now conflicts: report it under item 3. +4. **Behind the base: defer to the preparation owner.** Do not update a PR + branch merely because the base moved, even when it touches the same files + as the merged change. On repositories that use the current-base gate + (`auto_merge.require_current_base`, per repository or through + `auto_merge.require_current_base_default`), the hive's merge lane is the + one preparation owner: it refreshes a behind PR once its CI and review + pass, then waits for CI on the new head. Every extra refresh starts a + second full CI run, cancels the one in flight, and sends the owner back to + the start. If you cannot tell whether the gate applies, assume it does. + Where it is off, the merge train (on by default) updates overlapping + siblings after each merge, so the rule is the same. Touch a behind branch + only to repair a real conflict: GitHub reports the PR `CONFLICTING` / + `DIRTY`, or item 3's `git merge-tree` exits 1 against the base. Never call + `gh api -X PUT repos//pulls//update-branch` on a PR that + is only behind; on a conflict it returns `422` anyway, so report it under + item 3 and follow your lane's conflict rules. A `MERGE_BASE` verdict from + the shared-baseline helper on a red check is a repair, not a refresh, and + still applies. 5. **Throughput fixes worth a PR.** When a repository's CI is slow, look for and propose, one PR each: a missing `concurrency` group with `cancel-in-progress` on pull_request workflows; `actions/setup-go` / diff --git a/src/pkg/policies/defaults/ci-maintainer-full.md b/src/pkg/policies/defaults/ci-maintainer-full.md index 5625634c3f..cc6563d5f3 100644 --- a/src/pkg/policies/defaults/ci-maintainer-full.md +++ b/src/pkg/policies/defaults/ci-maintainer-full.md @@ -97,10 +97,24 @@ test problem. Check these before diagnosing any single PR: say so on the PR once and prefer the order that rebases the smaller diff. Use a sticky comment (edit the existing one, marker ``) rather than a new comment each run. -4. **Behind the base.** After the base branch moves, a PR that touches the - same files as the merged change should be updated immediately - (`gh api -X PUT repos//pulls//update-branch`), not left to - turn red later. A `422` means it now conflicts: report it under item 3. +4. **Behind the base: defer to the preparation owner.** Do not update a PR + branch merely because the base moved, even when it touches the same files + as the merged change. On repositories that use the current-base gate + (`auto_merge.require_current_base`, per repository or through + `auto_merge.require_current_base_default`), the hive's merge lane is the + one preparation owner: it refreshes a behind PR once its CI and review + pass, then waits for CI on the new head. Every extra refresh starts a + second full CI run, cancels the one in flight, and sends the owner back to + the start. If you cannot tell whether the gate applies, assume it does. + Where it is off, the merge train (on by default) updates overlapping + siblings after each merge, so the rule is the same. Touch a behind branch + only to repair a real conflict: GitHub reports the PR `CONFLICTING` / + `DIRTY`, or item 3's `git merge-tree` exits 1 against the base. Never call + `gh api -X PUT repos//pulls//update-branch` on a PR that + is only behind; on a conflict it returns `422` anyway, so report it under + item 3 and follow your lane's conflict rules. A `MERGE_BASE` verdict from + the shared-baseline helper on a red check is a repair, not a refresh, and + still applies. 5. **Throughput fixes worth a PR.** When a repository's CI is slow, look for and propose, one PR each: a missing `concurrency` group with `cancel-in-progress` on pull_request workflows; `actions/setup-go` / @@ -130,6 +144,64 @@ the file has no other open PRs against it, so the split does not become one more collision. Do not splinter: if the issue's evidence table no longer holds (few PRs, no overlaps), say so on the issue and close it instead. +## Merge Churn (standing goal) + +Base refreshes are the most expensive thing CI does that finds nothing: each +one reruns every pull_request workflow on a head whose PR content did not +change, and cancels the run in flight. Keep that cost visible and falling. +This is a standing item: it never closes, and it is measured, not fixed by +touching PRs (see item 4 of CI Throughput and Merge Order). + +**Measure weekly.** On your first kick on or after Monday 00:00 UTC, skip if +your newest `merge churn` bead is less than 7 days old. Otherwise measure the +previous 7 days on the primary repository's default branch. The PR and run +reads below are measurement only, an exception to any work-list prohibition +on listing PRs; never use them to select work. Take at most the 100 most +recently merged PRs (`gh pr list --repo --state merged --base + --search "merged:>=" --limit 100 --json +number,mergedAt`) and say so in the report when the cap was hit. + +1. **Refreshes per merged PR** (`refreshes_per_merged_pr`): for each merged + PR, count its commits that are the hive App's base refresh (authored by + the App's bot login, message `Merge branch '' into `): + `gh api repos//pulls//commits --paginate`. Report the mean + and the PR with the most. +2. **CI runs cancelled by refreshes** (`refresh_cancelled_run_share`): for + each refresh commit from 1, its non-base parent is the head it replaced; + count that head's cancelled pull_request runs + (`gh api "repos//actions/runs?head_sha=&status=cancelled"`). + Report the count and its share of all pull_request runs created in the + week. +3. **Release-merge cadence** (`release_merges_per_day`): releases published + in the week (`gh release list --repo --limit 100 --json + tagName,publishedAt`) divided by 7. Every release commit moves the base + and makes every open PR behind. +4. **Approval-to-merge latency** (`approval_to_merge_median`, + `approval_to_merge_p90`): for each merged PR, merge time minus its latest + `APPROVED` review (`gh api repos//pulls//reviews`); skip + PRs with none. Report median and p90. + +**Report.** Write one bead per week, title `merge churn: week of +`, priority 3 (2 when any threshold below is crossed), with the +four numbers, last week's numbers beside them, and the caps you hit. + +**Thresholds** (named so the report and the issue can cite them): + +| Name | Over threshold when | +| --- | --- | +| `refreshes_per_merged_pr` | mean above 1.5 | +| `refresh_cancelled_run_share` | above 20% of the week's pull_request runs | +| `release_merges_per_day` | above 6 | +| `approval_to_merge_median` / `approval_to_merge_p90` | median above 4h or p90 above 24h | + +**Escalate once.** When any threshold is crossed, keep ONE open issue per +repository, stable title `[ci-maintainer] Merge churn over threshold in +`, label `ci`: the numbers, which thresholds they cross, the +worst PRs as evidence, and the likeliest lever (release cadence, refresh +ordering, a slow lane). If that issue is already open, add one comment with +the new week's numbers instead of a new issue. When a full week is back +under every threshold, say so in one comment and close it. + ## Opening Issues **Scope each issue so a single PR can close it.** When a finding enumerates @@ -231,7 +303,8 @@ checks are green — waiting buys nothing. 5. Create a GitHub issue for each confirmed problem 6. For problems with a clear fix, create a worktree and open a PR 7. Create a bead for each finding -8. Summarize CI health in your response +8. Weekly: run the Merge Churn measurement when it is due +9. Summarize CI health in your response ${KNOWLEDGE} diff --git a/src/pkg/policies/defaults/ci-maintainer-holdgated.md b/src/pkg/policies/defaults/ci-maintainer-holdgated.md index 0b0c3e211f..099b0da405 100644 --- a/src/pkg/policies/defaults/ci-maintainer-holdgated.md +++ b/src/pkg/policies/defaults/ci-maintainer-holdgated.md @@ -96,10 +96,24 @@ test problem. Check these before diagnosing any single PR: say so on the PR once and prefer the order that rebases the smaller diff. Use a sticky comment (edit the existing one, marker ``) rather than a new comment each run. -4. **Behind the base.** After the base branch moves, a PR that touches the - same files as the merged change should be updated immediately - (`gh api -X PUT repos//pulls//update-branch`), not left to - turn red later. A `422` means it now conflicts: report it under item 3. +4. **Behind the base: defer to the preparation owner.** Do not update a PR + branch merely because the base moved, even when it touches the same files + as the merged change. On repositories that use the current-base gate + (`auto_merge.require_current_base`, per repository or through + `auto_merge.require_current_base_default`), the hive's merge lane is the + one preparation owner: it refreshes a behind PR once its CI and review + pass, then waits for CI on the new head. Every extra refresh starts a + second full CI run, cancels the one in flight, and sends the owner back to + the start. If you cannot tell whether the gate applies, assume it does. + Where it is off, the merge train (on by default) updates overlapping + siblings after each merge, so the rule is the same. Touch a behind branch + only to repair a real conflict: GitHub reports the PR `CONFLICTING` / + `DIRTY`, or item 3's `git merge-tree` exits 1 against the base. Never call + `gh api -X PUT repos//pulls//update-branch` on a PR that + is only behind; on a conflict it returns `422` anyway, so report it under + item 3 and follow your lane's conflict rules. A `MERGE_BASE` verdict from + the shared-baseline helper on a red check is a repair, not a refresh, and + still applies. 5. **Throughput fixes worth a PR.** When a repository's CI is slow, look for and propose, one PR each: a missing `concurrency` group with `cancel-in-progress` on pull_request workflows; `actions/setup-go` / diff --git a/src/pkg/policies/defaults/ci-maintainer.md b/src/pkg/policies/defaults/ci-maintainer.md index 3290702d06..729191e6dc 100644 --- a/src/pkg/policies/defaults/ci-maintainer.md +++ b/src/pkg/policies/defaults/ci-maintainer.md @@ -109,10 +109,24 @@ test problem. Check these before diagnosing any single PR: say so on the PR once and prefer the order that rebases the smaller diff. Use a sticky comment (edit the existing one, marker ``) rather than a new comment each run. -4. **Behind the base.** After the base branch moves, a PR that touches the - same files as the merged change should be updated immediately - (`gh api -X PUT repos//pulls//update-branch`), not left to - turn red later. A `422` means it now conflicts: report it under item 3. +4. **Behind the base: defer to the preparation owner.** Do not update a PR + branch merely because the base moved, even when it touches the same files + as the merged change. On repositories that use the current-base gate + (`auto_merge.require_current_base`, per repository or through + `auto_merge.require_current_base_default`), the hive's merge lane is the + one preparation owner: it refreshes a behind PR once its CI and review + pass, then waits for CI on the new head. Every extra refresh starts a + second full CI run, cancels the one in flight, and sends the owner back to + the start. If you cannot tell whether the gate applies, assume it does. + Where it is off, the merge train (on by default) updates overlapping + siblings after each merge, so the rule is the same. Touch a behind branch + only to repair a real conflict: GitHub reports the PR `CONFLICTING` / + `DIRTY`, or item 3's `git merge-tree` exits 1 against the base. Never call + `gh api -X PUT repos//pulls//update-branch` on a PR that + is only behind; on a conflict it returns `422` anyway, so report it under + item 3 and follow your lane's conflict rules. A `MERGE_BASE` verdict from + the shared-baseline helper on a red check is a repair, not a refresh, and + still applies. 5. **Throughput fixes worth a PR.** When a repository's CI is slow, look for and propose, one PR each: a missing `concurrency` group with `cancel-in-progress` on pull_request workflows; `actions/setup-go` / diff --git a/src/pkg/policies/defaults/quality-advisory.md b/src/pkg/policies/defaults/quality-advisory.md index 1ea4ac4705..08be1b9516 100644 --- a/src/pkg/policies/defaults/quality-advisory.md +++ b/src/pkg/policies/defaults/quality-advisory.md @@ -39,10 +39,24 @@ test problem. Check these before diagnosing any single PR: say so on the PR once and prefer the order that rebases the smaller diff. Use a sticky comment (edit the existing one, marker ``) rather than a new comment each run. -4. **Behind the base.** After the base branch moves, a PR that touches the - same files as the merged change should be updated immediately - (`gh api -X PUT repos//pulls//update-branch`), not left to - turn red later. A `422` means it now conflicts: report it under item 3. +4. **Behind the base: defer to the preparation owner.** Do not update a PR + branch merely because the base moved, even when it touches the same files + as the merged change. On repositories that use the current-base gate + (`auto_merge.require_current_base`, per repository or through + `auto_merge.require_current_base_default`), the hive's merge lane is the + one preparation owner: it refreshes a behind PR once its CI and review + pass, then waits for CI on the new head. Every extra refresh starts a + second full CI run, cancels the one in flight, and sends the owner back to + the start. If you cannot tell whether the gate applies, assume it does. + Where it is off, the merge train (on by default) updates overlapping + siblings after each merge, so the rule is the same. Touch a behind branch + only to repair a real conflict: GitHub reports the PR `CONFLICTING` / + `DIRTY`, or item 3's `git merge-tree` exits 1 against the base. Never call + `gh api -X PUT repos//pulls//update-branch` on a PR that + is only behind; on a conflict it returns `422` anyway, so report it under + item 3 and follow your lane's conflict rules. A `MERGE_BASE` verdict from + the shared-baseline helper on a red check is a repair, not a refresh, and + still applies. 5. **Throughput fixes worth a PR.** When a repository's CI is slow, look for and propose, one PR each: a missing `concurrency` group with `cancel-in-progress` on pull_request workflows; `actions/setup-go` / diff --git a/src/pkg/policies/defaults/quality-full.md b/src/pkg/policies/defaults/quality-full.md index d167a12627..f1e406b1e6 100644 --- a/src/pkg/policies/defaults/quality-full.md +++ b/src/pkg/policies/defaults/quality-full.md @@ -77,10 +77,24 @@ test problem. Check these before diagnosing any single PR: say so on the PR once and prefer the order that rebases the smaller diff. Use a sticky comment (edit the existing one, marker ``) rather than a new comment each run. -4. **Behind the base.** After the base branch moves, a PR that touches the - same files as the merged change should be updated immediately - (`gh api -X PUT repos//pulls//update-branch`), not left to - turn red later. A `422` means it now conflicts: report it under item 3. +4. **Behind the base: defer to the preparation owner.** Do not update a PR + branch merely because the base moved, even when it touches the same files + as the merged change. On repositories that use the current-base gate + (`auto_merge.require_current_base`, per repository or through + `auto_merge.require_current_base_default`), the hive's merge lane is the + one preparation owner: it refreshes a behind PR once its CI and review + pass, then waits for CI on the new head. Every extra refresh starts a + second full CI run, cancels the one in flight, and sends the owner back to + the start. If you cannot tell whether the gate applies, assume it does. + Where it is off, the merge train (on by default) updates overlapping + siblings after each merge, so the rule is the same. Touch a behind branch + only to repair a real conflict: GitHub reports the PR `CONFLICTING` / + `DIRTY`, or item 3's `git merge-tree` exits 1 against the base. Never call + `gh api -X PUT repos//pulls//update-branch` on a PR that + is only behind; on a conflict it returns `422` anyway, so report it under + item 3 and follow your lane's conflict rules. A `MERGE_BASE` verdict from + the shared-baseline helper on a red check is a repair, not a refresh, and + still applies. 5. **Throughput fixes worth a PR.** When a repository's CI is slow, look for and propose, one PR each: a missing `concurrency` group with `cancel-in-progress` on pull_request workflows; `actions/setup-go` / diff --git a/src/pkg/policies/defaults/quality-holdgated.md b/src/pkg/policies/defaults/quality-holdgated.md index 5c8f83e234..cdae2f03bc 100644 --- a/src/pkg/policies/defaults/quality-holdgated.md +++ b/src/pkg/policies/defaults/quality-holdgated.md @@ -77,10 +77,24 @@ test problem. Check these before diagnosing any single PR: say so on the PR once and prefer the order that rebases the smaller diff. Use a sticky comment (edit the existing one, marker ``) rather than a new comment each run. -4. **Behind the base.** After the base branch moves, a PR that touches the - same files as the merged change should be updated immediately - (`gh api -X PUT repos//pulls//update-branch`), not left to - turn red later. A `422` means it now conflicts: report it under item 3. +4. **Behind the base: defer to the preparation owner.** Do not update a PR + branch merely because the base moved, even when it touches the same files + as the merged change. On repositories that use the current-base gate + (`auto_merge.require_current_base`, per repository or through + `auto_merge.require_current_base_default`), the hive's merge lane is the + one preparation owner: it refreshes a behind PR once its CI and review + pass, then waits for CI on the new head. Every extra refresh starts a + second full CI run, cancels the one in flight, and sends the owner back to + the start. If you cannot tell whether the gate applies, assume it does. + Where it is off, the merge train (on by default) updates overlapping + siblings after each merge, so the rule is the same. Touch a behind branch + only to repair a real conflict: GitHub reports the PR `CONFLICTING` / + `DIRTY`, or item 3's `git merge-tree` exits 1 against the base. Never call + `gh api -X PUT repos//pulls//update-branch` on a PR that + is only behind; on a conflict it returns `422` anyway, so report it under + item 3 and follow your lane's conflict rules. A `MERGE_BASE` verdict from + the shared-baseline helper on a red check is a repair, not a refresh, and + still applies. 5. **Throughput fixes worth a PR.** When a repository's CI is slow, look for and propose, one PR each: a missing `concurrency` group with `cancel-in-progress` on pull_request workflows; `actions/setup-go` / diff --git a/src/pkg/policies/defaults/quality-measured.md b/src/pkg/policies/defaults/quality-measured.md index 48594475e1..84a7f608ea 100644 --- a/src/pkg/policies/defaults/quality-measured.md +++ b/src/pkg/policies/defaults/quality-measured.md @@ -40,10 +40,24 @@ test problem. Check these before diagnosing any single PR: say so on the PR once and prefer the order that rebases the smaller diff. Use a sticky comment (edit the existing one, marker ``) rather than a new comment each run. -4. **Behind the base.** After the base branch moves, a PR that touches the - same files as the merged change should be updated immediately - (`gh api -X PUT repos//pulls//update-branch`), not left to - turn red later. A `422` means it now conflicts: report it under item 3. +4. **Behind the base: defer to the preparation owner.** Do not update a PR + branch merely because the base moved, even when it touches the same files + as the merged change. On repositories that use the current-base gate + (`auto_merge.require_current_base`, per repository or through + `auto_merge.require_current_base_default`), the hive's merge lane is the + one preparation owner: it refreshes a behind PR once its CI and review + pass, then waits for CI on the new head. Every extra refresh starts a + second full CI run, cancels the one in flight, and sends the owner back to + the start. If you cannot tell whether the gate applies, assume it does. + Where it is off, the merge train (on by default) updates overlapping + siblings after each merge, so the rule is the same. Touch a behind branch + only to repair a real conflict: GitHub reports the PR `CONFLICTING` / + `DIRTY`, or item 3's `git merge-tree` exits 1 against the base. Never call + `gh api -X PUT repos//pulls//update-branch` on a PR that + is only behind; on a conflict it returns `422` anyway, so report it under + item 3 and follow your lane's conflict rules. A `MERGE_BASE` verdict from + the shared-baseline helper on a red check is a repair, not a refresh, and + still applies. 5. **Throughput fixes worth a PR.** When a repository's CI is slow, look for and propose, one PR each: a missing `concurrency` group with `cancel-in-progress` on pull_request workflows; `actions/setup-go` / diff --git a/src/pkg/policies/defaults/quality.md b/src/pkg/policies/defaults/quality.md index eb867191fd..af60d4bb1e 100644 --- a/src/pkg/policies/defaults/quality.md +++ b/src/pkg/policies/defaults/quality.md @@ -96,10 +96,24 @@ test problem. Check these before diagnosing any single PR: say so on the PR once and prefer the order that rebases the smaller diff. Use a sticky comment (edit the existing one, marker ``) rather than a new comment each run. -4. **Behind the base.** After the base branch moves, a PR that touches the - same files as the merged change should be updated immediately - (`gh api -X PUT repos//pulls//update-branch`), not left to - turn red later. A `422` means it now conflicts: report it under item 3. +4. **Behind the base: defer to the preparation owner.** Do not update a PR + branch merely because the base moved, even when it touches the same files + as the merged change. On repositories that use the current-base gate + (`auto_merge.require_current_base`, per repository or through + `auto_merge.require_current_base_default`), the hive's merge lane is the + one preparation owner: it refreshes a behind PR once its CI and review + pass, then waits for CI on the new head. Every extra refresh starts a + second full CI run, cancels the one in flight, and sends the owner back to + the start. If you cannot tell whether the gate applies, assume it does. + Where it is off, the merge train (on by default) updates overlapping + siblings after each merge, so the rule is the same. Touch a behind branch + only to repair a real conflict: GitHub reports the PR `CONFLICTING` / + `DIRTY`, or item 3's `git merge-tree` exits 1 against the base. Never call + `gh api -X PUT repos//pulls//update-branch` on a PR that + is only behind; on a conflict it returns `422` anyway, so report it under + item 3 and follow your lane's conflict rules. A `MERGE_BASE` verdict from + the shared-baseline helper on a red check is a repair, not a refresh, and + still applies. 5. **Throughput fixes worth a PR.** When a repository's CI is slow, look for and propose, one PR each: a missing `concurrency` group with `cancel-in-progress` on pull_request workflows; `actions/setup-go` / diff --git a/src/pkg/policies/defaults/scanner-full.md b/src/pkg/policies/defaults/scanner-full.md index 81c75f5893..dab186f407 100644 --- a/src/pkg/policies/defaults/scanner-full.md +++ b/src/pkg/policies/defaults/scanner-full.md @@ -155,7 +155,7 @@ ${PR_LIST} ## Resolving Merge Conflicts on PRs For PRs in the PR_LIST that have merge conflicts: -1. Use MCP `update_pull_request_branch` — this resolves conflicts when the PR branch is simply behind main +1. A PR that is only behind its base is not a conflict: leave it. Do NOT call MCP `update_pull_request_branch` on it. On repositories that use the current-base gate (`auto_merge.require_current_base`, per repository or through `auto_merge.require_current_base_default`), the hive's merge lane is the one preparation owner and refreshes a behind PR once its CI and review pass; an extra refresh reruns all of CI, cancels the run in flight and sends the owner back to the start. If you cannot tell whether the gate applies, assume it does. Update a branch only to repair a real conflict (GitHub reports `CONFLICTING` / `DIRTY`), using the steps below; `update_pull_request_branch` cannot resolve one. 2. For PRs authored by the hive App on branches this hive created (`agent/` label matches your lane, or the branch starts with `/`), resolve up to **3** conflicted own PRs per kick: fetch the base (`git fetch origin `), rebase onto it (`git rebase origin/`, or merge the base when safer), resolve conflicts preserving the PR's intent, `git push --force-with-lease`, and let CI validate (do NOT run the repo's build/lint/tests locally). Rebasing your own lane branch is allowed; never rewrite branches you did not create. If a sibling PR already landed the fix, close this PR with a one-line comment citing that sibling. 3. For PRs authored by humans or other bots, or for conflicts you cannot safely resolve, add/refresh `needs-rebase`, leave a one-line comment explaining the conflict, and **DEFER — move to the next PR**. 4. **NEVER use the gh CLI** — all GitHub operations go through MCP diff --git a/src/policies/ci-maintainer-advisory.md b/src/policies/ci-maintainer-advisory.md index aaa11e1eba..ef10a91b7e 100644 --- a/src/policies/ci-maintainer-advisory.md +++ b/src/policies/ci-maintainer-advisory.md @@ -39,10 +39,24 @@ test problem. Check these before diagnosing any single PR: say so on the PR once and prefer the order that rebases the smaller diff. Use a sticky comment (edit the existing one, marker ``) rather than a new comment each run. -4. **Behind the base.** After the base branch moves, a PR that touches the - same files as the merged change should be updated immediately - (`gh api -X PUT repos//pulls//update-branch`), not left to - turn red later. A `422` means it now conflicts: report it under item 3. +4. **Behind the base: defer to the preparation owner.** Do not update a PR + branch merely because the base moved, even when it touches the same files + as the merged change. On repositories that use the current-base gate + (`auto_merge.require_current_base`, per repository or through + `auto_merge.require_current_base_default`), the hive's merge lane is the + one preparation owner: it refreshes a behind PR once its CI and review + pass, then waits for CI on the new head. Every extra refresh starts a + second full CI run, cancels the one in flight, and sends the owner back to + the start. If you cannot tell whether the gate applies, assume it does. + Where it is off, the merge train (on by default) updates overlapping + siblings after each merge, so the rule is the same. Touch a behind branch + only to repair a real conflict: GitHub reports the PR `CONFLICTING` / + `DIRTY`, or item 3's `git merge-tree` exits 1 against the base. Never call + `gh api -X PUT repos//pulls//update-branch` on a PR that + is only behind; on a conflict it returns `422` anyway, so report it under + item 3 and follow your lane's conflict rules. A `MERGE_BASE` verdict from + the shared-baseline helper on a red check is a repair, not a refresh, and + still applies. 5. **Throughput fixes worth a PR.** When a repository's CI is slow, look for and propose, one PR each: a missing `concurrency` group with `cancel-in-progress` on pull_request workflows; `actions/setup-go` / diff --git a/src/policies/ci-maintainer-full.md b/src/policies/ci-maintainer-full.md index 5625634c3f..cc6563d5f3 100644 --- a/src/policies/ci-maintainer-full.md +++ b/src/policies/ci-maintainer-full.md @@ -97,10 +97,24 @@ test problem. Check these before diagnosing any single PR: say so on the PR once and prefer the order that rebases the smaller diff. Use a sticky comment (edit the existing one, marker ``) rather than a new comment each run. -4. **Behind the base.** After the base branch moves, a PR that touches the - same files as the merged change should be updated immediately - (`gh api -X PUT repos//pulls//update-branch`), not left to - turn red later. A `422` means it now conflicts: report it under item 3. +4. **Behind the base: defer to the preparation owner.** Do not update a PR + branch merely because the base moved, even when it touches the same files + as the merged change. On repositories that use the current-base gate + (`auto_merge.require_current_base`, per repository or through + `auto_merge.require_current_base_default`), the hive's merge lane is the + one preparation owner: it refreshes a behind PR once its CI and review + pass, then waits for CI on the new head. Every extra refresh starts a + second full CI run, cancels the one in flight, and sends the owner back to + the start. If you cannot tell whether the gate applies, assume it does. + Where it is off, the merge train (on by default) updates overlapping + siblings after each merge, so the rule is the same. Touch a behind branch + only to repair a real conflict: GitHub reports the PR `CONFLICTING` / + `DIRTY`, or item 3's `git merge-tree` exits 1 against the base. Never call + `gh api -X PUT repos//pulls//update-branch` on a PR that + is only behind; on a conflict it returns `422` anyway, so report it under + item 3 and follow your lane's conflict rules. A `MERGE_BASE` verdict from + the shared-baseline helper on a red check is a repair, not a refresh, and + still applies. 5. **Throughput fixes worth a PR.** When a repository's CI is slow, look for and propose, one PR each: a missing `concurrency` group with `cancel-in-progress` on pull_request workflows; `actions/setup-go` / @@ -130,6 +144,64 @@ the file has no other open PRs against it, so the split does not become one more collision. Do not splinter: if the issue's evidence table no longer holds (few PRs, no overlaps), say so on the issue and close it instead. +## Merge Churn (standing goal) + +Base refreshes are the most expensive thing CI does that finds nothing: each +one reruns every pull_request workflow on a head whose PR content did not +change, and cancels the run in flight. Keep that cost visible and falling. +This is a standing item: it never closes, and it is measured, not fixed by +touching PRs (see item 4 of CI Throughput and Merge Order). + +**Measure weekly.** On your first kick on or after Monday 00:00 UTC, skip if +your newest `merge churn` bead is less than 7 days old. Otherwise measure the +previous 7 days on the primary repository's default branch. The PR and run +reads below are measurement only, an exception to any work-list prohibition +on listing PRs; never use them to select work. Take at most the 100 most +recently merged PRs (`gh pr list --repo --state merged --base + --search "merged:>=" --limit 100 --json +number,mergedAt`) and say so in the report when the cap was hit. + +1. **Refreshes per merged PR** (`refreshes_per_merged_pr`): for each merged + PR, count its commits that are the hive App's base refresh (authored by + the App's bot login, message `Merge branch '' into `): + `gh api repos//pulls//commits --paginate`. Report the mean + and the PR with the most. +2. **CI runs cancelled by refreshes** (`refresh_cancelled_run_share`): for + each refresh commit from 1, its non-base parent is the head it replaced; + count that head's cancelled pull_request runs + (`gh api "repos//actions/runs?head_sha=&status=cancelled"`). + Report the count and its share of all pull_request runs created in the + week. +3. **Release-merge cadence** (`release_merges_per_day`): releases published + in the week (`gh release list --repo --limit 100 --json + tagName,publishedAt`) divided by 7. Every release commit moves the base + and makes every open PR behind. +4. **Approval-to-merge latency** (`approval_to_merge_median`, + `approval_to_merge_p90`): for each merged PR, merge time minus its latest + `APPROVED` review (`gh api repos//pulls//reviews`); skip + PRs with none. Report median and p90. + +**Report.** Write one bead per week, title `merge churn: week of +`, priority 3 (2 when any threshold below is crossed), with the +four numbers, last week's numbers beside them, and the caps you hit. + +**Thresholds** (named so the report and the issue can cite them): + +| Name | Over threshold when | +| --- | --- | +| `refreshes_per_merged_pr` | mean above 1.5 | +| `refresh_cancelled_run_share` | above 20% of the week's pull_request runs | +| `release_merges_per_day` | above 6 | +| `approval_to_merge_median` / `approval_to_merge_p90` | median above 4h or p90 above 24h | + +**Escalate once.** When any threshold is crossed, keep ONE open issue per +repository, stable title `[ci-maintainer] Merge churn over threshold in +`, label `ci`: the numbers, which thresholds they cross, the +worst PRs as evidence, and the likeliest lever (release cadence, refresh +ordering, a slow lane). If that issue is already open, add one comment with +the new week's numbers instead of a new issue. When a full week is back +under every threshold, say so in one comment and close it. + ## Opening Issues **Scope each issue so a single PR can close it.** When a finding enumerates @@ -231,7 +303,8 @@ checks are green — waiting buys nothing. 5. Create a GitHub issue for each confirmed problem 6. For problems with a clear fix, create a worktree and open a PR 7. Create a bead for each finding -8. Summarize CI health in your response +8. Weekly: run the Merge Churn measurement when it is due +9. Summarize CI health in your response ${KNOWLEDGE} diff --git a/src/policies/ci-maintainer-holdgated.md b/src/policies/ci-maintainer-holdgated.md index 0b0c3e211f..099b0da405 100644 --- a/src/policies/ci-maintainer-holdgated.md +++ b/src/policies/ci-maintainer-holdgated.md @@ -96,10 +96,24 @@ test problem. Check these before diagnosing any single PR: say so on the PR once and prefer the order that rebases the smaller diff. Use a sticky comment (edit the existing one, marker ``) rather than a new comment each run. -4. **Behind the base.** After the base branch moves, a PR that touches the - same files as the merged change should be updated immediately - (`gh api -X PUT repos//pulls//update-branch`), not left to - turn red later. A `422` means it now conflicts: report it under item 3. +4. **Behind the base: defer to the preparation owner.** Do not update a PR + branch merely because the base moved, even when it touches the same files + as the merged change. On repositories that use the current-base gate + (`auto_merge.require_current_base`, per repository or through + `auto_merge.require_current_base_default`), the hive's merge lane is the + one preparation owner: it refreshes a behind PR once its CI and review + pass, then waits for CI on the new head. Every extra refresh starts a + second full CI run, cancels the one in flight, and sends the owner back to + the start. If you cannot tell whether the gate applies, assume it does. + Where it is off, the merge train (on by default) updates overlapping + siblings after each merge, so the rule is the same. Touch a behind branch + only to repair a real conflict: GitHub reports the PR `CONFLICTING` / + `DIRTY`, or item 3's `git merge-tree` exits 1 against the base. Never call + `gh api -X PUT repos//pulls//update-branch` on a PR that + is only behind; on a conflict it returns `422` anyway, so report it under + item 3 and follow your lane's conflict rules. A `MERGE_BASE` verdict from + the shared-baseline helper on a red check is a repair, not a refresh, and + still applies. 5. **Throughput fixes worth a PR.** When a repository's CI is slow, look for and propose, one PR each: a missing `concurrency` group with `cancel-in-progress` on pull_request workflows; `actions/setup-go` / diff --git a/src/policies/ci-maintainer.md b/src/policies/ci-maintainer.md index 3290702d06..729191e6dc 100644 --- a/src/policies/ci-maintainer.md +++ b/src/policies/ci-maintainer.md @@ -109,10 +109,24 @@ test problem. Check these before diagnosing any single PR: say so on the PR once and prefer the order that rebases the smaller diff. Use a sticky comment (edit the existing one, marker ``) rather than a new comment each run. -4. **Behind the base.** After the base branch moves, a PR that touches the - same files as the merged change should be updated immediately - (`gh api -X PUT repos//pulls//update-branch`), not left to - turn red later. A `422` means it now conflicts: report it under item 3. +4. **Behind the base: defer to the preparation owner.** Do not update a PR + branch merely because the base moved, even when it touches the same files + as the merged change. On repositories that use the current-base gate + (`auto_merge.require_current_base`, per repository or through + `auto_merge.require_current_base_default`), the hive's merge lane is the + one preparation owner: it refreshes a behind PR once its CI and review + pass, then waits for CI on the new head. Every extra refresh starts a + second full CI run, cancels the one in flight, and sends the owner back to + the start. If you cannot tell whether the gate applies, assume it does. + Where it is off, the merge train (on by default) updates overlapping + siblings after each merge, so the rule is the same. Touch a behind branch + only to repair a real conflict: GitHub reports the PR `CONFLICTING` / + `DIRTY`, or item 3's `git merge-tree` exits 1 against the base. Never call + `gh api -X PUT repos//pulls//update-branch` on a PR that + is only behind; on a conflict it returns `422` anyway, so report it under + item 3 and follow your lane's conflict rules. A `MERGE_BASE` verdict from + the shared-baseline helper on a red check is a repair, not a refresh, and + still applies. 5. **Throughput fixes worth a PR.** When a repository's CI is slow, look for and propose, one PR each: a missing `concurrency` group with `cancel-in-progress` on pull_request workflows; `actions/setup-go` / diff --git a/src/policies/quality-advisory.md b/src/policies/quality-advisory.md index 1ea4ac4705..08be1b9516 100644 --- a/src/policies/quality-advisory.md +++ b/src/policies/quality-advisory.md @@ -39,10 +39,24 @@ test problem. Check these before diagnosing any single PR: say so on the PR once and prefer the order that rebases the smaller diff. Use a sticky comment (edit the existing one, marker ``) rather than a new comment each run. -4. **Behind the base.** After the base branch moves, a PR that touches the - same files as the merged change should be updated immediately - (`gh api -X PUT repos//pulls//update-branch`), not left to - turn red later. A `422` means it now conflicts: report it under item 3. +4. **Behind the base: defer to the preparation owner.** Do not update a PR + branch merely because the base moved, even when it touches the same files + as the merged change. On repositories that use the current-base gate + (`auto_merge.require_current_base`, per repository or through + `auto_merge.require_current_base_default`), the hive's merge lane is the + one preparation owner: it refreshes a behind PR once its CI and review + pass, then waits for CI on the new head. Every extra refresh starts a + second full CI run, cancels the one in flight, and sends the owner back to + the start. If you cannot tell whether the gate applies, assume it does. + Where it is off, the merge train (on by default) updates overlapping + siblings after each merge, so the rule is the same. Touch a behind branch + only to repair a real conflict: GitHub reports the PR `CONFLICTING` / + `DIRTY`, or item 3's `git merge-tree` exits 1 against the base. Never call + `gh api -X PUT repos//pulls//update-branch` on a PR that + is only behind; on a conflict it returns `422` anyway, so report it under + item 3 and follow your lane's conflict rules. A `MERGE_BASE` verdict from + the shared-baseline helper on a red check is a repair, not a refresh, and + still applies. 5. **Throughput fixes worth a PR.** When a repository's CI is slow, look for and propose, one PR each: a missing `concurrency` group with `cancel-in-progress` on pull_request workflows; `actions/setup-go` / diff --git a/src/policies/quality-full.md b/src/policies/quality-full.md index d167a12627..f1e406b1e6 100644 --- a/src/policies/quality-full.md +++ b/src/policies/quality-full.md @@ -77,10 +77,24 @@ test problem. Check these before diagnosing any single PR: say so on the PR once and prefer the order that rebases the smaller diff. Use a sticky comment (edit the existing one, marker ``) rather than a new comment each run. -4. **Behind the base.** After the base branch moves, a PR that touches the - same files as the merged change should be updated immediately - (`gh api -X PUT repos//pulls//update-branch`), not left to - turn red later. A `422` means it now conflicts: report it under item 3. +4. **Behind the base: defer to the preparation owner.** Do not update a PR + branch merely because the base moved, even when it touches the same files + as the merged change. On repositories that use the current-base gate + (`auto_merge.require_current_base`, per repository or through + `auto_merge.require_current_base_default`), the hive's merge lane is the + one preparation owner: it refreshes a behind PR once its CI and review + pass, then waits for CI on the new head. Every extra refresh starts a + second full CI run, cancels the one in flight, and sends the owner back to + the start. If you cannot tell whether the gate applies, assume it does. + Where it is off, the merge train (on by default) updates overlapping + siblings after each merge, so the rule is the same. Touch a behind branch + only to repair a real conflict: GitHub reports the PR `CONFLICTING` / + `DIRTY`, or item 3's `git merge-tree` exits 1 against the base. Never call + `gh api -X PUT repos//pulls//update-branch` on a PR that + is only behind; on a conflict it returns `422` anyway, so report it under + item 3 and follow your lane's conflict rules. A `MERGE_BASE` verdict from + the shared-baseline helper on a red check is a repair, not a refresh, and + still applies. 5. **Throughput fixes worth a PR.** When a repository's CI is slow, look for and propose, one PR each: a missing `concurrency` group with `cancel-in-progress` on pull_request workflows; `actions/setup-go` / diff --git a/src/policies/quality-holdgated.md b/src/policies/quality-holdgated.md index 5c8f83e234..cdae2f03bc 100644 --- a/src/policies/quality-holdgated.md +++ b/src/policies/quality-holdgated.md @@ -77,10 +77,24 @@ test problem. Check these before diagnosing any single PR: say so on the PR once and prefer the order that rebases the smaller diff. Use a sticky comment (edit the existing one, marker ``) rather than a new comment each run. -4. **Behind the base.** After the base branch moves, a PR that touches the - same files as the merged change should be updated immediately - (`gh api -X PUT repos//pulls//update-branch`), not left to - turn red later. A `422` means it now conflicts: report it under item 3. +4. **Behind the base: defer to the preparation owner.** Do not update a PR + branch merely because the base moved, even when it touches the same files + as the merged change. On repositories that use the current-base gate + (`auto_merge.require_current_base`, per repository or through + `auto_merge.require_current_base_default`), the hive's merge lane is the + one preparation owner: it refreshes a behind PR once its CI and review + pass, then waits for CI on the new head. Every extra refresh starts a + second full CI run, cancels the one in flight, and sends the owner back to + the start. If you cannot tell whether the gate applies, assume it does. + Where it is off, the merge train (on by default) updates overlapping + siblings after each merge, so the rule is the same. Touch a behind branch + only to repair a real conflict: GitHub reports the PR `CONFLICTING` / + `DIRTY`, or item 3's `git merge-tree` exits 1 against the base. Never call + `gh api -X PUT repos//pulls//update-branch` on a PR that + is only behind; on a conflict it returns `422` anyway, so report it under + item 3 and follow your lane's conflict rules. A `MERGE_BASE` verdict from + the shared-baseline helper on a red check is a repair, not a refresh, and + still applies. 5. **Throughput fixes worth a PR.** When a repository's CI is slow, look for and propose, one PR each: a missing `concurrency` group with `cancel-in-progress` on pull_request workflows; `actions/setup-go` / diff --git a/src/policies/quality-measured.md b/src/policies/quality-measured.md index 48594475e1..84a7f608ea 100644 --- a/src/policies/quality-measured.md +++ b/src/policies/quality-measured.md @@ -40,10 +40,24 @@ test problem. Check these before diagnosing any single PR: say so on the PR once and prefer the order that rebases the smaller diff. Use a sticky comment (edit the existing one, marker ``) rather than a new comment each run. -4. **Behind the base.** After the base branch moves, a PR that touches the - same files as the merged change should be updated immediately - (`gh api -X PUT repos//pulls//update-branch`), not left to - turn red later. A `422` means it now conflicts: report it under item 3. +4. **Behind the base: defer to the preparation owner.** Do not update a PR + branch merely because the base moved, even when it touches the same files + as the merged change. On repositories that use the current-base gate + (`auto_merge.require_current_base`, per repository or through + `auto_merge.require_current_base_default`), the hive's merge lane is the + one preparation owner: it refreshes a behind PR once its CI and review + pass, then waits for CI on the new head. Every extra refresh starts a + second full CI run, cancels the one in flight, and sends the owner back to + the start. If you cannot tell whether the gate applies, assume it does. + Where it is off, the merge train (on by default) updates overlapping + siblings after each merge, so the rule is the same. Touch a behind branch + only to repair a real conflict: GitHub reports the PR `CONFLICTING` / + `DIRTY`, or item 3's `git merge-tree` exits 1 against the base. Never call + `gh api -X PUT repos//pulls//update-branch` on a PR that + is only behind; on a conflict it returns `422` anyway, so report it under + item 3 and follow your lane's conflict rules. A `MERGE_BASE` verdict from + the shared-baseline helper on a red check is a repair, not a refresh, and + still applies. 5. **Throughput fixes worth a PR.** When a repository's CI is slow, look for and propose, one PR each: a missing `concurrency` group with `cancel-in-progress` on pull_request workflows; `actions/setup-go` / diff --git a/src/policies/quality.md b/src/policies/quality.md index eb867191fd..af60d4bb1e 100644 --- a/src/policies/quality.md +++ b/src/policies/quality.md @@ -96,10 +96,24 @@ test problem. Check these before diagnosing any single PR: say so on the PR once and prefer the order that rebases the smaller diff. Use a sticky comment (edit the existing one, marker ``) rather than a new comment each run. -4. **Behind the base.** After the base branch moves, a PR that touches the - same files as the merged change should be updated immediately - (`gh api -X PUT repos//pulls//update-branch`), not left to - turn red later. A `422` means it now conflicts: report it under item 3. +4. **Behind the base: defer to the preparation owner.** Do not update a PR + branch merely because the base moved, even when it touches the same files + as the merged change. On repositories that use the current-base gate + (`auto_merge.require_current_base`, per repository or through + `auto_merge.require_current_base_default`), the hive's merge lane is the + one preparation owner: it refreshes a behind PR once its CI and review + pass, then waits for CI on the new head. Every extra refresh starts a + second full CI run, cancels the one in flight, and sends the owner back to + the start. If you cannot tell whether the gate applies, assume it does. + Where it is off, the merge train (on by default) updates overlapping + siblings after each merge, so the rule is the same. Touch a behind branch + only to repair a real conflict: GitHub reports the PR `CONFLICTING` / + `DIRTY`, or item 3's `git merge-tree` exits 1 against the base. Never call + `gh api -X PUT repos//pulls//update-branch` on a PR that + is only behind; on a conflict it returns `422` anyway, so report it under + item 3 and follow your lane's conflict rules. A `MERGE_BASE` verdict from + the shared-baseline helper on a red check is a repair, not a refresh, and + still applies. 5. **Throughput fixes worth a PR.** When a repository's CI is slow, look for and propose, one PR each: a missing `concurrency` group with `cancel-in-progress` on pull_request workflows; `actions/setup-go` / diff --git a/src/policies/scanner-full.md b/src/policies/scanner-full.md index 81c75f5893..dab186f407 100644 --- a/src/policies/scanner-full.md +++ b/src/policies/scanner-full.md @@ -155,7 +155,7 @@ ${PR_LIST} ## Resolving Merge Conflicts on PRs For PRs in the PR_LIST that have merge conflicts: -1. Use MCP `update_pull_request_branch` — this resolves conflicts when the PR branch is simply behind main +1. A PR that is only behind its base is not a conflict: leave it. Do NOT call MCP `update_pull_request_branch` on it. On repositories that use the current-base gate (`auto_merge.require_current_base`, per repository or through `auto_merge.require_current_base_default`), the hive's merge lane is the one preparation owner and refreshes a behind PR once its CI and review pass; an extra refresh reruns all of CI, cancels the run in flight and sends the owner back to the start. If you cannot tell whether the gate applies, assume it does. Update a branch only to repair a real conflict (GitHub reports `CONFLICTING` / `DIRTY`), using the steps below; `update_pull_request_branch` cannot resolve one. 2. For PRs authored by the hive App on branches this hive created (`agent/` label matches your lane, or the branch starts with `/`), resolve up to **3** conflicted own PRs per kick: fetch the base (`git fetch origin `), rebase onto it (`git rebase origin/`, or merge the base when safer), resolve conflicts preserving the PR's intent, `git push --force-with-lease`, and let CI validate (do NOT run the repo's build/lint/tests locally). Rebasing your own lane branch is allowed; never rewrite branches you did not create. If a sibling PR already landed the fix, close this PR with a one-line comment citing that sibling. 3. For PRs authored by humans or other bots, or for conflicts you cannot safely resolve, add/refresh `needs-rebase`, leave a one-line comment explaining the conflict, and **DEFER — move to the next PR**. 4. **NEVER use the gh CLI** — all GitHub operations go through MCP