claude-dev-env 1.93.0 → 1.94.0

package/_shared/pr-loop/CLAUDE.md

@@ -8,6 +8,7 @@ Runtime documents and scripts shared by every PR-loop skill. Changes here affect
 |---|---|
 | `audit-contract.md` | Canonical finding schema (Shape A / Shape B) and loop contract; defines the JSON shapes every audit skill must emit |
 | `audit-reply-template.md` | Canonical reply skeleton Claude posts to each unresolved review thread; single source of truth for reply structure |
+| `post-audit-thread-contract.md` | Single source of truth for the `post_audit_thread.py` invocation string, exit-code table, and per-caller policy (bugteam exit 2 = hard blocker; autoconverge clean-audit failed post = recorded bypass) |
 | `fix-protocol.md` | Ordered sequence a fix lens follows: read, capture SHA, TDD, apply, validate, self-audit, commit, push, reply + resolve |
 | `gh-payloads.md` | How to build GitHub review and reply payloads via MCP tools; describes the one-review-per-loop pattern |
 | `state-schema.md` | Fields each PR-loop workflow tracks across iterations; documents common fields and per-skill extensions |

package/_shared/pr-loop/audit-contract.md

@@ -120,7 +120,7 @@ Sequence:
 2. Apply edits.
 3. Run `py_compile` (or language-equivalent) on each modified file.
 4. Compute `fix_diff` against pre-fix contents for the modified set.
-5. Run `bugteam_code_rules_gate.py` with explicit paths for every modified file.
+5. Run `_shared/pr-loop/scripts/code_rules_gate.py` with explicit paths for every modified file.
 6. Spawn a scoped audit of `fix_diff` with full A–P rigor, Shape A/B contract, adversarial pass, AND Haiku secondary in parallel (paranoid mode on post-fix).
 7. Read the previous loop's outcome XML (`<worktree_path>/.bugteam-pr<N>-loop<L-1>.outcomes.xml`) and obtain its total finding count. If this is the first loop (L <= 1) or the file does not exist, skip this comparison. Compute the post-fix total: previous total minus bugs fixed in this round plus new violations found in the post-fix audit (step 6). If the post-fix total exceeds the previous total, flag all new findings as same-loop fix-targets and revise. An increase in total findings across loop transitions is a regression.
 8. Any new findings become same-loop fix-targets. Internal iteration count increments by one.

package/_shared/pr-loop/gh-payloads.md

@@ -55,9 +55,9 @@ user-facing output (chat reply to the user) rather than in the PR review body.
 
 ## Review POST failure
 
-There is no fallback path. `post_audit_thread.py` exits `2` on retry
-exhaustion (four non-2xx responses across the built-in `1s / 4s / 16s` backoff)
-and the orchestrator halts with `error: post_audit_thread retry exhausted`.
+There is no fallback payload to build. On retry exhaustion
+`post_audit_thread.py` exits `2` and the orchestrator halts — see
+[`./post-audit-thread-contract.md`](./post-audit-thread-contract.md) § Exit codes.
 A hard blocker on the audit-posting path is a halt condition, not a degraded
 flat-issue-comment fall-through.
 

package/_shared/pr-loop/post-audit-thread-contract.md

