claude-dev-env 1.92.0 → 1.93.0

package/skills/gotcha/SKILL.md

@@ -22,7 +22,7 @@ The caller provides the obstacle context. Distill it into:
 - **What the user had to do** to resolve it.
 - **What to do differently next time** (the actionable gotcha).
 
-Determine which repo the skill lives in. Usually this is `claude-code-config`, but if the skill is in another repo (e.g. a project-specific `.claude/skills/` directory), use that repo instead.
+Determine which repo the skill lives in. Usually this is `claude-dev-env`, but if the skill is in another repo (e.g. a project-specific `.claude/skills/` directory), use that repo instead.
 
 ### Step 2 — Delegate to bg-agent
 
@@ -62,11 +62,11 @@ If a `## Gotchas` section already exists, append to it. If not, create it at the
 
 | Skill location | Repo |
 |---|---|
-| `packages/claude-dev-env/skills/<name>/` | `jl-cmd/claude-code-config` |
-| `~/.claude/skills/<name>/` | `jl-cmd/claude-code-config` (user skills) |
+| `packages/claude-dev-env/skills/<name>/` | `jl-cmd/claude-dev-env` |
+| `~/.claude/skills/<name>/` | `jl-cmd/claude-dev-env` (user skills) |
 | Project `.claude/skills/<name>/` | That project's repo |
 
-When unsure, ask the user which repo. Otherwise, default to `claude-code-config`.
+When unsure, ask the user which repo. Otherwise, default to `claude-dev-env`.
 
 ## Gotchas
 

package/skills/log-audit/SKILL.md

@@ -1,12 +1,10 @@
 ---
 name: log-audit
 description: >-
-  Watches this repo's own logs for patterns worth acting on. Use for /log-audit,
-  "audit the logs", "what keeps failing", or "what's getting slower". Reads the
-  hook block log and the diagnostic extractor pipeline, clusters recurring errors
-  and timing regressions, opens a grouped fix PR or a tracked optimization issue
-  per real finding, and mines the defects Copilot and Bugbot keep catching into
-  skill-edit proposals. Runs as a background agent that resumes after a restart.
+  Watches this repo's own logs for patterns worth acting on: clusters recurring
+  errors and timing regressions, then opens a grouped fix PR or a tracked
+  optimization issue per real finding. Use for /log-audit, 'audit the logs',
+  'what keeps failing', or 'what's getting slower'.
 ---
 
 # log-audit

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

@@ -22,7 +22,7 @@ Discovers every open pull request across the `jl-cmd/*` and `JonEcho/*` owner sc
 ## Workflow summary
 
 1. Call `discover_open_prs.discover_open_prs(all_owners=["jl-cmd", "JonEcho"])` to get the full open-PR list.
-2. For each PR, invoke `/bugteam --bugbot-retrigger <pr_number>` (omit `--bugbot-retrigger` if `CLAUDE_REVIEWS_DISABLED` has `bugbot`).
+2. For each PR, invoke `/bugteam <pr_number>`; include `--bugbot-retrigger` only when bugbot is enabled (`reviews_disabled.py --reviewer bugbot` exits 1).
 3. After each bugteam run, poll for new bugbot comments on a 60s → 120s → 240s → 480s → 960s backoff. Re-invoke bugteam if new findings appear.
 4. Emit a sweep summary when all PRs exit polling.
 

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

@@ -15,12 +15,17 @@ description: >-
 
 ## Contents
 
+- Transport check — gh presence and auth route the sweep local or through the cloud transport
 - When this skill applies — refusal cases and trigger conditions
 - Discovery — `scripts/discover_open_prs.py` queries via `gh search prs` across both owner scopes
 - Dispatch — `/bugteam --bugbot-retrigger <pr_numbers...>`
 - Post-convergence polling — bugbot replies and re-invocation
 - `scripts/discover_open_prs.py` — the discovery helper
 
