Merge remote-tracking branch 'origin/main' into feat/issue-sweep

# Conflicts:
#	AGENTS.md

Author: JacobPEvans-personal

AGENTS.md

@@ -17,7 +17,7 @@ This is a **Claude Code plugins repository** containing production-ready hooks f
 | **content-guards** | Pre/PostToolUse | Bash, Write, Edit | Token limits, markdown/README validation, webfetch guard, issue/PR backlog limits, public-repo leakage guard |
 | **git-guards** | PreToolUse | Bash, Edit, Write, NotebookEdit | Blocks dangerous git/gh commands and file edits on main branch |
 | **git-workflows** | Command/Skill | `/sync-main`, `/git-flow-next`, `/troubleshoot-rebase`, `/troubleshoot-precommit`, `/troubleshoot-worktree`, `/pre-commit-architecture` | Local git sync, branching model, and rebase/pre-commit/worktree troubleshooting |
-| **github-workflows** | Command/Skill | `/ship`, `/finalize-pr`, `/refresh-repo`, `/prune-branches` (incl. `--sweep` and `--prune-stale` modes), `/rebase-pr`, `/merge-pr` (incl. `--squash`/`-s`), `/pr-sweep`, `/issue-sweep`, `/resolve-pr-threads`, `/gh-cli-patterns`, `/shape-issues`, `/trigger-ai-reviews` | GitHub PR/issue management workflows, cross-repo workspace sweep, stale-branch pruning, risk-ranked open-PR sweep-to-zero, and issue sweeps that reconcile open issues against reality |
+| **github-workflows** | Command/Skill | `/ship`, `/finalize-pr`, `/refresh-repo`, `/prune-branches` (incl. `--sweep` and `--prune-stale` modes), `/rebase-pr`, `/merge-pr` (incl. `--squash`/`-s`), `/pr-sweep`, `/issue-sweep`, `/resolve-pr-threads`, `/gh-cli-patterns`, `/shape-issues`, `/trigger-ai-reviews` | GitHub PR/issue management workflows, cross-repo workspace sweep, stale-branch pruning, parallel open-PR sweep-to-zero, and issue sweeps that reconcile open issues against reality |
 | **infra-orchestration** | Skill | `/orchestrate-infra`, `/sync-inventory`, `/test-e2e` | Cross-repo infrastructure orchestration for Terraform and Ansible |
 | **code-standards** | Skill | `/code-quality-standards`, `/review-standards` | Code quality standards, documentation formatting, testing philosophy, and review guidelines |
 | **git-standards** | Skill | `/git-workflow-standards`, `/pr-standards` | Git workflow standards, branch hygiene, PR creation guards, workaround vs fix classification, and issue linking |

github-workflows/skills/pr-sweep/SKILL.md

@@ -1,89 +1,142 @@
 ---
 name: pr-sweep
-description: "Drive open PRs toward zero across one or many repos by risk-ranking every open PR, auto-merging the low-risk mergeable ones, and surfacing the rest with the exact reason each is held. Use when open PRs have piled up and you want them triaged and cleared in one pass. Batches over the existing /merge-pr and /finalize-pr per PR — it decides which PRs are safe to merge and delegates the merge, it does not reimplement merging."
+description: "Use when open pull requests have piled up in one repo or across an owner's repos and you want the pile triaged and driven toward zero in one pass — including when most of them are bot- or teammate-authored. Also use when a sweep must run many repos in parallel without racing approvals or flooding CI."
 ---
 
 # PR Sweep
 
-Take a pile of open PRs and drive it to zero: merge what is safe, surface what is
-not with a specific reason. This is triage-and-clear, distinct from
-`/prune-branches --sweep` (which deletes dead branches and worktrees). This
-skill acts on **open PRs**; that one acts on **repo/worktree state**.
+Drive a pile of open PRs toward zero: merge what is safe, repair what is
+cheaply repairable, and surface the rest with a concrete reason each. This is
+triage-and-clear on **open PRs**; `/prune-branches --sweep` acts on
+**repo/worktree state** and is a different job.
 
-It does not reimplement merging. It **risk-ranks**, then hands each merge to
-`/merge-pr` (which itself runs the readiness gate and calls `/finalize-pr`).
-Merges use `/merge-pr`'s default (merge commit) — this sweep never passes
-`--squash`.
+This skill decides **which** PRs move and in **what order**. It never
+reimplements merging: each merge is delegated to `/merge-pr`, each repair to
+`/finalize-pr`.
 
-> **State warning**: PR status, CI, and mergeability change between invocations.
-> Re-list and re-check every PR in this run; never act on a cached list.
+## Invariants
 
