claude-dev-env 1.38.1 → 1.40.0

package/skills/pr-converge/reference/obstacles/fix-trigger-bugbot.md

@@ -0,0 +1,13 @@
+# Re-trigger bugbot
+
+Run Step 3 bugbot re-trigger in same tick after push
+
+## Self-population
+
+Hit a wall on this step? Spawn a background agent to record it. Keep working.
+
+1. Spawn  — brief it: check  for an open PR touching this file, add a commit to it, or create a fresh branch + worktree + draft PR.
+2. Tell the agent your obstacle and what fixed it. It writes the entry below.
+
+## Obstacles
+

package/skills/pr-converge/reference/obstacles/fix-write-test.md

@@ -0,0 +1,13 @@
+# Write failing test
+
+Write failing test first when finding has behavior to test
+
+## Self-population
+
+Hit a wall on this step? Spawn a background agent to record it. Keep working.
+
+1. Spawn `general-purpose` — brief it: check for an open PR touching this file, add a commit to it, or create a fresh branch + worktree + draft PR.
+2. Tell the agent your obstacle and what fixed it. It writes the entry below.
+
+## Obstacles
+

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

@@ -23,8 +23,7 @@ protocol per [fix-protocol.md](fix-protocol.md). Pacing stays in main session vi
 Read [`../workflows/schedule-wakeup-loop.md`](../workflows/schedule-wakeup-loop.md)
 (installed copy under `$HOME/.claude/skills/pr-converge/workflows/`) before
 Step 4. The pre-flight gate guarantees `ScheduleWakeup` is invokable; the
-workflow file specifies delays, prompts, convergence cleanup, and
-inline-lag handling.
+workflow file specifies delays, prompts, and convergence cleanup.
 
 - **`/pr-converge`** (default): loops until convergence. After each tick
   (unless converged or stopped), run **Step 4**.
@@ -41,6 +40,8 @@ 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).
 
 Capture `number`, `head.sha` (= `current_head`), owner/repo, branch.
 
@@ -69,15 +70,19 @@ Capture `commit_id`, `submitted_at`, body, `classification` of index-0
 review for decisions below. When branch routes to **Fix protocol**, address
 **every** entry in `$dirty_reviews_path` — not just index 0.
 
-b. Fetch unaddressed inline comments from `cursor[bot]` for newest Bugbot
-review on `current_head`:
+b. Fetch ALL unresolved inline comment threads on the PR:
 
    ```
 pull_request_read(owner=OWNER, repo=REPO, pullNumber=NUMBER, method="get_review_comments")
-   → filter threads where `is_outdated == false` AND `is_resolved == false`
-     AND any comment has `.author` matching cursor/bugbot (case-insensitive substring)
+   → filter threads where `is_resolved == false`
    ```
 
