claude-dev-env 1.83.0 → 1.85.0

package/skills/monitor-open-prs/SKILL.md

@@ -27,7 +27,7 @@ description: >-
 
 Refusals — first match wins; respond with the quoted line exactly and stop:
 
-- **Disabled via environment.** When `CLAUDE_REVIEWS_DISABLED` (comma-separated, case-insensitive, whitespace-tolerant) contains the token `bugteam`: `/monitor-open-prs is a /bugteam dispatcher and /bugteam is disabled via CLAUDE_REVIEWS_DISABLED.`
+- **Disabled via environment.** When `CLAUDE_REVIEWS_DISABLED` (comma-separated, case-insensitive, whitespace-tolerant) has the token `bugteam`: `/monitor-open-prs is a /bugteam dispatcher and /bugteam is disabled via CLAUDE_REVIEWS_DISABLED.` Gate semantics live in the `reviewer-gates` skill ([../reviewer-gates/SKILL.md](../reviewer-gates/SKILL.md)).
 - **GitHub API not accessible.** `get_me failed. /monitor-open-prs needs active GitHub MCP credentials.`
 - **Dirty tree on the caller's repo.** `Uncommitted changes detected. Stash, commit, or revert before /monitor-open-prs.`
 - **Required subagents missing.** Confirm `code-quality-agent` and `clean-coder` exist. Else: `Required subagent type <name> not installed.`
