kandev/docs/specs/integrations/requirements/github-pr-merge-queue-recovery.md

status, system, created, owners

status	system	created	owners
draft	integrations	2026-08-24	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 REQ-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-002 owns attempt reservation, explicit retry, and stale auto-merge error reconciliation.
• Task PR Automation Controls
• Merge Queue Recovery Controls

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.