claude-dev-env 1.93.1 → 1.94.0

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

@@ -1,6 +1,15 @@
 # State across ticks
 
-**Dual persistence:** Single-PR `/pr-converge` writes loop state to
+## Contents
+
+- [Dual persistence](#dual-persistence)
+- [Fields](#fields)
+- [Read/write lifecycle](#readwrite-lifecycle)
+- [Handoff files](#handoff-files)
+
+## Dual persistence
+
+Single-PR `/pr-converge` writes loop state to
 `$CLAUDE_JOB_DIR/pr-converge-state.json`; that file is the source of truth
 for `phase`, heads, counters, status. Multi-PR mode additionally maintains
 `<TMPDIR>/pr-converge-<session_id>/state.json` for orchestrator coordination
@@ -9,6 +18,8 @@ across PRs. Both files share most of the fields below; the
 live ONLY in the single-PR `$CLAUDE_JOB_DIR/pr-converge-state.json` file
 (see those field entries below for details).
 
+## Fields
+
 - `phase`: `BUGBOT`, `CODE_REVIEW`, `BUGTEAM`, or `COPILOT_WAIT`. Start
   `CODE_REVIEW` on first tick. `BUGBOT` is the terminal external-confirmation
   phase reached after BUGTEAM converges; the internal `CODE_REVIEW` and
@@ -18,8 +29,20 @@ live ONLY in the single-PR `$CLAUDE_JOB_DIR/pr-converge-state.json` file
 - `code_review_clean_at`: HEAD SHA where the `/code-review` pass last
   reported clean (no validated findings), or `null`. Reset to `null` on
   every push.
+- `bugteam_clean_at`: HEAD SHA where bugteam 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.
+- `merge_state_status`: last-observed `mergeable_state` from
+  `pull_request_read(method="get")` (e.g. `clean`, `dirty`, `blocked`,
+  `behind`, `unknown`, `unstable`), or `null` before the first check. Reset
+  to `null` on every push. Gate (c) in [convergence-gates.md](convergence-gates.md)
+  invokes rebase on `dirty`; other non-`clean` values (`blocked`, `behind`,
+  `unknown`, `unstable`) are hard blockers.
+- `current_head`: SHA of the last-known PR HEAD. Each tick refreshes it from
+  `pull_request_read(method="get")` → `.head.sha`, and again after any push
+  that moves HEAD. Clean-at stamps, wait counters, and phase gates compare
+  against this value.
 - `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`
@@ -95,11 +118,13 @@ live ONLY in the single-PR `$CLAUDE_JOB_DIR/pr-converge-state.json` file
   `{agent_id, created_tick, last_used_tick}` for the persistent per-step
   agents the loop resumes across ticks. Exactly three step keys:
   `fix_executor` (the clean-coder that applies findings in Step 4 dirty,
-  Step 6 findings, gates (a)/(d), and Step 7a), `thread_sweep`, and
+  Step 6 findings, gates (a)/(b)/(e), and Step 7a), `thread_sweep`, and
   `copilot_watch`. `agent_id` is the id the `Agent` tool returned at spawn;
   `created_tick` is the `tick_count` at spawn; `last_used_tick` is bumped
   on every `SendMessage` resume.
 
+## Read/write lifecycle
+
 Single-PR tick begins by reading `$CLAUDE_JOB_DIR/pr-converge-state.json`
 if it exists and ends by writing the updated state back to that same file
 before scheduling the next wakeup. Multi-PR mode additionally coordinates

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

@@ -8,13 +8,21 @@ Python helper scripts for the `pr-converge` skill, plus their tests and a PowerS
 |---|---|
 | `check_bugbot_ci.py` | Checks bugbot CI check-run status on a given SHA |
 | `check_convergence.py` | Evaluates whether all convergence gates pass on the current HEAD |
+| `check_convergence_gates.py` | GitHub REST leaf checks (review and Bugbot) the convergence gates call |
+| `check_convergence_thread_gates.py` | GitHub GraphQL and REST leaf checks (review threads and pending reviewers) the convergence gates call |
 | `check_pending_reviews.py` | Fetches pending review requests and reviewer states |
 | `fetch_copilot_reviews.py` | Fetches Copilot reviewer reviews filtered to the current HEAD |
 | `post_fix_reply.py` | Posts an inline reply to a review comment thread |
 | `reflow_skill_md.py` | Reformats `SKILL.md` to enforce a line width limit |
 | `README.md` | MCP tool reference for PR operations used by the scripts |
+| `_pr_converge_path_setup.py` | Adds the scripts directory to `sys.path` for direct script imports |
+| `conftest.py` | Puts the scripts directory on `sys.path` so pytest collects the suite |
 | `test_check_bugbot_ci.py` | Tests for `check_bugbot_ci.py` |
 | `test_check_convergence.py` | Tests for `check_convergence.py` |
+| `test_check_convergence_contract.py` | Contract pins for `check_convergence.py` gate wiring |
+| `test_check_convergence_gates.py` | Tests for `check_convergence_gates.py` |
+| `test_check_convergence_thread_gates.py` | Tests for `check_convergence_thread_gates.py` |
+| `test__pr_converge_path_setup.py` | Tests for `_pr_converge_path_setup.py` |
 | `test_cursor_agents_continue.py` | Tests for the cursor-agents-continue toolset |
 | `test_reflow_skill_md.py` | Tests for `reflow_skill_md.py` |
 | `caller-window-pid.ps1` | Gets the PID of the calling terminal window |

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

@@ -84,8 +84,7 @@ Fetch via MCP:
     pull_request_read(method="get_review_comments", pullNumber=NUMBER, owner=OWNER, repo=REPO)
       → filter threads where `is_resolved == false`
 
-Sweep semantics and per-thread handling live in the `pr-fix-protocol`
-skill's unresolved-thread sweep (`../../pr-fix-protocol/SKILL.md`).
+Sweep semantics and per-thread handling live in the shared fix protocol ([`../../../_shared/pr-loop/fix-protocol.md`](../../../_shared/pr-loop/fix-protocol.md) step 12; skill deltas in [`../reference/fix-protocol.md`](../reference/fix-protocol.md)).
 
 ### Request Copilot review: `gh api` REST endpoint
 
@@ -99,7 +98,9 @@ Check for an existing pending review first with
 
 ## Shared modules
 
-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.
+Shared Python utilities live under `skills/_shared/pr-loop/scripts/` —
+`_xml_utils.py` for XML serialization, `_cli_utils.py` for CLI guards,
+`_path_resolver.py` for canonical path resolution.
 
 ## Tests
 

package/skills/pr-converge/scripts/_pr_converge_path_setup.py

@@ -0,0 +1,23 @@
+"""Put the pr-converge script directories on sys.path for standalone runs.
+
+Importing this module makes the skill's constants package and the shared
+``reviews_disabled`` module resolvable when a script in this directory runs
+as ``__main__``. Each directory is added once, guarded against duplicates.
+"""
+
+import sys
+from pathlib import Path
+
+_scripts_directory = Path(__file__).resolve().parent
+_skill_directory = _scripts_directory.parent
+_claude_dev_env_directory = _scripts_directory.parent.parent.parent
+_shared_pr_loop_scripts_directory = (
+    _claude_dev_env_directory / "_shared" / "pr-loop" / "scripts"
+)
+
+if str(_scripts_directory) not in sys.path:
+    sys.path.insert(0, str(_scripts_directory))
+if str(_skill_directory) not in sys.path:
+    sys.path.insert(0, str(_skill_directory))
+if str(_shared_pr_loop_scripts_directory) not in sys.path:
+    sys.path.insert(0, str(_shared_pr_loop_scripts_directory))