+## Transport check (before any GitHub step)
+
+Run `command -v gh`; when it succeeds, run `gh auth status`; for each PR the sweep dispatches, `gh api repos/<owner>/<repo> --jq .permissions.push` must print `true`. When any check fails, run the `pr-loop-cloud-transport` skill first and route every `gh` operation in this skill through its substitution matrix, including the discovery query (`mcp__github__search_pull_requests` with `perPage` in place of `gh search prs`).
+
 ## When this skill applies
 
 `/monitor-open-prs` authorizes one full sweep over all open PRs in both owner scopes.
@@ -41,7 +46,7 @@ Call `scripts/discover_open_prs.discover_open_prs(all_owners=["jl-cmd", "JonEcho
 For each discovered PR:
 
 1. Resolve the PR's repo checkout (existing worktree or fresh `git clone`).
-2. From that checkout, invoke `/bugteam --bugbot-retrigger <pr_number>`. When `python "$HOME/.claude/_shared/pr-loop/scripts/reviews_disabled.py" --reviewer bugbot` exits 0 (bugbot disabled), omit `--bugbot-retrigger` from the dispatched command so the bugbot leg sits out the run.
+2. From that checkout, invoke `/bugteam <pr_number>`. Include `--bugbot-retrigger` only when bugbot is enabled for the run — when `python "$HOME/.claude/_shared/pr-loop/scripts/reviews_disabled.py" --reviewer bugbot` exits 1. On exit 0 (bugbot disabled — the default) omit `--bugbot-retrigger` so the bugbot leg sits out the run.
 3. The `--bugbot-retrigger` flag tells bugteam to post `bugbot run` as an issue comment after every successful FIX push so Cursor's bugbot re-evaluates the new commit.
 4. Bugteam runs its own 20-loop audit/fix cycle per PR; this skill waits for each bugteam invocation to return before dispatching the next (or fanning out — see below).
 

package/skills/orchestrator/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: orchestrator
+description: >-
+  Advisor-orchestrator mode: plan and delegate while workflow-backed agents
+  execute; a shared session-advisor answers hard decisions with endorse,
+  correction, plan, or stop. Triggers: '/orchestrator', 'orchestrator
+  strategy', 'run with an orchestrator', 'executor-advisor mode',
+  'orchestrator enforcement', 'agent routing', 'orchestrate'.
+---
+
+# Orchestrator Strategy
+
+## Principle
+
+A frontier model plans and synthesizes while cheap workers do the
+token-heavy reading and doing — Anthropic's coordinator pattern, source:
+https://github.com/anthropics/claude-cookbooks/blob/main/managed_agents/CMA_plan_big_execute_small.ipynb
+("Coordinator pattern: big models for planning, small models for
+execution"). On the cookbook's own measured run, a coordinator
+delegating to Sonnet-5 workers came out cheaper and faster
+than a solo frontier agent held to the same verification rigor, with
+84-98% of the team's input tokens billed at the worker rate.
+
+Claude Code has no `multiagent` coordinator field or Managed-Agents-style
+`create_agent`/`send_to_agent` primitives; this skill reaches the same
+shape with the tools Claude Code already has. Under this skill the session
+is the advisor-orchestrator. In Claude Code the user always talks to the session and never to a
+subagent, so the session is the user's sole interface: all user-facing
+communication flows through it. It spawns and resumes executor subagents
+— `clean-coder` and the like — and those executors do every bit of the
+execution: the code edits, the build runs, the test runs. The orchestrating
+session drives the plan and routes hard decisions to the shared advisor
+(Claude: warm `session-advisor`; Grok: this session self-as-advisor).
+
+## Gotchas
+
+- **Double invocation duplicates the reminder loop.** A second `/orchestrator`
+  in the same session schedules a second refresh loop. Check whether the loop
+  is already running before you schedule one (see the invocation guard in
+  Process step 1).
+- **The orchestrating session never executes.** The moment it edits a file or
+  runs the tests itself, the pairing breaks and the executor's warm context is
+  wasted. Hand every code edit and every build or test run to an executor; keep
+  the orchestrating session's own tool use to orchestration and light
+  verification reads. Hard decisions go to the shared advisor (Claude:
+  `session-advisor` via SendMessage; Grok: this session inline).
+- **Flat ad hoc spawns bypass routing.** Every execution task goes through a
+  workflow-backed spawn or workflow resume so the required agent type, model,
+  prompt packet, and sidecar metadata stay attached to the work.
+- **Wrong agent or model is an enforcement failure.** If a task category maps
+  to `clean-coder` on `opus`, a `general-purpose` Sonnet spawn is not a cost
+  optimization; it is the wrong executor for the contract.
+- **Resuming an unnamed background agent needs its agentId.** A background
+  spawn returns an `agentId` (format `a...-...`); keep it so `SendMessage` can
+  reach that agent later. A named agent is reachable by name.
+- **Only the orchestrating session owns the shared advisor's lifecycle.** An
+  executor that finds the advisor unreachable (Claude warm agent, or this
+  session on Grok) reports that upward; it never spawns a replacement itself.
+
+## Process
+
+1. **Check whether the refresh loop is already running this
+   session.** If it is, do not schedule a second loop. Reuse any live
+   shared advisor bind (Claude warm `session-advisor`, or Grok self-bind —
+   run step 3 only when none exists yet), then skip straight to step 4.
+
+2. **Register the discipline reminder.** By default, schedule it with
+   `ScheduleWakeup` at `delaySeconds: 1200`, prompt `/orchestrator-refresh`,
+   where each refresh re-schedules the next one — a 1200-second wakeup costs
+   one prompt-cache miss per firing and nothing more (see Gotchas). The loop
+   mechanism (`/loop 20m /orchestrator-refresh`) is the escape hatch when
+   `ScheduleWakeup` is not available. Either way the reminder is the
+   enforcement surface: each firing re-asserts the discipline while the run is
+   in flight.
+
+3. **Bind the shared advisor before any executor.** Detect the host profile
+   first (see Host profiles in
+   [`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md)).
+   On a **Claude host**, follow the Warm-up procedure in that doc (Agent spawn
+   of `session-advisor`). Compute the model floor as the max of the
+   orchestrating session's own tier and the highest model in the Workflow Agent
+   Routing table below (today: max(Sonnet, Opus) = Opus). Paste the **Claude
+   host** Advisor block from that doc, with the resolved agent name filled in,
+   into every executor's spawn prompt. On a **Grok host**, skip that spawn —
+   use the protocol's self-as-advisor path (this session *is* the advisor;
+   single tier `Grok`, attempt result `self`). Paste the **Grok host** Advisor
+   block from that doc into every executor's spawn prompt — never the Claude
+   SendMessage block. Every row in the routing table is a consumer of the
+   shared advisor, not just this session. The orchestrating session owns the
+   shared advisor's lifecycle end to end (spawn or self-bind, drift handling
+   per the shared doc, shutdown at task end); executors only ever SendMessage
+   the warm agent (Claude) or report to this session (Grok).
+
+4. **Orchestrate the task.** Hold the plan and the user conversation. Execute
+   workflow-backed spawns or resumes using the routing table below, and keep
+   driving while they work. Every executor spawn includes the host-matched
+   Advisor block from step 3. Your own tool use stays orchestration and light
+   verification reads. Keep your task list updated religiously.
+
+5. **Consult the shared advisor at hard decisions.** Every consumer — each
+   executor and this session — consults when one of these holds (same list as
+   the protocol and Advisor block):
+   - A nontrivial plan is about to be locked in and acted on.
+   - The consumer believes its assigned work is finished.
+   - A commit, push, or other hard-to-reverse action is about to run.
+   - The same failure has come back more than once, or progress has stalled.
+   - The chosen approach is being reconsidered.
+
+   **Claude host:** consult the shared `session-advisor` via `SendMessage`.
+   **Grok host:** executors report to this orchestrating session; this session
+   answers the four signals inline (self-as-advisor — no Agent, no
+   SendMessage-to-`session-advisor`). Every consult gets back one of four
+   signals (ENDORSE, CORRECTION, PLAN, or STOP). See
+   `agents/session-advisor.md` for what each signal means and
+   [`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md)
+   for the consult format.
+
+## Workflow Agent Routing
+
+Every delegated task runs through a workflow-backed agent invocation. Do not
+spawn a flat subagent directly when a workflow invocation or workflow resume is
+available.
+
+| Work | Agent type | Model |
+|---|---|---|
+| Feature, bug, and refactor coding | `clean-coder` | `opus` |
+| Verification passes | `code-verifier` | `sonnet` |
+| Script runs, GitHub posting, and backfill driving | `general-purpose` runner | `sonnet` |
+| PR descriptions | `pr-description-writer` | `haiku`, with file-list grounding check |
+| Fan-out searches and checklist verification reads | `Explore` | `haiku`; use `sonnet` when judgment-heavy |
+
+Routing rules:
+
+- Use a workflow invocation or resume for each row above. The workflow prompt
+  must name the selected agent type, model, work category, task scope, and
+  expected output.
+- Resume a warm workflow agent before creating a new workflow run when the warm
+  agent holds the relevant context.
+- `clean-coder` owns code edits. `code-verifier` owns verification. The same
+  workflow agent never grades work it wrote.
+- PR-description workflows include the actual changed-file list in the prompt
+  and verify the final body against that file list before posting or returning
+  it.
+- Exploration workflows return file paths, line numbers, and direct evidence;
+  they do not write code or mutate repo state.
+
+## Agent reuse (non-negotiable)
+
+- **Resume before you spawn, always.** A warm agent carries its context and
+  cached tokens; a fresh spawn starts cold and pays to rebuild both.
+  Resume the existing workflow agent by name or `agentId` when it holds
+  relevant context. Prefer that path every time an existing workflow agent
+  matches the routing table.
+- **Spawn a fresh agent only when** no existing agent holds relevant context,
+  or a genuine task switch needs a clean context.
+- **Name the agent to resume.** When a PLAN from the shared advisor fits a warm
+  agent, name which agent to resume and where.
+
+## Constraints
+
+- One `/orchestrator` per session; the invocation guard blocks a second
+  reminder loop.
+- The orchestrating session orchestrates and routes hard decisions to the
+  shared advisor (host-matched path in step 5), but never edits code or runs a
+  build or test itself — executors do that.
+- Delegated execution uses workflow-backed agent invocations and follows the
+  Workflow Agent Routing table exactly.
+- One shared advisor per orchestrated session, owned by the orchestrating
+  session (see
+  [`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md))
+  — on Claude, executors consult a warm `session-advisor` via SendMessage; on
+  Grok, this session is the advisor and executors report here. Executors never
+  spawn or respawn the advisor.
+- Reuse a warm agent over a cold spawn whenever one holds relevant context.
+
+## File Index
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Orchestrator strategy, workflow routing contract, shared-advisor consult protocol, reuse rules, and constraints. |
+
+## Folder Map
+
+- `SKILL.md` — complete orchestrator workflow instructions.

