claude-dev-env 1.39.0 → 1.40.0

package/_shared/pr-loop/scripts/config/post_audit_thread_constants.py

@@ -69,6 +69,15 @@ EXIT_CODE_RETRY_EXHAUSTED: int = 2
 SHORT_SHA_LENGTH: int = 7
 
 ALL_GH_AUTH_TOKEN_COMMAND_PARTS: tuple[str, ...] = ("gh", "auth", "token")
+ALL_GH_API_USER_COMMAND_PARTS: tuple[str, ...] = ("gh", "api", "user")
+ALL_GH_AUTH_STATUS_COMMAND_PARTS: tuple[str, ...] = ("gh", "auth", "status")
+ALL_GH_API_COMMAND_PARTS: tuple[str, ...] = ("gh", "api")
+GH_AUTH_TOKEN_USER_FLAG: str = "--user"
+GH_USER_LOGIN_FIELD: str = "login"
+GH_PR_USER_FIELD: str = "user"
+GH_API_PR_PATH_TEMPLATE: str = "repos/{owner}/{repo}/pulls/{pr_number}"
+GH_AUTH_STATUS_ACCOUNT_LINE_MARKER: str = "Logged in to github.com account"
+GH_AUTH_STATUS_ACCOUNT_LINE_TOKEN_SEPARATOR: str = " "
 
 GH_TOKEN_ENV_VAR_NAME: str = "GH_TOKEN"
 GITHUB_TOKEN_ENV_VAR_NAME: str = "GITHUB_TOKEN"
@@ -76,6 +85,7 @@ ALL_GH_TOKEN_ENV_VAR_NAMES: tuple[str, ...] = (
     GH_TOKEN_ENV_VAR_NAME,
     GITHUB_TOKEN_ENV_VAR_NAME,
 )
+BUGTEAM_REVIEWER_ACCOUNT_ENV_VAR_NAME: str = "BUGTEAM_REVIEWER_ACCOUNT"
 
 JSON_FIELD_PATH: str = "path"
 JSON_FIELD_LINE: str = "line"

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

@@ -0,0 +1,8 @@
+"""Configuration constants for the CLAUDE_REVIEWS_DISABLED opt-out gate."""
+
+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"
+EXIT_CODE_BUGTEAM_DISABLED_VIA_ENV: int = 7

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

