claude-dev-env 1.93.1 → 1.95.0

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

@@ -0,0 +1,321 @@
+"""Contract-pin and flag tests for check_convergence.
+
+::
+
+    check_all(all gates passing)       -> exit 0, "All pre-conditions met ..."
+    check_all(one gate failing)        -> exit 1, "One or more ... do not mark ready."
+    _get_pr_head_sha raises SystemExit -> exit 2 propagates
+    parse_arguments([... --bugteam-post-blocked]) -> bugteam_post_blocked True
+
+The pin tests fix the stdout the four consumers parse (converge.mjs, pr-converge,
+bugteam, qbug) byte-for-byte, plus the exit codes and CLI surface. The flag tests
+drive the ``--bugteam-post-blocked`` bypass.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+from types import ModuleType
+
+import pytest
+
+import _pr_converge_path_setup  # noqa: F401
+from pr_converge_skill_constants.constants import EXIT_CODE_GH_ERROR
+
+_SCRIPTS_DIRECTORY = Path(__file__).absolute().parent
+_PR_CONVERGE_DIRECTORY = _SCRIPTS_DIRECTORY.parent
+
+CURRENT_HEAD_SHA = "abcdef1234567890abcdef1234567890abcdef12"
+
+_ALL_LEAF_GATE_NAMES = [
+    "_check_bugbot",
+    "_check_bugbot_not_dirty",
+    "_check_bugteam_clean",
+    "_check_bot_review",
+    "_count_unresolved_bot_threads",
+    "_get_mergeable",
+    "_check_no_pending_reviews",
+]
+
+EXPECTED_ALL_PASS_STDOUT = (
+    "HEAD: abcdef1\n\n"
+    "1. bugbot_clean_at == current_head: PASS — clean\n"
+    "2. bugbot review body clean: PASS — clean\n"
+    "3. bugteam_clean_at == current_head: PASS — clean\n"
+    "4. copilot_clean_at == current_head: PASS — clean\n"
+    "5. zero unresolved bot threads: PASS — clean\n"
+    "6. PR is mergeable: PASS — clean\n"
+    "7. no pending requested reviews: PASS — clean\n\n"
+    "All pre-conditions met — PR is ready to mark ready.\n"
+)
+
+EXPECTED_BUGBOT_DOWN_STDOUT = (
+    "HEAD: abcdef1\n\n"
+    "1. bugbot_clean_at == current_head: PASS — bypassed (bugbot_down)\n"
+    "2. bugteam_clean_at == current_head: PASS — clean\n"
+    "3. copilot_clean_at == current_head: PASS — clean\n"
+    "4. zero unresolved bot threads: PASS — clean\n"
+    "5. PR is mergeable: PASS — clean\n"
+    "6. no pending requested reviews: PASS — clean\n\n"
+    "All pre-conditions met — PR is ready to mark ready.\n"
+)
+
+EXPECTED_COPILOT_DOWN_STDOUT = (
+    "HEAD: abcdef1\n\n"
+    "1. bugbot_clean_at == current_head: PASS — clean\n"
+    "2. bugbot review body clean: PASS — clean\n"
+    "3. bugteam_clean_at == current_head: PASS — clean\n"
+    "4. copilot_clean_at == current_head: PASS — bypassed (copilot_down)\n"
+    "5. zero unresolved bot threads: PASS — clean\n"
+    "6. PR is mergeable: PASS — clean\n"
+    "7. no pending requested reviews: PASS — bypassed (copilot_down)\n\n"
+    "All pre-conditions met — PR is ready to mark ready.\n"
+)
+
+EXPECTED_FAIL_SUMMARY = "One or more pre-conditions not met — do not mark ready.\n"
+
+
+def _load_check_convergence() -> ModuleType:
+    if str(_PR_CONVERGE_DIRECTORY) not in sys.path:
+        sys.path.insert(0, str(_PR_CONVERGE_DIRECTORY))
+    if str(_SCRIPTS_DIRECTORY) not in sys.path:
+        sys.path.insert(0, str(_SCRIPTS_DIRECTORY))
+    module_path = _SCRIPTS_DIRECTORY / "check_convergence.py"
+    spec = importlib.util.spec_from_file_location(
+        "check_convergence_contract_under_test", 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
+
+
+check_convergence = _load_check_convergence()
+
+
+def _clean_head(**_call_keywords: object) -> str:
+    return CURRENT_HEAD_SHA
+
+
+def _clean_gate(**_call_keywords: object) -> tuple[bool, str]:
+    return True, "clean"
+
+
+def _refuse_bugteam_clean(**_call_keywords: object) -> tuple[bool, str]:
+    raise AssertionError(
+        "_check_bugteam_clean must not run when is_bugteam_post_blocked=True"
+    )
+
+
+def _patch_gates_clean(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(check_convergence, "_get_pr_head_sha", _clean_head)
+    for each_gate_name in _ALL_LEAF_GATE_NAMES:
+        monkeypatch.setattr(check_convergence, each_gate_name, _clean_gate)
+
+
+def test_all_pass_stdout_and_exit_code_match_the_pinned_contract(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    _patch_gates_clean(monkeypatch)
+    exit_code = check_convergence.check_all(
+        owner="o", repo="r", number=1, is_bugbot_down=False, is_copilot_down=False
+    )
+    assert capsys.readouterr().out == EXPECTED_ALL_PASS_STDOUT
+    assert exit_code == 0
+
+
+def test_bugbot_down_bypass_line_matches_the_pinned_contract(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    _patch_gates_clean(monkeypatch)
+    exit_code = check_convergence.check_all(
+        owner="o", repo="r", number=1, is_bugbot_down=True, is_copilot_down=False
+    )
+    assert capsys.readouterr().out == EXPECTED_BUGBOT_DOWN_STDOUT
+    assert exit_code == 0
+
+
+def test_copilot_down_bypass_lines_match_the_pinned_contract(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    _patch_gates_clean(monkeypatch)
+    exit_code = check_convergence.check_all(
+        owner="o", repo="r", number=1, is_bugbot_down=False, is_copilot_down=True
+    )
+    assert capsys.readouterr().out == EXPECTED_COPILOT_DOWN_STDOUT
+    assert exit_code == 0
+
+
+def test_a_failing_gate_yields_exit_one_and_the_fail_summary(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    _patch_gates_clean(monkeypatch)
+
+    def _blocked_mergeable(**_call_keywords: object) -> tuple[bool, str]:
+        return False, "blocked"
+
+    monkeypatch.setattr(check_convergence, "_get_mergeable", _blocked_mergeable)
+    exit_code = check_convergence.check_all(
+        owner="o", repo="r", number=1, is_bugbot_down=False, is_copilot_down=False
+    )
+    captured_stdout = capsys.readouterr().out
+    assert "6. PR is mergeable: FAIL — blocked\n" in captured_stdout
+    assert captured_stdout.endswith(EXPECTED_FAIL_SUMMARY)
+    assert exit_code == 1
+
+
+def test_gh_error_exit_code_is_two_and_propagates_from_head_fetch(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    def _raise_gh_error(**_call_keywords: object) -> str:
+        raise SystemExit(EXIT_CODE_GH_ERROR)
+
+    monkeypatch.setattr(check_convergence, "_get_pr_head_sha", _raise_gh_error)
+    with pytest.raises(SystemExit) as raised:
+        check_convergence.check_all(
+            owner="o", repo="r", number=1, is_bugbot_down=False, is_copilot_down=False
+        )
+    assert EXIT_CODE_GH_ERROR == 2
+    assert raised.value.code == 2
+
+
+def test_existing_cli_flags_stay_on_the_argument_surface() -> None:
+    arguments = check_convergence.parse_arguments(
+        [
+            "--owner",
+            "o",
+            "--repo",
+            "r",
+            "--pr-number",
+            "1",
+            "--bugbot-down",
+            "--copilot-down",
+        ]
+    )
+    assert arguments.owner == "o"
+    assert arguments.repo == "r"
+    assert getattr(arguments, "pr_number") == 1
+    assert arguments.bugbot_down is True
+    assert arguments.copilot_down is True
+
+
+def test_skip_bugteam_gate_when_bugteam_post_blocked_is_true(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    _patch_gates_clean(monkeypatch)
+    monkeypatch.setattr(
+        check_convergence, "_check_bugteam_clean", _refuse_bugteam_clean
+    )
+    exit_code = check_convergence.check_all(
+        owner="o",
+        repo="r",
+        number=1,
+        is_bugbot_down=False,
+        is_copilot_down=False,
+        is_bugteam_post_blocked=True,
+    )
+    assert "bypassed (bugteam_post_blocked)" in capsys.readouterr().out
+    assert exit_code == 0
+
+
+def test_run_bugteam_gate_when_bugteam_post_blocked_is_false(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    invoked_gate_names: list[str] = []
+
+    def _recording_bugteam_clean(**_call_keywords: object) -> tuple[bool, str]:
+        invoked_gate_names.append("_check_bugteam_clean")
+        return True, "clean"
+
+    _patch_gates_clean(monkeypatch)
+    monkeypatch.setattr(
+        check_convergence, "_check_bugteam_clean", _recording_bugteam_clean
+    )
+    exit_code = check_convergence.check_all(
+        owner="o",
+        repo="r",
+        number=1,
+        is_bugbot_down=False,
+        is_copilot_down=False,
+        is_bugteam_post_blocked=False,
+    )
+    assert "_check_bugteam_clean" in invoked_gate_names
+    assert "bypassed (bugteam_post_blocked)" not in capsys.readouterr().out
+    assert exit_code == 0
+
+
+def test_bugteam_post_blocked_flag_round_trips_through_parse_arguments() -> None:
+    arguments = check_convergence.parse_arguments(
+        ["--owner", "o", "--repo", "r", "--pr-number", "1", "--bugteam-post-blocked"]
+    )
+    assert arguments.bugteam_post_blocked is True
+
+
+def test_bugteam_post_blocked_defaults_to_false_when_flag_absent() -> None:
+    arguments = check_convergence.parse_arguments(
+        ["--owner", "o", "--repo", "r", "--pr-number", "1"]
+    )
+    assert arguments.bugteam_post_blocked is False
+
+
+def test_resolve_bugteam_post_blocked_true_when_flag_set(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("CLAUDE_REVIEWS_DISABLED", raising=False)
+    assert check_convergence._resolve_bugteam_post_blocked(True) is True
+
+
+def test_resolve_bugteam_post_blocked_true_when_env_disables_bugteam(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "bugteam")
+    assert check_convergence._resolve_bugteam_post_blocked(False) is True
+
+
+def test_resolve_bugteam_post_blocked_false_when_flag_unset_and_env_empty(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("CLAUDE_REVIEWS_DISABLED", raising=False)
+    assert check_convergence._resolve_bugteam_post_blocked(False) is False
+
+
+def test_resolve_bugteam_post_blocked_false_when_env_disables_only_copilot(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "copilot")
+    assert check_convergence._resolve_bugteam_post_blocked(False) is False
+
+
+def test_env_bugteam_token_does_not_disable_copilot_or_bugbot_opt_out(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "bugteam")
+    assert check_convergence._resolve_copilot_down(False) is False
+    assert check_convergence._resolve_bugteam_post_blocked(False) is True
+
+
+def test_main_derives_bugteam_post_blocked_from_env_when_flag_omitted(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "bugteam")
+    captured_bugteam_post_blocked: list[bool] = []
+
+    def stub_check_all(
+        *,
+        owner: str,
+        repo: str,
+        number: int,
+        is_bugbot_down: bool,
+        is_copilot_down: bool,
+        is_bugteam_post_blocked: bool = False,
+    ) -> int:
+        captured_bugteam_post_blocked.append(is_bugteam_post_blocked)
+        return 0
+
+    monkeypatch.setattr(check_convergence, "check_all", stub_check_all)
+    exit_code = check_convergence.main(["--owner", "o", "--repo", "r", "--pr-number", "1"])
+    assert exit_code == 0
+    assert captured_bugteam_post_blocked == [True]

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

@@ -0,0 +1,68 @@
+"""Behavioral tests for the review and Bugbot convergence gate leaves.
+
+::
+
+    _flatten_paginated_reviews(two pages) -> newest-first flat list
+    _bugbot_run_conclusion_detail(success) -> (True, "check run ...")
+    _check_bugbot(named complete run) -> (True, "check run ...")
+
+Each test drives the real leaf, stubbing only the ``gh`` transport helpers.
+"""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+import check_convergence_gates as gates
+
+
+def test_flatten_paginated_reviews_flattens_and_sorts_newest_first() -> None:
+    pages = [
+        [{"id": 1, "submitted_at": "2026-01-01T00:00:00Z"}],
+        [{"id": 2, "submitted_at": "2026-03-01T00:00:00Z"}],
+    ]
+    flattened = gates._flatten_paginated_reviews(json.dumps(pages))
+    assert flattened is not None
+    assert [each_review["id"] for each_review in flattened] == [2, 1]
+
+
+def test_flatten_paginated_reviews_returns_none_for_non_list_payload() -> None:
+    assert (
+        gates._flatten_paginated_reviews(json.dumps({"message": "Not Found"})) is None
+    )
+
+
+def test_bugbot_run_conclusion_detail_passes_on_a_complete_conclusion() -> None:
+    complete_conclusion = gates.ALL_BUGBOT_CHECK_RUN_COMPLETE_CONCLUSIONS[0]
+    passed, detail = gates._bugbot_run_conclusion_detail(
+        {"id": 55, "conclusion": complete_conclusion, "html_url": ""}
+    )
+    assert passed is True
+    assert "check run 55" in detail
+
+
+def test_check_bugbot_reports_success_when_the_named_run_is_complete(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    complete_conclusion = gates.ALL_BUGBOT_CHECK_RUN_COMPLETE_CONCLUSIONS[0]
+    run_name = f"x {gates.BUGBOT_CHECK_RUN_NAME_SUBSTRING} y"
+    payload = {
+        "check_runs": [
+            {
+                "name": run_name,
+                "id": 9,
+                "conclusion": complete_conclusion,
+                "html_url": "",
+            }
+        ]
+    }
+
+    def _stub_gh_api(endpoint_path: str) -> tuple[int, str]:
+        return 0, json.dumps(payload)
+
+    monkeypatch.setattr(gates, "_gh_api", _stub_gh_api)
+    passed, detail = gates._check_bugbot(owner="o", repo="r", sha="abc")
+    assert passed is True
+    assert "check run 9" in detail

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

@@ -0,0 +1,75 @@
+"""Behavioral tests for the review-thread and pending-reviewer gate leaves.
+
+::
+
+    _is_unresolved_bot_thread(cursor, unresolved) -> True
+    _count_unresolved_bot_threads(one cursor thread) -> (False, "1 unresolved ...")
+    _format_unresolved_detail(over limit) -> "... and N more"
+
+Each test drives the real leaf, stubbing only the ``gh`` transport helpers.
+"""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+import check_convergence_thread_gates as thread_gates
+
+
+def test_is_unresolved_bot_thread_true_for_cursor_authored_open_thread() -> None:
+    thread = {
+        "isResolved": False,
+        "isOutdated": False,
+        "comments": {"nodes": [{"author": {"login": "cursor[bot]"}}]},
+    }
+    logins = (thread_gates.CURSOR_LOGIN_FILTER_SUBSTRING,)
+    assert thread_gates._is_unresolved_bot_thread(thread, logins) is True
+
+
+def test_is_unresolved_bot_thread_false_for_resolved_thread() -> None:
+    thread = {
+        "isResolved": True,
+        "isOutdated": False,
+        "comments": {"nodes": [{"author": {"login": "cursor[bot]"}}]},
+    }
+    logins = (thread_gates.CURSOR_LOGIN_FILTER_SUBSTRING,)
+    assert thread_gates._is_unresolved_bot_thread(thread, logins) is False
+
+
+def test_count_unresolved_bot_threads_counts_a_single_cursor_thread(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    thread = {
+        "isResolved": False,
+        "isOutdated": False,
+        "path": "src/app.py",
+        "comments": {"nodes": [{"author": {"login": "cursor[bot]"}}]},
+    }
+    review_threads = {
+        "nodes": [thread],
+        "pageInfo": {"hasNextPage": False, "endCursor": None},
+    }
+    graphql_payload = {
+        "data": {"repository": {"pullRequest": {"reviewThreads": review_threads}}}
+    }
+
+    def _stub_gh_graphql(query: str, variables: dict[str, object]) -> tuple[int, str]:
+        return 0, json.dumps(graphql_payload)
+
+    monkeypatch.setattr(thread_gates, "_gh_graphql", _stub_gh_graphql)
+    passed, detail = thread_gates._count_unresolved_bot_threads(
+        owner="o", repo="r", number=1
+    )
+    assert passed is False
+    assert detail.startswith("1 unresolved")
+    assert "src/app.py" in detail
+
+
+def test_format_unresolved_detail_bounds_the_listed_paths() -> None:
+    over_limit = thread_gates.UNRESOLVED_THREAD_DETAIL_MAX + 2
+    all_threads = [{"path": f"file{each_index}.py"} for each_index in range(over_limit)]
+    detail = thread_gates._format_unresolved_detail(all_threads)
+    assert detail.startswith(f"{over_limit} unresolved")
+    assert "more" in detail

package/skills/pr-fix-protocol/SKILL.md

@@ -9,56 +9,56 @@ description: >-
 
 # PR Fix Protocol
 
-**Core principle:** a finding is addressed only when the fix is pushed, the thread carries a reply, and the thread is resolved — as one unit of work. Anything less leaves a convergence gate stalled.
+**Core principle:** a finding is addressed only when the fix is pushed, the thread carries a reply, and the thread is resolved — as one unit of work. Anything short of all three leaves a convergence gate stalled.
 
 ## How callers invoke this
 
-- **Skill-capable contexts** (a lead session with the `Skill` tool): `Skill({skill: "pr-fix-protocol", args: "--skill <caller> --pr <URL> --worktree <path> [findings payload or 'sweep']"})`.
-- **Fallback** (a subagent or teammate without the `Skill` tool): the caller's spawn prompt says "Read `~/.claude/skills/pr-fix-protocol/SKILL.md` and apply it with the parameters below."
+- **Skill-capable contexts** (a lead session that holds the `Skill` tool): `Skill({skill: "pr-fix-protocol", args: "--skill <caller> --pr <URL> --worktree <path> [findings payload or 'sweep']"})`.
+- **Fallback** (a subagent or teammate without the `Skill` tool): the caller's spawn prompt says to read `~/.claude/skills/pr-fix-protocol/SKILL.md` and apply it with the parameters below.
 
-The caller passes: its identity, the PR scope, the PR worktree path, this round's findings (or `sweep` for a thread sweep with no fresh findings), and its post-push obligations (which clean-SHA state fields to reset, which reviewers to re-trigger).
+The caller passes: its identity, the PR scope, the PR worktree path, this round's findings (or `sweep` for a thread sweep with no fresh findings), and its post-push obligations — which clean-SHA state fields to reset and which reviewers to re-trigger.
 
 ## Executor choice
 
-- **Single-PR loops** (no shared `state.json`): the lead spawns `Agent(subagent_type: "clean-coder")` to write the fix. Full-stop if `Agent` is unavailable. A spawned clean-coder does not inherit the lead's working directory — name the PR worktree path in its prompt and direct it to edit, stage, and commit there.
-- **Multi-PR orchestration** (shared `state.json`): a per-PR clean-coder teammate owns edits, replies, and state writes; the orchestrator never edits inline. The teammate obligations (reply before writing state, state fields, idle handoff) live in the calling skill's multi-PR reference.
+- **Single-PR loops** (no shared `state.json`): the lead spawns `Agent(subagent_type: "clean-coder")` to write the fix. Stop when `Agent` is unavailable. A spawned clean-coder starts in its own working directory, so its prompt names the PR worktree path and directs it to edit, stage, and commit there.
+- **Multi-PR orchestration** (shared `state.json`): a per-PR clean-coder teammate owns edits, replies, and state writes; the orchestrator holds back from inline edits. The teammate obligations — reply before writing state, which state fields to set, idle handoff — live in the calling skill's multi-PR reference.
 
-Run every git command in the PR worktree — `git add`, `git commit`, and `git push` act on the repo of the current working directory, so a cross-repo PR's fix lands in the PR's repo only when the cwd is its worktree.
+Run every git command in the PR worktree. `git add`, `git commit`, and `git push` act on the repo of the current working directory, so a cross-repo PR's fix lands in the PR's repo only when the working directory is its worktree.
 
 ## The fix sequence
 
-Follow the shared 13-step sequence in [`_shared/pr-loop/fix-protocol.md`](../../_shared/pr-loop/fix-protocol.md) exactly: read each file:line, capture the pre-fix SHA and contents, TDD where the finding has behavior, apply narrowly, `py_compile`, post-fix self-audit, stage by explicit path, one commit, fast-forward push, then reply + resolve atomically per thread. Its Constraints section (narrow scope, no `--no-verify`, preserve helpers) binds every executor.
+Follow the shared 13-step sequence in [`_shared/pr-loop/fix-protocol.md`](../../_shared/pr-loop/fix-protocol.md) exactly: read each file:line, capture the pre-fix SHA and contents, write a failing test first where the finding has behavior, apply the fix narrowly, `py_compile`, run the post-fix self-audit, stage by explicit path, make one commit, fast-forward push, then reply and resolve atomically per thread. Its Constraints section — narrow scope, keep the commit hooks, preserve helpers — binds every executor.
 
-**Reply transport:** the GitHub MCP `add_reply_to_pull_request_comment` is primary. `python "$HOME/.claude/skills/pr-converge/scripts/post_fix_reply.py" --owner <O> --repo <R> --pr-number <N> --in-reply-to <COMMENT_ID> --body "Fixed in <SHA> — <what changed>"` is the fallback for script-only contexts and multi-PR teammates. Both carry the body shape from [`_shared/pr-loop/audit-reply-template.md`](../../_shared/pr-loop/audit-reply-template.md). For body-only findings with no inline thread, post a top-level review reply citing the new HEAD SHA.
+**Reply transport:** the GitHub MCP `add_reply_to_pull_request_comment` is primary. For a script-only context or a multi-PR teammate, the fallback is `python "$HOME/.claude/skills/pr-converge/scripts/post_fix_reply.py" --owner <O> --repo <R> --pr-number <N> --in-reply-to <COMMENT_ID> --body "Fixed in <SHA> — <what changed>"`. Both carry the body shape from [`_shared/pr-loop/audit-reply-template.md`](../../_shared/pr-loop/audit-reply-template.md). For a body-only finding with no inline thread, post a top-level review reply that cites the new HEAD SHA.
 
-**Thread resolution:** `pull_request_review_write(method="resolve_thread", threadId=<PRRT node id>)` right after each reply. Harvest thread node ids (`PRRT_…`) from `get_review_comments` at fetch time.
+**Thread resolution:** call `pull_request_review_write(method="resolve_thread", threadId=<PRRT node id>)` right after each reply. Harvest the thread node ids (`PRRT_…`) from `get_review_comments` at fetch time.
 
 ## The unresolved-thread sweep (hard gate)
 
-No caller advances a phase, records a clean SHA, or marks a PR ready while ANY unresolved review thread exists on the PR.
+A caller advances a phase, records a clean SHA, or marks a PR ready only when the PR carries zero unresolved review threads.
 
 ```
 pull_request_read(method="get_review_comments") → filter threads where is_resolved == false
 ```
 
-- The filter is purely `is_resolved == false`. Author, anchor commit, and `is_outdated` are all irrelevant to the count.
-- `is_outdated` is informational, not a skip flag: GitHub marks a thread outdated when its anchor line changed, but the concern can still apply to current HEAD (the fix may have moved, not landed). Verify each outdated thread against current HEAD like any other.
-- Per unresolved thread: verify the concern against current HEAD. The concern holds → fix (this protocol) → reply → resolve. The concern does not hold on current HEAD → reply-with-note explaining why → resolve.
-- Code changed during the sweep → push and hand control back to the caller's re-entry phase. Only resolutions, no code → re-run the sweep without resetting caller state.
+- The filter is purely `is_resolved == false`. Author, anchor commit, and `is_outdated` play no part in the count.
+- `is_outdated` is informational, not a skip flag. GitHub marks a thread outdated when its anchor line changes, yet the concern can still apply to current HEAD — the fix may have moved rather than landed. Verify each outdated thread against current HEAD like any other.
+- Per unresolved thread: verify the concern against current HEAD. The concern holds → fix (this protocol) → reply → resolve. The concern does not hold on current HEAD → reply with a note that explains why → resolve.
+- Code changed during the sweep → push and hand control back to the caller's re-entry phase. Only resolutions and no code → re-run the sweep and keep the caller's state.
 
 ## Post-push obligations
 
 Every push through this protocol:
 
-1. Re-resolve `current_head` (`git rev-parse HEAD` locally; the PR `get` call for API-visible state).
+1. Re-resolve `current_head` — `git rev-parse HEAD` locally, and the PR `get` call for API-visible state.
 2. Reset the caller-named clean-SHA fields to null (`bugbot_clean_at`, `code_review_clean_at`, `copilot_clean_at` — whichever the caller tracks). A new HEAD invalidates every prior clean.
-3. Re-trigger reviewers per the caller's parameter (for Cursor Bugbot, the `reviewer-gates` Bugbot flow; for Copilot, the caller's request step). Audit-family callers (`bugteam`, `qbug`) skip re-triggering — their next loop iteration is the reviewer.
+3. Re-trigger reviewers per the caller's parameter — for Cursor Bugbot the `reviewer-gates` Bugbot flow, for Copilot the caller's request step. Audit-family callers (`bugteam`, `qbug`) skip re-triggering, since their next loop iteration is the reviewer.
 
 ## Gotchas
 
-- **Reply-then-resolve, atomic per thread.** Batching all replies before any resolves, or yielding to the orchestrator between the two, leaves threads half-addressed when a run dies mid-loop.
-- **An unchanged HEAD after step 11 means no commit landed** — exit `stuck — could not address findings` rather than reporting the findings as fixed.
-- **A resolved thread with no reply reads as dismissed.** Reviewers (and the humans reading the PR) need the one-paragraph explanation the template carries.
+- **Reply, then resolve, atomic per thread.** Batching every reply ahead of any resolve, or yielding to the orchestrator between the two, leaves threads half-addressed when a run dies mid-loop.
+- **An unchanged HEAD after step 11 means no commit landed.** Exit `stuck — could not address findings` rather than report the findings as fixed.
+- **A resolved thread with no reply reads as dismissed.** Reviewers and the humans reading the PR need the one-paragraph explanation the template carries.
 
 ## Folder map
 

package/skills/privacy-hygiene/SKILL.md

@@ -22,8 +22,8 @@ Find and remove personal data and high-confidence secrets before they land in gi
 
 | Category | Blocked examples | Allowed residual |
 |---|---|---|
-| Email | `person@company.io` | `user@example.com`, `user@example.org`, `user@example.net` |
-| Home path | `C:/Users/realname/...`, `/Users/realname/...`, `/home/realname/...` | `C:/Users/example/...`, `C:/Users/<you>/...`, `/Users/alice/...` |
+| Email | `user@example.com` | `user@example.com`, `user@example.org`, `user@example.net` |
+| Home path | `C:/Users/example/...`, `/Users/example/...`, `/home/example/...` | `C:/Users/example/...`, `C:/Users/<you>/...`, `/Users/alice/...` |
 | LAN address | Unlisted `10.x` / `172.16–31.x` / `192.168.x` | Public addresses; your NAS host from `CLAUDE_NAS_HOST` or `~/.claude/local-identity.json`; entries in `ALL_ALLOWLISTED_PRIVATE_IP_ADDRESSES` |
 | Secret | `ghp_…`, `github_pat_…`, `AKIA…`, PEM private-key headers | Public keys, redacted `***`, env var names without values |
 
@@ -55,7 +55,7 @@ git diff --name-only origin/main...HEAD
 Run from the repo root (PowerShell-friendly example):
 
 ```
-rg -n --hidden -g '!node_modules' -g '!.git' -e '@[A-Za-z0-9.-]+\.[A-Za-z]{2,}' -e 'Users[/\\][^/\\]+' -e '/home/[^/]+' -e '\b(10\.\d+\.\d+\.\d+|192\.168\.\d+\.\d+|172\.(1[6-9]|2\d|3[0-1])\.\d+\.\d+)\b' -e '\b(ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9_]{20,}\b' -e '\bgithub_pat_[A-Za-z0-9_]{20,}\b' -e '\bAKIA[0-9A-Z]{16}\b' -e '-----BEGIN [A-Z ]*PRIVATE KEY-----'
+rg -n --hidden -g '!node_modules' -g '!.git' -e '@[A-Za-z0-9.-]+\.[A-Za-z]{2,}' -e 'Users[/\\][^/\\]+' -e '[/]home/[^/]+' -e '\b(10\.\d+\.\d+\.\d+|192\.168\.\d+\.\d+|172\.(1[6-9]|2\d|3[0-1])\.\d+\.\d+)\b' -e '\b(ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9_]{20,}\b' -e '\bgithub_pat_[A-Za-z0-9_]{20,}\b' -e '\bAKIA[0-9A-Z]{16}\b' -e '-----BEGIN [A-Z ]*PRIVATE KEY-----'
 ```
 
 Review each hit. Ignore:
@@ -104,6 +104,7 @@ Hooks register via `hooks/hooks.json` into `~/.claude/settings.json`. Once insta
 ## Open knobs
 
 - **NAS / LAN allowlist:** Unlisted private IPs are blocked. The scanner resolves your NAS host from `CLAUDE_NAS_HOST`, then `~/.claude/local-identity.json` (`nas.host`), and allowlists it when it is a private address, so the committed tree holds no real host. `ALL_ALLOWLISTED_PRIVATE_IP_ADDRESSES` in `hooks_constants` holds the static allowlist for any host every machine must share.
+- **Commit-scan exempt repositories:** named owner/repo slugs skip the staged-commit PII scan only. Set `CLAUDE_PII_EXEMPT_REPOS` (comma-separated `owner/repo` values) or list them under `pii_exempt_repositories` in `~/.claude/local-identity.json`. Matching uses the repository's `remote.origin.url` and accepts only the exact host `github.com` (https, ssh scheme, or scp-style). A repository with no readable origin is never exempt (fail-closed to scanning). Write / Edit / MultiEdit and durable post bodies still scan in every repository.
 - **Public maintainer identity:** when a real email or name is intentional product surface, keep it and note that in the PR body so reviewers do not treat it as a leak.
 
 ## What this skill does not do

package/skills/reviewer-gates/SKILL.md

@@ -61,26 +61,44 @@ Run the pre-check once per run, not per tick or per round. Every later tick read
 
 ## Gate 3: Bugbot trigger, acknowledge, and CI-detect
 
-Cursor Bugbot signals through CI check runs, not always through a posted review. The decision tree runs against `<current_head>` with `check_bugbot_ci.py` (installed at `$HOME/.claude/skills/pr-converge/scripts/check_bugbot_ci.py`; `--help` documents every mode):
+Cursor Bugbot signals through CI check runs.
+Mode flags and exit codes for `check_bugbot_ci.py` live in the script docstring
+— run
+`python "$HOME/.claude/skills/pr-converge/scripts/check_bugbot_ci.py" --help`
+for every mode. Caller action sequence against `<current_head>`:
 
 1. **Silent-pass pre-check (always first).**
    `python "$HOME/.claude/skills/pr-converge/scripts/check_bugbot_ci.py" --check-clean --owner <O> --repo <R> --sha <current_head>`
-   - Exit 0 — Bugbot CI completed with a `success`/`neutral` conclusion and posted no review: a silent pass. Record `bugbot_clean_at = <current_head>` and stop; do not trigger.
-   - Exit 1 (not a silent pass) or exit 2 (gh CLI error, silent pass not confirmable) — continue.
+   - Silent pass confirmed → record `bugbot_clean_at = <current_head>` and stop; do not trigger.
+   - Silent pass not confirmed → continue.
 2. **Already-queued check.**
    `... check_bugbot_ci.py --check-active --owner <O> --repo <R> --sha <current_head>`
-   - Exit 0 — Bugbot is already queued on this commit. Skip posting; wait for completion (callers schedule their own wakeup).
-   - Exit 1 — continue.
-3. **Trigger.** Post exactly `bugbot run` as an issue comment (`add_issue_comment`) — no `@cursor[bot]` mention, no other text. `bugbot run` is empirically the only re-trigger Cursor Bugbot recognizes; every other phrasing silently no-ops. Wait 8 seconds with an in-turn Monitor delay, never a foreground `sleep` (blocked in headless runs).
+   - Already queued → skip posting; wait for completion (callers schedule their own wakeup).
+   - Not active → continue.
+3. **Trigger.** Post exactly `bugbot run` as an issue comment (`add_issue_comment`) — no `@cursor[bot]` mention, no other text. `bugbot run` is the only re-trigger Cursor Bugbot recognizes; every other phrasing silently no-ops. Wait 8 seconds with an in-turn Monitor delay, never a foreground `sleep` (blocked in headless runs).
 4. **Acknowledge check.**
    `... check_bugbot_ci.py --owner <O> --repo <R> --sha <current_head>`
-   - Exit 0 — a check run is present: record `bugbot_acknowledged_at = <now, ISO 8601>`; the caller polls on its own cadence.
-   - Exit non-zero — Bugbot is down: set `bugbot_down = true` and route past the Bugbot phase; the run continues on its remaining signals.
+   - Check run present → record `bugbot_acknowledged_at = <now, ISO 8601>`; the caller polls on its own cadence.
+   - Check run absent → Bugbot is down: set `bugbot_down = true` and route past the Bugbot phase; the run continues on its remaining signals.
 
 The silent-pass pre-check runs first so a bot that already finished cleanly is never re-prompted — Bugbot refuses to re-run on an evaluated commit, and without the pre-check the acknowledge step would falsely mark `bugbot_down = true`.
 
 **Flag reset rule:** `bugbot_down` resets to false whenever `<current_head>` changes — a new HEAD invalidates the old down-detection. `copilot_down` never resets mid-run; it holds until the run ends.
 
+## Convergence-check bypass flags
+
+When a reviewer is down, `check_convergence.py` must skip that reviewer's gate so the run still marks ready on its remaining signals. Each condition has one CLI flag and one matching `CLAUDE_REVIEWS_DISABLED` token:
+
+| Condition | `check_convergence.py` flag | `CLAUDE_REVIEWS_DISABLED` token |
+|---|---|---|
+| Bugbot down or off | `--bugbot-down` | `bugbot` |
+| Copilot down or opted out | `--copilot-down` | `copilot` |
+| Bugteam CLEAN post blocked | `--bugteam-post-blocked` | `bugteam` |
+
+The caller passes the flag on its own `check_convergence.py` run. The flag alone does not reach the independent mark-ready blocker hook, which re-runs `check_convergence.py` with no flags on `gh pr ready`. Each flag also honors its token: `check_convergence.py` reads the same bypass from `CLAUDE_REVIEWS_DISABLED`. So export the matching token in the same shell before `gh pr ready`, and the hook's no-flag re-check inherits the bypass through the env. Combine tokens with commas when more than one reviewer is down (`CLAUDE_REVIEWS_DISABLED="copilot,bugteam"`).
+
+The `bugteam` token here means the bugteam CLEAN-review gate is skipped for this convergence check. It does not disable the bugbot or copilot gates: each token is scoped to its own reviewer.
+
 ## Gotchas
 
 - **`bugbot run` is load-bearing text.** Alternative phrasings (`@cursor run`, `cursor review`, `bugbot please`) return no error and do nothing.