claude-dev-env 1.92.1 → 1.93.1

package/_shared/pr-loop/precatch-rubric.md

@@ -0,0 +1,65 @@
+# Pre-catch lens checklist
+
+The shared checklist the internal pre-catch lenses read on demand. 
+
+## Lane 1 — Deterministic sweep
+
+The mechanical, static, and test classes belong to a deterministic run. The static-sweep 
+step owns them: it runs the CODE_RULES gate (`code_rules_gate.py --base origin/main`), 
+`ruff`, `mypy`, and stem-matched `pytest` over the changed files. A reading lens trusts the 
+sweep to have cleared them and reviews sweep-clean code.
+
+- Every CODE_RULES violation the gate reports is a finding.
+- Every `ruff` and `mypy` diagnostic on a changed file is a finding.
+- Every failing test in a changed production module's paired test is a finding.
+- **Proof of absence:** the gate exits 0, `ruff` and `mypy` report no diagnostic
+  on the changed files, and the stem-matched tests pass.
+
+## Lane 2 — Doc-vs-code parity
+
+Every doc claim in the diff matches the code it describes. Reuse the
+`pr-consistency-audit` skill's canonical-source cross-reference method
+(`~/.claude/skills/pr-consistency-audit/SKILL.md`, canonical source first) and the
+drift rubric at
+`~/.claude/audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md`.
+
+- Every line citation resolves to the line it names.
+- Every referenced file or script path exists.
+- Every symbol is attributed to the file that defines it.
+- Every inventory table, env-var table, count claim, and ordering claim matches
+  the code.
+- **Proof of absence:** each referenced path, citation, symbol, and table checked
+  against its source and found in step.
+
+## Lane 3 — Test-assertion completeness
+
+Every changed or new production path carries a test that exercises its behavior.
+
+- Every changed or new production path has a paired test that calls it and asserts
+  on its return value or side effect.
+- A changed test pins the behavior it covers rather than hiding it behind a mock.
+- **Proof of absence:** each changed production path paired with a behavior test
+  that fails when the path regresses.
+
+## Lane 4 — PR-description-vs-diff two-way parity
+
+The PR body and the diff describe the same change, both directions.
+
+- Every claim in the PR body maps to a hunk in the diff.
+- Every hunk in the diff maps to a claim in the PR body.
+- Flag any invented path, invented count, or out-of-scope change.
+- **Proof of absence:** the two-way map complete — every claim has a hunk and
+  every hunk has a claim.
+
+## Lane 5 — Adversarial audit
+
+The bug-audit lens runs the adversarial second pass the audit contract specifies
+(`~/.claude/_shared/pr-loop/audit-contract.md`): assume the first A-P pass missed
+at least three P1 bugs, then find them.
+
+- Return new file:line findings for the bugs the first pass missed.
+- Or return a per-category proof-of-absence entry naming each re-examined category
+  and why it holds.
+- A bare "nothing new" is not an acceptable result for this pass.
+- **Proof of absence:** a per-category adversarial-probe entry for each re-examined
+  A-P category with no new finding.

package/_shared/pr-loop/scripts/CLAUDE.md

@@ -13,7 +13,7 @@ Python scripts invoked at runtime by the PR-loop skills. Each script is a standa
 | `revoke_project_claude_permissions.py` | Removes the allow-rules and entries that `grant_project_claude_permissions.py` wrote; safe to run when no prior grant exists |
 | `code_rules_gate.py` | Pre-commit gate that runs `code_rules_enforcer` checks on staged Python files before a fix commit lands, and the terminology sweep over the staged diff |
 | `terminology_sweep.py` | Flags a prose term that near-misses an identifier introduced on added code lines of a unified diff (shared leading word, divergent tail) |
-| `reviews_disabled.py` | Shared helper for the `CLAUDE_REVIEWS_DISABLED` opt-out gate; parses the env-var token to find which reviewer types are suppressed |
+| `reviews_disabled.py` | Shared helper for the reviewer opt-out and opt-in gates; parses `CLAUDE_REVIEWS_DISABLED` and `CLAUDE_REVIEWS_ENABLED` tokens to decide which reviewers run (bugbot is off by default and runs only when `CLAUDE_REVIEWS_ENABLED` lists it) |
 | `copilot_quota.py` | Copilot premium-request quota pre-check: resolves a configured GitHub account, reads its remaining `premium_interactions` quota via `gh api copilot_internal/user`, and exits 0 (run Copilot) or non-zero (skip: out of quota, API down, or no account configured) |
 | `reviewer_availability.py` | Unified reviewer-availability entry point for Copilot and Bugbot: reuses `copilot_quota.py` and `reviews_disabled.py` and exits 0 when the named `--reviewer` may be spawned, non-zero when it is opted out or (for Copilot) out of quota |
 | `fix_hookspath.py` | Repairs a malformed `core.hooksPath` global git config entry |

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

@@ -1,6 +1,7 @@
 import argparse
 import ast
 import importlib.util
+import os
 import re
 import subprocess
 import sys
@@ -15,13 +16,19 @@ from pr_loop_shared_constants.code_rules_gate_constants import (  # noqa: E402
     ALL_CODE_FILE_EXTENSIONS,
     ALL_GIT_DIFF_CACHED_NAME_ONLY_NULL_TERMINATED_COMMAND,
     ALL_GIT_DIFF_NAME_ONLY_NULL_TERMINATED_COMMAND_PREFIX,
+    ALL_POSIX_VENV_PYTHON_RELATIVE_PATH_SEGMENTS,
     ALL_PYTEST_CONFIG_FILE_SECTIONS,
     ALL_PYTEST_MODULE_INVOCATION,
     ALL_TEST_FILENAME_GLOB_SUFFIXES,
     ALL_TEST_FILENAME_SUFFIXES,
+    ALL_VENV_DIRECTORY_NAMES,
+    ALL_WINDOWS_VENV_PYTHON_RELATIVE_PATH_SEGMENTS,
     BANNED_NOUN_DEFINITION_LINE_GROUP_INDEX,
     BANNED_NOUN_SPAN_GROUP_INDEX,
     BANNED_NOUN_VIOLATION_PATTERN,
+    CODE_RULES_GATE_PYTHON_ENV_VAR,
+    CODE_RULES_GATE_PYTHONPATH_ENV_VAR,
+    COMMAND_LINE_ARGUMENT_SEPARATOR_LENGTH,
     DUPLICATE_BODY_DEFINITION_LINE_GROUP_INDEX,
     DUPLICATE_BODY_SPAN_GROUP_INDEX,
     DUPLICATE_BODY_VIOLATION_PATTERN,
@@ -35,8 +42,12 @@ from pr_loop_shared_constants.code_rules_gate_constants import (  # noqa: E402
     ISOLATION_DEFINITION_LINE_GROUP_INDEX,
     ISOLATION_SPAN_GROUP_INDEX,
     ISOLATION_VIOLATION_PATTERN,
+    MAXIMUM_STAGED_PYTEST_COMMAND_LINE_CHARACTERS,
     MAX_VIOLATIONS_PER_CHECK,
+    MINIMUM_STAGED_PYTEST_PYTHON_MAJOR,
+    MINIMUM_STAGED_PYTEST_PYTHON_MINOR,
     PYTHON_FILE_EXTENSION,
+    PYTHONPATH_ENV_VAR,
     STAGED_PYTEST_TIMEOUT_SECONDS,
     STAGED_TEST_FAILURE_HEADER,
     STAGED_TEST_GROUP_FAILURE_MESSAGE,
@@ -1620,33 +1631,230 @@ def _group_staged_tests_by_root(
     return tests_by_root
 
 
-def _run_pytest_for_group(group_root: Path, all_group_test_paths: list[Path]) -> int:
-    """Run pytest over one group's test files with the working directory at its root.
+def _venv_python_relative_path() -> tuple[str, ...]:
+    """Return the venv-relative python executable path segments for this platform.
+
+    Returns:
+        The Windows ``Scripts/python.exe`` segments on Windows, the POSIX
+        ``bin/python`` segments on every other platform.
+    """
+    if os.name == "nt":
+        return ALL_WINDOWS_VENV_PYTHON_RELATIVE_PATH_SEGMENTS
+    return ALL_POSIX_VENV_PYTHON_RELATIVE_PATH_SEGMENTS
+
+
+def _venv_python_executable(repository_root: Path) -> Path | None:
+    """Return the first existing venv interpreter under *repository_root*.
+
+    Checks each directory name in ``ALL_VENV_DIRECTORY_NAMES`` in order and
+    returns the platform-specific interpreter path the first time it exists
+    on disk.
 
     Args:
-        group_root: The owning test root used as the pytest working directory.
-        all_group_test_paths: The staged test files that share *group_root*.
+        repository_root: The repository root to search for a venv directory.
+
+    Returns:
+        The resolved interpreter path, or None when no candidate exists.
+    """
+    relative_python_path = _venv_python_relative_path()
+    for each_venv_directory_name in ALL_VENV_DIRECTORY_NAMES:
+        candidate_path = repository_root.joinpath(
+            each_venv_directory_name, *relative_python_path
+        )
+        if candidate_path.is_file():
+            return candidate_path
+    return None
+
+
+def _resolve_gate_python_executable(repository_root: Path) -> str:
+    """Return the interpreter the staged-test subprocess runs under.
+
+    Resolves in order: the ``CODE_RULES_GATE_PYTHON`` environment variable
+    when set, then the first existing project venv interpreter under
+    *repository_root*, then the interpreter running the gate itself.
+
+    Args:
+        repository_root: The repository root used to locate a project venv.
+
+    Returns:
+        The absolute path (or command name) of the interpreter to invoke.
+    """
+    configured_python = os.environ.get(CODE_RULES_GATE_PYTHON_ENV_VAR)
+    if configured_python:
+        return configured_python
+    venv_python = _venv_python_executable(repository_root)
+    if venv_python is not None:
+        return str(venv_python)
+    return sys.executable
+
+
+def _staged_pytest_environment() -> dict[str, str]:
+    """Return the subprocess environment for the staged-test pytest run.
+
+    Starts from ``repository_environment()`` (the GIT_-scrubbed process
+    environment) and, when ``CODE_RULES_GATE_PYTHONPATH`` is set, prepends
+    its value to ``PYTHONPATH`` so a resolved venv interpreter that lacks the
+    project on its default path can still import it.
+
+    Returns:
+        The environment mapping to pass to the staged-test subprocess.
+    """
+    environment = repository_environment()
+    configured_pythonpath = os.environ.get(CODE_RULES_GATE_PYTHONPATH_ENV_VAR)
+    if not configured_pythonpath:
+        return environment
+    existing_pythonpath = environment.get(PYTHONPATH_ENV_VAR, "")
+    environment[PYTHONPATH_ENV_VAR] = (
+        configured_pythonpath
+        if not existing_pythonpath
+        else os.pathsep.join([configured_pythonpath, existing_pythonpath])
+    )
+    return environment
+
+
+def _relative_pytest_argument(test_path: Path, group_root: Path) -> str:
+    """Express *test_path* as a pytest argument relative to *group_root*.
+
+    *group_root* is already the pytest working directory, so the relative form
+    names the same file in far fewer characters.
+
+    Example::
+
+        group_root = C:/repo/package
+        ok:   C:/repo/package/tests/test_a.py -> "tests/test_a.py"
+        flag: C:/elsewhere/test_b.py         -> no relative form; passed absolute
+
+    Args:
+        test_path: The staged test file to express as a pytest argument.
+        group_root: The pytest working directory for the group.
+
+    Returns:
+        The path relative to *group_root* when *test_path* sits under it,
+        otherwise the absolute path unchanged.
+    """
+    try:
+        return str(test_path.relative_to(group_root))
+    except ValueError:
+        return str(test_path)
+
+
+def _batched_pytest_arguments(
+    all_pytest_arguments: list[str], character_budget: int
+) -> list[list[str]]:
+    """Split pytest path arguments into command-line-length-safe batches.
+
+    Windows rejects a command line past 32767 characters with WinError 206, so a
+    large staged set passed in one invocation crashes the gate and denies the
+    commit. Each batch takes arguments until the next one would push its joined
+    length past *character_budget*.
+
+    Example::
+
+        character_budget = 10
+        arguments        = ["aaaa", "bbbb", "cccc"]
+        ok:   [["aaaa", "bbbb"], ["cccc"]]  - every batch within budget
+        flag: [["aaaa", "bbbb", "cccc"]]    - 14 characters, over budget
+
+    Args:
+        all_pytest_arguments: The path arguments to distribute, in order.
+        character_budget: The joined length each batch must stay within. An
+            argument wider than the budget on its own still lands in a batch
+            by itself, so no argument is ever dropped.
 
     Returns:
-        0 when the group's tests pass or collect nothing; pytest's non-zero
-        exit code otherwise.
+        One argument list per pytest invocation, preserving input order.
+    """
+    all_batches: list[list[str]] = []
+    current_batch: list[str] = []
+    current_length = 0
+    for each_argument in all_pytest_arguments:
+        argument_length = len(each_argument) + COMMAND_LINE_ARGUMENT_SEPARATOR_LENGTH
+        if current_batch and current_length + argument_length > character_budget:
+            all_batches.append(current_batch)
+            current_batch = []
+            current_length = 0
+        current_batch.append(each_argument)
+        current_length += argument_length
+    if current_batch:
+        all_batches.append(current_batch)
+    return all_batches
+
+
+def _pytest_batch_exit_code(all_batch_command: list[str], group_root: Path) -> int:
+    """Run one pytest invocation and normalize its exit code.
+
+    Args:
+        all_batch_command: The full argv for this pytest invocation.
+        group_root: The owning test root used as the working directory.
+
+    Returns:
+        0 when the batch passes or collects no tests; pytest's non-zero exit
+        code otherwise.
     """
     pytest_process = subprocess.run(
-        [
-            sys.executable,
-            *ALL_PYTEST_MODULE_INVOCATION,
-            *[str(each_path) for each_path in all_group_test_paths],
-        ],
+        all_batch_command,
         cwd=str(group_root),
         timeout=STAGED_PYTEST_TIMEOUT_SECONDS,
         check=False,
-        env=repository_environment(),
+        env=_staged_pytest_environment(),
     )
     if pytest_process.returncode == PYTEST_NO_TESTS_COLLECTED_EXIT_CODE:
         return 0
     return pytest_process.returncode
 
 
+def _run_pytest_for_group(
+    group_root: Path, all_group_test_paths: list[Path], repository_root: Path
+) -> int:
+    """Run pytest over one group's test files with the working directory at its root.
+
+    Paths are passed relative to *group_root* (the subprocess working directory)
+    and split into batches whose joined command line stays within
+    ``MAXIMUM_STAGED_PYTEST_COMMAND_LINE_CHARACTERS``, so a large staged set never
+    trips the Windows 32767-character limit. A staged set that fits the budget runs
+    as one invocation, exactly as an unbatched run did.
+
+    Example::
+
+        ok:   3 staged tests   -> 1 pytest invocation, argv well under the budget
+        flag: 800 staged tests -> 1 pytest invocation, argv over the Windows limit
+                                  (WinError 206); batching splits it across several
+
+    Args:
+        group_root: The owning test root used as the pytest working directory.
+        all_group_test_paths: The staged test files that share *group_root*.
+        repository_root: The repository root used to resolve a project venv
+            interpreter when ``CODE_RULES_GATE_PYTHON`` is not set.
+
+    Returns:
+        0 when every batch passes or collects nothing; the first failing batch's
+        non-zero pytest exit code otherwise.
+    """
+    all_fixed_command = [
+        _resolve_gate_python_executable(repository_root),
+        *ALL_PYTEST_MODULE_INVOCATION,
+    ]
+    fixed_command_length = sum(
+        len(each_part) + COMMAND_LINE_ARGUMENT_SEPARATOR_LENGTH
+        for each_part in all_fixed_command
+    )
+    all_batches = _batched_pytest_arguments(
+        [
+            _relative_pytest_argument(each_path, group_root)
+            for each_path in all_group_test_paths
+        ],
+        MAXIMUM_STAGED_PYTEST_COMMAND_LINE_CHARACTERS - fixed_command_length,
+    )
+    first_failing_exit_code = 0
+    for each_batch in all_batches:
+        batch_exit_code = _pytest_batch_exit_code(
+            [*all_fixed_command, *each_batch], group_root
+        )
+        if batch_exit_code != 0 and first_failing_exit_code == 0:
+            first_failing_exit_code = batch_exit_code
+    return first_failing_exit_code
+
+
 def run_staged_test_files(repository_root: Path) -> int:
     """Run pytest over the staged test files and return the gate exit code.
 
@@ -1670,7 +1878,7 @@ def run_staged_test_files(repository_root: Path) -> int:
     first_failing_exit_code = 0
     for each_group_root in sorted(tests_by_root):
         group_exit_code = _run_pytest_for_group(
-            each_group_root, tests_by_root[each_group_root]
+            each_group_root, tests_by_root[each_group_root], repository_root
         )
         if group_exit_code != 0:
             print(
@@ -1684,6 +1892,42 @@ def run_staged_test_files(repository_root: Path) -> int:
     return first_failing_exit_code
 
 
+def _staged_pytest_exit_code_for_current_python(repository_root: Path) -> int:
+    """Run the staged test files, or skip them on a Python below the minimum.
+
+    ::
+
+        running (3, 11), minimum (3, 12)  ->  log a notice and return 0 (skipped)
+        running (3, 12), minimum (3, 12)  ->  run pytest over the staged tests
+
+    The staged tests call newer-Python APIs, so an older interpreter fails them
+    for the environment rather than for a code defect. On such a runtime this
+    step is skipped so the gap does not block the commit, while the terminology
+    and code-rules checks still run.
+
+    Args:
+        repository_root: The repository root whose staged test files run.
+
+    Returns:
+        0 when the running Python is below the staged-test minimum, otherwise the
+        exit code from running the staged test files.
+    """
+    running_version = (sys.version_info.major, sys.version_info.minor)
+    minimum_version = (
+        MINIMUM_STAGED_PYTEST_PYTHON_MAJOR,
+        MINIMUM_STAGED_PYTEST_PYTHON_MINOR,
+    )
+    if running_version < minimum_version:
+        print(
+            f"code_rules_gate: Python {running_version} is below the staged-test "
+            f"minimum {minimum_version}; skipping the staged "
+            "pytest step (environment gap, not a code failure).",
+            file=sys.stderr,
+        )
+        return 0
+    return run_staged_test_files(repository_root)
+
+
 def _report_terminology_findings(all_findings: list[str]) -> None:
     """Print the terminology-sweep findings, when any, to standard error.
 
@@ -1782,7 +2026,9 @@ def main(all_arguments: list[str]) -> int:
     if arguments.staged:
         all_terminology_findings = staged_terminology_findings(repository_root)
         _report_terminology_findings(all_terminology_findings)
-        staged_test_exit_code = run_staged_test_files(repository_root)
+        staged_test_exit_code = _staged_pytest_exit_code_for_current_python(
+            repository_root
+        )
         staged_file_paths = paths_from_git_staged(repository_root)
         staged_file_paths = filter_paths_under_prefixes(
             staged_file_paths,

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

@@ -223,7 +223,7 @@ def parse_command_line_arguments(all_arguments: list[str]) -> argparse.Namespace
     parser.add_argument(
         CLI_FLAG_REPO,
         required=True,
-        help="Repository name (e.g., claude-code-config).",
+        help="Repository name (e.g., claude-dev-env).",
     )
     parser.add_argument(
         CLI_FLAG_PR_NUMBER,

package/_shared/pr-loop/scripts/pr_loop_shared_constants/CLAUDE.md

@@ -14,7 +14,7 @@ Named constants for every script in `_shared/pr-loop/scripts/`. Each module owns
 | `post_audit_thread_constants.py` | `post_audit_thread.py` — HTTP status codes, retry counts, GitHub API paths |
 | `preflight_constants.py` | `preflight.py` — env-var names, git subcommands, pytest exit codes, test discovery patterns |
 | `preflight_self_heal_constants.py` | `preflight_self_heal.py` — git config keys and local-scope detection strings |
-| `reviews_disabled_constants.py` | `reviews_disabled.py` — `CLAUDE_REVIEWS_DISABLED` token taxonomy |
+| `reviews_disabled_constants.py` | `reviews_disabled.py` — `CLAUDE_REVIEWS_DISABLED` and `CLAUDE_REVIEWS_ENABLED` env-var names and token taxonomy |
 | `copilot_quota_constants.py` | `copilot_quota.py` — `COPILOT_QUOTA_ACCOUNT` env-var name, `copilot_internal/user` API path, the `premium_interactions` gating field names, the four skip/run exit codes, and the default `.env` path |
 | `terminology_sweep_constants.py` | `terminology_sweep.py` — identifier and prose-token regexes, diff-parsing prefixes, code-file extensions, test-file detection patterns, and the finding-message template |
 | `reviewer_availability_constants.py` | `reviewer_availability.py` — the available/down exit codes for the unified reviewer-availability pre-check |

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

@@ -88,8 +88,24 @@ ALL_PYTEST_MODULE_INVOCATION: tuple[str, ...] = (
     "-q",
 )
 
+CODE_RULES_GATE_PYTHON_ENV_VAR: str = "CODE_RULES_GATE_PYTHON"
+
+CODE_RULES_GATE_PYTHONPATH_ENV_VAR: str = "CODE_RULES_GATE_PYTHONPATH"
+
+PYTHONPATH_ENV_VAR: str = "PYTHONPATH"
+
+ALL_VENV_DIRECTORY_NAMES: tuple[str, ...] = (".venv", "venv")
+
+ALL_WINDOWS_VENV_PYTHON_RELATIVE_PATH_SEGMENTS: tuple[str, ...] = ("Scripts", "python.exe")
+
+ALL_POSIX_VENV_PYTHON_RELATIVE_PATH_SEGMENTS: tuple[str, ...] = ("bin", "python")
+
 STAGED_PYTEST_TIMEOUT_SECONDS: int = 600
 
+MAXIMUM_STAGED_PYTEST_COMMAND_LINE_CHARACTERS: int = 24000
+
+COMMAND_LINE_ARGUMENT_SEPARATOR_LENGTH: int = 1
+
 STAGED_TEST_FAILURE_HEADER: str = (
     "code_rules_gate: staged test file(s) failed under pytest; commit blocked."
 )
@@ -119,3 +135,7 @@ STAGED_TEST_GROUP_FAILURE_MESSAGE: str = (
     "code_rules_gate: staged test group rooted at {group_root} "
     "failed under pytest; commit blocked."
 )
+
+MINIMUM_STAGED_PYTEST_PYTHON_MAJOR: int = 3
+
+MINIMUM_STAGED_PYTEST_PYTHON_MINOR: int = 12

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

@@ -1,8 +1,9 @@
-"""Configuration constants for the CLAUDE_REVIEWS_DISABLED opt-out gate."""
+"""Configuration constants for the reviewer opt-out and opt-in gates."""
 
 from __future__ import annotations
 
 CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME: str = "CLAUDE_REVIEWS_DISABLED"
+CLAUDE_REVIEWS_ENABLED_ENV_VAR_NAME: str = "CLAUDE_REVIEWS_ENABLED"
 CLAUDE_REVIEWS_DISABLED_TOKEN_SEPARATOR: str = ","
 CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN: str = "bugteam"
 CLAUDE_REVIEWS_DISABLED_BUGBOT_TOKEN: str = "bugbot"

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

@@ -11,9 +11,11 @@ Copilot counts as down in two cases: it is opted out via
 than quota available (out of quota, the quota API or account down, or no
 account configured).
 
-Bugbot carries no quota or availability API. It counts as down only when it
-is opted out via ``CLAUDE_REVIEWS_DISABLED``. A genuine runtime outage shows
-up later as a poll timeout, not here.
+Bugbot carries no quota or availability API. It is off by default and counts
+as down whenever it is disabled for the run: the default unless
+``CLAUDE_REVIEWS_ENABLED`` lists ``bugbot``, and always when
+``CLAUDE_REVIEWS_DISABLED`` lists it. A genuine runtime outage shows up later
+as a poll timeout, not here.
 
 The exit code tells the caller what to do. Exit 0 means the reviewer is
 available and may be spawned. The documented down code (3) means skip it. Any
@@ -42,8 +44,13 @@ from pr_loop_shared_constants.reviews_disabled_constants import (
     CLAUDE_REVIEWS_DISABLED_BUGBOT_TOKEN,
     CLAUDE_REVIEWS_DISABLED_COPILOT_TOKEN,
     CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME,
+    CLAUDE_REVIEWS_ENABLED_ENV_VAR_NAME,
+)
+from reviews_disabled import (
+    is_bugbot_disabled_via_env,
+    is_bugbot_opted_out_via_env,
+    is_copilot_disabled_via_env,
 )
-from reviews_disabled import is_bugbot_disabled_via_env, is_copilot_disabled_via_env
 
 
 @dataclass(frozen=True)
@@ -84,22 +91,45 @@ def _evaluate_copilot_availability(env_file_path: Path) -> ReviewerAvailability:
     return ReviewerAvailability(EXIT_CODE_REVIEWER_AVAILABLE, quota_decision.message)
 
 
+def _bugbot_down_message() -> str:
+    """Name the cause that keeps Cursor Bugbot off for this run.
+
+    An opt-out and the off-by-default state read differently to the operator:
+    one names ``CLAUDE_REVIEWS_DISABLED``, the other points at the
+    ``CLAUDE_REVIEWS_ENABLED`` opt-in the run is missing.
+
+    Returns:
+        The opt-out message when ``CLAUDE_REVIEWS_DISABLED`` lists ``bugbot``,
+        and the off-by-default opt-in message otherwise.
+    """
+    if is_bugbot_opted_out_via_env():
+        return (
+            f"reviewer-availability: bugbot is disabled via "
+            f"{CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME} — skipping."
+        )
+    return (
+        f"reviewer-availability: bugbot is off by default — set "
+        f"{CLAUDE_REVIEWS_ENABLED_ENV_VAR_NAME}={CLAUDE_REVIEWS_DISABLED_BUGBOT_TOKEN} "
+        f"to opt in — skipping."
+    )
+
+
 def _evaluate_bugbot_availability() -> ReviewerAvailability:
     """Decide whether Cursor Bugbot is available to spawn.
 
     Bugbot carries no quota or availability API, so this checks only the
-    deterministic ``CLAUDE_REVIEWS_DISABLED`` opt-out.
+    deterministic enable/disable env gate. Bugbot is off by default: it is
+    available only when ``CLAUDE_REVIEWS_ENABLED`` lists ``bugbot`` and
+    ``CLAUDE_REVIEWS_DISABLED`` does not.
 
     Returns:
-        A ReviewerAvailability that is down when Bugbot is opted out via
-        ``CLAUDE_REVIEWS_DISABLED``, and available otherwise.
+        A ReviewerAvailability that is down whenever Bugbot is disabled for
+        the run — the default unless ``CLAUDE_REVIEWS_ENABLED`` lists
+        ``bugbot``, and always when ``CLAUDE_REVIEWS_DISABLED`` lists it — and
+        available otherwise.
     """
     if is_bugbot_disabled_via_env():
-        return ReviewerAvailability(
-            EXIT_CODE_REVIEWER_DOWN,
-            f"reviewer-availability: bugbot is disabled via "
-            f"{CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME} — skipping.",
-        )
+        return ReviewerAvailability(EXIT_CODE_REVIEWER_DOWN, _bugbot_down_message())
     return ReviewerAvailability(
         EXIT_CODE_REVIEWER_AVAILABLE,
         "reviewer-availability: bugbot is available.",