claude-dev-env 8.99.1 → 8.100.0

package/hooks/blocking/merge_review_gate.py

@@ -1,11 +1,14 @@
-"""Deny an agent's merge until a review of the merged head came back clean.
+"""Deny an agent's pull request open or merge until a review of that 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 or every finding
-it reports is ruled out with a link to the posted rulings. The merge then
-names that exact head::
+The agent reviews its branch before it opens the pull request, and loops a
+code review on the pull request, fixing and pushing each finding, until one
+pass reports zero findings or every finding it reports is ruled out with a
+link to the posted rulings. The open and the merge then name that exact head::
 
+    open, open receipt says 0 findings at abc123, branch head abc123 -> allow
+    open, no open receipt for the branch head                        -> deny, review first
     merge, receipt says 0 findings at abc123, merge pinned to abc123 -> allow
+    merge, open receipt clean at abc123, merge pinned to abc123      -> allow
     merge, receipt rules out all 3 findings with a link, pinned       -> allow
     merge, receipt at abc123, merge pinned to def456                 -> deny, review again
     merge, receipt at abc123, merge names no head                    -> deny, pin it
@@ -32,12 +35,18 @@ hooks_directory = str(Path(__file__).resolve().parent.parent)
 if hooks_directory not in sys.path:
     sys.path.insert(0, hooks_directory)
 
+from blocking.merge_review_gate_parts.open_request import OpenRequest, open_request_from
+from blocking.merge_review_gate_parts.receipts import (
+    has_clean_open_review,
+    is_clean_receipt,
+    receipt_path,
+    same_commit,
+)
 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,
@@ -52,6 +61,7 @@ from hooks_constants.merge_review_gate_constants import (
     HOOK_EVENT_NAME,
     MATCH_HEAD_PATTERN,
     MERGE_TOOL_SUFFIX,
+    NO_CLEAN_OPEN_REVIEW_REASON_TEMPLATE,
     NO_CLEAN_REVIEW_REASON_TEMPLATE,
     NUMBER_FIELD,
     OPTION_WITH_VALUE_PATTERN,
@@ -59,18 +69,13 @@ from hooks_constants.merge_review_gate_constants import (
     PERMISSION_DECISION_REASON_KEY,
     PR_NUMBER_PATTERN,
     PR_URL_PATTERN,
-    RECEIPT_DIRECTORY_ENVIRONMENT_VARIABLE,
-    RECEIPT_FILE_NAME_TEMPLATE,
-    RECEIPT_FINDINGS_KEY,
     RECEIPT_HEAD_KEY,
-    RECEIPT_RULED_OUT_KEY,
-    RECEIPT_RULINGS_KEY,
     REPO_FIELD,
     REPO_OPTION_PATTERN,
     REPOSITORY_SEPARATOR,
     REVIEW_COMMAND_ENVIRONMENT_VARIABLE,
-    RULINGS_LINK_PATTERN,
     STALE_REVIEW_REASON_TEMPLATE,
+    UNKNOWN_OPEN_TARGET_REASON,
     UNKNOWN_TARGET_REASON,
     UNPINNED_MERGE_REASON_TEMPLATE,
 )
@@ -101,31 +106,25 @@ class MergeRequest:
         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.
+def open_deny_reason(request: OpenRequest) -> str | None:
+    """Return why a pull request open must wait for a clean review, or None to allow it.
 
     Args:
-        owner: Repository owner.
-        repo: Repository name.
-        number: Pull request number.
+        request: The open the tool call asks for.
 
     Returns:
-        The receipt file path.
+        The deny reason, or None when the open may run.
     """
-    return receipt_directory() / RECEIPT_FILE_NAME_TEMPLATE.format(
-        owner=owner.casefold(), repo=repo.casefold(), number=number
+    if not request.owner or not request.repo:
+        return UNKNOWN_OPEN_TARGET_REASON
+    if _is_exempt(request.slug):
+        return None
+    if not request.head:
+        return UNKNOWN_OPEN_TARGET_REASON
+    if has_clean_open_review(request.repo, request.head):
+        return None
+    return NO_CLEAN_OPEN_REVIEW_REASON_TEMPLATE.format(
+        slug=request.slug, head=request.head, review_command=_review_command()
     )
 
 
@@ -216,15 +215,15 @@ def _without_option_values(arguments: str) -> str:
     return OPTION_WITH_VALUE_PATTERN.sub(" ", arguments)
 
 
-def _is_exempt(request: MergeRequest) -> bool:
+def _is_exempt(slug: str) -> 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
+    return slug.casefold() in all_exempt
 
 
-def _clean_head(request: MergeRequest) -> str | None:
+def _numbered_receipt(request: MergeRequest) -> dict[str, object] | None:
     if request.number is None:
         return None
     try:
@@ -233,78 +232,26 @@ def _clean_head(request: MergeRequest) -> str | None:
         )
     except (OSError, ValueError):
         return None
-    if not isinstance(receipt, dict) or not is_clean_receipt(
-        receipt, request.owner, request.repo, request.number
-    ):
-        return None
-    head = receipt.get(RECEIPT_HEAD_KEY)
-    return head if isinstance(head, str) and head else None
-
-
-def is_clean_receipt(
-    all_receipt_fields: dict[str, object], owner: str, repo: str, number: int
-) -> bool:
-    """Return whether a recorded pass lets the merge through.
+    return receipt if isinstance(receipt, dict) else None
 
-    A pass is clean when it reported zero findings, or when every finding it
-    reported is ruled out and the receipt links the rulings comment posted on
-    this same pull request::
 
-        findings 0                                                -> clean
-        findings 2, ruled out 2, .../acme/tools/pull/12#issuecomment-9 -> clean
-        findings 2, ruled out 2, .../acme/other/pull/12#issuecomment-9 -> not clean
-
-    Args:
-        all_receipt_fields: The parsed receipt of one review pass.
-        owner: Owner of the pull request the merge targets.
-        repo: Repository of the pull request the merge targets.
-        number: Number of the pull request the merge targets.
-
-    Returns:
-        True when the pass counts as clean.
-    """
-    finding_count = all_receipt_fields.get(RECEIPT_FINDINGS_KEY)
-    if not _is_count(finding_count):
-        return False
-    return finding_count == 0 or _rules_out_every_finding(
-        all_receipt_fields, finding_count, owner, repo, number
-    )
-
-
-def _is_count(candidate: object) -> bool:
-    return isinstance(candidate, int) and not isinstance(candidate, bool) and candidate >= 0
-
-
-def _rules_out_every_finding(
-    all_receipt_fields: dict[str, object], finding_count: object, owner: str, repo: str, number: int
-) -> bool:
-    ruled_out_count = all_receipt_fields.get(RECEIPT_RULED_OUT_KEY)
-    return (
-        _is_count(ruled_out_count)
-        and ruled_out_count == finding_count
-        and _links_rulings_on(all_receipt_fields.get(RECEIPT_RULINGS_KEY), owner, repo, number)
-    )
+def _receipt_head(all_receipt_fields: dict[str, object] | None) -> str | None:
+    head = all_receipt_fields.get(RECEIPT_HEAD_KEY) if all_receipt_fields else None
+    return head if isinstance(head, str) and head else None
 
 
-def _links_rulings_on(rulings: object, owner: str, repo: str, number: int) -> bool:
-    rulings_match = RULINGS_LINK_PATTERN.fullmatch(rulings) if isinstance(rulings, str) else None
-    return (
-        rulings_match is not None
-        and rulings_match["owner"].casefold() == owner.casefold()
-        and rulings_match["repo"].casefold() == repo.casefold()
-        and int(rulings_match["number"]) == number
-    )
+def _clean_head(request: MergeRequest, all_receipt_fields: dict[str, object] | None) -> str | None:
+    if all_receipt_fields is None or request.number is None:
+        return None
+    if not is_clean_receipt(all_receipt_fields, request.owner, request.repo, request.number):
+        return None
+    return _receipt_head(all_receipt_fields)
 
 
 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.
 
@@ -316,17 +263,30 @@ def deny_reason(request: MergeRequest) -> str | None:
     """
     if not request.owner or not request.repo or request.number is None:
         return UNKNOWN_TARGET_REASON
-    if _is_exempt(request):
+    if _is_exempt(request.slug):
+        return None
+    numbered_receipt = _numbered_receipt(request)
+    numbered_head = _receipt_head(numbered_receipt)
+    pass_on_pinned_head = (
+        numbered_head is not None
+        and request.pinned_head is not None
+        and same_commit(numbered_head, request.pinned_head)
+    )
+    if (
+        request.pinned_head
+        and not pass_on_pinned_head
+        and has_clean_open_review(request.repo, request.pinned_head)
+    ):
         return None
     fields = {"slug": request.slug, "number": request.number}
-    clean_head = _clean_head(request)
+    clean_head = _clean_head(request, numbered_receipt)
     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):
+    if not same_commit(clean_head, request.pinned_head):
         return STALE_REVIEW_REASON_TEMPLATE.format(
             head=clean_head, pinned=request.pinned_head, **fields
         )
@@ -334,7 +294,7 @@ def deny_reason(request: MergeRequest) -> str | 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.
+    """Return a deny decision for an open or merge with no clean review, else None.
 
     Args:
         all_payload_fields: The parsed PreToolUse input.
@@ -342,10 +302,11 @@ def decision_for(all_payload_fields: dict[str, object]) -> dict[str, object] | N
     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)
