claude-dev-env 8.77.0 → 8.78.1

package/.agents/skills/pr-lifecycle/SKILL.md

@@ -298,7 +298,7 @@ Three things stay with the owner, and nothing else does:
 - A change the owner said they want to read first.
 - A repository whose branch rule requires an approving review the agent cannot give.
 
-Where the branch rule requires zero approvals and one status check, that check is the gate, and the agent merges on its verdict.
+Where the branch rule requires zero approvals and one status check, that check is the gate, and the agent merges on its verdict. Before any merge, the agent runs [the review loop](reference/review-loop-before-merge.md) until a pass on the head is clean.
 
 Validation is the precondition, and green means every check reported on the exact head commit. A branch rule that requires one status check names the floor a merge needs; a pull request whose other checks are red or still running is held until they report.
 

package/.agents/skills/pr-lifecycle/reference/review-loop-before-merge.md

@@ -0,0 +1,11 @@
+# The review loop runs before the merge
+
+A pull request the agent made merges only after a code review of its head comes back clean. Loop it:
+
+1. Review the head with the command `CLAUDE_MERGE_REVIEW_COMMAND` names. Where it is unset, run `/code-review high --max-findings all` against the base.
+2. Record the pass: `python3 ~/.claude/scripts/merge_review_receipt.py <owner>/<name> <number> <head sha> <finding count>`.
+3. Fix or answer every finding, push, and review the new head.
+4. Repeat until a pass records `CLEAN`.
+5. Merge pinned to that head: `expectedHeadSha` on the merge tool, or `--match-head-commit` on `gh pr merge`.
+
+`hooks/blocking/merge_review_gate.py` denies any other merge. In a merge-queue repository, enqueue with `gh pr merge <number> --repo <owner>/<name> --auto --match-head-commit <head sha>`; auto-merge that names no head is denied. A repository whose own CI and merge queue review and merge its pull requests is listed in `CLAUDE_MERGE_REVIEW_EXEMPT_REPOSITORIES`, comma separated as `owner/name`, and skips the gate.

package/hooks/blocking/merge_review_gate.py

