claude-dev-env 1.38.1 → 1.40.0

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

@@ -3,7 +3,13 @@
 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 four pass.
+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
+reference evidence from each prior gate. Skipping any gate silently is a
+hard blocker — report "gate evidence missing: <gate name>" and omit loop
+pacing. Do not mark ready with unverified gates.
 
 ## (a) Copilot findings gate
 
@@ -12,12 +18,11 @@ plus inline comments anchored to most recent Copilot review on
 `current_head`:
 
 ```
-pull_request_read(owner=OWNER, repo=REPO, pullNumber=NUMBER, method="get_reviews")
-  → filter `.user.login` for copilot (case-insensitive substring "copilot")
-  → sort by `.submitted_at` descending
+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
 
-pull_request_read(owner=OWNER, repo=REPO, pullNumber=NUMBER, method="get_review_comments")
-  → filter threads where `is_outdated == false` AND any comment has `.author` matching Copilot (case-insensitive substring "copilot")
+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
 ```
 
 Decide (four branches; match first whose predicate holds):
@@ -25,28 +30,63 @@ 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). 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
+  `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).
   Reset `bugbot_clean_at = null` AND `copilot_clean_at = null`, `phase =
   BUGBOT`, schedule next wakeup, return. Full back-to-back-clean cycle
-  plus all four gates must hold again on new HEAD.
+  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. Spawn Agent (subagent_type: clean-coder) to implement → push → post
-  top-level review reply using `pull_request_review_write(method="create", event="COMMENT", body)` citing new HEAD SHA → Step 3 in same tick.
+  top-level review reply via `python ~/.claude/skills/pr-converge/scripts/post_fix_reply.py` citing 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,
   schedule next wakeup, return. Convergence requires full
   back-to-back-clean on new HEAD.
 - **`classification == "clean"` (state `APPROVED`):** Set
-  `copilot_clean_at = current_head`. Continue to gate (b).
-- **No Copilot review on `current_head` yet:** Skip — gate (c) issues
-  proactive request. Continue to gate (b).
+  `copilot_clean_at = current_head`. Record evidence: "Copilot APPROVED at <SHA>".
+  Continue to gate (b).
+- **No Copilot review on `current_head` yet:** Record evidence: "No Copilot review at <SHA>".
+  Skip — gate (d) issues proactive request. Continue to gate (b).
+
+## (b) Claude reviewer gate
+
+Fetch latest Claude reviewer (`claude[bot]`) review plus inline comments
+anchored to most recent Claude review on `current_head`:
+
+```
+pull_request_read(owner=OWNER, repo=REPO, pullNumber=NUMBER, method="get_reviews")
+  → filter `.user.login` for claude (case-insensitive substring "claude")
+    AND `.commit_id == current_head`
+  → sort by `.submitted_at` descending
+
+pull_request_read(owner=OWNER, repo=REPO, pullNumber=NUMBER, method="get_review_comments")
+  → filter threads where `is_resolved == false`
+```
 
-## (b) Mergeability gate
+Decide (four branches; match first whose predicate holds):
+
+- **`classification == "dirty"` with non-empty inline comments matching
+  `pull_request_review_id`:** Treat identically to gate (a) dirty+inline
+  path — spawn Agent (subagent_type: clean-coder) to fix → push → reply inline on each thread. Reset
+  `bugbot_clean_at = null` AND `copilot_clean_at = null`, `phase = BUGBOT`,
+  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 — spawn Agent
+  (subagent_type: clean-coder) to implement → push → post top-level review reply via `python ~/.claude/skills/pr-converge/scripts/post_fix_reply.py`. Reset
+  `bugbot_clean_at = null` AND `copilot_clean_at = null`, `phase = BUGBOT`,
+  schedule next wakeup, return.
+- **`classification == "clean"` (state `APPROVED`):** Record evidence:
+  "Claude APPROVED at <SHA>". Continue to gate (c).
+- **No Claude review on `current_head` yet:** Record evidence:
+  "Claude absent at <SHA>". Continue to gate (c).
+
+## (c) Mergeability gate
 
 Resolve PR's mergeability state:
 
@@ -58,7 +98,8 @@ pull_request_read(owner=OWNER, repo=REPO, pullNumber=NUMBER, method="get")
 Persist `mergeable_state` into `merge_state_status`. Decide:
 
 - **`mergeable_state == "clean"` AND `mergeable == true`:**
-  Continue to gate (c).
+  Record evidence: "mergeable_state clean, mergeable=true at <SHA>".
+  Continue to gate (d).
 - **`mergeable_state == "dirty"` (or `mergeable == false`):** Do
   **not** mark ready. Invoke **`rebase`** skill
   ([`../../rebase/SKILL.md`](../../rebase/SKILL.md)) Phase 1–4 against PR's
@@ -67,47 +108,99 @@ Persist `mergeable_state` into `merge_state_status`. Decide:
   `copilot_clean_at = null`, `merge_state_status = null`, `phase = BUGBOT`,
   Step 3 on new HEAD, schedule next wakeup, return. Loop re-runs from
   scratch on new HEAD.
-- **`mergeable_state` is `"blocked"`, `"behind"`, or `"unknown"` for
-  non-conflict reasons** (required checks pending, branch behind base
-  without conflicts GitHub cannot auto-resolve): **hard blocker** per
+- **`mergeable_state` is `"blocked"`, `"behind"`, `"unknown"`, or `"unstable"` for
+  non-conflict reasons** (required checks pending/failing for "unstable",
+  branch behind base without conflicts for "behind", GitHub indeterminate
+  for "unknown"): **hard blocker** per
   [stop-conditions.md](stop-conditions.md) — do not invent a fix. Report specific
   `mergeable_state`, omit loop pacing.
 
-## (c) Post-convergence Copilot review request
+## (d) Post-convergence Copilot review request
 
-Once gates (a) and (b) both pass (Copilot clean at `current_head` *or* no
-Copilot review yet, AND `mergeable_state == "clean"`), request Copilot
-review:
+Once gates (a), (b), and (c) all pass (Copilot clean at `current_head` *or* no
+Copilot review yet, AND Claude clean or absent at `current_head`, AND
+`mergeable_state == "clean"`), request Copilot review:
 
 ```