+   For each unresolved thread, you still need to know **who** wrote it
+   and **what commit** it anchors to so you can decide how to address it
+   — but the gate itself doesn't filter on those fields. Verify each
+   thread's concern against current HEAD; either fix-and-resolve or
+   reply-with-note-and-resolve.
+
 c. Decide (four branches; match first whose predicate holds):
    - **No bugbot review yet, OR latest review's `commit_id` ≠
      `current_head`:** Re-trigger bugbot (Step 3), set `bugbot_clean_at =
@@ -93,15 +98,10 @@ c. Decide (four branches; match first whose predicate holds):
      `state.json`, goes idle; Step 3 on new HEAD runs after via
      orchestrator-spawned follow-up agent (§Fix result → general-purpose).
      No `state.json` (single-PR): spawn Agent (subagent_type: clean-coder) to implement → push → reply inline on each thread
-     via `add_reply_to_pull_request_comment` MCP → Step 3 in same tick (see
+     via `python ~/.claude/skills/pr-converge/scripts/post_fix_reply.py` → Step 3 in same tick (see
      [Single-PR fix workflow](fix-protocol.md#single-pr-fix-workflow) for
      full contract).
      Schedule next wakeup, return.
-   - **`commit_id == current_head` AND review body findings AND inline
-     API zero matching for `current_head`:** Transient API lag. Increment
-     `inline_lag_streak`. `>= 3` → hard blocker; report and terminate with
-     no loop pacing. Else Step 4 uses the BUGBOT inline-lag section of
-     `../workflows/schedule-wakeup-loop.md` (`delaySeconds: 90`).
 
 ### `phase == BUGTEAM`
 
@@ -119,13 +119,28 @@ Skill({skill: "bugteam", args:
      bugteam by reading [`../../bugteam/SKILL.md`](../../bugteam/SKILL.md). Same
      loop and gates; only harness steps differ.
 
-b. **Re-resolve current HEAD** — bugteam may have pushed commits during
-its run. `current_head` from Step 1 is potentially stale:
-   ```bash
-pull_request_read(owner=OWNER, repo=REPO, pullNumber=NUMBER, method="get") → `.head.sha`
+b. **Re-resolve current HEAD (MANDATORY — never skip).** Bugteam may have
+pushed commits during its run. `current_head` from Step 1 is stale:
+
+   ```
+   pull_request_read(owner=OWNER, repo=REPO, pullNumber=NUMBER, method="get") → `.head.sha`
+   ```
+
+   Capture `new_head`. Then check the most recent commit timestamp:
+
+   ```
+   list_commits(owner=OWNER, repo=REPO, sha="<branch>")
+     → sort by `.commit.committer.date` descending → index 0 `.commit.committer.date`
    ```
-If `new_head != current_head`, set `current_head = new_head` AND
-`bugbot_clean_at = null`. New commits invalidate bugbot's prior clean.
+
+   If the most recent commit timestamp is **less than 60 seconds ago**, the
+   GitHub API may not have propagated it to review endpoints yet. Do not
+   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.
 
 c. Inspect bugteam outcome. Reports `convergence (zero findings)` or list
 of unfixed findings with file:line.
@@ -137,34 +152,95 @@ never falsely terminates:
      Re-trigger bugbot same tick (Step 3) so new HEAD enters queue, `phase
      = BUGBOT`, schedule next wakeup, return.
    - **Convergence AND `bugbot_clean_at == current_head` (no push):**
-     Back-to-back clean — necessary, not sufficient. Run **[convergence-gates.md](convergence-gates.md)** to clear Copilot-findings, mergeability, post-convergence
-     Copilot-request. Only when all four gates pass mark PR ready and
+     Back-to-back clean — necessary, not sufficient. Run **[convergence-gates.md](convergence-gates.md)** to clear all six gates: Copilot findings,
+     Claude reviewer, mergeability, post-convergence Copilot request,
+     thread resolution. Only when all six gates pass mark PR ready and
      **omit loop pacing** per **Convergence** of active pacing workflow.
    - **Convergence BUT `bugbot_clean_at != current_head` (no push):**
      `phase = BUGBOT`, schedule next wakeup, return.