@@ -41,7 +41,7 @@ Call `scripts/discover_open_prs.discover_open_prs(all_owners=["jl-cmd", "JonEcho
 For each discovered PR:
 
 1. Resolve the PR's repo checkout (existing worktree or fresh `git clone`).
-2. From that checkout, invoke `/bugteam --bugbot-retrigger <pr_number>`. When `CLAUDE_REVIEWS_DISABLED` (comma-separated, case-insensitive, whitespace-tolerant) contains the token `bugbot`, omit `--bugbot-retrigger` from the dispatched command so the bugbot leg sits out the run.
+2. From that checkout, invoke `/bugteam --bugbot-retrigger <pr_number>`. When `python "$HOME/.claude/_shared/pr-loop/scripts/reviews_disabled.py" --reviewer bugbot` exits 0 (bugbot disabled), omit `--bugbot-retrigger` from the dispatched command so the bugbot leg sits out the run.
 3. The `--bugbot-retrigger` flag tells bugteam to post `bugbot run` as an issue comment after every successful FIX push so Cursor's bugbot re-evaluates the new commit.
 4. Bugteam runs its own 20-loop audit/fix cycle per PR; this skill waits for each bugteam invocation to return before dispatching the next (or fanning out — see below).
 

package/skills/post-audit-findings/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: post-audit-findings
+description: >-
+  Publishes an audit pass as one GitHub PR review via the shared
+  post_audit_thread.py: maps audit findings to the {path, line, side,
+  severity, description, fix_summary} JSON shape (splitting failure_mode at
+  the literal `Fix:` heading), partitions anchored vs unanchored findings so
+  one bad anchor cannot reject the whole POST, handles the self-PR reviewer
+  toggle via BUGTEAM_REVIEWER_ACCOUNT, and harvests finding comment ids and
+  PRRT thread node ids for the fix loop. Invoked by audit skills (bugteam,
+  qbug, findbugs) after each audit pass, CLEAN or DIRTY; not for ad-hoc PR
+  comments or review replies.
+---
+
+# Post Audit Findings
+
+**Core principle:** every audit pass — CLEAN or DIRTY — lands on the PR as exactly one review, so the unresolved-thread gate sees the pass and each finding becomes its own resolvable thread.
+
+## How callers invoke this
+
+- **Skill-capable contexts** (a lead session with the `Skill` tool): `Skill({skill: "post-audit-findings", args: "--skill <caller> --owner <O> --repo <R> --pr-number <N> --commit <head_sha> --state <CLEAN|DIRTY> --findings-json <path>"})`.
+- **Fallback** (a subagent or teammate without the `Skill` tool): the caller's spawn prompt says "Read `~/.claude/skills/post-audit-findings/SKILL.md` and apply it with the parameters below."
+
+`--skill <caller>` is required — the posted review names the audit skill that produced it. Capture `<head_sha>` once, at the start of the posting step, via `git rev-parse HEAD` in the worktree the diff was scoped against.
+
+## Findings-JSON mapping
+
+The findings file's root is a list of objects shaped `{path, line, side, severity, description, fix_summary}`. Map each audit finding:
+
+- Finding `file` → `path`.
+- The `failure_mode` field carries both the failure narrative AND the `Fix:` / `Validation:` text (per [`agents/code-quality-agent.md`](../../agents/code-quality-agent.md), "The `failure_mode` field is the audit-to-fix handoff"). Split it at the literal `Fix:` heading: the prefix becomes `description`; the suffix starting at `Fix:` (including the trailing `Validation:` clause) becomes `fix_summary`. When a finding omits the `Fix:` heading, write the full `failure_mode` text to BOTH fields so the script's `INLINE_COMMENT_BODY_TEMPLATE` still renders coherently.
+- Set `side="RIGHT"` for every entry.
+- On CLEAN, the file holds an empty array (`[]`).
+
+## Anchored vs unanchored partition
+
+Before serializing, partition findings into **anchored** (the line appears in the diff at `--commit`) and **unanchored** (it does not). Only anchored findings go into the JSON — the GitHub reviews API rejects the ENTIRE POST when any inline comment targets a line outside the diff, so a single unanchored entry breaks the whole review. Surface unanchored findings in the caller's user-facing report instead.
+
+Zero anchored findings → `--state CLEAN`; one or more → `--state DIRTY`.
+
+## Posting
+
+```bash
+python "$HOME/.claude/_shared/pr-loop/scripts/post_audit_thread.py" \
+  --skill <caller> \
+  --owner <owner> \
+  --repo <repo> \
+  --pr-number <N> \
+  --commit <head_sha> \
+  --state <CLEAN|DIRTY> \
+  --findings-json <path>
+```
+
+The script POSTs one review to `/repos/{owner}/{repo}/pulls/{N}/reviews`: `event=APPROVE` on CLEAN (GitHub stores it as `state=APPROVED`; empty `comments[]`; body documents "no findings"), `event=REQUEST_CHANGES` on DIRTY (one inline anchored comment per finding; each becomes its own resolvable thread).
+
+**Self-PR auto-toggle.** GitHub rejects both `APPROVE` and `REQUEST_CHANGES` with HTTP 422 when the authenticated identity matches the PR author. `post_audit_thread.py` detects this via `gh api user` + `gh api repos/<o>/<r>/pulls/<n>` and auto-resolves an alternate gh account's token for the reviews POST — the active `gh auth` account is not mutated; only the bearer token on the request changes, so no swap-back step exists.
+
+Configuration:
+
+- `GH_TOKEN` / `GITHUB_TOKEN` env vars take precedence over the toggle — set one to pin a reviewer identity by token.
+- `BUGTEAM_REVIEWER_ACCOUNT` names which authenticated alternate to prefer (for example `BUGTEAM_REVIEWER_ACCOUNT=jl-cmd`). The env var name is shared across every skill that invokes `post_audit_thread.py`. When unset, the script falls back to the first alternate account `gh auth status` reports.
+- The named alternate must be logged in (`gh auth login -h github.com -u <login>`) before the audit runs; on self-PR with no usable alternate the script exits 1 with a message pointing at `gh auth login`.
+
+**Exit codes:** `0` — success; the new review's `html_url` prints to stdout (surface it in the caller's report). `1` — user input error. `2` — retry exhaustion (1s / 4s / 16s backoff across four attempts): a hard blocker. On exit 2 the caller halts the loop (`error: post_audit_thread retry exhausted`) or tells the user the review post failed and the unresolved-thread gate will not see this pass — never a silent retry.
+
+## Harvest ids for the fix loop
+
+After a DIRTY post, fetch the new review's threads once and record, per finding: the finding comment's URL, its numeric comment id (the reply anchor), and its thread node id (`PRRT_…`, the `resolve_thread` handle):
+
+```
+pull_request_read(method="get_review_comments", ...) → match comments to the new review id
+```
+
+Hand the id triple to the fix step — `pr-fix-protocol` consumes it for the reply-and-resolve unit. Harvesting at post time saves the fix executor a second fetch and pins the mapping before any thread state changes.
+
+## Gotchas
+
+- **One unanchored comment voids the whole review.** The partition is not an optimization; skipping it makes every DIRTY post a coin flip.
+- **CLEAN still posts.** A pass that finds nothing and posts nothing is invisible to the unresolved-thread gate and to anyone auditing the loop's history.
+- **Exit 2 is a stop, not a retry.** The script already retried with backoff; a caller looping on top of it hammers the API to no effect.
+
+## Folder map
+
+- `SKILL.md` — this file. The posting script and its body template constants live in `_shared/pr-loop/scripts/` (`post_audit_thread.py`, `pr_loop_shared_constants/post_audit_thread_constants.py`); the review-payload reference is `_shared/pr-loop/gh-payloads.md`.

package/skills/pr-converge/CLAUDE.md

@@ -27,3 +27,5 @@ Drives a draft PR to convergence by looping Cursor Bugbot, a code-review pass, a
 - The pre-flight gate requires `EnterWorktree` before any file read or API call, and confirms `ScheduleWakeup` is in the tool list.
 - All findings and PR reports state verified facts only — no hedging language.
 - The GitHub MCP (`pull_request_read`, `pull_request_review_write`) is the primary path for PR inspection; `gh api` is the fallback.
+- Three step-scoped agents (`fix_executor`, `thread_sweep`, `copilot_watch`) persist across ticks via the `persistent_agents` map in loop state; each tick resumes them with `SendMessage` and spawns a fresh named agent when a stored id is dead.
+- The tick delegates shared mechanics to five sibling sub-skills: `reviewer-gates` (opt-out, Copilot quota, Bugbot trigger), `pr-scope-resolve` (target resolution), `pr-fix-protocol` (fix sequence + unresolved-thread sweep), `post-audit-findings` (audit posting), and `pr-loop-lifecycle` (run open/close).

package/skills/pr-converge/SKILL.md

@@ -43,25 +43,26 @@ working directory routes into the PR's repo for local work and returns to
 the session worktree before teardown. See
 [`reference/per-tick.md` § Step 1.5](reference/per-tick.md).
 
+## Resume from a prior run
+
+Before Step 0, check
+`~/.claude/runtime/pr-loop/bugteam-pr-<PR number>/handoff.json`. When
+`$CLAUDE_JOB_DIR/pr-converge-state.json` is absent but that handoff exists, seed
+`phase`, `tick_count`, and the clean-at SHAs from the run's `state-copy.json`, so
+a fresh session continues where the last one stopped rather than restarting at
+BUGBOT.
+
 ## Copilot quota pre-check (start of run)
 
-On the first tick, before Step 4, run the Copilot quota pre-check once:
-`python "$HOME/.claude/_shared/pr-loop/scripts/copilot_quota.py"`. It reads the
-account's remaining Copilot premium-request quota via `gh api
-copilot_internal/user` and prints one line — log that line. Exit 0 means Copilot
-has quota, so leave `copilot_down` false. Any non-zero exit means skip Copilot
-for the whole run — the account is out of quota, the quota API or account access
-is down, or no account is set — so set `copilot_down = true` in
-`pr-converge-state.json`. The account comes from the `COPILOT_QUOTA_ACCOUNT`
-environment variable or a git-ignored `.env` file, and the no-account line names
-the exact `.env` path and key to set.
-
-Run the pre-check once, not per tick. Every tick reads `copilot_down` from
-state. When `copilot_down` is true, skip the Copilot gate outright — no fetch,
-no request, no poll, no agent — and export `CLAUDE_REVIEWS_DISABLED="copilot"`
-in that tick's shell before the convergence check, so `check_convergence.py`
-bypasses the Copilot review gate and the pending-requested-reviews gate and the
-run still marks ready on the remaining signals.
+On the first tick, apply the `reviewer-gates` skill's Copilot quota gate
+(`../reviewer-gates/SKILL.md` § Gate 2) — once per run, never per tick. The
+flag lives in `pr-converge-state.json` as `copilot_down`, and every tick reads
+it. While `copilot_down` is true, the tick skips all Copilot work — no fetch,
+no request, no poll, no agent — and exports
+`CLAUDE_REVIEWS_DISABLED="copilot"` in that tick's shell before
+`check_convergence.py`, so the check bypasses the Copilot review gate and the
+pending-requested-reviews gate and the run still marks ready on the remaining
+signals.
 
 ## Budget-aware tick boundaries
 
@@ -69,7 +70,8 @@ Before starting any tick, estimate whether the remaining session/usage
 budget covers one full clean tick (worst case: a BUGBOT fetch + a
 full-diff CODE_REVIEW + a fix commit + replies). If it does not, do not
 start the tick. Stop at the current tick boundary: write updated state to
-`$CLAUDE_JOB_DIR/pr-converge-state.json`, then report the exact resume
+`$CLAUDE_JOB_DIR/pr-converge-state.json`, write the durable handoff (see
+[State persistence](#state-persistence)), then report the exact resume
 command (`/pr-converge <PR URL>`) and the persisted `phase`/`tick_count`.
 A tick cut off mid-flight poisons the resume state — clean SHAs recorded
 against work that never landed — so an unstarted tick is always cheaper
@@ -91,10 +93,58 @@ On tick entry, read this file if it exists to restore phase, tick_count, and
 clean-at SHAs. On tick exit, write updated state before calling ScheduleWakeup
 so the next tick resumes with accurate state.
 
+After the state write and before ScheduleWakeup, write the durable handoff so a
+fresh session in a new job can resume this run:
+
+```
+python "$HOME/.claude/skills/_shared/pr-loop/scripts/write_handoff.py" \
+  --pr-number <N> --head-ref <branch> --phase <phase> \
+  --resume-command "/pr-converge <PR URL>" \
+  --state-file "$CLAUDE_JOB_DIR/pr-converge-state.json" \
+  --completed-steps "<clean phases this run>"
+```
+
+It writes `handoff.json`, `HANDOFF.md`, and `state-copy.json` under
+`~/.claude/runtime/pr-loop/<run-name>/`. The job-dir state stays the source of
+truth for a resumed tick; the handoff copy is the pointer a fresh session reads
+when `$CLAUDE_JOB_DIR` is gone.
+
 Fields: `phase`, `tick_count`, `bugbot_clean_at`, `code_review_clean_at`,
 `bugteam_clean_at`, `copilot_clean_at`, `current_head`,
 `bugbot_acknowledged_at`, `bugbot_down`, `copilot_down`,
-`bugteam_skill_invoked_at_head`, `bugteam_skill_invoked_at_tick`.
+`bugteam_skill_invoked_at_head`, `bugteam_skill_invoked_at_tick`,
+`agents_session_id`, `persistent_agents`.
+
+## Persistent per-step agents
+
+Three step-scoped agents persist across ticks so their context carries
+forward: `fix_executor`, `thread_sweep`, and `copilot_watch`, recorded in
+the `persistent_agents` map
+([`reference/state-schema.md`](reference/state-schema.md)).
+
+- **Resume:** read `persistent_agents.<key>`. When an entry exists,
+  `SendMessage` to the stored `agent_id` with a tick payload that restates
+  the PR scope, `current_head`, the PR worktree path, this tick's findings
+  or threads, and the report-back contract. Bump `last_used_tick`, then
+  await completion.
+- **First spawn:** `Agent(subagent_type: "clean-coder", name:
+  "prc-fix-<PR#>")` — the `name` makes the agent a persistent teammate
+  that idles awaiting messages. Record `{agent_id, created_tick,
+  last_used_tick}` under the step key. Keep the spawn prompt fix-shaped,
+  never audit-shaped: the `pr_converge_bugteam_enforcer` hook blocks
+  audit-shaped clean-coder spawns during the BUGTEAM phase.
+- **Stale or dead id:** on a `SendMessage` failure, or no acknowledgment
+  within one bounded wait, drop the map entry, spawn a fresh named agent,
+  record it, and continue the tick. Never abort a tick on a stale id;
+  never retry the same dead id.
+- **Fresh every round (never persisted):** the Step 5 `/code-review --fix`
+  pass and the Step 6 bugteam audit (unbiased eyes each round; the
+  enforcer needs the formal Skill call), and every `code-verifier` — a
+  named code-verifier never fires `SubagentStop`, so no verdict mints (see
+  the named-`code-verifier` entry in the Gotchas list below).
+- **Shutdown:** at loop end (convergence or a stop condition), send each
+  persistent agent a shutdown request and clear `persistent_agents` before
+  the `pr-loop-lifecycle` Close.
 
 ## Gotchas
 
@@ -159,13 +209,9 @@ script invocations, decision criteria. Every "return to Step N" means the next
 tick starts fresh from that step.
 
 **Hard gate: do not advance from any step while ANY unresolved review
-thread exists on the PR.** The thread-count filter is purely
-`is_resolved == false` — author, commit anchor, and `is_outdated` are
-all irrelevant. After every fix, reply to each finding comment and
-resolve the thread via `pull_request_review_write(method="resolve_thread")`.
-For each unresolved thread, verify the concern against current HEAD;
-either fix-and-resolve, or reply-with-note-and-resolve when the concern
-no longer applies.
+thread exists on the PR.** The sweep semantics and per-thread handling live
+in the `pr-fix-protocol` skill's unresolved-thread sweep
+(`../pr-fix-protocol/SKILL.md`).
 
 **Full-PR-diff rule: every CODE-REVIEW round (Step 5) and every BUGTEAM
 round (Step 6) covers the FULL `origin/main...HEAD` diff — every file
@@ -176,11 +222,13 @@ against a partial diff is not a valid clean. Re-run the round against the
 full diff before recording `code_review_clean_at` or treating the bugteam
 round as converged. This rule holds every tick, every loop, every PR.
 
-- [ ] **Step 0: Grant project permissions**
-      `python "$HOME/.claude/skills/bugteam/scripts/grant_project_claude_permissions.py"`
+- [ ] **Step 0: Open the run**
+      Apply the `pr-loop-lifecycle` skill's Open section
+      (`../pr-loop-lifecycle/SKILL.md`): permission grant + worktree preflight.
 
 - [ ] **Step 1: Resolve PR scope + PR worktree**
-      Capture owner, repo, number, head SHA, branch. Resolve the **PR
+      Apply the `pr-scope-resolve` skill (`../pr-scope-resolve/SKILL.md`)
+      with caller `pr-converge`. Resolve the **PR
       worktree** — the local checkout every local step this tick targets:
       the `EnterWorktree` checkout when the PR shares the session's repo,
       else a checkout of the PR's repo that the working directory routes
@@ -205,6 +253,8 @@ round as converged. This rule holds every tick, every loop, every PR.
       See: [`reference/per-tick.md` § Step 2 BUGBOT + Step 3](reference/per-tick.md)
 
       - [ ] **Opt-out gate (runs first, every BUGBOT entry).**
+            Gate semantics live in the `reviewer-gates` skill
+            (`../reviewer-gates/SKILL.md` § Gate 1).
             `python "$HOME/.claude/_shared/pr-loop/scripts/reviews_disabled.py" --reviewer bugbot`
             - [ ] Exit 0 (`CLAUDE_REVIEWS_DISABLED` lists `bugbot`) → set `bugbot_down = true`, `phase = CODE_REVIEW`, advance to Step 5 (bypass). Cursor Bugbot is skipped for the entire run.
             - [ ] Exit 1 → continue below.
@@ -212,9 +262,7 @@ round as converged. This rule holds every tick, every loop, every PR.
       Fetch bugbot reviews + inline comments on `current_head`.
 
       - [ ] **dirty** (findings on `current_head`) →
-            - [ ] Fix each finding (spawn `clean-coder`)
-            - [ ] Reply to each finding comment via `python ~/.claude/skills/pr-converge/scripts/post_fix_reply.py`
-            - [ ] Resolve each addressed thread via `pull_request_review_write(method="resolve_thread")`
+            - [ ] Apply the `pr-fix-protocol` skill (`../pr-fix-protocol/SKILL.md`) to this tick's findings
             - [ ] Push → return to Step 4
       - [ ] **clean** (no findings on `current_head`) →
             - [ ] Count ALL unresolved threads on PR (`is_resolved == false`) → zero? advance; >0? fix + resolve first
@@ -222,14 +270,12 @@ round as converged. This rule holds every tick, every loop, every PR.
             - [ ] `phase = CODE_REVIEW`
             - [ ] Advance to Step 5
       - [ ] **no review yet / commit_id mismatch** →
-            - [ ] Run `python ~/.claude/skills/pr-converge/scripts/check_bugbot_ci.py --owner <O> --repo <R> --check-clean --sha <current_head>`
-            - [ ] Exit 0 (bugbot CI completed with success/neutral conclusion and no review = silent pass) → `bugbot_clean_at = current_head` → `phase = CODE_REVIEW` → advance to Step 5
-            - [ ] Exit 1 (not a silent pass) or Exit 2 (gh CLI error — silent pass not confirmable) → Run `python ~/.claude/skills/pr-converge/scripts/check_bugbot_ci.py --owner <O> --repo <R> --check-active --sha <current_head>`
-            - [ ] Exit 0 (already queued) → schedule 360s wakeup → return to Step 4 next tick
-            - [ ] Exit 1 → post exactly `bugbot run` via `add_issue_comment` (no `@cursor[bot]` mention, no other text), wait 8s
-            - [ ] Run `python ~/.claude/skills/pr-converge/scripts/check_bugbot_ci.py --owner <O> --repo <R> --sha <current_head>`
-            - [ ] Exit non-zero → `bugbot_down = true` → `phase = CODE_REVIEW` → advance to Step 5 (bypass)
-            - [ ] Exit 0 → record `bugbot_acknowledged_at`, schedule 360s wakeup → return to Step 4
+            Apply the `reviewer-gates` skill's Bugbot flow
+            (`../reviewer-gates/SKILL.md` § Gate 3) against `current_head`,
+            then map its outcomes:
+            - [ ] Silent pass → `bugbot_clean_at = current_head` → `phase = CODE_REVIEW` → advance to Step 5
+            - [ ] Already queued, or trigger acknowledged → schedule 360s wakeup → return to Step 4 next tick
+            - [ ] Bugbot down → `bugbot_down = true` → `phase = CODE_REVIEW` → advance to Step 5 (bypass)
 - [ ] **Step 5: CODE-REVIEW — run, fix, reset, advance**
       See: [`reference/per-tick.md` § Step 2 CODE_REVIEW](reference/per-tick.md)
 
@@ -264,13 +310,13 @@ round as converged. This rule holds every tick, every loop, every PR.
             - [ ] Re-trigger bugbot (Step 4 "no review yet" checklist)
             - [ ] `phase = BUGBOT` → schedule 360s wakeup → return to Step 4
       - [ ] **clean** (no changes applied) →
-            - [ ] Count ALL unresolved threads on PR (`is_resolved == false`) → zero? advance; >0? fix + resolve first
+            - [ ] Zero unresolved threads per the `pr-fix-protocol` sweep (`../pr-fix-protocol/SKILL.md`) → advance; else fix + resolve first (same skill)
             - [ ] `code_review_clean_at = current_head`
             - [ ] `phase = BUGTEAM` → advance to Step 6
 
 - [ ] **Step 6: BUGTEAM — run, decide, fix, reply, resolve**
       See: [`reference/per-tick.md` § Step 2 BUGTEAM](reference/per-tick.md);
-      [`../../bugteam/SKILL.md`](../../bugteam/SKILL.md)
+      [`../bugteam/SKILL.md`](../bugteam/SKILL.md)
 
       Pre-condition: `code_review_clean_at == current_head`.
 
@@ -300,9 +346,7 @@ round as converged. This rule holds every tick, every loop, every PR.
       - [ ] **converged + `bugbot_clean_at ≠ current_head`** →
             `phase = BUGBOT` → schedule 360s wakeup → return to Step 4
       - [ ] **findings without committed fixes** →
-            - [ ] Fix each finding (spawn `clean-coder`)
-            - [ ] Reply to each finding comment via `python ~/.claude/skills/pr-converge/scripts/post_fix_reply.py`
-            - [ ] Resolve each addressed thread via `pull_request_review_write(method="resolve_thread")`
+            - [ ] Apply the `pr-fix-protocol` skill (`../pr-fix-protocol/SKILL.md`) to the findings
             - [ ] Push → `phase = BUGBOT` → return to Step 4
 
 - [ ] **Step 7: Convergence gates**
@@ -317,15 +361,13 @@ round as converged. This rule holds every tick, every loop, every PR.
             pull_request_read(method="get_review_comments")
               → filter threads where is_resolved == false
             ```