+    open_request = open_request_from(all_payload_fields)
+    merge_request = merge_request_from(all_payload_fields)
+    reason = (open_deny_reason(open_request) if open_request is not None else None) or (
+        deny_reason(merge_request) if merge_request is not None else None
+    )
     if reason is None:
         return None
     return {

package/hooks/blocking/merge_review_gate_parts/__init__.py

@@ -0,0 +1 @@
+"""Decomposed concern modules the ``merge_review_gate`` entry hook wires together."""

package/hooks/blocking/merge_review_gate_parts/open_request.py

@@ -0,0 +1,163 @@
+"""Read the pull request open a PreToolUse payload asks for, and the head it opens with."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+hooks_directory = str(Path(__file__).resolve().parent.parent.parent)
+if hooks_directory not in sys.path:
+    sys.path.insert(0, hooks_directory)
+
+from hooks_constants.merge_review_gate_constants import (
+    ALL_ORIGIN_URL_ARGUMENTS,
+    ALL_SHELL_TOOL_NAMES,
+    CHANGE_FOLDER_PATTERN,
+    CREATE_TEXT_OPTION_PATTERN,
+    CREATE_TOOL_SUFFIX,
+    CURRENT_HEAD_REFERENCE,
+    CWD_FIELD,
+    GH_PR_CREATE_PATTERN,
+    GIT_TIMEOUT_SECONDS,
+    HEAD_BRANCH_FIELD,
+    HEAD_OPTION_PATTERN,
+    ORIGIN_URL_PATTERN,
+    OWNER_FIELD,
+    PULL_REQUEST_SCRIPT_CREATE_PATTERN,
+    REMOTE_BRANCH_PREFIX,
+    REPO_FIELD,
+    REPO_OPTION_PATTERN,
+)
+
+
+@dataclass(frozen=True)
+class OpenRequest:
+    """One pull request a tool call asks to open.
+
+    Attributes:
+        owner: Repository owner, or empty when it could not be read.
+        repo: Repository name, or empty when it could not be read.
+        head: The commit the pull request would open with, or None.
+    """
+
+    owner: str
+    repo: str
+    head: str | None
+
+    @property
+    def slug(self) -> str:
+        """Return ``owner/repo``."""
+        return f"{self.owner}/{self.repo}"
+
+
+def open_request_from(all_payload_fields: dict[str, object]) -> OpenRequest | None:
+    """Read the pull request open a PreToolUse payload asks for.
+
+    ::
+
+        mcp__github__create_pull_request {owner, repo, head}
+        gh pr create --repo o/r --head branch
+        python pull_request.py create --repo o/r --head branch
+
+    A branch resolves in the payload's folder or a ``cd`` target, as
+    ``origin/<branch>`` first. No head means ``HEAD``; no repository, ``origin``.
+
+    Args:
+        all_payload_fields: The parsed PreToolUse input.
+
+    Returns:
+        The open request, or None when the call opens no pull request.
+    """
+    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
+    working_folder = all_payload_fields.get(CWD_FIELD)
+    folder = working_folder if isinstance(working_folder, str) and working_folder else None
+    if tool_name.endswith(CREATE_TOOL_SUFFIX):
+        return _tool_open_request(tool_input, folder)
+    command = tool_input.get("command")
+    if tool_name not in ALL_SHELL_TOOL_NAMES or not isinstance(command, str):
+        return None
+    return _shell_open_request(command, folder)
+
+
+def _tool_open_request(all_tool_input: dict[object, object], folder: str | None) -> OpenRequest:
+    branch = all_tool_input.get(HEAD_BRANCH_FIELD)
+    return OpenRequest(
+        owner=str(all_tool_input.get(OWNER_FIELD, "")),
+        repo=str(all_tool_input.get(REPO_FIELD, "")),
+        head=_branch_commit(branch, folder) if isinstance(branch, str) and branch else None,
+    )
+
+
+def _shell_open_request(command: str, folder: str | None) -> OpenRequest | None:
+    options_only = CREATE_TEXT_OPTION_PATTERN.sub(" ", command)
+    create_match = GH_PR_CREATE_PATTERN.search(
+        options_only
+    ) or PULL_REQUEST_SCRIPT_CREATE_PATTERN.search(options_only)
+    if not create_match:
+        return None
+    folder = _folder_after_changes(options_only[: create_match.start()], folder)
+    rest = create_match["rest"]
+    repo_match = REPO_OPTION_PATTERN.search(rest)
+    owner, repo = (
+        (repo_match["owner"], repo_match["repo"]) if repo_match else _origin_repository(folder)
+    )
+    head_match = HEAD_OPTION_PATTERN.search(rest)
+    branch = head_match["head"] if head_match else CURRENT_HEAD_REFERENCE
+    return OpenRequest(owner=owner, repo=repo, head=_branch_commit(branch, folder))
+
+
+def _folder_after_changes(command_before_create: str, folder: str | None) -> str | None:
+    all_changes = list(CHANGE_FOLDER_PATTERN.finditer(command_before_create))
+    if not all_changes:
+        return folder
+    target = Path(os.path.expanduser(all_changes[-1]["folder"].strip("\"'")))
+    if not target.is_absolute() and folder:
+        target = Path(folder) / target
+    return str(target)
+
+
+def _run_git(all_arguments: list[str], folder: str | None) -> str | None:
+    try:
+        completed = subprocess.run(
+            ["git", *all_arguments],
+            cwd=folder,
+            capture_output=True,
+            text=True,
+            timeout=GIT_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if completed.returncode != 0:
+        return None
+    return completed.stdout.strip() or None
+
+
+def _branch_commit(branch: str, folder: str | None) -> str | None:
+    branch_name = branch.split(":", 1)[-1]
+    all_references = (
+        (branch_name,)
+        if branch_name == CURRENT_HEAD_REFERENCE
+        else (REMOTE_BRANCH_PREFIX + branch_name, branch_name)
+    )
+    for each_reference in all_references:
+        commit = _run_git(
+            ["rev-parse", "--verify", "--quiet", f"{each_reference}^{{commit}}"], folder
+        )
+        if commit:
+            return commit
+    return None
+
+
+def _origin_repository(folder: str | None) -> tuple[str, str]:
+    origin_url = _run_git(list(ALL_ORIGIN_URL_ARGUMENTS), folder)
+    origin_match = ORIGIN_URL_PATTERN.search(origin_url) if origin_url else None
+    if not origin_match:
+        return "", ""
+    return origin_match["owner"], origin_match["repo"]

package/hooks/blocking/merge_review_gate_parts/receipts.py

@@ -0,0 +1,192 @@
+"""Read the review receipts ``scripts/merge_review_receipt.py`` writes.
+
+A numbered receipt covers one pull request. An open receipt covers one head
+reviewed before its pull request opened.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+hooks_directory = str(Path(__file__).resolve().parent.parent.parent)
+if hooks_directory not in sys.path:
+    sys.path.insert(0, hooks_directory)
+
+from hooks_constants.merge_review_gate_constants import (
+    ALL_RECEIPT_DIRECTORY_SEGMENTS,
+    OPEN_HEAD_PATTERN,
+    OPEN_RECEIPT_DIRECTORY_NAME,
+    OPEN_RECEIPT_FILE_NAME_TEMPLATE,
+    OPEN_RECEIPT_GLOB_TEMPLATE,
+    OPEN_RECEIPT_HEAD_PATTERN,
+    RECEIPT_DIRECTORY_ENVIRONMENT_VARIABLE,
+    RECEIPT_FILE_NAME_TEMPLATE,
+    RECEIPT_FINDINGS_KEY,
+    RECEIPT_HEAD_KEY,
+    RECEIPT_RULED_OUT_KEY,
+    RECEIPT_RULINGS_KEY,
+    RULINGS_LINK_PATTERN,
+)
+
+
+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 open_receipt_path(owner: str, repo: str, head: str) -> Path:
+    """Return where the review receipt for a head reviewed before its pull request opened lives.
+
+    Args:
+        owner: Repository owner.
+        repo: Repository name.
+        head: The commit the pass reviewed.
+
+    Returns:
+        The receipt file path.
+    """
+    return (
+        receipt_directory()
+        / OPEN_RECEIPT_DIRECTORY_NAME
+        / OPEN_RECEIPT_FILE_NAME_TEMPLATE.format(
+            owner=owner.casefold(), repo=repo.casefold(), head=head.casefold()
+        )
+    )
+
+
+def has_clean_open_review(repo: str, head: str) -> bool:
+    """Return whether a pass recorded before the pull request opened found zero findings at a head.
+
+    The head may be a full or an abbreviated commit, matched against each
+    recorded head by prefix. The owner is left out of the match, since a
+    checkout whose origin still names a transferred repository's old owner
+    opens against the new one::
+
+        open receipt {head: abc1234..., findings: 0}, head abc1234 -> True
+        open receipt {head: abc1234..., findings: 2}, head abc1234 -> False
+        no open receipt for the repository                          -> False
+
+    Args:
+        repo: Repository name.
+        head: The commit the open or merge names.
+
+    Returns:
+        True when a clean open receipt covers that head.
+    """
+    if not OPEN_HEAD_PATTERN.fullmatch(head):
+        return False
+    folder = receipt_directory() / OPEN_RECEIPT_DIRECTORY_NAME
+    pattern = OPEN_RECEIPT_GLOB_TEMPLATE.format(repo=repo.casefold())
+    return any(_is_clean_open_receipt(each_path, head) for each_path in folder.glob(pattern))
+
+
+def _is_clean_open_receipt(path: Path, head: str) -> bool:
+    try:
+        all_receipt_fields = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return False
+    if not isinstance(all_receipt_fields, dict):
+        return False
+    recorded_head = all_receipt_fields.get(RECEIPT_HEAD_KEY)
+    return (
+        isinstance(recorded_head, str)
+        and OPEN_RECEIPT_HEAD_PATTERN.fullmatch(recorded_head) is not None
+        and same_commit(recorded_head, head)
+        and _is_count(all_receipt_fields.get(RECEIPT_FINDINGS_KEY))
+        and all_receipt_fields.get(RECEIPT_FINDINGS_KEY) == 0
+    )
+
+
+def is_clean_receipt(
+    all_receipt_fields: dict[str, object], owner: str, repo: str, number: int
+) -> bool:
+    """Return whether a recorded pass lets the merge through.
+
+    A pass is clean when it reported zero findings, or when every finding it
+    reported is ruled out and the receipt links the rulings comment posted on
+    this same pull request::
+
+        findings 0                                                -> clean
+        findings 2, ruled out 2, .../acme/tools/pull/12#issuecomment-9 -> clean
+        findings 2, ruled out 2, .../acme/other/pull/12#issuecomment-9 -> not clean
+
+    Args:
+        all_receipt_fields: The parsed receipt of one review pass.
+        owner: Owner of the pull request the merge targets.
+        repo: Repository of the pull request the merge targets.
+        number: Number of the pull request the merge targets.
+
+    Returns:
+        True when the pass counts as clean.
+    """
+    finding_count = all_receipt_fields.get(RECEIPT_FINDINGS_KEY)
+    if not _is_count(finding_count):
+        return False
+    return finding_count == 0 or _rules_out_every_finding(
+        all_receipt_fields, finding_count, owner, repo, number
+    )
+
+
+def same_commit(first: str, second: str) -> bool:
+    """Return whether two commit names match, one being a prefix of the other.
+
+    Args:
+        first: A full or abbreviated commit.
+        second: A full or abbreviated commit.
+
+    Returns:
+        True when the shorter name starts the longer one.
+    """
+    shorter, longer = sorted((first.casefold(), second.casefold()), key=len)
+    return longer.startswith(shorter)
+
+
+def _is_count(candidate: object) -> bool:
+    return isinstance(candidate, int) and not isinstance(candidate, bool) and candidate >= 0
+
+
+def _rules_out_every_finding(
+    all_receipt_fields: dict[str, object], finding_count: object, owner: str, repo: str, number: int
+) -> bool:
+    ruled_out_count = all_receipt_fields.get(RECEIPT_RULED_OUT_KEY)
+    return (
+        _is_count(ruled_out_count)
+        and ruled_out_count == finding_count
+        and _links_rulings_on(all_receipt_fields.get(RECEIPT_RULINGS_KEY), owner, repo, number)
+    )
+
+
+def _links_rulings_on(rulings: object, owner: str, repo: str, number: int) -> bool:
+    rulings_match = RULINGS_LINK_PATTERN.fullmatch(rulings) if isinstance(rulings, str) else None
+    return (
+        rulings_match is not None
+        and rulings_match["owner"].casefold() == owner.casefold()
+        and rulings_match["repo"].casefold() == repo.casefold()
+        and int(rulings_match["number"]) == number
+    )

package/hooks/blocking/test_merge_review_gate.py

@@ -1,5 +1,6 @@
 """Behavior tests for the clean-review merge gate."""
 
+import subprocess
 import sys
 from pathlib import Path
 
@@ -199,3 +200,220 @@ 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))
+
+
+def _git(folder: Path, *all_arguments: str) -> str:
+    completed = subprocess.run(
+        ["git", "-C", str(folder), *all_arguments], capture_output=True, text=True, check=True
+    )
+    return completed.stdout.strip()
+
+
+@pytest.fixture
+def branch_checkout(tmp_path: Path) -> tuple[Path, str]:
+    folder = tmp_path / "checkout"
+    folder.mkdir()
+    _git(folder, "init", "--quiet", "--initial-branch", "main")
+    _git(folder, "remote", "add", "origin", "https://github.com/acme/tools.git")
+    _git(folder, "checkout", "--quiet", "-b", "feature")
+    _git(
+        folder,
+        "-c",
+        "user.name=t",
+        "-c",
+        "user.email=t@example.com",
+        "commit",
+        "--quiet",
+        "--allow-empty",
+        "-m",
+        "first",
+    )
+    return folder, _git(folder, "rev-parse", "HEAD")
+
+
+def _create_tool(folder: Path, head: str = "feature") -> dict[str, object]:
+    return {
+        "tool_name": "mcp__github__create_pull_request",
+        "tool_input": {"owner": "acme", "repo": "tools", "head": head, "base": "main"},
+        "cwd": str(folder),
+    }
+
+
+def _bash_in(folder: Path, command: str) -> dict[str, object]:
+    return {"tool_name": "Bash", "tool_input": {"command": command}, "cwd": str(folder)}
+
+
+def test_should_deny_a_pull_request_open_with_no_review(branch_checkout: tuple[Path, str]) -> None:
+    folder, head = branch_checkout
+    reason = _reason(_create_tool(folder))
+    assert f"no clean review for head {head}" in reason
+    assert f"acme/tools open {head} 0" in reason
+
+
+def test_should_allow_a_pull_request_open_reviewed_clean_at_its_head(
+    branch_checkout: tuple[Path, str],
+) -> None:
+    folder, head = branch_checkout
+    merge_review_receipt.record_open_review("acme/tools", head, 0)
+    assert _reason(_create_tool(folder)) is None
+
+
+def test_should_deny_a_pull_request_open_whose_pass_found_findings(
+    branch_checkout: tuple[Path, str],
+) -> None:
+    folder, head = branch_checkout
+    merge_review_receipt.record_open_review("acme/tools", head, 2)
+    assert "no clean review" in _reason(_create_tool(folder))
+
+
+def test_should_deny_a_pull_request_open_after_a_push_past_the_review(
+    branch_checkout: tuple[Path, str],
+) -> None:
+    folder, _head = branch_checkout
+    merge_review_receipt.record_open_review("acme/tools", NEW_HEAD, 0)
+    assert "no clean review" in _reason(_create_tool(folder))
+
+
+def test_should_read_gh_pr_create_with_repo_and_head(branch_checkout: tuple[Path, str]) -> None:
+    folder, head = branch_checkout
+    command = "gh pr create --repo acme/tools --head feature --title t --body b"
+    assert "no clean review" in _reason(_bash_in(folder, command))
+    merge_review_receipt.record_open_review("acme/tools", head, 0)
+    assert _reason(_bash_in(folder, command)) is None
+
+
+def test_should_read_gh_pr_create_repository_from_origin(branch_checkout: tuple[Path, str]) -> None:
+    folder, head = branch_checkout
+    merge_review_receipt.record_open_review("acme/tools", head, 0)
+    assert _reason(_bash_in(folder, "gh pr create --fill")) is None
+
+
+def test_should_read_the_pull_request_script_create(branch_checkout: tuple[Path, str]) -> None:
+    folder, head = branch_checkout
+    command = "python scripts/pull_request.py create --repo acme/tools --head feature"
+    assert f"head {head}" in _reason(_bash_in(folder, command))
+
+
+def test_should_deny_a_pull_request_open_whose_head_cannot_be_read(tmp_path: Path) -> None:
+    reason = _reason(_create_tool(tmp_path, head="missing-branch"))
+    assert "names no repository or head commit" in reason
+
+
+def test_should_allow_a_pull_request_open_in_an_exempt_repository(
+    branch_checkout: tuple[Path, str], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    folder, _head = branch_checkout
+    monkeypatch.setenv("CLAUDE_MERGE_REVIEW_EXEMPT_REPOSITORIES", "acme/tools")
+    assert _reason(_create_tool(folder)) is None
+
+
+def test_should_allow_a_merge_pinned_to_the_head_reviewed_clean_before_open() -> None:
+    merge_review_receipt.record_open_review("acme/tools", CLEAN_HEAD, 0)
+    assert _reason(_merge_tool(CLEAN_HEAD)) is None
+    command = f"gh pr merge 12 --repo acme/tools --match-head-commit {CLEAN_HEAD[:7]}"
+    assert _reason(_bash(command)) is None
+
+
+def test_should_deny_a_merge_pinned_past_the_head_reviewed_before_open() -> None:
+    merge_review_receipt.record_open_review("acme/tools", CLEAN_HEAD, 0)
+    assert "no clean review" in _reason(_merge_tool(NEW_HEAD))
+
+
+def test_should_deny_an_unpinned_merge_with_only_an_open_review() -> None:
+    merge_review_receipt.record_open_review("acme/tools", CLEAN_HEAD, 0)
+    assert "no clean review" in _reason(_merge_tool())
+
+
+def test_should_not_accept_an_open_review_from_another_repository() -> None:
+    merge_review_receipt.record_open_review("acme/other", CLEAN_HEAD, 0)
+    assert "no clean review" in _reason(_merge_tool(CLEAN_HEAD))
+
+
+def test_should_accept_an_open_review_recorded_under_the_old_owner() -> None:
+    merge_review_receipt.record_open_review("oldowner/tools", CLEAN_HEAD, 0)
+    assert _reason(_merge_tool(CLEAN_HEAD)) is None
+
+
+def test_should_deny_a_merge_whose_numbered_pass_found_findings_at_the_open_reviewed_head() -> None:
+    merge_review_receipt.record_open_review("acme/tools", CLEAN_HEAD, 0)
+    merge_review_receipt.record_review("acme/tools", 12, CLEAN_HEAD, 2)
+    assert "no clean review" in _reason(_merge_tool(CLEAN_HEAD))
+
+
+def test_should_ignore_an_open_receipt_whose_head_is_not_a_commit(receipt_folder: Path) -> None:
+    heads_folder = receipt_folder / "heads"
+    heads_folder.mkdir()
+    (heads_folder / "acme__tools__a.json").write_text('{"head": "a", "findings": 0}', encoding="utf-8")
+    assert "no clean review" in _reason(_merge_tool(CLEAN_HEAD))
+
+
+def test_should_check_a_merge_chained_after_a_reviewed_open(
+    branch_checkout: tuple[Path, str],
+) -> None:
+    folder, head = branch_checkout
+    merge_review_receipt.record_open_review("acme/tools", head, 0)
+    command = (
+        "gh pr create --repo acme/tools --head feature --fill && "
+        f"gh pr merge 12 --repo acme/tools --match-head-commit {NEW_HEAD}"
+    )
+    assert "no clean review" in _reason(_bash_in(folder, command))
+
+
+def test_should_read_the_pushed_branch_before_the_local_one(
+    branch_checkout: tuple[Path, str],
+) -> None:
+    folder, local_head = branch_checkout
+    _git(
+        folder,
+        "-c",
+        "user.name=t",
+        "-c",
+        "user.email=t@example.com",
+        "commit",
+        "--quiet",
+        "--allow-empty",
+        "-m",
+        "pushed",
+    )
+    pushed_head = _git(folder, "rev-parse", "HEAD")
+    _git(folder, "update-ref", "refs/remotes/origin/feature", pushed_head)
+    _git(folder, "reset", "--quiet", "--hard", local_head)
+    merge_review_receipt.record_open_review("acme/tools", local_head, 0)
+    assert f"head {pushed_head}" in _reason(_create_tool(folder))
+
+
+def test_should_not_match_an_open_receipt_on_a_short_pinned_head() -> None:
+    merge_review_receipt.record_open_review("acme/tools", CLEAN_HEAD, 0)
+    assert "no clean review" in _reason(_merge_tool(CLEAN_HEAD[:3]))
+
+
+def test_should_allow_an_open_in_an_exempt_repository_with_an_unread_head(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv("CLAUDE_MERGE_REVIEW_EXEMPT_REPOSITORIES", "acme/tools")
+    assert _reason(_create_tool(tmp_path, head="missing-branch")) is None
+
+
+def test_should_skip_options_quoted_inside_the_title_or_body(
+    branch_checkout: tuple[Path, str],
+) -> None:
+    folder, head = branch_checkout
+    merge_review_receipt.record_open_review("acme/tools", head, 0)
+    command = (
+        "gh pr create --repo acme/tools --title 'use -R other/x' "
+        f"--body \"curl -H 'Accept: x'; -H {NEW_HEAD}\" --head feature"
+    )
+    assert _reason(_bash_in(folder, command)) is None
+
+
+def test_should_read_the_head_in_the_folder_a_cd_moves_to(
+    branch_checkout: tuple[Path, str], tmp_path: Path
+) -> None:
+    folder, head = branch_checkout
+    merge_review_receipt.record_open_review("acme/tools", head, 0)
+    elsewhere = tmp_path / "elsewhere"
+    elsewhere.mkdir()
+    assert _reason(_bash_in(elsewhere, f'cd "{folder}" && gh pr create --fill')) is None
+    assert "names no repository or head commit" in _reason(
+        _bash_in(folder, f'cd "{elsewhere}" && gh pr create --repo acme/tools --fill')
+    )

package/hooks/blocking/tests/test_open_request.py

@@ -0,0 +1,38 @@
+"""Behavioral tests for reading a pull request open from a PreToolUse payload.
+
+gh pr create --repo acme/tools --title "--head evil" -> acme/tools, quoted option ignored
+mcp create_pull_request {owner, repo}                -> acme/tools, no head
+gh pr merge 12                                       -> no open
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from blocking.merge_review_gate_parts.open_request import OpenRequest, open_request_from
+
+
+def _shell_payload(command: str, folder: Path) -> dict[str, object]:
+    return {"tool_name": "Bash", "tool_input": {"command": command}, "cwd": str(folder)}
+
+
+def test_should_read_the_repository_and_ignore_options_quoted_in_the_title(tmp_path: Path) -> None:
+    payload = _shell_payload('gh pr create --repo acme/tools --title "--head evil"', tmp_path)
+    assert open_request_from(payload) == OpenRequest(owner="acme", repo="tools", head=None)
+
+
+def test_should_read_the_create_tool_with_no_head_branch(tmp_path: Path) -> None:
+    payload = {
+        "tool_name": "mcp__github__create_pull_request",
+        "tool_input": {"owner": "acme", "repo": "tools"},
+        "cwd": str(tmp_path),
+    }
+    assert open_request_from(payload) == OpenRequest(owner="acme", repo="tools", head=None)
+
+
+def test_should_return_none_for_a_command_that_opens_nothing(tmp_path: Path) -> None:
+    assert open_request_from(_shell_payload("gh pr merge 12", tmp_path)) is None
+
+
+def test_should_name_the_slug_from_owner_and_repo() -> None:
+    assert OpenRequest(owner="acme", repo="tools", head=None).slug == "acme/tools"

package/hooks/blocking/tests/test_receipts.py

@@ -0,0 +1,57 @@
+"""Behavioral tests for the merge review receipt readers.
+
+open receipt {head: <full sha>, findings: 0}, head <short sha> -> clean
+open receipt {head: <full sha>, findings: 1}, head <short sha> -> not clean
+numbered receipt path                                         -> lowercased owner and repo
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+from blocking.merge_review_gate_parts.receipts import (
+    has_clean_open_review,
+    open_receipt_path,
+    receipt_path,
+    same_commit,
+)
+
+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 _write_open_receipt(finding_count: int) -> None:
+    path = open_receipt_path("acme", "tools", HEAD)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps({"head": HEAD, "findings": finding_count}), encoding="utf-8")
+
+
+def test_should_find_a_clean_open_review_by_short_head_under_any_owner() -> None:
+    _write_open_receipt(0)
+    assert has_clean_open_review("Tools", HEAD[:7]) is True
+
+
+def test_should_reject_an_open_review_that_counts_findings() -> None:
+    _write_open_receipt(1)
+    assert has_clean_open_review("tools", HEAD[:7]) is False
+
+
+def test_should_reject_a_head_that_is_not_a_commit() -> None:
+    _write_open_receipt(0)
+    assert has_clean_open_review("tools", "main") is False
+
+
+def test_should_lowercase_owner_and_repo_in_the_numbered_receipt_path(receipt_folder: Path) -> None:
+    assert receipt_path("Acme", "Tools", 12) == receipt_folder / "acme__tools__12.json"
+
+
+def test_should_match_commits_by_prefix_in_either_order() -> None:
+    assert same_commit(HEAD[:7].upper(), HEAD) is True
+    assert same_commit(HEAD, "def5678") is False

package/hooks/features/conduct-gates.md

@@ -20,7 +20,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
 - `blocking/resolve_thread_reply_gate.py` denies a review thread resolve until the agent's own transcript shows a reply on that same thread that posted after the last user prompt and that no successful resolve of the thread has spent. A resolve is a `resolve_review_thread` call, which names the thread by `threadID`; a `pull_request_review_write` call with method `resolve_thread`, which names it by `threadId`; a shell command with a `gh api graphql` `resolveReviewThread` mutation, which names it by a literal `PRRT_` id; or a shell call to `pulls/<n>/ccr/comments/<id>/resolve`, which names it by a comment id. A graphql resolve that names no `PRRT_` id is denied. A reply is an `add_reply_to_pull_request_comment` call, or a `gh api` call to a comment's `replies` endpoint or to `addPullRequestReviewThreadReply`, which names its thread by `PRRT_` id. A reply and a resolve by comment id match when they name the same comment, or when a successful tool result in the transcript, such as `pull_request_read` `get_review_comments`, lists the comment under the thread by its `discussion_r` anchor or `databaseId`. A reply whose result is an error, such as a refusal from `blocking/reply_length_gate.py`, does not count. With no readable transcript, the resolve passes.
 - `blocking/verify_before_commit_gate.py` denies a `git commit` in a repository with a `.claude/skills/verify` or `.agents/skills/verify` directory until the `verify` skill loads after the last user prompt, through a Skill call or the `/verify` command in that prompt. It reads the committed paths from the staged diff, the tracked changes for `-a`, and the paths of each `git add` earlier in the same command, and passes a commit whose paths are all docs, images, or test files.
 - `blocking/build_eval_before_eval_write_gate.py` denies a write to an eval file until a Skill call named exactly `claude-api` with args `build-eval`, or the `/claude-api build-eval` command, appears in the transcript.
-- `blocking/merge_review_gate.py` denies an agent's merge until a review pass on the merged head reported zero findings, or ruled out every finding and linked the posted rulings. 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. The reason tells the agent to run that command for the first three passes and `/code-review low --fix <number>` for each later pass; the gate itself counts no passes.
+- `blocking/merge_review_gate.py` denies an agent's merge until a review pass on the merged head reported zero findings, or ruled out every finding and linked the posted rulings. 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. The reason tells the agent to run that command for the first three passes and `/code-review low --fix <number>` for each later pass; the gate itself counts no passes. It also denies a pull request open, through `gh pr create`, `pull_request.py create` or a `create_pull_request` tool, until a pass recorded as `merge_review_receipt.py <owner/name> open <head> 0` covers the head the pull request opens with. A merge pinned to that same head passes on the open receipt.
 - `blocking/merge_over_review_offer_gate.py` denies a decision card or question that offers a merge while it names open review findings, a red check, unaddressed review comments, or an override. It reads the whole card as one text: every question, header, context, reason, and option, whether the option is a string or a label with a consequence or description.
 - `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.
 - `blocking/send_user_file_worktree_root_gate.py` denies a `SendUserFile` call that names a file outside the session's working directory, the `cwd` in the hook payload. The desktop file pane opens a sent file only under that folder and shows "Couldn't find this file" for any other path. The reason lists each outside file and names `<cwd>\.scratch\` as the folder to copy it into.
@@ -43,7 +43,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
 - `blocking/resolve_thread_reply_gate.py` runs on `PreToolUse`, matcher `Bash|PowerShell|mcp__.*__resolve_review_thread|mcp__.*__pull_request_review_write`, timeout `10` seconds in `hooks.json`.
 - `blocking/verify_before_commit_gate.py` runs on `PreToolUse`, matcher `Bash|PowerShell`, timeout `30` seconds in `hooks.json`.
 - `blocking/build_eval_before_eval_write_gate.py` runs on `PreToolUse`, matcher `Write|Edit|MultiEdit|NotebookEdit|apply_patch`, 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/merge_review_gate.py` runs on `PreToolUse`, matcher `Bash|PowerShell|mcp__.*__(create_pull_request|merge_pull_request|enable_pr_auto_merge)`, timeout `10` seconds in `hooks.json`.
 - `blocking/merge_over_review_offer_gate.py` runs on `PreToolUse`, matcher `AskUserQuestion|mcp__.*__ask_decision`, timeout `10` seconds in `hooks.json`.
 - `blocking/artifact_dark_mode_gate.py` runs on `PreToolUse`, matcher `Artifact`, timeout `60` seconds in `hooks.json`.
 - `blocking/send_user_file_worktree_root_gate.py` runs on `PreToolUse`, matcher `SendUserFile`, timeout `10` seconds in `hooks.json`.
@@ -70,7 +70,7 @@ Preconditions:
 - **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.
 - **Verify before commit.** Input is `git add app.py; git commit -m change` in a temporary repository with `.agents/skills/verify`, and a transcript with no `verify` load after its last prompt. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_verify_before_commit_gate.py -q`. The adjacent test observes a denial, then a silent allow after a `verify` Skill call or a `/verify` prompt. A load before the last prompt still denies. A docs-only commit, a tests-only commit, and a repository with no verify skill pass.
 - **Eval write.** Input is a Write to `evals/cases.json` with no build-eval call in the transcript. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_build_eval_before_eval_write_gate.py -q`. The adjacent test observes a denial, then an allow once the call appears; a write outside an eval path passes.
-- **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.
+- **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. An open with no clean open receipt at its head is denied; an open reviewed clean at its head, and a merge pinned to that head, pass.
 - **Merge offer.** Input is a decision card or AskUserQuestion that offers "Merge now", the merge queue, or a yes to "Merge it now?" while any part of the card names open findings or unaddressed review comments. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_merge_over_review_offer_gate.py -q`. The adjacent test observes a denial for each, including an offer and findings in separate questions; a card with no merge offer, a card about the merge review check itself, a card about shipping a docs change, and a merge offer after a clean review 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.
 - **Sent file root.** Input is a `SendUserFile` call for a file on `Y:\` or in the session scratchpad, with `cwd` set to a worktree. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_send_user_file_worktree_root_gate.py -q`. The adjacent test observes a denial that names the file and `<cwd>\.scratch\`; a file under `<cwd>\.scratch\` passes.

package/hooks/hooks.json

@@ -133,7 +133,7 @@
         ]
       },
       {
-        "matcher": "Bash|PowerShell|mcp__.*__(merge_pull_request|enable_pr_auto_merge)",
+        "matcher": "Bash|PowerShell|mcp__.*__(create_pull_request|merge_pull_request|enable_pr_auto_merge)",
         "hooks": [
           {
             "type": "command",

package/hooks/hooks_constants/merge_review_gate_constants.py

@@ -1,4 +1,4 @@
-"""Named constants for merge_review_gate, the clean-review merge gate."""
+"""Named constants for merge_review_gate, the clean-review open and merge gate."""
 
 from __future__ import annotations
 
@@ -10,12 +10,39 @@ PERMISSION_DECISION_REASON_KEY = "permissionDecisionReason"
 
 MERGE_TOOL_SUFFIX = "__merge_pull_request"
 AUTO_MERGE_TOOL_SUFFIX = "__enable_pr_auto_merge"
+CREATE_TOOL_SUFFIX = "__create_pull_request"
 ALL_SHELL_TOOL_NAMES = frozenset({"Bash", "PowerShell"})
 
 OWNER_FIELD = "owner"
 REPO_FIELD = "repo"
 NUMBER_FIELD = "pullNumber"
 EXPECTED_HEAD_FIELD = "expectedHeadSha"
+HEAD_BRANCH_FIELD = "head"
+CWD_FIELD = "cwd"
+
+GH_PR_CREATE_PATTERN = re.compile(r"(?:^|[\s;&|(])gh(?:\.exe)?\s+pr\s+create\b(?P<rest>[^;&|]*)")
+PULL_REQUEST_SCRIPT_CREATE_PATTERN = re.compile(
+    r"pull_request\.py[\"']?\s+create\b(?P<rest>[^;&|]*)"
+)
+HEAD_OPTION_PATTERN = re.compile(r"(?<!\S)(?:-H|--head)(?:=|\s+)[\"']?(?P<head>[^\s\"']+)")
+CHANGE_FOLDER_PATTERN = re.compile(
+    r"(?:^|[;&|(]\s*)(?:cd|pushd|Set-Location|sl)\s+(?:-Path\s+|-LiteralPath\s+)?"
+    r"(?P<folder>\"[^\"]*\"|'[^']*'|[^\s;&|)]+)",
+    re.IGNORECASE,
+)
+CREATE_TEXT_OPTION_PATTERN = re.compile(
+    r"(?<!\S)(?:-t|--title|-b|--body|-F|--body-file)(?:=|\s+)(?:\"[^\"]*\"|'[^']*'|\S+)"
+)
+ORIGIN_URL_PATTERN = re.compile(
+    r"github\.com[:/](?P<owner>[\w.-]+)/(?P<repo>[\w.-]+?)(?:\.git)?/?$"
+)
+GIT_TIMEOUT_SECONDS = 3
+ALL_ORIGIN_URL_ARGUMENTS = ("remote", "get-url", "origin")
+OPEN_HEAD_PATTERN = re.compile(r"[0-9a-fA-F]{7,40}")
+OPEN_RECEIPT_HEAD_PATTERN = re.compile(r"[0-9a-fA-F]{40}")
+REPOSITORY_SLUG_PATTERN = re.compile(r"[\w.-]+/[\w.-]+")
+REMOTE_BRANCH_PREFIX = "origin/"
+CURRENT_HEAD_REFERENCE = "HEAD"
 
 GH_PR_MERGE_PATTERN = re.compile(r"(?:^|[\s;&|(])gh(?:\.exe)?\s+pr\s+merge\b(?P<rest>[^;&|]*)")
 GH_API_MERGE_PATTERN = re.compile(
@@ -44,6 +71,10 @@ 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"
+OPEN_RECEIPT_DIRECTORY_NAME = "heads"
+OPEN_RECEIPT_FILE_NAME_TEMPLATE = "{owner}__{repo}__{head}.json"
+OPEN_RECEIPT_GLOB_TEMPLATE = "*__{repo}__*.json"
+OPEN_TARGET_WORD = "open"
 REPOSITORY_SEPARATOR = ","
 RECEIPT_HEAD_KEY = "head"
 RECEIPT_FINDINGS_KEY = "findings"
@@ -84,3 +115,17 @@ 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>`."
 )