-## Scope
-
-- `/pr-sweep` — open PRs in the current repo.
-- `/pr-sweep --org <owner>` — open PRs authored by you across the owner's repos
-  (`gh search prs --owner <owner> --author @me --state open`).
+These four hold in every mode. They are the difference between a sweep and a
+stampede.
 
-Always list first, act second. State the count before touching anything.
+1. **Triage is read-only and confers no merge authority.** Classifying a PR
+   never merges it.
+2. **A merge happens only against an execution order that pins the head
+   commit.** If the head moved since triage, the order is void — re-triage.
+   This is what makes an approval round impossible to race.
+3. **Serialize within a repo; parallelize across repos.** Merge ordering,
+   broken-base diagnosis, and repo-wide gates are all repo-scoped.
+4. **Cap concurrent merges globally** (default 2–3). Every merge triggers CI,
+   and CI capacity is finite and shared.
 
-## Step 1: List and gather signal
+Never pass `--admin`. Never merge a draft. Never bypass a failing check —
+repair it or hold the PR.
 
-For every open PR, collect the merge-decision signals in one pass:
+> **State warning**: PR status, CI, and mergeability change constantly, and
+> `mergeable`/`mergeStateStatus` are computed lazily — a first query often
+> returns `UNKNOWN`. Re-query before classifying, and never act on a list
+> gathered earlier in the session.
 
-```bash
-gh pr view <N> --json number,title,url,isDraft,mergeable,mergeStateStatus,\
-reviewDecision,additions,deletions,changedFiles,labels,baseRefName,headRefName
-```
-
-Also resolve whether the repo is git-flow (default branch `develop`) — a
-`develop → main` promotion PR is never swept (see Hold reasons).
+## Merge method is not this skill's business
 
-## Step 2: Risk-rank each PR
+`/merge-pr` resolves the merge method from the repo's capabilities and the
+branching model — see **git-flow-next** (git-workflows) for which method each
+target branch requires. This skill passes no method flag and states no
+default. A promotion PR into a production branch is never swept: hold it and
+point at `/promote-release`.
 
-Rank by blast radius and confidence, low to high:
+## Scope
 
-| Risk | Signals |
+- `/pr-sweep` — open PRs in the current repo.
+- `/pr-sweep --org <owner>` — open PRs across the owner's repos, **all
+  authors**. Bot and teammate PRs are usually the bulk of a real pile.
+- `--author <login>` — optional filter. Do not default to "mine": some token
+  types (app installation tokens) carry no user identity, so a self-filter
+  silently returns nothing.
+
+Command shapes live in **gh-cli-patterns**. List first, act second, and state
+the count before touching anything.
+
+## Phases
+
+Run all five in order. Phases 1 and 3 fan out; 0, 2, and 4 are the lead's.
+
+- **Phase 0 — Manifest (lead).** Enumerate repos × open PRs in one pass.
+  Report the count. Spawn one worker per repo, capped (default 4 concurrent).
+- **Phase 1 — Triage (workers, parallel, read-only).** Each worker classifies
+  every PR in its repo and detects repo-level conditions (broken base,
+  repo-wide gate). Output: one report block per repo. No writes.
+- **Phase 2 — Approval (lead, one round).** Batch **all** escalations into a
+  single round — one short paragraph per PR: identity, diffstat, state, and
+  the specific yes/no question. No diffs. Then issue per-repo execution
+  orders: `(PR number, head OID)` plus any ordering constraints.
+- **Phase 3 — Execute (workers).** Continue the *same* worker by message so it
+  keeps its triage context. Per repo, serially: take a merge-budget slot,
+  assert the head OID still matches, delegate to `/merge-pr`, wait on
+  merge-triggered CI with an event-driven monitor, release the slot. `FIX`
+  items go to `/finalize-pr`, then back through triage.
+- **Phase 4 — Verify and report (lead).** Wait for merge-triggered CI to
+  settle, then attribute every red by timestamp against merge time before
+  claiming a clean sweep.
+
+The lead does exactly two blocking things: the Phase 2 round and the Phase 4
+aggregation. It never re-derives repo state itself.
+
+## Classification
+
+Every PR gets exactly one verdict.
+
+| Verdict | Meaning |
 | --- | --- |
