claude-dev-env 1.92.1 → 1.93.0

package/skills/pr-converge/SKILL.md

@@ -1,20 +1,26 @@
 ---
 name: pr-converge
 description: >-
-  Drives the current PR to convergence by looping Cursor Bugbot, a
-  code-review pass, a second-opinion bug audit, and Copilot — applying
-  TDD fixes, posting inline replies, and re-triggering reviewers each
-  tick until all reviewers are clean on the same HEAD. Use when the user
-  says
-  '/pr-converge', 'drive PR to convergence', 'loop bugbot and bugteam',
-  'babysit bugbot and bugteam', 'until both are clean', or 'converge this
-  PR'.
+  Loops Cursor Bugbot, a code review, a bug audit, and Copilot on the current
+  PR, applying TDD fixes until all are clean on one HEAD. Use when the user says
+  '/pr-converge', 'drive PR to convergence', 'loop bugbot and bugteam', 'babysit
+  bugbot and bugteam', 'until both are clean', or 'converge this PR'.
 ---
 
 # PR Converge
 
-One tick per invocation. Bugbot ↔ code-review ↔ bugteam ↔ Copilot loop on
-a draft PR until all are clean on the same `HEAD` and mergeable.
+One tick per invocation. A code-review ↔ bugteam ↔ Bugbot ↔ Copilot loop on
+a draft PR: the internal code-review and bugteam passes drive the code to clean
+first, then Cursor Bugbot and Copilot run as terminal confirmation gates, until
+all are clean on the same `HEAD` and mergeable.
+
+## Transport check (before any GitHub step)
+
+Run `command -v gh`; when it succeeds, run `gh auth status`; once the PR
+scope is resolved, run `gh api repos/<owner>/<repo> --jq .permissions.push`
+and take `true` as the pass. When any check fails, run the
+`pr-loop-cloud-transport` skill first and route every `gh` operation in this
+skill through its substitution matrix.
 
 ## Pre-flight
 
@@ -50,7 +56,7 @@ Before Step 0, check
 `$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.
+CODE_REVIEW.
 
 ## Copilot quota pre-check (start of run)
 
@@ -64,6 +70,29 @@ no request, no poll, no agent — and exports
 pending-requested-reviews gate and the run still marks ready on the remaining
 signals.
 
+## Copilot findings — two-tier triage
+
+The Copilot step tiers each finding it surfaces. A **self-healing** finding is
+pure style, type hints, misplaced or unused imports, formatting, magic-value
+extraction, a test-only change, a doc-or-description vs code mismatch, or code
+de-duplication — a fix that cannot change observable runtime behavior for
+production callers. Self-healing findings flow into the existing fix tick and
+count toward convergence, with no user alert. The tick-paced loop holds them
+naturally: the fix lands on `current_head`, the next tick re-checks, and the run
+converges when the Copilot step is clean.
+
+A **code-concern** finding is behavior-changing or needs a product decision:
+logic or correctness, security, data handling, error-handling semantics, or
+concurrency. Tier a finding as code-concern whenever the tier is in doubt. On
+one or more code-concern findings, do not auto-fix them and do not let the tick
+mark the PR ready. Run the
+[`copilot-finding-triage`](../copilot-finding-triage/SKILL.md) gate: send the
+ntfy alert with the finding summary and the Copilot review link, then hold for
+the user's response on a 45-minute deadline that spans ticks — carry the
+deadline in the run's persisted state so each tick reads it on entry. Act on the
+user's direction when it arrives inside the window; when the deadline passes
+with no response, run teardown and report the code-concern findings un-reviewed.
+
 ## Budget-aware tick boundaries
 
 Before starting any tick, estimate whether the remaining session/usage
@@ -137,7 +166,7 @@ the `persistent_agents` map
   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`
