claude-dev-env 1.93.1 → 1.95.0

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

@@ -1,5 +1,13 @@
 # Convergence gates
 
+## Contents
+
+- [(a) Copilot findings gate](#a-copilot-findings-gate)
+- [(b) Claude reviewer gate (agent-side)](#b-claude-reviewer-gate-agent-side)
+- [(c) Mergeability gate](#c-mergeability-gate)
+- [(d) Post-convergence Copilot review request](#d-post-convergence-copilot-review-request)
+- [(e) Thread-resolution gate](#e-thread-resolution-gate)
+- [(f) Mark ready and report](#f-mark-ready-and-report)
 Run **only** after the terminal Bugbot gate confirms the HEAD
 (`bugbot_clean_at == current_head` OR `bugbot_down`), which runs just before
 these gates once Step 2 BUGTEAM reports `convergence (zero findings)` with no
@@ -36,33 +44,34 @@ 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). Apply the `pr-fix-protocol` skill
-  (`../../pr-fix-protocol/SKILL.md`) in the same tick.
-  Reset `bugbot_clean_at = null`, `code_review_clean_at = null`, AND
-  `copilot_clean_at = null`, `phase = CODE_REVIEW`, schedule next wakeup,
-  return. Full back-to-back-clean cycle plus all six gates must hold again on
-  new HEAD.
+  dirty). Apply the shared fix protocol ([`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md); skill deltas in [`fix-protocol.md`](fix-protocol.md)) in the same tick.
+  Reset push-invalidated markers per [ground-rules.md](ground-rules.md) /
+  [state-schema.md](state-schema.md) (all `*_clean_at`, `merge_state_status`,
+  `bugbot_down`, `bugbot_acknowledged_at`), `phase = CODE_REVIEW`, 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. Apply the
-  `pr-fix-protocol` skill (`../../pr-fix-protocol/SKILL.md`), whose reply
+  shared fix protocol ([`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md); skill deltas in [`fix-protocol.md`](fix-protocol.md)), whose reply
   step for body-only findings posts a top-level review reply citing the
-  new HEAD SHA. Reset
-  `bugbot_clean_at = null`, `code_review_clean_at = null`, AND
-  `copilot_clean_at = null`, `phase = CODE_REVIEW`,
-  schedule next wakeup, return. Convergence needs full
-  back-to-back-clean on new HEAD.
+  new HEAD SHA. Reset push-invalidated markers per
+  [ground-rules.md](ground-rules.md) / [state-schema.md](state-schema.md)
+  (all `*_clean_at`, `merge_state_status`, `bugbot_down`,
+  `bugbot_acknowledged_at`), `phase = CODE_REVIEW`, 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>".
   Continue to gate (b).
 - **No Copilot review on `current_head` yet:** Record evidence: "No Copilot review at <SHA>".
   Skip — gate (d) issues proactive request. Continue to gate (b).
 
-## (b) Claude reviewer gate
+## (b) Claude reviewer gate (agent-side)
 
-Fetch latest Claude reviewer (`claude[bot]`) review plus inline comments
-anchored to most recent Claude review on `current_head`:
+Agent-side only — not a `check_convergence.py` condition. Fetch latest Claude
+reviewer (`claude[bot]`) review plus inline comments anchored to most recent
+Claude review on `current_head`:
 
 ```
 pull_request_read(owner=OWNER, repo=REPO, pullNumber=NUMBER, method="get_reviews")
@@ -78,17 +87,20 @@ 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 — apply the `pr-fix-protocol` skill
-  (`../../pr-fix-protocol/SKILL.md`). Reset
-  `bugbot_clean_at = null` AND `copilot_clean_at = null`, `phase = CODE_REVIEW`,
-  schedule next wakeup, return.
+  path — apply the shared fix protocol ([`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md); skill deltas in [`fix-protocol.md`](fix-protocol.md)). Reset push-invalidated markers per
+  [ground-rules.md](ground-rules.md) / [state-schema.md](state-schema.md)
+  (all `*_clean_at`, `merge_state_status`, `bugbot_down`,
+  `bugbot_acknowledged_at`), `phase = CODE_REVIEW`, 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 — apply the
-  `pr-fix-protocol` skill (`../../pr-fix-protocol/SKILL.md`). Reset
-  `bugbot_clean_at = null` AND `copilot_clean_at = null`, `phase = CODE_REVIEW`,
-  schedule next wakeup, return.
+  shared fix protocol ([`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md); skill deltas in [`fix-protocol.md`](fix-protocol.md)). Reset
+  push-invalidated markers per [ground-rules.md](ground-rules.md) /
+  [state-schema.md](state-schema.md) (all `*_clean_at`, `merge_state_status`,
+  `bugbot_down`, `bugbot_acknowledged_at`), `phase = CODE_REVIEW`, schedule
+  next wakeup, return.
 - **`classification == "clean"` (state `APPROVED`):** Record evidence:
   "Claude APPROVED at <SHA>". Continue to gate (c).
 - **No Claude review on `current_head` yet:** Record evidence:
@@ -112,11 +124,11 @@ Persist `mergeable_state` into `merge_state_status`. Decide:
   **not** mark ready. Invoke **`rebase`** skill
   ([`../../rebase/SKILL.md`](../../rebase/SKILL.md)) Phase 1–4 against PR's
   base ref. After rebase + force-with-lease push, new HEAD invalidates
-  every prior clean state — reset `bugbot_clean_at = null`,
-  `code_review_clean_at = null`, `copilot_clean_at = null`,
-  `merge_state_status = null`, `phase = CODE_REVIEW`,
-  schedule next wakeup, return. Loop re-runs from
-  scratch on new HEAD.
+  every prior clean state — reset push-invalidated markers per
+  [ground-rules.md](ground-rules.md) / [state-schema.md](state-schema.md)
+  (all `*_clean_at`, `merge_state_status`, `bugbot_down`,
+  `bugbot_acknowledged_at`), `phase = CODE_REVIEW`, schedule next wakeup,
+  return. Loop re-runs from scratch on new HEAD.
 - **`mergeable_state` is `"blocked"`, `"behind"`, `"unknown"`, or `"unstable"` for
   non-conflict reasons** (required checks pending/failing for "unstable",
   branch behind base without conflicts for "behind", GitHub indeterminate
@@ -155,12 +167,14 @@ against `current_head`. Decide:
   - `state: APPROVED` → set `copilot_clean_at = current_head`. Record
     evidence: "Copilot APPROVED at <SHA>". Re-validate gates (b) and (c)
     on same tick (Claude status and mergeability may have changed while
-    waiting). Set `phase = BUGTEAM`.
+    waiting). Stay on `COPILOT_WAIT` — do not re-enter BUGTEAM.
     Continue to gate (e) when (b) and (c) still pass.
   - `state: CHANGES_REQUESTED` or `COMMENTED` with non-empty body → dirty.
-    Treat identically to gate (a) dirty path — spawn Agent (subagent_type: clean-coder) to fix,
-    reset `bugbot_clean_at = null` AND `copilot_clean_at = null`,
-    `phase = CODE_REVIEW`, schedule next wakeup, return.
+    Treat identically to gate (a) dirty path — apply the shared fix protocol ([`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md); skill deltas in [`fix-protocol.md`](fix-protocol.md)).
+    Reset push-invalidated markers per [ground-rules.md](ground-rules.md) /
+    [state-schema.md](state-schema.md) (all `*_clean_at`, `merge_state_status`,
+    `bugbot_down`, `bugbot_acknowledged_at`), `phase = CODE_REVIEW`, schedule
+    next wakeup, return.
 - **No Copilot review at `current_head` yet:** Record evidence: "No Copilot
   review at <SHA> (wait count: <N>)". Increment `copilot_wait_count`
   (init 0 on first COPILOT_WAIT entry; reset to 0 on every push and on every
@@ -171,48 +185,72 @@ against `current_head`. Decide:
 
 ## (e) Thread-resolution gate
 
-Before marking ready, count ALL unresolved review threads on the PR:
+Agent-side prep before the machine checklist in gate (f). The script label
+`zero unresolved bot threads` is what marks ready; this gate clears those
+threads first.
 
-```
-pull_request_read(owner=OWNER, repo=REPO, pullNumber=NUMBER, method="get_review_comments")
-  → filter threads where `is_resolved == false`
-  → count
-```
+Machine filter (same as `check_convergence.py`):
 
-This count is the `pr-fix-protocol` unresolved-thread sweep
-(`../../pr-fix-protocol/SKILL.md`).
+- `isResolved == false`
+- `isOutdated == true` → thread **excluded** (does not fail the gate)
+- first-comment author login contains `cursor`, `claude`, or `copilot`
+  (case-insensitive substrings only)
+
+Broader unresolved-thread sweeps (all authors, including human reviewers) are
+agent-side via the shared fix protocol ([`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md); skill deltas in [`fix-protocol.md`](fix-protocol.md)) and are not script conditions.
 
 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. 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 = CODE_REVIEW`, schedule next wakeup, return. If only resolutions
-  (no code changes), re-check this gate without resetting.
+- **Zero unresolved bot threads** under the filter above: Record evidence:
+  "0 unresolved bot threads at <SHA>". Continue to gate (f).
+- **One or more unresolved bot threads:** Do **not** mark ready. Apply the
+  shared fix protocol unresolved-thread sweep ([`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md) step 12; skill deltas in [`fix-protocol.md`](fix-protocol.md)). Push if any code changed → reset
+  push-invalidated markers per [ground-rules.md](ground-rules.md) /
+  [state-schema.md](state-schema.md) (all `*_clean_at`, `merge_state_status`,
+  `bugbot_down`, `bugbot_acknowledged_at`), `phase = CODE_REVIEW`, schedule
+  next wakeup, return. If only resolutions (no code changes), re-check this
+  gate without resetting.
 
 ## (f) Mark ready and report
 
-**Mandatory pre-condition checklist.** Before calling `update_pull_request`,
-verify ALL seven conditions below. Three are preconditions from the main
-loop (bugbot clean, bugteam convergence, no intervening push); four are
-evidence from gates (a)–(e) above. All seven must be confirmed:
+**Machine pre-condition checklist.** Run the script — do not hand-check labels:
+
+```
+python $HOME/.claude/skills/pr-converge/scripts/check_convergence.py \
+  --owner <O> --repo <R> --pr-number <N> \
+  [--bugbot-down] [--copilot-down]
+```
+
+Ready means exit `0` and the line:
+
+```
+All pre-conditions met — PR is ready to mark ready.
+```
+
+Exact printed labels (script order):
+
+1. `bugbot_clean_at == current_head`
+2. `bugbot review body clean` (omitted when `bugbot_down`)
+3. `bugteam_clean_at == current_head`
+4. `copilot_clean_at == current_head`
+5. `zero unresolved bot threads`
+6. `PR is mergeable`
+7. `no pending requested reviews`
+
+On label 5: `isOutdated == true` excludes the thread; bot filter is login
+substrings `cursor` | `claude` | `copilot` only. The script has no Claude
+APPROVED review gate.
 
-- [ ] `bugbot_clean_at == current_head` (from per-tick.md Step 2 BUGBOT §c)
-- [ ] bugteam `convergence (zero findings)` at `current_head` (from per-tick.md Step 2 BUGTEAM §d)
-- [ ] `copilot_clean_at == current_head` (from gate (a) or gate (d)), or the Copilot gate bypassed for the run via `copilot_down`
-- [ ] Claude `APPROVED` or absent at `current_head` (from gate (b))
-- [ ] `mergeable_state == "clean"` AND `mergeable == true` (from gate (c))
-- [ ] Zero unresolved review threads anywhere on the PR (from gate (e))
-- [ ] No push since bugteam convergence (from per-tick.md Step 2 BUGTEAM §b)
+**Agent-side only (not script conditions):** Claude reviewer presence or
+APPROVED state (gate (b)); broader non-bot thread sweeps; loop preconditions
+such as no push since bugteam convergence. Confirm those in the agent path
+before invoking the script; they never appear as `check_convergence.py` labels.
 
-If ANY checkbox cannot be confirmed with evidence, do NOT mark ready.
-Report the specific missing condition and route through the appropriate
-fix path (BUGBOT for dirty reviews, rebase for merge conflicts, etc.).
+When the script fails (exit 1), do NOT mark ready. Report the FAIL label and
+route through the matching fix path (BUGBOT for dirty reviews, rebase for
+merge conflicts, and so on).
 
-Only when ALL seven conditions are confirmed:
+When the script passes (exit 0):
 
 Use the `update_pull_request` MCP tool:
 
@@ -220,7 +258,5 @@ Use the `update_pull_request` MCP tool:
 
 With `state.json`, append convergence row to
 `<TMPDIR>/pr-converge-<session_id>/converged.log` per `multi-pr-orchestration.md` §Memory; else skip.
-Report: `PR #<NUMBER> converged: bugbot CLEAN at <SHA>, bugteam CLEAN at
-<SHA>, mergeable_state clean, copilot CLEAN at <SHA>, claude <APPROVED|absent>
-at <SHA>, 0 unresolved threads across PR; marked ready for review`.
-**Omit loop pacing** per **Convergence** of active pacing workflow.
+Report from the script's PASS lines (the seven labels above). **Omit loop
+pacing** per **Convergence** of active pacing workflow.

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

@@ -12,14 +12,18 @@ stop]
 
 <example> CODE_REVIEW tick (the entry phase), the static sweep raises a
 `ruff` failure on a changed file. Claude: [fixes it TDD, one commit, pushes,
-resets `bugbot_clean_at = null` and `code_review_clean_at = null`, stays
-`phase = CODE_REVIEW`, Step 4 at 270s, re-runs the sweep next tick]
+resets push-invalidated markers per [ground-rules.md](ground-rules.md) /
+[state-schema.md](state-schema.md) (all `*_clean_at`, `merge_state_status`,
+`bugbot_down`, `bugbot_acknowledged_at`), stays `phase = CODE_REVIEW`, Step 4
+at 270s, re-runs the sweep next tick]
 </example>
 
 <example> CODE_REVIEW tick, static sweep clean, `/code-review high --fix`
 applies fixes to the working tree. Claude: [commits the applied fixes in one
-commit, pushes, resets `bugbot_clean_at = null` and `code_review_clean_at =
-null`, stays `phase = CODE_REVIEW`, Step 4 at 270s, returns]
+commit, pushes, resets push-invalidated markers per
+[ground-rules.md](ground-rules.md) / [state-schema.md](state-schema.md) (all
+`*_clean_at`, `merge_state_status`, `bugbot_down`, `bugbot_acknowledged_at`),
+stays `phase = CODE_REVIEW`, Step 4 at 270s, returns]
 </example>
 
 <example> CODE_REVIEW tick, static sweep clean and `/code-review high --fix`
@@ -28,14 +32,17 @@ clean (no changes applied). Claude: [sets `code_review_clean_at = HEAD`,
 </example>
 
 <example> BUGTEAM phase, bugteam pushed a fix commit during its run. Claude:
-[re-resolves HEAD, resets `bugbot_clean_at = null` and `code_review_clean_at =
-null`, `phase = CODE_REVIEW`, Step 4 at 270s, re-enters the internal passes on
-the new HEAD]
+[re-resolves HEAD, resets push-invalidated markers per
+[ground-rules.md](ground-rules.md) / [state-schema.md](state-schema.md) (all
+`*_clean_at`, `merge_state_status`, `bugbot_down`, `bugbot_acknowledged_at`),
+`phase = CODE_REVIEW`, Step 4 at 270s, re-enters the internal passes on the
+new HEAD]
 </example>
 
 <example> BUGTEAM phase, bugteam reports convergence with no push. Claude:
-[the internal passes are clean on `current_head`; `phase = BUGBOT` — routes into
-the terminal Bugbot gate in the same tick]
+[the internal passes are clean on `current_head`; stamps `bugteam_clean_at =
+current_head`, then `phase = BUGBOT` — routes into the terminal Bugbot gate in
+the same tick]
 </example>
 
 <example> Terminal BUGBOT gate, Bugbot disabled for the run (the default).
@@ -51,8 +58,10 @@ the same tick]
 
 <example> Terminal BUGBOT gate, Bugbot has 2 unaddressed findings on HEAD.
 Claude: [TDD-fixes both, one commit, pushes, replies inline on both threads,
-resets `bugbot_clean_at = null` and `code_review_clean_at = null`, `phase =
-CODE_REVIEW`, Step 4 at 270s, re-enters the internal passes on the new HEAD]
+resets push-invalidated markers per [ground-rules.md](ground-rules.md) /
+[state-schema.md](state-schema.md) (all `*_clean_at`, `merge_state_status`,
+`bugbot_down`, `bugbot_acknowledged_at`), `phase = CODE_REVIEW`, Step 4 at
+270s, re-enters the internal passes on the new HEAD]
 </example>
 
 <example> Convergence gates after the terminal Bugbot gate confirms
@@ -74,8 +83,7 @@ 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>", re-validate gates (b) and (c).
-  Gate (e): the `pr-fix-protocol` unresolved-thread sweep
-    (`../../pr-fix-protocol/SKILL.md`) → zero across PR → record evidence.
+  Gate (e): the shared fix protocol unresolved-thread sweep ([`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md) step 12; skill deltas in [`fix-protocol.md`](fix-protocol.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>,
@@ -93,17 +101,20 @@ HEAD`, `phase = BUGTEAM`]
 <example> Convergence gates reached, but `mergeStateStatus: DIRTY` (base
 advanced, merge conflicts). Claude: [runs §Convergence gate (c); does NOT
 mark ready; invokes `rebase` skill per `../../rebase/SKILL.md` Phase 1–4;
-after force-with-lease push, resets `bugbot_clean_at = null`,
-`code_review_clean_at = null`, `copilot_clean_at = null`, `merge_state_status
-= null`, `phase = CODE_REVIEW`, schedules next wakeup]
+after force-with-lease push, resets push-invalidated markers per
+[ground-rules.md](ground-rules.md) / [state-schema.md](state-schema.md) (all
+`*_clean_at`, `merge_state_status`, `bugbot_down`, `bugbot_acknowledged_at`),
+`phase = CODE_REVIEW`, schedules next wakeup]
 </example>
 
 <example> Convergence gates reached, mergeability CLEAN, Copilot review at
 `current_head` `state == "CHANGES_REQUESTED"` with two unaddressed inline
 findings. Claude: [runs §Convergence gates (a); applies Fix protocol (TDD
-test → fix → push → reply inline both threads), resets `bugbot_clean_at`,
-`code_review_clean_at`, and `copilot_clean_at` null, `phase = CODE_REVIEW`,
-schedules next wakeup, re-enters the internal passes on the new HEAD]
+test → fix → push → reply inline both threads), resets push-invalidated
+markers per [ground-rules.md](ground-rules.md) /
+[state-schema.md](state-schema.md) (all `*_clean_at`, `merge_state_status`,
+`bugbot_down`, `bugbot_acknowledged_at`), `phase = CODE_REVIEW`, schedules
+next wakeup, re-enters the internal passes on the new HEAD]
 </example>
 
 <example> Convergence gates reached, mergeability CLEAN, no Copilot review on
@@ -114,7 +125,7 @@ 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>";
 re-validates gates (b) Claude absent and (c) mergeability clean,
-records evidence for both; gate (e) — the `pr-fix-protocol`
+records evidence for both; gate (e) — the shared fix protocol
 unresolved-thread sweep — passes trivially, record evidence:
 "0 unresolved threads across PR at <SHA>";
 runs `update_pull_request(pullNumber=NUMBER,
@@ -127,9 +138,10 @@ at <SHA>, bugteam CLEAN at <SHA>, mergeable_state clean, copilot CLEAN at
 Copilot review returned `state: CHANGES_REQUESTED` with inline findings on
 `current_head`. Claude: [does NOT mark PR ready — gate (d) failed;
 applies Fix protocol on every confirmed Copilot finding (TDD test → fix →
-push → reply inline on each thread); resets `bugbot_clean_at = null`,
-`code_review_clean_at = null`, and `copilot_clean_at = null`; `phase =
-CODE_REVIEW`; schedules next wakeup, re-enters the internal passes on the new
-HEAD. Full back-to-back-clean cycle plus all six gates must hold again on new
-HEAD.]
+push → reply inline on each thread); resets push-invalidated markers per
+[ground-rules.md](ground-rules.md) / [state-schema.md](state-schema.md) (all
+`*_clean_at`, `merge_state_status`, `bugbot_down`, `bugbot_acknowledged_at`);
+`phase = CODE_REVIEW`; schedules next wakeup, re-enters the internal passes
+on the new HEAD. Full back-to-back-clean cycle plus all six gates must hold
+again on new HEAD.]
 </example>

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

@@ -1,11 +1,9 @@
 # Fix protocol
 
-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).
+Open and apply the shared fix sequence in
+[`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md)
+— executor choice, the 13-step sequence, reply transport, thread resolution,
+and post-push resets. 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-entry rule.
@@ -17,7 +15,9 @@ obligations and the same-tick re-entry rule.
   (what changed + commit identifier), matching §Audit result → fix worker step 4 — **before** writing
   `state.json` and going idle.
 - Writes `last_action: "fix_pushed"`, `current_head: <new SHA>`,
-  `bugbot_clean_at: null`, `code_review_clean_at: null`, `bugbot_down: false`,
+  `bugbot_clean_at: null`, `code_review_clean_at: null`,
+  `bugteam_clean_at: null`, `copilot_clean_at: null`,
+  `merge_state_status: null`, `bugbot_down: false`,
   `phase: "CODE_REVIEW"`, `status: "awaiting_code_review"`, `last_updated`
   (ISO-8601 UTC) to `state.json` (per §Concurrency).
 - Goes idle. Orchestrator spawns a follow-up `general-purpose` agent for the

package/skills/pr-converge/reference/multi-pr-orchestration.md

@@ -41,6 +41,10 @@ Create once at session start. Each teammate writes result before going idle.
       "phase": "BUGBOT",
       "current_head": "f9a7d49e",
       "bugbot_clean_at": null,
+      "code_review_clean_at": null,
+      "bugteam_clean_at": null,
+      "copilot_clean_at": null,
+      "merge_state_status": null,
       "inline_lag_streak": 0,
       "bugbot_down": false,
       "tick_count": 5,
@@ -52,8 +56,8 @@ Create once at session start. Each teammate writes result before going idle.
 }
 ```
 
-**`status` values:** `fresh` | `in_progress` | `awaiting_bugbot` |
-`awaiting_bugteam` | `converged` | `blocked`
+**`status` values:** `fresh` | `in_progress` | `awaiting_code_review` |
+`awaiting_bugbot` | `awaiting_bugteam` | `converged` | `blocked`
 
 **Write rule:** Subagents read current file, merge **only** their PR's entry
 under `prs`, write back. Writes keyed on `pr_number`; other PRs untouched.
@@ -112,8 +116,10 @@ Bugfind subagent completes (findings or clean):
      `add_reply_to_pull_request_comment(owner, repo, pullNumber, commentId, body)`.
   5. Writes `state.json` (per §Concurrency): `last_action: "fix_pushed"`,
      `current_head: <new SHA>`, `bugbot_clean_at: null`,
-     `bugbot_down: false`, `phase:
-     "BUGBOT"`, `status: "awaiting_bugbot"`, `last_updated` ISO-8601 UTC.
+     `code_review_clean_at: null`, `bugteam_clean_at: null`,
+     `copilot_clean_at: null`, `merge_state_status: null`,
+     `bugbot_down: false`, `phase: "CODE_REVIEW"`,
+     `status: "awaiting_code_review"`, `last_updated` ISO-8601 UTC.
   6. Goes idle.
 
 - **PRs with zero findings:** spawn one `general-purpose` subagent per PR via

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

@@ -1,5 +1,16 @@
 # Per-tick work
 
+## Contents
+
+- [Invocation modes](#invocation-modes)
+- [Pacing workflow](#pacing-workflow)
+- [Step 1: Resolve current HEAD and PR context](#step-1-resolve-current-head-and-pr-context)
+- [Step 1.5: Resolve the PR worktree (cwd routing)](#step-15-resolve-the-pr-worktree-cwd-routing)
+- [Step 2: Branch on phase](#step-2-branch-on-phase)
+- [Step 3: Re-trigger bugbot](#step-3-re-trigger-bugbot)
+- [Step 4: Loop pacing](#step-4-loop-pacing)
+- [Bugteam execution](#bugteam-execution)
+
 Use on **draft PR**. Cursor Bugbot and `/bugteam` re-run after each push. Fix
 findings between rounds until back-to-back clean on same `HEAD`, then mark
 PR ready for review.
@@ -40,8 +51,10 @@ pull_request_read(owner=OWNER, repo=REPO, pullNumber=NUMBER, method="get") → `
 ```
 
 If owner/repo/number are not yet known, extract them from the PR URL.
-If `current_head` changed since last tick, reset `bugbot_down` to `false`
-(new HEAD invalidates prior down-detection state).
+If `current_head` changed since last tick, reset push-invalidated markers
+per [ground-rules.md](ground-rules.md) / [state-schema.md](state-schema.md)
+(all `*_clean_at`, `merge_state_status`, `bugbot_down`, `bugbot_acknowledged_at`) —
+new HEAD invalidates prior clean and down-detection state.
 
 Capture `number`, `head.sha` (= `current_head`), owner/repo, branch.
 
@@ -166,10 +179,11 @@ a. **Static sweep — runs first, before `/code-review`.** Run the deterministic
    gates over the full `origin/main...HEAD` changed files:
    `python "$HOME/.claude/_shared/pr-loop/scripts/code_rules_gate.py" --base origin/main`,
    `ruff`, `mypy`, and stem-matched `pytest`. On any failure, apply the
-   `pr-fix-protocol` skill (`../../pr-fix-protocol/SKILL.md`), commit and push,
-   reset `bugbot_clean_at = null` and `code_review_clean_at = null`, stay
-   `phase = CODE_REVIEW`, and re-run the sweep. When the sweep is clean, run
-   `/code-review` below.
+   shared fix protocol ([`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md); skill deltas in [`fix-protocol.md`](fix-protocol.md)), commit and push,
+   reset push-invalidated markers per [ground-rules.md](ground-rules.md) /
+   [state-schema.md](state-schema.md) (all `*_clean_at`, `merge_state_status`,
+   `bugbot_down`, `bugbot_acknowledged_at`), stay `phase = CODE_REVIEW`, and
+   re-run the sweep. When the sweep is clean, run `/code-review` below.
 
 b. Run Claude Code's built-in `/code-review high --fix` on the FULL
    `origin/main...HEAD` diff — every file the PR touches — via the
@@ -192,11 +206,13 @@ b. Run Claude Code's built-in `/code-review high --fix` on the FULL
 c. Decide (two branches; match first whose predicate holds):
 
    - **`/code-review` applied fixes (working tree changed):** Commit the
-     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`. Stay
-     `phase = CODE_REVIEW`, schedule next wakeup, return. Every fix push
-     re-enters the internal passes on the new HEAD.
+     applied fixes in one commit → push, following the shared fix protocol
+     commit and push steps ([`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md)). Reset
+     push-invalidated markers per [ground-rules.md](ground-rules.md) /
+     [state-schema.md](state-schema.md) (all `*_clean_at`, `merge_state_status`,
+     `bugbot_down`, `bugbot_acknowledged_at`). Stay `phase = CODE_REVIEW`,
+     schedule next wakeup, return. Every fix push re-enters the internal
+     passes on the new HEAD.
    - **Clean (no changes applied):** Set
      `code_review_clean_at = current_head`, `phase = BUGTEAM`. Continue
      BUGTEAM in same tick — back-to-back convergence requires code-review and
@@ -244,9 +260,11 @@ pushed commits during its run. `current_head` from Step 1 is stale:
    proceed with convergence-gates — schedule a 90s wakeup and return.
    Re-resolve HEAD next tick.
 
-   If `new_head != current_head`, set `current_head = new_head`,
-   `bugbot_clean_at = null`, `bugbot_down = false`. New commits invalidate
-   bugbot's prior clean and down-detection state.
+   If `new_head != current_head`, set `current_head = new_head` and reset
+   push-invalidated markers per [ground-rules.md](ground-rules.md) /
+   [state-schema.md](state-schema.md) (all `*_clean_at`, `merge_state_status`,
+   `bugbot_down`, `bugbot_acknowledged_at`). New commits invalidate prior
+   clean and down-detection state.
 
 c. Inspect bugteam outcome. Reports `convergence (zero findings)` or list
 of unfixed findings with file:line.
@@ -254,17 +272,19 @@ of unfixed findings with file:line.
 d. Decide based on post-bugteam state — order matters. Check
 pushed-during-bugteam FIRST so a convergence report against a stale HEAD
 never falsely terminates:
-   - **Audit pushed this tick (`bugbot_clean_at` reset in step b):**
-     Reset `code_review_clean_at = null`, `phase = CODE_REVIEW`, schedule next
-     wakeup, return. Every fix push re-enters the internal passes on the new
-     HEAD.
+   - **Audit pushed this tick (clean-at fields reset in step b):**
+     `phase = CODE_REVIEW`, schedule next wakeup, return. Every fix push
+     re-enters the internal passes on the new HEAD.
    - **Convergence AND no push:** the internal passes are clean on
-     `current_head`. `phase = BUGBOT` — route into the terminal Bugbot gate,
-     which confirms and then runs the convergence gates. Continue BUGBOT in the
-     same tick.
-   - **Findings without committed fixes:** apply the `pr-fix-protocol`
-     skill (`../../pr-fix-protocol/SKILL.md`). Reset `code_review_clean_at =
-     null`, `phase = CODE_REVIEW`, schedule next wakeup, return.
+     `current_head`. Stamp `bugteam_clean_at = current_head`, then
+     `phase = BUGBOT` — route into the terminal Bugbot gate, which confirms
+     and then runs the convergence gates. Continue BUGBOT in the same tick.
+   - **Findings without committed fixes:** apply the shared fix protocol
+     ([`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md); skill deltas in [fix-protocol.md](fix-protocol.md)). Reset push-invalidated markers
+     per [ground-rules.md](ground-rules.md) / [state-schema.md](state-schema.md)
+     (all `*_clean_at`, `merge_state_status`, `bugbot_down`,
+     `bugbot_acknowledged_at`), `phase = CODE_REVIEW`, schedule next wakeup,
+     return.
 
 ### `phase == BUGBOT` (terminal gate)
 
@@ -314,8 +334,8 @@ pull_request_read(owner=OWNER, repo=REPO, pullNumber=NUMBER, method="get_review_
    → filter threads where `is_resolved == false`
    ```
 
-   Per-thread handling lives in the `pr-fix-protocol` skill's
-   unresolved-thread sweep (`../../pr-fix-protocol/SKILL.md`).
+   Per-thread handling lives in the shared fix protocol's
+   unresolved-thread sweep (`../../../_shared/pr-loop/fix-protocol.md`).
 
 c. Decide (four branches; match first whose predicate holds):
    - **No bugbot review yet, OR latest review's `commit_id` ≠
@@ -327,11 +347,13 @@ c. Decide (four branches; match first whose predicate holds):
      `inline_lag_streak = 0`, advance to the [convergence
      gates](convergence-gates.md) in the same tick.
    - **`commit_id == current_head` with unaddressed inline findings:**
-     Apply the `pr-fix-protocol` skill (`../../pr-fix-protocol/SKILL.md`).
-     Reset `inline_lag_streak = 0`, `bugbot_clean_at = null`,
-     `code_review_clean_at = null`, `phase = CODE_REVIEW`. With `state.json`:
-     the clean-coder teammate executes the fix, writes `state.json`, goes idle;
-     the next tick re-enters CODE_REVIEW on the new HEAD. No `state.json`
+     Apply the shared fix protocol ([`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md); skill deltas in [`fix-protocol.md`](fix-protocol.md)).
+     Reset `inline_lag_streak = 0` and push-invalidated markers per
+     [ground-rules.md](ground-rules.md) / [state-schema.md](state-schema.md)
+     (all `*_clean_at`, `merge_state_status`, `bugbot_down`,
+     `bugbot_acknowledged_at`), `phase = CODE_REVIEW`. With `state.json`: the
+     clean-coder teammate executes the fix, writes `state.json`, goes idle; the
+     next tick re-enters CODE_REVIEW on the new HEAD. No `state.json`
      (single-PR): the lead executes it, stays `phase = CODE_REVIEW`. Schedule
      next wakeup, return.
 
@@ -355,17 +377,18 @@ python ~/.claude/skills/pr-converge/scripts/fetch_copilot_inline_comments.py --o
 b. Decide (three branches; match first whose predicate holds):
 
    - **Copilot review `state: APPROVED` at `current_head`:** Set
-     `copilot_clean_at = current_head`. Record "Copilot APPROVED". Set
-     `phase = BUGTEAM`. Continue to convergence-gates.md gate (b) in same
-     tick — back-to-back convergence requires all gates on same HEAD.
+     `copilot_clean_at = current_head`. Record "Copilot APPROVED". Stay on
+     `COPILOT_WAIT` — do not re-enter BUGTEAM. Continue to
+     convergence-gates.md gate (b) in same tick; re-validate gates (b), (c),
+     then (e), (f) on the same HEAD.
    - **Copilot review dirty (CHANGES_REQUESTED or COMMENTED with findings)
-     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`, `code_review_clean_at = null`, AND
-     `copilot_clean_at = null`. **Set `phase = CODE_REVIEW`** (NOT
-     COPILOT_WAIT) — every fix push re-enters the internal passes on the new
-     HEAD. Schedule next wakeup, return.
+     at `current_head`:** Apply the shared fix protocol ([`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md); skill deltas in [`fix-protocol.md`](fix-protocol.md)) — it covers body-only findings with
+     no inline threads. Reset push-invalidated markers per
+     [ground-rules.md](ground-rules.md) / [state-schema.md](state-schema.md)
+     (all `*_clean_at`, `merge_state_status`, `bugbot_down`,
+     `bugbot_acknowledged_at`). **Set `phase = CODE_REVIEW`** (NOT COPILOT_WAIT)
+     — every fix push re-enters the internal passes on the new HEAD. Schedule
+     next wakeup, return.
    - **No Copilot review at `current_head` yet:** Increment
      `copilot_wait_count` (init 0 on COPILOT_WAIT entry; reset to 0 on
      every push and on every successful Copilot review). `>= 3` → hard