-   - **Findings without committed fixes:** spawn Agent (subagent_type: clean-coder) to implement fixes and push, then reply inline via `add_reply_to_pull_request_comment` MCP, following [Single-PR fix workflow](fix-protocol.md#single-pr-fix-workflow).
+   - **Findings without committed fixes:** spawn Agent (subagent_type: clean-coder) to implement fixes and push, then reply inline via `python ~/.claude/skills/pr-converge/scripts/post_fix_reply.py`, following [Single-PR fix workflow](fix-protocol.md#single-pr-fix-workflow).
      `phase = BUGBOT`, schedule next wakeup, return.
 
-## Step 3: Re-trigger bugbot
+### `phase == COPILOT_WAIT`
 
-Use the `add_issue_comment` MCP tool:
+Post-convergence Copilot re-check. Enters after gate (d) requests Copilot
+review. Do **not** run bugteam here — that only happens after BUGBOT clean
+on this HEAD.
 
-    add_issue_comment(owner="OWNER", repo="REPO", issueNumber=NUMBER, body="bugbot run")
+a. Fetch latest Copilot review at `current_head` plus unaddressed inline
+   comments:
 
-`bugbot run` is empirically the only re-trigger Cursor Bugbot recognizes;
-alternative phrasings (`re-review`, `bugbot please`, etc.) silently no-op.
+   ```
+python ~/.claude/skills/pr-converge/scripts/fetch_copilot_reviews.py --owner <O> --repo <R> --pr-number <N>
+  → filter by `.commit_id == current_head`, sort by `.submitted_at` descending
+
+python ~/.claude/skills/pr-converge/scripts/fetch_copilot_inline_comments.py --owner <O> --repo <R> --pr-number <N> --commit <current_head>
+  → unaddressed inline threads on the latest Copilot review at current_head
+   ```
 
-**Gotcha (duplicate `bugbot run` while review queued):** Skip Step 3 when
-the latest `bugbot run` PR comment has an `:eyes:` or `:+1:` reaction; wait
-for review or HEAD change before re-triggering.
+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 review dirty (CHANGES_REQUESTED or COMMENTED with findings)
+     at `current_head`:** Apply **Fix protocol** — spawn Agent
+     (subagent_type: clean-coder) to implement → push → reply inline on each
+     thread via `python ~/.claude/skills/pr-converge/scripts/post_fix_reply.py`. For body-only
+     findings (no inline threads), post top-level review reply citing new
+     HEAD SHA. Reset
+     `bugbot_clean_at = null` AND `copilot_clean_at = null`. **Set
+     `phase = BUGBOT`** (NOT COPILOT_WAIT) — every fix push requires a full
+     back-to-back-clean cycle on the new HEAD. Schedule next wakeup, return.
+   - **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
+     blocker per [stop-conditions.md](stop-conditions.md). Otherwise
+     schedule next wakeup (360s), return.
+
+**Non-negotiable:** After any Copilot fix push, `phase` MUST route to
+`BUGBOT`. Never cycle COPILOT_WAIT → fix → COPILOT_WAIT. The
+back-to-back-clean guarantee (bugbot ∧ bugteam both clean on same HEAD
+before gates re-open) only holds when every fix commit re-enters through
+BUGBOT.
+
+## Step 3: Re-trigger bugbot
+
+- [ ] **Opt-out gate.** When `CLAUDE_REVIEWS_DISABLED` (comma-separated,
+  case-insensitive, whitespace-tolerant) contains `bugbot`, set
+  `bugbot_down = true`, skip every check below, set `phase = BUGTEAM`,
+  and continue BUGTEAM in the same tick. The downstream loop branches on
+  `bugbot_down` exactly the way it does when bugbot CI is unavailable.
+- [ ] **Silent-pass pre-check.** Run `python ~/.claude/skills/pr-converge/scripts/check_bugbot_ci.py --check-clean --owner <O> --repo <R> --sha <current_head>`
+- [ ] Exit 0 → bugbot CI completed clean with no review (silent pass); set `bugbot_clean_at = current_head`, `phase = BUGTEAM`, continue BUGTEAM same tick
+- [ ] Exit 1 (not a silent pass) or Exit 2 (gh CLI error — silent pass not confirmable) → continue with the trigger flow below
+- [ ] Run `python ~/.claude/skills/pr-converge/scripts/check_bugbot_ci.py --check-active --owner <O> --repo <R> --sha <current_head>`
+- [ ] Exit 0 → bugbot already queued on this commit; skip posting, wait for completion
+- [ ] Exit 1 → post trigger via `add_issue_comment(owner="OWNER", repo="REPO", issueNumber=NUMBER, body="bugbot run")`
+- [ ] Wait 8s
+- [ ] Run `python ~/.claude/skills/pr-converge/scripts/check_bugbot_ci.py --owner <O> --repo <R> --sha <current_head>`
+- [ ] Exit non-zero → bugbot is down; set `bugbot_down = true`, `phase = BUGTEAM`, continue BUGTEAM same tick
+- [ ] Exit 0 (check run present) → record `bugbot_acknowledged_at = <now ISO 8601>`, proceed to Step 4
+
+The silent-pass pre-check fires FIRST so we never re-trigger a bot that
+already finished cleanly. Cursor Bugbot communicates "no findings" by
+completing the CI check with `conclusion: success` (or `neutral`) and
+posting no review. The pre-check treats that outcome as
+`bugbot_clean_at = current_head`, equivalent to an explicit clean
+review. Without it, the trigger flow would re-prompt a bot that has
+already evaluated this commit and refuses to re-run, and the bypass
+branch would falsely mark `bugbot_down = true`.
+
+`bugbot run` is empirically the only re-trigger Cursor Bugbot recognizes;
+alternative phrasings silently no-op.
 
 ## Step 4: Loop pacing
 
 **`ScheduleWakeup` field hints** (prefer [Pacing
 workflow](#pacing-workflow)):
 
-- `delaySeconds: 270` after bugbot re-trigger. Bugbot finishes in 1–4
-  min; 270s stays under 5-min prompt-cache TTL with margin. Exception:
+- `delaySeconds: 360` after bugbot re-trigger. Exception:
   BUGBOT inline-lag branch uses `delaySeconds: 90` (no re-trigger;
   awaiting GitHub inline API).
 - `reason`: short sentence on what is awaited, including `phase` and

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

@@ -6,12 +6,33 @@ counters, status, not conversation transcript. No `state.json` (typical
 single-PR `/pr-converge`) → track in each assistant turn as
 plain text so next tick re-reads from context:
 
-- `phase`: `BUGBOT` or `BUGTEAM`. Start `BUGBOT` on first tick.
+- `phase`: `BUGBOT`, `BUGTEAM`, or `COPILOT_WAIT`. Start `BUGBOT` on first tick.
 - `bugbot_clean_at`: HEAD SHA where bugbot last reported clean, or `null`.
   Reset to `null` on every push.
+- `copilot_clean_at`: HEAD SHA where Copilot last reported clean, or `null`.
+  Reset to `null` on every push.
+- `copilot_wait_count`: integer, init `0`. Consecutive COPILOT_WAIT ticks
+  with no Copilot review surfaced at `current_head`. Escalate as hard blocker
+  at `>= 3`. Reset to `0` when a Copilot review surfaces at `current_head`
+  (APPROVED or dirty) or on any non-COPILOT_WAIT branch.
 - `inline_lag_streak`: integer, init `0`. Consecutive ticks where review
   body shows findings against `current_head` but inline API returns zero
   matching. Reset to `0` on any other branch outcome.
+- `bugbot_down`: boolean, init `false`. Set `true` when bugbot fails to
+  acknowledge a trigger comment; forces phase to BUGTEAM. Also set `true`
+  when an acknowledged trigger has been outstanding more than 30 minutes
+  with no surfaced review at `current_head` (per Step 2 BUGBOT (c)
+  30-minute budget — see `per-tick.md`). Reset to `false` on every push.
+  Once set, remains `true` until the next push; if bugbot stays down
+  across ticks, the flag persists and BUGTEAM continues.
+- `bugbot_acknowledged_at`: ISO 8601 timestamp string or `null`. Records
+  the wall-clock moment Cursor Bugbot acknowledged the most recent
+  `bugbot run` trigger comment (i.e. the trigger comment carries an
+  `:eyes:`/`:+1:` reaction). Init `null`. Set in Step 3 once the
+  reaction-check fires positive. Reset to `null` on every push and on
+  every BUGTEAM jump triggered by the 30-minute budget. Step 2 BUGBOT
+  (c) reads this field to decide between "schedule next wakeup" and
+  "escalate to bugbot-down".
 - `tick_count`: integer, init `0`. Increment every tick.
 
 Tick begins reading prior state line from most recent assistant message

package/skills/pr-converge/reference/stop-conditions.md

@@ -1,12 +1,14 @@
 # Stop conditions
 
-- **Convergence** (back-to-back clean ∧ no outstanding Copilot findings
-  on `current_head` ∧ `mergeable_state == "clean"` with `mergeable ==
-  true` ∧ post-convergence Copilot request returned `clean` at
-  `current_head`): use `update_pull_request(pullNumber=NUMBER, owner=OWNER, repo=REPO, draft=false)`. With
+- **Convergence** (back-to-back clean ∧ all six gates pass per
+  [convergence-gates.md](convergence-gates.md) gate (f) checklist:
+  Copilot clean at `current_head`, Claude clean or absent,
+  `mergeable_state == "clean"` with `mergeable == true`,
+  post-convergence Copilot review `APPROVED`, zero unresolved bot
+  threads): use `update_pull_request(pullNumber=NUMBER, owner=OWNER, repo=REPO, draft=false)`. With
   `state.json`, append convergence row to
   `<TMPDIR>/pr-converge-<session_id>/converged.log` per `multi-pr-orchestration.md` §Memory; else
-  skip. Report [convergence-gates.md](convergence-gates.md) (d) summary, then **omit loop pacing**
+  skip. Report [convergence-gates.md](convergence-gates.md) (f) summary, then **omit loop pacing**
   per **Convergence** in `../workflows/schedule-wakeup-loop.md`. End all loops
   once all PRs terminal (converged or blocked).
 - **Hard blocker:** API auth failure across two ticks, CI regression
@@ -17,8 +19,8 @@
   blocker and diagnosis, **omit loop pacing** per
   `../workflows/schedule-wakeup-loop.md`.
 - **Hard blocker (`mergeable_state` non-clean non-dirty):**
-  `mergeable_state` is `"blocked"`, `"unknown"`, or `"behind"` (required
-  checks pending, branch behind base without textual conflicts, or
+  `mergeable_state` is `"blocked"`, `"unknown"`, `"behind"`, or `"unstable"` (required
+  checks pending/failing, branch behind base without textual conflicts, or
   GitHub indeterminate). Investigate before retrying; `rebase` skill
   handles `"dirty"` (textual conflicts) only. Report specific
   `mergeable_state`, **omit loop pacing**.

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

@@ -20,11 +20,11 @@ Fetch all reviews and filter for `cursor[bot]`:
 
 Classification: clean if review body has no findings count; dirty if body matches "found N potential issue".
 
-### Bugbot inline comments: `pull_request_read(method="get_review_comments")`
+### Inline comment threads (used by BUGBOT phase and convergence gate (e))
 
-Fetch all review comments and filter for `cursor[bot]`, matching `pull_request_review_id` to the newest Bugbot review on the target commit:
-
-    pull_request_read(method="get_review_comments", pullNumber=NUMBER, owner=OWNER, repo=REPO)
+Fetch all unresolved inline threads on the PR. The convergence gate is
+author-agnostic and commit-agnostic — see "Inline comment threads"
+below for the canonical fetch.
 
 ### PR head SHA: `pull_request_read(method="get")`
 
@@ -38,7 +38,7 @@ Access `.head.sha` from the response.
 
 Post the bugbot re-trigger comment:
 
-    add_issue_comment(owner="OWNER", repo="REPO", issueNumber=NUMBER, body="bugbot run")
+    add_issue_comment(owner="OWNER", repo="REPO", issue_number=NUMBER, body="bugbot run")
 
 `bugbot run` is the only recognized re-trigger phrase; alternative phrasings silently no-op.
 
@@ -48,17 +48,16 @@ Mark a draft PR as ready for review:
 
     update_pull_request(pullNumber=NUMBER, owner=OWNER, repo=REPO, draft=false)
 
-### Reply to inline comment: `add_reply_to_pull_request_comment`
+### Reply to inline comment: `python scripts/post_fix_reply.py`
 
 Reply to an inline review comment thread:
 
-    add_reply_to_pull_request_comment(
-      commentId=COMMENT_ID,
-      body=REPLY_BODY,
-      owner=OWNER,
-      repo=REPO,
-      pullNumber=NUMBER
-    )
+```
+python scripts/post_fix_reply.py --owner <O> --repo <R> --pr-number <N> \
+  --in-reply-to <COMMENT_ID> --body "<reply text>"
+```
+
+Omit `--in-reply-to` to post a general PR comment instead.
 
 ### Mergeability: `pull_request_read(method="get")`
 
@@ -68,52 +67,41 @@ Read mergeability fields from the PR:
 
 Fields: `.mergeable`, `.mergeable_state`, `.head.sha`.
 
-### Copilot reviews: `pull_request_read(method="get_reviews")`
+### Copilot reviews: `python scripts/fetch_copilot_reviews.py`
 
-Fetch all reviews and filter for `copilot-pull-request-reviewer[bot]`:
+```
+python scripts/fetch_copilot_reviews.py --owner <O> --repo <R> --pr-number <N>
+```
 
-    pull_request_read(method="get_reviews", pullNumber=NUMBER, owner=OWNER, repo=REPO)
+Returns JSON array of Copilot reviews newest-first. Classification:
+`APPROVED` → clean, `CHANGES_REQUESTED` → dirty, `COMMENTED` with
+non-empty body → dirty.
 
-Classification: `APPROVED` → clean, `CHANGES_REQUESTED` → dirty, `COMMENTED` with non-empty body → dirty.
+### Inline comment threads: `pull_request_read(method="get_review_comments")`
 
-### Copilot inline comments: `pull_request_read(method="get_review_comments")`
-
-Fetch all review comments and filter for `copilot-pull-request-reviewer[bot]`, matching `pull_request_review_id` to the newest Copilot review on the target commit:
+Fetch via MCP. The convergence gate filters ONLY on resolution state:
 
     pull_request_read(method="get_review_comments", pullNumber=NUMBER, owner=OWNER, repo=REPO)
+      → filter threads where `is_resolved == false`
 
-### Request Copilot review: `add_issue_comment` or `request_copilot_review`
-
-Two options:
-
-1. Comment-based trigger:
-   ```
-   add_issue_comment(owner=OWNER, repo=REPO, issueNumber=NUMBER, body="@copilot review")
-   ```
-2. Dedicated MCP tool (when available):
-   ```
-   request_copilot_review(owner=OWNER, repo=REPO, pullNumber=NUMBER)
-   ```
+The fields `comment.author`, `comment.commit.oid`, and `is_outdated`
+remain useful for **deciding how to address** each unresolved thread
+(re-fix? reply-with-note?), but they do not exclude a thread from the
+count.
 
-The `[bot]` suffix is load-bearing per `../../copilot-review/SKILL.md`.
+### Request Copilot review: `gh api` REST endpoint
 
-### Claude reviews: `pull_request_read(method="get_reviews")`
+```
+gh api --method POST repos/<O>/<R>/pulls/<N>/requested_reviewers \
+  -f 'reviewers[]=copilot-pull-request-reviewer[bot]'
+```
 
-Fetch all reviews and filter for login containing `claude`:
-
-    pull_request_read(method="get_reviews", pullNumber=NUMBER, owner=OWNER, repo=REPO)
-
-Classification: same state-based rules as Copilot reviews.
-
-### Claude inline comments: `pull_request_read(method="get_review_comments")`
-
-Fetch all review comments and filter for login containing `claude`, matching `pull_request_review_id` to the newest Claude review on the target commit:
-
-    pull_request_read(method="get_review_comments", pullNumber=NUMBER, owner=OWNER, repo=REPO)
+Check for an existing pending review first with
+`python scripts/check_pending_reviews.py --owner <O> --repo <R> --pr-number <N> --user copilot`.
 
 ## Shared modules
 
-No shared fetch core modules are needed. Each review or comment fetch is a single MCP tool call with client-side filtering by login.
+Shared Python utilities live under `_shared/pr-loop/scripts/` — `_xml_utils.py` for XML serialization, `_cli_utils.py` for CLI guards, `_path_resolver.py` for canonical path resolution. These serve `/bugteam`, `/qbug`, `/findbugs`, and `/fixbugs` equally.
 
 ## Tests