+- **Fresh every round (never persisted):** the Step 5 `/code-review high --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
@@ -188,7 +217,7 @@ post a fresh PR in a fresh branch based on origin main to the user.
   Windows is Git Bash which cannot execute PowerShell cmdlets. Route all
   PowerShell work through the PowerShell tool or `pwsh -NoProfile -File`.
 - **Cross-repo PR: route cwd into the PR worktree before `/code-review`** —
-  `/code-review --fix` (Step 5) audits the repo of the current working
+  `/code-review high --fix` (Step 5) audits the repo of the current working
   directory. When the session is rooted in a different repo than the PR,
   `EnterWorktree` cannot re-root (it is scoped to the session's repo);
   resolve the PR worktree and `cd` into it per
@@ -237,7 +266,7 @@ round as converged. This rule holds every tick, every loop, every PR.
       and [§ Step 1.5](reference/per-tick.md)
 
 - [ ] **Step 2: Initialize loop state**
-      `phase = BUGBOT`; all counters at zero; `run_name` resolved.
+      `phase = CODE_REVIEW`; all counters at zero; `run_name` resolved.
 
 - [ ] **Step 3: Mergeability check**
       See: [`reference/convergence-gates.md` § (c)](reference/convergence-gates.md)
@@ -249,37 +278,38 @@ round as converged. This rule holds every tick, every loop, every PR.
       - [ ] mergeable → advance to Step 4
       - [ ] not mergeable → rebase → force-push → return to Step 1
 
-- [ ] **Step 4: BUGBOT — fetch, decide, fix, reply, resolve**
-      See: [`reference/per-tick.md` § Step 2 BUGBOT + Step 3](reference/per-tick.md)
+- [ ] **Step 4: BUGBOT — terminal Bugbot confirmation gate**
+      The terminal external gate. Step 6 routes here after BUGTEAM converges, so
+      Bugbot confirms code the internal passes already drove to clean.
+      See: [`reference/per-tick.md` § BUGBOT terminal gate + Step 3](reference/per-tick.md)
 
-      - [ ] **Opt-out gate (runs first, every BUGBOT entry).**
+      - [ ] **Availability gate (runs first, every BUGBOT entry).**
             Gate semantics live in the `reviewer-gates` skill
-            (`../reviewer-gates/SKILL.md` § Gate 1).
+            (`../reviewer-gates/SKILL.md` § Gate 1). Cursor Bugbot is off by default and runs only when `CLAUDE_REVIEWS_ENABLED` lists `bugbot`; a `bugbot` token in `CLAUDE_REVIEWS_DISABLED` keeps it off even then.
             `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 0 (Bugbot disabled for this run — the default) → set `bugbot_down = true`, advance to the Step 7 convergence gates (no trigger, no wait, no agent). Cursor Bugbot is skipped for the entire run.
             - [ ] Exit 1 → continue below.
 
       Fetch bugbot reviews + inline comments on `current_head`.
 
       - [ ] **dirty** (findings on `current_head`) →
             - [ ] Apply the `pr-fix-protocol` skill (`../pr-fix-protocol/SKILL.md`) to this tick's findings
-            - [ ] Push → return to Step 4
+            - [ ] Push → reset `bugbot_clean_at = null`, `code_review_clean_at = null` → `phase = CODE_REVIEW` → return to Step 5
       - [ ] **clean** (no findings on `current_head`) →
             - [ ] Count ALL unresolved threads on PR (`is_resolved == false`) → zero? advance; >0? fix + resolve first
             - [ ] `bugbot_clean_at = current_head`
-            - [ ] `phase = CODE_REVIEW`
-            - [ ] Advance to Step 5
+            - [ ] Advance to the Step 7 convergence gates
       - [ ] **no review yet / commit_id mismatch** →
             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
+            - [ ] Silent pass → `bugbot_clean_at = current_head` → advance to the Step 7 convergence gates
             - [ ] 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)
-
-      Pre-condition: `bugbot_clean_at == current_head` (or `bugbot_down == true`).
+            - [ ] Bugbot down → `bugbot_down = true` → advance to the Step 7 convergence gates (bypass)
+- [ ] **Step 5: CODE-REVIEW — entry phase: static sweep, review, fix, advance**
+      The first internal step of every convergence tick (Step 2 seeds
+      `phase = CODE_REVIEW`), re-entered after any fix push.
+      See: [`reference/per-tick.md` § CODE_REVIEW entry](reference/per-tick.md)
 
       Pre-condition: the working directory is the Step 1.5 PR worktree on
       `current_head` (`git rev-parse --show-toplevel` is that checkout).
