Add PR-only queue cleanup mode that dispatches one canonical review per PR #390

New Issue

2026-07-07T08:51:11-05:00

jcwalker3 commented

2026-07-07 08:51:11 -05:00

Problem

Operator queues sometimes need to process open PRs deterministically: one canonical review per PR, then stop or hand off—without batch queue-status reports, multi-PR selection in one run, or author-side fixes mixed into reviewer cleanup.

Today the canonical review-merge-pr workflow supports inventory and selection, but there is no dedicated PR-only queue cleanup mode that dispatches isolated review runs per PR with enforced boundaries.

Required behavior

Add a documented workflow mode (e.g. pr-queue-cleanup or review-one-pr) under skills/llm-project-workflow/.
Mode iterates open PRs (or an operator-supplied PR list) and dispatches exactly one canonical review-merge run per PR:
- complete PR inventory with pagination proof before any selection claim
- pin head SHA for the selected PR only
- session-owned worktree under branches/
- single terminal review decision per PR (approve / request-changes / comment / skip with proof)
- no multi-PR validation or batch final report substituting for per-PR proof
After each PR, emit that PR's final report; optional queue summary only after explicit per-PR reports exist.
Merge is forbidden in cleanup mode unless operator explicitly authorizes merge for that specific PR in that run.
Register resolver/route task so reviewer profiles can enter cleanup mode; author profiles cannot.

Acceptance criteria

Workflow file + template for PR-only cleanup mode.
MCP task routing / capability mapping for cleanup mode (reviewer role only).
Tests: single-PR dispatch, blocked multi-PR batching, inventory pagination proof required, merge blocked without explicit per-PR authorization.
Runbook section describing when to use cleanup mode vs full queue review.

Related issues

#290 — PR review state machine umbrella
#173 — blind PR queue evidence requirements
#339 — queue-status report verifier (batch reports must not fake per-PR proof)
#340 — gitea_list_prs pagination metadata (dependency for inventory proof)

Non-goals

Do not auto-merge PRs in cleanup mode.
Do not perform author fixes or branch pushes from reviewer cleanup mode.
Do not replace the full review-merge-pr workflow; compose with it per PR.

## Problem Operator queues sometimes need to process open PRs deterministically: **one canonical review per PR**, then stop or hand off—without batch queue-status reports, multi-PR selection in one run, or author-side fixes mixed into reviewer cleanup. Today the canonical `review-merge-pr` workflow supports inventory and selection, but there is no dedicated **PR-only queue cleanup** mode that dispatches isolated review runs per PR with enforced boundaries. ## Required behavior 1. Add a documented workflow mode (e.g. `pr-queue-cleanup` or `review-one-pr`) under `skills/llm-project-workflow/`. 2. Mode iterates open PRs (or an operator-supplied PR list) and dispatches **exactly one** canonical review-merge run per PR: - complete PR inventory with pagination proof before any selection claim - pin head SHA for the selected PR only - session-owned worktree under `branches/` - single terminal review decision per PR (approve / request-changes / comment / skip with proof) - no multi-PR validation or batch final report substituting for per-PR proof 3. After each PR, emit that PR's final report; optional queue summary only after explicit per-PR reports exist. 4. Merge is forbidden in cleanup mode unless operator explicitly authorizes merge for that specific PR in that run. 5. Register resolver/route task so reviewer profiles can enter cleanup mode; author profiles cannot. ## Acceptance criteria - [ ] Workflow file + template for PR-only cleanup mode. - [ ] MCP task routing / capability mapping for cleanup mode (reviewer role only). - [ ] Tests: single-PR dispatch, blocked multi-PR batching, inventory pagination proof required, merge blocked without explicit per-PR authorization. - [ ] Runbook section describing when to use cleanup mode vs full queue review. ## Related issues - **#290** — PR review state machine umbrella - **#173** — blind PR queue evidence requirements - **#339** — queue-status report verifier (batch reports must not fake per-PR proof) - **#340** — `gitea_list_prs` pagination metadata (dependency for inventory proof) ## Non-goals - Do not auto-merge PRs in cleanup mode. - Do not perform author fixes or branch pushes from reviewer cleanup mode. - Do not replace the full `review-merge-pr` workflow; compose with it per PR.

