claude-dev-env 8.99.1 → 8.100.1

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/test_verify_before_commit_gate.py

@@ -43,13 +43,32 @@ TOOL_RESULT_ENTRY = {
     },
 }
 
+REFUSED_TOOL_RESULT_ENTRY = {
+    "type": "user",
+    "message": {
+        "content": [
+            {
+                "type": "tool_result",
+                "tool_use_id": "toolu_1",
+                "content": "<tool_use_error>Skill verify cannot be used with Skill tool</tool_use_error>",
+                "is_error": True,
+            }
+        ]
+    },
+}
+
 
 def _skill_entry(skill_name: str) -> dict[str, object]:
     return {
         "type": "assistant",
         "message": {
             "content": [
-                {"type": "tool_use", "name": "Skill", "input": {"skill": skill_name}}
+                {
+                    "type": "tool_use",
+                    "id": "toolu_1",
+                    "name": "Skill",
+                    "input": {"skill": skill_name},
+                }
             ]
         },
     }
@@ -197,6 +216,33 @@ def test_docs_only_commit_passes(repository: Path, tmp_path: Path) -> None:
     )
 
 
+def test_data_files_under_docs_folder_pass(repository: Path, tmp_path: Path) -> None:
+    (repository / "docs" / "records").mkdir(parents=True)
+    (repository / "docs" / "records" / "proof.json").write_text("{}\n", encoding="utf-8")
+    (repository / "docs" / "ruleset.yaml").write_text("rules: []\n", encoding="utf-8")
+    _git(repository, "add", "-A")
+    assert not _is_denied(
+        _payload("git commit -m records", repository, _unverified(tmp_path))
+    )
+
+
+def test_code_under_docs_folder_is_denied(repository: Path, tmp_path: Path) -> None:
+    (repository / "docs").mkdir()
+    (repository / "docs" / "conf.py").write_text("VALUE = 2\n", encoding="utf-8")
+    _git(repository, "add", "-A")
+    assert _is_denied(
+        _payload("git commit -m conf", repository, _unverified(tmp_path))
+    )
+
+
+def test_json_outside_docs_folder_is_denied(repository: Path, tmp_path: Path) -> None:
+    (repository / "config.json").write_text("{}\n", encoding="utf-8")
+    _git(repository, "add", "-A")
+    assert _is_denied(
+        _payload("git commit -m config", repository, _unverified(tmp_path))
+    )
+
+
 def test_tests_only_commit_passes(repository: Path, tmp_path: Path) -> None:
     (repository / "test_app.py").write_text(
         "def test_value() -> None:\n    pass\n", encoding="utf-8"
@@ -219,6 +265,15 @@ def test_docs_plus_code_commit_is_denied(repository: Path, tmp_path: Path) -> No
     )
 
 
+def test_refused_verify_skill_call_is_denied(repository: Path, tmp_path: Path) -> None:
+    (repository / "app.py").write_text("VALUE = 2\n", encoding="utf-8")
+    _git(repository, "add", "app.py")
+    transcript_path = _transcript(
+        tmp_path, PROMPT_ENTRY, _skill_entry("verify"), REFUSED_TOOL_RESULT_ENTRY
+    )
+    assert _is_denied(_payload("git commit -m change", repository, transcript_path))
+
+
 def test_verify_skill_call_after_the_last_prompt_passes(
     repository: Path, tmp_path: Path
 ) -> None:

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/blocking/verify_before_commit_gate.py