-      - [ ] Any unresolved? → For each: verify concern against current HEAD;
-            if still applies → Fix (spawn `clean-coder`) → reply → resolve;
-            if no longer applies → reply-with-note → resolve. Push if any code changed → return to Step 4
+      - [ ] Any unresolved? → apply the `pr-fix-protocol` skill's unresolved-thread sweep (`../pr-fix-protocol/SKILL.md`). Push if any code changed → return to Step 4
       - [ ] When `copilot_down == true` (start-of-run quota pre-check), skip the Copilot fetch below — no request, no poll, no agent — and continue to gate (b); the Copilot gate is bypassed for the whole run.
       - [ ] Fetch Copilot review on `current_head` (top-level review state — uses get_reviews, identifies by reviewer):
             ```
             python ~/.claude/skills/pr-converge/scripts/fetch_copilot_reviews.py --owner <O> --repo <R> --pr-number <N>
             ```
-      - [ ] dirty → Fix (spawn `clean-coder`) → reply → resolve threads → push → return to Step 4
+      - [ ] dirty → apply the `pr-fix-protocol` skill (`../pr-fix-protocol/SKILL.md`) → push → return to Step 4
       - [ ] clean (no findings) → `copilot_clean_at = current_head` → gate (b)
       - [ ] no review yet → gate (b)
 