@@ -0,0 +1,51 @@
+# post_audit_thread.py invocation contract
+
+Single source of truth for how every PR-loop caller runs
+[`scripts/post_audit_thread.py`](scripts/post_audit_thread.py) to post one
+audit review per pass. The script posts an `APPROVE` review on `CLEAN` (an
+empty findings list, zero inline comments) and a `REQUEST_CHANGES` review on
+`DIRTY` (one inline anchored comment per finding). It reads its body skeleton
+from [`audit-reply-template.md`](audit-reply-template.md) at runtime.
+
+## Invocation
+
+```
+python "<pr-loop-scripts>/post_audit_thread.py" \
+  --skill <caller> \
+  --owner <owner> \
+  --repo <repo> \
+  --pr-number <N> \
+  --commit <head_sha> \
+  --state <CLEAN|DIRTY> \
+  --findings-json <path>
+```
+
+Capture `<head_sha>` with `git rev-parse HEAD` in the caller's cwd right before
+the call, so the review attaches to the commit the audit scoped. `--findings-json`
+points to a JSON file whose root is a list; on `CLEAN` the list is empty (`[]`).
+
+## Exit codes
+
+The script retries on its own with 1s / 4s / 16s backoff across four tries (one
+plus three retries). It then exits:
+
+| Exit | Meaning |
+|---|---|
+| `0` | Review posted. The new review's `html_url` is on stdout. |
+| `1` | User input error: bad arguments, malformed findings JSON, or a missing template. |
+| `2` | Retry exhaustion: every try failed. |
+
+## Per-caller policy
+
+The same exit codes carry different weight per caller:
+
+- **bugteam** — an exit `2` is a hard blocker. The lead exits with
+  `error: post_audit_thread retry exhausted`, and does not retry or fall back to
+  a flat issue comment.
+- **autoconverge clean-audit** — any post that does not land (a denied post, an
+  error, or an agent that never ran) is a recorded bypass, not a blocker. Every
+  review lens already cleared the HEAD, so the CLEAN post is a record-keeping
+  artifact. The run records a bypass note, sets the convergence check's
+  `--bugteam-post-blocked` flag, and proceeds to the terminal Bugbot gate. Full
+  policy: [`../../skills/autoconverge/reference/stop-conditions.md`](../../skills/autoconverge/reference/stop-conditions.md)
+  § "Clean-audit post bypassed".

package/_shared/pr-loop/scripts/README.md

@@ -9,11 +9,11 @@ Runnable helpers used by **bugteam**, **qbug**, **pr-converge**, and related ski
 | `preflight.py` | Local checks before a PR-loop run (pytest discovery, optional pre-commit, hooksPath sanity). |
 | `reviewer_availability.py` | Unified availability check for Copilot and Bugbot; reuses `copilot_quota.py` and `reviews_disabled.py` and exits 0 when the named `--reviewer` may be spawned. |
 | `code_rules_gate.py` | CODE_RULES gate over PR-scoped diffs (`--base`, staged-only, path filters). |
-| `fix_hookspath.py` | Repair `core.hooksPath` when it does not point at the packaged git-hooks tree. |
+| `fix_hookspath.py` | Repair `core.hooksPath` when it does not point at the packaged git-hooks tree. Single home for unexpected non-empty git stderr (hard-fail `RuntimeError`); skill wrappers may call it later. |
 | `grant_project_claude_permissions.py` / `revoke_project_claude_permissions.py` | Claude Code permission JSON helpers used during publish-style flows. |
 | `_claude_permissions_common.py` | Shared implementation for the permission scripts. |
 
-Configuration lives under `config/` next to these scripts (for example `preflight_constants.py`, `code_rules_gate_constants.py`).
+Configuration lives under `pr_loop_shared_constants/` next to these scripts (for example `preflight_constants.py`, `code_rules_gate_constants.py`, `fix_hookspath_constants.py`).
 
 ## Gate semantics
 

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

@@ -28,6 +28,7 @@ from pr_loop_shared_constants.code_rules_gate_constants import (  # noqa: E402
     BANNED_NOUN_VIOLATION_PATTERN,
     CODE_RULES_GATE_PYTHON_ENV_VAR,
     CODE_RULES_GATE_PYTHONPATH_ENV_VAR,
+    COMMAND_LINE_ARGUMENT_SEPARATOR_LENGTH,
     DUPLICATE_BODY_DEFINITION_LINE_GROUP_INDEX,
     DUPLICATE_BODY_SPAN_GROUP_INDEX,
     DUPLICATE_BODY_VIOLATION_PATTERN,
@@ -41,6 +42,7 @@ from pr_loop_shared_constants.code_rules_gate_constants import (  # noqa: E402
     ISOLATION_DEFINITION_LINE_GROUP_INDEX,
     ISOLATION_SPAN_GROUP_INDEX,
     ISOLATION_VIOLATION_PATTERN,
+    MAXIMUM_STAGED_PYTEST_COMMAND_LINE_CHARACTERS,
     MAX_VIOLATIONS_PER_CHECK,
     MINIMUM_STAGED_PYTEST_PYTHON_MAJOR,
     MINIMUM_STAGED_PYTEST_PYTHON_MINOR,
@@ -1710,11 +1712,114 @@ def _staged_pytest_environment() -> dict[str, str]:
     return environment
 
 
+def _relative_pytest_argument(test_path: Path, group_root: Path) -> str:
+    """Express *test_path* as a pytest argument relative to *group_root*.
+
+    *group_root* is already the pytest working directory, so the relative form
+    names the same file in far fewer characters.
+
+    Example::
+
+        group_root = C:/repo/package
+        ok:   C:/repo/package/tests/test_a.py -> "tests/test_a.py"
+        flag: C:/elsewhere/test_b.py         -> no relative form; passed absolute
+
+    Args:
+        test_path: The staged test file to express as a pytest argument.
+        group_root: The pytest working directory for the group.
+
+    Returns:
+        The path relative to *group_root* when *test_path* sits under it,
+        otherwise the absolute path unchanged.
+    """
+    try:
+        return str(test_path.relative_to(group_root))
+    except ValueError:
+        return str(test_path)
+
+
+def _batched_pytest_arguments(
+    all_pytest_arguments: list[str], character_budget: int
+) -> list[list[str]]:
+    """Split pytest path arguments into command-line-length-safe batches.
+
+    Windows rejects a command line past 32767 characters with WinError 206, so a
+    large staged set passed in one invocation crashes the gate and denies the
+    commit. Each batch takes arguments until the next one would push its joined
+    length past *character_budget*.
+
+    Example::
+
+        character_budget = 10
+        arguments        = ["aaaa", "bbbb", "cccc"]
+        ok:   [["aaaa", "bbbb"], ["cccc"]]  - every batch within budget
+        flag: [["aaaa", "bbbb", "cccc"]]    - 14 characters, over budget
+
+    Args:
+        all_pytest_arguments: The path arguments to distribute, in order.
+        character_budget: The joined length each batch must stay within. An
+            argument wider than the budget on its own still lands in a batch
+            by itself, so no argument is ever dropped.
+
+    Returns:
+        One argument list per pytest invocation, preserving input order.
+    """
+    all_batches: list[list[str]] = []
+    current_batch: list[str] = []
+    current_length = 0
+    for each_argument in all_pytest_arguments:
+        argument_length = len(each_argument) + COMMAND_LINE_ARGUMENT_SEPARATOR_LENGTH
+        if current_batch and current_length + argument_length > character_budget:
+            all_batches.append(current_batch)
+            current_batch = []
+            current_length = 0
+        current_batch.append(each_argument)
+        current_length += argument_length
+    if current_batch:
+        all_batches.append(current_batch)
+    return all_batches
+
+
+def _pytest_batch_exit_code(all_batch_command: list[str], group_root: Path) -> int:
+    """Run one pytest invocation and normalize its exit code.
+
+    Args:
+        all_batch_command: The full argv for this pytest invocation.
+        group_root: The owning test root used as the working directory.
+
+    Returns:
+        0 when the batch passes or collects no tests; pytest's non-zero exit
+        code otherwise.
+    """
+    pytest_process = subprocess.run(
+        all_batch_command,
+        cwd=str(group_root),
+        timeout=STAGED_PYTEST_TIMEOUT_SECONDS,
+        check=False,
+        env=_staged_pytest_environment(),
+    )
+    if pytest_process.returncode == PYTEST_NO_TESTS_COLLECTED_EXIT_CODE:
+        return 0
+    return pytest_process.returncode
+
+
 def _run_pytest_for_group(
     group_root: Path, all_group_test_paths: list[Path], repository_root: Path
 ) -> int:
     """Run pytest over one group's test files with the working directory at its root.
 
+    Paths are passed relative to *group_root* (the subprocess working directory)
+    and split into batches whose joined command line stays within
+    ``MAXIMUM_STAGED_PYTEST_COMMAND_LINE_CHARACTERS``, so a large staged set never
+    trips the Windows 32767-character limit. A staged set that fits the budget runs
+    as one invocation, exactly as an unbatched run did.
+
+    Example::
+
+        ok:   3 staged tests   -> 1 pytest invocation, argv well under the budget
+        flag: 800 staged tests -> 1 pytest invocation, argv over the Windows limit
+                                  (WinError 206); batching splits it across several
+
     Args:
         group_root: The owning test root used as the pytest working directory.
         all_group_test_paths: The staged test files that share *group_root*.
@@ -1722,23 +1827,32 @@ def _run_pytest_for_group(
             interpreter when ``CODE_RULES_GATE_PYTHON`` is not set.
 
     Returns:
-        0 when the group's tests pass or collect nothing; pytest's non-zero
-        exit code otherwise.
+        0 when every batch passes or collects nothing; the first failing batch's
+        non-zero pytest exit code otherwise.
     """
-    pytest_process = subprocess.run(
+    all_fixed_command = [
+        _resolve_gate_python_executable(repository_root),
+        *ALL_PYTEST_MODULE_INVOCATION,
+    ]
+    fixed_command_length = sum(
+        len(each_part) + COMMAND_LINE_ARGUMENT_SEPARATOR_LENGTH
+        for each_part in all_fixed_command
+    )
+    all_batches = _batched_pytest_arguments(
         [
-            _resolve_gate_python_executable(repository_root),
-            *ALL_PYTEST_MODULE_INVOCATION,
-            *[str(each_path) for each_path in all_group_test_paths],
+            _relative_pytest_argument(each_path, group_root)
+            for each_path in all_group_test_paths
         ],
-        cwd=str(group_root),
-        timeout=STAGED_PYTEST_TIMEOUT_SECONDS,
-        check=False,
-        env=_staged_pytest_environment(),
+        MAXIMUM_STAGED_PYTEST_COMMAND_LINE_CHARACTERS - fixed_command_length,
     )
-    if pytest_process.returncode == PYTEST_NO_TESTS_COLLECTED_EXIT_CODE:
-        return 0
-    return pytest_process.returncode
+    first_failing_exit_code = 0
+    for each_batch in all_batches:
+        batch_exit_code = _pytest_batch_exit_code(
+            [*all_fixed_command, *each_batch], group_root
+        )
+        if batch_exit_code != 0 and first_failing_exit_code == 0:
+            first_failing_exit_code = batch_exit_code
+    return first_failing_exit_code
 
 
 def run_staged_test_files(repository_root: Path) -> int:

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

@@ -53,6 +53,9 @@ def list_local_core_hooks_path_values(
     Returns:
         Non-empty stripped values from ``git config --local --get-all``, or
         an empty list when no values are configured.
+
+    Raises:
+        RuntimeError: When git exits non-zero with a non-empty stderr diagnostic.
     """
     git_command = [
         "git",
@@ -75,11 +78,9 @@ def list_local_core_hooks_path_values(
     if completed_process.returncode != 0:
         diagnostic_stderr = completed_process.stderr.strip()
         if diagnostic_stderr:
-            print(
-                "fix_hookspath: git read of local core.hooksPath on "
-                f"{repository_root} exited {completed_process.returncode}: "
-                f"{diagnostic_stderr}",
-                file=sys.stderr,
+            raise RuntimeError(
+                f"git read of local core.hooksPath on {repository_root} "
+                f"exited {completed_process.returncode}: {diagnostic_stderr}"
             )
         return []
     return [
@@ -99,8 +100,11 @@ def read_global_core_hooks_path(
             forwarded to ``subprocess.run``.
 
     Returns:
-        The stripped global value, or an empty string when unset or when git
-        returns non-zero.
+        The stripped global value, or an empty string when the key is unset
+        (git exits non-zero with empty stderr).
+
+    Raises:
+        RuntimeError: When git exits non-zero with a non-empty stderr diagnostic.
     """
     git_command = list(ALL_GIT_GLOBAL_GET_CORE_HOOKS_PATH_COMMAND)
     completed_process = subprocess.run(
@@ -115,10 +119,9 @@ def read_global_core_hooks_path(
     if completed_process.returncode != 0:
         diagnostic_stderr = completed_process.stderr.strip()
         if diagnostic_stderr:
-            print(
-                "fix_hookspath: git read of global core.hooksPath exited "
-                f"{completed_process.returncode}: {diagnostic_stderr}",
-                file=sys.stderr,
+            raise RuntimeError(
+                f"git read of global core.hooksPath exited "
+                f"{completed_process.returncode}: {diagnostic_stderr}"
             )
         return ""
     return completed_process.stdout.strip()
@@ -280,7 +283,8 @@ def main(
             forwarded to every git invocation and to the preflight rerun.
 
     Returns:
-        Zero on success. Non-zero on the first failing git command or on a
+        Zero on success. Non-zero on the first failing git command, on a
+        hard-fail git stderr diagnostic (caught ``RuntimeError``), or on a
         non-zero preflight rerun exit code.
     """
     arguments = parse_arguments(all_arguments)
@@ -302,6 +306,37 @@ def main(
             file=sys.stderr,
         )
         return 1
+    try:
+        return _repair_hooks_path_then_rerun_preflight(
+            repository_root=repository_root,
+            canonical_hooks_directory=canonical_hooks_directory,
+            all_environment_overrides=all_environment_overrides,
+        )
+    except RuntimeError as runtime_error:
+        print(f"fix_hookspath: {runtime_error}", file=sys.stderr)
+        return 1
+
+
+def _repair_hooks_path_then_rerun_preflight(
+    repository_root: Path,
+    canonical_hooks_directory: Path,
+    all_environment_overrides: dict[str, str] | None,
+) -> int:
+    """Apply local/global hooksPath repairs, then re-run preflight.
+
+    Args:
+        repository_root: Repository root used for local git config and preflight.
+        canonical_hooks_directory: Absolute path to the packaged git-hooks tree.
+        all_environment_overrides: Optional environment variable mapping
+            forwarded to every git invocation and to the preflight rerun.
+
+    Returns:
+        Zero on success. Non-zero on the first failing git write or on a
+        non-zero preflight rerun exit code.
+
+    Raises:
+        RuntimeError: When a git read exits non-zero with non-empty stderr.
+    """
     local_hooks_path_values = list_local_core_hooks_path_values(
         repository_root,
         all_environment_overrides,

package/_shared/pr-loop/scripts/pr_loop_shared_constants/code_rules_gate_constants.py

@@ -102,6 +102,10 @@ ALL_POSIX_VENV_PYTHON_RELATIVE_PATH_SEGMENTS: tuple[str, ...] = ("bin", "python"
 
 STAGED_PYTEST_TIMEOUT_SECONDS: int = 600
 
+MAXIMUM_STAGED_PYTEST_COMMAND_LINE_CHARACTERS: int = 24000
+
+COMMAND_LINE_ARGUMENT_SEPARATOR_LENGTH: int = 1
+
 STAGED_TEST_FAILURE_HEADER: str = (
     "code_rules_gate: staged test file(s) failed under pytest; commit blocked."
 )

package/_shared/pr-loop/scripts/tests/test_code_rules_gate.py

@@ -483,16 +483,11 @@ def test_check_wrapper_plumb_through_exempts_test_files() -> None:
         "    return _helper('a', clean_name='b')\n"
     )
     shared_issues = gate_module.check_wrapper_plumb_through(source, "pkg/test_thing.py")
-    bugteam_gate = _load_bugteam_gate_module()
-    bugteam_issues = bugteam_gate.check_wrapper_plumb_through(source, "pkg/test_thing.py")
     assert shared_issues == [], (
         "a test_* function in a test-file path that calls a module-level helper "
         "exposing an optional kwarg is not a wrapper; the shared gate must exempt "
         "test files and emit zero findings"
     )
-    assert bugteam_issues == [], (
-        "the bugteam gate copy must apply the identical test-file exemption"
-    )
 
 
 def test_check_wrapper_plumb_through_still_flags_non_test_path_with_test_shape() -> None:
@@ -1245,8 +1240,6 @@ def test_check_wrapper_plumb_through_dedupes_nested_public_function_calls() -> N
     assert len(issues) == 1, f"expected 1 finding, got {len(issues)}: {issues!r}"
 
 
-
-
 def test_check_wrapper_plumb_through_ignores_calls_nested_inside_delegate_arguments() -> None:
     """Regression: nested callees inside another call's arguments are not wrapper sites.
 
@@ -1766,68 +1759,6 @@ def test_main_blocks_banned_noun_on_added_lines_past_document_order(
     )
 
 
-def _load_bugteam_gate_module() -> ModuleType:
-    bugteam_scripts_dir = (
-        Path(__file__).resolve().parents[4]
-        / "skills"
-        / "bugteam"
-        / "scripts"
-    )
-    if str(bugteam_scripts_dir) not in sys.path:
-        sys.path.insert(0, str(bugteam_scripts_dir))
-    module_path = bugteam_scripts_dir / "bugteam_code_rules_gate.py"
-    spec = importlib.util.spec_from_file_location("bugteam_code_rules_gate", module_path)
-    assert spec is not None
-    assert spec.loader is not None
-    module = importlib.util.module_from_spec(spec)
-    spec.loader.exec_module(module)
-    return module
-
-
-def test_both_gates_classify_wrapper_plumb_through_identically() -> None:
-    """The bugteam and _shared gate copies of check_wrapper_plumb_through must
-    return identical findings. A class method calling a module-level delegate
-    is not a wrapper; both gates must exclude it rather than one emitting a
-    false positive the other does not."""
-    bugteam_gate = _load_bugteam_gate_module()
-    class_method_calling_delegate = (
-        "def fetch(target, *, retries=3):\n"
-        "    return target\n"
-        "\n"
-        "class MyService:\n"
-        "    def public_method(self, target):\n"
-        "        return fetch(target)\n"
-    )
-    nested_call_inside_delegate_argument = (
-        "def delegate(value, *, retries=3):\n"
-        "    return value\n"
-        "\n"
-        "def helper(value):\n"
-        "    return value\n"
-        "\n"
-        "def public_caller(value):\n"
-        "    return delegate(helper(value))\n"
-    )
-    name_call_dropping_kwarg = (
-        "def delegate(value, *, retries=3):\n"
-        "    return value\n"
-        "\n"
-        "def public_wrapper(value):\n"
-        "    return delegate(value)\n"
-    )
-    for each_source in (
-        class_method_calling_delegate,
-        nested_call_inside_delegate_argument,
-        name_call_dropping_kwarg,
-    ):
-        shared_issues = gate_module.check_wrapper_plumb_through(each_source, "module.py")
-        bugteam_issues = bugteam_gate.check_wrapper_plumb_through(each_source, "module.py")
-        assert shared_issues == bugteam_issues, (
-            "both gate copies of check_wrapper_plumb_through must classify "
-            f"identically; shared={shared_issues!r} bugteam={bugteam_issues!r}"
-        )
-
-
 def test_check_wrapper_plumb_through_stays_under_function_length_threshold() -> None:
     """check_wrapper_plumb_through must stay under the enforcer's function-length
     blocking threshold so editing it (e.g. aligning the two gate copies) does
@@ -2722,3 +2653,149 @@ def test_staged_pytest_environment_prepends_configured_pythonpath(
     assert environment["PYTHONPATH"] == os.pathsep.join(
         ["/configured/site-packages", "/already/on/path"]
     )
+
+
+def _record_pytest_invocations(
+    monkeypatch: pytest.MonkeyPatch, *, all_exit_codes: list[int]
+) -> list[list[str]]:
+    """Patch subprocess.run to record each pytest argv and return staged exit codes."""
+    all_recorded_commands: list[list[str]] = []
+    all_remaining_exit_codes = list(all_exit_codes)
+
+    def _fake_subprocess_run(
+        all_command: list[str], **_keyword_arguments: object
+    ) -> subprocess.CompletedProcess[bytes]:
+        all_recorded_commands.append(list(all_command))
+        exit_code = all_remaining_exit_codes.pop(0) if all_remaining_exit_codes else 0
+        return subprocess.CompletedProcess(all_command, exit_code, b"", b"")
+
+    monkeypatch.setattr(gate_module.subprocess, "run", _fake_subprocess_run)
+    return all_recorded_commands
+
+
+def _staged_test_paths_under(group_root: Path, path_count: int) -> list[Path]:
+    return [
+        group_root
+        / "tests"
+        / "subpackage_with_a_realistically_long_directory_name"
+        / f"test_module_with_a_realistically_long_name_{each_index:04d}.py"
+        for each_index in range(path_count)
+    ]
+
+
+def _path_arguments_of(all_pytest_command: list[str]) -> list[str]:
+    fixed_prefix_length = len(gate_module.ALL_PYTEST_MODULE_INVOCATION) + 1
+    return all_pytest_command[fixed_prefix_length:]
+
+
+def test_run_pytest_for_group_batches_a_large_staged_set_under_the_budget(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """WinError 206: a staged set whose joined argv passes Windows' 32767-character
+    command-line limit crashed the gate and denied the commit. The paths must be
+    split across several pytest invocations, none of them over the budget.
+    """
+    all_recorded_commands = _record_pytest_invocations(monkeypatch, all_exit_codes=[])
+    all_test_paths = _staged_test_paths_under(tmp_path, 800)
+
+    exit_code = gate_module._run_pytest_for_group(tmp_path, all_test_paths, tmp_path)
+
+    assert exit_code == 0
+    assert len(all_recorded_commands) > 1, (
+        "a staged set wider than the command-line budget must be split across "
+        "several pytest invocations rather than passed in one oversized argv"
+    )
+    for each_command in all_recorded_commands:
+        assert (
+            len(" ".join(each_command))
+            <= gate_module.MAXIMUM_STAGED_PYTEST_COMMAND_LINE_CHARACTERS
+        )
+    all_batched_arguments = [
+        each_argument
+        for each_command in all_recorded_commands
+        for each_argument in _path_arguments_of(each_command)
+    ]
+    assert len(all_batched_arguments) == len(all_test_paths)
+
+
+def test_run_pytest_for_group_passes_paths_relative_to_the_group_root(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """group_root is already the subprocess cwd, so each path argument is passed
+    relative to it - the shortening that keeps a large staged set under the limit.
+    """
+    all_recorded_commands = _record_pytest_invocations(monkeypatch, all_exit_codes=[])
+    test_path = tmp_path / "tests" / "test_relative.py"
+
+    gate_module._run_pytest_for_group(tmp_path, [test_path], tmp_path)
+
+    assert _path_arguments_of(all_recorded_commands[0]) == [
+        str(Path("tests") / "test_relative.py")
+    ]
+
+
+def test_run_pytest_for_group_passes_an_outside_path_absolute(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    all_recorded_commands = _record_pytest_invocations(monkeypatch, all_exit_codes=[])
+    group_root = tmp_path / "group"
+    outside_path = tmp_path / "elsewhere" / "test_outside.py"
+
+    gate_module._run_pytest_for_group(group_root, [outside_path], tmp_path)
+
+    assert _path_arguments_of(all_recorded_commands[0]) == [str(outside_path)]
+
+
+def test_run_pytest_for_group_runs_one_invocation_for_a_small_staged_set(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    all_recorded_commands = _record_pytest_invocations(monkeypatch, all_exit_codes=[])
+    all_test_paths = _staged_test_paths_under(tmp_path, 3)
+
+    exit_code = gate_module._run_pytest_for_group(tmp_path, all_test_paths, tmp_path)
+
+    assert exit_code == 0
+    assert len(all_recorded_commands) == 1, (
+        "a staged set that fits the budget must behave exactly as before: "
+        "one pytest invocation carrying every path"
+    )
+
+
+def test_run_pytest_for_group_surfaces_the_first_failing_batch_exit_code(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A failure in any batch must surface, and every batch must still run so the
+    operator sees the whole staged-test picture rather than the first failure alone.
+    """
+    all_recorded_commands = _record_pytest_invocations(
+        monkeypatch, all_exit_codes=[0, 1, 2]
+    )
+    all_test_paths = _staged_test_paths_under(tmp_path, 800)
+
+    exit_code = gate_module._run_pytest_for_group(tmp_path, all_test_paths, tmp_path)
+
+    assert exit_code == 1
+    assert len(all_recorded_commands) >= 3
+
+
+def test_run_pytest_for_group_treats_no_tests_collected_as_a_pass_per_batch(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _record_pytest_invocations(
+        monkeypatch,
+        all_exit_codes=[gate_module.PYTEST_NO_TESTS_COLLECTED_EXIT_CODE, 0],
+    )
+    all_test_paths = _staged_test_paths_under(tmp_path, 800)
+
+    exit_code = gate_module._run_pytest_for_group(tmp_path, all_test_paths, tmp_path)
+
+    assert exit_code == 0, (
+        "a batch that collects no tests is not a failure; only a real pytest "
+        "failure exit code may block the commit"
+    )