jcwalker3 added the status:in-progress label 2026-07-07 08:56:27 -05:00

jcwalker3 commented

2026-07-07 08:56:44 -05:00

Claiming #390 for implementation (author session, prgs-author / jcwalker3).

Branch: feat/issue-390-pr-queue-cleanup-mode

Planned slice per acceptance criteria:

skills/llm-project-workflow/workflows/pr-queue-cleanup.md — canonical PR-only cleanup mode: forbids issue claiming, branch creation, implementation edits, and issue filing; exactly one canonical review run per PR; stop after REQUEST_CHANGES; after APPROVED, same-PR merge only with explicit per-PR operator authorization and passing merge gates; hard stop after merge or merge blocker; next PR requires a fresh run; final report names the next suggested PR without continuing.
task_capability_map.py + role_session_router.py — pr_queue_cleanup task mapped to reviewer role (gitea.pr.review); author sessions route wrong_role_stop.
pr_queue_cleanup.py — assess_pr_queue_cleanup_report verifier: single terminal decision, no multi-PR batching, inventory pagination proof, per-PR merge authorization, no issue/branch mutations in cleanup mode.
Runbook section + workflow contract tests + verifier tests.

Working in branches/issue-390-pr-queue-cleanup-mode.

Claiming #390 for implementation (author session, `prgs-author` / `jcwalker3`). **Branch:** `feat/issue-390-pr-queue-cleanup-mode` **Planned slice per acceptance criteria:** 1. `skills/llm-project-workflow/workflows/pr-queue-cleanup.md` — canonical PR-only cleanup mode: forbids issue claiming, branch creation, implementation edits, and issue filing; exactly one canonical review run per PR; stop after `REQUEST_CHANGES`; after `APPROVED`, same-PR merge only with explicit per-PR operator authorization and passing merge gates; hard stop after merge or merge blocker; next PR requires a fresh run; final report names the next suggested PR without continuing. 2. `task_capability_map.py` + `role_session_router.py` — `pr_queue_cleanup` task mapped to reviewer role (`gitea.pr.review`); author sessions route `wrong_role_stop`. 3. `pr_queue_cleanup.py` — `assess_pr_queue_cleanup_report` verifier: single terminal decision, no multi-PR batching, inventory pagination proof, per-PR merge authorization, no issue/branch mutations in cleanup mode. 4. Runbook section + workflow contract tests + verifier tests. Working in `branches/issue-390-pr-queue-cleanup-mode`.

jcwalker3 referenced this issue from a commit

2026-07-07 09:02:58 -05:00

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

jcwalker3 referenced a pull request that will close this issue

2026-07-07 09:03:23 -05:00

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

jcwalker3 referenced this issue from a commit

2026-07-07 09:06:55 -05:00

