claude-dev-env 1.35.0 → 1.36.1

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

@@ -0,0 +1,139 @@
+"""Tests for trigger_bugbot.
+
+Covers:
+- gh pr comment is invoked with --body-file (per gh-body-file rule)
+- the body file written contains the literal phrase "bugbot run\\n"
+- the comment URL emitted by gh is returned
+- the temp body file is cleaned up
+- subprocess errors propagate
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import subprocess
+from pathlib import Path
+from types import ModuleType
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+
+def _load_module() -> ModuleType:
+    module_path = Path(__file__).parent / "trigger_bugbot.py"
+    spec = importlib.util.spec_from_file_location("trigger_bugbot", module_path)
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+trigger_bugbot_module = _load_module()
+
+
+def _completed(stdout: str) -> subprocess.CompletedProcess:
+    process = MagicMock(spec=subprocess.CompletedProcess)
+    process.stdout = stdout
+    process.returncode = 0
+    return process
+
+
+def test_should_invoke_gh_pr_comment_with_body_file_flag() -> None:
+    captured_body_paths: list[str] = []
+
+    def capture_body_file_contents(*subprocess_args, **_subprocess_kwargs):
+        invoked_argv = subprocess_args[0]
+        assert "--body-file" in invoked_argv
+        body_file_path = invoked_argv[invoked_argv.index("--body-file") + 1]
+        captured_body_paths.append(body_file_path)
+        return _completed("https://github.com/acme/widget/issues/42#issuecomment-99\n")
+
+    with patch("subprocess.run", side_effect=capture_body_file_contents) as mock_run:
+        trigger_bugbot_module.trigger_bugbot(owner="acme", repo="widget", number=42)
+    invoked_argv = mock_run.call_args[0][0]
+    assert invoked_argv[0:3] == ["gh", "pr", "comment"]
+    assert "42" in invoked_argv
+    assert "--repo" in invoked_argv
+    assert "acme/widget" in invoked_argv
+
+
+def test_should_write_literal_bugbot_run_phrase_into_body_file() -> None:
+    captured_body_contents: list[str] = []
+
+    def capture_body_file_contents(*subprocess_args, **_subprocess_kwargs):
+        invoked_argv = subprocess_args[0]
+        body_file_path = Path(invoked_argv[invoked_argv.index("--body-file") + 1])
+        captured_body_contents.append(body_file_path.read_text(encoding="utf-8"))
+        return _completed("https://example.com\n")
+
+    with patch("subprocess.run", side_effect=capture_body_file_contents):
+        trigger_bugbot_module.trigger_bugbot(owner="acme", repo="widget", number=42)
+    assert len(captured_body_contents) == 1
+    assert captured_body_contents[0] == "bugbot run\n"
+
+
+def test_should_return_comment_url_from_gh_stdout() -> None:
+    expected_url = "https://github.com/acme/widget/pull/42#issuecomment-12345"
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _completed(f"{expected_url}\n")
+        comment_url = trigger_bugbot_module.trigger_bugbot(
+            owner="acme", repo="widget", number=42
+        )
+    assert comment_url == expected_url
+
+
+def test_should_remove_temp_body_file_after_invocation() -> None:
+    captured_body_paths: list[Path] = []
+
+    def capture_body_file_contents(*subprocess_args, **_subprocess_kwargs):
+        invoked_argv = subprocess_args[0]
+        captured_body_paths.append(
+            Path(invoked_argv[invoked_argv.index("--body-file") + 1])
+        )
+        return _completed("https://example.com\n")
+
+    with patch("subprocess.run", side_effect=capture_body_file_contents):
+        trigger_bugbot_module.trigger_bugbot(owner="acme", repo="widget", number=42)
+    assert len(captured_body_paths) == 1
+    assert not captured_body_paths[0].exists()
+
+
+def test_should_raise_when_gh_subprocess_fails() -> None:
+    failure = subprocess.CalledProcessError(
+        returncode=1, cmd=["gh"], stderr="auth failure"
+    )
+    with patch("subprocess.run", side_effect=failure):
+        with pytest.raises(subprocess.CalledProcessError):
+            trigger_bugbot_module.trigger_bugbot(owner="acme", repo="widget", number=42)
+
+
+def test_should_write_imported_constant_directly_without_local_alias() -> None:
+    captured_body_contents: list[str] = []
+
+    def capture_body_file_contents(*subprocess_args, **_subprocess_kwargs):
+        invoked_argv = subprocess_args[0]
+        body_file_path = Path(invoked_argv[invoked_argv.index("--body-file") + 1])
+        captured_body_contents.append(body_file_path.read_text(encoding="utf-8"))
+        return _completed("https://example.com\n")
+
+    with patch("subprocess.run", side_effect=capture_body_file_contents):
+        trigger_bugbot_module.trigger_bugbot(owner="acme", repo="widget", number=99)
+    assert len(captured_body_contents) == 1
+    assert (
+        captured_body_contents[0]
+        == trigger_bugbot_module.BUGBOT_RUN_TRIGGER_PHRASE
+    )
+
+
+def test_should_render_repo_arg_via_named_template_constant() -> None:
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _completed("https://example.com\n")
+        trigger_bugbot_module.trigger_bugbot(owner="acme", repo="widget", number=42)
+    invoked_argv = mock_run.call_args[0][0]
+    expected_repo_arg = trigger_bugbot_module.GH_REPO_ARG_TEMPLATE.format(
+        owner="acme", repo="widget"
+    )
+    assert expected_repo_arg == "acme/widget"
+    repo_flag_index = invoked_argv.index("--repo")
+    assert invoked_argv[repo_flag_index + 1] == expected_repo_arg

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

@@ -0,0 +1,111 @@
+"""Tests for view_pr_context.
+
+Covers:
+- gh pr view is invoked with the documented --json field list
+- the parsed JSON object is returned
+- subprocess errors propagate
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import subprocess
+from pathlib import Path
+from types import ModuleType
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+
+def _load_module() -> ModuleType:
+    module_path = Path(__file__).parent / "view_pr_context.py"
+    spec = importlib.util.spec_from_file_location("view_pr_context", module_path)
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+view_pr_context_module = _load_module()
+
+
+def _completed(stdout: str) -> subprocess.CompletedProcess:
+    process = MagicMock(spec=subprocess.CompletedProcess)
+    process.stdout = stdout
+    process.returncode = 0
+    return process
+
+
+def test_should_invoke_gh_pr_view_with_documented_field_list() -> None:
+    payload = json.dumps(
+        {
+            "number": 42,
+            "url": "https://github.com/acme/widget/pull/42",
+            "headRefOid": "abc123",
+            "baseRefName": "main",
+            "headRefName": "feat/x",
+            "isDraft": True,
+        }
+    )
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _completed(payload)
+        view_pr_context_module.view_pr_context()
+    invoked_argv = mock_run.call_args[0][0]
+    assert invoked_argv[0:3] == ["gh", "pr", "view"]
+    assert "--json" in invoked_argv
+    fields_arg = invoked_argv[invoked_argv.index("--json") + 1]
+    for required_field in (
+        "number",
+        "url",
+        "headRefOid",
+        "baseRefName",
+        "headRefName",
+        "isDraft",
+    ):
+        assert required_field in fields_arg
+
+
+def test_should_return_parsed_json_object() -> None:
+    payload = {
+        "number": 42,
+        "url": "https://github.com/acme/widget/pull/42",
+        "headRefOid": "abc123",
+        "baseRefName": "main",
+        "headRefName": "feat/x",
+        "isDraft": True,
+    }
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _completed(json.dumps(payload))
+        pr_context = view_pr_context_module.view_pr_context()
+    assert pr_context == payload
+
+
+def test_should_raise_when_gh_subprocess_fails() -> None:
+    failure = subprocess.CalledProcessError(
+        returncode=1, cmd=["gh"], stderr="auth failure"
+    )
+    with patch("subprocess.run", side_effect=failure):
+        with pytest.raises(subprocess.CalledProcessError):
+            view_pr_context_module.view_pr_context()
+
+
+def test_should_pass_imported_constant_directly_without_local_alias() -> None:
+    payload = json.dumps(
+        {
+            "number": 7,
+            "url": "https://github.com/acme/widget/pull/7",
+            "headRefOid": "deadbeef",
+            "baseRefName": "main",
+            "headRefName": "feat/y",
+            "isDraft": False,
+        }
+    )
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _completed(payload)
+        view_pr_context_module.view_pr_context()
+    invoked_argv = mock_run.call_args[0][0]
+    fields_arg = invoked_argv[invoked_argv.index("--json") + 1]
+    expected_fields = view_pr_context_module.PR_CONTEXT_FIELDS
+    assert fields_arg is expected_fields

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

