Files
kandev/docs/specs/integrations/requirements/github-pr-merge-queue-recovery.md
T
2026-09-06 11:36:16 +01:00

134 lines
6.5 KiB
Markdown

---
status: draft
system: integrations
created: 2026-08-24
owners:
- Kandev
---
# GitHub PR Merge Queue Recovery Requirements
## Overview
GitHub can remove a pull request from a merge queue after a merge-group check
fails or a conflict appears. Kandev shows active queue membership, but it does
not retain the removal event or repair the pull request.
Queue-aware automation extends the existing per-PR auto-fix and auto-merge
controls. It does not add a separate queue-recovery preference.
## Terminology
- **Queue attempt:** One queue entry for one pull-request head commit.
- **Queue removal:** A GitHub `RemovedFromMergeQueueEvent` for an open pull
request.
- **Actionable removal:** A queue removal with a failed check, a timed-out
check, or a merge conflict.
## Requirements
### REQ-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-001: Queue removal observation
**Intent:** Kandev must retain a queue removal after the active queue entry
disappears. This record lets automation respond after a short queue attempt.
#### Acceptance criteria
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-001.1:** When GitHub reports
a queue removal, Kandev shall store its provider event ID, time, reason, and
available commit identity.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-001.2:** When Kandev misses
the active queue entry, a later poll shall still detect the latest queue
removal from the pull-request timeline.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-001.3:** When Kandev
restarts, the last observed queue attempt and removal shall remain available
for deduplication and status display.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-001.4:** When a queue-aware
read fails, Kandev shall preserve the last complete queue-recovery state.
### REQ-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-002: Queue failure auto-fix
**Intent:** Auto-fix must send actionable merge-queue failures to the linked
task agent without sending the same removal more than once.
#### Acceptance criteria
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-002.1:** When auto-fix is
enabled and a new actionable removal appears, Kandev shall send or queue one
auto-fix prompt for that removal.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-002.2:** The prompt shall
include the queue-removal reason and conflict state. It shall include failed
check names and links only when Kandev has an exact commit identity for those
checks.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-002.3:** The removal event ID
shall participate in the auto-fix checkpoint. Repeated polls shall not send
the same removal again.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-002.4:** A queue-recovery
prompt shall consume one of the existing 10 auto-fix rounds for that linked
pull request.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-002.5:** A manual or unknown
removal without failed-check or conflict evidence shall not start auto-fix.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-002.6:** When the task is
busy, the queue-recovery prompt shall use the existing durable auto-fix queue
and coalescing rules.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-002.7:** When a user enables
auto-fix after Kandev retained an unhandled actionable removal with durable
queue-attempt evidence for the current head, the next evaluation shall send
or queue one repair prompt.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-002.8:** Kandev shall not
treat the removal event's commit as a merge-group commit unless GitHub
identifies it as such.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-002.9:** When Kandev first
observes an actionable removal after the active queue entry disappears, it
shall start auto-fix only when durable evidence from an attempted or adopted
queue entry matches the current pull-request head. A passive removal-only
baseline is not sufficient provenance, so Kandev shall fail closed when that
evidence is unavailable.
### REQ-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-003: Safe automatic requeue
**Intent:** Auto-merge must requeue a repaired pull request without creating a
same-head retry loop or reversing an intentional queue removal.
#### Acceptance criteria
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-003.1:** When GitHub accepts
a queue attempt, Kandev shall record the attempted pull-request head commit.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-003.2:** When GitHub removes
that queue attempt, auto-merge shall not requeue the same head commit.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-003.3:** When the head commit
changes and the existing merge gates pass, auto-merge shall submit one new
queue-aware merge request.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-003.4:** A user or agent can
repair the pull request when auto-fix is disabled. A later eligible head
commit shall still re-arm auto-merge.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-003.5:** When both controls
are enabled, each actionable removal can start one repair round. A new
eligible head can then start one queue attempt.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-003.6:** Kandev shall use
GitHub's queue-aware default merge action. It shall not bypass repository
rules or choose direct merge instead of the required queue.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-003.7:** When a user enables
auto-merge while the pull request already has an active queue entry, Kandev
shall adopt that entry and head as the current attempt. It shall not submit a
duplicate merge request.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-003.8:** When a user enables
auto-merge after a queue removal, Kandev shall keep the same-head guard. It
shall wait for a new eligible head instead of reversing the removal.
## Related requirements
- [GitHub PR Merge Queue](github-pr-merge-queue.md)
`REQ-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-002` owns attempt reservation,
explicit retry, and stale auto-merge error reconciliation.
- [Task PR Automation Controls](../../ui/requirements/ci-pr-automation.md)
- [Merge Queue Recovery Controls](../../ui/requirements/ci-pr-merge-queue-recovery-controls.md)
## Out of scope
- Webhook ingestion for merge-group events.
- Automatic retry of a flaky queue failure without a new pull-request head.
- Editing branch protection, rulesets, or workflow files from the controls.
- Removing a pull request from the queue.
- Coordinated recovery and queue ordering for stacked pull requests.
- GitLab merge-request behavior.