@@ -357,10 +399,7 @@ round as converged. This rule holds every tick, every loop, every PR.
         → count threads where is_resolved == false
       ```
       - [ ] zero unresolved → gate (e)
-      - [ ] unresolved → For each: verify against HEAD;
-            still applies → Fix (spawn `clean-coder`) → reply → resolve;
-            no longer applies → reply-with-note → resolve.
-            Push if code changed → return to Step 4
+      - [ ] unresolved → apply the `pr-fix-protocol` skill's unresolved-thread sweep (`../pr-fix-protocol/SKILL.md`). Push if code changed → return to Step 4
 
       **(e) Mark ready**
       - [ ] When `copilot_down == true`, export `CLAUDE_REVIEWS_DISABLED="copilot"` in this tick's shell before the check below, so it bypasses the Copilot review gate and the pending-requested-reviews gate.
@@ -384,22 +423,22 @@ round as converged. This rule holds every tick, every loop, every PR.
       - [ ] **clean (no findings)** →
             `copilot_clean_at = current_head` → return to Step 7 (re-validate gates b, d, e)
       - [ ] **dirty (findings present)** →
-            - [ ] Fix each finding (spawn `clean-coder`)
-            - [ ] Reply to each finding comment via `python ~/.claude/skills/pr-converge/scripts/post_fix_reply.py`
-            - [ ] Resolve each addressed thread via `pull_request_review_write(method="resolve_thread")`
+            - [ ] Apply the `pr-fix-protocol` skill (`../pr-fix-protocol/SKILL.md`) to the findings
             - [ ] Push → `phase = BUGBOT` → return to Step 4
       - [ ] **no review yet** →
             increment `copilot_wait_count` → ≥ 3 = hard blocker → stop
             schedule 360s wakeup → return to Step 7a next tick
 
 - [ ] **Step 8: Clean working tree**
-      See: [`bugteam/reference/teardown-publish-permissions.md` § Step 4](../../bugteam/reference/teardown-publish-permissions.md)
+      `pr-loop-lifecycle` Close (`../pr-loop-lifecycle/SKILL.md`).
+      See: [`pr-loop-lifecycle/reference/teardown-publish-permissions.md` § Clean working tree](../pr-loop-lifecycle/reference/teardown-publish-permissions.md)
 
 - [ ] **Step 9: Rewrite PR description**
-      See: [`bugteam/reference/teardown-publish-permissions.md` § Step 4.5](../../bugteam/reference/teardown-publish-permissions.md)
+      `pr-loop-lifecycle` Close.
+      See: [`pr-loop-lifecycle/reference/teardown-publish-permissions.md` § Publish the final PR description](../pr-loop-lifecycle/reference/teardown-publish-permissions.md)
 
-- [ ] **Step 10: Revoke project permissions**
-      `python "$HOME/.claude/skills/bugteam/scripts/revoke_project_claude_permissions.py"`
+- [ ] **Step 10: Revoke project permissions (always)**
+      `pr-loop-lifecycle` Close (`../pr-loop-lifecycle/SKILL.md` § Close).
 
 - [ ] **Step 11: Print final report**
       Print this block verbatim — no paraphrase, no extra commentary:

package/skills/pr-converge/reference/CLAUDE.md

@@ -8,7 +8,7 @@ Reference documents for the `pr-converge` skill. These files define the per-tick
 |---|---|
 | `per-tick.md` | Step-by-step procedure for one tick (resolve HEAD, run BUGBOT, CODE_REVIEW, BUGTEAM, COPILOT_WAIT phases, schedule next wakeup) |
 | `convergence-gates.md` | Six gates that must all pass before the PR is marked ready for review |
-| `fix-protocol.md` | How to apply fixes: TDD first, one commit per fix round, reply to each finding inline |
+| `fix-protocol.md` | pr-converge deltas on the `pr-fix-protocol` skill: multi-PR teammate obligations and the same-tick bugbot re-trigger rule |
 | `ground-rules.md` | Non-negotiable constraints for the convergence loop |
 | `stop-conditions.md` | Conditions that end the loop without convergence (cap reached, stuck, user stop) |
 | `state-schema.md` | Fields in `pr-converge-state.json` and their meanings |

package/skills/pr-converge/reference/convergence-gates.md

@@ -35,22 +35,21 @@ Decide (four branches; match first whose predicate holds):
 
 - **`classification == "dirty"` with non-empty inline comments matching
   `pull_request_review_id`:** Fix protocol input (same shape as bugbot
-  dirty). Spawn Agent (subagent_type: clean-coder) to implement → push → reply inline on each thread via
-  `python ~/.claude/skills/pr-converge/scripts/post_fix_reply.py` → Step 3 in same tick (see
-  [Single-PR fix workflow](fix-protocol.md#single-pr-fix-workflow) for
-  full contract).
+  dirty). Apply the `pr-fix-protocol` skill
+  (`../../pr-fix-protocol/SKILL.md`) → Step 3 in same tick.
   Reset `bugbot_clean_at = null` AND `copilot_clean_at = null`, `phase =
   BUGBOT`, schedule next wakeup, return. Full back-to-back-clean cycle
   plus all six gates must hold again on new HEAD.
 - **`classification == "dirty"` with empty inline comments matching
   `pull_request_review_id`:** Copilot posted findings only in review body
   (`CHANGES_REQUESTED` or `COMMENTED` with non-empty body, no inline
-  threads). Parse body for actionable findings. Spawn Agent (subagent_type: clean-coder) to implement → push → post
-  top-level review reply via `python ~/.claude/skills/pr-converge/scripts/post_fix_reply.py` citing new HEAD SHA → Step 3 in same tick.
-  Reset
+  threads). Parse body for actionable findings. Apply the
+  `pr-fix-protocol` skill (`../../pr-fix-protocol/SKILL.md`), whose reply
+  step for body-only findings posts a top-level review reply citing the
+  new HEAD SHA → Step 3 in same tick. Reset
   `bugbot_clean_at = null` AND
   `copilot_clean_at = null`, `phase = BUGBOT`, Step 3 on new HEAD,
-  schedule next wakeup, return. Convergence requires full
+  schedule next wakeup, return. Convergence needs full
   back-to-back-clean on new HEAD.
 - **`classification == "clean"` (state `APPROVED`):** Set
   `copilot_clean_at = current_head`. Record evidence: "Copilot APPROVED at <SHA>".
@@ -77,14 +76,15 @@ Decide (four branches; match first whose predicate holds):
 
 - **`classification == "dirty"` with non-empty inline comments matching
   `pull_request_review_id`:** Treat identically to gate (a) dirty+inline
-  path — spawn Agent (subagent_type: clean-coder) to fix → push → reply inline on each thread. Reset
+  path — apply the `pr-fix-protocol` skill
+  (`../../pr-fix-protocol/SKILL.md`). Reset
   `bugbot_clean_at = null` AND `copilot_clean_at = null`, `phase = BUGBOT`,
   schedule next wakeup, return.
 - **`classification == "dirty"` with empty inline comments matching
   `pull_request_review_id`:** Claude posted findings only in review body
   (`CHANGES_REQUESTED` or `COMMENTED` with non-empty body, no inline
-  threads). Treat identically to gate (a) dirty+body path — spawn Agent
-  (subagent_type: clean-coder) to implement → push → post top-level review reply via `python ~/.claude/skills/pr-converge/scripts/post_fix_reply.py`. Reset
+  threads). Treat identically to gate (a) dirty+body path — apply the
+  `pr-fix-protocol` skill (`../../pr-fix-protocol/SKILL.md`). Reset
   `bugbot_clean_at = null` AND `copilot_clean_at = null`, `phase = BUGBOT`,
   schedule next wakeup, return.
 - **`classification == "clean"` (state `APPROVED`):** Record evidence:
@@ -176,19 +176,16 @@ pull_request_read(owner=OWNER, repo=REPO, pullNumber=NUMBER, method="get_review_
   → count
 ```
 