+NO_CLEAN_OPEN_REVIEW_REASON_TEMPLATE = (
+    "{slug} has no clean review for head {head}, which this pull request would open with. "
+    "Review the branch diff with `{review_command}`, fix and push every finding, and review "
+    "again until a pass reports zero findings. Record that pass with `"
+    + RECORD_COMMAND
+    + " {slug} "
+    + OPEN_TARGET_WORD
+    + " {head} 0`, then open the pull request. The merge accepts that receipt while the "
+    "head stays {head}."
+)
+UNKNOWN_OPEN_TARGET_REASON = (
+    "This pull request names no repository or head commit the review gate can read. Run it "
+    "from the branch checkout, or pass `--repo owner/name` and `--head <pushed branch>`."
+)

package/package.json

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

package/scripts/merge_review_receipt.py

@@ -13,8 +13,14 @@ clean once the rulings are posted and linked::
     python3 merge_review_receipt.py owner/name 12 def5678 2 --ruled-out 2 --rulings <url>
         -> CLEAN owner/name#12 def5678 (2 findings ruled out: <url>)
 
+A pass run before the pull request exists names ``open`` in place of the
+number, and records the head it reviewed::
+
+    python3 merge_review_receipt.py owner/name open def5678 0   -> CLEAN owner/name open def5678
+
 ``hooks/blocking/merge_review_gate.py`` allows a merge pinned to the head of
