claude-dev-env 1.45.0 → 1.46.0

package/_shared/pr-loop/scripts/pr_loop_shared_constants/reviews_disabled_constants.py

@@ -5,4 +5,5 @@ from __future__ import annotations
 CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME: str = "CLAUDE_REVIEWS_DISABLED"
 CLAUDE_REVIEWS_DISABLED_TOKEN_SEPARATOR: str = ","
 CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN: str = "bugteam"
+CLAUDE_REVIEWS_DISABLED_BUGBOT_TOKEN: str = "bugbot"
 EXIT_CODE_BUGTEAM_DISABLED_VIA_ENV: int = 7

package/_shared/pr-loop/scripts/reviews_disabled.py

@@ -7,9 +7,12 @@ rules and disabled-token taxonomy live in exactly one place.
 
 from __future__ import annotations
 
+import argparse
 import os
+import sys
 
 from pr_loop_shared_constants.reviews_disabled_constants import (
+    CLAUDE_REVIEWS_DISABLED_BUGBOT_TOKEN,
     CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN,
     CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME,
     CLAUDE_REVIEWS_DISABLED_TOKEN_SEPARATOR,
@@ -18,28 +21,98 @@ from pr_loop_shared_constants.reviews_disabled_constants import (
 
 
 __all__ = [
+    "CLAUDE_REVIEWS_DISABLED_BUGBOT_TOKEN",
     "CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN",
     "CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME",
     "CLAUDE_REVIEWS_DISABLED_TOKEN_SEPARATOR",
     "EXIT_CODE_BUGTEAM_DISABLED_VIA_ENV",
+    "is_bugbot_disabled_via_env",
     "is_bugteam_disabled_via_env",
+    "main",
 ]
 
 
-def is_bugteam_disabled_via_env() -> bool:
-    """Check whether CLAUDE_REVIEWS_DISABLED opts the bug-audit family out of running.
+def _is_reviewer_disabled_via_env(reviewer_token: str) -> bool:
+    """Check whether CLAUDE_REVIEWS_DISABLED lists the given reviewer token.
+
+    Args:
+        reviewer_token: The reviewer token to look for, already lowercase
+            (for example the bugteam or bugbot token constant).
 
     Returns:
-        True when the env var contains the literal ``bugteam`` token
-        (comma-separated, case-insensitive, whitespace-tolerant).
+        True when the env var contains ``reviewer_token`` as one of its
+        comma-separated entries (case-insensitive, whitespace-tolerant).
     """
-    reviews_disabled_env_var_name = CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME
     reviews_disabled_token_separator = CLAUDE_REVIEWS_DISABLED_TOKEN_SEPARATOR
-    reviews_disabled_bugteam_token = CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN
-    raw_value = os.environ.get(reviews_disabled_env_var_name, "")
+    disabled_reviewers_text = os.environ.get(CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME, "")
     all_disabled_tokens = frozenset(
         each_raw_token.strip().lower()
-        for each_raw_token in raw_value.split(reviews_disabled_token_separator)
+        for each_raw_token in disabled_reviewers_text.split(
+            reviews_disabled_token_separator
+        )
         if each_raw_token.strip()
     )
-    return reviews_disabled_bugteam_token in all_disabled_tokens
+    return reviewer_token in all_disabled_tokens
+
+
+def is_bugteam_disabled_via_env() -> bool:
+    """Check whether CLAUDE_REVIEWS_DISABLED opts the bug-audit family out.
+
+    Returns:
+        True when the env var lists the ``bugteam`` token.
+    """
+    return _is_reviewer_disabled_via_env(CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN)
+
+
+def is_bugbot_disabled_via_env() -> bool:
+    """Check whether CLAUDE_REVIEWS_DISABLED opts Cursor Bugbot out.
+
+    Returns:
+        True when the env var lists the ``bugbot`` token.
+    """
+    return _is_reviewer_disabled_via_env(CLAUDE_REVIEWS_DISABLED_BUGBOT_TOKEN)
+
+
+def parse_arguments(all_argv: list[str]) -> argparse.Namespace:
+    """Parse command-line arguments for the reviewer opt-out check.
+
+    Args:
+        all_argv: Argument list excluding the program name, typically
+            ``sys.argv[1:]``.
+
+    Returns:
+        Namespace exposing a ``reviewer`` attribute constrained to the
+        known reviewer tokens.
+    """
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--reviewer",
+        required=True,
+        choices=[
+            CLAUDE_REVIEWS_DISABLED_BUGBOT_TOKEN,
+            CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN,
+        ],
+        help="Reviewer token to test against CLAUDE_REVIEWS_DISABLED",
+    )
+    return parser.parse_args(all_argv)
+
+
+def main(all_arguments: list[str]) -> int:
+    """Exit 0 when the named reviewer is disabled via CLAUDE_REVIEWS_DISABLED.
+
+    Args:
+        all_arguments: Argument list excluding the program name.
+
+    Returns:
+        0 when the named reviewer is opted out by the env var, 1 otherwise.
+    """
+    arguments = parse_arguments(all_arguments)
+    disabled_checker_by_reviewer = {
+        CLAUDE_REVIEWS_DISABLED_BUGBOT_TOKEN: is_bugbot_disabled_via_env,
+        CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN: is_bugteam_disabled_via_env,
+    }
+    return 0 if disabled_checker_by_reviewer[arguments.reviewer]() else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/_shared/pr-loop/scripts/tests/test_code_rules_gate.py

@@ -49,6 +49,11 @@ def initialize_git_repository(repository_root: Path) -> None:
     run_git_in_repository(repository_root, "config", "user.email", "test@example.com")
     run_git_in_repository(repository_root, "config", "user.name", "Test")
     run_git_in_repository(repository_root, "config", "commit.gpgsign", "false")
+    disabled_hooks_directory = repository_root / "disabled-git-hooks"
+    disabled_hooks_directory.mkdir()
+    run_git_in_repository(
+        repository_root, "config", "core.hooksPath", str(disabled_hooks_directory)
+    )
 
 
 def commit_all_files(repository_root: Path, commit_message: str) -> None:

package/_shared/pr-loop/scripts/tests/test_reviews_disabled.py

@@ -34,3 +34,60 @@ def test_is_bugteam_disabled_via_env_returns_false_when_env_is_empty(
 ) -> None:
     monkeypatch.delenv("CLAUDE_REVIEWS_DISABLED", raising=False)
     assert reviews_disabled.is_bugteam_disabled_via_env() is False
+
+
+def test_is_bugbot_disabled_via_env_returns_true_when_env_lists_bugbot(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "bugbot")
+    assert reviews_disabled.is_bugbot_disabled_via_env() is True
+
+
+def test_is_bugbot_disabled_via_env_returns_false_when_env_is_empty(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("CLAUDE_REVIEWS_DISABLED", raising=False)
+    assert reviews_disabled.is_bugbot_disabled_via_env() is False
+
+
+def test_is_bugbot_disabled_via_env_returns_false_when_only_bugteam_listed(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "bugteam")
+    assert reviews_disabled.is_bugbot_disabled_via_env() is False
+
+
+def test_is_bugbot_disabled_via_env_true_when_both_tokens_listed_mixed_case(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", " BugTeam , BUGBOT ")
+    assert reviews_disabled.is_bugbot_disabled_via_env() is True
+    assert reviews_disabled.is_bugteam_disabled_via_env() is True
+
+
+def test_cli_main_returns_zero_when_named_reviewer_disabled(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "bugbot")
+    assert reviews_disabled.main(["--reviewer", "bugbot"]) == 0
+
+
+def test_cli_main_returns_one_when_named_reviewer_not_disabled(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("CLAUDE_REVIEWS_DISABLED", raising=False)
+    assert reviews_disabled.main(["--reviewer", "bugbot"]) == 1
+
+
+def test_cli_main_returns_one_when_other_reviewer_disabled(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "bugteam")
+    assert reviews_disabled.main(["--reviewer", "bugbot"]) == 1
+
+
+def test_cli_main_supports_bugteam_reviewer(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "bugteam")
+    assert reviews_disabled.main(["--reviewer", "bugteam"]) == 0

package/hooks/blocking/content_search_zoekt_redirect_guidance.py

@@ -7,12 +7,31 @@ def get_zoekt_redirect_reason_brief() -> str:
     )
 
 
+def worktree_path_filter_fragment() -> str:
+    return "\\.claude/worktrees/"
+
+
+def worktree_path_display_fragment() -> str:
+    return ".claude/worktrees/"
+
+
 def get_zoekt_redirect_guidance() -> str:
+    worktree_filter_fragment = worktree_path_filter_fragment()
+    worktree_display_fragment = worktree_path_display_fragment()
     return (
         "Use Zoekt MCP instead: mcp__zoekt__search(query=\"your pattern\"). "
         "Supports regex, 'file:pattern' for file filtering, 'lang:py' for language. "
         "Also available: mcp__zoekt__search_symbols, mcp__zoekt__find_references, mcp__zoekt__file_content. "
         "Example: mcp__zoekt__search(query=\"verify_theme_assets file:\\.py$\")\n\n"
+        "WORKTREE NOISE: indexed trees include git worktrees under "
+        + worktree_display_fragment
+        + " that duplicate the same code across branches. By default append '-file:"
+        + worktree_filter_fragment
+        + "' to each query so results stay on the primary checkout. When the user explicitly "
+        "asks about a worktree, branch, or PR checkout, drop that exclusion or filter to it "
+        "positively, e.g. mcp__zoekt__search(query=\"your pattern file:"
+        + worktree_filter_fragment
+        + "<branch>/\").\n\n"
         "INDEX ROOTS (when Grep/Search in a tree is redirected): set ZOEKT_REDIRECT_INDEXED_ROOTS to a JSON array "
         "of absolute paths, or ~/.claude/zoekt-indexed-roots.json as {\"roots\": [\"/abs/path/to/repo/\", ...]}. "
         "Optional ZOEKT_REDIRECT_INDEXED_ROOTS_FILE points to a different JSON file. "

package/hooks/blocking/test_content_search_to_zoekt_redirector_unit.py

@@ -14,6 +14,8 @@ from content_search_zoekt_block_payload import build_block_payload
 from content_search_zoekt_redirect_guidance import (
     get_zoekt_redirect_guidance,
     get_zoekt_redirect_reason_brief,
+    worktree_path_display_fragment,
+    worktree_path_filter_fragment,
 )
 
 
@@ -52,5 +54,33 @@ class BuildBlockPayloadTests(unittest.TestCase):
         )
 
 
+class RedirectGuidanceWorktreeTests(unittest.TestCase):
+    def test_guidance_defaults_to_excluding_worktrees(self) -> None:
+        guidance = get_zoekt_redirect_guidance()
+        expected_default_exclusion = f"-file:{worktree_path_filter_fragment()}"
+        self.assertIn(expected_default_exclusion, guidance)
+
+    def test_guidance_explains_how_to_search_a_worktree(self) -> None:
+        guidance = get_zoekt_redirect_guidance()
+        positive_filter_example = (
+            f'query="your pattern file:{worktree_path_filter_fragment()}<branch>/'
+        )
+        self.assertIn(positive_filter_example, guidance)
+        self.assertIn("worktree", guidance.lower())
+
+    def test_worktree_filter_fragment_is_a_regex_escaped_path(self) -> None:
+        self.assertEqual(worktree_path_filter_fragment(), "\\.claude/worktrees/")
+
+    def test_guidance_describes_worktree_path_unescaped_in_prose(self) -> None:
+        guidance = get_zoekt_redirect_guidance()
+        prose_substring = (
+            f"git worktrees under {worktree_path_display_fragment()} that"
+        )
+        self.assertIn(prose_substring, guidance)
+
+    def test_worktree_display_fragment_is_the_unescaped_path(self) -> None:
+        self.assertEqual(worktree_path_display_fragment(), ".claude/worktrees/")
+
+
 if __name__ == "__main__":
     unittest.main()

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.45.0",
+    "version": "1.46.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/skills/bugteam/scripts/test_bugteam_code_rules_gate.py

@@ -33,6 +33,11 @@ def initialize_git_repository(repository_root: Path) -> None:
     run_git_in_repository(repository_root, "config", "user.email", "test@example.com")
     run_git_in_repository(repository_root, "config", "user.name", "Test")
     run_git_in_repository(repository_root, "config", "commit.gpgsign", "false")
+    disabled_hooks_directory = repository_root / "disabled-git-hooks"
+    disabled_hooks_directory.mkdir()
+    run_git_in_repository(
+        repository_root, "config", "core.hooksPath", str(disabled_hooks_directory)
+    )
 
 
 def commit_all_files(repository_root: Path, commit_message: str) -> None:

package/skills/pr-converge/SKILL.md

@@ -125,6 +125,11 @@ no longer applies.
 - [ ] **Step 4: BUGBOT — fetch, decide, fix, reply, resolve**
       See: [`reference/per-tick.md` § Step 2 BUGBOT + Step 3](reference/per-tick.md)
 
+      - [ ] **Opt-out gate (runs first, every BUGBOT entry).**
+            `python "$HOME/.claude/_shared/pr-loop/scripts/reviews_disabled.py" --reviewer bugbot`
+            - [ ] Exit 0 (`CLAUDE_REVIEWS_DISABLED` lists `bugbot`) → set `bugbot_down = true`, `phase = BUGTEAM`, advance to Step 5 (bypass). Cursor Bugbot is skipped for the entire run.
+            - [ ] Exit 1 → continue below.
+
       Fetch bugbot reviews + inline comments on `current_head`.
 
       - [ ] **dirty** (findings on `current_head`) →

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

@@ -49,6 +49,16 @@ Capture `number`, `head.sha` (= `current_head`), owner/repo, branch.
 
 ### `phase == BUGBOT`
 
+**Opt-out gate (runs first, before any fetch or trigger).**
+`python "$HOME/.claude/_shared/pr-loop/scripts/reviews_disabled.py" --reviewer bugbot`
+
+- Exit 0 (`CLAUDE_REVIEWS_DISABLED` lists `bugbot`) → set `bugbot_down = true`,
+  `phase = BUGTEAM`, continue BUGTEAM in the same tick; skip steps a–c below.
+- Exit 1 → proceed to step a.
+
+Because `bugbot_down` resets on every push, this gate re-runs on every
+BUGBOT entry and keeps Cursor Bugbot skipped for the entire run.
+
 a. Fetch Cursor Bugbot reviews newest-first, walk back until first clean:
 
    ```
@@ -207,11 +217,10 @@ BUGBOT.
 
 ## Step 3: Re-trigger bugbot
 
-- [ ] **Opt-out gate.** When `CLAUDE_REVIEWS_DISABLED` (comma-separated,
-  case-insensitive, whitespace-tolerant) contains `bugbot`, set
-  `bugbot_down = true`, skip every check below, set `phase = BUGTEAM`,
-  and continue BUGTEAM in the same tick. The downstream loop branches on
-  `bugbot_down` exactly the way it does when bugbot CI is unavailable.
+- [ ] **Opt-out gate.** Enforced at BUGBOT entry (see `### phase == BUGBOT`).
+  When `CLAUDE_REVIEWS_DISABLED` lists `bugbot`, the entry gate sets
+  `bugbot_down = true` and routes to BUGTEAM before any trigger flow runs,
+  so the checks below are skipped.
 - [ ] **Silent-pass pre-check.** Run `python ~/.claude/skills/pr-converge/scripts/check_bugbot_ci.py --check-clean --owner <O> --repo <R> --sha <current_head>`
 - [ ] Exit 0 → bugbot CI completed clean with no review (silent pass); set `bugbot_clean_at = current_head`, `phase = BUGTEAM`, continue BUGTEAM same tick
 - [ ] Exit 1 (not a silent pass) or Exit 2 (gh CLI error — silent pass not confirmable) → continue with the trigger flow below

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

@@ -23,9 +23,13 @@ live ONLY in the single-PR `$CLAUDE_JOB_DIR/pr-converge-state.json` file
   matching. Reset to `0` on any other branch outcome.
 - `bugbot_down`: boolean, init `false`. Set `true` when bugbot fails to
   acknowledge a trigger comment; forces phase to BUGTEAM. Also set `true`
-  when an acknowledged trigger has been outstanding more than 30 minutes
-  with no surfaced review at `current_head` (per Step 2 BUGBOT (c)
-  30-minute budget — see `per-tick.md`). Reset to `false` on every push.
+  at every BUGBOT-phase entry when `CLAUDE_REVIEWS_DISABLED` lists the
+  `bugbot` token (env opt-out via the BUGBOT entry gate in `per-tick.md`),
+  which routes straight to BUGTEAM before any bugbot fetch or trigger. Also
+  set `true` when an acknowledged trigger has been outstanding more than 30
+  minutes with no surfaced review at `current_head` (per Step 2 BUGBOT (c)
+  30-minute budget — see `per-tick.md`). Reset to `false` on every push;
+  the entry gate re-applies the env opt-out on the next BUGBOT entry.
   Once set, remains `true` until the next push; if bugbot stays down
   across ticks, the flag persists and BUGTEAM continues.
 - `bugbot_acknowledged_at`: ISO 8601 timestamp string or `null`. Records

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

@@ -4,6 +4,10 @@ Usage:
   python scripts/check_convergence.py --owner <O> --repo <R> --pr-number <N>
                                       [--bugbot-down]
 
+The bugbot check-run gate is bypassed when either ``--bugbot-down`` is
+passed OR the ``CLAUDE_REVIEWS_DISABLED`` environment variable lists the
+``bugbot`` token, so a Bugbot opt-out closes the gate without the flag.
+
 Exit codes:
   0 — all pre-conditions met
   1 — one or more conditions not met (FAIL lines printed to stdout)
@@ -48,6 +52,14 @@ from pr_converge_skill_constants.constants import (
     UNRESOLVED_THREAD_DETAIL_MAX,
 )
 
+_shared_pr_loop_scripts_dir = (
+    Path(__file__).absolute().parents[3] / "_shared" / "pr-loop" / "scripts"
+)
+if str(_shared_pr_loop_scripts_dir) not in sys.path:
+    sys.path.insert(0, str(_shared_pr_loop_scripts_dir))
+
+from reviews_disabled import is_bugbot_disabled_via_env
+
 
 def _is_bugteam_review(review_body: str) -> bool:
     """Return True when a review body opens with a bugteam audit header.
@@ -621,6 +633,20 @@ def parse_arguments(all_argv: list[str]) -> argparse.Namespace:
     return parser.parse_args(all_argv)
 
 
+def _resolve_bugbot_down(bugbot_down_flag: bool) -> bool:
+    """Combine the explicit flag with the CLAUDE_REVIEWS_DISABLED env opt-out.
+
+    Args:
+        bugbot_down_flag: Value of the ``--bugbot-down`` CLI flag.
+
+    Returns:
+        True when the flag is set OR ``CLAUDE_REVIEWS_DISABLED`` lists the
+        ``bugbot`` token, so the env opt-out bypasses the bugbot gates even
+        when the caller omits the flag.
+    """
+    return bugbot_down_flag or is_bugbot_disabled_via_env()
+
+
 def main(all_arguments: list[str]) -> int:
     """Run the script end-to-end against parsed CLI arguments.
 
@@ -635,7 +661,7 @@ def main(all_arguments: list[str]) -> int:
         owner=arguments.owner,
         repo=arguments.repo,
         number=getattr(arguments, "pr_number"),
-        bugbot_down=arguments.bugbot_down,
+        bugbot_down=_resolve_bugbot_down(arguments.bugbot_down),
     )
 
 

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

@@ -217,6 +217,34 @@ def test_private_helpers_recognize_dirty_legacy_header_body() -> None:
     assert check_convergence._is_clean_bugteam_review(DIRTY_LEGACY_BUGTEAM_BODY) is False
 
 
+def should_resolve_bugbot_down_true_when_flag_set(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("CLAUDE_REVIEWS_DISABLED", raising=False)
+    assert check_convergence._resolve_bugbot_down(True) is True
+
+
+def should_resolve_bugbot_down_true_when_env_disables_bugbot(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "bugbot")
+    assert check_convergence._resolve_bugbot_down(False) is True
+
+
+def should_resolve_bugbot_down_false_when_flag_unset_and_env_empty(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("CLAUDE_REVIEWS_DISABLED", raising=False)
+    assert check_convergence._resolve_bugbot_down(False) is False
+
+
+def should_resolve_bugbot_down_false_when_env_disables_only_bugteam(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "bugteam")
+    assert check_convergence._resolve_bugbot_down(False) is False
+
+
 def should_bypass_bugbot_gates_when_bugbot_down_is_true(
     monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
 ) -> None: