Phase 6 follow-up: auto-merge promote PRs with quality-gate self-validation (Option C)

[cbeaulieu-gt]

Summary

Phase 6 (#144) ships with Option A — human-in-loop: STAGE 5 opens a promote PR; a human reviews and merges. This issue tracks the Option C — auto-merge with self-validation end state.

When this lands, weekly digest-bump PRs will auto-merge once claude-pr-review/quality-gate posts success on the rebuilt overlay's self-review. The dogfood becomes the gate: a healthy overlay's review persona green-lights its own promotion; a regressed overlay's review fails, blocking the conveyor and triggering operator response.

Motivation

Inquisitor Pass 1 on the Phase 6 plan (2026-05-05) identified that the "fully automated promotion" framing in the master plan didn't reconcile with the bot-authored promote PR being subject to required claude-pr-review/quality-gate. Three viable resolutions were considered:

• A. Human-in-loop — chosen for Phase 6 MVP (Phase 6: digest-bump-PR automation + rollback.yml + freshness alarm + prune-pending.yml #144). Lower risk, weekly human touch.
• B. App as ruleset bypass actor — bypass the gate entirely for App-authored PRs. Rejected: expands App blast radius; if PEM leaks, gate-bypassed PRs can be opened.
• C. Auto-merge with self-validation — chosen for follow-up (this issue). True automation + gated.

Acceptance Criteria

• STAGE 5 promote PR enables auto-merge — either via peter-evans/create-pull-request's auto-merge input or a follow-up step that calls gh pr merge --auto --squash
• Auto-merge waits for claude-pr-review/quality-gate to post success before merging (default GitHub auto-merge behavior with required checks)
• Rollback workflow (runtime-rollback.yml) is hardened with the pre-PR validation from Charge 5 of Inquisitor Pass 1 — this is a hard prerequisite because a stuck conveyor must be unstuck-able by rollback
• STAGE 5 promote PR includes a "kill switch" comment / label that, when applied by an operator, disables auto-merge for that specific PR (operator override path)
• Documented runbook for "promote PR's quality-gate failed; how do I diagnose and recover" — at minimum a section in CLAUDE.md "CI Runtime"
• At least 4 successful auto-merge cycles observed before this issue closes (one weekly cadence per overlay change-class — base, review, fix, explain — to exercise the conveyor end-to-end)

Technical Notes

• Auto-merge mechanics on bot PRs. peter-evans/create-pull-request documents an auto-merge input that calls the GitHub auto-merge API. Verify this works for App-authored PRs (some auto-merge paths require human confirmation; the API call from the action should bypass that).
• Failure mode: bad overlay freezes the conveyor. A regression in any overlay's review persona will flip claude-pr-review/quality-gate to failure on the promote PR. All subsequent promotes pile up. Recovery: dispatch runtime-rollback.yml to revert to the last-known-good pubsha. The rollback PR is also bot-authored, so it MUST also be auto-mergeable — but rollback PRs may need a different gate (you don't want quality-gate to evaluate the broken overlay's own review). Spec amendment may be needed to give rollback its own bypass path.
• Don't enable until rollback is bulletproof. Charge 5 of Pass 1 highlighted that the rollback workflow doesn't validate target digests pre-PR. Phase 6 (Phase 6: digest-bump-PR automation + rollback.yml + freshness alarm + prune-pending.yml #144) folds in pre-PR inventory-match.sh + overlay-smoke validation. That hardening is a hard prerequisite for this issue.
• Quiet-window guard. Consider adding a "quiet-window" check that suppresses auto-merge during ongoing CI activity (e.g., open PRs against main with pending CI). Reduces blast radius if a regression slips in.

Out of Scope

• Phase 6 MVP itself (Phase 6: digest-bump-PR automation + rollback.yml + freshness alarm + prune-pending.yml #144) — that ships Option A.
• The branch-protection ruleset reconfiguration for Option B — explicitly rejected.
• Forked-PR auth question (§13 Q4) — separate spec deferral.

References

• Phase 6: digest-bump-PR automation + rollback.yml + freshness alarm + prune-pending.yml #144 — Phase 6 epic; ships Option A with this issue as the queued evolution
• Inquisitor Pass 1 findings (2026-05-05, in docs/superpowers/plans/phase-6-promotion.md plan refresh log) — Charges 2 (this trade-off) and 5 (rollback hardening prerequisite)
• agent-memory/general-purpose/feedback_gh_actions_not_addable_ruleset_bypass.md — explains why Option B was rejected

🤖 Generated by Claude Code on behalf of @cbeaulieu-gt