-the newest pass only when that pass is clean.
+the newest pass only when that pass is clean. It allows a pull request open
+whose head has a clean ``open`` pass, and a merge pinned to that same head.
 """
 
 from __future__ import annotations
@@ -30,12 +36,19 @@ 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 is_clean_receipt, receipt_path
+from blocking.merge_review_gate_parts.receipts import (
+    is_clean_receipt,
+    open_receipt_path,
+    receipt_path,
+)
 from hooks_constants.merge_review_gate_constants import (
+    OPEN_RECEIPT_HEAD_PATTERN,
+    OPEN_TARGET_WORD,
     RECEIPT_FINDINGS_KEY,
     RECEIPT_HEAD_KEY,
     RECEIPT_RULED_OUT_KEY,
     RECEIPT_RULINGS_KEY,
+    REPOSITORY_SLUG_PATTERN,
 )
 
 
@@ -64,9 +77,29 @@ def record_review(
     return _write_receipt(slug, number, receipt)
 
 
+def record_open_review(slug: str, head: str, finding_count: int) -> Path:
+    """Write the receipt for one review pass run before the pull request opens.
+
+    Args:
+        slug: Repository as ``owner/name``.
+        head: The commit the pass reviewed.
+        finding_count: How many findings the pass reported.
+
+    Returns:
+        The receipt path written.
+    """
+    owner, repo = slug.split("/", 1)
+    return _write_receipt_at(
+        open_receipt_path(owner, repo, head), _receipt_fields(head, finding_count, 0, "")
+    )
+
+
 def _write_receipt(slug: str, number: int, all_receipt_fields: dict[str, object]) -> Path:
     owner, repo = slug.split("/", 1)
-    path = receipt_path(owner, repo, number)
+    return _write_receipt_at(receipt_path(owner, repo, number), all_receipt_fields)
+
+
+def _write_receipt_at(path: Path, all_receipt_fields: dict[str, object]) -> Path:
     path.parent.mkdir(parents=True, exist_ok=True)
     path.write_text(json.dumps(all_receipt_fields) + "\n", encoding="utf-8")
     return path
@@ -94,7 +127,9 @@ def main(all_arguments: Sequence[str], stdout: TextIO = sys.stdout) -> int:
     """
     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(
+        "number", help=f"Pull request number, or {OPEN_TARGET_WORD} before the pull request opens."
+    )
     parser.add_argument("head", help="The head commit the pass reviewed.")
     parser.add_argument("findings", type=int, help="Findings the pass reported.")
     parser.add_argument(
@@ -103,6 +138,23 @@ def main(all_arguments: Sequence[str], stdout: TextIO = sys.stdout) -> int:
     parser.add_argument("--rulings", default="", help="Link to the posted rulings.")
     parsed = parser.parse_args(all_arguments)
     rulings = parsed.rulings.strip()
+    if not REPOSITORY_SLUG_PATTERN.fullmatch(parsed.slug) or ".." in parsed.slug:
+        parser.error("slug must be owner/name")
+    if parsed.number == OPEN_TARGET_WORD:
+        if parsed.ruled_out or rulings:
+            parser.error(f"an {OPEN_TARGET_WORD} pass is clean only at zero findings")
+        if parsed.findings < 0:
+            parser.error("findings must be zero or more")
+        if not OPEN_RECEIPT_HEAD_PATTERN.fullmatch(parsed.head):
+            parser.error(f"an {OPEN_TARGET_WORD} pass needs the full 40 character commit")
+        record_open_review(parsed.slug, parsed.head, parsed.findings)
+        verdict = "CLEAN" if parsed.findings == 0 else "REVIEWED"
+        count_note = "" if parsed.findings == 0 else f" {parsed.findings} findings"
+        stdout.write(f"{verdict} {parsed.slug} {OPEN_TARGET_WORD} {parsed.head}{count_note}\n")
+        return 0 if parsed.findings == 0 else 1
+    if not parsed.number.isdigit():
+        parser.error(f"number must be a pull request number or {OPEN_TARGET_WORD}")
+    parsed.number = int(parsed.number)
     if parsed.ruled_out < 0 or parsed.ruled_out > parsed.findings:
         parser.error("--ruled-out must be between 0 and the finding count")
     if parsed.ruled_out and not rulings:

package/scripts/test_merge_review_receipt.py

@@ -122,3 +122,56 @@ def test_should_report_reviewed_when_the_rulings_link_points_at_another_pull_req
     )
     assert exit_code == 1
     assert verdict_stream.getvalue() == f"REVIEWED acme/tools#12 {HEAD} 2 findings\n"