@@ -0,0 +1,77 @@
+"""Post a `bugbot run` comment to re-trigger a Cursor Bugbot review.
+
+Writes the literal trigger phrase to a temp file (per the gh-body-file rule —
+`gh pr comment --body "..."` may corrupt backticks), invokes
+`gh pr comment --body-file`, and removes the temp file on success or failure.
+"""
+
+import argparse
+import os
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+if str(Path(__file__).resolve().parent) not in sys.path:
+    sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from evict_cached_config_modules import evict_cached_config_modules
+
+evict_cached_config_modules()
+
+from config.pr_converge_constants import (
+    BUGBOT_RUN_TEMPFILE_PREFIX,
+    BUGBOT_RUN_TEMPFILE_SUFFIX,
+    BUGBOT_RUN_TRIGGER_PHRASE,
+    GH_REPO_ARG_TEMPLATE,
+)
+
+
+def trigger_bugbot(*, owner: str, repo: str, number: int) -> str:
+    """Post the bugbot re-trigger comment, return the comment URL gh emits."""
+    file_descriptor, raw_path = tempfile.mkstemp(
+        suffix=BUGBOT_RUN_TEMPFILE_SUFFIX, prefix=BUGBOT_RUN_TEMPFILE_PREFIX
+    )
+    try:
+        os.close(file_descriptor)
+        body_file_path = Path(raw_path)
+        body_file_path.write_text(BUGBOT_RUN_TRIGGER_PHRASE, encoding="utf-8")
+        repo_arg = GH_REPO_ARG_TEMPLATE.format(owner=owner, repo=repo)
+        gh_command: list[str] = [
+            "gh",
+            "pr",
+            "comment",
+            str(number),
+            "--repo",
+            repo_arg,
+            "--body-file",
+            str(body_file_path),
+        ]
+        completed = subprocess.run(
+            gh_command,
+            capture_output=True,
+            check=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+        )
+        return completed.stdout.strip()
+    finally:
+        Path(raw_path).unlink(missing_ok=True)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--owner", required=True)
+    parser.add_argument("--repo", required=True)
+    parser.add_argument("--number", required=True, type=int)
+    parsed_arguments = parser.parse_args()
+    comment_url = trigger_bugbot(
+        owner=parsed_arguments.owner, repo=parsed_arguments.repo, number=parsed_arguments.number
+    )
+    sys.stdout.write(f"{comment_url}\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,47 @@
+"""Resolve the per-tick PR context (number, url, head sha, branch names, draft state).
+
+Wraps `gh pr view --json ...` so the skill body emits one script invocation
+instead of repeating the field list inline.
+"""
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+if str(Path(__file__).resolve().parent) not in sys.path:
+    sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from evict_cached_config_modules import evict_cached_config_modules
+
+evict_cached_config_modules()
+
+from config.pr_converge_constants import PR_CONTEXT_FIELDS
+
+
+def view_pr_context() -> dict[str, object]:
+    """Return the parsed JSON object from `gh pr view --json <fields>`."""
+    gh_command: list[str] = ["gh", "pr", "view", "--json", PR_CONTEXT_FIELDS]
+    completed = subprocess.run(
+        gh_command,
+        capture_output=True,
+        check=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+    return json.loads(completed.stdout)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.parse_args()
+    pr_context = view_pr_context()
+    json.dump(pr_context, sys.stdout)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/pr-converge/test_team_lifecycle.py

@@ -0,0 +1,56 @@
+"""Markdown assertion tests for pr-converge orchestrator team lifecycle.
+
+Locks in the contract that pr-converge multi-PR orchestration must:
+  - own a single long-lived team for the whole sweep
+  - pass that team to every bugteam invocation via attach mode
+  - tear down only when every PR reaches `converged` or `blocked`
+"""
+
+from __future__ import annotations
+
+import pathlib
+
+
+def _skill_text() -> str:
+    here = pathlib.Path(__file__).parent
+    return (here / "SKILL.md").read_text(encoding="utf-8")
+
+
+def test_skill_documents_orchestrator_owned_team_in_multi_pr_mode():
+    skill_text = _skill_text()
+    assert "team_name" in skill_text
+    assert "TeamCreate" in skill_text
+    assert "orchestrator" in skill_text.lower()
+
+
+def test_skill_passes_attach_mode_to_bugteam_invocations():
+    skill_text = _skill_text()
+    assert "BUGTEAM_TEAM_LIFECYCLE" in skill_text
+    assert "attach" in skill_text
+    assert "BUGTEAM_TEAM_NAME" in skill_text
+
+
+def test_skill_tears_down_team_only_on_full_convergence():
+    skill_text = _skill_text()
+    assert "TeamDelete" in skill_text
+    convergence_phrases = [
+        "every PR",
+        "all PRs",
+        "fully converged",
+        "every prs[",
+    ]
+    assert any(phrase in skill_text for phrase in convergence_phrases)
+
+
+def test_state_schema_includes_team_name_field():
+    skill_text = _skill_text()
+    assert '"team_name"' in skill_text or "team_name:" in skill_text
+
+
+def test_skill_md_physical_lines_fit_eighty_column_limit():
+    skill_text = _skill_text()
+    for each_line_number, each_physical_line in enumerate(skill_text.splitlines(), 1):
+        assert len(each_physical_line) <= 80, (
+            "SKILL.md line %s exceeds 80 columns (%s chars)"
+            % (each_line_number, len(each_physical_line))
+        )

package/skills/pr-converge/workflows/ahk-auto-continue-loop.md

@@ -0,0 +1,108 @@
+# AHK auto-continue loop pacing (pr-converge)
+
+Load this document when **`ScheduleWakeup` is not available** in this session (orchestrated teams disabled, restricted tool registry, Cursor
+  without that primitive, or the user wants a visibly-running pacer). Follow it for **every** instruction below that depends on that choice.
+  Shared bugbot / bugteam / Fix protocol steps stay in the main `SKILL.md`.
+
+## Session behavior
+
+Keep ticks in the **same** window the auto-typer targets so each `continue` re-enters here and reads the same state line and `gh` context.
+
+## Why this path exists
+
+It is not a separate "mode" the user must remember — bare `/pr-converge` already implies loop-until-done; when the primary wakeup tool is
+  missing, fall through to AHK automatically. The per-tick work is unchanged; what changes is who fires the next tick. Instead of
+  `ScheduleWakeup` re-entering the skill, an external AutoHotkey utility auto-types `continue` into the active Claude Code window every 5
+  minutes, and the model treats each `continue` as the next tick trigger.
+
+**AHK is loop pacing only:** every `phase == BUGTEAM` tick still runs **`/bugteam`** via the bugteam skill per Step 2 of the main skill —
+  nothing here replaces that audit.
+
+**Fix protocol** commits use **`Task`** with **`subagent_type: "generalPurpose"`** and the **clean-coder preamble** from the main
+  [`SKILL.md` Fix protocol](../SKILL.md#fix-protocol) section (same as ScheduleWakeup pacing — Cursor has no `clean-coder` `subagent_type`).
+
+Ensure `~/.claude/agents/clean-coder.md` exists (Windows: `%USERPROFILE%\.claude\agents\clean-coder.md`). Optionally also copy it to
+  `.cursor/agents/clean-coder.md` in the repo when you want the file co-located with the checkout; the spawn **prompt** must still name the
+  absolute path the subagent should **Read** first.
+
+### One-time setup at the start of the loop
+
+The skill bundles its driver scripts under `scripts/` and resolves them at runtime via `$HOME\.claude\skills\pr-converge\scripts\…` (the same
+  convention `/logifix` uses). The bundled `.cmd` launchers locate their siblings via `%~dp0`, so they need no path arguments — only the AHK
+  target PID.
+
+Run these two commands in order (PowerShell-friendly Bash escaping):
+
+1. Resolve the PID of the GUI ancestor that hosts this Claude Code session:
+   ```bash
+   pwsh -NoProfile -ExecutionPolicy Bypass -File "$HOME\.claude\skills\pr-converge\scripts\caller-window-pid.ps1"
+   ```
+   Capture the printed integer as `caller_pid`. Verify it points at the right window before continuing:
+   ```bash
+   pwsh -NoProfile -Command "Get-Process -Id $caller_pid | Select-Object Id,ProcessName,MainWindowTitle"
+   ```
+2. Launch the auto-typer attached to that PID with auto-start enabled. The bundled launcher accepts the PID as its first arg and the
+  `--start-on` flag is forwarded to the AHK script:
+   ```bash
+   "$HOME\.claude\skills\pr-converge\scripts\cursor-agents-continue.cmd" $caller_pid --start-on
+   ```
+   AutoHotkey v2 must be installed at `C:\Program Files\AutoHotkey\v2\AutoHotkey64.exe`.
+
+### Per-tick behavior under this driver
+
+- Run Steps 1–3 of **Per-tick work** in the main `SKILL.md` exactly as written.
+- In **Step 4**, do **not** call `ScheduleWakeup` — the auto-typer is the pacer (this is the fallback branch of Step 4 in the main skill).
+- End every assistant response with the literal sentence `Awaiting next "continue" tick.` so the next iteration is unambiguously identifiable
+  in the transcript.
+- When the next user message is `continue` (auto-typed by AHK) or any close paraphrase, treat it as the next tick of default-loop
+  `/pr-converge` and re-enter from Step 1 against the freshest PR state.
+
+### Convergence cleanup
+
+On back-to-back clean (the existing convergence rule in the main skill), run `gh pr ready`, then kill the auto-typer when this session used
+  this AHK pacing path:
+
+```bash
+pwsh -NoProfile -Command "Get-CimInstance Win32_Process -Filter \"Name='AutoHotkey64.exe'\" | Where-Object CommandLine -like '*cursor-agents-continue.ahk*' | ForEach-Object { Stop-Process -Id $_.ProcessId -Force }"
+```
+
+Report convergence in the same one-sentence shape as the standard flow, plus a second sentence noting the auto-typer was stopped. The skill
+  returns; no next tick fires.
+
+### Gotchas
+
+- **Resolver fallback semantics matter.** `caller-window-pid.ps1` walks up the parent process chain, terminates at `explorer.exe`, and falls
+  back to the foreground window when no GUI ancestor is found. Always verify `MainWindowTitle` after capture — if it isn't the Claude Code
+  session, the auto-typer will fire `continue` into the wrong window and the loop stalls silently.
+- **Tick-duration vs. 5-minute cadence.** The auto-typer fires every 5 minutes regardless of model activity. A tick that runs longer than 5
+  minutes will receive a queued `continue` while still in flight; Claude Code processes these sequentially, so there's no corruption, but the
+  loop pace becomes irregular. Don't try to "fix" this by shortening the AHK interval — the `bugbot run` cadence already has its own pacing
+  baked into the standard flow.
+- **AHK runs as `#SingleInstance Force`.** Re-running the launcher replaces the prior instance silently. Safe to re-issue if the loop appears
+  stalled.
+- **`Stop-Process -Force` on `AutoHotkey64` is broad.** It kills every AHK instance, not just the one this skill started. When the user has
+  unrelated AHK utilities running, scope the kill by command-line match instead:
+  ```bash
+  pwsh -NoProfile -Command "Get-CimInstance Win32_Process -Filter \"Name='AutoHotkey64.exe'\" | Where-Object CommandLine -like '*cursor-agents-continue.ahk*' | ForEach-Object { Stop-Process -Id $_.ProcessId -Force }"
+  ```
+- **State-line responsibility is unchanged.** The state line (phase, bugbot_clean_at, inline_lag_streak, tick_count) is still emitted at the
+  end of every tick — it's how the next tick reads prior state. The auto-typer only fires `continue`; it does not preserve state for you.
+- **No `tick_count` ceiling.** `tick_count` is observability-only (same as the main skill and `state-schema.md`). This path ends on convergence or **Stop conditions** in `SKILL.md`, not on a tick counter.
+- **`/bugteam` is not optional for BUGTEAM ticks.** AHK only paces **when** the next tick runs; it does not replace the bugteam skill. Skipping
+  **`/bugteam`** after a clean Bugbot review breaks the back-to-back contract.
+- **Fix protocol:** use **`Task` + `generalPurpose`** with the clean-coder **Read** preamble from the main [`SKILL.md` Fix protocol](../SKILL.md#fix-protocol)
+  (never a bare `generalPurpose` production edit). Ensure the clean-coder agent markdown exists at `~/.claude/agents/clean-coder.md` (Windows:
+  `%USERPROFILE%\.claude\agents\clean-coder.md`); copy into `.cursor/agents/` only if you want a repo-local duplicate.
+
+## BUGBOT inline-lag (this path only)
+
+When Step 2 BUGBOT branch c routes to API lag and you are on **this** pacing path: complete Step 4 per **Per-tick behavior under this driver**
+  above (fixed AHK cadence — there is no 60s shortcut). The inline comments should appear on the next tick.
+
+## Convergence
+
+On back-to-back clean: stop the auto-typer per **Convergence cleanup** above; omit `ScheduleWakeup` (not used on this path).
+
+## Stop / safety (this path)
+
+On hard blockers or user stop: omit loop pacing and stop the AHK auto-typer if it was started, per main skill **Stop conditions**. Use the same **scoped** `Get-CimInstance` / `Stop-Process` command as **Convergence cleanup** (command-line match on `cursor-agents-continue.ahk`) so unrelated AutoHotkey instances are not killed.

package/skills/pr-converge/workflows/schedule-wakeup-loop.md

@@ -0,0 +1,37 @@
+# ScheduleWakeup loop pacing (pr-converge)
+
+Load this document when **`ScheduleWakeup` is available** in the parent harness session and you use it for converge **loop pacing** (primary /
+  orchestrated-teams path). Follow it for **every** instruction below that depends on that choice. Shared bugbot / bugteam / Fix protocol steps
+  stay in the main `SKILL.md`.
+
+## Session behavior
+
+Call `ScheduleWakeup` from this same session so the next tick fires back into **this** transcript with the prior tick's state line and PR
+  context still addressable.
+
+## Step 4 — `ScheduleWakeup` branch
+
+At end of tick (unless convergence or another stop condition already omitted pacing), call `ScheduleWakeup` with:
+
+- `delaySeconds: 270` whenever bugbot was just re-triggered (whether by Step 3 directly, by the Fix protocol's mandatory re-trigger, or by
+  BUGTEAM branch 1's same-tick re-trigger). Bugbot finishes a review in 1–4 minutes, so 270s stays under the 5-minute prompt-cache TTL while
+  giving a margin past bugbot's typical upper bound. The single exception is the BUGBOT inline-lag branch in Step 2 of the main skill, which
+  uses `delaySeconds: 60` because no re-trigger fired and the only thing being awaited is GitHub's inline-comments API catching up.
+- `reason`: one short sentence on what is being awaited, including the current `phase` and `bugbot_clean_at` SHA when set.
+- `prompt: "/pr-converge"` — re-enters this skill on the next firing with default loop semantics (no need for the user to type `/loop`). If
+  the parent harness requires the `/loop` wrapper for wakeups to execute, `prompt: "/loop /pr-converge"` is equivalent.
+
+## BUGBOT inline-lag (this path only)
+
+When Step 2 BUGBOT branch c routes to API lag and you are on **this** pacing path: complete Step 4 with `ScheduleWakeup` using `delaySeconds:
+  60` (lag is short-lived).
+
+## Convergence
+
+On back-to-back clean: **omit** further `ScheduleWakeup` calls. Do not start the AHK auto-typer for loop pacing when this path is the active
+  pacer.
+
+## Stop / safety (this path)
+
+On hard blockers or user stop: omit `ScheduleWakeup` per main skill **Stop conditions**. If the session never used AHK for pacing,
+  skip AHK shutdown commands in the companion AHK workflow.

package/skills/qbug/SKILL.md

@@ -19,8 +19,8 @@ description: >-
 
 Shared artifacts with /bugteam are referenced below by path, using the `${CLAUDE_SKILL_DIR}` host-substitution convention (both skills land under `~/.claude/skills/` after install):
 
-- Pre-flight script: `${CLAUDE_SKILL_DIR}/../bugteam/scripts/bugteam_preflight.py`
-- Code-rules gate script: `${CLAUDE_SKILL_DIR}/../bugteam/scripts/bugteam_code_rules_gate.py`
+- Pre-flight script: `${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/preflight.py`
+- Code-rules gate script: `${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/code_rules_gate.py`
 - Bug category rubric A–J: [`bugteam/PROMPTS.md`](../bugteam/PROMPTS.md#audit-spawn-prompt-xml-bugfind-teammate)
 - **Audit contract** (finding schema, proof-of-absence, adversarial pass, Haiku secondary, post-fix self-audit, diagnostics JSON): [`bugteam/reference/audit-contract.md`](../bugteam/reference/audit-contract.md)
 - PR comment lifecycle shape: [`bugteam/SKILL.md`](../bugteam/SKILL.md#step-25-pr-comments-one-review-per-loop)
@@ -48,7 +48,7 @@ Refusals — first match wins; respond with the quoted line exactly and stop:
 ## Step 0: Pre-flight
 
 ```bash
-python "${CLAUDE_SKILL_DIR}/../bugteam/scripts/bugteam_preflight.py"
+python "${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/preflight.py"
 ```
 
 `${CLAUDE_SKILL_DIR}` is host-substituted before the shell runs. Non-zero → fix before continuing. `BUGTEAM_PREFLIGHT_SKIP=1` is emergency only. Add `--pre-commit` when `.pre-commit-config.yaml` exists.
@@ -97,7 +97,7 @@ import os
 from pathlib import Path
 
 skill_dir = Path(os.environ["CLAUDE_SKILL_DIR"])
-gate_script_path = (skill_dir / ".." / "bugteam" / "scripts" / "bugteam_code_rules_gate.py").resolve()
+gate_script_path = (skill_dir / ".." / ".." / "_shared" / "pr-loop" / "scripts" / "code_rules_gate.py").resolve()
 categories_file_path = (skill_dir / ".." / "bugteam" / "PROMPTS.md").resolve()
 ```
 

package/skills/qbug/test_qbug_skill_post_fix_audit.py

@@ -22,8 +22,8 @@ def _load_skill_text() -> str:
 
 def test_should_require_post_fix_gate_before_git_add() -> None:
     skill_text = _load_skill_text()
-    assert "bugteam_code_rules_gate" in skill_text, (
-        "FIX step must run bugteam_code_rules_gate against modified files"
+    assert "code_rules_gate" in skill_text, (
+        "FIX step must run code_rules_gate against modified files"
     )
     assert "post-fix" in skill_text.lower() or "post_fix" in skill_text.lower(), (
         "FIX step must reference a post-fix audit phase"