@@ -288,18 +318,28 @@ round as converged. This rule holds every tick, every loop, every PR.
       current working directory, so this routing targets the real PR
       diff. This `cd` is routine and automatic.
 
-      Run Claude Code's built-in `/code-review --fix` on the full
+      - [ ] **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`.
+            - [ ] Any failure → apply the `pr-fix-protocol` skill
+                  (`../pr-fix-protocol/SKILL.md`), commit/push, reset
+                  `bugbot_clean_at = null` and `code_review_clean_at = null`, stay
+                  `phase = CODE_REVIEW`, and re-run (return to Step 5).
+            - [ ] Clean → run `/code-review` below.
+
+      Run Claude Code's built-in `/code-review high --fix` on the full
       `origin/main...HEAD` diff —
       the [local diff review](https://code.claude.com/docs/en/code-review#review-a-diff-locally)
       — so it reviews the diff and applies its findings to the working
-      tree. Pass no effort argument, so the review uses the session's
-      current effort.
+      tree. Invoke `/code-review high --fix` so the pre-catch pass gets broad
+      coverage regardless of the session's current effort.
 
       **Scope: the FULL `origin/main...HEAD` diff every tick** — every file
       the PR touches. Do not delta-scope to commits added since the prior
       clean SHA, do not scope to a single file, do not scope to bugbot's
       flagged paths. Before running, confirm the working tree is on the
-      PR's HEAD with no uncommitted edits, then invoke `/code-review --fix`
+      PR's HEAD with no uncommitted edits, then invoke `/code-review high --fix`
       with no path arguments so it audits the whole branch diff against
       `origin/main`. A partial-scope round does not count and cannot set
       `code_review_clean_at`.
@@ -307,8 +347,7 @@ round as converged. This rule holds every tick, every loop, every PR.
       - [ ] **fixes applied** (working tree changed) →
             - [ ] Commit the applied fixes (one commit) → push
             - [ ] reset `bugbot_clean_at = null`, `code_review_clean_at = null`
-            - [ ] Re-trigger bugbot (Step 4 "no review yet" checklist)
-            - [ ] `phase = BUGBOT` → schedule 360s wakeup → return to Step 4
+            - [ ] stay `phase = CODE_REVIEW` → return to Step 5 (internal-first)
       - [ ] **clean** (no changes applied) →
             - [ ] 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`
@@ -338,21 +377,21 @@ round as converged. This rule holds every tick, every loop, every PR.
 
       - [ ] **bugteam pushed new commits** →
             - [ ] Verify all bugteam review threads replied + resolved
-            - [ ] Re-trigger bugbot (Step 4 "no review yet" checklist)
-            - [ ] `phase = BUGBOT` → schedule 360s wakeup → return to Step 4
-      - [ ] **converged (zero findings) + `bugbot_clean_at == current_head`** →
+            - [ ] reset `bugbot_clean_at = null`, `code_review_clean_at = null`
+            - [ ] `phase = CODE_REVIEW` → schedule 360s wakeup → return to Step 5
+      - [ ] **converged (zero findings), no push** →
             - [ ] Count ALL unresolved threads on PR (`is_resolved == false`) → zero? advance; >0? fix + resolve first
-            - [ ] Advance to Step 7
-      - [ ] **converged + `bugbot_clean_at ≠ current_head`** →
-            `phase = BUGBOT` → schedule 360s wakeup → return to Step 4
+            - [ ] `phase = BUGBOT` → advance to Step 4 (terminal Bugbot gate)
       - [ ] **findings without committed fixes** →
             - [ ] Apply the `pr-fix-protocol` skill (`../pr-fix-protocol/SKILL.md`) to the findings
-            - [ ] Push → `phase = BUGBOT` → return to Step 4
+            - [ ] Push → reset `bugbot_clean_at = null`, `code_review_clean_at = null` → `phase = CODE_REVIEW` → return to Step 5
 
 - [ ] **Step 7: Convergence gates**
       See: [`reference/convergence-gates.md`](reference/convergence-gates.md)
 