-When you address an unresolved thread, you still need its author and
-anchor commit so you can decide how to fix it — but the gate doesn't
-filter on those fields.
+This count is the `pr-fix-protocol` unresolved-thread sweep
+(`../../pr-fix-protocol/SKILL.md`).
 
 Decide:
 
 - **Zero unresolved threads:** Record evidence:
   "0 unresolved threads across PR at <SHA>". Continue to gate (f).
-- **One or more unresolved threads:** Do **not** mark ready. For each
-  unresolved thread, verify the concern against current HEAD. If still
-  applies, apply Fix protocol (test → fix → push → reply → resolve). If
-  no longer applies (e.g. code already changed), reply-with-note
-  explaining why and resolve. Push if any code changed → reset
+- **One or more unresolved threads:** Do **not** mark ready. Apply the
+  `pr-fix-protocol` skill's unresolved-thread sweep
+  (`../../pr-fix-protocol/SKILL.md`). Push if any code changed → reset
   `bugbot_clean_at = null` AND `copilot_clean_at = null`,
   `phase = BUGBOT`, schedule next wakeup, return. If only resolutions
   (no code changes), re-check this gate without resetting.

package/skills/pr-converge/reference/examples.md

@@ -54,9 +54,8 @@ sufficient. Runs `convergence-gates.md` gates in order:
     Next tick: re-run gate (a) fetch → Copilot `APPROVED` at `current_head`
     → set `copilot_clean_at = current_head`, record evidence: "Copilot
     APPROVED at <SHA>", set `phase = BUGTEAM`, re-validate gates (b) and (c).
