claude-dev-env 1.45.0 → 1.47.0

package/CLAUDE.md

@@ -1,5 +1,9 @@
 # Claude Development Assistant
 
+The user is short on time and tokens. When you reply, always assume they'll only read your first few sentences and final sentences. Anything else is skimmed at best. Frame your replies accordingly.
+
+The user is short on tokens; whenever a task can be achieved cleanly and effectively, optimize to save the user $$ and token usage.
+
 The user delegates execution to you and expects zero manual steps unless strictly necessary. Execute every command you can directly. Only instruct the user to do something manually when you are technically unable to do it yourself. When a task involves credentials or other sensitive input, display a minimal secure UI (e.g., a password dialog) to collect it rather than asking the user to paste it into chat or run the command themselves. When direction is ambiguous, use AskUserQuestion to clarify before acting.
 
 ## Code Rules
@@ -18,7 +22,10 @@ Full banned-pattern set + enforcement: `~/.claude/rules/no-historical-clutter.md
 
 ## GOTCHAS
 When making code changes, make sure you are working in the proper worktree path for the task at hand.
-When writing to an existing file, you must either EDIT the file, or remove it and THEN re-write it if it's truly a full re-write.
+
+## Choosing Edit vs Write
+
+`Edit` changes existing files; `Write` creates new ones. Default to `Edit` — reach for `Write` only for a genuinely new path. For a true full rewrite, delete the file first, then `Write`.
 
 ## File-Global Constants
 

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,39 @@ 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 FRESHNESS: the index trails just-written code — recent or unpushed commits sync and reindex "
+        "on a short delay, so a symbol you just added can be missing from Zoekt for a few minutes even though "
+        "it is on disk. Worktrees are fully indexed and retrievable with the positive 'file:"
+        + worktree_filter_fragment
+        + "<branch>/' filter above, but that same lag applies to anything freshly edited. When a Zoekt search "
+        "returns nothing for code you know exists on disk, do not treat it as absent: Grep a specific file "
+        "(a path ending in a file extension is exempt from this redirect) or read the file directly to confirm "
+        "current contents.\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,39 @@ 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/")
+
+    def test_guidance_documents_index_freshness_escape_hatch(self) -> None:
+        guidance = get_zoekt_redirect_guidance()
+        self.assertIn("INDEX FRESHNESS:", guidance)
+        self.assertIn("exempt from this redirect", guidance)
+        self.assertIn("read the file directly", guidance)
+
+
 if __name__ == "__main__":
     unittest.main()

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.45.0",
+    "version": "1.47.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:

package/skills/pre-compact/SKILL.md

@@ -5,8 +5,10 @@ description: >-
   `/compact <directive>` string to the operator's clipboard so the next prompt
   is a single paste. The directive pins the session's load-bearing identifiers
   (branch, PR, HEAD, worktree, in-flight work, decisions, blockers, files in
-  play, follow-ups) and lists the redundant tool outputs the summarizer should
-  drop. Use when the user says `/pre-compact`, asks to prep for compaction, or
+  play, follow-ups) the next steps depend on, so the summarizer keeps them with
+  high fidelity. It confirms the operator's intent for the next chat through a
+  structured question first, then validates each identifier against its live
+  source before stating it. Use when the user says `/pre-compact`, asks to prep for compaction, or
   asks to compose a focus directive for `/compact`.
 disable-model-invocation: true
 ---
@@ -20,16 +22,35 @@ string to the operator's clipboard.
 
 **Announce at start:** "I'm composing your compact focus directive."
 
-## Step 1 — Read the live session
-
-Pull the load-bearing identifiers from the current conversation. Run
-`git status`, `git rev-parse --short HEAD`, or `gh pr view` when values are
-not already in context.
+## Step 1 — Confirm the next-session intent
+
+Before composing anything, ask the operator what they intend to work on in
+the next chat. Do not infer it silently from the conversation, and do not
+ask it raw — use `AskUserQuestion` with two to four options drawn from the
+session context (the threads left open, the obvious next actions, the task
+the operator last steered toward); the tool's free-text fallback covers
+anything unlisted. The selected intent is the directive's forward task:
+Step 2 scopes every field to what that intent needs, and the rendered
+`In-flight` line states it.
+
+## Step 2 — Read and validate the live session
+
+Validate every identifier directly before stating it. Conversation context
+goes stale within a session — a PR merges, HEAD advances, a worktree
+advances to a newer commit — so confirm each value against its live source
+at compose time rather than carrying it from memory. Run the command in
+each field's Source column; for a PR, capture its merge state
+(`gh pr view --json state,mergedAt`) and state `merged` or `open` from that
+result, never from recollection. A value that cannot be confirmed against a
+live source is not dropped silently — surface it to the operator via
+`AskUserQuestion` to clarify (offer the candidate values found plus the
+free-text fallback) and use the answer. Omit it only when the operator
+chooses to skip it.
 
 | Field | What to capture | Source |
 |---|---|---|
 | `branch` | Active branch name | `git branch --show-current` |
-| `pr` | Active PR number, when one exists | `gh pr view --json number` |
+| `pr` | Active PR number and its merge state (open / merged), when one exists | `gh pr view --json number,state,mergedAt` |
 | `head` | Short HEAD SHA (whatever `git rev-parse --short` outputs) | `git rev-parse --short HEAD` |
 | `worktree` | Absolute path to the working directory | `pwd` |
 | `in_flight` | One sentence describing what is being worked on right now | conversation |
@@ -41,7 +62,15 @@ not already in context.
 A field whose value cannot be stated as a concrete identifier is omitted
 from the directive.
 
-## Step 2 — Render the directive
+Scope every field to what the Step 1 intent needs next. Compaction carries
+forward the slice of session history the remaining work needs: capture a
+`decision`, `blocker`, or `in_flight` detail when a next step relies on
+it, and leave a detail the next steps do not touch (a settled question, a
+resolved blocker, a path not taken) out by simply not listing it. When a
+settled decision still constrains the next step, list its outcome as one
+line, not the deliberation behind it.
+
+## Step 3 — Render the directive
 
 Render this exact shape, populating only the fields with concrete values:
 
@@ -56,25 +85,21 @@ Preserve:
 - Blockers: <bullet per blocker>
 - Files: <path>, <path>, <path>
 - Follow-ups: <bullet per follow-up>
-
-Drop:
-- Tool outputs already applied to files
-- Per-tick progress narration
-- Resolved findings and superseded SHAs
-- Listing/grep output whose conclusion appears above
 ```
 
