claude-dev-env 1.35.0 → 1.36.0

package/hooks/config/stuttering_import_binding_constants.py

@@ -0,0 +1,11 @@
+"""Constants for the stuttering ``all_``/``ALL_`` AST import-binding scan.
+
+Lives under the hooks-tree ``config/`` package so module-level
+UPPER_SNAKE constants satisfy the CODE_RULES "constants live in config"
+requirement and share a home with the other hook-tree configuration
+(``messages``, ``stuttering_check_config``, ``project_paths_reader``).
+"""
+
+WILDCARD_IMPORT_SENTINEL = "*"
+MODULE_PATH_SEPARATOR = "."
+AST_LINENO_ATTRIBUTE = "lineno"

package/hooks/config/sys_path_insert_constants.py

@@ -0,0 +1,4 @@
+"""Constants for the sys.path.insert deduplication guard checker."""
+
+MAX_SYS_PATH_INSERT_ISSUES: int = 25
+SYS_PATH_INSERT_GUIDANCE: str = "guard with `if <path> not in sys.path:` to avoid pushing the same entry on every reload"

package/hooks/config/test_banned_identifiers_constants.py

@@ -0,0 +1,48 @@
+"""Behavior tests for banned-identifier configuration constants."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+_HOOKS_ROOT = Path(__file__).resolve().parent.parent
+if str(_HOOKS_ROOT) not in sys.path:
+    sys.path.insert(0, str(_HOOKS_ROOT))
+
+from config.banned_identifiers_constants import (
+    ALL_BANNED_IDENTIFIERS,
+    BANNED_IDENTIFIER_MESSAGE_SUFFIX,
+    BANNED_IDENTIFIER_SKIP_ADVISORY,
+    MAX_BANNED_IDENTIFIER_ISSUES,
+)
+
+
+def test_all_banned_identifiers_includes_canonical_offenders() -> None:
+    canonical_offenders = {
+        "result",
+        "data",
+        "output",
+        "response",
+        "value",
+        "item",
+        "temp",
+        "argv",
+        "args",
+        "kwargs",
+        "argc",
+    }
+    assert canonical_offenders <= ALL_BANNED_IDENTIFIERS
+
+
+def test_max_banned_identifier_issues_is_positive_cap() -> None:
+    assert MAX_BANNED_IDENTIFIER_ISSUES > 0
+
+
+def test_banned_identifier_message_suffix_references_naming_section() -> None:
+    assert "CODE_RULES" in BANNED_IDENTIFIER_MESSAGE_SUFFIX
+    assert "Naming" in BANNED_IDENTIFIER_MESSAGE_SUFFIX
+
+
+def test_banned_identifier_skip_advisory_explains_skip_reason() -> None:
+    assert "skipped" in BANNED_IDENTIFIER_SKIP_ADVISORY
+    assert "parse" in BANNED_IDENTIFIER_SKIP_ADVISORY

package/hooks/config/test_hardcoded_user_path_constants.py

@@ -0,0 +1,78 @@
+"""Behavior tests for hardcoded user-path detection constants."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+_HOOKS_ROOT = Path(__file__).resolve().parent.parent
+if str(_HOOKS_ROOT) not in sys.path:
+    sys.path.insert(0, str(_HOOKS_ROOT))
+
+from config.hardcoded_user_path_constants import HARDCODED_USER_PATH_PATTERN
+
+
+def test_pattern_matches_windows_user_home() -> None:
+    match = HARDCODED_USER_PATH_PATTERN.search("C:/Users/jon/notes")
+    assert match is not None
+    assert match.group(0) == "C:/Users/jon"
+
+
+def test_pattern_matches_macos_user_home() -> None:
+    match = HARDCODED_USER_PATH_PATTERN.search("/Users/bob/Documents")
+    assert match is not None
+    assert match.group(0) == "/Users/bob"
+
+
+def test_pattern_matches_linux_user_home() -> None:
+    match = HARDCODED_USER_PATH_PATTERN.search("/home/alice/data")
+    assert match is not None
+    assert match.group(0) == "/home/alice"
+
+
+def test_pattern_excludes_windows_public_shared_folder() -> None:
+    assert HARDCODED_USER_PATH_PATTERN.search("C:/Users/Public/Documents") is None
+
+
+def test_pattern_excludes_windows_shared_folder() -> None:
+    assert HARDCODED_USER_PATH_PATTERN.search("C:/Users/Shared/data") is None
+
+
+def test_pattern_excludes_windows_all_users_folder() -> None:
+    assert HARDCODED_USER_PATH_PATTERN.search("C:/Users/All Users/AppData") is None
+
+
+def test_pattern_excludes_macos_shared_folder() -> None:
+    assert HARDCODED_USER_PATH_PATTERN.search("/Users/Shared/data") is None
+
+
+def test_pattern_excludes_macos_public_shared_folder() -> None:
+    assert HARDCODED_USER_PATH_PATTERN.search("/Users/Public/Documents") is None
+
+
+def test_pattern_excludes_windows_lowercase_public_shared_folder() -> None:
+    assert HARDCODED_USER_PATH_PATTERN.search("c:/users/public/Documents") is None
+
+
+def test_pattern_excludes_windows_lowercase_shared_folder() -> None:
+    assert HARDCODED_USER_PATH_PATTERN.search("c:/users/shared/data") is None
+
+
+def test_pattern_excludes_windows_lowercase_all_users_folder() -> None:
+    assert HARDCODED_USER_PATH_PATTERN.search("c:/users/all users/AppData") is None
+
+
+def test_pattern_excludes_windows_mixed_case_public_shared_folder() -> None:
+    assert HARDCODED_USER_PATH_PATTERN.search("C:/Users/PuBlIc/Documents") is None
+
+
+def test_pattern_excludes_windows_uppercase_public_shared_folder() -> None:
+    assert HARDCODED_USER_PATH_PATTERN.search("C:/Users/PUBLIC/Documents") is None
+
+
+def test_pattern_excludes_macos_lowercase_shared_folder() -> None:
+    assert HARDCODED_USER_PATH_PATTERN.search("/Users/shared/data") is None
+
+
+def test_pattern_excludes_macos_lowercase_public_shared_folder() -> None:
+    assert HARDCODED_USER_PATH_PATTERN.search("/Users/public/Documents") is None