@@ -33,6 +33,8 @@ from hooks_constants.verify_before_commit_gate_constants import (
     ALL_ADD_EVERYTHING_OPTIONS,
     ALL_COMMIT_ALL_OPTIONS,
     ALL_COMMIT_VALUED_SHORT_FLAGS,
+    ALL_DOCS_DATA_EXTENSIONS,
+    ALL_DOCS_DIRECTORY_NAMES,
     ALL_DOCS_EXTENSIONS,
     ALL_GIT_EXECUTABLES,
     ALL_SLASH_COMMAND_MARKERS,
@@ -176,7 +178,12 @@ def _is_docs_or_test_path(repository_path: str) -> bool:
     path = PurePosixPath(repository_path)
     if path.suffix.lower() in ALL_DOCS_EXTENSIONS or path.name in ALL_TEST_FILE_NAMES:
         return True
-    if any(each_part in ALL_TEST_DIRECTORY_NAMES for each_part in path.parts[:-1]):
+    all_directory_parts = path.parts[:-1]
+    if path.suffix.lower() in ALL_DOCS_DATA_EXTENSIONS and any(
+        each_part in ALL_DOCS_DIRECTORY_NAMES for each_part in all_directory_parts
+    ):
+        return True
+    if any(each_part in ALL_TEST_DIRECTORY_NAMES for each_part in all_directory_parts):
         return True
     return (
         path.name.startswith(ALL_TEST_FILE_PREFIXES)
@@ -245,6 +252,9 @@ def decision_for(all_payload_fields: dict[str, object]) -> dict[str, object] | N
         git commit, code staged, no verify since the last prompt      -> DENY_REASON
         git add app.py; git commit, empty index, no verify            -> DENY_REASON
         git commit, only docs or test files                           -> None
+        git commit, only data files (.json, .jsonl, .yaml, .yml,
+            .csv) under a docs folder                                 -> None
+        git commit, a .py file under a docs folder                    -> DENY_REASON
         git commit after a verify Skill call or a /verify prompt      -> None
         git commit in a repository with no verify skill directory     -> None
         transcript missing or unreadable, or git fails                -> None

package/hooks/features/conduct-gates.md

@@ -18,9 +18,9 @@ This family stops a chat reply, edited message, or tool call when its payload br
 - `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/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/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 whose result comes back without an error, 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, test files, or `.json`, `.jsonl`, `.yaml`, `.yml`, or `.csv` files under a `docs` folder.
 - `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`.
@@ -68,9 +68,9 @@ Preconditions:
 - **Step note.** Input is a tool call after a transcript message without a status line while the flag is on. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_step_note_gate.py -q`. The adjacent test observes a block until a status line appears.
 - **Checked claim.** Input is a Write after hedged reasoning in the transcript. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_verify_before_acting.py -q`. The adjacent test observes a block and a logged blocked outcome.
 - **Lifecycle skill.** Input is a `git commit` or `gh pr create` command with no `pr-lifecycle` invocation in the transcript. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_pr_lifecycle_skill_gate.py -q`. The adjacent test observes a denial, then a silent allow once the skill or its slash command appears.
-- **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.
+- **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 commit of data files under a `docs` folder, a tests-only commit, and a repository with no verify skill pass. A `.py` file under `docs` and a `.json` file outside `docs` still deny.
 - **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/hooks/hooks_constants/verify_before_commit_gate_constants.py

@@ -3,7 +3,7 @@
 DENY_REASON = (
     "This repository has a verify skill, and this commit changes code. Invoke the verify "
     "skill with the Skill tool, run the check it routes you to, then run the same command again. "
-    "A commit that changes only docs or tests passes without it."
+    "A commit that changes only docs, data files under a docs folder, or tests passes without it."
 )
 SKILL_NAME = "verify"
 ALL_SLASH_COMMAND_MARKERS = ("<command-name>/verify</command-name>",)
@@ -47,6 +47,8 @@ ALL_DOCS_EXTENSIONS = frozenset(
         ".ico",
     }
 )
+ALL_DOCS_DIRECTORY_NAMES = frozenset({"docs"})
+ALL_DOCS_DATA_EXTENSIONS = frozenset({".json", ".jsonl", ".yaml", ".yml", ".csv"})
 ALL_TEST_DIRECTORY_NAMES = frozenset({"tests", "test", "__tests__"})
 ALL_TEST_FILE_PREFIXES = ("test_",)
 ALL_TEST_FILE_SUFFIXES = ("_test.py",)

package/hooks/test_transcript_skill_scan.py

@@ -18,9 +18,14 @@ from transcript_skill_scan import (
 )
 
 
-def _skill_entry(name: str) -> str:
+def _skill_entry(name: str, tool_use_id: str = "toolu_skill") -> str:
     return json.dumps(
-        {"type": "assistant", "message": {"content": [{"type": "tool_use", "name": "Skill", "input": {"skill": name}}]}}
+        {
+            "type": "assistant",
+            "message": {
+                "content": [{"type": "tool_use", "id": tool_use_id, "name": "Skill", "input": {"skill": name}}]
+            },
+        }
     )
 
 
@@ -144,12 +149,40 @@ def _prompt_entry(content: object) -> str:
 
 
 def test_skill_since_last_prompt_survives_tool_results_and_skill_bodies() -> None:
-    tool_result = _prompt_entry([{"type": "tool_result", "content": "Launching skill: verify"}])
+    tool_result = _prompt_entry(
+        [{"type": "tool_result", "tool_use_id": "toolu_skill", "content": "Launching skill: verify"}]
+    )
     skill_body = json.dumps({"type": "user", "isMeta": True, "message": {"content": "Base directory for this skill"}})
     lines = [_prompt_entry("Commit it."), _skill_entry("verify"), tool_result, skill_body]
     assert is_skill_loaded_since_last_prompt(lines, ("verify",), ())
 
 
+def test_refused_skill_load_leaves_the_skill_unloaded() -> None:
+    refused_result = _prompt_entry(
+        [
+            {
+                "type": "tool_result",
+                "tool_use_id": "toolu_skill",
+                "content": "<tool_use_error>Skill verify cannot be used with Skill tool</tool_use_error>",
+                "is_error": True,
+            }
+        ]
+    )
+    lines = [_prompt_entry("Commit it."), _skill_entry("verify"), refused_result]
+    assert not is_skill_loaded_since_last_prompt(lines, ("verify",), ())
+
+
+def test_skill_call_with_no_result_yet_leaves_the_skill_unloaded() -> None:
+    lines = [_prompt_entry("Commit it."), _skill_entry("verify")]
+    assert not is_skill_loaded_since_last_prompt(lines, ("verify",), ())
+
+
+def test_result_for_another_call_leaves_the_skill_unloaded() -> None:
+    other_result = _prompt_entry([{"type": "tool_result", "tool_use_id": "toolu_other", "content": "done"}])
+    lines = [_prompt_entry("Commit it."), _skill_entry("verify"), other_result]
+    assert not is_skill_loaded_since_last_prompt(lines, ("verify",), ())
+
+
 def test_next_prompt_drops_a_skill_loaded_in_the_last_turn() -> None:
     lines = [_prompt_entry("First."), _skill_entry("verify"), _prompt_entry([{"type": "text", "text": "Second."}])]
     assert not is_skill_loaded_since_last_prompt(lines, ("verify",), ())