-| **Low** (auto-merge candidate) | `mergeable == MERGEABLE`, CI clean (`mergeStateStatus` CLEAN), not draft, no unresolved threads, small diff, docs/config/test-only or a bot dependency bump from a trusted source |
-| **Medium** (surface, do not auto-merge) | app/library code, larger diff, passing CI but no review, or any label like `needs-review`/`blocked` |
-| **High** (surface, flag loudly) | touches auth/secrets/migrations/infra, failing or pending CI, conflicts, or a `develop → main` promotion |
-
-The bar for **auto-merge** is deliberately conservative: low risk **and** nothing
-held. When unsure, rank up — a surfaced PR costs a glance; a wrongly-merged one
-costs a revert.
+| **MERGE** | Mergeable, checks green, not draft, no unresolved threads, and either low blast radius or an approved escalation. |
+| **FIX** | One delegated `/finalize-pr` away from mergeable — unresolved review threads, a stale rollup, a repairable check. Re-triage after. |
+| **HOLD** | Cannot proceed without a decision or new work. Always carries a reason. |
+| **ESCALATE** | Mergeable but the *judgment* is not the sweep's to make. Goes to Phase 2 as a question, never as an assumption. |
 
-## Step 3: Auto-merge the low-risk set
+Rank up when unsure. A surfaced PR costs a glance; a wrongly-merged one costs
+a revert.
 
-For each low-risk PR, delegate — do not merge by hand:
+## Hold reasons (never auto-merge)
 
-- Invoke **`/merge-pr <N>`** (no `--squash`). It re-runs the readiness gate, calls
-  `/finalize-pr` for soft blocks, and aborts on hard stops. Trust its refusal: if
-  it declines, the PR moves to the surfaced list with that reason.
-- Never pass `--admin`, never bypass a failing check, never merge a draft.
+- Draft, merge conflicts, or checks failing for a real (non-infrastructure)
+  reason.
+- A promotion PR into a production branch — use `/promote-release`.
+- Changes touching auth, secrets, migrations, permissions, or live infra — a
+  human decides.
+- An explicit human "do not merge", or a review-gate label. A prior human
+  refusal outranks the sweep.
+- `/merge-pr` refused — carry its reason forward verbatim.
+- A PR another session is actively working (recently pushed, in flight).
 
-## Step 4: Report
+## Report
 
 ```text
 PR Sweep — <scope>
-  Swept (merged):   <N> — <title>   (× each)
-  Held:             <N> — <reason: draft | CI red | conflicts | needs review | promotion | high-risk>
+  Merged:     <repo#N> — <title>
+  Fixed+merged: <repo#N> — <what was repaired>
+  Held:       <repo#N> — <reason>
+  Escalated:  <repo#N> — <question> → <decision>
+  Repo findings: <broken base | repo-wide gate | infra failure>
   Open before → after: <b> → <a>
 ```
 
-Every PR is either merged or listed with a concrete reason — never silently
-skipped. If nothing is low-risk, say so; a sweep that merges nothing is a valid
-outcome, not a failure.
+Every PR is merged or listed with a concrete reason — never silently skipped.
+A sweep that merges nothing is a valid outcome. File follow-ups per the
+project's issue-routing convention, and end a run that is blocked on a human
+decision by naming that decision.
 
-## Hold reasons (never auto-merge)
+## Mechanics
 
-- Draft, failing/pending CI, merge conflicts, unresolved review threads.
-- `develop → main` promotion PRs — use `/promote-release`.
-- Anything touching auth, secrets, DB migrations, or live infra — a human decides.
-- `/merge-pr` refused — carry its reason forward verbatim.
+Diagnosis and parallel-protocol detail — lazy state, `UNSTABLE` vs `BLOCKED`,
+broken-base proof, repo-wide gates, infrastructure-failure signatures, worker
+and order schemas: see [references/sweep-mechanics.md](references/sweep-mechanics.md).
 
 ## Related Skills
 
-- **merge-pr** (github-workflows) — performs each merge; this skill decides which.
-- **finalize-pr** (github-workflows) — PR metadata/soft-block handling, via merge-pr.
-- **prune-branches** (github-workflows) — the repo/worktree sweep; complementary, not this.
-- **promote-release** (github-workflows) — the correct path for held promotion PRs.
+- **merge-pr** (github-workflows) — performs each merge and owns method resolution.
+- **finalize-pr** (github-workflows) — drives one PR to mergeable; the `FIX` delegate.
+- **resolve-pr-threads** (github-workflows) — review-thread resolution.
+- **gh-cli-patterns** (github-workflows) — canonical command shapes and queries.
+- **promote-release** (github-workflows) — the held-promotion path.
+- **git-flow-next** (git-workflows) — the branching model that decides merge method.
+- **prune-branches**, **refresh-repo** (github-workflows) — complementary cleanup.