package/hooks/config/test_hook_log_extractor_constants.py

@@ -24,7 +24,7 @@ from config.hook_log_extractor_constants import (
     STOP_WRAPPER_DEBOUNCE_SECONDS,
     STOP_WRAPPER_LAST_RUN_TIMESTAMP_FILE,
     WINDOWS_CREATE_NEW_PROCESS_GROUP_FLAG,
-    WINDOWS_DETACHED_PROCESS_FLAG,
+    WINDOWS_CREATE_NO_WINDOW_FLAG,
 )
 
 
@@ -116,8 +116,8 @@ def test_stop_wrapper_last_run_timestamp_file_is_under_claude_home() -> None:
 
 
 def test_windows_creation_flags_are_distinct_nonzero_bits() -> None:
-    assert WINDOWS_DETACHED_PROCESS_FLAG > 0
+    assert WINDOWS_CREATE_NO_WINDOW_FLAG > 0
     assert WINDOWS_CREATE_NEW_PROCESS_GROUP_FLAG > 0
     assert (
-        WINDOWS_DETACHED_PROCESS_FLAG & WINDOWS_CREATE_NEW_PROCESS_GROUP_FLAG
+        WINDOWS_CREATE_NO_WINDOW_FLAG & WINDOWS_CREATE_NEW_PROCESS_GROUP_FLAG
     ) == 0

package/hooks/config/test_pre_tool_use_stdin.py

@@ -0,0 +1,80 @@
+"""Tests for PreToolUse stdin JSON parsing helper."""
+
+from __future__ import annotations
+
+import inspect
+import io
+import json
+import sys
+from unittest.mock import patch
+
+from config import pre_tool_use_stdin
+from config.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+
+
+def test_pre_tool_use_stdin_uses_shared_encoding_and_decode_constants() -> None:
+    """Pin: stdin parsing must use shared constants, not duplicate literals."""
+    module_source = inspect.getsource(pre_tool_use_stdin)
+    assert "UTF8_ENCODING" in module_source
+    assert "DECODE_ERRORS_POLICY" in module_source
+    assert "UTF8_BYTE_ORDER_MARK" in module_source
+    assert '.decode("utf-8"' not in module_source
+    assert 'errors="replace"' not in module_source
+    assert "stdin_parse_constants" not in module_source
+
+
+def test_read_returns_none_for_empty_stdin() -> None:
+    with patch("sys.stdin", io.StringIO("")):
+        assert read_hook_input_dictionary_from_stdin() is None
+
+
+def test_read_returns_none_for_whitespace_only_stdin() -> None:
+    with patch("sys.stdin", io.StringIO("   \n\t  ")):
+        assert read_hook_input_dictionary_from_stdin() is None
+
+
+def test_read_returns_none_for_invalid_json() -> None:
+    with patch("sys.stdin", io.StringIO("not json")):
+        assert read_hook_input_dictionary_from_stdin() is None
+
+
+def test_read_returns_none_for_json_array_root() -> None:
+    with patch("sys.stdin", io.StringIO("[1, 2]")):
+        assert read_hook_input_dictionary_from_stdin() is None
+
+
+def test_read_strips_bom_and_returns_dict() -> None:
+    payload = {"tool_name": "Bash", "tool_input": {"command": "ls"}}
+    with patch("sys.stdin", io.StringIO("\ufeff" + json.dumps(payload))):
+        parsed = read_hook_input_dictionary_from_stdin()
+    assert parsed == payload
+
+
+def test_read_returns_dict_for_valid_json_object() -> None:
+    payload = {"tool_name": "Read", "tool_input": {"file_path": "/tmp/x"}}
+    with patch("sys.stdin", io.StringIO(json.dumps(payload))):
+        parsed = read_hook_input_dictionary_from_stdin()
+    assert parsed == payload
+
+
+def test_read_uses_buffer_when_present() -> None:
+    payload = {"tool_name": "Bash", "tool_input": {}}
+    raw_bytes = json.dumps(payload).encode("utf-8")
+    binary_stream = io.BytesIO(raw_bytes)
+    text_wrapper = io.TextIOWrapper(binary_stream, encoding="utf-8")
+    with patch("sys.stdin", text_wrapper):
+        parsed = read_hook_input_dictionary_from_stdin()
+    assert parsed == payload
+
+
+def test_read_returns_none_when_buffer_and_text_read_raise_attribute_error() -> None:
+    class BrokenStandardInput:
+        @property
+        def buffer(self) -> object:
+            raise AttributeError("no buffer")
+
+        def read(self, size: int = -1) -> str:
+            raise AttributeError("no read")
+
+    with patch("sys.stdin", BrokenStandardInput()):
+        assert read_hook_input_dictionary_from_stdin() is None

