claude-dev-env 1.93.1 → 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/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/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