claude-dev-env 8.76.0 → 8.78.0

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 and any auto-merge. 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,303 @@
+"""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                                                        -> deny, merge pinned instead
+    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}
+    if request.is_auto_merge:
+        return AUTO_MERGE_REASON_TEMPLATE.format(**fields)
+    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:
+        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/reply_length_gate.py

@@ -57,6 +57,7 @@ later pass, so this gate denies it and the model resends a shorter one.
 
 from __future__ import annotations
 
+import json
 import os
 import re
 import sys
@@ -75,9 +76,14 @@ from visual_reply_rules import (
     second_reply_violation,
     visual_violation,
     widget_anchor_violation,
+    widget_flowchart_advice,
 )
 from hooks_constants.hook_block_logger import log_hook_block
 from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+from hooks_constants.hook_specific_output_keys import (
+    HOOK_EVENT_NAME_KEY,
+    HOOK_SPECIFIC_OUTPUT_KEY,
+)
 from hooks_constants.reply_length_gate_constants import (
     ALL_CHECKED_TOOL_NAMES,
     ALL_DECISION_CARD_PROSE_KEYS,
@@ -101,6 +107,7 @@ from hooks_constants.reply_length_gate_constants import (
     EM_DASH_MESSAGE,
     EM_DASH_PATTERN,
     FENCED_BLOCK_PATTERN,
+    ADDITIONAL_CONTEXT_KEY,
     HOOK_EVENT_NAME,
     INLINE_CODE_PATTERN,
     LINE_BREAK_PATTERN,
@@ -322,6 +329,18 @@ def tool_violation(
     return None if violation is None else (violation, reply_text)
 
 
+def write_flowchart_advice(tool_name: object, all_tool_input: dict[str, object]) -> None:
+    """Print the flowchart advice for an allowed widget call that is not a flowchart."""
+    mode_rules = active_mode_rules()
+    if not isinstance(tool_name, str) or mode_rules is None:
+        return
+    advice = widget_flowchart_advice(tool_name, all_tool_input, mode_rules)
+    if advice is None:
+        return
+    hook_event_output = {HOOK_EVENT_NAME_KEY: HOOK_EVENT_NAME, ADDITIONAL_CONTEXT_KEY: advice}
+    sys.stdout.write(json.dumps({HOOK_SPECIFIC_OUTPUT_KEY: hook_event_output}))
+
+
 def main() -> int:
     hook_input = read_hook_input_dictionary_from_stdin()
     if hook_input is None:
@@ -332,6 +351,7 @@ def main() -> int:
         return ALLOW_EXIT_CODE
     checked = tool_violation(tool_name, tool_input, hook_input.get(TRANSCRIPT_PATH_KEY))
     if checked is None:
+        write_flowchart_advice(tool_name, tool_input)
         return ALLOW_EXIT_CODE
     violation, reply_text = checked
     block_reason = violation + RETRY_INSTRUCTION

package/hooks/blocking/test_merge_review_gate.py

@@ -0,0 +1,115 @@
+"""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_even_after_a_clean_review() -> 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 "Auto-merge" 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))

package/hooks/blocking/test_reply_length_gate.py