-  Gate (e): `pull_request_read(method="get_review_comments")` → count
-    threads where `is_resolved == false` (no author/commit/outdated
-    filter) → zero across PR → record evidence.
+  Gate (e): the `pr-fix-protocol` unresolved-thread sweep
+    (`../../pr-fix-protocol/SKILL.md`) → zero across PR → record evidence.
   Gate (f): all six gates pass → `update_pull_request(pullNumber=NUMBER,
     owner=OWNER, repo=REPO, draft=false)`.
 Reports "PR #N converged: bugbot CLEAN at <SHA>, bugteam CLEAN at <SHA>,
@@ -100,8 +99,9 @@ Copilot review `state: APPROVED` at `current_head`. Claude: [re-runs
 gate (a) fetch → APPROVED → sets `copilot_clean_at = current_head`,
 records evidence: "Copilot APPROVED at <SHA>", sets `phase = BUGTEAM`;
 re-validates gates (b) Claude absent and (c) mergeability clean,
-records evidence for both; gate (e) zero unresolved threads passes
-trivially, record evidence: "0 unresolved threads across PR at <SHA>";
+records evidence for both; gate (e) — the `pr-fix-protocol`
+unresolved-thread sweep — passes trivially, record evidence:
+"0 unresolved threads across PR at <SHA>";
 runs `update_pull_request(pullNumber=NUMBER,
 owner=OWNER, repo=REPO, draft=false)`; reports "PR #N converged: bugbot CLEAN
 at <SHA>, bugteam CLEAN at <SHA>, mergeable_state clean, copilot CLEAN at

package/skills/pr-converge/reference/fix-protocol.md

@@ -1,10 +1,15 @@
 # Fix protocol
 
-Single-PR (no `state.json`): production edits run in main session via
-`Agent` (`subagent_type: "clean-coder"`). Multi-PR (`state.json`):
-clean-coder teammate; orchestrator never edits inline. Hook handling
+The full fix protocol — executor choice, the shared 13-step sequence,
+reply transport, thread resolution, the unresolved-thread sweep, and
+post-push resets — lives in the `pr-fix-protocol` skill
+(`../../pr-fix-protocol/SKILL.md`), which follows the shared step
+sequence in `../../../_shared/pr-loop/fix-protocol.md`. Hook handling
 per [ground-rules.md](ground-rules.md).
 
+This file holds only the pr-converge deltas: the multi-PR teammate
+obligations and the same-tick re-trigger rule.
+
 **Multi-PR (`state.json`) teammate obligations** (plus TDD, commit, push):
 
 - Replies inline on each addressed finding via
@@ -21,44 +26,12 @@ per [ground-rules.md](ground-rules.md).
 Orchestrator does not reply inline, trigger bugbot, or read repo source
 files during fix phase in multi-PR mode.
 
-### Single-PR fix workflow
-
-**Single-PR (no `state.json`) — same gates, main session executor:**
-
-Run every command below in the PR worktree (the working directory routed in
-[per-tick.md § Step 1.5](per-tick.md)). The `git add`, `git commit`, and
-`git push` act on the repo of the current working directory, so a cross-repo
-PR's fix lands in the PR's repo only when the cwd is its worktree. A spawned
-`clean-coder` does not inherit the lead's working directory — name the PR
-worktree path in its prompt and direct it to edit, stage, and commit there,
-matching the worktree-path handoff bugteam embeds in its fix worker's spawn
-prompt.
-
-- Read each referenced file:line.
-- Write failing test first when finding has behavior to test. Pure doc /
-  comment / naming nits with no behavior → straight to fix.
-- **Implement** via `Agent` (`subagent_type: "clean-coder"`).
-  Full-stop if `Agent` is unavailable.
-- Stage affected files and create one new commit on existing branch:
-  ```bash
-git add <files> && git commit -m "fix(review): <brief summary>"
-  ```
-**Pre-commit gate:** honor hooks; full-stop on bypass.
-- Push the new commit:
-  ```bash
-git push origin <BRANCH>
-  ```
-**Pre-push gate:** honor hooks; full-stop on bypass. Capture new HEAD
-only after both gates pass; set `current_head`, `bugbot_clean_at = null`.
-- Reply inline on each addressed comment thread using `python scripts/post_fix_reply.py`:
+### Same-tick re-trigger rule
 
-  ```
-  python scripts/post_fix_reply.py --owner <O> --repo <R> --pr-number <N> --in-reply-to <COMMENT_ID> --body "Fixed in <SHA> — <what changed>"
-  ```
-- **After pushing a fix, always run Step 3 (`bugbot run`) in the same
-  tick** regardless of phase. New commit **resets full convergence cycle**:
-  prior bugbot clean and prior bugteam clean on older SHA do **not**
-  count toward convergence on new `HEAD`. Must re-obtain bugbot CLEAN on
-  `current_head`, then bugteam CLEAN on same `HEAD` with no
-  intervening push. Re-triggering in same tick saves a wakeup cycle vs
-  deferring Step 3.
+**After pushing a fix, always run Step 3 (`bugbot run`) in the same
+tick** regardless of phase. A new commit **resets the full convergence
+cycle**: a bugbot clean and a bugteam clean on an older SHA do **not**
+count toward convergence on the new `HEAD`. Re-obtain bugbot CLEAN on
+`current_head`, then bugteam CLEAN on the same `HEAD` with no
+intervening push. Re-triggering in the same tick saves a wakeup cycle
+vs deferring Step 3.

package/skills/pr-converge/reference/obstacles/fix-publish-summary.md

@@ -1,6 +1,6 @@
 # Publish fix summary
 
-Publish fix summary HTML via /doc-gist with commit SHA and per-fix descriptions
+Publish fix summary HTML via the Artifact tool with commit SHA and per-fix descriptions
 
 ## Self-population