claude-dev-env 1.39.0 → 1.41.0

package/hooks/test__gh_pr_author_swap_utils.py

@@ -0,0 +1,333 @@
+"""Canonical-location tests for the gh-pr-author swap utils module.
+
+The TDD enforcer matches a production filename ``X.py`` to ``test_X.py``;
+``_gh_pr_author_swap_utils.py`` carries a leading underscore that the
+enforcer treats as part of the name. This file's tests are the canonical
+match. The broader behavioural suite lives alongside in
+``blocking/test_gh_pr_author_swap_utils.py``.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import pathlib
+import sys
+import tempfile
+
+import pytest
+
+from config.gh_pr_author_swap_constants import STATE_FILE_PERMISSION_MODE
+
+_HOOKS_ROOT = pathlib.Path(__file__).resolve().parent
+if str(_HOOKS_ROOT) not in sys.path:
+    sys.path.insert(0, str(_HOOKS_ROOT))
+
+utils_module_spec = importlib.util.spec_from_file_location(
+    "_gh_pr_author_swap_utils",
+    _HOOKS_ROOT / "_gh_pr_author_swap_utils.py",
+)
+assert utils_module_spec is not None
+assert utils_module_spec.loader is not None
+utils_module = importlib.util.module_from_spec(utils_module_spec)
+utils_module_spec.loader.exec_module(utils_module)
+
+
+def test_state_file_path_rejects_path_traversal_session_id() -> None:
+    """A session_id containing path-traversal characters must not escape tempdir.
+
+    Regression guard: an unsanitised ``session_id`` containing ``../`` or
+    ``/`` would interpolate into the filename and let the resulting path
+    land outside ``tempfile.gettempdir()``. The sanitiser strips every
+    character outside ``[A-Za-z0-9_-]`` and falls back to the default
+    session id when the result is empty.
+    """
+    sanitised_path = utils_module._state_file_path("../../tmp/evil")
+    temporary_directory_path = pathlib.Path(tempfile.gettempdir()).resolve()
+    assert sanitised_path.parent.resolve() == temporary_directory_path
+
+
+def test_state_file_path_rejects_backslash_in_session_id() -> None:
+    """Backslashes are also unsafe path separators on Windows."""
+    sanitised_path = utils_module._state_file_path("evil\\..\\..\\system32")
+    temporary_directory_path = pathlib.Path(tempfile.gettempdir()).resolve()
+    assert sanitised_path.parent.resolve() == temporary_directory_path
+
+
+def test_state_file_path_rejects_nul_byte_in_session_id() -> None:
+    """A NUL byte inside the session id must not reach the filename."""
+    sanitised_path = utils_module._state_file_path("abc\x00../def")
+    temporary_directory_path = pathlib.Path(tempfile.gettempdir()).resolve()
+    assert sanitised_path.parent.resolve() == temporary_directory_path
+    assert "\x00" not in sanitised_path.name
+
+
+def test_state_file_path_preserves_safe_session_id() -> None:
+    """A well-formed session id passes through unchanged."""
+    safe_session_id = "session-001_abc"
+    produced_path = utils_module._state_file_path(safe_session_id)
+    assert safe_session_id in produced_path.name
+
+
+def test_backtick_substitution_blanks_inner_quoted_literals() -> None:
+    """A ``gh pr create`` literal inside a single-quoted argument of a backtick body must not trigger.
+
+    Mirrors ``$(printf '...')`` behaviour: when the backtick body's
+    quoted literal contains the token, the matcher must blank the
+    quoted region before searching.
+    """
+    stripped_command = utils_module._strip_quoted_regions("foo `printf ';gh pr create'`")
+    assert not utils_module._command_invokes_gh_pr_create_in_stripped(stripped_command)
+
+
+def test_backtick_substitution_matches_unquoted_gh_pr_create_inside_body() -> None:
+    """A bare ``gh pr create`` inside a backtick body still matches.
+
+    Symmetric to ``$(gh pr create)`` — the substitution body is real
+    code, so the matcher must see it.
+    """
+    stripped_command = utils_module._strip_quoted_regions("echo `gh pr create --title T`")
+    assert utils_module._command_invokes_gh_pr_create_in_stripped(stripped_command)
+
+
+def test_state_file_is_attacker_planted_returns_true_for_world_readable_mode(
+    tmp_path: pathlib.Path,
+) -> None:
+    """A state file with mode 0o644 is flagged as attacker-planted on POSIX.
+
+    The enforcer always atomically creates state files at 0o600. A file
+    at the predictable swap-state path with any other mode bits cannot
+    have come from the enforcer running as this user.
+    """
+    if not hasattr(os, "getuid"):
+        return
+    state_file = tmp_path / "gh_pr_author_swap_session-attacker.json"
+    state_file.write_text("{}", encoding="utf-8")
+    os.chmod(state_file, 0o644)
+
+    assert utils_module._state_file_is_attacker_planted(state_file) is True
+
+
+def test_state_file_is_attacker_planted_returns_false_for_well_formed_file(
+    tmp_path: pathlib.Path,
+) -> None:
+    """A state file written exactly the way the enforcer writes is not flagged."""
+    state_file = tmp_path / "gh_pr_author_swap_session-good.json"
+    state_file.write_text("{}", encoding="utf-8")
+    if hasattr(os, "getuid"):
+        os.chmod(state_file, STATE_FILE_PERMISSION_MODE)
+
+    assert utils_module._state_file_is_attacker_planted(state_file) is False
+
+
+def test_state_file_is_attacker_planted_returns_false_for_missing_file(
+    tmp_path: pathlib.Path,
+) -> None:
+    """A missing state file is treated as not-planted so callers can no-op cleanly."""
+    missing_state_file = tmp_path / "gh_pr_author_swap_session-missing.json"
+
+    assert utils_module._state_file_is_attacker_planted(missing_state_file) is False
+
+
+def test_state_file_is_attacker_planted_returns_true_for_non_regular_file(
+    tmp_path: pathlib.Path,
+) -> None:
+    """A FIFO at the predictable swap-state path is flagged as attacker-planted.
+
+    The enforcer only writes regular files; any non-regular file type
+    (symlink, FIFO, device) at the predictable path indicates another
+    party pre-created it to redirect the restore or cleanup hook.
+    """
+    if not hasattr(os, "mkfifo"):
+        pytest.skip("mkfifo not available on this platform")
+    if not hasattr(os, "getuid"):
+        pytest.skip("POSIX ownership semantics not available on this platform")
+    fifo_state_file = tmp_path / "gh_pr_author_swap_session-fifo.json"
+    os.mkfifo(fifo_state_file, STATE_FILE_PERMISSION_MODE)
+
+    assert utils_module._state_file_is_attacker_planted(fifo_state_file) is True
+
+
+def test_state_file_is_attacker_planted_returns_true_when_lstat_raises_os_error(
+    tmp_path: pathlib.Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """An ``OSError`` from ``lstat`` fails closed — the path is treated as planted.
+
+    A path that exists but is unreadable (permission denied, broken
+    filesystem mount, etc.) cannot be proven safe, so the helper
+    returns True to keep the restore or cleanup hook from trusting it.
+    """
+    if not hasattr(os, "getuid"):
+        pytest.skip("POSIX ownership semantics not available on this platform")
+    unreadable_state_file = tmp_path / "gh_pr_author_swap_session-unreadable.json"
+    unreadable_state_file.write_text("{}", encoding="utf-8")
+
+    def raise_permission_error(self: pathlib.Path) -> os.stat_result:
+        raise PermissionError("simulated lstat failure")
+
+    monkeypatch.setattr(pathlib.Path, "lstat", raise_permission_error)
+
+    assert utils_module._state_file_is_attacker_planted(unreadable_state_file) is True
+
+
+def test_strip_bash_comments_preserves_substitution_body_when_hash_is_inside_dollar_paren() -> None:
+    """Regression: ``$(date +%H # 24h) && gh pr create`` must not let the regex eat past the substitution closer.
+
+    Before this fix ``_strip_bash_comments`` ran a flat regex sweep that
+    blanked from ``#`` to end-of-line regardless of substitution depth.
+    A ``#`` preceded by whitespace inside a ``$(...)`` body consumed
+    the closing ``)`` AND every byte after it on the same line,
+    erasing a real ``gh pr create`` invocation from the enforcer's
+    view and silently bypassing the swap.
+    """
+    raw_command = "$(date +%H # 24h) && gh pr create --title T"
+    preprocessed_command = utils_module._preprocess_command_for_matching(raw_command)
+    assert "gh pr create" in preprocessed_command
+    assert utils_module._command_invokes_gh_pr_create_in_stripped(preprocessed_command)
+
+
+def test_strip_bash_comments_preserves_substitution_body_when_hash_is_inside_backtick() -> None:
+    """Regression: a ``#`` inside a backtick body must not erase a trailing ``gh pr create``.
+
+    Backtick substitution is symmetric with ``$(...)``; the
+    substitution-aware comment walker must treat both shapes the same.
+    """
+    raw_command = "foo `cmd # comment` bar && gh pr create"
+    preprocessed_command = utils_module._preprocess_command_for_matching(raw_command)
+    assert "gh pr create" in preprocessed_command
+    assert utils_module._command_invokes_gh_pr_create_in_stripped(preprocessed_command)
+
+
+def test_strip_bash_comments_strips_top_level_trailing_comment() -> None:
+    """Existing behaviour: a top-level trailing ``#`` comment after ``gh pr create`` is blanked.
+
+    The comment-stripping pass must still erase a real top-level
+    comment so the enforcer treats only the command portion as code.
+    """
+    raw_command = "gh pr create # this is a comment"
+    preprocessed_command = utils_module._preprocess_command_for_matching(raw_command)
+    assert "this is a comment" not in preprocessed_command
+
+
+def test_strip_bash_comments_strips_prior_line_comment_only() -> None:
+    """Existing behaviour: a comment on line 1 is blanked but a ``gh pr create`` on line 2 still matches.
+
+    The newline is preserved so the matcher can still tell the two
+    lines apart, and the second-line command stays intact.
+    """
+    raw_command = "echo a # b\ngh pr create"
+    preprocessed_command = utils_module._preprocess_command_for_matching(raw_command)
+    assert "gh pr create" in preprocessed_command
+    assert "# b" not in preprocessed_command
+    assert utils_module._command_invokes_gh_pr_create_in_stripped(preprocessed_command)
+
+
+def test_lstat_indicates_attacker_planted_returns_false_for_well_formed_lstat(
+    tmp_path: pathlib.Path,
+) -> None:
+    """A 0o600 regular file owned by the current user is not flagged.
+
+    Mirrors ``test_state_file_is_attacker_planted_returns_false_for_well_formed_file``
+    but feeds the helper a pre-computed ``lstat`` result so the helper
+    does not perform its own syscall.
+    """
+    state_file = tmp_path / "gh_pr_author_swap_session-well_formed.json"
+    state_file.write_text("{}", encoding="utf-8")
+    if hasattr(os, "getuid"):
+        os.chmod(state_file, STATE_FILE_PERMISSION_MODE)
+
+    file_lstat_result = state_file.lstat()
+
+    assert utils_module._lstat_indicates_attacker_planted(file_lstat_result) is False
+
+
+def test_lstat_indicates_attacker_planted_returns_true_for_world_readable_mode(
+    tmp_path: pathlib.Path,
+) -> None:
+    """A 0o644 regular file is flagged as attacker-planted on POSIX.
+
+    The enforcer always creates state files at 0o600, so a divergent
+    mode is treated as a plant.
+    """
+    if not hasattr(os, "getuid"):
+        pytest.skip("POSIX ownership semantics not available on this platform")
+    state_file = tmp_path / "gh_pr_author_swap_session-mode_wrong.json"
+    state_file.write_text("{}", encoding="utf-8")
+    os.chmod(state_file, 0o644)
+
+    file_lstat_result = state_file.lstat()
+
+    assert utils_module._lstat_indicates_attacker_planted(file_lstat_result) is True
+
+
+def test_lstat_indicates_attacker_planted_returns_true_for_foreign_uid(
+    tmp_path: pathlib.Path,
+) -> None:
+    """A regular 0o600 file owned by a different uid is flagged on POSIX.
+
+    The helper sees only the ``stat_result`` it is given, so the test
+    builds a synthetic ``os.stat_result`` whose ``st_uid`` does not match
+    ``os.getuid()`` and feeds it directly to the helper.
+    """
+    if not hasattr(os, "getuid"):
+        pytest.skip("POSIX ownership semantics not available on this platform")
+    state_file = tmp_path / "gh_pr_author_swap_session-foreign_uid.json"
+    state_file.write_text("{}", encoding="utf-8")
+    os.chmod(state_file, STATE_FILE_PERMISSION_MODE)
+    real_lstat_result = state_file.lstat()
+    foreign_user_id = os.getuid() + 1
+    synthetic_stat_fields = (
+        real_lstat_result.st_mode,
+        real_lstat_result.st_ino,
+        real_lstat_result.st_dev,
+        real_lstat_result.st_nlink,
+        foreign_user_id,
+        real_lstat_result.st_gid,
+        real_lstat_result.st_size,
+        real_lstat_result.st_atime,
+        real_lstat_result.st_mtime,
+        real_lstat_result.st_ctime,
+    )
+    synthetic_stat_result = os.stat_result(synthetic_stat_fields)
+
+    assert utils_module._lstat_indicates_attacker_planted(synthetic_stat_result) is True
+
+
+def test_lstat_indicates_attacker_planted_returns_true_for_non_regular_file(
+    tmp_path: pathlib.Path,
+) -> None:
+    """A FIFO at the predictable swap-state path is flagged.
+
+    Mirrors ``test_state_file_is_attacker_planted_returns_true_for_non_regular_file``
+    but feeds the helper the FIFO's own ``lstat`` result rather than the
+    path.
+    """
+    if not hasattr(os, "mkfifo"):
+        pytest.skip("mkfifo not available on this platform")
+    if not hasattr(os, "getuid"):
+        pytest.skip("POSIX ownership semantics not available on this platform")
+    fifo_state_file = tmp_path / "gh_pr_author_swap_session-fifo.json"
+    os.mkfifo(fifo_state_file, STATE_FILE_PERMISSION_MODE)
+
+    file_lstat_result = fifo_state_file.lstat()
+
+    assert utils_module._lstat_indicates_attacker_planted(file_lstat_result) is True
+
+
+def test_lstat_indicates_attacker_planted_returns_false_on_windows(
+    tmp_path: pathlib.Path,
+) -> None:
+    """On Windows (no ``os.getuid``) the helper short-circuits to False.
+
+    Windows tempdir is already per-user, so the cross-user attack
+    surface this check guards against on POSIX does not exist there.
+    """
+    if hasattr(os, "getuid"):
+        pytest.skip("POSIX has os.getuid; this case asserts Windows-only behaviour")
+    state_file = tmp_path / "gh_pr_author_swap_session-windows.json"
+    state_file.write_text("{}", encoding="utf-8")
+
+    file_lstat_result = state_file.lstat()
+
+    assert utils_module._lstat_indicates_attacker_planted(file_lstat_result) is False

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.39.0",
+    "version": "1.41.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/skills/_shared/pr-loop/scripts/write_audit_outcomes.py

@@ -70,8 +70,8 @@ def _populate_findings(parent: Element, findings_data: list[dict[str, object]])
 
     Scalar finding fields become XML attributes on `<finding>`; the
     body fields named in `ALL_FINDING_BODY_ELEMENT_KEYS` (defined in
-    `config/path_resolver_constants.py` and currently
-    `("title", "excerpt", "description")`) become child elements.
+    `packages/claude-dev-env/skills/_shared/pr-loop/scripts/config/path_resolver_constants.py`
+    and currently `("title", "excerpt", "description")`) become child elements.
     Nested dicts or lists in scalar slots are flattened to string form
     so attribute serialization stays well-defined.
 

package/skills/_shared/pr-loop/scripts/write_fix_outcomes.py

@@ -1,8 +1,8 @@
 """Validate status enum values and write <bugteam_fix> XML at the canonical path.
 
 Status enum (canonical source: `ALL_VALID_FIX_STATUSES` in
-`config/path_resolver_constants.py`): fixed | could_not_address |
-hook_blocked | unverified_fixed.
+`packages/claude-dev-env/skills/_shared/pr-loop/scripts/config/path_resolver_constants.py`):
+fixed | could_not_address | hook_blocked | unverified_fixed.
 
 Each outcome's scalar fields become XML attributes on `<outcome>`; the
 body fields named in `ALL_FIX_OUTCOME_BODY_ELEMENT_KEYS` (currently

package/skills/bugteam/SKILL.md

@@ -32,6 +32,11 @@ other failures require manual fix before Step 0. Full detail:
 
 First match wins; respond with the quoted line exactly and stop:
 
+- **Disabled via environment.** When `CLAUDE_REVIEWS_DISABLED` contains the
+  token `bugteam` (comma-separated, case-insensitive, whitespace-tolerant):
+  `/bugteam is disabled via CLAUDE_REVIEWS_DISABLED.` The pre-flight script
+  also exits 7 in this case so any caller invoking it directly halts on the
+  same signal.
 - **No PR or upstream diff.** `No PR or upstream diff. /bugteam needs a target.`
 - **Dirty tree.** `Uncommitted changes detected. Stash, commit, or revert before
   /bugteam.`
@@ -50,16 +55,29 @@ Every internal audit pass (CLEAN or DIRTY) ends with one call to
 finding; each becomes its own resolvable thread). The mandate applies
 whether bugteam runs inside `/pr-converge` or standalone.
 