@@ -635,13 +635,21 @@ def test_should_deny_an_anchor_link_inside_widget_code(
     assert "does not open in the Claude app" in stderr_text
 
 
-def test_should_allow_widget_code_with_no_anchor(
+def test_should_allow_widget_code_with_no_anchor_and_advise_a_flowchart(
     monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
 ) -> None:
-    exit_code, _ = run_gate(
-        monkeypatch, capsys, WIDGET_TOOL_NAME, {"widget_code": "<div>Three steps</div>"}
+    hook_input = {
+        "hook_event_name": "PreToolUse",
+        "tool_name": WIDGET_TOOL_NAME,
+        "tool_input": {"widget_code": "<div>Three steps</div>"},
+    }
+    monkeypatch.setattr(
+        "sys.stdin", io.TextIOWrapper(io.BytesIO(json.dumps(hook_input).encode("utf-8")))
     )
+    exit_code = reply_length_gate.main()
     assert exit_code == 0
+    advice_output = json.loads(capsys.readouterr().out)
+    assert "Redraw this widget as one SVG flowchart" in advice_output["hookSpecificOutput"]["additionalContext"]
 
 
 def test_should_skip_the_mode_checks_when_the_switch_turns_the_mode_off(

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 to be pinned to that head, denies auto-merge, 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
@@ -30,13 +32,14 @@ Preconditions:
 
 - Run each command from the repository root with Python and pytest available. The tests create transcript and payload fixtures.
 
-- **Reply length.** Input is a reply with four sentences, a plain pull request number, an abbreviation, two sentences with no widget this turn, or widget code with an anchor link. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_reply_length_gate.py -q`. The adjacent test observes a denial and its count, link, or mode reason.
+- **Reply length.** Input is a reply with four sentences, a plain pull request number, an abbreviation, two sentences with no widget this turn, or widget code with an anchor link. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_reply_length_gate.py -q`. The adjacent test observes a denial and its count, link, or mode reason. Widget code with no flowchart passes with a flowchart reminder in `additionalContext`.
 - **Edit marker.** Input is an update message with strikethrough or an edit note. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_edit_marker_gate.py -q`. The adjacent test observes a denial; clean replacement text passes.
 - **Handoff close.** Input is an issue comment that says the issue is closed and that the found defect belongs to another issue. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_issue_close_handoff_gate.py -q`. The adjacent test observes a denial; a close with a plain cross-reference and a routing comment on an open issue both pass.
 - **Session title.** Input is a set session title call with no leading emoji or a name over 25 characters. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_session_title_format_gate.py -q`. The adjacent test observes a denial that names the broken rule; a well-formed title passes.
 - **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. 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 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,72 @@
+"""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} merges a future head no review has seen. Run the "
+    "review loop until it is clean, then merge directly, pinned to the reviewed 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/reply_length_gate_constants.py

@@ -88,3 +88,5 @@ BANNED_WORD_MESSAGE = 'Banned word "{banned_word}". Delete it and name the evide
 LONG_SENTENCE_MESSAGE = (
     'Sentence too long: {word_count} words, limit {word_limit}: "{sentence_preview}".'
 )
+
+ADDITIONAL_CONTEXT_KEY = "additionalContext"

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/hooks/hooks_constants/test_visual_reply_rules_constants.py

@@ -26,6 +26,7 @@ def test_rule_key_constants_name_rules_in_the_shipped_rule_list() -> None:
         constants.NO_PICTURE_RULE_KEY,
         constants.ABBREVIATIONS_RULE_KEY,
         constants.ONE_ITEM_RULE_KEY,
+        constants.FLOWCHART_RULE_KEY,
     } <= all_shipped_keys
     assert constants.ALLOWED_CAPITALIZED_WORDS_KEY in rules_document
     assert constants.LOWERCASE_ABBREVIATIONS_KEY in rules_document

package/hooks/hooks_constants/visual_reply_rules_constants.py

@@ -36,6 +36,15 @@ TRACKER_NUMBER_PATTERN = re.compile(
     r"\b(?:issues?|items?|cards?|tickets?|tasks?)\s*#?\d+", re.IGNORECASE
 )
 WIDGET_ANCHOR_PATTERN = re.compile(r"<a\b[^>]*\bhref\s*=", re.IGNORECASE)
+FLOWCHART_RULE_KEY = "not_flowchart"
+WIDGET_CODE_KEY = "widget_code"
+WIDGET_INPUT_KEY = "input"
+FLOWCHART_SVG_PATTERN = re.compile(r"<svg\b", re.IGNORECASE)
+FLOWCHART_ARROW_PATTERN = re.compile(r"marker-end", re.IGNORECASE)
+FLOWCHART_MARKER_BLOCK_PATTERN = re.compile(r"<marker\b[^>]*(?<!/)>.*?</marker>", re.IGNORECASE | re.DOTALL)
+FLOWCHART_DIAMOND_PATTERN = re.compile(
+    r"<polygon\b|<path\b[^>]*\bd=[\"']M[^\"']*L[^\"']*L[^\"']*L[^\"']*Z[\"']", re.IGNORECASE
+)
 
 TRANSCRIPT_ENCODING = "utf-8"
 ENTRY_TYPE_KEY = "type"
@@ -57,6 +66,7 @@ ABBREVIATION_MESSAGE = 'Abbreviation "{abbreviation}" in the text. {reminder}'
 TRACKER_NUMBER_MESSAGE = 'Tracker number "{reference}" in the text. {reminder}'
 NO_VISUAL_MESSAGE = "This reply has {sentence_count} sentences and no visual this turn. {reminder}"
 SECOND_REPLY_MESSAGE = "A reply already went out this turn. {reminder}"
+NOT_FLOWCHART_MESSAGE = "This widget is not a flowchart. {reminder}"
 WIDGET_ANCHOR_MESSAGE = (
     "A link sits inside the widget code, and a widget link does not open in the Claude app."
     " Remove the anchor and put the page link in the reply text."

package/hooks/test_context_budget_hooks.py

@@ -24,6 +24,7 @@ CONTEXT_OUTPUT_PATTERN = re.compile(r"additionalContext|ADDITIONAL_CONTEXT|addit
 UNMEASURED_REASON_BY_SCRIPT = {
     "blocking/pre_tool_use_dispatcher.py": "relays its hosted hooks' output",
     "blocking/bash_pre_tool_use_dispatcher.py": "relays its hosted hooks' output",
+    "blocking/reply_length_gate.py": "advises only on a widget while visual reply mode is on",
     "lifecycle/nested_project_hooks.py": "relays a nested project's own hooks",
     "routing/thread_spawn_pace_hook.py": "quotes a usage reading capped by its own constant",
     "session/issue_tracker_session_starter.py": "emits only for a repository the user's "

package/hooks/test_visual_reply_rules.py

@@ -8,6 +8,7 @@ _hooks_directory = str(Path(__file__).resolve().parent)
 if _hooks_directory not in sys.path:
     sys.path.insert(0, _hooks_directory)
 
+from hooks_constants.visual_reply_rules_constants import RULES_FILE_PATH
 from visual_reply_rules import (
     abbreviation_violation,
     load_rules,
@@ -17,6 +18,7 @@ from visual_reply_rules import (
     visual_shown_this_turn,
     visual_violation,
     widget_anchor_violation,
+    widget_flowchart_advice,
 )
 
 SHIPPED_RULES = load_rules()
@@ -162,3 +164,46 @@ def test_second_reply_violation_denies_only_after_a_delivered_reply(tmp_path: Pa
     )
     assert second_reply_violation(str(transcript_path), SHIPPED_RULES) is not None
     assert second_reply_violation(str(tmp_path / "missing.jsonl"), SHIPPED_RULES) is None
+
+
+FLOWCHART_CODE = (
+    '<svg><path d="M0 20L40 0L80 20L40 40Z"/>'
+    '<path d="M80 20H120" marker-end="url(#a)"/></svg>'
+)
+
+
+def test_widget_flowchart_advice_should_pass_an_svg_with_a_diamond_and_arrows() -> None:
+    rules = load_rules()
+    assert rules is not None
+    nested_input = {"input": {"widget_code": FLOWCHART_CODE}}
+    assert widget_flowchart_advice("mcp__hearthbot__post_widget", nested_input, rules) is None
+
+
+def test_widget_flowchart_advice_should_advise_on_cards_and_shapes_without_a_decision() -> None:
+    rules = load_rules()
+    assert rules is not None
+    card_input = {"widget_code": "<div class='card'>Merged</div>"}
+    no_diamond_input = {"widget_code": '<svg><path marker-end="url(#a)"/></svg>'}
+    arrowhead_only_input = {
+        "widget_code": '<svg><marker id="a"><polygon points="0 0,9 5,0 9"/></marker>'
+        '<rect/><path marker-end="url(#a)"/></svg>'
+    }
+    for each_input in (card_input, no_diamond_input, arrowhead_only_input):
+        reason = widget_flowchart_advice("mcp__hearthbot__post_widget", each_input, rules)
+        assert reason is not None and "diamond" in reason
+    assert widget_flowchart_advice("mcp__hearthbot__reply", card_input, rules) is None
+
+
+def test_widget_flowchart_advice_should_stay_quiet_when_the_rule_list_has_no_flowchart_rule(
+    tmp_path: Path,
+) -> None:
+    shipped_document = json.loads(RULES_FILE_PATH.read_text(encoding="utf-8"))
+    shipped_document["rules"] = [
+        each for each in shipped_document["rules"] if each["key"] != "not_flowchart"
+    ]
+    rules_path = tmp_path / "rules.json"
+    rules_path.write_text(json.dumps(shipped_document), encoding="utf-8")
+    rules = load_rules(rules_path)
+    assert rules is not None
+    card_input = {"widget_code": "<div class='card'>Merged</div>"}
+    assert widget_flowchart_advice("mcp__hearthbot__post_widget", card_input, rules) is None

package/hooks/visual_reply_rules.py

@@ -58,6 +58,14 @@ from hooks_constants.visual_reply_rules_constants import (
     TRANSCRIPT_ENCODING,
     USER_ENTRY_TYPE,
     WIDGET_ANCHOR_MESSAGE,
+    FLOWCHART_ARROW_PATTERN,
+    FLOWCHART_DIAMOND_PATTERN,
+    FLOWCHART_MARKER_BLOCK_PATTERN,
+    FLOWCHART_RULE_KEY,
+    FLOWCHART_SVG_PATTERN,
+    NOT_FLOWCHART_MESSAGE,
+    WIDGET_CODE_KEY,
+    WIDGET_INPUT_KEY,
     WIDGET_ANCHOR_PATTERN,
     WIDGET_TOOL_NAME_SUFFIX,
 )
@@ -153,6 +161,35 @@ def widget_anchor_violation(tool_name: str, all_tool_input: dict[str, object]) -
     return WIDGET_ANCHOR_MESSAGE if WIDGET_ANCHOR_PATTERN.search(serialized_input) else None
 
 
+def widget_flowchart_advice(
+    tool_name: str, all_tool_input: dict[str, object], rules: VisualReplyRules
+) -> str | None:
+    """Return the advice for widget code that is not a flowchart, else None.
+
+    The gate passes this advice to the session and still allows the call.
+
+    A flowchart widget is one SVG with at least one arrow marker and one
+    diamond shape for a yes or no check. Shapes inside a ``<marker>`` block
+    are arrowheads, so they never count as the diamond::
+
+        <svg><path d="M0 0L9 5L0 9L-9 5Z"/><path marker-end="url(#a)"/></svg>
+    """
+    all_rule_keys = {each.key for each in rules.all_rules}
+    if not tool_name.endswith(WIDGET_TOOL_NAME_SUFFIX) or FLOWCHART_RULE_KEY not in all_rule_keys:
+        return None
+    widget_code = all_tool_input.get(WIDGET_CODE_KEY)
+    if widget_code is None:
+        widget_input = all_tool_input.get(WIDGET_INPUT_KEY)
+        widget_code = widget_input.get(WIDGET_CODE_KEY) if isinstance(widget_input, dict) else None
+    code_text = FLOWCHART_MARKER_BLOCK_PATTERN.sub(
+        "", widget_code if isinstance(widget_code, str) else ""
+    )
+    all_shape_patterns = (FLOWCHART_SVG_PATTERN, FLOWCHART_ARROW_PATTERN, FLOWCHART_DIAMOND_PATTERN)
+    if all(each_pattern.search(code_text) for each_pattern in all_shape_patterns):
+        return None
+    return NOT_FLOWCHART_MESSAGE.format(reminder=rules.reminder(FLOWCHART_RULE_KEY))
+
+
 def _parsed_entries(all_transcript_lines: Iterable[str]) -> list[dict[str, object]]:
     all_entries = []
     for each_line in all_transcript_lines:

package/package.json

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

package/rules/visual-reply-rules.json

@@ -8,7 +8,7 @@
     {
       "key": "no_picture",
       "label": "No picture",
-      "reminder": "Show the item as one visual first, a widget or a published page. Then send one reply of one to three short sentences that states the outcome and each fact the user needs, and links the page."
+      "reminder": "Show the item as one visual first, a widget or a published page. Prefer a flowchart that runs left to right, with boxes for steps, a diamond for each yes or no check, and arrows between them. Then send one reply of one to three short sentences that states the outcome and each fact the user needs, and links the page."
     },
     {
       "key": "too_many_words",
@@ -25,6 +25,11 @@
       "label": "Wall of text",
       "reminder": "Put each point, and each step the reader takes, on its own line."
     },
+    {
+      "key": "not_flowchart",
+      "label": "No flowchart",
+      "reminder": "Redraw this widget as one SVG flowchart that runs left to right, with boxes for steps, a diamond for each yes or no check, and arrows between them, unless the item has no steps or checks."
+    },
     {
       "key": "use_flowchart",
       "label": "Use the flowchart",

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}