feat: add PR-only queue cleanup mode with per-PR dispatch gates (Closes #390)

Adds canonical pr-queue-cleanup workflow, report verifier, reviewer-only task routing, and runbook guidance so operators can drain open PRs one canonical review at a time with fail-closed boundaries on batching and unauthorized merges. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
2026-07-07 10:02:49 -04:00
parent ae566d5cd1
commit 91c67930ec
14 changed files with 642 additions and 1 deletions
@@ -0,0 +1,86 @@
+---
+task_mode: pr-queue-cleanup
+canonical: true
+final_report_schema: ../schemas/pr-queue-cleanup-final-report.md
+---
+
+# PR-only queue cleanup workflow (canonical)
+
+**Task mode:** `pr-queue-cleanup`
+
+Reviewer-role mode for cleanup periods when the queue holds many open PRs.
+Each run dispatches **exactly one** canonical review for **exactly one** PR,
+then stops after any terminal review mutation. The next PR always requires a
+new run with fresh identity, capability, and inventory proof.
+
+This mode composes with the canonical review workflow: for the selected PR,
+load and follow [`workflows/review-merge-pr.md`](review-merge-pr.md) in full.
+This file adds the cleanup-mode boundaries around that per-PR run; it does
+not replace the review workflow.
+
+## 0. Load the canonical workflow first
+
+Load this file and `workflows/review-merge-pr.md` before any mutation and
+report source, version/commit/hash, and any conflict with the operator
+prompt. If either cannot be loaded, stop and produce a recovery handoff.
+
+## 1. Mode isolation — forbidden actions
+
+PR-only cleanup mode forbids, with no exceptions:
+
+* issue claiming (`claim_issue`, `mark_issue`, `lock_issue`)
+* branch creation or push (`create_branch`, `push_branch`)
+* implementation edits of any kind
+* new issue filing (`create_issue`)
+* PR creation (`create_pr`) and commit tools (`commit_files`)
+* reviewing a second PR after any terminal review mutation
+
+`pr_queue_cleanup.check_cleanup_task_allowed` fails closed on these tasks.
+If author-side work is needed, stop and hand off to `work-issue` mode in a
+separate session.
+
+## 2. Identity, capability, and routing
+
+Route `pr_queue_cleanup` through `gitea_route_task_session` — reviewer role
+required; author sessions receive `wrong_role_stop`. Prove `gitea.pr.review`
+capability before selection. Merge additionally requires `gitea.pr.merge`
+plus the explicit per-PR authorization in §4.
+
+## 3. Inventory and selection
+
+Build the complete open-PR inventory with pagination proof
+(`inventory_complete`, final page, `total_count`) before any selection
+claim. Select exactly one PR according to project queue ordering rules
+(oldest-first unless the operator queue says otherwise), skipping earlier
+PRs only with live per-PR proof. No multi-PR validation and no batch report
+may substitute for per-PR proof.
+
+## 4. Terminal mutation chain
+
+`pr_queue_cleanup.resolve_cleanup_run_state` is the authority:
+
+* After `REQUEST_CHANGES` → the run stops.
+* After `COMMENT` or a proof-backed skip → the run stops.
+* After `APPROVED` → the run may continue **only** to same-PR merge, and only
+  when the operator explicitly authorized merge for that specific PR in this
+  run (`Merge authorized: true`) and every merge gate passes.
+* After merge, or on any merge blocker → the run stops.
+* Any terminal mutation targeting a PR other than the selected PR is a hard
+  stop and must be reported as a violation.
+
+## 5. Fresh run per PR
+
+The next PR requires a new run with fresh identity, capability, inventory,
+and ordering proof. Do not carry pinned SHAs, eligibility classes, or
+validation results across runs.
+
+## 6. Final report
+
+Use the schema in
+[`schemas/pr-queue-cleanup-final-report.md`](../schemas/pr-queue-cleanup-final-report.md).
+The report must include the **Next suggested PR** (from the proven ordering)
+without continuing to it, exactly one **Selected PR**, the single terminal
+decision, pagination proof, and `Issue mutations: none` / `Branch mutations:
+none`. `pr_queue_cleanup.assess_pr_queue_cleanup_report` validates these
+fields and fails closed on batch reviews, missing pagination proof, missing
+next-suggested-PR, unauthorized merges, or any issue/branch mutation.