@@ -0,0 +1,304 @@
+"""Deny an agent's merge until a review of the merged head came back clean.
+
+The agent that drives a pull request loops a code review on it, fixing and
+pushing each finding, until one pass reports zero findings. The merge then
+names that exact head::
+
+    merge, receipt says 0 findings at abc123, merge pinned to abc123 -> allow
+    merge, receipt at abc123, merge pinned to def456                 -> deny, review again
+    merge, receipt at abc123, merge names no head                    -> deny, pin it
+    merge, no receipt or the receipt counts findings                 -> deny, run the loop
+    auto-merge or enqueue pinned to the clean head                    -> allow
+    auto-merge that names no head                                     -> deny, pin it
+    repository listed in CLAUDE_MERGE_REVIEW_EXEMPT_REPOSITORIES      -> allow
+
+The deny reason names the review command CLAUDE_MERGE_REVIEW_COMMAND sets,
+or ``/code-review high --max-findings all`` when it is unset.
+
+``scripts/merge_review_receipt.py`` writes the receipt this reads.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+hooks_directory = str(Path(__file__).resolve().parent.parent)
+if hooks_directory not in sys.path:
+    sys.path.insert(0, hooks_directory)
+
+from hooks_constants.hook_specific_output_keys import (
+    HOOK_SPECIFIC_OUTPUT_KEY,
+    PERMISSION_DECISION_KEY,
+)
+from hooks_constants.merge_review_gate_constants import (
+    ALL_RECEIPT_DIRECTORY_SEGMENTS,
+    ALL_SHELL_TOOL_NAMES,
+    AUTO_MERGE_REASON_TEMPLATE,
+    AUTO_MERGE_TOOL_SUFFIX,
+    API_SHA_FIELD_PATTERN,
+    AUTO_OPTION_PATTERN,
+    DEFAULT_REVIEW_COMMAND,
+    DENY_DECISION,
+    EXEMPT_REPOSITORIES_ENVIRONMENT_VARIABLE,
+    EXPECTED_HEAD_FIELD,
+    GH_API_MERGE_PATTERN,
+    GH_PR_MERGE_PATTERN,
+    HOOK_EVENT_NAME,
+    MATCH_HEAD_PATTERN,
+    MERGE_TOOL_SUFFIX,
+    NO_CLEAN_REVIEW_REASON_TEMPLATE,
+    NUMBER_FIELD,
+    OPTION_WITH_VALUE_PATTERN,
+    OWNER_FIELD,
+    PERMISSION_DECISION_REASON_KEY,
+    PR_NUMBER_PATTERN,
+    PR_URL_PATTERN,
+    RECEIPT_DIRECTORY_ENVIRONMENT_VARIABLE,
+    RECEIPT_FILE_NAME_TEMPLATE,
+    RECEIPT_FINDINGS_KEY,
+    RECEIPT_HEAD_KEY,
+    REPO_FIELD,
+    REPO_OPTION_PATTERN,
+    REPOSITORY_SEPARATOR,
+    REVIEW_COMMAND_ENVIRONMENT_VARIABLE,
+    STALE_REVIEW_REASON_TEMPLATE,
+    UNKNOWN_TARGET_REASON,
+    UNPINNED_MERGE_REASON_TEMPLATE,
+)
+from hooks_constants.pre_tool_use_stdin import print_decision_from_stdin
+
+
+@dataclass(frozen=True)
+class MergeRequest:
+    """One merge a tool call asks for.
+
+    Attributes:
+        owner: Repository owner, or empty when the call names none.
+        repo: Repository name, or empty when the call names none.
+        number: Pull request number, or None when the call names none.
+        pinned_head: The head the merge is pinned to, or None.
+        is_auto_merge: Whether the call turns on auto-merge.
+    """
+
+    owner: str
+    repo: str
+    number: int | None
+    pinned_head: str | None
+    is_auto_merge: bool
+
+    @property
+    def slug(self) -> str:
+        """Return ``owner/repo``."""
+        return f"{self.owner}/{self.repo}"
+
+
+def receipt_directory() -> Path:
+    """Return the folder that holds one review receipt per pull request.
+
+    Returns:
+        The folder CLAUDE_MERGE_REVIEW_RECEIPT_DIR names, else ``~/.claude/merge-reviews``.
+    """
+    override = os.environ.get(RECEIPT_DIRECTORY_ENVIRONMENT_VARIABLE)
+    if override:
+        return Path(override)
+    return Path.home().joinpath(*ALL_RECEIPT_DIRECTORY_SEGMENTS)
+
+
+def receipt_path(owner: str, repo: str, number: int) -> Path:
+    """Return where the review receipt for one pull request lives.
+
+    Args:
+        owner: Repository owner.
+        repo: Repository name.
+        number: Pull request number.
+
+    Returns:
+        The receipt file path.
+    """
+    return receipt_directory() / RECEIPT_FILE_NAME_TEMPLATE.format(
+        owner=owner.casefold(), repo=repo.casefold(), number=number
+    )
+
+
+def merge_request_from(all_payload_fields: dict[str, object]) -> MergeRequest | None:
+    """Read the merge a PreToolUse payload asks for.
+
+    ::
+
+        mcp__github__merge_pull_request {owner, repo, pullNumber, expectedHeadSha}
+        mcp__github__enable_pr_auto_merge {owner, repo, pullNumber}
+        gh pr merge 12 --repo o/r --match-head-commit abc123
+        gh api repos/o/r/pulls/12/merge -X PUT
+
+    Args:
+        all_payload_fields: The parsed PreToolUse input.
+
+    Returns:
+        The merge request, or None when the call merges nothing.
+    """
+    tool_name = all_payload_fields.get("tool_name")
+    tool_input = all_payload_fields.get("tool_input")
+    if not isinstance(tool_name, str) or not isinstance(tool_input, dict):
+        return None
+    if tool_name.endswith((MERGE_TOOL_SUFFIX, AUTO_MERGE_TOOL_SUFFIX)):
+        return _tool_merge_request(tool_name, tool_input)
+    command = tool_input.get("command")
+    if tool_name not in ALL_SHELL_TOOL_NAMES or not isinstance(command, str):
+        return None
+    return _shell_merge_request(command)
+
+
+def _tool_merge_request(tool_name: str, all_tool_input: dict[object, object]) -> MergeRequest:
+    number = all_tool_input.get(NUMBER_FIELD)
+    pinned_head = all_tool_input.get(EXPECTED_HEAD_FIELD)
+    return MergeRequest(
+        owner=str(all_tool_input.get(OWNER_FIELD, "")),
+        repo=str(all_tool_input.get(REPO_FIELD, "")),
+        number=int(number) if isinstance(number, (int, float)) else None,
+        pinned_head=pinned_head if isinstance(pinned_head, str) and pinned_head else None,
+        is_auto_merge=tool_name.endswith(AUTO_MERGE_TOOL_SUFFIX),
+    )
+
+
+def _shell_merge_request(command: str) -> MergeRequest | None:
+    api_match = GH_API_MERGE_PATTERN.search(command)
+    if api_match:
+        return MergeRequest(
+            owner=api_match["owner"],
+            repo=api_match["repo"],
+            number=int(api_match["number"]),
+            pinned_head=_api_pinned_head(command),
+            is_auto_merge=False,
+        )
+    merge_match = GH_PR_MERGE_PATTERN.search(command)
+    if not merge_match:
+        return None
+    rest = merge_match["rest"]
+    owner, repo, number = _gh_pr_merge_target(rest)
+    head_match = MATCH_HEAD_PATTERN.search(rest)
+    return MergeRequest(
+        owner=owner,
+        repo=repo,
+        number=number,
+        pinned_head=head_match["sha"] if head_match else None,
+        is_auto_merge=bool(AUTO_OPTION_PATTERN.search(rest)),
+    )
+
+
+def _gh_pr_merge_target(arguments: str) -> tuple[str, str, int | None]:
+    url_match = PR_URL_PATTERN.search(arguments)
+    if url_match:
+        return url_match["owner"], url_match["repo"], int(url_match["number"])
+    repo_match = REPO_OPTION_PATTERN.search(arguments)
+    number_match = PR_NUMBER_PATTERN.search(_without_option_values(arguments))
+    return (
+        repo_match["owner"] if repo_match else "",
+        repo_match["repo"] if repo_match else "",
+        int(number_match["number"]) if number_match else None,
+    )
+
+
+def _api_pinned_head(command: str) -> str | None:
+    sha_match = API_SHA_FIELD_PATTERN.search(command)
+    return sha_match["sha"] if sha_match else None
+
+
+def _without_option_values(arguments: str) -> str:
+    return OPTION_WITH_VALUE_PATTERN.sub(" ", arguments)
+
+
+def _is_exempt(request: MergeRequest) -> bool:
+    listed = os.environ.get(EXEMPT_REPOSITORIES_ENVIRONMENT_VARIABLE, "")
+    all_exempt = {
+        each.strip().casefold() for each in listed.split(REPOSITORY_SEPARATOR) if each.strip()
+    }
+    return request.slug.casefold() in all_exempt
+
+
+def _clean_head(request: MergeRequest) -> str | None:
+    if request.number is None:
+        return None
+    try:
+        receipt = json.loads(
+            receipt_path(request.owner, request.repo, request.number).read_text(encoding="utf-8")
+        )
+    except (OSError, ValueError):
+        return None
+    if not isinstance(receipt, dict) or receipt.get(RECEIPT_FINDINGS_KEY) != 0:
+        return None
+    head = receipt.get(RECEIPT_HEAD_KEY)
+    return head if isinstance(head, str) and head else None
+
+
+def _review_command() -> str:
+    return os.environ.get(REVIEW_COMMAND_ENVIRONMENT_VARIABLE) or DEFAULT_REVIEW_COMMAND
+
+
+def _same_commit(first: str, second: str) -> bool:
+    shorter, longer = sorted((first.casefold(), second.casefold()), key=len)
+    return longer.startswith(shorter)
+
+
+def deny_reason(request: MergeRequest) -> str | None:
+    """Return why a merge must wait for a clean review, or None to allow it.
+
+    Args:
+        request: The merge the tool call asks for.
+
+    Returns:
+        The deny reason, or None when the merge may run.
+    """
+    if not request.owner or not request.repo or request.number is None:
+        return UNKNOWN_TARGET_REASON
+    if _is_exempt(request):
+        return None
+    fields = {"slug": request.slug, "number": request.number}
+    clean_head = _clean_head(request)
+    if clean_head is None:
+        return NO_CLEAN_REVIEW_REASON_TEMPLATE.format(review_command=_review_command(), **fields)
+    if request.pinned_head is None and request.is_auto_merge:
+        return AUTO_MERGE_REASON_TEMPLATE.format(head=clean_head, **fields)
+    if request.pinned_head is None:
+        return UNPINNED_MERGE_REASON_TEMPLATE.format(head=clean_head, **fields)
+    if not _same_commit(clean_head, request.pinned_head):
+        return STALE_REVIEW_REASON_TEMPLATE.format(
+            head=clean_head, pinned=request.pinned_head, **fields
+        )
+    return None
+
+
+def decision_for(all_payload_fields: dict[str, object]) -> dict[str, object] | None:
+    """Return a deny decision for a merge with no clean review, else None.
+
+    Args:
+        all_payload_fields: The parsed PreToolUse input.
+
+    Returns:
+        The hook output that denies the call, or None to allow it.
+    """
+    request = merge_request_from(all_payload_fields)
+    if request is None:
+        return None
+    reason = deny_reason(request)
+    if reason is None:
+        return None
+    return {
+        HOOK_SPECIFIC_OUTPUT_KEY: {
+            "hookEventName": HOOK_EVENT_NAME,
+            PERMISSION_DECISION_KEY: DENY_DECISION,
+            PERMISSION_DECISION_REASON_KEY: reason,
+        }
+    }
+
+
+def main() -> int:
+    """Read one payload, print a deny when needed, and exit zero."""
+    return print_decision_from_stdin(decision_for)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/hooks/blocking/pr_lifecycle_skill_gate.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import json
 import re
 import shlex
 import sys
@@ -54,7 +53,7 @@ from hooks_constants.hook_specific_output_keys import (
     HOOK_SPECIFIC_OUTPUT_KEY,
     PERMISSION_DECISION_KEY,
 )
-from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+from hooks_constants.pre_tool_use_stdin import print_decision_from_stdin
 from hooks_constants.setup_project_paths_constants import DECODE_ERRORS_POLICY, UTF8_ENCODING
 from blocking.followup_pr_dedupe import create_tool_fields, duplicate_followup_reason
 from blocking.pull_request_proof import (
@@ -298,12 +297,7 @@ def _deny(reason: str) -> dict[str, object]:
 
 def main() -> int:
     """Read one payload, print a deny when needed, and exit zero."""
-    payload = read_hook_input_dictionary_from_stdin()
-    if payload is not None:
-        decision = decision_for(payload)
-        if decision is not None:
-            sys.stdout.write(json.dumps(decision) + "\n")
-    return 0
+    return print_decision_from_stdin(decision_for)
 
 
 if __name__ == "__main__":

package/hooks/blocking/test_merge_review_gate.py

@@ -0,0 +1,132 @@
+"""Behavior tests for the clean-review merge gate."""
+
+import sys
+from pathlib import Path
+
+import pytest
+
+HOOKS_DIRECTORY = Path(__file__).resolve().parent.parent
+SCRIPTS_DIRECTORY = HOOKS_DIRECTORY.parent / "scripts"
+for each_directory in (HOOKS_DIRECTORY, SCRIPTS_DIRECTORY):
+    if str(each_directory) not in sys.path:
+        sys.path.insert(0, str(each_directory))
+
+import merge_review_receipt
+from blocking import merge_review_gate as gate
+
+CLEAN_HEAD = "abc1234def5678abc1234def5678abc1234def56"
+NEW_HEAD = "9999999aaaaaaa9999999aaaaaaa9999999aaaaa"
+
+
+@pytest.fixture(autouse=True)
+def receipt_folder(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+    monkeypatch.setenv("CLAUDE_MERGE_REVIEW_RECEIPT_DIR", str(tmp_path))
+    monkeypatch.delenv("CLAUDE_MERGE_REVIEW_EXEMPT_REPOSITORIES", raising=False)
+    monkeypatch.delenv("CLAUDE_MERGE_REVIEW_COMMAND", raising=False)
+    return tmp_path
+
+
+def _merge_tool(head: str | None = None) -> dict[str, object]:
+    tool_input: dict[str, object] = {"owner": "acme", "repo": "tools", "pullNumber": 12}
+    if head is not None:
+        tool_input["expectedHeadSha"] = head
+    return {"tool_name": "mcp__github__merge_pull_request", "tool_input": tool_input}
+
+
+def _bash(command: str) -> dict[str, object]:
+    return {"tool_name": "Bash", "tool_input": {"command": command}}
+
+
+def _reason(payload: dict[str, object]) -> str | None:
+    decision = gate.decision_for(payload)
+    if decision is None:
+        return None
+    return decision["hookSpecificOutput"]["permissionDecisionReason"]
+
+
+def test_should_deny_a_merge_with_no_review() -> None:
+    assert "no clean review" in _reason(_merge_tool(CLEAN_HEAD))
+
+
+def test_should_deny_a_merge_whose_last_pass_found_findings() -> None:
+    merge_review_receipt.record_review("acme/tools", 12, CLEAN_HEAD, 2)
+    assert "no clean review" in _reason(_merge_tool(CLEAN_HEAD))
+
+
+def test_should_allow_a_merge_pinned_to_the_clean_head() -> None:
+    merge_review_receipt.record_review("acme/tools", 12, CLEAN_HEAD, 0)
+    assert _reason(_merge_tool(CLEAN_HEAD)) is None
+
+
+def test_should_deny_a_merge_pinned_to_a_head_pushed_after_the_review() -> None:
+    merge_review_receipt.record_review("acme/tools", 12, CLEAN_HEAD, 0)
+    assert "Review the new head" in _reason(_merge_tool(NEW_HEAD))
+
+
+def test_should_deny_an_unpinned_merge_after_a_clean_review() -> None:
+    merge_review_receipt.record_review("acme/tools", 12, CLEAN_HEAD, 0)
+    assert "names no head" in _reason(_merge_tool())
+
+
+def test_should_deny_auto_merge_that_names_no_head() -> None:
+    merge_review_receipt.record_review("acme/tools", 12, CLEAN_HEAD, 0)
+    payload = {
+        "tool_name": "mcp__github__enable_pr_auto_merge",
+        "tool_input": {"owner": "acme", "repo": "tools", "pullNumber": 12},
+    }
+    assert f"--match-head-commit {CLEAN_HEAD}" in _reason(payload)
+
+
+def test_should_allow_any_merge_in_an_exempt_repository(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("CLAUDE_MERGE_REVIEW_EXEMPT_REPOSITORIES", "other/x, ACME/Tools")
+    assert _reason(_merge_tool()) is None
+
+
+def test_should_read_a_gh_pr_merge_pinned_with_a_short_head() -> None:
+    merge_review_receipt.record_review("acme/tools", 12, CLEAN_HEAD, 0)
+    command = f"gh pr merge --squash 12 --repo acme/tools --match-head-commit {CLEAN_HEAD[:7]}"
+    assert _reason(_bash(command)) is None
+
+
+def test_should_deny_gh_pr_merge_auto() -> None:
+    merge_review_receipt.record_review("acme/tools", 12, CLEAN_HEAD, 0)
+    assert "Auto-merge" in _reason(
+        _bash("gh pr merge https://github.com/acme/tools/pull/12 --auto")
+    )
+
+
+def test_should_deny_gh_pr_merge_with_no_repository() -> None:
+    assert "names no repository" in _reason(_bash("gh pr merge 12 --squash"))
+
+
+def test_should_read_a_gh_api_merge_with_a_sha_field() -> None:
+    merge_review_receipt.record_review("acme/tools", 12, CLEAN_HEAD, 0)
+    command = f"gh api -X PUT repos/acme/tools/pulls/12/merge -f sha={CLEAN_HEAD}"
+    assert _reason(_bash(command)) is None
+
+
+def test_should_ignore_commands_that_merge_nothing() -> None:
+    assert gate.decision_for(_bash("gh pr view 12 --repo acme/tools")) is None
+    assert gate.decision_for(_bash("git merge origin/main")) is None
+
+
+def test_should_name_the_configured_review_command(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("CLAUDE_MERGE_REVIEW_COMMAND", "/team-review")
+    assert "`/team-review`" in _reason(_merge_tool(CLEAN_HEAD))
+
+
+def test_should_allow_auto_merge_pinned_to_the_clean_head() -> None:
+    merge_review_receipt.record_review("acme/tools", 12, CLEAN_HEAD, 0)
+    command = f"gh pr merge 12 --repo acme/tools --auto --match-head-commit {CLEAN_HEAD}"
+    assert _reason(_bash(command)) is None
+
+
+def test_should_deny_pinned_auto_merge_with_no_clean_review() -> None:
+    command = f"gh pr merge 12 --repo acme/tools --auto --match-head-commit {CLEAN_HEAD}"
+    assert "no clean review" in _reason(_bash(command))
+
+
+def test_should_deny_auto_merge_pinned_to_a_newer_head() -> None:
+    merge_review_receipt.record_review("acme/tools", 12, CLEAN_HEAD, 0)
+    command = f"gh pr merge 12 --repo acme/tools --auto --match-head-commit {NEW_HEAD}"
+    assert "Review the new head" in _reason(_bash(command))

package/hooks/features/conduct-gates.md

@@ -11,6 +11,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
 - `blocking/step_note_gate.py` requires a status line before a tool call while its opt-in flag is on.
 - `blocking/verify_before_acting.py` blocks a completed mutating call when the agent's reasoning contains an unchecked claim.
 - `blocking/pr_lifecycle_skill_gate.py` denies a commit, push, pull request action, or merge until the `pr-lifecycle` skill appears in the transcript since the last compaction.
+- `blocking/merge_review_gate.py` denies an agent's merge until a review pass on the merged head reported zero findings. It reads the receipt `scripts/merge_review_receipt.py` writes, requires the merge, auto-merge or merge-queue entry to be pinned to that head, and skips repositories listed in `CLAUDE_MERGE_REVIEW_EXEMPT_REPOSITORIES`. Its deny reason names the review command `CLAUDE_MERGE_REVIEW_COMMAND` sets.
 - `blocking/artifact_dark_mode_gate.py` denies an Artifact page publish when the page, inside the publish wrapper, keeps a light body or shows text under 4.5:1 contrast in dark mode. `blocking/artifact_dark_mode_render.cjs` renders the page in headless Chromium for it.
 
 ## When it fires
@@ -22,6 +23,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
 - `blocking/step_note_gate.py` runs on `PreToolUse`, matcher `*`, timeout `15` seconds in `hooks.json`.
 - `blocking/verify_before_acting.py` runs on `PostToolUse`, matcher `Write|Edit|MultiEdit|NotebookEdit|Agent|Task|apply_patch|Bash|PowerShell|mcp__.*`, timeout `10` seconds in `hooks.json`.
 - `blocking/pr_lifecycle_skill_gate.py` runs on `PreToolUse`, matcher `Bash|PowerShell|mcp__.*__(create_pull_request|merge_pull_request|enable_pr_auto_merge|update_pull_request|actions_run_trigger)`, timeout `10` seconds in `hooks.json`.
+- `blocking/merge_review_gate.py` runs on `PreToolUse`, matcher `Bash|PowerShell|mcp__.*__(merge_pull_request|enable_pr_auto_merge)`, timeout `10` seconds in `hooks.json`.
 - `blocking/artifact_dark_mode_gate.py` runs on `PreToolUse`, matcher `Artifact`, timeout `60` seconds in `hooks.json`.
 
 ## Proving it
@@ -37,6 +39,7 @@ Preconditions:
 - **Step note.** Input is a tool call after a transcript message without a status line while the flag is on. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_step_note_gate.py -q`. The adjacent test observes a block until a status line appears.
 - **Checked claim.** Input is a Write after hedged reasoning in the transcript. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_verify_before_acting.py -q`. The adjacent test observes a block and a logged blocked outcome.
 - **Lifecycle skill.** Input is a `git commit` or `gh pr create` command with no `pr-lifecycle` invocation in the transcript. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_pr_lifecycle_skill_gate.py -q`. The adjacent test observes a denial, then a silent allow once the skill or its slash command appears.
+- **Clean review.** Input is a merge with no receipt, a receipt with findings, a merge pinned to a newer head, an unpinned merge, or auto-merge with no head. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_merge_review_gate.py -q`. The adjacent test observes a denial for each; a merge or auto-merge pinned to the clean head and a merge in an exempt repository pass.
 - **Dark mode page.** Input is an Artifact publish of a page that themes `html` but leaves `body` to the publish wrapper. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_artifact_dark_mode_gate.py -q`. The adjacent test observes a denial that names the text and its contrast; a page that themes `body` passes. The render tests skip on a host with no Node Playwright and Chromium.
 
 ## Gotchas
@@ -48,3 +51,4 @@ Preconditions:
 - The handoff close gate reads the `body` and `comment` fields of issue tools only. A `gh issue close --comment` command in Bash and a pull request body that closes the issue with `Closes #N` do not reach it.
 - The lifecycle gate counts only invocations after the last compaction, so a compacted session invokes `pr-lifecycle` again. A missing or unreadable transcript allows the call.
 - The dark mode gate denies a page publish when Node, Playwright or Chromium is missing, and its reason names the install command. It checks both dark signals, `prefers-color-scheme: dark` and `data-theme="dark"` on the root element.
+- The clean-review gate trusts the receipt. A receipt the agent writes by hand with zero findings passes, so the pr-lifecycle skill names the review loop that writes it. A `gh pr merge` that names no repository is denied, because the gate cannot tell which repository the current branch belongs to.

package/hooks/hooks.json

@@ -102,6 +102,16 @@
           }
         ]
       },
+      {
+        "matcher": "Bash|PowerShell|mcp__.*__(merge_pull_request|enable_pr_auto_merge)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/merge_review_gate.py",
+            "timeout": 10
+          }
+        ]
+      },
       {
         "matcher": "Read",
         "hooks": [

package/hooks/hooks_constants/merge_review_gate_constants.py

@@ -0,0 +1,73 @@
+"""Named constants for merge_review_gate, the clean-review merge gate."""
+
+from __future__ import annotations
+
+import re
+
+HOOK_EVENT_NAME = "PreToolUse"
+DENY_DECISION = "deny"
+PERMISSION_DECISION_REASON_KEY = "permissionDecisionReason"
+
+MERGE_TOOL_SUFFIX = "__merge_pull_request"
+AUTO_MERGE_TOOL_SUFFIX = "__enable_pr_auto_merge"
+ALL_SHELL_TOOL_NAMES = frozenset({"Bash", "PowerShell"})
+
+OWNER_FIELD = "owner"
+REPO_FIELD = "repo"
+NUMBER_FIELD = "pullNumber"
+EXPECTED_HEAD_FIELD = "expectedHeadSha"
+
+GH_PR_MERGE_PATTERN = re.compile(r"(?:^|[\s;&|(])gh(?:\.exe)?\s+pr\s+merge\b(?P<rest>[^;&|]*)")
+GH_API_MERGE_PATTERN = re.compile(
+    r"(?:^|[\s;&|(])gh(?:\.exe)?\s+api\b[^;&|]*?repos/(?P<owner>[\w.-]+)/(?P<repo>[\w.-]+)/pulls/(?P<number>\d+)/merge\b"
+)
+PR_NUMBER_PATTERN = re.compile(r"(?:^|\s)#?(?P<number>\d+)(?:\s|$)")
+PR_URL_PATTERN = re.compile(
+    r"github\.com/(?P<owner>[\w.-]+)/(?P<repo>[\w.-]+)/pull/(?P<number>\d+)"
+)
+REPO_OPTION_PATTERN = re.compile(r"(?:-R|--repo)[\s=](?P<owner>[\w.-]+)/(?P<repo>[\w.-]+)")
+MATCH_HEAD_PATTERN = re.compile(r"--match-head-commit[\s=](?P<sha>[0-9a-fA-F]{7,40})")
+API_SHA_FIELD_PATTERN = re.compile(r"(?:-f|-F|--field|--raw-field)[\s=]sha=(?P<sha>[0-9a-fA-F]{7,40})")
+OPTION_WITH_VALUE_PATTERN = re.compile(
+    r"(?<!\S)(?:-R|--repo|--match-head-commit|-t|--subject|-b|--body|-F|--body-file|-A|--author-email)"
+    r"(?:=|\s+)(?:\"[^\"]*\"|'[^']*'|\S+)"
+)
+AUTO_OPTION_PATTERN = re.compile(r"(?:^|\s)--auto(?:\s|$)")
+
+EXEMPT_REPOSITORIES_ENVIRONMENT_VARIABLE = "CLAUDE_MERGE_REVIEW_EXEMPT_REPOSITORIES"
+REVIEW_COMMAND_ENVIRONMENT_VARIABLE = "CLAUDE_MERGE_REVIEW_COMMAND"
+DEFAULT_REVIEW_COMMAND = "/code-review high --max-findings all"
+RECEIPT_DIRECTORY_ENVIRONMENT_VARIABLE = "CLAUDE_MERGE_REVIEW_RECEIPT_DIR"
+ALL_RECEIPT_DIRECTORY_SEGMENTS = (".claude", "merge-reviews")
+RECEIPT_FILE_NAME_TEMPLATE = "{owner}__{repo}__{number}.json"
+REPOSITORY_SEPARATOR = ","
+RECEIPT_HEAD_KEY = "head"
+RECEIPT_FINDINGS_KEY = "findings"
+RECORD_COMMAND = "python3 ~/.claude/scripts/merge_review_receipt.py"
+
+NO_CLEAN_REVIEW_REASON_TEMPLATE = (
+    "{slug}#{number} has no clean review on the head you are merging. Run the review "
+    "loop: review the pull request head with `{review_command}`, fix and push every "
+    "finding, and review again "
+    "until a pass reports zero findings. Record that pass with `"
+    + RECORD_COMMAND
+    + " {slug} {number} <head sha> 0`, then merge pinned to that head."
+)
+UNPINNED_MERGE_REASON_TEMPLATE = (
+    "{slug}#{number} has a clean review for {head}, but this merge names no head. "
+    "Pass expectedHeadSha (merge tool) or --match-head-commit (gh pr merge) set to "
+    "{head}, so a push after the review cannot ride the merge."
+)
+STALE_REVIEW_REASON_TEMPLATE = (
+    "{slug}#{number} was reviewed clean at {head}, and this merge names {pinned}. "
+    "Review the new head until a pass reports zero findings, record it, then merge."
+)
+AUTO_MERGE_REASON_TEMPLATE = (
+    "Auto-merge on {slug}#{number} names no head, so it could merge a head no review "
+    "has seen. Run `gh pr merge {number} --repo {slug} --auto --match-head-commit {head}`, "
+    "which arms auto-merge or joins the merge queue only while the head is {head}."
+)
+UNKNOWN_TARGET_REASON = (
+    "This merge names no repository and pull request number the review gate can read. "
+    "Name both, such as `gh pr merge 12 --repo owner/name --match-head-commit <sha>`."
+)

package/hooks/hooks_constants/pre_tool_use_stdin.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import json
 import sys
+from collections.abc import Callable
 
 from hooks_constants.setup_project_paths_constants import (
     DECODE_ERRORS_POLICY,
@@ -46,3 +47,22 @@ def read_hook_input_dictionary_from_stdin() -> dict[str, object] | None:
     if not isinstance(parsed_payload, dict):
         return None
     return parsed_payload
+
+
+def print_decision_from_stdin(
+    decision_for: Callable[[dict[str, object]], dict[str, object] | None],
+) -> int:
+    """Read one payload, print the decision the gate returns, and return zero.
+
+    Args:
+        decision_for: The gate's function from a payload to its hook output, or None.
+
+    Returns:
+        Zero, so the hook never fails the tool call on its own.
+    """
+    payload = read_hook_input_dictionary_from_stdin()
+    if payload is not None:
+        decision = decision_for(payload)
+        if decision is not None:
+            sys.stdout.write(json.dumps(decision) + "\n")
+    return 0

package/hooks/hooks_constants/test_pre_tool_use_stdin.py

@@ -78,3 +78,20 @@ def test_read_returns_none_when_buffer_and_text_read_raise_attribute_error() ->
 
     with patch("sys.stdin", BrokenStandardInput()):
         assert read_hook_input_dictionary_from_stdin() is None
+
+
+def test_print_decision_from_stdin_writes_the_gate_output() -> None:
+    output = io.StringIO()
+    with patch("sys.stdin", io.StringIO('{"tool_name": "Bash"}')), patch("sys.stdout", output):
+        exit_code = pre_tool_use_stdin.print_decision_from_stdin(
+            lambda payload: {"seen": payload["tool_name"]}
+        )
+    assert exit_code == 0
+    assert json.loads(output.getvalue()) == {"seen": "Bash"}
+
+
+def test_print_decision_from_stdin_writes_nothing_on_allow() -> None:
+    output = io.StringIO()
+    with patch("sys.stdin", io.StringIO('{"tool_name": "Bash"}')), patch("sys.stdout", output):
+        assert pre_tool_use_stdin.print_decision_from_stdin(lambda payload: None) == 0
+    assert output.getvalue() == ""

package/package.json

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

package/scripts/merge_review_receipt.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+"""Record one review pass on a pull request head for the merge review gate.
+
+The agent loops a code review on its pull request. Each pass is recorded::
+
+    python3 merge_review_receipt.py owner/name 12 abc1234 3   -> REVIEWED owner/name#12 abc1234 3 findings
+    fix, push, review the new head
+    python3 merge_review_receipt.py owner/name 12 def5678 0   -> CLEAN owner/name#12 def5678
+
+``hooks/blocking/merge_review_gate.py`` allows a merge pinned to the head of
+the newest pass only when that pass counted zero findings.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+from typing import TextIO
+
+hooks_directory = str(Path(__file__).resolve().parent.parent / "hooks")
+if hooks_directory not in sys.path:
+    sys.path.insert(0, hooks_directory)
+
+from blocking.merge_review_gate import receipt_path
+from hooks_constants.merge_review_gate_constants import (
+    RECEIPT_FINDINGS_KEY,
+    RECEIPT_HEAD_KEY,
+)
+
+
+def record_review(slug: str, number: int, head: str, finding_count: int) -> Path:
+    """Write the receipt for one review pass, replacing the previous pass.
+
+    Args:
+        slug: Repository as ``owner/name``.
+        number: Pull request number.
+        head: The commit the pass reviewed.
+        finding_count: How many findings the pass reported.
+
+    Returns:
+        The receipt path written.
+    """
+    owner, repo = slug.split("/", 1)
+    path = receipt_path(owner, repo, number)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        json.dumps({RECEIPT_HEAD_KEY: head, RECEIPT_FINDINGS_KEY: finding_count})
+        + "\n",
+        encoding="utf-8",
+    )
+    return path
+
+
+def main(all_arguments: Sequence[str], stdout: TextIO = sys.stdout) -> int:
+    """Record one pass and print its verdict line.
+
+    Args:
+        all_arguments: Command arguments after the program name.
+        stdout: Stream that receives the verdict.
+
+    Returns:
+        0 for a clean pass, and 1 for a pass with findings.
+    """
+    parser = argparse.ArgumentParser(prog="merge_review_receipt")
+    parser.add_argument("slug", help="Repository as owner/name.")
+    parser.add_argument("number", type=int, help="Pull request number.")
+    parser.add_argument("head", help="The head commit the pass reviewed.")
+    parser.add_argument("findings", type=int, help="Findings the pass reported.")
+    parsed = parser.parse_args(all_arguments)
+    record_review(parsed.slug, parsed.number, parsed.head, parsed.findings)
+    if parsed.findings == 0:
+        stdout.write(f"CLEAN {parsed.slug}#{parsed.number} {parsed.head}\n")
+        return 0
+    stdout.write(
+        f"REVIEWED {parsed.slug}#{parsed.number} {parsed.head} {parsed.findings} findings\n"
+    )
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/scripts/policy_lint/config/constants.py

