fix(ci): stop auto-merge-bot-prs.yml's self-referential check-polling deadlock

[devopam]

Summary

auto-merge-bot-prs.yml has never actually been able to merge a bot PR — it always times out after ~10 minutes. Root cause, found while investigating why PRs #324, #325, #326 (dependabot) sat open despite passing CI:

The workflow's own 'Wait for status checks' step polled checks.listForRef on the PR's head SHA and waited for every check run on that SHA to report completed before merging. That list includes the workflow's own currently-running check run — which by definition is never completed while the polling step itself is still executing. The loop therefore always sees N-1 of N complete, forever, until its own 60-attempt (~10 min) timeout throws. This is unrelated to the earlier YAML-comment-placement fix in #327 — that fixed a cosmetic if: block-scalar corruption, not this logic bug.

Fix

Replaced the hand-rolled wait-then-merge loop with GitHub's native gh pr merge --squash --auto, which delegates 'wait for the branch's required status checks, then merge' to GitHub itself. No self-polling is possible, and it correctly waits only on branch protection's required-checks list (7 named contexts) rather than every check run present on the SHA (17, including unrelated ones like CodeQL/Sourcery/zizmor that were never required). Confirmed allow_auto_merge is already enabled on this repo.

Also fixed the workflow_dispatch trigger, which was listed but never actually functional (the old script only ever read context.payload.pull_request, which is absent on a manual dispatch) — it now accepts a `pr_number" input.

Verification

• ruff/format/mypy/full unit suite: clean (2950 passed, 3 skipped) — doc/workflow-only change, no source touched
• zizmor on the new file: no findings
• yaml.safe_load confirms the if: block parses to the exact intended boolean expression (no comment-splicing, unlike the pre-chore: internal audit remediation (25 tasks + security fix + ruff sweep) #327 bug)
• CHANGELOG updated under [Unreleased] → Fixed

Follow-up (not in this PR)

PRs #324, #325, #326 predate this fix and are stuck in BEHIND/BLOCKED merge state (branch protection's strict: true requires them to be updated against current main, which just took a large merge). Plan to update and merge them separately once this fix lands.

🤖 Generated with Claude Code

Summary by Sourcery

Restore reliable bot pull request auto-merging by delegating required-check waiting to GitHub and support manually triggered merges.

New Features:

• Enable manual workflow dispatches to target a specified pull request for auto-merge.

Bug Fixes:

• Replace the self-referential status-check polling that could never complete with GitHub-managed auto-merge, allowing eligible bot pull requests to merge after required checks pass.

CI:

• Update the bot auto-merge workflow to use native squash auto-merge and report failures through a pull request comment.

Chores:

• Document the auto-merge workflow fix in the unreleased changelog.

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}