claude-dev-env 1.39.0 → 1.41.0

package/CLAUDE.md

@@ -5,7 +5,7 @@ The user delegates execution to you and expects zero manual steps unless strictl
 ## Code Rules
 @~/.claude/docs/CODE_RULES.md
 
-When a UNC path is mapped to a drive letter, ALWAYS prefer the drive letter and NEVER use UNC.
+ALWAYS call the AskUserQuestion tool if you have a question for the user. Provide content-appropriate default options, with a flag for the recommended one.
 
 ## GOTCHAS
 When making code changes, make sure you are working in the proper worktree path for the task at hand.

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/grant_project_claude_permissions.py

@@ -9,9 +9,22 @@ the changes applied. No-op when the entries already exist.
 import sys
 from pathlib import Path
 
-sys.modules.pop("config", None)
-if str(Path(__file__).resolve().parent) not in sys.path:
-    sys.path.insert(0, str(Path(__file__).resolve().parent))
+parent_directory = str(Path(__file__).absolute().parent)
+try:
+    sys.path.remove(parent_directory)
+except ValueError:
+    pass
+if parent_directory not in sys.path:
+    sys.path.insert(0, parent_directory)
+
+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.")
+    or each_module_key == "_claude_permissions_common"
+]:
+    sys.modules.pop(each_cached_module_name, None)
 
 from _claude_permissions_common import (  # noqa: E402
     append_if_missing,
@@ -41,6 +54,15 @@ from config.claude_settings_keys_constants import (  # noqa: E402
 def add_rules_to_allow_list(
     all_settings: dict[str, object], all_rules_to_add: list[str]
 ) -> int:
+    """Add permission rules to the settings allow list.
+
+    Args:
+        all_settings: The parsed settings dictionary.
+        all_rules_to_add: Permission rule strings to append.
+
+    Returns:
+        Number of rules actually added (new entries).
+    """
     permissions_section = ensure_dict_section(
         all_settings, CLAUDE_SETTINGS_PERMISSIONS_KEY
     )
@@ -57,6 +79,15 @@ def add_rules_to_allow_list(
 def add_directory_to_additional_directories(
     all_settings: dict[str, object], directory_path: str
 ) -> int:
+    """Add a project path to the additionalDirectories allow list.
+
+    Args:
+        all_settings: The parsed settings dictionary.
+        directory_path: The project directory path to add.
+
+    Returns:
+        1 when the entry was added, 0 when it already existed.
+    """
     permissions_section = ensure_dict_section(
         all_settings, CLAUDE_SETTINGS_PERMISSIONS_KEY
     )
@@ -71,6 +102,15 @@ def add_directory_to_additional_directories(
 def add_auto_mode_environment_entry(
     all_settings: dict[str, object], entry_text: str
 ) -> int:
+    """Add an auto-mode environment entry for the project.
+
+    Args:
+        all_settings: The parsed settings dictionary.
+        entry_text: The environment entry text to add.
+
+    Returns:
+        1 when the entry was added, 0 when it already existed.
+    """
     auto_mode_section = ensure_dict_section(
         all_settings, CLAUDE_SETTINGS_AUTO_MODE_KEY
     )
@@ -83,6 +123,16 @@ def add_auto_mode_environment_entry(
 
 
 def grant_permissions_for_current_directory() -> None:
+    """Grant Edit/Write/Read permissions for the current project directory.
+
+    Reads the current project path, constructs permission rules from config
+    constants, and writes them to ~/.claude/settings.json atomically.
+
+    Raises:
+        SystemExit: When the current directory is not a valid project root.
+        ValueError: Propagated from get_current_project_path() when the path
+                    contains glob metacharacters.
+    """
     claude_user_settings_path: Path = get_claude_user_settings_path()
     project_root_path = Path.cwd()
     if not is_valid_project_root(project_root_path):

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

@@ -33,10 +33,13 @@ from pathlib import Path
 from typing import NoReturn
 
 sys.modules.pop("config", None)
-if str(Path(__file__).resolve().parent) not in sys.path:
-    sys.path.insert(0, str(Path(__file__).resolve().parent))
+if str(Path(__file__).absolute().parent) not in sys.path:
+    sys.path.insert(0, str(Path(__file__).absolute().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()