@@ -64,6 +64,7 @@ ALL_ACTION_BOUNDARY_PREFIXES = ("deny_", "block_", "ask_")
 ALL_ACTION_BOUNDARY_EXEMPT_REGISTRATION_PATHS = (
     "blocking/bash_pre_tool_use_dispatcher.py",
     "blocking/pr_lifecycle_skill_gate.py",
+    "blocking/merge_review_gate.py",
     "blocking/step_note_gate.py",
     "blocking/reply_length_gate.py",
     "blocking/edit_marker_gate.py",

package/scripts/test_merge_review_receipt.py

@@ -0,0 +1,38 @@
+"""Tests for the merge review receipt recorder."""
+
+from __future__ import annotations
+
+import json
+from io import StringIO
+from pathlib import Path
+
+import pytest
+
+import merge_review_receipt
+
+HEAD = "abc1234def5678abc1234def5678abc1234def56"
+
+
+@pytest.fixture(autouse=True)
+def receipt_folder(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+    monkeypatch.setenv("CLAUDE_MERGE_REVIEW_RECEIPT_DIR", str(tmp_path))
+    return tmp_path
+
+
+def test_should_print_clean_and_exit_zero_for_a_pass_with_no_findings(receipt_folder: Path) -> None:
+    verdict_stream = StringIO()
+    assert merge_review_receipt.main(["acme/tools", "12", HEAD, "0"], verdict_stream) == 0
+    assert verdict_stream.getvalue() == f"CLEAN acme/tools#12 {HEAD}\n"
+
+
+def test_should_exit_one_and_count_findings_for_a_pass_with_findings() -> None:
+    verdict_stream = StringIO()
+    assert merge_review_receipt.main(["acme/tools", "12", HEAD, "3"], verdict_stream) == 1
+    assert verdict_stream.getvalue() == f"REVIEWED acme/tools#12 {HEAD} 3 findings\n"
+
+
+def test_record_review_replaces_the_previous_pass(receipt_folder: Path) -> None:
+    merge_review_receipt.record_review("Acme/Tools", 12, "old", 4)
+    path = merge_review_receipt.record_review("Acme/Tools", 12, HEAD, 0)
+    assert path == receipt_folder / "acme__tools__12.json"
+    assert json.loads(path.read_text(encoding="utf-8")) == {"head": HEAD, "findings": 0}