claude-dev-env 1.82.0 → 1.84.0

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
 

package/skills/pr-converge/reference/per-tick.md

@@ -190,11 +190,8 @@ pull_request_read(owner=OWNER, repo=REPO, pullNumber=NUMBER, method="get_review_
    → filter threads where `is_resolved == false`
    ```
 
-   For each unresolved thread, you still need to know **who** wrote it
-   and **what commit** it anchors to so you can decide how to address it
-   — but the gate itself doesn't filter on those fields. Verify each
-   thread's concern against current HEAD; either fix-and-resolve or
-   reply-with-note-and-resolve.
+   Per-thread handling lives in the `pr-fix-protocol` skill's
+   unresolved-thread sweep (`../../pr-fix-protocol/SKILL.md`).
 
 c. Decide (four branches; match first whose predicate holds):
    - **No bugbot review yet, OR latest review's `commit_id` ≠
@@ -206,15 +203,12 @@ c. Decide (four branches; match first whose predicate holds):
      in same tick — back-to-back convergence requires code-review then
      bugteam on same HEAD before next wakeup.
    - **`commit_id == current_head` with unaddressed inline findings:**
-     Apply **Fix protocol**. Reset `inline_lag_streak = 0`. With
-     `state.json`: clean-coder teammate pushes, replies inline, writes
-     `state.json`, goes idle; Step 3 on new HEAD runs after via
-     orchestrator-spawned follow-up agent (§Fix result → general-purpose).
-     No `state.json` (single-PR): 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).
-     Schedule next wakeup, return.
+     Apply the `pr-fix-protocol` skill (`../../pr-fix-protocol/SKILL.md`).
+     Reset `inline_lag_streak = 0`. With `state.json`: the clean-coder
+     teammate executes it, writes `state.json`, goes idle; Step 3 on new
+     HEAD runs after via orchestrator-spawned follow-up agent (§Fix result
+     → general-purpose). No `state.json` (single-PR): the lead executes it
+     → Step 3 in same tick. Schedule next wakeup, return.
 
 ### `phase == CODE_REVIEW`
 
@@ -245,8 +239,8 @@ a. Run Claude Code's built-in `/code-review --fix` on the FULL
 b. Decide (two branches; match first whose predicate holds):
 
    - **`/code-review` applied fixes (working tree changed):** Commit the
-     applied fixes in one commit → push, following [Single-PR fix
-     workflow](fix-protocol.md#single-pr-fix-workflow). Reset
+     applied fixes in one commit → push, following the `pr-fix-protocol`
+     skill's commit and push steps (`../../pr-fix-protocol/SKILL.md`). Reset
      `bugbot_clean_at = null` AND `code_review_clean_at = null`. Re-trigger
      bugbot (Step 3) so the new HEAD enters the queue. Set `phase = BUGBOT`,
      schedule next wakeup, return. A code-review fix push requires a full
@@ -318,7 +312,8 @@ never falsely terminates:
      **omit loop pacing** per **Convergence** of active pacing workflow.
    - **Convergence BUT `bugbot_clean_at != current_head` (no push):**
      `phase = BUGBOT`, schedule next wakeup, return.
-   - **Findings without committed fixes:** spawn Agent (subagent_type: clean-coder) to implement fixes and push, then reply inline via `python ~/.claude/skills/pr-converge/scripts/post_fix_reply.py`, following [Single-PR fix workflow](fix-protocol.md#single-pr-fix-workflow).
+   - **Findings without committed fixes:** apply the `pr-fix-protocol`
+     skill (`../../pr-fix-protocol/SKILL.md`).
      `phase = BUGBOT`, schedule next wakeup, return.
 
 ### `phase == COPILOT_WAIT`
@@ -345,11 +340,9 @@ b. Decide (three branches; match first whose predicate holds):
      `phase = BUGTEAM`. Continue to convergence-gates.md gate (b) in same
      tick — back-to-back convergence requires all gates on same HEAD.
    - **Copilot review dirty (CHANGES_REQUESTED or COMMENTED with findings)
-     at `current_head`:** Apply **Fix protocol** — 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`. For body-only
-     findings (no inline threads), post top-level review reply citing new
-     HEAD SHA. Reset
+     at `current_head`:** Apply the `pr-fix-protocol` skill
+     (`../../pr-fix-protocol/SKILL.md`) — it covers body-only findings with
+     no inline threads. Reset
      `bugbot_clean_at = null` AND `copilot_clean_at = null`. **Set
      `phase = BUGBOT`** (NOT COPILOT_WAIT) — every fix push requires a full
      back-to-back-clean cycle on the new HEAD. Schedule next wakeup, return.
@@ -370,29 +363,15 @@ BUGBOT.
 - [ ] **Opt-out gate.** Enforced at BUGBOT entry (see `### phase == BUGBOT`).
   When `CLAUDE_REVIEWS_DISABLED` lists `bugbot`, the entry gate sets
   `bugbot_down = true` and routes to BUGTEAM before any trigger flow runs,
-  so the checks below are skipped.
-- [ ] **Silent-pass pre-check.** Run `python ~/.claude/skills/pr-converge/scripts/check_bugbot_ci.py --check-clean --owner <O> --repo <R> --sha <current_head>`
-- [ ] Exit 0 → bugbot CI completed clean with no review (silent pass); set `bugbot_clean_at = current_head`, `phase = CODE_REVIEW`, continue CODE_REVIEW same tick
-- [ ] Exit 1 (not a silent pass) or Exit 2 (gh CLI error — silent pass not confirmable) → continue with the trigger flow below
-- [ ] Run `python ~/.claude/skills/pr-converge/scripts/check_bugbot_ci.py --check-active --owner <O> --repo <R> --sha <current_head>`
-- [ ] Exit 0 → bugbot already queued on this commit; skip posting, wait for completion
-- [ ] Exit 1 → post trigger via `add_issue_comment(owner="OWNER", repo="REPO", issueNumber=NUMBER, body="bugbot run")`
-- [ ] Wait 8s
-- [ ] Run `python ~/.claude/skills/pr-converge/scripts/check_bugbot_ci.py --owner <O> --repo <R> --sha <current_head>`
-- [ ] Exit non-zero → bugbot is down; set `bugbot_down = true`, `phase = CODE_REVIEW`, continue CODE_REVIEW same tick
-- [ ] Exit 0 (check run present) → record `bugbot_acknowledged_at = <now ISO 8601>`, proceed to Step 4
-
-The silent-pass pre-check fires FIRST so we never re-trigger a bot that
-already finished cleanly. Cursor Bugbot communicates "no findings" by
-completing the CI check with `conclusion: success` (or `neutral`) and
-posting no review. The pre-check treats that outcome as
-`bugbot_clean_at = current_head`, equivalent to an explicit clean
-review. Without it, the trigger flow would re-prompt a bot that has
-already evaluated this commit and refuses to re-run, and the bypass
-branch would falsely mark `bugbot_down = true`.
-
-`bugbot run` is empirically the only re-trigger Cursor Bugbot recognizes;
-alternative phrasings silently no-op.
+  so the flow below is skipped.
+- [ ] Apply the `reviewer-gates` skill's Bugbot flow
+  (`../../reviewer-gates/SKILL.md` § Gate 3) against `current_head` — the
+  silent-pass pre-check, the already-queued check, the trigger comment, and
+  the acknowledge check, with their rationale. Map its outcomes:
+- [ ] Silent pass → set `bugbot_clean_at = current_head`, `phase = CODE_REVIEW`, continue CODE_REVIEW same tick
+- [ ] Already queued → skip posting, wait for completion, advance to Step 4
+- [ ] Trigger acknowledged (`bugbot_acknowledged_at` recorded) → advance to Step 4
+- [ ] Bugbot down → set `bugbot_down = true`, `phase = CODE_REVIEW`, continue CODE_REVIEW same tick
 
 ## Step 4: Loop pacing
 

package/skills/pr-converge/reference/state-schema.md

@@ -79,6 +79,21 @@ live ONLY in the single-PR `$CLAUDE_JOB_DIR/pr-converge-state.json` file
   The enforcer requires this value to equal the current `tick_count` so a
   Skill invocation from a prior tick cannot wave through clean-coder
   audit-shaped Agent spawns on a later tick at the same HEAD.
+- `agents_session_id`: string or `null`, init `null`. The session id that
+  spawned the persistent per-step agents recorded in `persistent_agents`.
+  On tick entry, compare it to the current session id: when they differ,
+  clear `persistent_agents` to `{}` and stamp this field with the current
+  session id. `ScheduleWakeup` re-enters the same session, so a mismatch
+  means a fresh-session manual resume — the stored agent ids point at dead
+  agents and must not be reused.
+- `persistent_agents`: object, init `{}`. Map of step-key →
+  `{agent_id, created_tick, last_used_tick}` for the persistent per-step
+  agents the loop resumes across ticks. Exactly three step keys:
+  `fix_executor` (the clean-coder that applies findings in Step 4 dirty,
+  Step 6 findings, gates (a)/(d), and Step 7a), `thread_sweep`, and
+  `copilot_watch`. `agent_id` is the id the `Agent` tool returned at spawn;
+  `created_tick` is the `tick_count` at spawn; `last_used_tick` is bumped
+  on every `SendMessage` resume.
 
 Single-PR tick begins by reading `$CLAUDE_JOB_DIR/pr-converge-state.json`
 if it exists and ends by writing the updated state back to that same file

package/skills/pr-converge/scripts/README.md

@@ -79,15 +79,13 @@ non-empty body → dirty.
 
 ### Inline comment threads: `pull_request_read(method="get_review_comments")`
 
-Fetch via MCP. The convergence gate filters ONLY on resolution state:
+Fetch via MCP:
 
     pull_request_read(method="get_review_comments", pullNumber=NUMBER, owner=OWNER, repo=REPO)
       → filter threads where `is_resolved == false`
 
-The fields `comment.author`, `comment.commit.oid`, and `is_outdated`
-remain useful for **deciding how to address** each unresolved thread
-(re-fix? reply-with-note?), but they do not exclude a thread from the
-count.
+Sweep semantics and per-thread handling live in the `pr-fix-protocol`
+skill's unresolved-thread sweep (`../../pr-fix-protocol/SKILL.md`).
 
 ### Request Copilot review: `gh api` REST endpoint
 

package/skills/pr-fix-protocol/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: pr-fix-protocol
+description: >-
+  Applies reviewer findings to a PR as verified fixes and drives unresolved
+  review threads to zero: executor choice (clean-coder spawn or multi-PR
+  teammate with a worktree-path handoff), the shared 13-step fix sequence
+  (TDD, one commit, fast-forward push), an atomic reply-and-resolve per
+  thread, the unresolved-thread sweep hard gate (is_resolved == false is the
+  only filter), and post-push state resets. Invoked by PR-loop orchestrators
+  (pr-converge, autoconverge, bugteam, qbug, copilot-review) whenever a
+  reviewer reports findings or unresolved threads exist; not for ad-hoc "fix
+  this bug" requests outside a PR review loop.
+---
+
+# PR Fix Protocol
+
+**Core principle:** a finding is addressed only when the fix is pushed, the thread carries a reply, and the thread is resolved — as one unit of work. Anything less leaves a convergence gate stalled.
+
+## How callers invoke this
+
+- **Skill-capable contexts** (a lead session with the `Skill` tool): `Skill({skill: "pr-fix-protocol", args: "--skill <caller> --pr <URL> --worktree <path> [findings payload or 'sweep']"})`.
+- **Fallback** (a subagent or teammate without the `Skill` tool): the caller's spawn prompt says "Read `~/.claude/skills/pr-fix-protocol/SKILL.md` and apply it with the parameters below."
+
+The caller passes: its identity, the PR scope, the PR worktree path, this round's findings (or `sweep` for a thread sweep with no fresh findings), and its post-push obligations (which clean-SHA state fields to reset, which reviewers to re-trigger).
+
+## Executor choice
+
+- **Single-PR loops** (no shared `state.json`): the lead spawns `Agent(subagent_type: "clean-coder")` to write the fix. Full-stop if `Agent` is unavailable. 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.
+- **Multi-PR orchestration** (shared `state.json`): a per-PR clean-coder teammate owns edits, replies, and state writes; the orchestrator never edits inline. The teammate obligations (reply before writing state, state fields, idle handoff) live in the calling skill's multi-PR reference.
+
+Run every git command in the PR worktree — `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.
+
+## The fix sequence
+
+Follow the shared 13-step sequence in [`_shared/pr-loop/fix-protocol.md`](../../_shared/pr-loop/fix-protocol.md) exactly: read each file:line, capture the pre-fix SHA and contents, TDD where the finding has behavior, apply narrowly, `py_compile`, post-fix self-audit, stage by explicit path, one commit, fast-forward push, then reply + resolve atomically per thread. Its Constraints section (narrow scope, no `--no-verify`, preserve helpers) binds every executor.
+
+**Reply transport:** the GitHub MCP `add_reply_to_pull_request_comment` is primary. `python "$HOME/.claude/skills/pr-converge/scripts/post_fix_reply.py" --owner <O> --repo <R> --pr-number <N> --in-reply-to <COMMENT_ID> --body "Fixed in <SHA> — <what changed>"` is the fallback for script-only contexts and multi-PR teammates. Both carry the body shape from [`_shared/pr-loop/audit-reply-template.md`](../../_shared/pr-loop/audit-reply-template.md). For body-only findings with no inline thread, post a top-level review reply citing the new HEAD SHA.
+
+**Thread resolution:** `pull_request_review_write(method="resolve_thread", threadId=<PRRT node id>)` right after each reply. Harvest thread node ids (`PRRT_…`) from `get_review_comments` at fetch time.
+
+## The unresolved-thread sweep (hard gate)
+
+No caller advances a phase, records a clean SHA, or marks a PR ready while ANY unresolved review thread exists on the PR.
+
+```
+pull_request_read(method="get_review_comments") → filter threads where is_resolved == false
+```
+
+- The filter is purely `is_resolved == false`. Author, anchor commit, and `is_outdated` are all irrelevant to the count.
+- `is_outdated` is informational, not a skip flag: GitHub marks a thread outdated when its anchor line changed, but the concern can still apply to current HEAD (the fix may have moved, not landed). Verify each outdated thread against current HEAD like any other.
+- Per unresolved thread: verify the concern against current HEAD. The concern holds → fix (this protocol) → reply → resolve. The concern does not hold on current HEAD → reply-with-note explaining why → resolve.
+- Code changed during the sweep → push and hand control back to the caller's re-entry phase. Only resolutions, no code → re-run the sweep without resetting caller state.
+
+## Post-push obligations
+
+Every push through this protocol:
+
+1. Re-resolve `current_head` (`git rev-parse HEAD` locally; the PR `get` call for API-visible state).
+2. Reset the caller-named clean-SHA fields to null (`bugbot_clean_at`, `code_review_clean_at`, `copilot_clean_at` — whichever the caller tracks). A new HEAD invalidates every prior clean.
+3. Re-trigger reviewers per the caller's parameter (for Cursor Bugbot, the `reviewer-gates` Bugbot flow; for Copilot, the caller's request step). Audit-family callers (`bugteam`, `qbug`) skip re-triggering — their next loop iteration is the reviewer.
+
+## Gotchas
+
+- **Reply-then-resolve, atomic per thread.** Batching all replies before any resolves, or yielding to the orchestrator between the two, leaves threads half-addressed when a run dies mid-loop.
+- **An unchanged HEAD after step 11 means no commit landed** — exit `stuck — could not address findings` rather than reporting the findings as fixed.
+- **A resolved thread with no reply reads as dismissed.** Reviewers (and the humans reading the PR) need the one-paragraph explanation the template carries.
+
+## Folder map
+
+- `SKILL.md` — this file. The step sequence, reply template, and payload shapes live in `_shared/pr-loop/` (`fix-protocol.md`, `audit-reply-template.md`, `gh-payloads.md`); the reply fallback script lives in `pr-converge/scripts/`.

package/skills/pr-loop-lifecycle/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: pr-loop-lifecycle
+description: >-
+  Opens and closes a PR-loop run: the .claude/** permission grant (with the
+  auto-mode AskUserQuestion escalation when the classifier blocks it),
+  worktree preflight and cwd routing, then the ordered close — conditional
+  TeamDelete for team callers, worktree teardown, working-tree clean, PR
+  description rewrite via pr-description-writer, the always-run permission
+  revoke, and the caller-parameterized final report. Invoked by PR-loop
+  orchestrators (bugteam, pr-converge, autoconverge, qbug) at run start and
+  run end, including error exits; not for general git cleanup or permission
+  management outside a PR loop.
+---
+
+# PR Loop Lifecycle
+
+**Core principle:** a PR-loop run opens with an explicit, revocable permission grant and closes the same way every time — teardown, description rewrite, revoke, report — no matter how the run ended.
+
+## How callers invoke this
+
+- **Skill-capable contexts** (a lead session with the `Skill` tool): `Skill({skill: "pr-loop-lifecycle", args: "--skill <caller> <open|close> [parameters]"})`.
+- **Fallback** (a subagent or teammate without the `Skill` tool): the caller's spawn prompt says "Read `~/.claude/skills/pr-loop-lifecycle/SKILL.md` and apply the `<open|close>` section with the parameters below."
+
+The caller passes its identity (fills the final-report header and scratch-file prefix), whether it runs an agent team (gates the TeamDelete step), and at close time the run's exit reason, loop count, and SHAs.
+
+## Open
+
+1. **Grant project permissions:**
+   `python "$HOME/.claude/_shared/pr-loop/scripts/grant_project_claude_permissions.py"`
+   The script writes idempotent allow-rules and `additionalDirectories` entries into `~/.claude/settings.json` so subagents can edit the project's `.claude/` tree without prompting.
+
+   **Auto-mode escalation:** in an unattended run the permission classifier can block this grant as an unrequested allowlist change. Keep the run alive — surface the exact command to the user through `AskUserQuestion` and ask them to approve it or run it themselves with the `!` prefix. Continue once the grant lands. A user who wants future runs to skip the prompt can add a standing Bash allow-rule for the script in their settings.
+
+2. **Worktree preflight:** confirm the session is isolated (the working directory path includes `.claude/worktrees/`) before the first tick or round. Classify the working tree against the PR's repo with
+   `python "$HOME/.claude/skills/_shared/pr-loop/scripts/preflight_worktree.py" --owner <O> --repo <R> --mode <classify|strict>`
+   and route per the caller's cwd-routing reference (pr-converge Step 1.5 for the classify route; autoconverge pre-flight for the strict route). Capture the session worktree path before routing away — close-time steps target the session repo.
+
+## Close
+
+Run these in order from the lead session on EVERY exit — converged, cap reached, stuck, or error.
+
+1. **TeamDelete (team callers only).** Callers that created an agent team remove it with `TeamDelete`; single-agent and workflow callers skip this step.
+2. **Worktree teardown:**
+   ```bash
+   python "$HOME/.claude/skills/_shared/pr-loop/scripts/teardown_worktrees.py" \
+     --run-temp-dir "<run_temp_dir>" \
+     --all-pr-jsons '<json array of {number, owner, repo}>'
+   ```
+   Tolerates already-removed worktrees and missing directories; removal is Windows-safe per `~/.claude/rules/windows-filesystem-safe.md`.
+3. **Clean the working tree.** Return to the session worktree, remove run-scoped scratch files, and leave `git status` clean of run artifacts.
+4. **Rewrite the PR description.** Follow [`reference/teardown-publish-permissions.md` § Publish the final PR description](reference/teardown-publish-permissions.md): capture the cumulative diff and original body, brief the `pr-description-writer` agent, publish via `update_pull_request`, remove the scratch files. On failure, report it and continue — the revoke still runs.
+5. **Revoke project permissions (always):**
+   `python "$HOME/.claude/_shared/pr-loop/scripts/revoke_project_claude_permissions.py"`
+   Non-negotiable, including on error exits: leaving the grant in place lets future sessions inherit elevated `.claude/**` access without an explicit opt-in. Run revoke even when earlier close steps partially failed; log cleanup errors separately.
+6. **Final report.** Print the caller's report block verbatim — no paraphrase, no extra commentary:
+   ```
+   /<caller> exit: <converged | cap reached | stuck | error>
+   Loops: <loop_count>
+   Starting commit: <starting_sha7>
+   Final commit: <current_HEAD_sha7>
+   ```
+   Callers append their own lines (net change, loop log, converged SHAs) per their SKILL.md.
+
+## Gotchas
+
+- **Revoke runs on the error path too.** The single most common lifecycle defect is a run that dies mid-loop and leaves the `.claude/**` grant in settings.
+- **Close targets the session repo.** A cross-repo run that routed its cwd into the PR's worktree returns to the session worktree before steps 3–5; grant and revoke read the current working directory.
+- **TeamDelete fires once, at run end.** Removing the team between audit-fix iterations is a bug.
+
+## Folder map
+
+- `SKILL.md` — this file.
+- `reference/teardown-publish-permissions.md` — the full close sequence: utility-script homes, teardown, PR-description rewrite brief, revoke, report shape.

package/skills/{bugteam → pr-loop-lifecycle}/reference/teardown-publish-permissions.md

@@ -1,5 +1,7 @@
 # Utility scripts, teardown, PR body, permissions, report
 
+The ordered close sequence for a PR-loop run. `<caller>` is the invoking skill's name (`bugteam`, `pr-converge`, `autoconverge`, `qbug`); it prefixes scratch files and the final-report header.
+
 ## Utility scripts (progressive disclosure)
 
 Fragile or repeatable shell sequences live in one of two shared script directories. Match the reference depth to the directory:
@@ -7,17 +9,13 @@ Fragile or repeatable shell sequences live in one of two shared script directori
 - **Package-root** [`_shared/pr-loop/scripts/`](../../../_shared/pr-loop/scripts/) holds `code_rules_gate.py`, `preflight.py`, `post_audit_thread.py`, and the permission helpers. Reference it as `../../../_shared/…` in markdown and `${CLAUDE_SKILL_DIR}/../../_shared/…` at runtime (resolves to `~/.claude/_shared/`). Inventory: [`../../../_shared/pr-loop/scripts/README.md`](../../../_shared/pr-loop/scripts/README.md).
 - **Skill-tree** [`skills/_shared/pr-loop/scripts/`](../../_shared/pr-loop/scripts/) holds `teardown_worktrees.py`, `build_audit_prompt.py`, `build_fix_prompt.py`, `init_loop_state.py`, `write_audit_outcomes.py`, `write_fix_outcomes.py`, and `_path_resolver.py`. Reference it as `../../_shared/…` in markdown and `${CLAUDE_SKILL_DIR}/../_shared/…` at runtime (resolves to `~/.claude/skills/_shared/`).
 
-Bugteam-specific scripts (e.g. revoke, see Step 5) live in the skill-local [`scripts/`](../scripts/) directory. Anthropic: [Progressive disclosure patterns](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#progressive-disclosure-patterns) — utility scripts are **executed**, not loaded into context as primary reading. Bugteam-script inventory: [`../scripts/README.md`](../scripts/README.md). Gate-only merge-base / diff semantics: [`../../../_shared/pr-loop/code-rules-gate.md`](../../../_shared/pr-loop/code-rules-gate.md).
-
-### Pre-flight (recommended before Step 0)
-
-From the repository root, run the command in `SKILL.md`. If the exit code is non-zero, stop and fix failing checks before granting permissions. Optional: `BUGTEAM_PREFLIGHT_SKIP=1` skips pre-flight (emergency only). Optional: `--pre-commit` when `.pre-commit-config.yaml` exists.
+Caller-specific scripts live in the calling skill's own `scripts/` directory with their own README inventory. Anthropic: [Progressive disclosure patterns](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#progressive-disclosure-patterns) — utility scripts are **executed**, not loaded into context as primary reading. Gate-only merge-base / diff semantics: [`../../../_shared/pr-loop/code-rules-gate.md`](../../../_shared/pr-loop/code-rules-gate.md).
 
-## Step 4 — Clean working tree
+## Clean working tree
 
-When the cycle exits (any reason), run these steps in order from **this** session (the lead).
+When the run exits (any reason), run these steps in order from **this** session (the lead).
 
-1. **Delete the team:** `TeamDelete` removes `~/.claude/teams/bugteam/` and `~/.claude/tasks/bugteam/`. Only at convergence/cap/stuck — not between loops.
+1. **TeamDelete (team callers only):** a caller that created an agent team removes `~/.claude/teams/<caller>/` and `~/.claude/tasks/<caller>/` with `TeamDelete`. Only at convergence/cap/stuck — not between loops. Single-agent and workflow callers skip this step.
 
 2. Run [`teardown_worktrees.py`](../../_shared/pr-loop/scripts/teardown_worktrees.py)
    to remove each PR's worktree (`git worktree remove`) and the run temp
@@ -33,11 +31,11 @@ When the cycle exits (any reason), run these steps in order from **this** sessio
    `onexc`/`onerror` handler for Windows ReadOnly attribute safety
    (see `~/.claude/rules/windows-filesystem-safe.md`).
 
-## Step 4.5 — Finalize the PR description (mandatory)
+## Publish the final PR description (mandatory)
 
-After teardown and before permission revoke, the lead rewrites the PR body to the PR’s **final cumulative state** — what the change delivers, not the bugteam process. This is the **only** PR-write the lead performs (audit and fix comments stay with teammates).
+After teardown and before permission revoke, the lead rewrites the PR body to the PR's **final cumulative state** — what the change delivers, not the loop's process. This is the **only** PR-write the lead performs (audit and fix comments stay with the agents that produced them).
 
-The lead delegates body text to the `pr-description-writer` agent so the global mandatory-pr-description-writer hook accepts the subsequent `gh pr edit`. The lead does **not** compose the body inline.
+The lead delegates body text to the `pr-description-writer` agent so the global mandatory-pr-description-writer hook accepts the `gh pr edit` that follows. The lead does **not** compose the body inline.
 
 `pr-description-writer` comes from the global git-workflow rule in `claude-code-config`. Invoke with `Agent`:
 
@@ -50,37 +48,37 @@ Agent(
 )
 ```
 
-If that subagent is missing, fall back to `general-purpose` with the same brief — the hook treats agent-authored bodies the same. If neither exists, log a warning and skip Step 4.5.
+If that subagent is missing, fall back to `general-purpose` with the same brief — the hook treats agent-authored bodies the same. If neither exists, log a warning and skip this step.
 
 **Steps:**
 
-1. Capture cumulative diff: `pull_request_read(method="get_diff", pullNumber=N, owner=O, repo=R)` → write the response text to `.bugteam-final.diff` using the `Write` tool.
-2. Capture original body: `pull_request_read(method="get", pullNumber=N, owner=O, repo=R)` → extract `.body` from the response, write it to `.bugteam-original-body.md` using the `Write` tool.
+1. Capture cumulative diff: `pull_request_read(method="get_diff", pullNumber=N, owner=O, repo=R)` → write the response text to `.<caller>-final.diff` using the `Write` tool.
+2. Capture original body: `pull_request_read(method="get", pullNumber=N, owner=O, repo=R)` → extract `.body` from the response, write it to `.<caller>-original-body.md` using the `Write` tool.
 3. Agent brief:
    - **Inputs:** diff path, original body path, head branch, base branch.
    - **Constraint:** describe what the PR delivers from the cumulative diff — behavior, user-visible effect, merge rationale. Process metadata (loops, fix counts, findings) stays in review comments.
-   - **Preservation rule:** if the original body has manually curated sections (linked issues, screenshots, test plan, “Risk Assessment”, etc.), preserve them verbatim and only rewrite narrative around them.
+   - **Preservation rule:** if the original body has manually curated sections (linked issues, screenshots, test plan, "Risk Assessment", etc.), preserve them verbatim and only rewrite narrative around them.
    - **Output:** new body markdown.
-4. Write `.bugteam-final-body.md`.
-5. Publish the new body: `update_pull_request(pullNumber=N, owner=O, repo=R, body=<contents of .bugteam-final-body.md>)`.
-6. Delete `.bugteam-final.diff`, `.bugteam-original-body.md`, `.bugteam-final-body.md`.
+4. Write `.<caller>-final-body.md`.
+5. Publish the new body: `update_pull_request(pullNumber=N, owner=O, repo=R, body=<contents of .<caller>-final-body.md>)`.
+6. Remove `.<caller>-final.diff`, `.<caller>-original-body.md`, `.<caller>-final-body.md`.
 
-If Step 4.5 fails (agent error, hook block, network), report in the final report and continue to Step 5. The original PR body remains; commits and comments are unaffected.
+If this step fails (agent error, hook block, network), report in the final report and continue to the revoke. The original PR body remains; commits and comments are unaffected.
 
-## Step 5 — Revoke project permissions (mandatory, always)
+## Revoke project permissions (mandatory, always)
 
 After team cleanup — including on error, cap-reached, or stuck exits — run:
 
 ```bash
-python "${CLAUDE_SKILL_DIR}/scripts/revoke_project_claude_permissions.py"
+python "${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/revoke_project_claude_permissions.py"
 ```
 
-This removes allow rules and `additionalDirectories` added in Step 0. Revoke is non-negotiable: leaving the grant in place would let future sessions inherit elevated `.claude/**` access without an explicit opt-in. Run revoke even if Step 4 partially failed; log cleanup errors separately.
+This removes allow rules and `additionalDirectories` added at open. Revoke is non-negotiable: leaving the grant in place would let future sessions inherit elevated `.claude/**` access without an explicit opt-in. Run revoke even if teardown partially failed; log cleanup errors separately.
 
-## Step 6 — Final report
+## Final report
 
 ```
-/bugteam exit: <converged | cap reached | stuck | error>
+/<caller> exit: <converged | cap reached | stuck | error>
 Loops: <loop_count>
 Starting commit: <starting_sha7>
 Final commit: <current_HEAD_sha7>

package/skills/pr-scope-resolve/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: pr-scope-resolve
+description: >-
+  Resolves the audit/fix target for a PR-loop skill: owner, repo, PR number,
+  head ref, base ref, PR URL, and starting head SHA — via
+  pull_request_read(method="get"), a search_pull_requests branch fallback, then a
+  git merge-base upstream-diff fallback, ending in the canonical refusal line
+  when no target exists. Invoked by PR-loop orchestrators (pr-converge,
+  bugteam, qbug, findbugs, fixbugs) as their first step; not for general git
+  questions or branch management.
+---
+
+# PR Scope Resolve
+
+**Core principle:** every PR-loop skill agrees on what it is auditing before any other work. One resolution ladder, one refusal line.
+
+## How callers invoke this
+
+- **Skill-capable contexts** (a lead session with the `Skill` tool): `Skill({skill: "pr-scope-resolve", args: "--skill <caller> [PR URL if the user gave one]"})`.
+- **Fallback** (a subagent or teammate without the `Skill` tool): the caller's spawn prompt says "Read `~/.claude/skills/pr-scope-resolve/SKILL.md` and apply the resolution ladder with the parameters below."
+
+The caller identity fills the refusal template. The resolved scope hands back: `owner`, `repo`, `number`, `head_ref`, `base_ref`, `url`, and `head_sha` (the starting `current_head`).
+
+## The resolution ladder
+
+Match the first rung that holds:
+
+1. **A PR URL was given.** Extract `owner`, `repo`, and `number` from the URL, then `pull_request_read(method="get", pullNumber=N, owner=O, repo=R)` for `head.sha`, `head.ref`, `base.ref`, and draft state.
+2. **Open PR for the current branch.** Call `pull_request_read(method="get")` with the PR number from the caller's context. When the number is unknown, recover it with the `search_pull_requests` MCP tool using the current branch name, then fetch as in rung 1.
+3. **No PR, but a remote default branch exists.** The scope is the upstream diff: `git merge-base HEAD origin/<default>` then `git diff <merge-base>...HEAD`. `head_sha` is `git rev-parse HEAD`; there is no PR number or URL, and steps that post to a PR are skipped by the caller.
+4. **Neither.** Respond exactly with the refusal template and stop:
+
+   `No PR or upstream diff. /<caller> needs a target.`
+
+## Ground rules
+
+- **The GitHub MCP is the primary transport** (`pull_request_read`, `search_pull_requests`); raw `gh api` is the fallback. MCP calls behave the same from any worktree, so scope resolution never depends on the working directory.
+- **Re-resolve `head_sha` after any push or external wait.** The scope tuple (`owner`, `repo`, `number`) is stable for a run; the head SHA is not.
+- **Full-diff scope.** The resolved scope always means the full `origin/<base>...HEAD` diff — every file the PR touches. A caller that narrows to a file list, commit range, or flagged-path subset is out of contract with every convergence gate downstream.
+
+## Gotchas
+
+- **`search_pull_requests` recovers PR numbers from branch names**, but a branch reused across repos returns several hits — filter by repo before trusting the number.
+- **A draft-state read belongs to this step.** Callers that need a draft PR (convergence loops that mark ready at the end) check `isDraft` here, on the same `get` call, rather than paying a second fetch later.
+
+## Folder map
+
+- `SKILL.md` — this file; the ladder is MCP- and git-native, so the skill ships no scripts.

package/skills/qbug/CLAUDE.md

@@ -6,13 +6,13 @@ Quick baseline PR audit: one clean-coder subagent loops audit → fix → commit
 
 ## Purpose
 
-`/qbug` is the required baseline review for every new PR. It runs the same A–N bug category rubric and CODE_RULES gate as `/bugteam` but with a single persistent subagent (no TeamCreate, no per-loop clean-room, no loop cap). Escalate to `/bugteam` when bias isolation across loops matters.
+`/qbug` is the required baseline review for every new PR. It runs the same A–P bug category rubric and CODE_RULES gate as `/bugteam` but with a single persistent subagent (no TeamCreate, no per-loop clean-room, no loop cap). Escalate to `/bugteam` when bias isolation across loops matters.
 
 ## Key files
 
 | File | Purpose |
 |---|---|
-| `SKILL.md` | The complete skill — four steps (pre-flight, resolve PR scope, spawn subagent cycle, final report). Self-contained with full subagent XML prompt inline. |
+| `SKILL.md` | The complete skill — four steps (pre-flight, resolve PR scope via the `pr-scope-resolve` skill, spawn subagent cycle, final report). The subagent XML prompt is inline and points the embedded agent at the `post-audit-findings` and `pr-fix-protocol` skills for review posting and reply/resolve mechanics. |
 
 ## Shared artifacts (referenced by path, not copied)
 
@@ -25,7 +25,7 @@ The skill references shared scripts from `../_shared/pr-loop/scripts/`:
 | `post_audit_thread.py` | Posts one GitHub review per loop (APPROVE or REQUEST_CHANGES) |
 | `audit-reply-template.md` | Unified reply body shape for resolved threads |
 
-Bug category rubric A–N lives at `../bugteam/PROMPTS.md`. Audit contract (finding schema, proof-of-absence, Haiku secondary, self-audit) lives at `../bugteam/reference/audit-contract.md`.
+Bug category rubric A–P lives at `../bugteam/PROMPTS.md`. Audit contract (finding schema, proof-of-absence, Haiku secondary, self-audit) lives at `../../_shared/pr-loop/audit-contract.md`.
 
 ## Subagent structure
 
@@ -37,4 +37,4 @@ Bug category rubric A–N lives at `../bugteam/PROMPTS.md`. Audit contract (find
 
 - The lead resolves the temp directory via Python's `tempfile.gettempdir()` and passes the absolute path to the subagent.
 - Each loop: one `code_rules_gate.py` pre-audit, one GitHub review posted, one commit on fix.
-- Self-PR toggle: `post_audit_thread.py` detects author-equals-reviewer and switches to an alternate `gh` account automatically.
+- Self-PR toggle, findings-JSON mapping, and anchored-only serialization live in the `post-audit-findings` skill; reply-and-resolve mechanics live in the `pr-fix-protocol` skill.