91 lines
3.9 KiB
Markdown
91 lines
3.9 KiB
Markdown
---
|
|
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.
|
|
|
|
If the open PR queue is empty:
|
|
* First, look at **Approvals** next: check if there are open PRs with pending/completed approvals requiring attention or merge.
|
|
* Next, look at **Issues** next: check if there are unresolved open issues requiring action/fixes.
|
|
|
|
## 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.
|