test: expand PR-queue-cleanup coverage to full acceptance matrix (#390)

sysadmin closed this issue

2026-07-07 09:07:52 -05:00

sysadmin referenced this issue from a commit

2026-07-07 09:07:53 -05:00

Merge pull request 'feat: add PR-only queue cleanup mode with per-PR dispatch gates (Closes #390)' (#393) from feat/issue-390-pr-queue-cleanup-mode into master

sysadmin removed the status:in-progress label 2026-07-07 09:07:54 -05:00

jcwalker3 referenced this issue

2026-07-07 09:15:17 -05:00

Add issue/PR work leases so multiple LLMs cannot accidentally do the same work #267

jcwalker3 referenced this issue

2026-07-07 09:15:18 -05:00

Merged PRs must trigger branch and worktree cleanup reconciliation #269

jcwalker3 referenced this issue

2026-07-07 09:15:48 -05:00

Issue claims need heartbeat leases and stale-claim cleanup #268

jcwalker3 commented

2026-07-07 09:20:42 -05:00

Evidence update — concurrent reviewer sessions can race the PR-only queue.

A reviewer run stopped correctly after detecting that another sysadmin / prgs-reviewer session approved/merged PR #380 mid-run. The first session’s inventory had listed #380 as open, but a later feedback fetch showed it closed/approved at 09:11:01 by the same reviewer identity. The target branch also advanced from 103364a to b5ee656, and fresh review/baseline worktrees from the other session were present.

This shows PR-only queue cleanup mode needs concurrency control:

one active reviewer queue run per repo/profile, or
a queue lease / selected-PR lease before validation/review mutation
stale inventory invalidation when another reviewer mutates the queue
hard stop when target branch changes during selection
final report must say the run stopped and must not reuse old queue state

Expected behavior:

Reviewer queue cleanup acquires a short-lived queue lease before selection.
A second reviewer session must fail closed or run read-only diagnostics only.
The lease records repo, profile, selected PR if any, timestamp, and phase.
The lease expires or releases after terminal mutation/final report.
If target branch advances during selection, the run invalidates inventory and restarts/stops.
Tests cover concurrent reviewer sessions, same identity collision, stale inventory after merge, and stale target branch after another session merges.

Evidence update — concurrent reviewer sessions can race the PR-only queue. A reviewer run stopped correctly after detecting that another `sysadmin / prgs-reviewer` session approved/merged PR #380 mid-run. The first session’s inventory had listed #380 as open, but a later feedback fetch showed it closed/approved at 09:11:01 by the same reviewer identity. The target branch also advanced from `103364a` to `b5ee656`, and fresh review/baseline worktrees from the other session were present. This shows PR-only queue cleanup mode needs concurrency control: - one active reviewer queue run per repo/profile, or - a queue lease / selected-PR lease before validation/review mutation - stale inventory invalidation when another reviewer mutates the queue - hard stop when target branch changes during selection - final report must say the run stopped and must not reuse old queue state Expected behavior: 1. Reviewer queue cleanup acquires a short-lived queue lease before selection. 2. A second reviewer session must fail closed or run read-only diagnostics only. 3. The lease records repo, profile, selected PR if any, timestamp, and phase. 4. The lease expires or releases after terminal mutation/final report. 5. If target branch advances during selection, the run invalidates inventory and restarts/stops. 6. Tests cover concurrent reviewer sessions, same identity collision, stale inventory after merge, and stale target branch after another session merges.

Sign in to join this conversation.

Branches Tags

master

fix/issue-709-decision-lock-cross-profile

fix/issue-695-native-transport-quarantine

fix/issue-698-report-validator-schema

fix/issue-702-stale-binding-lease-recovery

fix/issue-699-structured-auth-mcp-errors

fix/issue-695-native-quarantine-v2

fix/issue-693-review-decision-lock-recovery

fix/issue-691-obsolete-reviewer-lease-cleanup

feat/issue-687-reconciler-branch-delete

fix/issue-683-workflow-guard-hardening

chore/issue-681-preserve-review-session-wip

feat/issue-604-anti-stomp-preflight

feat/issue-606-sentry-observability

fix/issue-671-block-stable-branch-push

fix/issue-675-residual-preflight-remediation

fix/issue-673-remediate-regressions-part2

fix/issue-673-remediate-regressions

feat/issue-603-lifecycle-labels

fix/issue-627-set-issue-labels-pagination

feat/issue-601-first-class-leases

feat/issue-612-incident-bridge

feat/issue-600-controller-allocator-api

fix/issue-620-head-scoped-review-locks

feat/issue-613-allocator-db-substrate

docs/mcp-stable-control-runtime-policy

feat/issue-609-prepared-review-verdict-resume

feat/issue-610-live-remote-parity

feat/issue-503-reviewer-active-worktree

feat/issue-470-preflight-contract

feat/issue-440-lock-recovery

feat/issue-440-branch-recovery

feat/issue-458-queue-fail-closed-copy

feat/issue-400-early-duplicate-work-gate

feat/issue-308-reconcile-inventory-pagination

feat/issue-308-reconcile-pagination-proof

docs/issue-261-agent-temp-artifact-cleanup

feat/issue-262-map-commit-files

fix/infra-stop-conflict-marker-false-positive

feat/issue-139-role-aware-task-routing

feat/issue-188-continuation-selection-wall

feat/issue-189-continuation-mode-proofs

feat/issue-232-refresh-wiki-proof-heads

feat/issue-210-block-workspace-edits

feat/issue-204-exact-issue-lock

docs/issue-80-label-taxonomy

docs/issue-79-safety-boundary-updates

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Scaled-Tech-Consulting/Gitea-Tools#390