-The `Preserve:` block leads so the summarizer maximizes recall first. The
-`Drop:` block lists the lightest-touch removals — raw tool outputs are the
-safest content to drop because the work they produced lives in the files
-and commits.
+The directive lists only what the next steps consume, so the summarizer
+preserves that with high fidelity and compresses the rest of the trace on
+its own — naming what to keep is a clearer instruction than enumerating
+what to cut. Keep the list tight: a `Preserve:` block padded with finished
+or out-of-scope context dilutes the summarizer's focus on what happens
+next.
 
 Source: [Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)
 — "start by maximizing recall to ensure your compaction prompt captures
 every relevant piece of information from the trace, then iterate to improve
 precision by eliminating superfluous content."
 
-## Step 3 — Copy `/compact <directive>` to the clipboard
+## Step 4 — Copy `/compact <directive>` to the clipboard
 
 Write the full `/compact <directive>` string to a temporary file via the
 Write tool, then copy the file contents to the clipboard with PowerShell:
@@ -91,7 +116,7 @@ unmodified regardless of which characters it contains.
 A reasonable temp path under `$env:TEMP` (Windows) or `$TMPDIR` (POSIX)
 works; clean it up after the `Set-Clipboard` call returns.
 
-## Step 4 — Hand off
+## Step 5 — Hand off
 
 Print this confirmation line to the operator:
 
@@ -99,8 +124,8 @@ Print this confirmation line to the operator:
 > compact this conversation with focus.
 
 Then list up to the first three `Preserve:` bullets (or fewer when the
-directive omits fields) and the first `Drop:` bullet inline so the
-operator can spot-check before pasting.
+directive omits fields) inline so the operator can spot-check before
+pasting.
 
 ---