claude-dev-env 1.92.1 → 1.93.0

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,18 @@ 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,
     DUPLICATE_BODY_DEFINITION_LINE_GROUP_INDEX,
     DUPLICATE_BODY_SPAN_GROUP_INDEX,
     DUPLICATE_BODY_VIOLATION_PATTERN,
@@ -36,7 +42,10 @@ from pr_loop_shared_constants.code_rules_gate_constants import (  # noqa: E402
     ISOLATION_SPAN_GROUP_INDEX,
     ISOLATION_VIOLATION_PATTERN,
     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,12 +1629,97 @@ 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:
+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:
+        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 _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.
 
     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 the group's tests pass or collect nothing; pytest's non-zero
@@ -1633,14 +1727,14 @@ def _run_pytest_for_group(group_root: Path, all_group_test_paths: list[Path]) ->
     """
     pytest_process = subprocess.run(
         [
-            sys.executable,
+            _resolve_gate_python_executable(repository_root),
             *ALL_PYTEST_MODULE_INVOCATION,
             *[str(each_path) for each_path in all_group_test_paths],
         ],
         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
@@ -1670,7 +1764,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 +1778,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 +1912,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,6 +88,18 @@ 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
 
 STAGED_TEST_FAILURE_HEADER: str = (
@@ -119,3 +131,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.",

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

@@ -1,8 +1,16 @@
-"""Shared helper for the CLAUDE_REVIEWS_DISABLED opt-out gate.
+"""Decide which PR reviewers run from the opt-out and opt-in env token lists.
 
-Both ``skills/bugteam/scripts/bugteam_preflight.py`` and
-``_shared/pr-loop/scripts/preflight.py`` consume this helper so the parsing
-rules and disabled-token taxonomy live in exactly one place.
+::
+
+    enabled lists bugbot, disabled empty    -> bugbot   ok:   runs
+    no lists set                            -> bugbot   flag: off (default)
+    enabled lists bugbot, disabled bugbot   -> bugbot   flag: off (opt-out wins)
+    disabled empty                          -> bugteam  ok:   runs
+    disabled lists copilot                  -> copilot  flag: off
+
+Bugbot is off by default and runs only when the enabled list names it.
+Bugteam and copilot run by default and stop only when the disabled list
+names them; both lists parse case-insensitively and tolerate whitespace.
 """
 
 from __future__ import annotations
@@ -17,6 +25,7 @@ from pr_loop_shared_constants.reviews_disabled_constants import (
     CLAUDE_REVIEWS_DISABLED_COPILOT_TOKEN,
     CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME,
     CLAUDE_REVIEWS_DISABLED_TOKEN_SEPARATOR,
+    CLAUDE_REVIEWS_ENABLED_ENV_VAR_NAME,
     EXIT_CODE_BUGTEAM_DISABLED_VIA_ENV,
 )
 
@@ -27,18 +36,24 @@ __all__ = [
     "CLAUDE_REVIEWS_DISABLED_COPILOT_TOKEN",
     "CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME",
     "CLAUDE_REVIEWS_DISABLED_TOKEN_SEPARATOR",
+    "CLAUDE_REVIEWS_ENABLED_ENV_VAR_NAME",
     "EXIT_CODE_BUGTEAM_DISABLED_VIA_ENV",
     "is_bugbot_disabled_via_env",
+    "is_bugbot_opted_out_via_env",
     "is_bugteam_disabled_via_env",
     "is_copilot_disabled_via_env",
     "main",
 ]
 
 
-def _is_reviewer_disabled_via_env(reviewer_token: str) -> bool:
-    """Check whether CLAUDE_REVIEWS_DISABLED lists the given reviewer token.
+def _is_reviewer_listed_in_env(
+    environment_variable_name: str, reviewer_token: str
+) -> bool:
+    """Check whether an environment variable lists the given reviewer token.
 
     Args:
+        environment_variable_name: The environment variable to read, either
+            the reviews-disabled or the reviews-enabled variable name.
         reviewer_token: The reviewer token to look for, already lowercase
             (for example the bugteam or bugbot token constant).
 
@@ -46,16 +61,14 @@ def _is_reviewer_disabled_via_env(reviewer_token: str) -> bool:
         True when the env var contains ``reviewer_token`` as one of its
         comma-separated entries (case-insensitive, whitespace-tolerant).
     """
-    reviews_disabled_token_separator = CLAUDE_REVIEWS_DISABLED_TOKEN_SEPARATOR
-    disabled_reviewers_text = os.environ.get(CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME, "")
-    all_disabled_tokens = frozenset(
+    reviews_token_separator = CLAUDE_REVIEWS_DISABLED_TOKEN_SEPARATOR
+    listed_reviewers_text = os.environ.get(environment_variable_name, "")
+    all_listed_tokens = frozenset(
         each_raw_token.strip().lower()
-        for each_raw_token in disabled_reviewers_text.split(
-            reviews_disabled_token_separator
-        )
+        for each_raw_token in listed_reviewers_text.split(reviews_token_separator)
         if each_raw_token.strip()
     )
-    return reviewer_token in all_disabled_tokens
+    return reviewer_token in all_listed_tokens
 
 
 def is_bugteam_disabled_via_env() -> bool:
@@ -64,16 +77,45 @@ def is_bugteam_disabled_via_env() -> bool:
     Returns:
         True when the env var lists the ``bugteam`` token.
     """
-    return _is_reviewer_disabled_via_env(CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN)
+    return _is_reviewer_listed_in_env(
+        CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME, CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN
+    )
 
 
 def is_bugbot_disabled_via_env() -> bool:
+    """Check whether Cursor Bugbot is disabled for this run.
+
+    Cursor Bugbot is off by default. It runs only when
+    ``CLAUDE_REVIEWS_ENABLED`` lists ``bugbot``, and a ``bugbot`` token in
+    ``CLAUDE_REVIEWS_DISABLED`` forces it off even when the opt-in lists it.
+
+    Returns:
+        True when ``CLAUDE_REVIEWS_DISABLED`` lists ``bugbot`` or when
+        ``CLAUDE_REVIEWS_ENABLED`` does not list ``bugbot``.
+    """
+    is_opted_out = _is_reviewer_listed_in_env(
+        CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME, CLAUDE_REVIEWS_DISABLED_BUGBOT_TOKEN
+    )
+    is_opted_in = _is_reviewer_listed_in_env(
+        CLAUDE_REVIEWS_ENABLED_ENV_VAR_NAME, CLAUDE_REVIEWS_DISABLED_BUGBOT_TOKEN
+    )
+    return is_opted_out or not is_opted_in
+
+
+def is_bugbot_opted_out_via_env() -> bool:
     """Check whether CLAUDE_REVIEWS_DISABLED opts Cursor Bugbot out.
 
+    The opt-out forces Bugbot off even when ``CLAUDE_REVIEWS_ENABLED`` lists
+    ``bugbot``. This reports only the opt-out signal, where
+    ``is_bugbot_disabled_via_env`` also reports off for the default case in
+    which neither env var names ``bugbot``.
+
     Returns:
-        True when the env var lists the ``bugbot`` token.
+        True when ``CLAUDE_REVIEWS_DISABLED`` lists the ``bugbot`` token.
     """
-    return _is_reviewer_disabled_via_env(CLAUDE_REVIEWS_DISABLED_BUGBOT_TOKEN)
+    return _is_reviewer_listed_in_env(
+        CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME, CLAUDE_REVIEWS_DISABLED_BUGBOT_TOKEN
+    )
 
 
 def is_copilot_disabled_via_env() -> bool:
@@ -82,11 +124,13 @@ def is_copilot_disabled_via_env() -> bool:
     Returns:
         True when the env var lists the ``copilot`` token.
     """
-    return _is_reviewer_disabled_via_env(CLAUDE_REVIEWS_DISABLED_COPILOT_TOKEN)
+    return _is_reviewer_listed_in_env(
+        CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME, CLAUDE_REVIEWS_DISABLED_COPILOT_TOKEN
+    )
 
 
 def parse_arguments(all_argv: list[str]) -> argparse.Namespace:
-    """Parse command-line arguments for the reviewer opt-out check.
+    """Parse command-line arguments for the reviewer opt-out and opt-in gate check.
 
     Args:
         all_argv: Argument list excluding the program name, typically
@@ -105,19 +149,19 @@ def parse_arguments(all_argv: list[str]) -> argparse.Namespace:
             CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN,
             CLAUDE_REVIEWS_DISABLED_COPILOT_TOKEN,
         ],
-        help="Reviewer token to test against CLAUDE_REVIEWS_DISABLED",
+        help="Reviewer token to test against the CLAUDE_REVIEWS_DISABLED / CLAUDE_REVIEWS_ENABLED gates",
     )
     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.
+    """Exit 0 when the named reviewer is disabled for this run.
 
     Args:
         all_arguments: Argument list excluding the program name.
 
     Returns:
-        0 when the named reviewer is opted out by the env var, 1 otherwise.
+        0 when the named reviewer is disabled for this run, 1 otherwise.
     """
     arguments = parse_arguments(all_arguments)
     disabled_checker_by_reviewer = {