claude-dev-env 2.2.1 → 2.4.0

package/hooks/blocking/pr_description_proof_of_work.py

@@ -20,10 +20,11 @@ _hooks_dir = str(Path(__file__).resolve().parent.parent)
 if _hooks_dir not in sys.path:
     sys.path.insert(0, _hooks_dir)
 
-from blocking.pr_description_body_audit import _iter_section_headers  # noqa: E402
-from blocking.pr_description_pr_number import (  # noqa: E402
-    _extract_pr_number_from_command,
+from blocking.convergence_gate_blocker import (  # noqa: E402
+    _repo_flag_arguments,
+    _resolve_named_identity,
 )
+from blocking.pr_description_body_audit import _iter_section_headers  # noqa: E402
 from hooks_constants.pr_description_enforcer_constants import (  # noqa: E402
     BULLET_MARKER_PATTERN,
     FENCED_CODE_BLOCK_PATTERN,
@@ -32,7 +33,6 @@ from hooks_constants.pr_description_enforcer_constants import (  # noqa: E402
 from hooks_constants.pr_description_proof_of_work_constants import (  # noqa: E402
     ALL_HONEST_GAP_PHRASES,
     ALL_PR_DIFF_SUBCOMMANDS,
-    ALL_PR_VIEW_NUMBER_ARGUMENTS,
     ALL_PROOF_HEADING_KEYWORDS,
     ALL_VISUAL_FILE_SUFFIXES,
     COMMENT_BODY_JSON_FIELD,
@@ -49,7 +49,6 @@ from hooks_constants.pr_description_proof_of_work_constants import (  # noqa: E4
     PLAN_LINKAGE_KEYWORD_PATTERN,
     PR_COMMENTS_API_PATH_TEMPLATE,
     PR_DIFF_NAME_ONLY_FLAG,
-    PR_NUMBER_JSON_FIELD,
     PR_READY_GATE_MESSAGE_TEMPLATE,
     PR_READY_INVOCATION_PATTERN,
     PR_READY_UNDO_FLAG,
@@ -112,13 +111,18 @@ def audit_proof_comment_body(body: str, pr_number: int | None) -> list[str]:
         an honest-gaps statement, and (when the PR diff is visual) an
         image embed.
     """
-    is_visual_change = _detect_visual_change(pr_number)
+    is_visual_change = _detect_visual_change(pr_number, None)
     return _missing_proof_parts(body, is_visual_change)
 
 
 def evaluate_pr_ready_gate(command: str) -> str | None:
     """Decide whether a gh pr ready command may proceed.
 
+    Every gh read the gate runs binds to the repository the command names —
+    a full PR URL or a ``--repo``/``-R`` flag — so a command targeting one
+    repository from a working tree checked out to another audits the named
+    repository's PR, not the working tree's.
+
     Args:
         command: The raw shell command captured by the hook.
 
@@ -127,15 +131,14 @@ def evaluate_pr_ready_gate(command: str) -> str | None:
         carries no passing proof comment, or None when a passing proof
         comment exists or any gh query fails.
     """
-    resolved_pr_number = _extract_pr_number_from_command(command)
-    if resolved_pr_number is None:
-        resolved_pr_number = _resolve_current_pr_number()
-    if resolved_pr_number is None:
+    target_identity = _resolve_named_identity(command, None)
+    if target_identity is None:
         return None
-    all_comment_bodies = _fetch_pr_comment_bodies(resolved_pr_number)
+    all_target_repo, resolved_pr_number = target_identity
+    all_comment_bodies = _fetch_pr_comment_bodies(resolved_pr_number, all_target_repo)
     if all_comment_bodies is None:
         return None
-    is_visual_change = _detect_visual_change(resolved_pr_number)
+    is_visual_change = _detect_visual_change(resolved_pr_number, all_target_repo)
     for each_body in all_comment_bodies:
         if not is_proof_shaped_body(each_body):
             continue
@@ -173,29 +176,30 @@ def _run_gh_command(all_gh_arguments: list[str]) -> str | None:
     return completed_process.stdout
 
 
-def _resolve_current_pr_number() -> int | None:
-    """Resolve the PR number of the current branch's open PR.
+def _build_comments_api_path(pr_number: int, all_target_repo: tuple[str, str] | None) -> str:
+    """Build the issues-comments API path for the named repository's PR.
+
+    Args:
+        pr_number: The PR number whose comments to read.
+        all_target_repo: The (owner, repo) pair the command names, or None to
+            leave gh's ``{owner}``/``{repo}`` placeholders for gh to expand
+            from the current directory's repository.
 
     Returns:
-        The PR number from ``gh pr view``, or None when no PR resolves or
-        gh fails.
+        The ``repos/<owner>/<repo>/issues/<pr_number>/comments`` path with
+        the named owner and repo filled in, or the placeholder form when no
+        repository is named.
     """
-    view_stdout = _run_gh_command(list(ALL_PR_VIEW_NUMBER_ARGUMENTS))
-    if view_stdout is None:
-        return None
-    try:
-        view_record = json.loads(view_stdout)
-    except json.JSONDecodeError:
-        return None
-    if not isinstance(view_record, dict):
-        return None
-    resolved_number = view_record.get(PR_NUMBER_JSON_FIELD)
-    if isinstance(resolved_number, int):
-        return resolved_number
-    return None
+    comments_api_path = PR_COMMENTS_API_PATH_TEMPLATE.format(pr_number=pr_number)
+    if all_target_repo is None:
+        return comments_api_path
+    owner, repo = all_target_repo
+    return comments_api_path.format(owner=owner, repo=repo)
 
 
-def _fetch_pr_comment_bodies(pr_number: int) -> list[str] | None:
+def _fetch_pr_comment_bodies(
+    pr_number: int, all_target_repo: tuple[str, str] | None
+) -> list[str] | None:
     """Read every comment body on a PR through the paginated issues API.
 
     The query runs ``gh api --paginate --slurp`` so every page lands in one
@@ -204,13 +208,15 @@ def _fetch_pr_comment_bodies(pr_number: int) -> list[str] | None:
 
     Args:
         pr_number: The PR number whose comments to read.
+        all_target_repo: The (owner, repo) pair the command names, or None to
+            read the current directory's repository.
 
     Returns:
         The comment bodies across all pages, or None when gh fails or the
         output is not the slurped page-array shape — the caller fails open
         on None.
     """
-    comments_api_path = PR_COMMENTS_API_PATH_TEMPLATE.format(pr_number=pr_number)
+    comments_api_path = _build_comments_api_path(pr_number, all_target_repo)
     api_stdout = _run_gh_command(
         [GH_API_SUBCOMMAND, comments_api_path, GH_PAGINATE_FLAG, GH_SLURP_FLAG]
     )
@@ -232,7 +238,9 @@ def _fetch_pr_comment_bodies(pr_number: int) -> list[str] | None:
     return all_comment_bodies
 
 
-def _detect_visual_change(pr_number: int | None) -> bool:
+def _detect_visual_change(
+    pr_number: int | None, all_target_repo: tuple[str, str] | None
+) -> bool:
     """Decide whether the PR diff carries visual work.
 
     A diff is visual when a changed file carries an image, HTML, or
@@ -242,21 +250,31 @@ def _detect_visual_change(pr_number: int | None) -> bool:
     Args:
         pr_number: The PR number to diff, or None to diff the current
             branch's PR.
+        all_target_repo: The (owner, repo) pair the command names, or None to
+            diff the current directory's repository.
 
     Returns:
         True when the diff is visual; False when it is not or when any gh
         query fails — an unknowable diff never adds the visual requirement.
     """
     all_number_arguments = [str(pr_number)] if pr_number is not None else []
+    all_repo_arguments = _repo_flag_arguments(all_target_repo)
     name_only_stdout = _run_gh_command(
-        [*ALL_PR_DIFF_SUBCOMMANDS, *all_number_arguments, PR_DIFF_NAME_ONLY_FLAG]
+        [
+            *ALL_PR_DIFF_SUBCOMMANDS,
+            *all_number_arguments,
+            *all_repo_arguments,
+            PR_DIFF_NAME_ONLY_FLAG,
+        ]
     )
     if name_only_stdout is None:
         return False
     for each_changed_path in name_only_stdout.splitlines():
         if Path(each_changed_path.strip()).suffix.lower() in ALL_VISUAL_FILE_SUFFIXES:
             return True
-    diff_stdout = _run_gh_command([*ALL_PR_DIFF_SUBCOMMANDS, *all_number_arguments])
+    diff_stdout = _run_gh_command(
+        [*ALL_PR_DIFF_SUBCOMMANDS, *all_number_arguments, *all_repo_arguments]
+    )
     if diff_stdout is None:
         return False
     return HEX_COLOR_ADDED_LINE_PATTERN.search(diff_stdout[:MAX_DIFF_SCAN_CHARS]) is not None

package/hooks/blocking/test_bash_pre_tool_use_dispatcher.py

@@ -213,7 +213,7 @@ def test_additional_context_is_collected_from_deciding_hooks() -> None:
 
 
 def test_powershell_selects_the_three_shared_hooks() -> None:
-    """Selecting for PowerShell yields the three shared hooks in registration order."""
+    """Selecting for PowerShell yields the shared hooks in registration order."""
     powershell_paths = [
         each_entry.script_relative_path
         for each_entry in select_applicable_entries(POWERSHELL_TOOL_NAME)
@@ -222,6 +222,9 @@ def test_powershell_selects_the_three_shared_hooks() -> None:
         "blocking/pii_prevention_blocker.py",
         "blocking/verified_commit_gate.py",
         "blocking/verdict_directory_write_blocker.py",
+        "blocking/code_review_push_gate.py",
+        "blocking/code_review_pr_create_gate.py",
+        "blocking/code_review_stamp_directory_write_blocker.py",
     ]
 
 

package/hooks/blocking/test_code_review_enforcement_config_bootstrap.py

@@ -0,0 +1,62 @@
+"""Regression tests for the code-review enforcement constants bootstrap.
+
+These prove the shared constants module resolves to the sibling
+``config/code_review_enforcement_constants.py`` file even when a foreign
+``config`` package sits ahead of ``blocking`` on ``sys.path``, and that a
+registration a caller placed first is left untouched.
+"""
+
+import subprocess
+from collections.abc import Callable
+
+RunUnderConfigShadow = Callable[[str], subprocess.CompletedProcess[str]]
+
+
+def test_register_binds_dotted_name_to_sibling_constants_file(
+    run_under_config_shadow: RunUnderConfigShadow,
+) -> None:
+    completed_probe = run_under_config_shadow(
+        "import code_review_enforcement_config_bootstrap as bootstrap\n"
+        "bootstrap.register_code_review_enforcement_constants()\n"
+        "import config.code_review_enforcement_constants as loaded\n"
+        "print(loaded.__file__)\n"
+        "print(loaded.STAMP_DIRECTORY_NAME)\n"
+    )
+    assert completed_probe.returncode == 0, completed_probe.stderr
+    assert "IS_DECOY_CONFIG" not in completed_probe.stdout
+    resolved_file_line, stamp_directory_line = completed_probe.stdout.splitlines()[:2]
+    assert resolved_file_line.replace("\\", "/").endswith(
+        "blocking/config/code_review_enforcement_constants.py"
+    )
+    assert stamp_directory_line == "code-review-stamps"
+
+
+def test_register_binds_push_required_effort(
+    run_under_config_shadow: RunUnderConfigShadow,
+) -> None:
+    completed_probe = run_under_config_shadow(
+        "import code_review_enforcement_config_bootstrap as bootstrap\n"
+        "bootstrap.register_code_review_enforcement_constants()\n"
+        "import config.code_review_enforcement_constants as loaded\n"
+        "print(loaded.PUSH_REQUIRED_EFFORT)\n"
+    )
+    assert completed_probe.returncode == 0, completed_probe.stderr
+    assert completed_probe.stdout.strip().splitlines()[-1] == "low"
+
+
+def test_register_leaves_an_already_cached_module_untouched(
+    run_under_config_shadow: RunUnderConfigShadow,
+) -> None:
+    completed_probe = run_under_config_shadow(
+        "import sys\n"
+        "import types\n"
+        "sentinel = types.ModuleType('config.code_review_enforcement_constants')\n"
+        "sentinel.ORIGIN = 'caller-seeded'\n"
+        "sys.modules['config.code_review_enforcement_constants'] = sentinel\n"
+        "import code_review_enforcement_config_bootstrap as bootstrap\n"
+        "bootstrap.register_code_review_enforcement_constants()\n"
+        "import config.code_review_enforcement_constants as loaded\n"
+        "print(getattr(loaded, 'ORIGIN', 'displaced'))\n"
+    )
+    assert completed_probe.returncode == 0, completed_probe.stderr
+    assert completed_probe.stdout.strip().splitlines()[-1] == "caller-seeded"

package/hooks/blocking/test_code_review_gate_deny.py

@@ -0,0 +1,54 @@
+"""Behavioral tests for the shared code-review gate deny scaffold.
+
+The tests drive the two shared helpers directly: the payload builder's shape and
+the log-and-emit helper's stdout, so both code-review gates inherit one verified
+deny path.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import sys
+from pathlib import Path
+from types import ModuleType
+
+import pytest
+
+_HOOK_DIR = Path(__file__).resolve().parent
+if str(_HOOK_DIR) not in sys.path:
+    sys.path.insert(0, str(_HOOK_DIR))
+
+
+def _load_module(module_name: str) -> ModuleType:
+    module_spec = importlib.util.spec_from_file_location(
+        module_name, _HOOK_DIR / f"{module_name}.py"
+    )
+    assert module_spec is not None
+    assert module_spec.loader is not None
+    loaded_module = importlib.util.module_from_spec(module_spec)
+    module_spec.loader.exec_module(loaded_module)
+    return loaded_module
+
+
+deny_module = _load_module("code_review_gate_deny")
+
+
+def test_build_payload_carries_reason_and_deny_decision() -> None:
+    deny_payload = deny_module.build_code_review_deny_payload("blocked reason")
+    hook_output = deny_payload["hookSpecificOutput"]
+    assert hook_output["permissionDecision"] == "deny"
+    assert hook_output["permissionDecisionReason"] == "blocked reason"
+
+
+def test_log_and_emit_code_review_deny_writes_payload_to_stdout(
+    capsys: pytest.CaptureFixture[str],
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    monkeypatch.setattr(Path, "home", lambda: tmp_path)
+    deny_module.log_and_emit_code_review_deny("blocked reason", "Bash", "code_review_push_gate")
+    emitted_payload = json.loads(capsys.readouterr().out)
+    hook_output = emitted_payload["hookSpecificOutput"]
+    assert hook_output["permissionDecision"] == "deny"
+    assert hook_output["permissionDecisionReason"] == "blocked reason"

package/hooks/blocking/test_code_review_pr_create_gate.py

@@ -0,0 +1,185 @@
+"""Behavioral tests for the PR-create code-review gate.
+
+Each test drives the gate against a real git work tree with a change surface
+and a real stamp store under an isolated home, so the deny/allow decision runs
+the same hash-and-coverage path the hook runs in production.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import subprocess
+import sys
+from pathlib import Path
+from types import ModuleType
+
+import pytest
+
+_HOOK_DIR = Path(__file__).resolve().parent
+if str(_HOOK_DIR) not in sys.path:
+    sys.path.insert(0, str(_HOOK_DIR))
+
+GIT_TIMEOUT_SECONDS = 30
+XHIGH_EFFORT = "xhigh"
+LOW_EFFORT = "low"
+SURFACE_SOURCE = "def add(a: int, b: int) -> int:\n    return a + b\n"
+SURFACE_CHANGE = "def add(a: int, b: int) -> int:\n    return a - b\n"
+MCP_CREATE_PR_TOOL = "mcp__plugin_github_github__create_pull_request"
+
+
+def _load_module(module_name: str) -> ModuleType:
+    module_spec = importlib.util.spec_from_file_location(
+        module_name, _HOOK_DIR / f"{module_name}.py"
+    )
+    assert module_spec is not None
+    assert module_spec.loader is not None
+    loaded_module = importlib.util.module_from_spec(module_spec)
+    module_spec.loader.exec_module(loaded_module)
+    return loaded_module
+
+
+gate_module = _load_module("code_review_pr_create_gate")
+store_module = _load_module("code_review_stamp_store")
+deny_module = _load_module("code_review_gate_deny")
+
+
+def _run_git(repository_directory: Path, *git_arguments: str) -> None:
+    subprocess.run(
+        ["git", "-C", str(repository_directory), *git_arguments],
+        check=True,
+        capture_output=True,
+        text=True,
+        timeout=GIT_TIMEOUT_SECONDS,
+    )
+
+
+def _make_repo_with_change_surface(tmp_path: Path) -> Path:
+    origin_directory = tmp_path / "origin.git"
+    work_directory = tmp_path / "work"
+    work_directory.mkdir()
+    subprocess.run(
+        ["git", "init", "--bare", "--initial-branch=main", str(origin_directory)],
+        check=True,
+        capture_output=True,
+        text=True,
+        timeout=GIT_TIMEOUT_SECONDS,
+    )
+    _run_git(work_directory, "init", "--initial-branch=main")
+    _run_git(work_directory, "config", "user.email", "tests@example.com")
+    _run_git(work_directory, "config", "user.name", "Reviewer")
+    (work_directory / "app.py").write_text(SURFACE_SOURCE, encoding="utf-8")
+    _run_git(work_directory, "add", "-A")
+    _run_git(work_directory, "commit", "-m", "base")
+    _run_git(work_directory, "remote", "add", "origin", str(origin_directory))
+    _run_git(work_directory, "push", "-u", "origin", "main")
+    (work_directory / "app.py").write_text(SURFACE_CHANGE, encoding="utf-8")
+    return work_directory
+
+
+def _isolate_home(monkeypatch: pytest.MonkeyPatch, fake_home: Path) -> None:
+    home_text = str(fake_home)
+    monkeypatch.setenv("HOME", home_text)
+    monkeypatch.setenv("USERPROFILE", home_text)
+    monkeypatch.delenv("HOMEDRIVE", raising=False)
+    monkeypatch.delenv("HOMEPATH", raising=False)
+
+
+def _prepared_repo(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> Path:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    _isolate_home(monkeypatch, fake_home)
+    return _make_repo_with_change_surface(tmp_path)
+
+
+def _record_stamp(work_directory: Path, effort: str) -> None:
+    surface_hash = store_module.live_surface_hash(str(work_directory))
+    assert surface_hash is not None
+    store_module.record_clean_stamp(str(work_directory), surface_hash, effort)
+
+
+def test_command_invokes_gh_pr_create_detects_real_invocation() -> None:
+    assert gate_module.command_invokes_gh_pr_create("gh pr create --title T --body-file b.md")
+
+
+def test_gh_pr_edit_is_not_a_create() -> None:
+    assert not gate_module.command_invokes_gh_pr_create("gh pr edit 1 --title T")
+
+
+def test_echoed_prose_is_not_a_create() -> None:
+    assert not gate_module.command_invokes_gh_pr_create('echo "gh pr create"')
+
+
+def test_is_mcp_create_pull_request_tool_matches_configured_name() -> None:
+    assert gate_module.is_mcp_create_pull_request_tool(MCP_CREATE_PR_TOOL)
+    assert not gate_module.is_mcp_create_pull_request_tool("Bash")
+
+
+def test_uncovered_surface_denies_pr_create(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    work_directory = _prepared_repo(monkeypatch, tmp_path)
+    deny_reason = gate_module.deny_reason_for_directory(str(work_directory))
+    assert deny_reason is not None
+    assert "PR_CREATE_GATE" in deny_reason
+
+
+def test_covering_xhigh_stamp_allows_pr_create(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    work_directory = _prepared_repo(monkeypatch, tmp_path)
+    _record_stamp(work_directory, XHIGH_EFFORT)
+    assert gate_module.deny_reason_for_directory(str(work_directory)) is None
+
+
+def test_low_only_stamp_does_not_satisfy_xhigh(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    work_directory = _prepared_repo(monkeypatch, tmp_path)
+    _record_stamp(work_directory, LOW_EFFORT)
+    deny_reason = gate_module.deny_reason_for_directory(str(work_directory))
+    assert deny_reason is not None
+    assert "PR_CREATE_GATE" in deny_reason
+
+
+def test_shell_gh_pr_create_payload_denies_without_stamp(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    work_directory = _prepared_repo(monkeypatch, tmp_path)
+    payload = {
+        "tool_name": "Bash",
+        "tool_input": {"command": "gh pr create --title T --body-file b.md"},
+        "cwd": str(work_directory),
+    }
+    deny_decision = gate_module.decision_for_payload(payload)
+    assert deny_decision is not None
+    assert deny_decision["hookSpecificOutput"]["permissionDecision"] == "deny"
+
+
+def test_mcp_create_pull_request_payload_denies_without_stamp(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    work_directory = _prepared_repo(monkeypatch, tmp_path)
+    payload = {
+        "tool_name": MCP_CREATE_PR_TOOL,
+        "tool_input": {"owner": "o", "repo": "r"},
+        "cwd": str(work_directory),
+    }
+    deny_decision = gate_module.decision_for_payload(payload)
+    assert deny_decision is not None
+    assert deny_decision["hookSpecificOutput"]["permissionDecision"] == "deny"
+
+
+def test_gh_pr_edit_payload_is_not_denied(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    work_directory = _prepared_repo(monkeypatch, tmp_path)
+    payload = {
+        "tool_name": "Bash",
+        "tool_input": {"command": "gh pr edit 1 --title T"},
+        "cwd": str(work_directory),
+    }
+    assert gate_module.decision_for_payload(payload) is None
+
+
+def test_build_deny_payload_shape() -> None:
+    deny_payload = deny_module.build_code_review_deny_payload("blocked reason")
+    assert deny_payload["hookSpecificOutput"]["permissionDecision"] == "deny"
+    assert deny_payload["hookSpecificOutput"]["permissionDecisionReason"] == "blocked reason"