package/skills/orchestrator-refresh/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: orchestrator-refresh
+description: >-
+  Fired by the /orchestrator loop reminder about every 20 minutes to
+  re-assert the advisor discipline mid-run: orchestrate, route hard decisions
+  to the shared advisor (ENDORSE / CORRECTION / PLAN / STOP — SendMessage on
+  Claude, self-as-advisor on Grok), reuse warm agents. Triggers:
+  '/orchestrator-refresh'.
+---
+
+# Orchestrator Refresh
+
+Detect the host profile first (see Host profiles in
+[`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md)).
+Re-assert the discipline for that host only — do not invent a Claude
+`session-advisor` spawn on a Grok host.
+
+1. **You are the advisor-orchestrator.** Orchestrate and hold the user
+   conversation; spawn executor subagents to do all the work — every code edit
+   and build or test run.
+2. **Hard decisions go to the shared advisor.**
+   - **Claude host:** executors consult the warm `session-advisor` via
+     `SendMessage` and receive one of four signals — ENDORSE, CORRECTION, PLAN,
+     or STOP. The orchestrating session routes its own hard decisions the same
+     way and keeps its tool use to orchestration and light verification reads.
+   - **Grok host:** this session *is* the advisor (self-as-advisor). Do **not**
+     spawn `session-advisor` and do **not** tell executors to SendMessage a
+     separate advisor agent. Executors report blockers to this session; answer
+     with ENDORSE / CORRECTION / PLAN / STOP inline.
+3. **Resume before you spawn.** `SendMessage` an existing *executor* agent by
+   name or `agentId` to reuse its warm context; prefer that over a cold spawn.
+   (On Grok this is executor reuse only — not an advisor spawn.)
+4. **Fresh spawn only for a genuine task switch.** No tool compacts or clears a
+   subagent's context, so a clean context comes from a fresh spawn — never tell
+   an agent to compact.
+5. **Re-schedule the next refresh** (about 1200 seconds out) when the loop
+   mechanism needs each firing to queue the following one.

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

@@ -1,15 +1,11 @@
 ---
 name: post-audit-findings
 description: >-
-  Publishes an audit pass as one GitHub PR review via the shared
-  post_audit_thread.py: maps audit findings to the {path, line, side,
-  severity, description, fix_summary} JSON shape (splitting failure_mode at
-  the literal `Fix:` heading), partitions anchored vs unanchored findings so
-  one bad anchor cannot reject the whole POST, handles the self-PR reviewer
-  toggle via BUGTEAM_REVIEWER_ACCOUNT, and harvests finding comment ids and
-  PRRT thread node ids for the fix loop. Invoked by audit skills (bugteam,
-  qbug, findbugs) after each audit pass, CLEAN or DIRTY; not for ad-hoc PR
-  comments or review replies.
+  Publishes an audit pass as a GitHub PR review through post_audit_thread.py:
+  maps findings to the review-comment JSON shape, splits anchored from
+  unanchored, and collects the comment and thread ids for the fix loop. Invoked
+  by audit skills (bugteam, qbug, findbugs) after each pass; not for ad-hoc
+  comments.
 ---
 
 # Post Audit Findings

package/skills/pr-consistency-audit/SKILL.md

@@ -1,7 +1,11 @@
 ---
 name: pr-consistency-audit
 description: >-
-  Audits a PR for cross-file inconsistencies. Finds wrong argument names, missing required args, references to files or scripts that do not exist, stale feature remnants, docstring-vs-implementation mismatches, placeholder text, cross-file contradictions, parameter naming convention violations, and cross-platform bugs. Use when the user says "audit this PR", "find inconsistencies", "cross-reference docs against scripts", "check for stale references", "PR consistency audit".
+  Audits a PR for cross-file inconsistencies: wrong arguments, missing files or
+  scripts, stale remnants, docstring mismatches, and cross-platform bugs. Use
+  when the user says 'audit this PR', 'find inconsistencies', 'cross-reference
+  docs against scripts', 'check for stale references', or 'PR consistency
+  audit'.
 ---
 
 # PR Consistency Audit

package/skills/pr-converge/CLAUDE.md

@@ -1,6 +1,6 @@
 # pr-converge skill
 
-Drives a draft PR to convergence by looping Cursor Bugbot, a code-review pass, a second-opinion bug audit (`bugteam`), and Copilot — applying TDD fixes, posting inline replies, and re-triggering reviewers each tick until all reviewers are clean on the same HEAD and the PR is mergeable.
+Drives a draft PR to convergence by driving the internal passes to clean first — a code-review pass and a bugteam audit — then running Cursor Bugbot and Copilot as terminal confirmation gates, applying TDD fixes, posting inline replies, and re-triggering the external reviewers each tick until all are clean on the same HEAD and the PR is mergeable.
 
 **Trigger:** `/pr-converge`, "drive PR to convergence", "loop bugbot and bugteam", "babysit bugbot and bugteam", "until both are clean", "converge this PR".
 

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 |