package/hooks/config/unused_module_import_constants.py

@@ -0,0 +1,7 @@
+"""Constants for the unused module-level import scan in ``code_rules_enforcer``."""
+
+MAX_UNUSED_IMPORT_ISSUES: int = 25
+UNUSED_IMPORT_GUIDANCE: str = (
+    "remove unused import; if kept for side effects, mark with `# noqa: F401`"
+)
+TYPE_CHECKING_IDENTIFIER: str = "TYPE_CHECKING"

package/hooks/config/windows_rmtree_blocker_constants.py

@@ -0,0 +1,3 @@
+"""Configuration constants for the windows_rmtree_blocker PreToolUse hook."""
+
+PYTHON_FILE_EXTENSION: str = ".py"

package/hooks/diagnostic/hook_log_stop_wrapper.py

@@ -9,8 +9,11 @@ stay near zero. The wrapper:
    path: a small file read, well under 10ms).
 2. Otherwise records the current timestamp, then launches the extractor
    as a fully detached background process (no stdio, separate process
-   group on POSIX or DETACHED_PROCESS|CREATE_NEW_PROCESS_GROUP on
-   Windows) and returns without waiting for it.
+   group on POSIX or CREATE_NO_WINDOW|CREATE_NEW_PROCESS_GROUP on
+   Windows) and returns without waiting for it. CREATE_NO_WINDOW
+   prevents a console flash on Windows even when the wrapper goes
+   through ``bws run`` first; DETACHED_PROCESS would let the
+   grandchild python.exe allocate a fresh console.
 
 Bitwarden injection: when both ``bws`` is on PATH and
 ``BWS_ACCESS_TOKEN`` is set, the extractor is launched via
@@ -45,7 +48,7 @@ from config.hook_log_extractor_constants import (
     STOP_WRAPPER_EXTRACTOR_SCRIPT_NAME,
     STOP_WRAPPER_LAST_RUN_TIMESTAMP_FILE,
     WINDOWS_CREATE_NEW_PROCESS_GROUP_FLAG,
-    WINDOWS_DETACHED_PROCESS_FLAG,
+    WINDOWS_CREATE_NO_WINDOW_FLAG,
     WINDOWS_OS_NAME,
 )
 
@@ -113,7 +116,7 @@ def _detached_spawn_keyword_arguments() -> dict[str, object]:
     }
     if os.name == WINDOWS_OS_NAME:
         spawn_arguments["creationflags"] = (
-            WINDOWS_DETACHED_PROCESS_FLAG
+            WINDOWS_CREATE_NO_WINDOW_FLAG
             | WINDOWS_CREATE_NEW_PROCESS_GROUP_FLAG
         )
         startup_info = subprocess.STARTUPINFO()

package/hooks/git-hooks/config.py

