claude-dev-env 1.36.1 → 1.37.0

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

@@ -0,0 +1,118 @@
+# Convergence gates
+
+Run **only** when Step 2 BUGTEAM reports `convergence (zero findings)` AND
+`bugbot_clean_at == current_head` AND no push during bugteam tick. Gates run
+in order; first failure determines next-tick behavior. Mark PR ready only
+when all four pass.
+
+## (a) Copilot findings gate
+
+Fetch latest Copilot reviewer (`copilot-pull-request-reviewer[bot]`) review
+plus inline comments anchored to most recent Copilot review on
+`current_head`:
+
+```bash
+python "${CLAUDE_SKILL_DIR}/scripts/fetch_copilot_reviews.py" \
+--owner <OWNER> --repo <REPO> --number <NUMBER>
+
+python "${CLAUDE_SKILL_DIR}/scripts/fetch_copilot_inline_comments.py" \
+--owner <OWNER> --repo <REPO> --number <NUMBER> --commit "$current_head"
+```
+
+Decide (four branches; match first whose predicate holds):
+
+- **`classification == "dirty"` with non-empty inline comments matching
+  `pull_request_review_id`:** Fix protocol input (same shape as bugbot
+  dirty). Apply Fix protocol on every inline finding (TDD test →
+  production fix → push → reply inline on each thread), reset
+  `bugbot_clean_at = null` AND `copilot_clean_at = null`, `phase = BUGBOT`,
+  Step 3 on new HEAD, schedule next wakeup, return. Full
+  back-to-back-clean cycle plus all four gates must hold again on new HEAD.
+- **`classification == "dirty"` with empty inline comments matching
+  `pull_request_review_id`:** Copilot posted findings only in review body
+  (`CHANGES_REQUESTED` or `COMMENTED` with non-empty body, no inline
+  threads). Parse body for actionable findings, apply Fix protocol using
+  body excerpts (TDD test → production fix → push). Post top-level review
+  reply acknowledging fixes and citing new HEAD SHA. 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).
+
+## (b) Mergeability gate
+
+Resolve PR's mergeability state:
+
+```bash
+python "${CLAUDE_SKILL_DIR}/scripts/check_pr_mergeability.py" \
+--owner <OWNER> --repo <REPO> --number <NUMBER>
+```
+
+Persist `mergeStateStatus` into `merge_state_status`. Decide:
+
+- **`mergeStateStatus == "CLEAN"` AND `mergeable == "MERGEABLE"`:**
+  Continue to gate (c).
+- **`mergeStateStatus == "DIRTY"` (or `mergeable == "CONFLICTING"`):** Do
+  **not** mark ready. Invoke **`rebase`** skill
+  ([`../../rebase/SKILL.md`](../../rebase/SKILL.md)) Phase 1–4 against PR's
+  base ref. After rebase + force-with-lease push, new HEAD invalidates
+  every prior clean state — reset `bugbot_clean_at = null`,
+  `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.
+- **`mergeStateStatus` is `BLOCKED`, `BEHIND`, or `UNKNOWN` for
+  non-conflict reasons** (required checks pending, branch behind base
+  without conflicts GitHub cannot auto-resolve): **hard blocker** per
+  [stop-conditions.md](stop-conditions.md) — do not invent a fix. Report specific
+  `mergeStateStatus`, omit loop pacing.
+
+## (c) Post-convergence Copilot review request
+
+Once gates (a) and (b) both pass (Copilot clean at `current_head` *or* no
+Copilot review yet, AND `mergeStateStatus == "CLEAN"`), request Copilot
+review:
+
+```bash
+python "${CLAUDE_SKILL_DIR}/scripts/request_copilot_review.py" \
+--owner <OWNER> --repo <REPO> --number <NUMBER>
+```
+
+After request, schedule next wakeup and return — next tick checks response.
+
+Next tick with `phase == BUGTEAM` and prior state preserved → re-run gate
+(a) first. Decide:
+
+- **Copilot review `clean` (state `APPROVED`):** Set `copilot_clean_at =
+  current_head`. Mark PR ready (`mark_pr_ready.py`), report convergence
+  per §(d), terminate per [stop-conditions.md](stop-conditions.md) / Convergence.
+- **Copilot review `dirty`:** Treat identically to gate (a) dirty path —
+  fix in same PR, restart convergence from BUGBOT. Apply Fix protocol on
+  every confirmed Copilot finding (TDD test → production fix → push →
+  reply inline on each thread; for body-only findings with empty inline,
+  parse body excerpts and post top-level review reply citing new HEAD).
+  Reset `bugbot_clean_at = null` AND `copilot_clean_at = null`, `phase =
+  BUGBOT`, Step 3 on new HEAD, 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).
+
+## (d) Mark ready and report
+
+Only when all four gates pass — bugbot CLEAN ∧ bugteam CLEAN ∧
+`mergeStateStatus == "CLEAN"` ∧ Copilot CLEAN at HEAD — run:
+
+```bash
+python "${CLAUDE_SKILL_DIR}/scripts/mark_pr_ready.py" \
+--owner <OWNER> --repo <REPO> --number <NUMBER>
+```
+
+When scripts unavailable, `gh pr ready <NUMBER> --repo <OWNER>/<REPO>` is
+equivalent. 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>, mergeStateStatus CLEAN, copilot CLEAN at <SHA>; marked ready for
+review`. **Omit loop pacing** per **Convergence** of active pacing workflow.

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