-request_copilot_review(owner=OWNER, repo=REPO, pullNumber=NUMBER)
+gh api --method POST repos/<O>/<R>/pulls/<N>/requested_reviewers \
+  -f 'reviewers[]=copilot-pull-request-reviewer[bot]'
 ```
 
-When the `request_copilot_review` MCP tool is unavailable, use `add_issue_comment` as fallback: `add_issue_comment(owner=OWNER, repo=REPO, issueNumber=NUMBER, body="@copilot review")`.
+Check for an existing pending review first with
+`python ~/.claude/skills/pr-converge/scripts/check_pending_reviews.py --owner <O> --repo <R> --pr-number <N> --user copilot`.
+
+After request, set `phase = COPILOT_WAIT`, schedule next wakeup, and return.
+The COPILOT_WAIT phase prevents the agent from re-entering convergence gates
+while Copilot processes. Next tick with `phase == COPILOT_WAIT`:
+re-run the fetch from gate (a) — `python ~/.claude/skills/pr-converge/scripts/fetch_copilot_reviews.py`
+plus MCP `get_review_comments` filtered for Copilot inline threads —
+against `current_head`. Decide:
+
+- **Copilot review present at `current_head`:**
+  - `state: APPROVED` → set `copilot_clean_at = current_head`. Record
+    evidence: "Copilot APPROVED at <SHA>". Re-validate gates (b) and (c)
+    on same tick (Claude status and mergeability may have changed while
+    waiting). Set `phase = BUGTEAM`.
+    Continue to gate (e) when (b) and (c) still pass.
+  - `state: CHANGES_REQUESTED` or `COMMENTED` with non-empty body → dirty.
+    Treat identically to gate (a) dirty path — spawn Agent (subagent_type: clean-coder) to fix,
+    reset `bugbot_clean_at = null` AND `copilot_clean_at = null`,
+    `phase = BUGBOT`, 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
+  successful Copilot review). After three consecutive empty waits
+  (`copilot_wait_count >= 3`), escalate as hard blocker — report
+  "Copilot did not surface a review on current_head after 3 wakeups"
+  and omit loop pacing. Otherwise schedule next wakeup (360s), return.
+
+## (e) Thread-resolution gate
+
+Before marking ready, count ALL unresolved review threads on the PR:
+
+```
+pull_request_read(owner=OWNER, repo=REPO, pullNumber=NUMBER, method="get_review_comments")
+  → filter threads where `is_resolved == false`
+  → count
+```
+
+When you address an unresolved thread, you still need its author and
+anchor commit so you can decide how to fix it — but the gate doesn't
+filter on those fields.
+
+Decide:
+
+- **Zero unresolved threads:** Record evidence:
+  "0 unresolved threads across PR at <SHA>". Continue to gate (f).
+- **One or more unresolved threads:** Do **not** mark ready. For each
+  unresolved thread, verify the concern against current HEAD. If still
+  applies, apply Fix protocol (test → fix → push → reply → resolve). If
+  no longer applies (e.g. code already changed), reply-with-note
+  explaining why and resolve. Push if any code changed → reset
+  `bugbot_clean_at = null` AND `copilot_clean_at = null`,
+  `phase = BUGBOT`, schedule next wakeup, return. If only resolutions
+  (no code changes), re-check this gate without resetting.
 
-After request, schedule next wakeup and return — next tick checks response.
+## (f) Mark ready and report
 
-Next tick with `phase == BUGTEAM` and prior state preserved → re-run gate
-(a) first. Decide:
+**Mandatory pre-condition checklist.** Before calling `update_pull_request`,
+verify ALL seven conditions below. Three are preconditions from the main
+loop (bugbot clean, bugteam convergence, no intervening push); four are
+evidence from gates (a)–(e) above. All seven must be confirmed:
 
-- **Copilot review `clean` (state `APPROVED`):** Set `copilot_clean_at =
-  current_head`. Mark PR ready (`update_pull_request(pullNumber=NUMBER, owner=OWNER, repo=REPO, draft=false)`), report convergence
-  per §(d), terminate per [stop-conditions.md](stop-conditions.md) / Convergence.
-- **Copilot review `dirty`:** Treat identically to gate (a) dirty path —
-  spawn Agent (subagent_type: clean-coder) to fix in same PR, restart convergence from BUGBOT. Follow [Single-PR fix workflow](fix-protocol.md#single-pr-fix-workflow).
-  For body-only findings with empty inline, spawn Agent (subagent_type: clean-coder) to implement, then post top-level review reply
-  citing new HEAD SHA. Reset `bugbot_clean_at = null` AND
-  `copilot_clean_at = null`, `phase = BUGBOT`, schedule next wakeup,
-  return. Full back-to-back-clean cycle plus all four gates must hold
-  again on new HEAD.
-- **No Copilot review at `current_head` yet (still propagating):**
-  Schedule one more wakeup (270s), re-check next tick. After three consecutive empty waits,
-  escalate as hard blocker per [stop-conditions.md](stop-conditions.md).
+- [ ] `bugbot_clean_at == current_head` (from per-tick.md Step 2 BUGBOT §c)
+- [ ] bugteam `convergence (zero findings)` at `current_head` (from per-tick.md Step 2 BUGTEAM §d)
+- [ ] `copilot_clean_at == current_head` (from gate (a) or gate (d))
+- [ ] Claude `APPROVED` or absent at `current_head` (from gate (b))
+- [ ] `mergeable_state == "clean"` AND `mergeable == true` (from gate (c))
+- [ ] Zero unresolved review threads anywhere on the PR (from gate (e))
+- [ ] No push since bugteam convergence (from per-tick.md Step 2 BUGTEAM §b)
 
-## (d) Mark ready and report
+If ANY checkbox cannot be confirmed with evidence, do NOT mark ready.
+Report the specific missing condition and route through the appropriate
+fix path (BUGBOT for dirty reviews, rebase for merge conflicts, etc.).
 
-Only when all four gates pass — bugbot CLEAN ∧ bugteam CLEAN ∧
-`mergeable_state == "clean"` ∧ Copilot CLEAN at HEAD — run:
+Only when ALL seven conditions are confirmed:
 
 Use the `update_pull_request` MCP tool:
 
@@ -116,5 +209,6 @@ Use the `update_pull_request` MCP tool:
 With `state.json`, append convergence row to
 `<TMPDIR>/pr-converge-<session_id>/converged.log` per `multi-pr-orchestration.md` §Memory; else skip.
 Report: `PR #<NUMBER> converged: bugbot CLEAN at <SHA>, bugteam CLEAN at