-      Pre-condition: Step 6 converged AND `bugbot_clean_at == current_head`.
+      Pre-condition: Step 6 converged AND (`bugbot_clean_at == current_head` OR
+      `bugbot_down`). The terminal Bugbot gate (Step 4) sets that state just
+      before these gates run.
       Count unresolved threads before each gate.
 
       **(a) Universal unresolved-thread sweep**
@@ -361,13 +400,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? → apply the `pr-fix-protocol` skill's unresolved-thread sweep (`../pr-fix-protocol/SKILL.md`). 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 → reset markers → `phase = CODE_REVIEW` → return to Step 5
       - [ ] 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 → apply the `pr-fix-protocol` skill (`../pr-fix-protocol/SKILL.md`) → push → return to Step 4
+      - [ ] dirty → apply the `pr-fix-protocol` skill (`../pr-fix-protocol/SKILL.md`) → push → reset markers → `phase = CODE_REVIEW` → return to Step 5
       - [ ] clean (no findings) → `copilot_clean_at = current_head` → gate (b)
       - [ ] no review yet → gate (b)
 
@@ -399,7 +438,7 @@ round as converged. This rule holds every tick, every loop, every PR.
         → count threads where is_resolved == false
       ```
       - [ ] zero unresolved → gate (e)
-      - [ ] unresolved → apply the `pr-fix-protocol` skill's unresolved-thread sweep (`../pr-fix-protocol/SKILL.md`). 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 → reset markers → `phase = CODE_REVIEW` → return to Step 5
 
       **(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.
@@ -409,7 +448,7 @@ round as converged. This rule holds every tick, every loop, every PR.
               --owner <O> --repo <R> --pr-number <N>
             ```
       - [ ] Exit 0 (all pass) → `update_pull_request(draft=false)` → advance to Step 8
-      - [ ] Exit 1 (FAIL lines) → address each failure → return to Step 4
+      - [ ] Exit 1 (FAIL lines) → address each failure → reset markers → `phase = CODE_REVIEW` → return to Step 5
       - [ ] Exit 2 (gh error) → retry once; persistent → stop
 
 - [ ] **Step 7a: COPILOT_WAIT — fetch Copilot, decide**
@@ -424,7 +463,7 @@ round as converged. This rule holds every tick, every loop, every PR.
             `copilot_clean_at = current_head` → return to Step 7 (re-validate gates b, d, e)
       - [ ] **dirty (findings present)** →
             - [ ] Apply the `pr-fix-protocol` skill (`../pr-fix-protocol/SKILL.md`) to the findings
-            - [ ] Push → `phase = BUGBOT` → return to Step 4
+            - [ ] Push → reset markers → `phase = CODE_REVIEW` → return to Step 5
       - [ ] **no review yet** →
             increment `copilot_wait_count` → ≥ 3 = hard blocker → stop
             schedule 360s wakeup → return to Step 7a next tick

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

@@ -6,7 +6,7 @@ Reference documents for the `pr-converge` skill. These files define the per-tick
 
 | File | Purpose |
 |---|---|