@@ -0,0 +1,76 @@
+# Examples
+
+Worked examples for `pr-converge`. Read on demand when a tick's
+classification is novel or ambiguous against the in-skill rules. Cross-refs
+into `SKILL.md` use `§Section name` notation.
+
+<example> User: `/pr-converge` Claude: [PR context + one tick bugbot/bugteam
+work; Step 4 per `workflows/schedule-wakeup-loop.md` — default loop until
+convergence or stop]
+</example>
+
+<example> BUGBOT tick, latest bugbot review against older commit. Claude:
+[posts `bugbot run`, sets `bugbot_clean_at = null`, Step 4 per
+`workflows/schedule-wakeup-loop.md` (e.g. 270s wakeup), returns]
+</example>
+
+<example> BUGBOT tick, bugbot has 2 unaddressed findings on HEAD. Claude:
+[TDD-fixes both, one commit, pushes, replies inline on both threads, posts
+`bugbot run`, Step 4 at 270s, returns]
+</example>
+
+<example> BUGBOT tick, bugbot clean against HEAD. Claude: [sets
+`bugbot_clean_at = HEAD`, `phase = BUGTEAM`, runs `Skill({skill: "bugteam",
+...})` in same tick]
+</example>
+
+<example> BUGTEAM phase, bugteam reports convergence and `bugbot_clean_at
+== current_head`. Claude: [runs `gh pr ready <NUMBER>`, reports "PR
+converged: bugbot CLEAN at <SHA>, bugteam CLEAN at <SHA>; marked ready for
+review", applies **Convergence** from `workflows/schedule-wakeup-loop.md`]
+</example>
+
+<example> BUGTEAM phase, bugteam pushed fix commit during run. Claude:
+[re-resolves HEAD, sets `bugbot_clean_at = null`, posts `bugbot run` in
+same tick, `phase = BUGBOT`, Step 4 at 270s]
+</example>
+
+<example> BUGBOT tick, review body says "found 3 potential issues" against
+HEAD but inline API returns zero matching for `current_head`. Claude:
+[increments `inline_lag_streak` to 1, Step 4 inline-lag rules (90s
+`ScheduleWakeup`), returns]
+</example>
+
+<example> Back-to-back clean reached, but `mergeStateStatus: DIRTY` (base
+advanced, merge conflicts). Claude: [runs §Convergence gates (b); does NOT
+mark ready; invokes `rebase` skill per `../../rebase/SKILL.md` Phase 1–4;
+after force-with-lease push, resets `bugbot_clean_at = null`,
+`copilot_clean_at = null`, `merge_state_status = null`, `phase = BUGBOT`,
+posts `bugbot run` on new HEAD, schedules next wakeup]
+</example>
+
+<example> Back-to-back clean, mergeability CLEAN, Copilot review at
+`current_head` `state == "CHANGES_REQUESTED"` with two unaddressed inline
+findings. Claude: [runs §Convergence gates (a); applies Fix protocol (TDD
+test → fix → push → reply inline both threads), resets `bugbot_clean_at`
+and `copilot_clean_at` null, `phase = BUGBOT`, posts `bugbot run` on new
+HEAD, schedules next wakeup]
+</example>
+
+<example> Back-to-back clean, mergeability CLEAN, no Copilot review on
+`current_head`. Claude requests Copilot via `request_copilot_review.py`,
+waits one tick. Next tick: Copilot review `state: APPROVED`. Claude: [sets
+`copilot_clean_at = current_head`; runs `mark_pr_ready.py`; reports "PR
+#N converged: bugbot CLEAN at <SHA>, bugteam CLEAN at <SHA>,
+mergeStateStatus CLEAN, copilot CLEAN; 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;
+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
+gates must hold again on new HEAD.]
+</example>

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

@@ -0,0 +1,54 @@
+# Fix protocol
+
+Single-PR (no `state.json`): production edits run in main session via
+`Agent` (`subagent_type: "clean-coder"`). Multi-PR (`state.json`):
+clean-coder teammate; orchestrator never edits inline. Hook handling
+per [ground-rules.md](ground-rules.md).
+
+**Multi-PR (`state.json`) teammate obligations** (plus TDD, commit, push):
+
+- Replies inline on each addressed finding via
+  `reply_to_inline_comment.py` (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).
+- Goes idle. Orchestrator spawns follow-up `general-purpose` agent for
+  bugbot trigger and monitoring.
+
+Orchestrator does not reply inline, trigger bugbot, or read repo source
+files during fix phase in multi-PR mode.
+
+**Single-PR (no `state.json`) — same gates, main session executor:**
+
+- Read each referenced file:line.
+- Write failing test first when finding has behavior to test. Pure doc /
+  comment / naming nits with no behavior → straight to fix.
+- **Implement** via `Agent` (`subagent_type: "clean-coder"`).
+  Full-stop if `Agent` is unavailable.
+- Stage affected files and create one new commit on existing branch:
+  ```bash
+git add <files> && git commit -m "fix(review): <brief summary>"
+  ```
+**Pre-commit gate:** honor hooks; full-stop on bypass.
+- Push the new commit:
+  ```bash
+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 `--body-file` (per
+  gh-body-file rule):
+  ```bash
+python "${CLAUDE_SKILL_DIR}/scripts/reply_to_inline_comment.py" \
+--owner <OWNER> --repo <REPO> --number <NUMBER> \
+--comment-id <COMMENT_ID> --body-file <path/to/reply.md>
+  ```
+- **After pushing a fix, always run Step 3 (`bugbot run`) in the same
+  tick** regardless of phase. New commit **resets full convergence cycle**:
+  prior bugbot clean and prior bugteam clean on older SHA do **not**
+  count toward convergence on new `HEAD`. Must re-obtain bugbot CLEAN on
+  `current_head`, then bugteam CLEAN on same `HEAD` with no
+  intervening push. Re-triggering in same tick saves a wakeup cycle vs
+  deferring Step 3.

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

@@ -0,0 +1,13 @@
+# Ground rules
+
+- **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.**
+- **`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.
+- **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

@@ -0,0 +1,204 @@
+# Multi-PR orchestration model
+
+Loaded by `pr-converge` only when `state.json` exists at
+`<TMPDIR>/pr-converge-<session_id>/state.json`. Single-PR runs ignore.
+
+## Core rule: orchestrator is traffic controller only
+
+Orchestrator (main session) **never** reads repo source files, writes code,
+audits findings, or does per-PR codebase work inline. Reads `state.json` for
+traffic state, writes only narrow fields per §Orchestrator `state.json`
+writes, receives teammate handoffs, spawns next worker. Every audit/fix unit
+runs inside dedicated teammate.
+
+[Workflow-style skill](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#use-workflows-for-complex-tasks):
+orchestrator splits multi-PR problem into parallel per-PR subworkflows
+owned by short-lived teammates. Orchestrator job: keep state file
+consistent, spawn next agent.
+
+## Per-PR state file
+
+Create once at session start. Each teammate writes result before going idle.
+
+**Path:** `<TMPDIR>/pr-converge-<session_id>/state.json`. **Session ID:**
+`YYYYMMDDHHMMSS` captured once when loop starts.
+
+**Directory lifecycle:** Keep `<TMPDIR>/pr-converge-<session_id>/` until every
+`prs[...]` is `converged` or `blocked`, or user stops. Then delete folder.
+`mark_pr_ready.py` / `gh pr ready` on GitHub is canonical record. See
+[Memory](#memory) for optional append-only log.
+
+**Barebones schema:**
+
+```json
+{
+  "session_id": "20260502050000",
+  "prs": {
+    "289": {
+      "owner": "jl-cmd",
+      "repo": "claude-code-config",
+      "branch": "feat/shared-pr-loop-extraction",
+      "phase": "BUGBOT",
+      "current_head": "f9a7d49e",
+      "bugbot_clean_at": null,
+      "inline_lag_streak": 0,
+      "tick_count": 5,
+      "last_action": "bugbot_triggered",
+      "status": "in_progress",
+      "last_updated": "2026-05-02T10:00:00Z"
+    }
+  }
+}
+```
+
+**`status` values:** `fresh` | `in_progress` | `awaiting_bugbot` |
+`awaiting_bugteam` | `converged` | `blocked`
+
+**Write rule:** Subagents read current file, merge **only** their PR's entry
+under `prs`, write back. Writes keyed on `pr_number`; other PRs untouched.
+
+**Concurrency (mandatory):** Naive read–modify–write loses updates when
+multiple subagents finish in same wall-clock window (10+ idle notifications
+together). Every subagent write **must** use serialized access plus atomic
+publish:
+
+1. **Acquire** exclusive lock at sibling path `state.json.lock` via atomic
+   create-only primitive (`mkdir` on Unix; on Windows `New-Item` / `md`
+   guarded so only one creator succeeds, or host file lock API). On
+   contention, sleep with jitter and retry. Cap retries and escalate per
+   **Stop conditions** if lock never clears (stuck subagent).
+2. **Read** `state.json`, merge `prs[<pr_number>]` only, write full merged
+   JSON to `state.json.tmp`.
+3. **Replace** `state.json` atomically from `state.json.tmp` (`os.replace` /
+   same-volume rename so readers never see half-written file).
+4. **Release** lock (`rmdir` / `Remove-Item`).
+
+**Orchestrator `state.json` writes (traffic metadata only):** Subagents
+own audit/fix payloads. Orchestrator **must not** merge finding bodies,
+file contents, or subagent-owned fields except two exceptions. Uses same
+§Concurrency lock.
+
+1. **Per-tick `tick_count` bump (mandatory):** At start of each tick, one
+   locked read–merge–publish: every `prs[<pr_number>]` whose `status` is
+   not `converged` or `blocked` → increment `tick_count` by 1 (init `0`),
+   refresh `last_updated`. Observability only — no ceiling; loop ends on
+   convergence or **Stop conditions**.
+2. **`phase` when only orchestrator decides:** Orchestrator applies a
+   Step 2 phase transition (including BUGTEAM §(d) `phase = BUGBOT`
+   without immediate subagent write) and no subagent merge occurs that
+   tick → orchestrator performs one locked merge setting only
+   `prs[<pr_number>].phase` and `last_updated`.
+
+Orchestrator reads file at start of every tick for cross-PR state, not
+conversation context.
+
+## Subagent spawning rules
+
+Multiple PRs returning simultaneously (10+ idle notifications) → spawn
+one agent per PR in single parallel message. Never process any PR inline.
+
+### Audit result → fix worker per PR
+
+Bugfind subagent completes (findings or clean):
+
+- **PRs with findings:** spawn one fix worker per PR via
+  `Agent(subagent_type="clean-coder", run_in_background=true)`. Worker:
+  1. Reads outcomes XML.
+  2. Applies TDD fixes (test first, then production).
+  3. Commits, pushes one fix commit.
+  4. Replies inline on each addressed finding via
+     `reply_to_inline_comment.py`.
+  5. Writes `state.json` (per §Concurrency): `last_action: "fix_pushed"`,
+     `current_head: <new SHA>`, `bugbot_clean_at: null`, `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
+     `mark_pr_ready.py`, 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"`,
+     `last_updated` ISO-8601 UTC — **before** going idle. Skipping leaves
+     orchestrator with stale `awaiting_bugteam` / `in_progress` row, risks
+     duplicate work.
+  2. Else: update `state.json` (per §Concurrency) with `last_action:
+     "audit_clean"`, `status: "awaiting_bugbot"`, `phase: "BUGBOT"`, then
+     trigger bugbot via `trigger_bugbot.py`.
+  3. Goes idle.
+
+### Fix result → general-purpose per PR
+
+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 `trigger_bugbot.py`.
+  3. Polls `fetch_bugbot_reviews.py` every 60s (up to 10 polls) until review
+     anchored to `current_head` appears.
+  4. **Poll / classify loop** (repeat from 4a whenever 4c retries):
+     - **4a.** Fetch inline comments via `fetch_bugbot_inline_comments.py`.
+     - **4b.** 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`
+       (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 =
+       current_head`, reset `inline_lag_streak`, update `last_action`,
+       `status`, `phase: BUGTEAM`.
+     - **4e. `dirty`:** exit. Locked merge: reset `inline_lag_streak`,
+       record findings count, update `last_action`, `status`, `phase:
+       BUGBOT`.
+  5. 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
+    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 ≥
+    3` hard blocker, not fix pass.
+
+## What orchestrator does per tick
+
+1. Per-tick `tick_count` bump for every non-terminal PR under `prs`.
+2. Read `state.json`.
+3. Each PR with new subagent results → spawn next agent per rules, all
+   in one parallel message.
+4. Re-read `state.json` if needed for scheduling.
+5. Call `ScheduleWakeup` with appropriate delay.
+6. Nothing else.
+
+## Memory
+
+Run directory `<TMPDIR>/pr-converge-<session_id>/` holds `state.json` and
+optional `converged.log`. Keep from first create until every PR under `prs`
+is `converged` or `blocked`, or **Stop conditions** ends loop. Safe to
+delete folder after — `mark_pr_ready.py` / `gh pr ready` on GitHub is
+canonical record. Folder skill, not a plugin package; do **not** rely
+on `${CLAUDE_PLUGIN_DATA}`. OS/disk cleanup of `<TMPDIR>` (reboot, policy)
+can remove files mid-run — environmental risk.
+
+**`converged.log` (multi-PR only — requires `state.json`):**
+
+- **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 `mark_pr_ready.py`. Append **before**
+  locked `state.json` publish so log row survives failed merge.
+- **Never read inside loop.** User / follow-up tooling only.
+
+Single-PR runs without `state.json`: do **not** append `converged.log`;
+in-conversation summary plus GitHub ready state suffice.

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

@@ -0,0 +1,201 @@
+# Per-tick work
+
+Use on **draft PR**. Cursor Bugbot and `/bugteam` re-run after each push. Fix
+findings between rounds until back-to-back clean on same `HEAD`, then mark
+PR ready for review.
+
+Run every tick in parent harness session. Pacing lives in
+[`../workflows/schedule-wakeup-loop.md`](../workflows/schedule-wakeup-loop.md) (read before Step 4); see [Pacing
+workflow](#pacing-workflow).
+
+Every BUGTEAM tick runs **bugteam** — never hand-rolled substitute. Fix
+protocol per [fix-protocol.md](fix-protocol.md). Pacing stays in main session via
+`ScheduleWakeup` (pre-flight aborts when absent).
+
+## Invocation modes
+
+- **`/pr-converge`** runs one tick, then Step 4 schedules the next via
+  `ScheduleWakeup`. Omit the next wakeup only on convergence or **Stop
+  conditions**.
+
+## Pacing workflow
+
+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.
+
+- **`/pr-converge`** (default): loops until convergence. After each tick
+  (unless converged or stopped), run **Step 4**.
+
+## Step 1: Resolve current HEAD and PR context
+
+Read prior tick's state line from most recent assistant message (or
+initialize fields if none). Increment `tick_count` by 1 in conversation
+state line when **no** `state.json` (single-PR only). With `state.json`, do
+**not** increment here — orchestrator's per-tick bump is sole increment.
+
+```bash
+python "${CLAUDE_SKILL_DIR}/scripts/view_pr_context.py"
+```
+
+Capture `number`, `headRefOid` (= `current_head`), owner/repo, branch.
+
+## Step 2: Branch on `phase`
+
+### `phase == BUGBOT`
+
+a. Fetch Cursor Bugbot reviews newest-first, walk back until first clean:
+
+   ```bash
+python "${CLAUDE_SKILL_DIR}/scripts/fetch_bugbot_reviews.py" \
+--owner <OWNER> --repo <REPO> --number <NUMBER>
+   ```
+
+Track dirty entries in a temp file; Fix protocol reads it back later
+this tick.
+
+Iterate from index 0 (most recent) toward older:
+
+   - Dirty review → append JSON line with `{review_id, commit_id,
+     submitted_at, body}`.
+   - Stop at first clean. Older reviews presumed addressed at that
+     checkpoint.
+   - Index 0 clean → `$dirty_reviews_path` stays empty.
+
+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`. Script uses same `--paginate --slurp` pattern,
+resolves review via reviews list, returns only inline rows whose
+`pull_request_review_id` matches that review (excludes stale threads from
+older reviews on same SHA).
+
+   ```bash
+python "${CLAUDE_SKILL_DIR}/scripts/fetch_bugbot_inline_comments.py" \
+--owner <OWNER> --repo <REPO> --number <NUMBER> --commit "$current_head"
+   ```
+
+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 =
+     null`, reset `inline_lag_streak = 0`, schedule next wakeup, return.
+   - **`commit_id == current_head` AND zero unaddressed inline AND review
+     body clean:** Set `bugbot_clean_at = current_head`, reset
+     `inline_lag_streak = 0`, `phase = BUGTEAM`. Continue BUGTEAM in same
+     tick — back-to-back convergence requires bugteam on same HEAD
+     before next wakeup.
+   - **`commit_id == current_head` with unaddressed inline findings:**
+     Apply **Fix protocol**. Reset `inline_lag_streak = 0`. With
+     `state.json`: clean-coder teammate pushes, replies inline, writes
+     `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): implement → push → inline replies
+     → Step 3 in same tick per loaded pacing workflow. 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`
+
+a. Run **bugteam** on current PR.
+
+   - **`Skill` invokable**: invoke bugteam
+     with `Skill`.
+
+     ```
+Skill({skill: "bugteam", args:
+"https://github.com/<OWNER>/<REPO>/pull/<NUMBER>"})
+     ```
+
+   - **`Skill` not invokable** (typical delegated teammate): worker executes
+     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
+new_head=$(python "${CLAUDE_SKILL_DIR}/scripts/resolve_pr_head.py" \
+--owner <OWNER> --repo <REPO> --number <NUMBER>)
+   ```
+If `new_head != current_head`, set `current_head = new_head` AND
+`bugbot_clean_at = null`. New commits invalidate bugbot's prior clean.
+
+c. Inspect bugteam outcome. Reports `convergence (zero findings)` or list
+of unfixed findings with file:line.
+
+d. Decide based on post-bugteam state — order matters. Check
+pushed-during-bugteam FIRST so convergence report against stale HEAD
+never falsely terminates:
+   - **Audit pushed this tick (`bugbot_clean_at` reset in step b):**
+     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
+     **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:** apply **[fix-protocol.md](fix-protocol.md)**; Step 3
+     on new HEAD runs after fix handoff per `multi-pr-orchestration.md` or in-tick for
+     single-PR. `phase = BUGBOT`, schedule next wakeup, return.
+
+## Step 3: Re-trigger bugbot
+
+Prefer portable script (temp body file, `gh pr comment --body-file`):
+
+```bash
+python "${CLAUDE_SKILL_DIR}/scripts/trigger_bugbot.py" \
+--owner <OWNER> --repo <REPO> --number <NUMBER>
+```
+
+**Bundled PowerShell alternative** (same gh-body-file contract):
+
+```bash
+POST_BUGBOT_RUN="$HOME/.claude/skills/pr-converge/scripts/post-bugbot-run.ps1"
+pwsh -NoProfile -ExecutionPolicy Bypass -File "$POST_BUGBOT_RUN" \
+"https://github.com/<OWNER>/<REPO>/pull/<NUMBER>"
+```
+
+`bugbot run` is empirically the only re-trigger Cursor Bugbot recognizes;
+alternative phrasings (`re-review`, `bugbot please`, etc.) silently no-op.
+
+**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.
+
+## 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:
+  BUGBOT inline-lag branch uses `delaySeconds: 90` (no re-trigger;
+  awaiting GitHub inline API).
+- `reason`: short sentence on what is awaited, including `phase` and
+  `bugbot_clean_at` SHA.
+- `prompt: "/pr-converge"`.
+
+**On convergence:** apply **Convergence** section of
+`../workflows/schedule-wakeup-loop.md` (omit wakeups).
+
+## Bugteam execution
+
+**Second audit** (BUGTEAM phase) is **always** **bugteam** skill: preflight,
+CODE_RULES gate, **`code-quality-agent`** / **`clean-coder`** loop, audit
+rubric, outcome shape, Step 2 BUGTEAM §(b)–(d) contract — all in
+[`../../bugteam/SKILL.md`](../../bugteam/SKILL.md) plus `PROMPTS.md` / `EXAMPLES.md` /
+`CONSTRAINTS.md`. Do not re-spec.
+
+**pr-converge rule:** Prefer **`Skill({skill: "bugteam", args: "<PR URL or
+args>"})`** wherever registry exposes `Skill`. When `Skill` not invokable
+(typical delegated teammate), worker runs **bugteam** by loading
+`../../bugteam/SKILL.md` from the same checkout. If bugteam cannot run, cancel the
+convergence loop fully and report the issue to the user.