@@ -20,10 +20,10 @@ GATE_PATH_OVERRIDE_ENV_VAR: str = "CODE_RULES_GATE_PATH"
 CLAUDE_HOME_ENV_VAR: str = "CLAUDE_HOME"
 CLAUDE_HOME_DEFAULT_SUBDIRECTORY: str = ".claude"
 GATE_SCRIPT_RELATIVE_PATH: tuple[str, ...] = (
-    "skills",
-    "bugteam",
+    "_shared",
+    "pr-loop",
     "scripts",
-    "bugteam_code_rules_gate.py",
+    "code_rules_gate.py",
 )
 GATE_INFRASTRUCTURE_FAILURE_EXIT_CODE: int = 2
 GATE_SCRIPT_NOT_FOUND_MESSAGE: str = (

package/hooks/git-hooks/test_gate_utils.py

@@ -44,7 +44,7 @@ def test_resolve_gate_script_path_defaults_to_claude_home_when_env_var_set(
     resolved_path, exact_allowed = gate_utils.resolve_gate_script_path()
 
     expected_path = (
-        tmp_path / "skills" / "bugteam" / "scripts" / "bugteam_code_rules_gate.py"
+        tmp_path / "_shared" / "pr-loop" / "scripts" / "code_rules_gate.py"
     )
     assert resolved_path == expected_path
     assert exact_allowed is None
@@ -63,10 +63,10 @@ def test_resolve_gate_script_path_falls_back_to_home_dot_claude_when_no_env_vars
     expected_path = (
         tmp_path
         / ".claude"
-        / "skills"
-        / "bugteam"
+        / "_shared"
+        / "pr-loop"
         / "scripts"
-        / "bugteam_code_rules_gate.py"
+        / "code_rules_gate.py"
     )
     assert resolved_path == expected_path
     assert exact_allowed is None
@@ -106,13 +106,13 @@ def test_is_safe_regular_file_accepts_exact_override_path(
     assert is_safe
 
 
-def test_is_safe_regular_file_rejects_claude_home_override_outside_home_dot_claude(
+def test_is_safe_regular_file_rejects_gate_outside_home_dot_claude_tree(
     tmp_path: Path,
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
     attacker_home = tmp_path / "attacker_home"
     gate_under_attacker_home = (
-        attacker_home / "skills" / "bugteam" / "scripts" / "bugteam_code_rules_gate.py"
+        attacker_home / "_shared" / "pr-loop" / "scripts" / "code_rules_gate.py"
     )
     gate_under_attacker_home.parent.mkdir(parents=True)
     gate_under_attacker_home.write_text("", encoding="utf-8")
@@ -130,7 +130,7 @@ def test_is_safe_regular_file_accepts_gate_inside_home_dot_claude(
 ) -> None:
     home_dir = tmp_path / "real_home"
     gate_path = (
-        home_dir / ".claude" / "skills" / "bugteam" / "scripts" / "bugteam_code_rules_gate.py"
+        home_dir / ".claude" / "_shared" / "pr-loop" / "scripts" / "code_rules_gate.py"
     )
     gate_path.parent.mkdir(parents=True)
     gate_path.write_text("", encoding="utf-8")
@@ -148,7 +148,7 @@ def test_is_safe_regular_file_rejects_nonexistent_path_under_trusted_prefix(
     home_dir = tmp_path / "real_home"
     (home_dir / ".claude").mkdir(parents=True)
     missing_gate_path = (
-        home_dir / ".claude" / "skills" / "bugteam" / "scripts" / "missing_gate.py"
+        home_dir / ".claude" / "_shared" / "pr-loop" / "scripts" / "missing_gate.py"
     )
     monkeypatch.setattr(Path, "home", staticmethod(lambda: home_dir))
 
@@ -182,7 +182,7 @@ def test_is_safe_regular_file_uses_claude_home_env_as_trust_root(
 ) -> None:
     custom_claude_home = tmp_path / "custom_claude"
     gate_path = (
-        custom_claude_home / "skills" / "bugteam" / "scripts" / "bugteam_code_rules_gate.py"
+        custom_claude_home / "_shared" / "pr-loop" / "scripts" / "code_rules_gate.py"
     )
     gate_path.parent.mkdir(parents=True)
     gate_path.write_text("", encoding="utf-8")
@@ -202,7 +202,7 @@ def test_resolve_gate_script_path_snapshot_is_consistent_with_is_safe_regular_fi
 ) -> None:
     custom_claude_home = tmp_path / "custom_claude"
     gate_path = (
-        custom_claude_home / "skills" / "bugteam" / "scripts" / "bugteam_code_rules_gate.py"
+        custom_claude_home / "_shared" / "pr-loop" / "scripts" / "code_rules_gate.py"
     )
     gate_path.parent.mkdir(parents=True)
     gate_path.write_text("", encoding="utf-8")

package/hooks/mypy.ini

@@ -0,0 +1,2 @@
+[mypy]
+mypy_path = .

package/package.json

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

package/rules/gh-paginate.md

@@ -0,0 +1,125 @@
+# gh API Pagination Rule
+
+**Root cause:** The GitHub REST API returns 30 items per page by default. `gh api repos/<owner>/<repo>/pulls/<number>/reviews` and `gh api repos/<owner>/<repo>/pulls/<number>/comments` silently truncate at 30 results without warning. PRs that have accumulated more than 30 reviews or inline comments — common on long PR-loop cycles where bugbot, copilot, or the in-house bugteam each post repeatedly — return only the **oldest** 30, hiding the most recent reviews and findings entirely. A `sort_by(.submitted_at) | last` (or `| reverse`) on a truncated array picks the latest entry **within the first 30**, not the actual latest, which produces a stale-but-confident report that then drives wrong decisions (e.g., re-triggering bugbot when it has already posted a CLEAN review on a later page).
+
+**Rule:** All `gh api` calls that read `pulls/<number>/reviews`, `pulls/<number>/comments`, `issues/<number>/comments`, or any other paginated GitHub list endpoint **must** request the full set of pages AND apply any cross-page jq operation through external `jq`, not through `gh`'s built-in `--jq`. Use `--paginate --slurp | jq` (preferred — see [Safe patterns](#safe-patterns)). Never call these endpoints with their default pagination, and never use `gh`'s `--jq` for cross-page operations like `sort_by | last` or `| reverse | .[0]`.
+
+## Two defects, one rule
+
+This rule guards against two distinct silent-truncation defects that compound:
+
+1. **Default 30-item page.** Without `--paginate`, only the first page is fetched. On long PRs this hides the most recent reviews entirely.
+2. **`--jq` runs per-page, not on the concatenated result.** Per [GitHub CLI #10459](https://github.com/cli/cli/issues/10459), `gh api --paginate --jq '<filter>'` applies `<filter>` to each page **separately** and emits one output per page. Cross-page operations like `sort_by(.submitted_at) | last` therefore operate within each page independently, not across the merged result set. On PRs with more than 100 reviews this still produces a wrong-but-confident "latest" review even when `--paginate` is set.
+
+The safe patterns below fix both defects together: `--paginate --slurp` walks every page AND emits a single merged structure, and an **external** `jq` then runs cross-page operations on that merged structure.
+
+## Affected endpoints
+
+The rule applies to every paginated read from the GitHub REST API. Common offenders in this repo's PR-loop skills:
+
+- `gh api repos/<owner>/<repo>/pulls/<number>/reviews`
+- `gh api repos/<owner>/<repo>/pulls/<number>/comments`
+- `gh api repos/<owner>/<repo>/pulls/<number>/files`
+- `gh api repos/<owner>/<repo>/issues/<number>/comments`
+- `gh api repos/<owner>/<repo>/pulls`
+- `gh api repos/<owner>/<repo>/issues`
+
+The same rule applies to any other endpoint documented as paginated by GitHub (see [GitHub REST API pagination](https://docs.github.com/en/rest/using-the-rest-api/using-pagination-in-the-rest-api)).
+
+Single-object endpoints (e.g., `repos/<owner>/<repo>/pulls/<number>` returning one PR object) are not paginated — `?per_page=...` is silently ignored, and neither `--paginate` nor external `jq` is required. Use `gh`'s `--jq` directly on those endpoints.
+
+## Safe patterns
+
+### Preferred — `--paginate --slurp` piped to external `jq`
+
+`gh --paginate --slurp` walks every page and emits a single merged JSON array of page-arrays (`[[page1_items...], [page2_items...], ...]`). Pipe to external `jq` to flatten and filter across the full result set:
+
+```bash
+gh api 'repos/<owner>/<repo>/pulls/<number>/reviews?per_page=100' --paginate --slurp \
+  | jq '[.[][] | select(.user.login=="cursor[bot]")] | sort_by(.submitted_at) | last'
+```
+
+The `.[][]` flattens the array-of-pages into one stream of items before the cross-page operators (`sort_by`, `last`, `reverse`) run. Combine with `?per_page=100` so each page fetches 100 items instead of 30, reducing round-trips on long PRs without changing correctness.
+
+`gh`'s `--jq` flag and `--slurp` flag are mutually exclusive (gh CLI rejects `--paginate --slurp --jq` with `the --slurp option is not supported with --jq or --template`), which is why the filter must run in an external `jq` invocation.
+
+### Acceptable — single-page bound on a paginated list endpoint when result fits
+
+When you have an explicit reason to read at most one page from a **paginated** list endpoint (e.g., a known-small list), document the bound in a comment and use `?per_page=100` without `--paginate`. Cross-page operators are not in play here, so `gh`'s `--jq` is safe:
+
+```bash
+# Bound: a freshly created issue is expected to have <= 100 comments.
+gh api 'repos/<owner>/<repo>/issues/<number>/comments?per_page=100' \
+  --jq '[.[] | select(.user.login=="cursor[bot]")] | length'
+```
+
+This pattern is only safe when the endpoint is confirmed to return a list smaller than 100 entries. Lists that grow over the PR's lifetime (reviews, comments) must use `--paginate --slurp` plus external `jq`.
+
+### Single-object endpoints — no pagination needed
+
+Endpoints that return a single object (e.g., `pulls/<number>`, `issues/<number>`) are not paginated. `?per_page=...`, `--paginate`, and `--slurp` are all unnecessary. Use `gh`'s built-in `--jq` directly:
+
+```bash
+gh api 'repos/<owner>/<repo>/pulls/<number>' --jq '.head.sha'
+```
+
+### Newest-first walk
+
+Pair pagination with explicit reverse-sort so the consumer reads newest-first regardless of the API's internal order:
+
+```bash
+gh api 'repos/<owner>/<repo>/pulls/<number>/reviews?per_page=100' --paginate --slurp \
+  | jq '[.[][] | select(.user.login=="cursor[bot]")] | sort_by(.submitted_at) | reverse'
+```
+
+This is the canonical pattern for the bugbot ↔ bugteam convergence loop: walk newest-first, stop at the first clean review.
+
+## What NOT to do
+
+```bash
+# BAD — default 30-item page silently truncates on long PRs
+gh api repos/<owner>/<repo>/pulls/<number>/reviews \
+  --jq '[.[] | select(.user.login=="cursor[bot]")] | sort_by(.submitted_at) | last'
+
+# BAD — `?per_page=100` alone caps at 100 items; PRs with 100+ reviews still truncate
+gh api 'repos/<owner>/<repo>/pulls/<number>/reviews?per_page=100' \
+  --jq '[.[] | select(.user.login=="cursor[bot]")] | sort_by(.submitted_at) | last'
+
+# BAD — --paginate fetches every page, but `--jq` runs PER-PAGE (gh CLI #10459).
+# `sort_by(.submitted_at) | last` operates within each page independently and
+# emits one "latest" per page, not the actual latest across the full result set.
+gh api 'repos/<owner>/<repo>/pulls/<number>/reviews?per_page=100' --paginate \
+  --jq '[.[] | select(.user.login=="cursor[bot]")] | sort_by(.submitted_at) | last'
+
+# BAD — taking `| last` on an unpaginated read returns the latest of the first 30,
+# not the actual latest. Same defect for `| reverse | .[0]`.
+```
+
+## Why both defects matter
+
+`gh api`'s default page is the FIRST page of results, ordered oldest-to-newest by the GitHub API. When the result set exceeds 30 items, page 1 contains the OLDEST 30 — not the newest. A jq `| last` after `sort_by(.submitted_at)` picks the latest entry within those 30 oldest items, producing output that looks correct but reports a state from days or weeks ago.
+
+`--paginate` alone does NOT fix this when paired with `--jq`: gh applies the jq filter to each page separately and emits one result per page. A consumer reading "the last line of output" still gets the latest within a single page, not the latest across all pages. The skill that consumes this output then makes decisions (re-trigger bugbot, mark a finding stale, report convergence) against an obsolete view of the PR.
+
+`--paginate --slurp | jq` fixes both defects: every page is fetched, every page is merged into one structure before any jq operator runs, and cross-page operations see the full result set.
+
+## Consumers
+
+Skills and scripts in this repo that read paginated endpoints and must therefore use `--paginate --slurp` plus external `jq`:
+
+- `pr-converge` — bugbot review walk (BUGBOT phase, Step 2.a) and inline-comments fetch (Step 2.b).
+- `bugteam` — review threads, inline comments, audit-loop history.
+- `qbug` — same as bugteam, scoped to a single subagent loop.
+- `pr-review-responder` — review comments fetch (already enforced; this rule extends the same constraint to reviews and other endpoints).
+- `monitor-many` — open-PR enumeration and per-PR review/comment scans.
+- `babysit-pr` — review-comment polling.
+
+Updating any of these to read paginated endpoints requires `--paginate --slurp` plus external `jq` (or a documented single-page bound on a small list).
+
+## Enforcement
+
+This rule is documentation-only at present. A future PreToolUse hook may pattern-match `Bash` invocations of `gh api repos/.../pulls/<n>/(reviews|comments)` without `--paginate --slurp` (or with `--paginate --jq` doing cross-page operations) and return a corrective message. Until that hook lands, treat this rule as binding by review and rely on it during skill authoring.
+
+## Precedent
+
+The `pr-review-responder` skill predated this rule and forbids default pagination on `pulls/<n>/comments` reads (`packages/claude-dev-env/skills/pr-review-responder/SKILL.md` Rule 1). This file generalizes that constraint to every paginated GitHub endpoint, adds the `--jq` per-page defect (gh CLI #10459) discovered while reviewing this rule, and centralizes the safe patterns so additional skills inherit the rule by reference instead of restating it.

package/skills/bugteam/CONSTRAINTS.md

@@ -1,25 +1,31 @@
 # Bugteam — invariants and design rationale
 
+## Path A vs Path B
+
+**Path A** (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`): the constraints below apply as written — `TeamCreate`, isolated teammate sessions, lead-only `TeamDelete`. **Path B** (Task harness): read [`reference/workflow-path-b-task-harness.md`](reference/workflow-path-b-task-harness.md) for harness-only steps; **agent types** (`code-quality-agent`, `clean-coder`), **models**, **one commit per fix**, **gate-before-AUDIT**, **10-loop cap**, and **outcome XML** remain identical to `SKILL.md`. Path B intentionally uses **`Task`** from the lead instead of teammate isolation — see that file **Clean-room note**.
+
 ## Constraints
 
-- **Agent teams required, not parallel subagents.** The skill MUST use Claude Code's agent teams feature (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`). Spawning `code-quality-agent` and `clean-coder` as parallel subagents from the lead's context = fail; the clean-room property requires independent teammate sessions.
-- **Orchestrator-only `TeamCreate`.** Only the lead session (this session, when `/bugteam` is invoked) calls `TeamCreate`. Teammates never call `TeamCreate` — if a teammate's spawn prompt instructs it to, that is a skill defect. When additional parallel work is needed (e.g., parallel auditors from loop 4 onward, supplementary audit of adjacent files), the lead spawns additional teammates into the EXISTING team by passing the current `team_name` to every `Agent(...)` call. Multiple teammate "sets" live inside one team under one orchestrator. The runtime enforces this: `TeamCreate` called while the session already leads a team returns the error `Already leading team "<name>". A leader can only manage one team at a time. Use TeamDelete to end the current team before creating a new one.` — direct quote from the runtime's response when this invariant is violated.
+- **Path A — agent teams required, not parallel subagents from the lead without `TeamCreate`.** On Path A, the skill MUST use Claude Code's agent teams feature (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`). Spawning `code-quality-agent` and `clean-coder` as parallel **Agents** with `team_name` from the lead is the supported pattern. Spawning ad-hoc `generalPurpose` workers in place of those roles = fail. **Path B** does not use `TeamCreate`; it uses **`Task`** carrying the same Path A spawn contracts per [`reference/workflow-path-b-task-harness.md`](reference/workflow-path-b-task-harness.md) (AUDIT/FIX spawn; when the host rejects `subagent_type="clean-coder"`, apply **Path B — Cursor `Task` registry**). Not a substitute for skipping `code-quality-agent` / `clean-coder` work.
+- **Path B — Cursor `Task` registry.** When the host `Task` tool rejects `subagent_type="clean-coder"`, Path B FIX MUST use `subagent_type: "generalPurpose"` plus the mandatory **Read** of `clean-coder.md` in the FIX prompt per [`reference/workflow-path-b-task-harness.md`](reference/workflow-path-b-task-harness.md) (FIX spawn, Cursor host split). This is the documented shim, not an ad-hoc `generalPurpose` bypass of the clean-coder contract.
+- **Path A — orchestrator-only `TeamCreate`.** Only the lead session (this session, when `/bugteam` is invoked) calls `TeamCreate`. Teammates never call `TeamCreate` — if a teammate's spawn prompt instructs it to, that is a skill defect. When additional parallel work is needed (e.g., parallel auditors from loop 4 onward, supplementary audit of adjacent files), the lead spawns additional teammates into the EXISTING team by passing the current `team_name` to every `Agent(...)` call. Multiple teammate "sets" live inside one team under one orchestrator. The runtime enforces this: `TeamCreate` called while the session already leads a team returns the error `Already leading team "<name>". A leader can only manage one team at a time. Use TeamDelete to end the current team before creating a new one.` — direct quote from the runtime's response when this invariant is violated. The Step 2 lifecycle resolution in [Team lifecycle](SKILL.md#team-lifecycle-path-a-only) parses this exact error in `auto` mode to attach to the existing team rather than fail. **Path B:** no `TeamCreate`; parallel work uses parallel **`Task`** calls per [`reference/workflow-path-b-task-harness.md`](reference/workflow-path-b-task-harness.md).
 - **One team per invocation, multi-PR supported.** All PRs in a single /bugteam invocation share one team created by the orchestrator. Per-PR identity lives in the teammate name prefix (`bugfind-pr<N>-loop<L>` / `bugfix-pr<N>-loop<L>`) and the `<team_temp_dir>/pr-<N>/` subfolder containing that PR's git worktree, diff patches, and outcome XML files.
 - **Grant before any spawn, revoke before any return.** Step 0 grants project `.claude/**` permissions; Step 5 revokes. Both are mandatory. Revoke runs on every exit path including error, cap-reached, and stuck.
 - **Fresh teammate per loop.** Both bugfind and bugfix are spawned new each loop and shut down after their action. Reusing a teammate across loops accumulates context inside that teammate's window — defeats clean-room.
 - **One up-front confirmation = whole cycle.** The `/bugteam` invocation authorizes the entire cycle; every subsequent decision runs on that single authorization.
 - **10-loop hard cap.** Counted as **AUDIT** completions (increment in Step 3). Standards-fix passes before an audit do not advance `loop_count`. Worst case includes extra clean-coder spawns for the code-rules gate.
-- **Code rules gate before every AUDIT.** Run `scripts/bugteam_code_rules_gate.py` until exit **0** before spawning **bugfind**. Same `validate_content` logic as `hooks/blocking/code_rules_enforcer.py`.
+- **Code rules gate before every AUDIT.** Run `_shared/pr-loop/scripts/code_rules_gate.py` (resolved via `${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/code_rules_gate.py`) until exit **0** before spawning **bugfind**. Same `validate_content` logic as `hooks/blocking/code_rules_enforcer.py`.
 - **Clean-room audits, every loop.** Each bugfind teammate's spawn prompt contains only the PR scope, audit rubric, and the current loop number. Prior loop history stays in the lead.
 - **Targeted fixes.** Each fix teammate sees ONLY the most recent audit's findings. Prior loops are invisible to the fix teammate.
 - **Opus 4.7 at xhigh effort for both teammates.** Both `Agent(...)` spawns pass `model="opus"`, which resolves to Opus 4.7 on the Anthropic API. Opus 4.7's default effort level in Claude Code is `xhigh` (https://code.claude.com/docs/en/model-config — *"On Opus 4.7, the default effort is `xhigh` for all plans and providers."*), so no `effort` override is needed at spawn time. Effort is set per-subagent in YAML frontmatter, not via the `Agent` tool's parameters; `code-quality-agent` and `clean-coder` rely on the model default. The trade vs Sonnet is higher per-loop cost in exchange for deeper audit recall and stronger fix correctness on bug-hunting work, which the per-PR loop economics tolerate (10-loop hard cap bounds total spend).
 - **Fix teammate receives the latest audit as its input contract.** Passing the audit's findings to the fix teammate is the input contract — each loop's fix run operates on the current audit's output and only that.
 - **One commit per fix action.** Loops produce one commit per loop, not one per bug.
 - **Linear branch, fixed PR base.** Every loop appends one forward-only commit; existing commits and the PR base stay intact throughout the cycle.
-- **Lead-only cleanup.** Per the docs: *"Always use the lead to clean up. Teammates should not run cleanup because their team context may not resolve correctly, potentially leaving resources in an inconsistent state."* This session is the lead, and cleanup runs here only.
-- **Cleanup the per-team scoped temp directory on exit.** The resolved `<team_temp_dir>` (absolute literal captured in Step 2) is deleted entirely so no loop patches leak between runs.
+- **Lead-only cleanup, gated by `team_owned`.** Per the docs: *"Always use the lead to clean up. Teammates should not run cleanup because their team context may not resolve correctly, potentially leaving resources in an inconsistent state."* This session is the lead, and cleanup runs here only. Step 4 calls `TeamDelete` **only when `team_owned == true`** (this invocation called `TeamCreate` itself). When `team_owned == false` (lifecycle `attach`, or `auto` after the runtime's `Already leading team` fallback), the orchestrator that originally created the team owns teardown — see [Team lifecycle](SKILL.md#team-lifecycle-path-a-only).
+- **Orchestrators must use `attach` mode, not `owned`.** When `/bugteam` runs inside an orchestrator that is itself managing a long-lived team across PRs (`pr-converge` multi-PR mode, `monitor-open-prs`), the orchestrator passes `BUGTEAM_TEAM_LIFECYCLE=attach` and `BUGTEAM_TEAM_NAME=<existing>`. `owned` mode under such an orchestrator would either error out (the session already leads a team) or, worse, tear down the orchestrator's team mid-sweep on the first invocation's Step 4. `auto` is the safe default for ambiguous callers; `attach` is the explicit-orchestrator contract.
+- **Cleanup the per-team scoped temp directory on exit, gated by `team_owned`.** When `team_owned == true`, the resolved `<team_temp_dir>` is removed entirely so no loop patches leak between runs. When `team_owned == false`, only this invocation's per-PR subfolders (`<team_temp_dir>/pr-<N>/`) are removed; the orchestrator-owned parent stays so the next attached invocation can write its own per-PR subfolders without colliding.
 - **Cleanup all `.bugteam-*` files on exit.** `.bugteam-loop-*.patch`, `.bugteam-loop-*.outcomes.xml`, `.bugteam-final.diff`, `.bugteam-original-body.md`, `.bugteam-final-body.md`. Working directory ends clean.
-- **Teammates own audit/fix comment posting.** Bugfind posts ONE per-loop review (parent body + child finding comments in a single batched POST, with review-fallback to a top-level issue comment). Bugfix posts the fix replies after committing. All comment, review, and reply POSTs belong to the teammates; the lead's single PR-write action is the final description rewrite at Step 4.5.
+- **Audit/fix comment posting.** **Path A:** Bugfind posts ONE per-loop review (parent body + child finding comments in a single batched POST, with review-fallback to a top-level issue comment). Bugfix posts the fix replies after committing. All comment, review, and reply POSTs belong to the teammates; the lead's single PR-write action is the final description rewrite at Step 4.5. **Path B:** the **lead** performs the same POSTs after Task handoffs (`SKILL.md` Step 2.5 + [`reference/workflow-path-b-task-harness.md`](reference/workflow-path-b-task-harness.md) § Step 2.5).
 - **Lead owns the final PR description rewrite only** (Step 4.5), and only via the `pr-description-writer` agent. The lead does not compose the description inline.
 - **One review per loop, findings as child comments of that review.** Each loop posts a single pull-request review whose body is the loop header and whose `comments[]` are the anchored findings. Each loop's review stands alone — one review created per loop, fully self-contained on the PR conversation.
 - **PR description rewrite on every exit.** Step 4.5 runs on `converged`, `cap reached`, and `stuck`. On `error`, the rewrite is best-effort; if it fails, surface the error in the final report and continue to revoke.