@@ -37,6 +37,9 @@ if str(Path(__file__).resolve().parent) not in sys.path:
     sys.path.insert(0, str(Path(__file__).resolve().parent))
 
 from config.post_audit_thread_constants import (
+    ALL_GH_API_COMMAND_PARTS,
+    ALL_GH_API_USER_COMMAND_PARTS,
+    ALL_GH_AUTH_STATUS_COMMAND_PARTS,
     ALL_GH_AUTH_TOKEN_COMMAND_PARTS,
     ALL_GH_TOKEN_ENV_VAR_NAMES,
     ALL_REQUIRED_FINDING_FIELDS,
@@ -47,6 +50,7 @@ from config.post_audit_thread_constants import (
     ALL_SUPPORTED_STATES,
     AUDIT_BODY_SKELETON_CLOSE_MARKER,
     AUDIT_BODY_SKELETON_OPEN_MARKER,
+    BUGTEAM_REVIEWER_ACCOUNT_ENV_VAR_NAME,
     CLI_FLAG_COMMIT,
     CLI_FLAG_FINDINGS_JSON,
     CLI_FLAG_OWNER,
@@ -60,6 +64,12 @@ from config.post_audit_thread_constants import (
     ERROR_RESPONSE_PREVIEW_CHARS,
     EXIT_CODE_RETRY_EXHAUSTED,
     EXIT_CODE_USER_ERROR,
+    GH_API_PR_PATH_TEMPLATE,
+    GH_AUTH_STATUS_ACCOUNT_LINE_MARKER,
+    GH_AUTH_STATUS_ACCOUNT_LINE_TOKEN_SEPARATOR,
+    GH_AUTH_TOKEN_USER_FLAG,
+    GH_PR_USER_FIELD,
+    GH_USER_LOGIN_FIELD,
     GITHUB_API_ACCEPT_HEADER,
     GITHUB_API_BASE_URL,
     GITHUB_API_USER_AGENT,
@@ -682,6 +692,287 @@ def resolve_github_token() -> str:
     return token_text
 
 
+def query_active_gh_user_login() -> str:
+    """Return the login of the gh account that owns the current ``gh auth token``.
+
+    Calls ``gh api /user`` and reads ``.login`` off the response. The result
+    is the gh CLI's currently active account — the one whose token a default
+    ``gh auth token`` call would emit.
+
+    Returns:
+        Login string of the active github.com account.
+
+    Raises:
+        UserInputError: ``gh`` not on PATH, the ``gh api /user`` call fails,
+            or the response is missing a string ``login`` field.
+    """
+    try:
+        completion = subprocess.run(
+            list(ALL_GH_API_USER_COMMAND_PARTS),
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            check=False,
+        )
+    except FileNotFoundError as missing_gh_error:
+        raise UserInputError(
+            "`gh` CLI not installed or not on PATH; cannot query the active "
+            "github.com account login"
+        ) from missing_gh_error
+    if completion.returncode != 0:
+        raise UserInputError(
+            f"`gh api /user` failed (exit {completion.returncode}): "
+            f"{completion.stderr.strip()}"
+        )
+    try:
+        parsed_value: object = json.loads(completion.stdout)
+    except json.JSONDecodeError as decode_error:
+        raise UserInputError(
+            f"`gh api /user` response not parseable as JSON: {decode_error}"
+        ) from decode_error
+    if not isinstance(parsed_value, dict):
+        raise UserInputError(
+            f"`gh api /user` response root must be an object; "
+            f"got {type(parsed_value).__name__}"
+        )
+    typed_response: dict[str, object] = parsed_value
+    login_value = typed_response.get(GH_USER_LOGIN_FIELD)
+    if not isinstance(login_value, str) or not login_value:
+        raise UserInputError(
+            f"`gh api /user` response missing string {GH_USER_LOGIN_FIELD!r}"
+        )
+    return login_value
+
+
+def query_pull_request_author_login(owner: str, repo: str, pr_number: int) -> str:
+    """Return the login of the user who authored a pull request.
+
+    Calls ``gh api /repos/{owner}/{repo}/pulls/{N}`` and reads ``.user.login``
+    off the response.
+
+    Args:
+        owner: Repository owner slug.
+        repo: Repository name slug.
+        pr_number: Pull request number.
+
+    Returns:
+        Login string of the PR author.
+
+    Raises:
+        UserInputError: ``gh api`` call fails, response malformed, or the
+            nested ``user.login`` field is missing.
+    """
+    pull_request_api_path = GH_API_PR_PATH_TEMPLATE.format(
+        owner=owner, repo=repo, pr_number=pr_number,
+    )
+    try:
+        completion = subprocess.run(
+            list(ALL_GH_API_COMMAND_PARTS) + [pull_request_api_path],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            check=False,
+        )
+    except FileNotFoundError as missing_gh_error:
+        raise UserInputError(
+            "`gh` CLI not installed or not on PATH; cannot query the PR "
+            "author login"
+        ) from missing_gh_error
+    if completion.returncode != 0:
+        raise UserInputError(
+            f"`gh api {pull_request_api_path}` failed (exit "
+            f"{completion.returncode}): {completion.stderr.strip()}"
+        )
+    try:
+        parsed_value: object = json.loads(completion.stdout)
+    except json.JSONDecodeError as decode_error:
+        raise UserInputError(
+            f"`gh api {pull_request_api_path}` response not parseable as "
+            f"JSON: {decode_error}"
+        ) from decode_error
+    if not isinstance(parsed_value, dict):
+        raise UserInputError(
+            f"`gh api {pull_request_api_path}` response root must be an "
+            f"object; got {type(parsed_value).__name__}"
+        )
+    typed_response: dict[str, object] = parsed_value
+    user_field = typed_response.get(GH_PR_USER_FIELD)
+    if not isinstance(user_field, dict):
+        raise UserInputError(
+            f"PR response missing object {GH_PR_USER_FIELD!r}"
+        )
+    typed_user: dict[str, object] = user_field
+    login_value = typed_user.get(GH_USER_LOGIN_FIELD)
+    if not isinstance(login_value, str) or not login_value:
+        raise UserInputError(
+            f"PR author missing string {GH_USER_LOGIN_FIELD!r} field"
+        )
+    return login_value
+
+
+def list_authenticated_gh_account_logins() -> list[str]:
+    """Return every github.com account login currently authenticated via gh.
+
+    Parses ``gh auth status`` output line-by-line. The CLI writes its
+    human-readable status to stderr by default; the function reads both
+    stdout and stderr to be resilient to the gh version in use.
+
+    Returns:
+        List of login strings in the order ``gh auth status`` reports them.
+        Empty list when no accounts are logged in.
+
+    Raises:
+        UserInputError: ``gh`` not on PATH.
+    """
+    try:
+        completion = subprocess.run(
+            list(ALL_GH_AUTH_STATUS_COMMAND_PARTS),
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            check=False,
+        )
+    except FileNotFoundError as missing_gh_error:
+        raise UserInputError(
+            "`gh` CLI not installed or not on PATH; cannot list "
+            "authenticated github.com accounts"
+        ) from missing_gh_error
+    output_text = (completion.stdout or "") + (completion.stderr or "")
+    parsed_logins: list[str] = []
+    for each_line in output_text.splitlines():
+        marker_index = each_line.find(GH_AUTH_STATUS_ACCOUNT_LINE_MARKER)
+        if marker_index < 0:
+            continue
+        remainder = each_line[marker_index + len(GH_AUTH_STATUS_ACCOUNT_LINE_MARKER):].strip()
+        space_index = remainder.find(GH_AUTH_STATUS_ACCOUNT_LINE_TOKEN_SEPARATOR)
+        login_candidate = remainder[:space_index] if space_index >= 0 else remainder
+        if login_candidate and login_candidate not in parsed_logins:
+            parsed_logins.append(login_candidate)
+    return parsed_logins
+
+
+def fetch_gh_token_for_account(account_login: str) -> str:
+    """Return the cached gh token for a specific authenticated account.
+
+    Calls ``gh auth token --user <login>``. Does not mutate which account
+    is "active" in the gh CLI; only retrieves a stored token.
+
+    Args:
+        account_login: github.com login whose token should be returned.
+
+    Returns:
+        Cached gh token string, stripped of trailing whitespace.
+
+    Raises:
+        UserInputError: ``gh`` not on PATH, the call fails, or it returns
+            empty output.
+    """
+    try:
+        completion = subprocess.run(
+            list(ALL_GH_AUTH_TOKEN_COMMAND_PARTS) + [GH_AUTH_TOKEN_USER_FLAG, account_login],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            check=False,
+        )
+    except FileNotFoundError as missing_gh_error:
+        raise UserInputError(
+            f"`gh` CLI not installed or not on PATH; cannot fetch token "
+            f"for account {account_login!r}"
+        ) from missing_gh_error
+    if completion.returncode != 0:
+        raise UserInputError(
+            f"`gh auth token --user {account_login}` failed (exit "
+            f"{completion.returncode}): {completion.stderr.strip()}"
+        )
+    token_text = completion.stdout.strip()
+    if not token_text:
+        raise UserInputError(
+            f"`gh auth token --user {account_login}` returned empty output"
+        )
+    return token_text
+
+
+def resolve_reviewer_token(owner: str, repo: str, pr_number: int) -> str:
+    """Return the GitHub token to use for the reviews POST, auto-toggling on self-PR.
+
+    Precedence rules, evaluated in order:
+
+    - ``GH_TOKEN`` / ``GITHUB_TOKEN`` env var set → returned unchanged; no
+      toggle attempt.
+    - Active gh account differs ``vs.`` PR author → return the active
+      account's token via :func:`resolve_github_token` (no toggle).
+    - Active gh account matches PR author (self-PR) → if the env var
+      ``BUGTEAM_REVIEWER_ACCOUNT`` names an authenticated alternate, use
+      that account's token; else fall back to the first alternate
+      authenticated account ``gh auth status`` reports. Token is fetched
+      via :func:`fetch_gh_token_for_account`. The active account is not
+      mutated; only the token sent on the reviews request changes.
+
+    Args:
+        owner: Repository owner slug.
+        repo: Repository name slug.
+        pr_number: Pull request number whose author dictates whether a
+            toggle is needed.
+
+    Returns:
+        Bearer-token string suitable for the reviews POST.
+
+    Raises:
+        UserInputError: self-PR detected and no alternate gh account is
+            authenticated, or any underlying gh query fails.
+    """
+    for each_env_var_name in ALL_GH_TOKEN_ENV_VAR_NAMES:
+        env_token_value = os.environ.get(each_env_var_name, "").strip()
+        if env_token_value:
+            return env_token_value
+    active_account_login = query_active_gh_user_login()
+    pr_author_login = query_pull_request_author_login(owner, repo, pr_number)
+    if active_account_login.lower() != pr_author_login.lower():
+        return resolve_github_token()
+    all_authenticated_logins = list_authenticated_gh_account_logins()
+    all_alternate_logins = [
+        each_login for each_login in all_authenticated_logins
+        if each_login.lower() != pr_author_login.lower()
+    ]
+    if not all_alternate_logins:
+        raise UserInputError(
+            f"Self-PR detected: active gh account {active_account_login!r} "
+            f"matches PR author. GitHub rejects APPROVE / REQUEST_CHANGES on "
+            f"self-authored PRs with HTTP 422. No alternate authenticated gh "
+            f"account found — run `gh auth login` as a separate reviewer "
+            f"account before invoking the audit skill."
+        )
+    pinned_reviewer_account = os.environ.get(
+        BUGTEAM_REVIEWER_ACCOUNT_ENV_VAR_NAME, ""
+    ).strip()
+    if pinned_reviewer_account:
+        matching_pinned_account = next(
+            (
+                each_login for each_login in all_alternate_logins
+                if each_login.lower() == pinned_reviewer_account.lower()
+            ),
+            None,
+        )
+        if matching_pinned_account is None:
+            raise UserInputError(
+                f"Self-PR detected and "
+                f"{BUGTEAM_REVIEWER_ACCOUNT_ENV_VAR_NAME}="
+                f"{pinned_reviewer_account!r} is set, but that account is "
+                f"not in the alternate-reviewer set "
+                f"{all_alternate_logins!r} (PR author "
+                f"{pr_author_login!r} is excluded). Run `gh auth login` "
+                f"for {pinned_reviewer_account!r} or unset the env var to "
+                f"fall back to the first alternate account."
+            )
+        return fetch_gh_token_for_account(matching_pinned_account)
+    return fetch_gh_token_for_account(all_alternate_logins[0])
+
+
 def build_reviews_endpoint_url(owner: str, repo: str, pr_number: int) -> str:
     """Compose the full reviews-endpoint URL for a PR.
 
@@ -915,7 +1206,11 @@ def post_audit_review(parsed_arguments: argparse.Namespace) -> PostedReview:
         repo=parsed_arguments.repo,
         pr_number=parsed_arguments.pr_number,
     )
-    token_text = resolve_github_token()
+    token_text = resolve_reviewer_token(
+        owner=parsed_arguments.owner,
+        repo=parsed_arguments.repo,
+        pr_number=parsed_arguments.pr_number,
+    )
     return post_review_with_retries(endpoint_url, token_text, all_request_fields)
 
 

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

@@ -57,6 +57,12 @@ from config.preflight_constants import (
     PYTHON_FILE_SUFFIX,
     TESTS_DIRECTORY_NAME,
 )
+from reviews_disabled import (
+    CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN,
+    CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME,
+    EXIT_CODE_BUGTEAM_DISABLED_VIA_ENV,
+    is_bugteam_disabled_via_env,
+)
 
 
 def verify_git_hooks_path(repository_root: Path | None = None) -> int:
@@ -67,8 +73,13 @@ def verify_git_hooks_path(repository_root: Path | None = None) -> int:
     overrides such as Husky or lefthook. Falls back to the current working
     directory's effective config when *repository_root* is None.
 
-    Returns zero when the configured path ends with the expected hooks suffix.
-    Returns non-zero and prints a correction message when unset or pointing elsewhere.
+    Args:
+        repository_root: Optional repository root to check. When None, uses
+            the current working directory's effective config.
+
+    Returns:
+        Zero when the configured path ends with the expected hooks suffix.
+        Non-zero and prints a correction message when unset or pointing elsewhere.
     """
     expected_hooks_path_suffix = HOOKS_PATH_VERIFICATION_SUFFIX
     enforcement_absent_message = (
@@ -123,6 +134,18 @@ def verify_git_hooks_path(repository_root: Path | None = None) -> int:
 
 
 def find_repository_root(start: Path) -> Path:
+    """Find the repository root by walking up from the starting directory.
+
+    Searches for a ``.git`` directory or file in parent directories. Falls
+    back to the nearest ancestor containing ``pytest.ini`` when no git
+    repository is found.
+
+    Args:
+        start: The directory to start searching from.
+
+    Returns:
+        The repository root path, or *start* when no repository is found.
+    """
     resolved = start.resolve()
     all_candidates = [resolved, *resolved.parents]
     for each_candidate in all_candidates:
@@ -136,6 +159,17 @@ def find_repository_root(start: Path) -> Path:
 
 
 def has_pytest_configuration(root: Path) -> bool:
+    """Check whether a directory has pytest configuration available.
+
+    Checks for ``pytest.ini`` directly, then falls back to searching for
+    ``[tool.pytest]`` in ``pyproject.toml``.
+
+    Args:
+        root: The directory to check for pytest configuration.
+
+    Returns:
+        True when pytest configuration is found in either location.
+    """
     if (root / PYTEST_INI_FILENAME).is_file():
         return True
     pyproject = root / PYPROJECT_TOML_FILENAME
@@ -146,6 +180,20 @@ def has_pytest_configuration(root: Path) -> bool:
 
 
 def has_discoverable_tests(root: Path) -> bool | None:
+    """Check whether the repository contains discoverable test files via git ls-files.
+
+    When the root has no ``.git`` marker, returns True without invoking git.
+    Otherwise asks git for tracked plus untracked test files matching the
+    discovery patterns, respecting ``.gitignore``.
+
+    Args:
+        root: The directory tree root to search.
+
+    Returns:
+        True when at least one matching test file is found. False when git
+        succeeds and returns an empty list. None when git is unavailable or
+        the ls-files invocation fails.
+    """
     git_marker = root / GIT_DIRECTORY_NAME
     if not (git_marker.is_dir() or git_marker.is_file()):
         return True
@@ -192,6 +240,21 @@ def run_pytest(
     verbose: bool,
     all_test_paths: list[Path] | None = None,
 ) -> int:
+    """Run pytest in the repository root and return the exit code.
+
+    Passes ``--ff`` (failed-first) and ``-q`` unless *verbose* is True. When
+    *all_test_paths* is provided, restricts the run to those paths via the
+    ``--`` positional separator so pytest does not misinterpret leading
+    hyphens as options. Treats the "no tests collected" exit code as a pass.
+
+    Args:
+        repository_root: The repository root for running pytest.
+        verbose: When True, omit ``-q`` so individual test names show.
+        all_test_paths: Optional list of test paths to restrict the run.
+
+    Returns:
+        The pytest exit code, or 0 when no tests were collected.
+    """
     command = [sys.executable, "-m", "pytest", PYTEST_FAILED_FIRST_FLAG]
     if not verbose:
         command.append("-q")
@@ -209,6 +272,20 @@ def run_pytest(
 
 
 def get_changed_files(repository_root: Path, base_ref: str) -> list[Path] | None:
+    """Return the list of files changed between *base_ref* and HEAD.
+
+    Refuses base refs beginning with ``-`` to prevent option injection into
+    git diff. Logs a warning and returns None on every failure path so the
+    caller can fall back to running the full suite.
+
+    Args:
+        repository_root: The repository root for running git diff.
+        base_ref: The git base ref to diff against (e.g., ``origin/main``).
+
+    Returns:
+        A list of relative file paths changed vs *base_ref*. None when
+        *base_ref* is invalid or git diff fails.
+    """
     if base_ref.startswith("-"):
         print(
             f"bugteam_preflight: invalid base_ref '{base_ref}' starts "
@@ -295,6 +372,18 @@ def _find_related_test_files(changed_path: Path, repository_root: Path) -> list[
 def discover_related_tests(
     all_changed_files: list[Path], repository_root: Path
 ) -> list[Path]:
+    """Discover all test files related to the given changed files.
+
+    Walks every changed path through :func:`_find_related_test_files` and
+    returns the sorted, de-duplicated union.
+
+    Args:
+        all_changed_files: The list of changed source files to map to tests.
+        repository_root: The repository root for resolving relative paths.
+
+    Returns:
+        Sorted list of unique related test file paths.
+    """
     related: set[Path] = set()
     for each_file in all_changed_files:
         related.update(_find_related_test_files(each_file, repository_root))
@@ -302,6 +391,14 @@ def discover_related_tests(
 
 
 def run_pre_commit(repository_root: Path) -> int:
+    """Run pre-commit on all files and return its exit code.
+
+    Args:
+        repository_root: The repository root for running pre-commit.
+
+    Returns:
+        The pre-commit exit code (0 on success, non-zero on failure).
+    """
     completed = subprocess.run(
         list(ALL_PRE_COMMIT_RUN_ALL_FILES_COMMAND),
         cwd=str(repository_root),
@@ -311,6 +408,15 @@ def run_pre_commit(repository_root: Path) -> int:
 
 
 def parse_arguments(all_arguments: list[str]) -> argparse.Namespace:
+    """Parse command-line arguments for the preflight script.
+
+    Args:
+        all_arguments: Command-line argument list.
+
+    Returns:
+        Parsed namespace with repo_root, no_pytest, pre_commit, verbose,
+        base_ref, and scope attributes.
+    """
     parser = argparse.ArgumentParser(
         description="Run local checks before /bugteam (pytest, optional pre-commit).",
     )
@@ -360,6 +466,16 @@ def parse_arguments(all_arguments: list[str]) -> argparse.Namespace:
 
 
 def main(all_arguments: list[str]) -> int:
+    """Run the preflight checks (git-hooks path, pytest, optional pre-commit).
+
+    Args:
+        all_arguments: Command-line argument list to forward to argparse.
+
+    Returns:
+        Zero on success. Non-zero exit code on the first failing check.
+        Returns :data:`EXIT_CODE_BUGTEAM_DISABLED_VIA_ENV` when
+        ``CLAUDE_REVIEWS_DISABLED`` lists the ``bugteam`` token.
+    """
     arguments = parse_arguments(all_arguments)
     skip_env_var_name = BUGTEAM_PREFLIGHT_SKIP_ENV_VAR_NAME
     skip_enabled_value = BUGTEAM_PREFLIGHT_SKIP_ENABLED_VALUE
@@ -369,6 +485,17 @@ def main(all_arguments: list[str]) -> int:
             file=sys.stderr,
         )
         return 0
+    reviews_disabled_env_var_name = CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME
+    reviews_disabled_bugteam_token = CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN
+    disabled_via_env_exit_code = EXIT_CODE_BUGTEAM_DISABLED_VIA_ENV
+    if is_bugteam_disabled_via_env():
+        print(
+            f"bugteam_preflight: halted "
+            f"({reviews_disabled_env_var_name} contains "
+            f"'{reviews_disabled_bugteam_token}').",
+            file=sys.stderr,
+        )
+        return disabled_via_env_exit_code
     start = Path.cwd()
     repository_root = (
         arguments.repo_root.resolve()

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

@@ -0,0 +1,59 @@
+"""Shared helper for the CLAUDE_REVIEWS_DISABLED opt-out gate.
+
+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.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+for each_cached_module_name in [
+    each_module_key
+    for each_module_key in list(sys.modules)
+    if each_module_key == "config" or each_module_key.startswith("config.")
+]:
+    sys.modules.pop(each_cached_module_name, None)
+_shared_pr_loop_scripts_directory = str(Path(__file__).absolute().parent)
+while _shared_pr_loop_scripts_directory in sys.path:
+    sys.path.remove(_shared_pr_loop_scripts_directory)
+if _shared_pr_loop_scripts_directory not in sys.path:
+    sys.path.insert(0, _shared_pr_loop_scripts_directory)
+
+from config.reviews_disabled_constants import (
+    CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN,
+    CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME,
+    CLAUDE_REVIEWS_DISABLED_TOKEN_SEPARATOR,
+    EXIT_CODE_BUGTEAM_DISABLED_VIA_ENV,
+)
+
+
+__all__ = [
+    "CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN",
+    "CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME",
+    "CLAUDE_REVIEWS_DISABLED_TOKEN_SEPARATOR",
+    "EXIT_CODE_BUGTEAM_DISABLED_VIA_ENV",
+    "is_bugteam_disabled_via_env",
+]
+
+
+def is_bugteam_disabled_via_env() -> bool:
+    """Check whether CLAUDE_REVIEWS_DISABLED opts the bug-audit family out of running.
+
+    Returns:
+        True when the env var contains the literal ``bugteam`` token
+        (comma-separated, 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, "")
+    all_disabled_tokens = frozenset(
+        each_raw_token.strip().lower()
+        for each_raw_token in raw_value.split(reviews_disabled_token_separator)
+        if each_raw_token.strip()
+    )
+    return reviews_disabled_bugteam_token in all_disabled_tokens