+
+
+def test_should_record_a_clean_open_pass_under_heads(receipt_folder: Path) -> None:
+    verdict_stream = StringIO()
+    assert merge_review_receipt.main(["acme/tools", "open", HEAD, "0"], verdict_stream) == 0
+    assert verdict_stream.getvalue() == f"CLEAN acme/tools open {HEAD}\n"
+    receipt = json.loads((receipt_folder / "heads" / f"acme__tools__{HEAD}.json").read_text())
+    assert receipt == {"head": HEAD, "findings": 0}
+
+
+def test_record_open_review_writes_the_head_receipt_in_lowercase(receipt_folder: Path) -> None:
+    path = merge_review_receipt.record_open_review("Acme/Tools", HEAD.upper(), 2)
+    assert path == receipt_folder / "heads" / f"acme__tools__{HEAD}.json"
+    assert json.loads(path.read_text(encoding="utf-8")) == {"head": HEAD.upper(), "findings": 2}
+
+
+def test_should_exit_one_for_an_open_pass_with_findings() -> None:
+    verdict_stream = StringIO()
+    assert merge_review_receipt.main(["acme/tools", "open", HEAD, "2"], verdict_stream) == 1
+    assert verdict_stream.getvalue() == f"REVIEWED acme/tools open {HEAD} 2 findings\n"
+
+
+@pytest.mark.parametrize(
+    "all_arguments",
+    [
+        ["acme/tools", "open", HEAD, "-1"],
+        ["acme/tools", "open", HEAD, "2", "--ruled-out", "2", "--rulings", RULINGS_LINK],
+        ["acme/tools", "twelve", HEAD, "0"],
+    ],
+)
+def test_should_refuse_an_open_pass_it_cannot_record(
+    all_arguments: list[str], receipt_folder: Path
+) -> None:
+    with pytest.raises(SystemExit):
+        merge_review_receipt.main(all_arguments, StringIO())
+    assert list(receipt_folder.iterdir()) == []
+
+
+@pytest.mark.parametrize("head", ["abc", "abc1234", "../../escape", "zzzzzzz"])
+def test_should_refuse_an_open_pass_whose_head_is_not_a_commit(head: str, receipt_folder: Path) -> None:
+    with pytest.raises(SystemExit):
+        merge_review_receipt.main(["acme/tools", "open", head, "0"], StringIO())
+    assert list(receipt_folder.iterdir()) == []
+
+
+@pytest.mark.parametrize("slug", ["owner-repo", "a/b/../c", "a/.."])
+@pytest.mark.parametrize("number", ["open", "12"])
+def test_should_refuse_a_slug_that_is_not_owner_and_name(
+    slug: str, number: str, receipt_folder: Path
+) -> None:
+    with pytest.raises(SystemExit):
+        merge_review_receipt.main([slug, number, HEAD, "0"], StringIO())
+    assert list(receipt_folder.iterdir()) == []