-**Self-PR precondition.** GitHub rejects both `APPROVE` and
-`REQUEST_CHANGES` reviews when the authenticated identity (the `gh auth`
-token in scope) matches the PR author with HTTP 422 ("Cannot
-approve/request changes on your own pull request"). `post_audit_thread.py`
-will retry on transient errors and then exit 2 (retry exhaustion); the
-script does not detect the self-PR case and downgrade to `COMMENT`. To
-run bugteam on a PR you authored, switch `gh auth` to an alternate
-reviewer identity (a separate GitHub account) BEFORE invoking the skill.
-Without this switch, exit 2 is a hard halt — there is no automated
-fallback path. The script does not auto-downgrade on the self-PR case.
+**Self-PR auto-toggle.** GitHub rejects both `APPROVE` and
+`REQUEST_CHANGES` reviews with HTTP 422 when the authenticated identity
+matches the PR author ("Cannot approve/request changes on your own pull
+request"). `post_audit_thread.py` detects this case via `gh api user` +
+`gh api repos/<o>/<r>/pulls/<n>` and auto-resolves an alternate gh
+account's token for the reviews POST — the active `gh auth` account is
+not mutated; only the bearer token sent on the request changes. After
+the POST the active account is still whoever it was before, so no
+"swap back" step is needed.
+
+Configuration:
+
+- `GH_TOKEN` / `GITHUB_TOKEN` env vars take precedence over the toggle.
+  Set them when you need to pin a specific reviewer identity by token
+  rather than by account login.
+- `BUGTEAM_REVIEWER_ACCOUNT` env var names which authenticated alternate
+  to prefer when a toggle is needed (for example,
+  `BUGTEAM_REVIEWER_ACCOUNT=jl-cmd`). When unset, the script falls back
+  to the first alternate account `gh auth status` reports.
+- The named alternate must be logged in (`gh auth login -h github.com -u
+  <login>`) before the audit skill runs. The script exits 1 with a
+  pointing-at-`gh auth login` message when self-PR is detected and no
+  usable alternate is authenticated.
 
 ```
 python "${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/post_audit_thread.py" \

package/skills/bugteam/reference/audit-contract.md

@@ -91,6 +91,17 @@ The audit must either produce new Shape A findings citing new file:line referenc
 
 For `/bugteam`, the single audit agent provides per-category coverage by walking all A–K rubrics in one invocation.
 
+## Merge rules
+
+When the LEAD combines findings from multiple sources (primary auditor, Haiku secondary auditor, adversarial pass), it applies these rules:
+
+- **De-dup key**: `(file, line, category)`. Two findings sharing the same `(file, line, category)` tuple are the same finding and collapse into one entry.
+- **Severity conflict**: max wins (`P0 > P1 > P2`). When sources disagree on severity for the same de-dup key, the merged entry keeps the highest severity.
+- **Unique-to-secondary findings**: added to the merged set with the secondary's severity and source annotation.
+- **Unique-to-primary findings**: kept as-is.
+- **Zero secondary findings**: primary set trusted; proceed.
+- **Malformed or non-parseable secondary output**: lead trusts the primary set and logs the event in `loop-<L>-diagnostics.json` under `haiku_findings` as `[{"parse_error": "<message>"}]`.
+
 ## Post-fix self-audit
 
 Audit-and-fix skills (`/qbug`, `/bugteam`) MUST re-audit modified files between `py_compile` and `git add`. This catches fix-induced regressions in the same loop that introduced them rather than on loop N+1.
@@ -109,6 +120,17 @@ Sequence:
 
 `converged` exit condition: `primary_audit_clean AND post_fix_audit_clean` for the committing loop.
 
+## De-dup and merge
+
+Findings from primary, adversarial, Haiku secondary, and post-fix passes are merged into a single deduped finding list before persistence.
+
+- **De-dup key:** `(file, line, category)`. Two findings sharing the same `(file, line, category)` tuple collapse into a single deduped entry.
+- **Severity conflict resolution:** `max wins`. When merged findings disagree on severity, the deduped entry carries the maximum severity (`P0 > P1 > P2`).
+- **Excerpt and failure_mode:** the deduped entry inherits these fields from the highest-severity contributing finding. Ties keep the first observed contributor.
+- **`evidence_files`:** the deduped entry carries the union of every contributor's `evidence_files`, deduplicated and sorted.
+
+The merged list lands in `loop-<L>-diagnostics.json` under both `merged` (one entry per contributing finding) and `deduped` (one entry per unique `(file, line, category)` tuple).
+
 ## Persistence
 
 Every audit loop writes two JSON files under the skill's scoped temp directory (resolved via `tempfile.gettempdir()`):

package/skills/bugteam/reference/github-pr-reviews.md

@@ -22,7 +22,7 @@ python "${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/post_audit_thread.py"
 
 Capture `<head_sha>` via `git rev-parse HEAD` in the subagent cwd immediately before this call so the review attaches to the commit the audit actually scoped.
 
-`--findings-json` points to a JSON file whose root is a list of objects shaped `{path, line, side, severity, description, fix_summary}`. Build it from the merged Shape A findings: finding `file` → `path`. Each finding's `failure_mode` carries the full audit-to-fix handoff text per [`agents/code-quality-agent.md`](../../../agents/code-quality-agent.md); split `failure_mode` at the literal `Fix:` heading so the failure narrative becomes `description` and the suffix beginning at `Fix:` (including the trailing `Validation:` clause) becomes `fix_summary`. When a finding's `failure_mode` omits the `Fix:` heading, write the full text to BOTH `description` and `fix_summary` so the script's body template (`INLINE_COMMENT_BODY_TEMPLATE` in [`scripts/config/post_audit_thread_constants.py`](../../../_shared/pr-loop/scripts/config/post_audit_thread_constants.py)) renders coherently. Set `side="RIGHT"` for every entry. On CLEAN the list is empty (`[]`); on DIRTY the list carries one entry per finding.
+`--findings-json` points to a JSON file whose root is a list of objects shaped `{path, line, side, severity, description, fix_summary}`. Build it from the merged Shape A findings: finding `file` → `path`. Each finding's `failure_mode` carries the full audit-to-fix handoff text per [`agents/code-quality-agent.md`](../../../agents/code-quality-agent.md); split `failure_mode` at the literal `Fix:` heading so the failure narrative becomes `description` and the suffix beginning at `Fix:` (including the trailing `Validation:` clause) becomes `fix_summary`. When a finding's `failure_mode` omits the `Fix:` heading, write the full text to BOTH `description` and `fix_summary` so the script's body template (`INLINE_COMMENT_BODY_TEMPLATE` in [`packages/claude-dev-env/_shared/pr-loop/scripts/config/post_audit_thread_constants.py`](../../../_shared/pr-loop/scripts/config/post_audit_thread_constants.py)) renders coherently. Set `side="RIGHT"` for every entry. On CLEAN the list is empty (`[]`); on DIRTY the list carries one entry per finding.
 
 The script handles retries internally — 1s / 4s / 16s backoff across four attempts (one initial plus three retries). Exit codes:
 

package/skills/bugteam/reference/team-setup.md

@@ -138,3 +138,8 @@ Self-claiming by task subject prefix keeps each teammate on its assigned PR.
 **`--bugbot-retrigger` flag:** when present, the FIX subagent posts a `bugbot
 run` issue comment via the Step 2.5 issue-comments fallback endpoint after
 every successful FIX push, to re-trigger Cursor's bugbot on the new commit.
+
+**Opt-out gate.** When `CLAUDE_REVIEWS_DISABLED` (comma-separated,
+case-insensitive, whitespace-tolerant) contains the token `bugbot`, the FIX
+subagent skips the re-trigger post even when the flag is present. The rest of
+the bugteam audit/fix cycle continues unchanged.

package/skills/bugteam/scripts/bugteam_fix_hookspath.py

@@ -5,14 +5,20 @@ import subprocess
 import sys
 from pathlib import Path
 
+parent_directory = str(Path(__file__).resolve().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.")
 ]:
     sys.modules.pop(each_cached_module_name, None)
-if str(Path(__file__).resolve().parent) not in sys.path:
-    sys.path.insert(0, str(Path(__file__).resolve().parent))
 
 from config.bugteam_fix_hookspath_constants import (
     ALL_CANONICAL_HOOKS_DIRECTORY_COMPONENTS,

package/skills/bugteam/scripts/bugteam_preflight.py

@@ -12,8 +12,11 @@ for each_cached_module_name in [
     if each_module_key == "config" or each_module_key.startswith("config.")
 ]:
     sys.modules.pop(each_cached_module_name, None)
-if str(Path(__file__).resolve().parent) not in sys.path:
-    sys.path.insert(0, str(Path(__file__).resolve().parent))
+_bugteam_scripts_directory = str(Path(__file__).absolute().parent)
+while _bugteam_scripts_directory in sys.path:
+    sys.path.remove(_bugteam_scripts_directory)
+if _bugteam_scripts_directory not in sys.path:
+    sys.path.insert(0, _bugteam_scripts_directory)
 
 from config.bugteam_preflight_constants import (
     ALL_DISCOVERY_IGNORE_DIRECTORIES,
@@ -32,6 +35,26 @@ from config.bugteam_preflight_constants import (
     PYTEST_INI_FILENAME,
 )
 
+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 = (
+    Path(__file__).absolute().parent
+    / ".." / ".." / ".." / "_shared" / "pr-loop" / "scripts"
+).absolute()
+if str(_shared_pr_loop_scripts_directory) not in sys.path:
+    sys.path.insert(0, str(_shared_pr_loop_scripts_directory))
+
+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) -> int:
     """Check that core.hooksPath resolves to the claude-dev-env git-hooks directory.
@@ -259,6 +282,17 @@ def main(all_argv: list[str] | None = None) -> int:
     if os.environ.get(BUGTEAM_PREFLIGHT_SKIP_ENV_VAR_NAME, "").strip() == "1":
         print(f"{BUGTEAM_PREFLIGHT_PREFIX}skipped (BUGTEAM_PREFLIGHT_SKIP=1).", 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_PREFIX}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()
     resolved_repository_root: Path = (
         arguments.repo_root.resolve()

package/skills/bugteam/scripts/test__claude_permissions_common.py

@@ -19,6 +19,54 @@ if _script_directory not in sys.path:
     sys.path.insert(0, _script_directory)
 
 import _claude_permissions_common as common_module
+import grant_project_claude_permissions as grant_module
+import revoke_project_claude_permissions as revoke_module
+
+
+def test_is_valid_project_root_not_defined_on_common_module() -> None:
+    """The common module must not expose ``is_valid_project_root``.
+
+    Both grant and revoke define their own local copy. A shared copy on
+    the common module would be a third parallel definition with no
+    production caller, so its absence is the asserted contract.
+    """
+    assert not hasattr(common_module, "is_valid_project_root")
+
+
+def test_grant_is_valid_project_root_detects_git_marker(tmp_path: Path) -> None:
+    git_project_root = tmp_path / "git_project"
+    (git_project_root / ".git").mkdir(parents=True)
+    assert grant_module.is_valid_project_root(git_project_root) is True
+
+
+def test_grant_is_valid_project_root_detects_claude_marker(tmp_path: Path) -> None:
+    claude_project_root = tmp_path / "claude_project"
+    (claude_project_root / ".claude").mkdir(parents=True)
+    assert grant_module.is_valid_project_root(claude_project_root) is True
+
+
+def test_grant_is_valid_project_root_rejects_unmarked_directory(tmp_path: Path) -> None:
+    unmarked_directory = tmp_path / "no_marker"
+    unmarked_directory.mkdir()
+    assert grant_module.is_valid_project_root(unmarked_directory) is False
+
+
+def test_revoke_is_valid_project_root_detects_git_marker(tmp_path: Path) -> None:
+    git_project_root = tmp_path / "git_project"
+    (git_project_root / ".git").mkdir(parents=True)
+    assert revoke_module.is_valid_project_root(git_project_root) is True
+
+
+def test_revoke_is_valid_project_root_detects_claude_marker(tmp_path: Path) -> None:
+    claude_project_root = tmp_path / "claude_project"
+    (claude_project_root / ".claude").mkdir(parents=True)
+    assert revoke_module.is_valid_project_root(claude_project_root) is True
+
+
+def test_revoke_is_valid_project_root_rejects_unmarked_directory(tmp_path: Path) -> None:
+    unmarked_directory = tmp_path / "no_marker"
+    unmarked_directory.mkdir()
+    assert revoke_module.is_valid_project_root(unmarked_directory) is False
 
 
 def test_write_atomically_with_mode_releases_fd_when_fdopen_raises(

package/skills/bugteam/scripts/test_bugteam_preflight.py

@@ -266,3 +266,44 @@ def test_has_pytest_configuration_returns_false_without_either_file(
     repository_root = tmp_path / "repo"
     repository_root.mkdir()
     assert bugteam_preflight.has_pytest_configuration(repository_root) is False
+
+
+def test_main_should_halt_when_env_var_lists_bugteam(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """CLAUDE_REVIEWS_DISABLED=bugteam must halt preflight with the dedicated exit code."""
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "bugteam")
+    monkeypatch.delenv("BUGTEAM_PREFLIGHT_SKIP", raising=False)
+    exit_code = bugteam_preflight.main(["--no-pytest"])
+    assert exit_code == bugteam_preflight.EXIT_CODE_BUGTEAM_DISABLED_VIA_ENV
+    captured = capsys.readouterr()
+    assert "CLAUDE_REVIEWS_DISABLED" in captured.err
+    assert "bugteam" in captured.err
+
+
+def test_main_should_continue_when_env_var_omits_bugteam(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    """CLAUDE_REVIEWS_DISABLED without the bugteam token must not halt preflight."""
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "copilot,bugbot")
+    monkeypatch.delenv("BUGTEAM_PREFLIGHT_SKIP", raising=False)
+    claude_hooks_path = tmp_path / ".claude" / "hooks" / "git-hooks"
+    claude_hooks_path.mkdir(parents=True)
+    with patch("subprocess.run") as mock_run:
+        mock_run.return_value = _make_completed_process(
+            str(claude_hooks_path) + "\n", returncode=0
+        )
+        exit_code = bugteam_preflight.main(["--no-pytest"])
+    assert exit_code != bugteam_preflight.EXIT_CODE_BUGTEAM_DISABLED_VIA_ENV
+
+
+def test_main_should_halt_when_env_var_contains_uppercase_or_whitespace_bugteam_token(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Token matching must be case-insensitive and whitespace-tolerant."""
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", " BugTeam , copilot ")
+    monkeypatch.delenv("BUGTEAM_PREFLIGHT_SKIP", raising=False)
+    exit_code = bugteam_preflight.main(["--no-pytest"])
+    assert exit_code == bugteam_preflight.EXIT_CODE_BUGTEAM_DISABLED_VIA_ENV