-<SHA>, mergeable_state CLEAN, copilot CLEAN at <SHA>; marked ready for
-review`. **Omit loop pacing** per **Convergence** of active pacing workflow.
+<SHA>, mergeable_state clean, copilot CLEAN at <SHA>, claude <APPROVED|absent>
+at <SHA>, 0 unresolved threads across PR; marked ready for review`.
+**Omit loop pacing** per **Convergence** of active pacing workflow.

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

@@ -25,9 +25,33 @@ convergence or stop]
 </example>
 
 <example> BUGTEAM phase, bugteam reports convergence and `bugbot_clean_at
-== current_head`. Claude: [runs `update_pull_request(pullNumber=NUMBER, owner=OWNER, repo=REPO, draft=false)`, reports "PR
-converged: bugbot CLEAN at <SHA>, bugteam CLEAN at <SHA>; marked ready for
-review", applies **Convergence** from `workflows/schedule-wakeup-loop.md`]
+== current_head` (no push). Claude: [back-to-back clean — necessary, not
+sufficient. 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`
+    → record evidence, set `copilot_clean_at = current_head`.
+  Gate (b): two calls — `pull_request_read(method="get_reviews")` +
+    `pull_request_read(method="get_review_comments")`
+    → filter Claude → absent at `current_head`
+    → record evidence, continue (trivially clean).
+  Gate (c): `pull_request_read(method="get")` → `.mergeable_state == "clean"`
+    AND `.mergeable == true` → record evidence.
+  Gate (d): set `phase = COPILOT_WAIT`;
+    `request_copilot_review(owner=OWNER, repo=REPO, pullNumber=NUMBER)`
+    → 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).
+  Gate (e): `pull_request_read(method="get_review_comments")` → count
+    threads where `is_resolved == false` (no author/commit/outdated
+    filter) → zero across PR → record evidence.
+  Gate (f): all six gates pass → `update_pull_request(pullNumber=NUMBER,
+    owner=OWNER, repo=REPO, draft=false)`.
+Reports "PR #N converged: bugbot CLEAN at <SHA>, bugteam CLEAN at <SHA>,
+mergeable_state clean, copilot CLEAN at <SHA>, claude absent at <SHA>,
+0 unresolved threads across PR; marked ready for review",
+applies **Convergence** from `workflows/schedule-wakeup-loop.md`]
 </example>
 
 <example> BUGTEAM phase, bugteam pushed fix commit during run. Claude:
@@ -42,7 +66,7 @@ HEAD but inline API returns zero matching for `current_head`. Claude:
 </example>
 
 <example> Back-to-back clean reached, but `mergeStateStatus: DIRTY` (base
-advanced, merge conflicts). Claude: [runs §Convergence gates (b); does NOT
+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`,
@@ -58,19 +82,27 @@ HEAD, schedules next wakeup]
 </example>
 
 <example> Back-to-back clean, mergeability CLEAN, no Copilot review on
-`current_head`. Claude requests Copilot via `add_issue_comment(owner=OWNER, repo=REPO, issueNumber=NUMBER, body="@copilot review")`,
-waits one tick. Next tick: Copilot review `state: APPROVED`. Claude: [sets
-`copilot_clean_at = current_head`; runs `update_pull_request(pullNumber=NUMBER, owner=OWNER, repo=REPO, draft=false)`; reports "PR
-#N converged: bugbot CLEAN at <SHA>, bugteam CLEAN at <SHA>,
-mergeable_state clean, copilot CLEAN; marked ready for review"]
+`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`;
+re-validates gates (b) Claude absent and (c) mergeability clean,
+records evidence for both; gate (e) zero unresolved threads passes
+trivially, record evidence: "0 unresolved threads across PR at <SHA>";
+runs `update_pull_request(pullNumber=NUMBER,
+owner=OWNER, repo=REPO, draft=false)`; reports "PR #N converged: bugbot CLEAN
+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
-`current_head`. Claude: [does NOT mark PR ready — gate (4) failed;
+`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 four
+HEAD; schedules next wakeup. 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,12 +8,13 @@ per [ground-rules.md](ground-rules.md).
 **Multi-PR (`state.json`) teammate obligations** (plus TDD, commit, push):
 
 - Replies inline on each addressed finding via
-  `add_reply_to_pull_request_comment(owner, repo, pullNumber, commentId, body)`
+  `python scripts/post_fix_reply.py --owner <O> --repo <R> --pr-number <N> --in-reply-to <COMMENT_ID> --body <text>`
   (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`, `phase: "BUGBOT"`, `status: "awaiting_bugbot"`,
-  `last_updated` (ISO-8601 UTC) to `state.json` (per §Concurrency).
+  `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.
 
@@ -40,10 +41,10 @@ git push origin <BRANCH>
   ```
 **Pre-push gate:** honor hooks; full-stop on bypass. Capture new HEAD
 only after both gates pass; set `current_head`, `bugbot_clean_at = null`.
-- Reply inline on each addressed comment thread using the `add_reply_to_pull_request_comment` MCP tool:
+- Reply inline on each addressed comment thread using `python scripts/post_fix_reply.py`:
 
   ```
-  add_reply_to_pull_request_comment(owner=OWNER, repo=REPO, pullNumber=NUMBER, commentId=COMMENT_ID, body="Fixed in <SHA> — <what changed>")
+  python scripts/post_fix_reply.py --owner <O> --repo <R> --pr-number <N> --in-reply-to <COMMENT_ID> --body "Fixed in <SHA> — <what changed>"
   ```
 - **After pushing a fix, always run Step 3 (`bugbot run`) in the same
   tick** regardless of phase. New commit **resets full convergence cycle**:

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

@@ -3,11 +3,13 @@
 - **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`.**
-- **All `*_clean_at` and `merge_state_status` reset on every push.**
+- **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.
-- **Honor pre-push and pre-commit hooks.** Read output, fix the cause,
-  retry. Full-stop on bypass.
+- **All production edits go through `clean-coder`.** The lead never edits
+  production files directly. Every fix — bugbot, bugteam, Copilot, or
+  Claude finding — spawns `Agent(subagent_type="clean-coder")` to
+  implement. No exceptions.
 - **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).

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

@@ -42,6 +42,7 @@ Create once at session start. Each teammate writes result before going idle.
       "current_head": "f9a7d49e",
       "bugbot_clean_at": null,
       "inline_lag_streak": 0,
+      "bugbot_down": false,
       "tick_count": 5,
       "last_action": "bugbot_triggered",
       "status": "in_progress",
@@ -109,14 +110,15 @@ Bugfind subagent completes (findings or clean):
   4. Replies inline on each addressed finding via
      `add_reply_to_pull_request_comment(owner, repo, pullNumber, commentId, body)`.
   5. Writes `state.json` (per §Concurrency): `last_action: "fix_pushed"`,
-     `current_head: <new SHA>`, `bugbot_clean_at: null`, `phase:
+     `current_head: <new SHA>`, `bugbot_clean_at: null`,
+     `bugbot_down: false`, `phase:
      "BUGBOT"`, `status: "awaiting_bugbot"`, `last_updated` ISO-8601 UTC.
   6. Goes idle.
 
 - **PRs with zero findings:** spawn one `general-purpose` subagent per PR via
   `Agent(subagent_type="general-purpose", run_in_background=true)`. Subagent:
   1. `bugbot_clean_at == current_head` (back-to-back clean): run
-     `update_pull_request(pullNumber=PR_NUMBER, owner=OWNER, repo=REPO, draft=false)`, append convergence row to
+     `update_pull_request(pullNumber=NUMBER, owner=OWNER, repo=REPO, draft=false)`, append convergence row to
      `<TMPDIR>/pr-converge-<session_id>/converged.log` per §Memory, then
      write `state.json` (per §Concurrency) with `status: "converged"`,
      `last_action: "converged"` (or `marked_ready`), `phase: "BUGBOT"`,
@@ -125,8 +127,18 @@ Bugfind subagent completes (findings or clean):
      duplicate work.
   2. Else: update `state.json` (per §Concurrency) with `last_action:
      "audit_clean"`, `status: "awaiting_bugbot"`, `phase: "BUGBOT"`, then
-     trigger bugbot via `add_issue_comment(owner, repo, issueNumber, body="bugbot run")`.
-  3. Goes idle.
+     trigger bugbot via `add_issue_comment(owner, repo, issue_number, body="bugbot run")`.
+  3. **Bugbot-down detection.** Capture the comment ID from the
+     `add_issue_comment` response. Sleep 15 seconds. Fetch comments via
+     `issue_read(method="get_comments", owner=owner, repo=repo, issue_number=issue_number)`,
+     select the comment whose `id` matches the captured ID, and check its
+     reactions. If the comment has zero reactions (reactions
+     count is `0` or absent): set `bugbot_down = true`,
+     `phase: "BUGTEAM"`, `status: "in_progress"`,
+     `last_action: "bugbot_down_detected"`, `last_updated` ISO-8601 UTC
+     via `state.json`, spawn a `bugteam` subagent, and return (skip going
+     idle). If one or more reactions present, continue to step 4.
+  4. Goes idle.
 
 ### Fix result → general-purpose per PR
 
@@ -135,40 +147,53 @@ When bugfix (clean-coder) subagent completes after push:
 - Spawn one `general-purpose` subagent per PR via
   `Agent(subagent_type="general-purpose", run_in_background=true)`. Subagent:
   1. Reads `state.json` for its PR.
-  2. Triggers bugbot via `add_issue_comment(owner, repo, issueNumber, body="bugbot run")`.
-  3. Polls `pull_request_read(method="get_reviews")` every 60s (up to 10 polls) until review
-     anchored to `current_head` appears with `commit_id == current_head`.
-  4. **Poll / classify loop** (repeat from 4a whenever 4c retries):
-     - **4a.** Fetch inline comments via `pull_request_read(method="get_review_comments")` filtered by review ID and `commit_id == current_head`.
-     - **4b.** Classify — three outcomes (same as `SKILL.md` Step 2 BUGBOT):
+  2. Triggers bugbot via `add_issue_comment(owner, repo, issue_number, body="bugbot run")`.
+  3. **Bugbot-down detection.** Capture the comment ID from the
+     `add_issue_comment` response. Sleep 15 seconds. Fetch comments via
+     `issue_read(method="get_comments", owner=owner, repo=repo, issue_number=issue_number)`,
+     select the comment whose `id` matches the captured ID, and check its
+     reactions. If the comment has zero reactions (reactions
+     count is `0` or absent): set `bugbot_down = true`,
+     `phase: "BUGTEAM"`, `status: "in_progress"`,
+     `last_action: "bugbot_down_detected"`, `last_updated` ISO-8601 UTC
+     via `state.json`, spawn a `bugteam` subagent, and return (skip
+     polling loop). If one or more reactions present, continue to step 4.
+  4. Polls `pull_request_read(method="get_reviews")` every 60s (up to 10 polls)
+     until review anchored to `current_head` appears with `commit_id ==
+     current_head`. If polling reaches limit without a matching review, write
+     `state.json` with `status: "blocked"`, `last_action: "review_timeout"`,
+     and go idle.
+  5. **Poll / classify loop** (repeat from 5a whenever 5c retries):
+     - **5a.** Fetch inline comments via `pull_request_read(method="get_review_comments")` filtered by review ID and `commit_id == current_head`.
+     - **5b.** Classify — three outcomes (same as `SKILL.md` Step 2 BUGBOT):
        - **`clean`:** review body clean, zero unaddressed inline findings.
        - **`dirty`:** ≥1 unaddressed inline finding for `current_head`
          (actionable for Fix protocol / `clean-coder`).
        - **`inline_lag`:** review body shows findings, inline API returns
          zero matching for `current_head` (transient desync — `SKILL.md`
          Step 2 BUGBOT fourth bullet).
-     - **4c. `inline_lag`:** locked merge: increment `inline_lag_streak`
+     - **5c. `inline_lag`:** locked merge: increment `inline_lag_streak`
        (missing → `0` first); set `last_action: "inline_lag_wait"`,
        `phase: "BUGBOT"`, `last_updated`; keep `status` consistent (e.g.
        `awaiting_bugbot`). `inline_lag_streak >= 3` → **hard blocker** per
        `SKILL.md` §Stop conditions (structurally inconsistent review);
        report and go idle **without** classifying as `dirty`. Else sleep
-       90s and repeat from 4a (re-fetch inline only).
-     - **4d. `clean`:** exit. Locked merge: `bugbot_clean_at =
+       90s and repeat from 5a (re-fetch inline only).
+     - **5d. `clean`:** exit. Locked merge: `bugbot_clean_at =
        current_head`, reset `inline_lag_streak`, update `last_action`,
        `status`, `phase: BUGTEAM`.
-     - **4e. `dirty`:** exit. Locked merge: reset `inline_lag_streak`,
+     - **5e. `dirty`:** exit. Locked merge: reset `inline_lag_streak`,
        record findings count, update `last_action`, `status`, `phase:
        BUGBOT`.
-  5. Reports one-line outcome to orchestrator.
+  6. Reports one-line outcome to orchestrator.
 
 - Orchestrator reads updated `state.json`, spawns next agent:
   - `clean` → `general-purpose` runs BUGTEAM phase (bugteam via `Skill`
     when available, else inline by reading bugteam `SKILL.md`).
-  - Exited on `dirty` (4e) with actionable inline threads → spawn same
+  - Exited on `dirty` (5e) with actionable inline threads → spawn same
     fix worker as "audit result with findings". Do **not** spawn
-    `clean-coder` when monitor only saw `inline_lag` (4c retries) without
-    reaching 4e — that path retries or escalates via `inline_lag_streak ≥
+    `clean-coder` when monitor only saw `inline_lag` (5c retries) without
+    reaching 5e — that path retries or escalates via `inline_lag_streak ≥
     3` hard blocker, not fix pass.
 
 ## What orchestrator does per tick
@@ -196,7 +221,7 @@ can remove files mid-run — environmental risk.
 - **Path:** sibling of `state.json`.
 - **Format:** one tab-separated row per converged PR: ISO8601 UTC,
   owner/repo#number, bugbot SHA, bugteam SHA.
-- **Append site:** agent running `update_pull_request(pullNumber=PR_NUMBER, owner=OWNER, repo=REPO, draft=false)`. Append **before**
+- **Append site:** agent running `update_pull_request(pullNumber=NUMBER, owner=OWNER, repo=REPO, draft=false)`. Append **before**
   locked `state.json` publish so log row survives failed merge.
 - **Never read inside loop.** User / follow-up tooling only.
 

package/skills/pr-converge/reference/obstacles/fix-post-replies.md

@@ -0,0 +1,13 @@
+# Post fix replies
+
+Post fix reply on each addressed comment thread via add_reply_to_pull_request_comment
+
+## 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-publish-summary.md

@@ -0,0 +1,13 @@
+# Publish fix summary
+
+Publish fix summary HTML via /doc-gist with commit SHA and per-fix descriptions
+
+## 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-push.md

@@ -0,0 +1,13 @@
+# Push
+
+git push origin BRANCH, honor pre-push hooks
+
+## 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-read-filelines.md

@@ -0,0 +1,13 @@
+# Read file:lines
+
+Read each referenced file:line before implementing
+
+## 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-reset-state.md

@@ -0,0 +1,13 @@
+# Reset state
+
+Set bugbot_clean_at=null, capture new current_head
+
+## 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-resolve-threads.md

@@ -0,0 +1,13 @@
+# Resolve threads
+
+Resolve each addressed thread via pull_request_review_write resolve_thread
+
+## 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-spawn-clean-coder.md

@@ -0,0 +1,13 @@
+# Spawn clean-coder
+
+Spawn Agent(subagent_type=clean-coder) to implement fixes
+
+## 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-stage-commit.md

@@ -0,0 +1,13 @@
+# Stage and commit
+
+git add files, git commit, honor pre-commit hooks
+
+## 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
+