-| `per-tick.md` | Step-by-step procedure for one tick (resolve HEAD, run BUGBOT, CODE_REVIEW, BUGTEAM, COPILOT_WAIT phases, schedule next wakeup) |
+| `per-tick.md` | Step-by-step procedure for one tick (resolve HEAD, run the internal CODE_REVIEW and BUGTEAM phases, then the terminal BUGBOT and COPILOT_WAIT gates, schedule next wakeup) |
 | `convergence-gates.md` | Six gates that must all pass before the PR is marked ready for review |
 | `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 |

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

@@ -1,9 +1,10 @@
 # Convergence gates
 
-Run **only** when Step 2 BUGTEAM reports `convergence (zero findings)` AND
-`bugbot_clean_at == current_head` AND no push during bugteam tick. Gates run
-in order; first failure determines next-tick behavior. Mark PR ready only
-when all six pass.
+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
+push during the bugteam tick. Gates run in order; first failure determines
+next-tick behavior. Mark PR ready only when all six pass.
 
 **Mandatory evidence rule:** Every gate that fetches data MUST produce a
 summary of its findings before proceeding to the next gate. Gate (f) MUST
@@ -36,19 +37,20 @@ 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`) → 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.
+  (`../../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.
 - **`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
   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,
+  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.
 - **`classification == "clean"` (state `APPROVED`):** Set
@@ -78,14 +80,14 @@ Decide (four branches; match first whose predicate holds):
   `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 = BUGBOT`,
+  `bugbot_clean_at = null` AND `copilot_clean_at = null`, `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 = BUGBOT`,
+  `bugbot_clean_at = null` AND `copilot_clean_at = null`, `phase = CODE_REVIEW`,
   schedule next wakeup, return.
 - **`classification == "clean"` (state `APPROVED`):** Record evidence:
   "Claude APPROVED at <SHA>". Continue to gate (c).
@@ -111,8 +113,9 @@ Persist `mergeable_state` into `merge_state_status`. Decide:
   ([`../../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`,
-  `copilot_clean_at = null`, `merge_state_status = null`, `phase = BUGBOT`,
-  Step 3 on new HEAD, schedule next wakeup, return. Loop re-runs from
+  `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.
 - **`mergeable_state` is `"blocked"`, `"behind"`, `"unknown"`, or `"unstable"` for
   non-conflict reasons** (required checks pending/failing for "unstable",
@@ -157,7 +160,7 @@ against `current_head`. Decide:
   - `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 = BUGBOT`, schedule next wakeup, return.
+    `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
@@ -187,7 +190,7 @@ Decide:
   `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
+  `phase = CODE_REVIEW`, schedule next wakeup, return. If only resolutions
   (no code changes), re-check this gate without resetting.
 
 ## (f) Mark ready and report

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

@@ -4,40 +4,60 @@ Worked examples for `pr-converge`. Read on demand when a tick's
 classification is novel or ambiguous against the in-skill rules. Cross-refs
 into `SKILL.md` use `§Section name` notation.
 
-<example> User: `/pr-converge` Claude: [PR context + one tick bugbot/bugteam
-work; Step 4 per `workflows/schedule-wakeup-loop.md` — default loop until
-convergence or stop]
+<example> User: `/pr-converge` Claude: [PR context + one tick of internal
+code-review/bugteam work, then the terminal Bugbot and Copilot gates; Step 4
+per `workflows/schedule-wakeup-loop.md` — default loop until convergence or
+stop]
 </example>
 
-<example> BUGBOT tick, latest bugbot review against older commit. Claude:
-[posts `bugbot run`, sets `bugbot_clean_at = null`, Step 4 per
-`workflows/schedule-wakeup-loop.md` (e.g. 270s wakeup), returns]
+<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]
 </example>
 
-<example> BUGBOT tick, bugbot has 2 unaddressed findings on HEAD. Claude:
-[TDD-fixes both, one commit, pushes, replies inline on both threads, posts
-`bugbot run`, Step 4 at 270s, returns]
+<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]
 </example>
 
-<example> BUGBOT tick, bugbot clean against HEAD. Claude: [sets
-`bugbot_clean_at = HEAD`, `phase = CODE_REVIEW`, runs `/code-review --fix`
-in same tick]
+<example> CODE_REVIEW tick, static sweep clean and `/code-review high --fix`
+clean (no changes applied). Claude: [sets `code_review_clean_at = HEAD`,
+`phase = BUGTEAM`, runs `Skill({skill: "bugteam", ...})` in same tick]
 </example>
 
-<example> CODE_REVIEW tick, `/code-review --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`, posts
-`bugbot run`, `phase = BUGBOT`, Step 4 at 270s, returns]
+<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]
 </example>
 
-<example> CODE_REVIEW tick, `/code-review --fix` clean (no changes
-applied). Claude: [sets `code_review_clean_at = HEAD`, `phase = BUGTEAM`,
-runs `Skill({skill: "bugteam", ...})` in same tick]
+<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]
 </example>
 
-<example> BUGTEAM phase, bugteam reports convergence and `bugbot_clean_at
-== current_head` (no push). Claude: [back-to-back clean — necessary, not
-sufficient. Runs `convergence-gates.md` gates in order:
+<example> Terminal BUGBOT gate, Bugbot disabled for the run (the default).
+Claude: [availability gate exits 0, sets `bugbot_down = true`, advances to the
+`convergence-gates.md` gates with the Bugbot gate bypassed — no trigger, no
+wait, no agent]
+</example>
+
+<example> Terminal BUGBOT gate, Bugbot enabled and clean on HEAD. Claude:
+[sets `bugbot_clean_at = HEAD`, advances to the `convergence-gates.md` gates in
+the same tick]
+</example>
+
+<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]
+</example>
+
+<example> Convergence gates after the terminal Bugbot gate confirms
+(`bugbot_clean_at == current_head`). Claude: [runs `convergence-gates.md` gates
+in order:
   Gate (a): two calls — `pull_request_read(method="get_reviews")` +
     `pull_request_read(method="get_review_comments")`
     → filter Copilot → APPROVED at `current_head`
@@ -53,7 +73,7 @@ sufficient. Runs `convergence-gates.md` gates in order:
     → schedule next wakeup, return.
     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).
+    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 (f): all six gates pass → `update_pull_request(pullNumber=NUMBER,
@@ -64,40 +84,35 @@ mergeable_state clean, copilot CLEAN at <SHA>, claude absent at <SHA>,
 applies **Convergence** from `workflows/schedule-wakeup-loop.md`]
 </example>
 
-<example> BUGTEAM phase, bugteam pushed fix commit during run. Claude:
-[re-resolves HEAD, sets `bugbot_clean_at = null`, posts `bugbot run` in
-same tick, `phase = BUGBOT`, Step 4 at 270s]
-</example>
-
-<example> BUGBOT tick, review body says "found 3 potential issues" against
-HEAD but inline API returns zero matching for `current_head`. Claude:
-[increments `inline_lag_streak` to 1, Step 4 inline-lag rules (90s
-`ScheduleWakeup`), returns]
+<example> CODE_REVIEW tick, review body says "found 3 potential issues"
+against HEAD (a stale prior finding) but the diff is clean. Claude: [the static
+sweep and `/code-review high --fix` both pass, sets `code_review_clean_at =
+HEAD`, `phase = BUGTEAM`]
 </example>
 
-<example> Back-to-back clean reached, but `mergeStateStatus: DIRTY` (base
+<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`,
-`copilot_clean_at = null`, `merge_state_status = null`, `phase = BUGBOT`,
-posts `bugbot run` on new HEAD, schedules next wakeup]
+`code_review_clean_at = null`, `copilot_clean_at = null`, `merge_state_status
+= null`, `phase = CODE_REVIEW`, schedules next wakeup]
 </example>
 
-<example> Back-to-back clean, mergeability CLEAN, Copilot review at
+<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`
-and `copilot_clean_at` null, `phase = BUGBOT`, posts `bugbot run` on new
-HEAD, schedules next wakeup]
+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]
 </example>
 
-<example> Back-to-back clean, mergeability CLEAN, no Copilot review on
+<example> Convergence gates reached, mergeability CLEAN, no Copilot review on
 `current_head`. Claude sets `phase = COPILOT_WAIT`, runs gate (d):
 `request_copilot_review(owner=OWNER, repo=REPO, pullNumber=NUMBER)`,
 schedules next wakeup, returns. Next tick:
 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`;
+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`
 unresolved-thread sweep — passes trivially, record evidence:
@@ -108,12 +123,13 @@ at <SHA>, bugteam CLEAN at <SHA>, mergeable_state clean, copilot CLEAN at
 <SHA>, claude absent at <SHA>, 0 unresolved threads across PR; marked ready for review"]
 </example>
 
-<example> Back-to-back clean, mergeability CLEAN, post-convergence Copilot
-review returned `state: CHANGES_REQUESTED` with inline findings on
+<example> Convergence gates reached, mergeability CLEAN, post-convergence
+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` and
-`copilot_clean_at = null`; `phase = BUGBOT`; posts `bugbot run` on new
-HEAD; schedules next wakeup. Full back-to-back-clean cycle plus all six
-gates must hold again on new HEAD.]
+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.]
 </example>

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

@@ -8,7 +8,7 @@ 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.
+obligations and the same-tick re-entry rule.
 
 **Multi-PR (`state.json`) teammate obligations** (plus TDD, commit, push):
 
@@ -17,21 +17,21 @@ obligations and the same-tick re-trigger 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`, `bugbot_down: false`, `phase: "BUGBOT"`,
-  `status: "awaiting_bugbot"`, `last_updated` (ISO-8601 UTC) to
-  `state.json` (per §Concurrency).
-- Goes idle. Orchestrator spawns follow-up `general-purpose` agent for
-  bugbot trigger and monitoring.
+  `bugbot_clean_at: null`, `code_review_clean_at: 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
+  CODE_REVIEW re-entry on the new HEAD.
 
-Orchestrator does not reply inline, trigger bugbot, or read repo source
+Orchestrator does not reply inline, re-enter code-review, or read repo source
 files during fix phase in multi-PR mode.
 
-### Same-tick re-trigger rule
+### Same-tick re-entry rule
 
-**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.
+**After pushing a fix, re-enter the CODE_REVIEW phase in the same tick**
+regardless of phase. A new commit **resets the full convergence cycle**: a
+code-review clean, a bugteam clean, and a Bugbot clean on an older SHA do
+**not** count toward convergence on the new `HEAD`. Re-run the static sweep and
+`/code-review high --fix` on `current_head`, then bugteam, then the terminal
+Bugbot gate, all on the same `HEAD` with no intervening push. Re-entering in the
+same tick saves a wakeup cycle.

package/skills/pr-converge/reference/ground-rules.md

@@ -1,24 +1,28 @@
 # Ground rules
 
+- **Internal-first.** The internal code-review and bugteam passes drive the code
+  to clean each tick; Cursor Bugbot and Copilot run only after that, as terminal
+  confirmation gates.
 - **Append commits.** Each tick adds at most one fix commit.
-- **Bugbot findings on current SHA mean fix-then-push-then-`bugbot run`,
-  not another naked `bugbot run`.**
+- **Bugbot findings on the current SHA mean fix-then-push-then-re-enter
+  CODE_REVIEW,** so the internal passes re-clear the new HEAD before the terminal
+  Bugbot gate runs again.
 - **All `*_clean_at`, `merge_state_status`, and `bugbot_down` reset on every push.**
 - **`bugbot run` comment is load-bearing.** Literal phrase exactly —
   empirically the only re-trigger Cursor Bugbot recognizes.
-- **Production edits go through `clean-coder`, except `/code-review --fix`.**
+- **Production edits go through `clean-coder`, except `/code-review high --fix`.**
   The lead never hand-edits production files. Every bugbot, bugteam,
   Copilot, or Claude finding spawns `Agent(subagent_type="clean-coder")` to
-  implement the fix. The CODE_REVIEW phase is the one exception: `/code-review
-  --fix` applies its own findings to the working tree, which the next
-  BUGBOT/BUGTEAM cycle re-reviews after the loop resets.
+  apply the fix. The CODE_REVIEW phase is the one exception: `/code-review
+  high --fix` applies its own findings to the working tree, which the next
+  CODE_REVIEW/BUGTEAM cycle re-reviews after the loop resets.
 - **Adapt when reality contradicts on-disk state.** If `state.json`,
   `git`, or `gh` disagree with live PR, escalate as hard blocker per
   [stop-conditions.md](stop-conditions.md).
 - **Cross-repo cwd routing is routine, not a fork.** When the PR under
   convergence lives in a different repo than the session is rooted in, route
   the working directory into a checkout of the PR's repo automatically —
-  `/code-review --fix`, `git`, and every `clean-coder` fix spawn act on the
+  `/code-review high --fix`, `git`, and every `clean-coder` fix spawn act on the
   repo of the current working directory. The resolution is fixed
   ([per-tick.md § Step 1.5](per-tick.md)): resolve the PR worktree, `cd` into
   it, run local work there. Do not pause, ask, or raise it as a material fork.