claude-dev-env 1.90.0 → 1.92.0

package/hooks/blocking/pr_description_enforcer.py

@@ -1,10 +1,11 @@
-"""PreToolUse hook gating gh pr create/edit/comment body content.
-
-Reads a PreToolUse JSON payload on stdin, recognises the body-carrying
-gh pr create/edit/comment Bash invocations, audits the PR body against the
-Anthropic claude-code style rules, and denies the command when the body fails.
-Readability-management CLI flags short-circuit the stdin path to adjust the
-persisted readability state.
+"""PreToolUse hook gating gh pr create/edit/comment bodies and gh pr ready.
+
+Reads a PreToolUse JSON payload on stdin, audits body-carrying gh pr
+create/edit/comment invocations against the Anthropic claude-code style
+rules plus the proof-of-work audit for proof-shaped comment bodies, and
+denies gh pr ready while the PR carries no passing proof comment.
+Readability-management CLI flags short-circuit the stdin path to adjust
+the persisted readability state.
 """
 
 import json
@@ -32,6 +33,12 @@ from blocking.pr_description_pr_number import (  # noqa: E402
     _command_carries_body_flag,
     _extract_pr_number_from_command,
 )
+from blocking.pr_description_proof_of_work import (  # noqa: E402
+    audit_proof_comment_body,
+    evaluate_pr_ready_gate,
+    is_pr_ready_command,
+    is_proof_shaped_body,
+)
 from blocking.pr_description_readability import (  # noqa: E402
     _build_readability_escape_hatch_message,
     _dispatch_cli_flag,
@@ -131,6 +138,28 @@ def validate_pr_body(body: str, pr_number: int | None = None) -> list[str]:
     return violations
 
 
+def _emit_denial(denial_reason: str) -> None:
+    """Print the PreToolUse deny payload for a violation and log the block.
+
+    Args:
+        denial_reason: The permissionDecisionReason text for the deny payload.
+    """
+    denial_payload = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": denial_reason,
+        }
+    }
+    log_hook_block(
+        calling_hook_name="pr_description_enforcer.py",
+        hook_event="PreToolUse",
+        block_reason=denial_reason,
+    )
+    print(json.dumps(denial_payload))
+    sys.stdout.flush()
+
+
 def main() -> None:
     for each_argv_token in sys.argv[1:]:
         if each_argv_token in ALL_READABILITY_CLI_FLAG_TOKENS:
@@ -154,6 +183,12 @@ def main() -> None:
     if not command:
         sys.exit(0)
 
+    if is_pr_ready_command(command):
+        ready_denial_reason = evaluate_pr_ready_gate(command)
+        if ready_denial_reason is not None:
+            _emit_denial(ready_denial_reason)
+        sys.exit(0)
+
     has_any_body_flag = _command_carries_body_flag(command)
     is_pr_create = "gh pr create" in command and has_any_body_flag
     is_pr_edit = "gh pr edit" in command and has_any_body_flag
@@ -173,28 +208,17 @@ def main() -> None:
 
     violations = validate_pr_body(body, pr_number=extracted_pr_number)
 
+    if is_pr_comment and is_proof_shaped_body(body):
+        violations.extend(audit_proof_comment_body(body, extracted_pr_number))
+
     if violations:
         violation_list = "; ".join(violations)
         pr_guide_reference = f" @{PR_GUIDE_PATH}" if os.path.exists(PR_GUIDE_PATH) else ""
-        denial_reason = (
+        _emit_denial(
             f"BLOCKED: [PR_DESCRIPTION] {violation_list}. "
             f"Rewrite the body yourself in Anthropic claude-code style. "
             f"Guide:{pr_guide_reference}"
         )
-        denial_payload = {
-            "hookSpecificOutput": {
-                "hookEventName": "PreToolUse",
-                "permissionDecision": "deny",
-                "permissionDecisionReason": denial_reason,
-            }
-        }
-        log_hook_block(
-            calling_hook_name="pr_description_enforcer.py",
-            hook_event="PreToolUse",
-            block_reason=denial_reason,
-        )
-        print(json.dumps(denial_payload))
-        sys.stdout.flush()
 
     sys.exit(0)
 

package/hooks/blocking/pr_description_pr_number.py

@@ -2,7 +2,8 @@
 
 Reports whether a captured shell command carries any body or body-file flag,
 and extracts the positional PR number (bare integer or GitHub PR URL) from a
-gh pr edit/comment command while skipping value-taking flags and their values.
+gh pr edit/comment/ready command while skipping value-taking flags and their
+values.
 """
 
 import re
@@ -29,6 +30,7 @@ from blocking._gh_body_arg_utils import (  # noqa: E402
     strip_surrounding_quotes,
 )
 from hooks_constants.pr_description_enforcer_constants import (  # noqa: E402
+    ALL_PR_NUMBER_BEARING_GH_PR_SUBCOMMANDS,
     GH_PR_COMMAND_MIN_TOKEN_COUNT,
 )
 
@@ -59,7 +61,7 @@ def _resolve_positional_pr_number(token: str) -> int | None:
 
 
 def _extract_pr_number_from_command(command: str) -> int | None:
-    """Return the PR number positional argument from a `gh pr edit|comment` command.
+    """Return the PR number positional argument from a `gh pr edit|comment|ready` command.
 
     Skips value-taking non-body flags (and their value tokens) so that ``--repo owner/r``
     pairs do not consume the trailing PR number. Accepts both a bare integer literal
@@ -83,7 +85,7 @@ def _extract_pr_number_from_command(command: str) -> int | None:
     if all_tokens[0] != "gh" or all_tokens[1] != "pr":
         return None
     subcommand_token = all_tokens[2]
-    if subcommand_token not in {"edit", "comment"}:
+    if subcommand_token not in ALL_PR_NUMBER_BEARING_GH_PR_SUBCOMMANDS:
         return None
     all_value_taking_bare_flags: frozenset[str] = (
         non_body_value_flags | all_body_flags | {body_file_flag, body_file_short_flag}

package/hooks/blocking/pr_description_proof_of_work.py

@@ -0,0 +1,367 @@
+"""Audit proof-of-work PR comments and gate gh pr ready on a passing one.
+
+A proof comment shows the work behind a PR: the command run on real data,
+the measured outcomes, the parent issue it advances, an image when the
+change is visual, and the gaps the offline proof cannot cover. This module
+detects proof-shaped comment bodies, audits the five parts, and blocks
+``gh pr ready`` while no passing proof comment exists on the PR. Every gh
+query fails open, so a tooling failure never blocks a command.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import subprocess
+import sys
+from pathlib import Path
+
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
+from blocking.pr_description_body_audit import _iter_section_headers  # noqa: E402
+from blocking.pr_description_pr_number import (  # noqa: E402
+    _extract_pr_number_from_command,
+)
+from hooks_constants.pr_description_enforcer_constants import (  # noqa: E402
+    BULLET_MARKER_PATTERN,
+    FENCED_CODE_BLOCK_PATTERN,
+    TABLE_ROW_LINE_PATTERN,
+)
+from hooks_constants.pr_description_proof_of_work_constants import (  # noqa: E402
+    ALL_HONEST_GAP_PHRASES,
+    ALL_PR_DIFF_SUBCOMMANDS,
+    ALL_PR_VIEW_NUMBER_ARGUMENTS,
+    ALL_PROOF_HEADING_KEYWORDS,
+    ALL_VISUAL_FILE_SUFFIXES,
+    COMMENT_BODY_JSON_FIELD,
+    DIGIT_PATTERN,
+    GH_API_SUBCOMMAND,
+    GH_COMMAND_TIMEOUT_SECONDS,
+    GH_EXECUTABLE,
+    GH_PAGINATE_FLAG,
+    GH_SLURP_FLAG,
+    HEX_COLOR_ADDED_LINE_PATTERN,
+    IMAGE_EMBED_PATTERN,
+    ISSUE_REFERENCE_PATTERN,
+    MAX_DIFF_SCAN_CHARS,
+    PLAN_LINKAGE_KEYWORD_PATTERN,
+    PR_COMMENTS_API_PATH_TEMPLATE,
+    PR_DIFF_NAME_ONLY_FLAG,
+    PR_NUMBER_JSON_FIELD,
+    PR_READY_GATE_MESSAGE_TEMPLATE,
+    PR_READY_INVOCATION_PATTERN,
+    PR_READY_UNDO_FLAG,
+    PROOF_PART_COMMAND_MESSAGE,
+    PROOF_PART_HONEST_GAPS_MESSAGE,
+    PROOF_PART_MEASURED_MESSAGE,
+    PROOF_PART_PLAN_LINKAGE_MESSAGE,
+    PROOF_PART_VISUAL_MESSAGE,
+)
+from hooks_constants.setup_project_paths_constants import UTF8_ENCODING  # noqa: E402
+
+logger = logging.getLogger(__name__)
+
+
+def is_pr_ready_command(command: str) -> bool:
+    """Decide whether a shell command marks a PR ready for review.
+
+    Args:
+        command: The raw shell command captured by the hook.
+
+    Returns:
+        True for a ``gh pr ready`` command without ``--undo``; False for
+        every other command, including the undo form that returns a PR to
+        draft and any command that only mentions the phrase ``gh pr ready``
+        inside a quoted argument or commit message.
+    """
+    if PR_READY_UNDO_FLAG in command:
+        return False
+    return PR_READY_INVOCATION_PATTERN.search(command) is not None
+
+
+def is_proof_shaped_body(body: str) -> bool:
+    """Decide whether a comment body presents itself as a proof of work.
+
+    Args:
+        body: The comment body markdown text.
+
+    Returns:
+        True when any markdown heading names proof or verification; False
+        when no heading does.
+    """
+    for each_header in _iter_section_headers(body):
+        header_lower = each_header.lower()
+        if any(each_keyword in header_lower for each_keyword in ALL_PROOF_HEADING_KEYWORDS):
+            return True
+    return False
+
+
+def audit_proof_comment_body(body: str, pr_number: int | None) -> list[str]:
+    """Audit a proof-shaped comment body for the five proof parts.
+
+    Args:
+        body: The comment body markdown text.
+        pr_number: The PR number named in the command, or None when the
+            command targets the current branch's PR.
+
+    Returns:
+        One message per missing proof part. Empty when the body carries a
+        command block, a measured-value element, a plan-linkage sentence,
+        an honest-gaps statement, and (when the PR diff is visual) an
+        image embed.
+    """
+    is_visual_change = _detect_visual_change(pr_number)
+    return _missing_proof_parts(body, is_visual_change)
+
+
+def evaluate_pr_ready_gate(command: str) -> str | None:
+    """Decide whether a gh pr ready command may proceed.
+
+    Args:
+        command: The raw shell command captured by the hook.
+
+    Returns:
+        A denial reason stating the five-part proof standard when the PR
+        carries no passing proof comment, or None when a passing proof
+        comment exists or any gh query fails.
+    """
+    resolved_pr_number = _extract_pr_number_from_command(command)
+    if resolved_pr_number is None:
+        resolved_pr_number = _resolve_current_pr_number()
+    if resolved_pr_number is None:
+        return None
+    all_comment_bodies = _fetch_pr_comment_bodies(resolved_pr_number)
+    if all_comment_bodies is None:
+        return None
+    is_visual_change = _detect_visual_change(resolved_pr_number)
+    for each_body in all_comment_bodies:
+        if not is_proof_shaped_body(each_body):
+            continue
+        if not _missing_proof_parts(each_body, is_visual_change):
+            return None
+    return PR_READY_GATE_MESSAGE_TEMPLATE.format(pr_number=resolved_pr_number)
+
+
+def _run_gh_command(all_gh_arguments: list[str]) -> str | None:
+    """Run one gh command and return its stdout.
+
+    Args:
+        all_gh_arguments: The gh arguments after the executable name.
+
+    Returns:
+        The command stdout on a zero exit, or None when gh is missing,
+        times out, or exits non-zero — the caller fails open on None.
+    """
+    try:
+        completed_process = subprocess.run(
+            [GH_EXECUTABLE, *all_gh_arguments],
+            capture_output=True,
+            text=True,
+            encoding=UTF8_ENCODING,
+            errors="replace",
+            timeout=GH_COMMAND_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        logger.warning("gh command failed to run: %s", all_gh_arguments)
+        return None
+    if completed_process.returncode != 0:
+        logger.warning("gh command exited %d: %s", completed_process.returncode, all_gh_arguments)
+        return None
+    return completed_process.stdout
+
+
+def _resolve_current_pr_number() -> int | None:
+    """Resolve the PR number of the current branch's open PR.
+
+    Returns:
+        The PR number from ``gh pr view``, or None when no PR resolves or
+        gh fails.
+    """
+    view_stdout = _run_gh_command(list(ALL_PR_VIEW_NUMBER_ARGUMENTS))
+    if view_stdout is None:
+        return None
+    try:
+        view_record = json.loads(view_stdout)
+    except json.JSONDecodeError:
+        return None
+    if not isinstance(view_record, dict):
+        return None
+    resolved_number = view_record.get(PR_NUMBER_JSON_FIELD)
+    if isinstance(resolved_number, int):
+        return resolved_number
+    return None
+
+
+def _fetch_pr_comment_bodies(pr_number: int) -> list[str] | None:
+    """Read every comment body on a PR through the paginated issues API.
+
+    The query runs ``gh api --paginate --slurp`` so every page lands in one
+    JSON array of pages, and the flattening happens here after the full
+    pagination rather than per page.
+
+    Args:
+        pr_number: The PR number whose comments to read.
+
+    Returns:
+        The comment bodies across all pages, or None when gh fails or the
+        output is not the slurped page-array shape — the caller fails open
+        on None.
+    """
+    comments_api_path = PR_COMMENTS_API_PATH_TEMPLATE.format(pr_number=pr_number)
+    api_stdout = _run_gh_command(
+        [GH_API_SUBCOMMAND, comments_api_path, GH_PAGINATE_FLAG, GH_SLURP_FLAG]
+    )
+    if api_stdout is None:
+        return None
+    try:
+        all_comment_pages = json.loads(api_stdout)
+    except json.JSONDecodeError:
+        return None
+    if not isinstance(all_comment_pages, list):
+        return None
+    all_comment_bodies: list[str] = []
+    for each_page in all_comment_pages:
+        if not isinstance(each_page, list):
+            continue
+        for each_comment_record in each_page:
+            if isinstance(each_comment_record, dict):
+                all_comment_bodies.append(str(each_comment_record.get(COMMENT_BODY_JSON_FIELD, "")))
+    return all_comment_bodies
+
+
+def _detect_visual_change(pr_number: int | None) -> bool:
+    """Decide whether the PR diff carries visual work.
+
+    A diff is visual when a changed file carries an image, HTML, or
+    stylesheet suffix, or when an added line carries a six-digit hex color
+    value.
+
+    Args:
+        pr_number: The PR number to diff, or None to diff the current
+            branch's PR.
+
+    Returns:
+        True when the diff is visual; False when it is not or when any gh
+        query fails — an unknowable diff never adds the visual requirement.
+    """
+    all_number_arguments = [str(pr_number)] if pr_number is not None else []
+    name_only_stdout = _run_gh_command(
+        [*ALL_PR_DIFF_SUBCOMMANDS, *all_number_arguments, PR_DIFF_NAME_ONLY_FLAG]
+    )
+    if name_only_stdout is None:
+        return False
+    for each_changed_path in name_only_stdout.splitlines():
+        if Path(each_changed_path.strip()).suffix.lower() in ALL_VISUAL_FILE_SUFFIXES:
+            return True
+    diff_stdout = _run_gh_command([*ALL_PR_DIFF_SUBCOMMANDS, *all_number_arguments])
+    if diff_stdout is None:
+        return False
+    return HEX_COLOR_ADDED_LINE_PATTERN.search(diff_stdout[:MAX_DIFF_SCAN_CHARS]) is not None
+
+
+def _missing_proof_parts(body: str, is_visual_change: bool) -> list[str]:
+    """Collect the proof parts a comment body is missing.
+
+    Args:
+        body: The comment body markdown text.
+        is_visual_change: Whether the PR diff carries visual work, which
+            adds the image-embed requirement.
+
+    Returns:
+        One message per missing part, in the standard's order: command
+        block, measured values, plan linkage, visual element, honest gaps.
+    """
+    prose_without_fences = FENCED_CODE_BLOCK_PATTERN.sub("", body)
+    all_missing_parts: list[str] = []
+    if not _has_command_block(body):
+        all_missing_parts.append(PROOF_PART_COMMAND_MESSAGE)
+    if not _has_measured_value(prose_without_fences):
+        all_missing_parts.append(PROOF_PART_MEASURED_MESSAGE)
+    if not _has_plan_linkage(prose_without_fences):
+        all_missing_parts.append(PROOF_PART_PLAN_LINKAGE_MESSAGE)
+    if is_visual_change and not _has_visual_element(prose_without_fences):
+        all_missing_parts.append(PROOF_PART_VISUAL_MESSAGE)
+    if not _has_honest_gaps(prose_without_fences):
+        all_missing_parts.append(PROOF_PART_HONEST_GAPS_MESSAGE)
+    return all_missing_parts
+
+
+def _has_command_block(body: str) -> bool:
+    """Report whether the body carries a fenced code block with content.
+
+    Args:
+        body: The comment body markdown text.
+
+    Returns:
+        True when at least one fenced code block holds a non-empty line
+        between its fence lines.
+    """
+    for each_fence_match in FENCED_CODE_BLOCK_PATTERN.finditer(body):
+        all_inner_lines = each_fence_match.group(0).splitlines()[1:-1]
+        if any(each_line.strip() for each_line in all_inner_lines):
+            return True
+    return False
+
+
+def _has_measured_value(prose_without_fences: str) -> bool:
+    """Report whether the prose carries a measured-value element.
+
+    Args:
+        prose_without_fences: The body text with fenced code blocks removed.
+
+    Returns:
+        True when a pipe-table row or a bullet line carries a digit.
+    """
+    for each_line in prose_without_fences.splitlines():
+        if not DIGIT_PATTERN.search(each_line):
+            continue
+        if TABLE_ROW_LINE_PATTERN.match(each_line) or BULLET_MARKER_PATTERN.match(each_line):
+            return True
+    return False
+
+
+def _has_plan_linkage(prose_without_fences: str) -> bool:
+    """Report whether the prose links the PR to its parent plan.
+
+    Args:
+        prose_without_fences: The body text with fenced code blocks removed.
+
+    Returns:
+        True when one line carries both an issue reference (``#123``) and a
+        linkage word (issue, phase, plan, parent, advances, milestone, or
+        part of).
+    """
+    for each_line in prose_without_fences.splitlines():
+        has_issue_reference = ISSUE_REFERENCE_PATTERN.search(each_line) is not None
+        if has_issue_reference and PLAN_LINKAGE_KEYWORD_PATTERN.search(each_line) is not None:
+            return True
+    return False
+
+
+def _has_visual_element(prose_without_fences: str) -> bool:
+    """Report whether the prose embeds an image.
+
+    Args:
+        prose_without_fences: The body text with fenced code blocks removed.
+
+    Returns:
+        True when a markdown image embed (``![...](...)``) is present.
+    """
+    return IMAGE_EMBED_PATTERN.search(prose_without_fences) is not None
+
+
+def _has_honest_gaps(prose_without_fences: str) -> bool:
+    """Report whether the prose states what the proof cannot show.
+
+    Args:
+        prose_without_fences: The body text with fenced code blocks removed.
+
+    Returns:
+        True when the prose carries a gap phrase (gap, limitation, cannot,
+        does not show, not shown, unverified, or not covered).
+    """
+    prose_lower = prose_without_fences.lower()
+    return any(each_phrase in prose_lower for each_phrase in ALL_HONEST_GAP_PHRASES)

package/hooks/blocking/precommit_code_rules_gate.py

@@ -122,7 +122,10 @@ def run_staged_gate(repository_root: Path) -> tuple[int, str]:
     """Run the shared code_rules_gate engine in staged mode.
 
     Args:
-        repository_root: Repository root passed to the gate's --repo-root.
+        repository_root: Repository root passed to the gate's --repo-root
+            and used as the gate subprocess working directory, so relative
+            paths the gate's checks resolve land in the committing worktree
+            rather than the hook's own working directory.
 
     Returns:
         Tuple of the gate exit code and its stderr report. A missing gate
@@ -147,6 +150,7 @@ def run_staged_gate(repository_root: Path) -> tuple[int, str]:
             encoding="utf-8",
             errors="replace",
             timeout=GATE_TIMEOUT_SECONDS,
+            cwd=str(repository_root),
         )
     except subprocess.TimeoutExpired:
         return 1, (

package/hooks/blocking/test_code_rules_enforcer_comment_string_awareness.py

@@ -17,6 +17,8 @@ import sys
 from pathlib import Path
 from types import SimpleNamespace
 
+import pytest
+
 _BLOCKING_DIRECTORY = str(Path(__file__).resolve().parent)
 _HOOKS_DIRECTORY = str(Path(__file__).resolve().parent.parent)
 if _BLOCKING_DIRECTORY not in sys.path:
@@ -119,11 +121,15 @@ def test_check_comment_changes_skips_removal_when_old_python_un_parseable() -> N
     assert issues == []
 
 
-def test_check_comment_changes_still_detects_removal_on_parseable_python() -> None:
+def test_check_comment_changes_advises_without_blocking_on_removal_on_parseable_python(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
     old_content = 'x = 1  # existing comment\n'
     new_content = 'x = 1\n'
     issues = code_rules_enforcer.check_comment_changes(old_content, new_content, "foo.py")
-    assert any("Existing comment removed" in each_issue for each_issue in issues)
+    assert not any("Existing comment removed" in each_issue for each_issue in issues)
+    captured = capsys.readouterr()
+    assert "[CODE_RULES advisory] Existing comment removed" in captured.err
 
 
 def test_python_check_should_exempt_directive_without_space_after_hash() -> None:

package/hooks/blocking/test_code_verifier_spawn_preflight_gate.py

@@ -287,6 +287,37 @@ def make_conflict_repository(tmp_path: Path) -> Path:
     return repository_root
 
 
+def make_stale_self_upstream_conflict_repository(tmp_path: Path) -> Path:
+    repository_root = make_conflict_repository(tmp_path)
+    feature_sha = run_git(repository_root, "rev-parse", "HEAD")
+    run_git(repository_root, "remote", "add", "origin", str(repository_root))
+    run_git(repository_root, "update-ref", "refs/remotes/origin/feature", feature_sha)
+    run_git(repository_root, "config", "branch.feature.remote", "origin")
+    run_git(repository_root, "config", "branch.feature.merge", "refs/heads/feature")
+    return repository_root
+
+
+def make_merge_in_progress_repository(tmp_path: Path) -> Path:
+    repository_root = tmp_path / "repo"
+    repository_root.mkdir()
+    initialize_repository(repository_root)
+    base_sha = commit_file(repository_root, "shared.py", SHARED_BASE_SOURCE, "add shared")
+    run_git(repository_root, "update-ref", "refs/remotes/origin/main", base_sha)
+    run_git(repository_root, "checkout", "-b", "feature")
+    commit_file(repository_root, "shared.py", SHARED_FEATURE_SOURCE, "feature edit")
+    advance_origin_main_divergent(repository_root, base_sha, "shared.py", SHARED_DIVERGENT_SOURCE)
+    return repository_root
+
+
+def start_conflicting_merge(repository_root: Path) -> None:
+    subprocess.run(
+        ["git", "-C", str(repository_root), "merge", "--no-edit", "origin/main"],
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+
+
 def test_non_code_verifier_agent_is_no_op(tmp_path: Path) -> None:
     repository_root = make_conflict_repository(tmp_path)
     write_working_tree_file(repository_root, "violator.py", VIOLATING_MODULE_SOURCE)
@@ -473,6 +504,46 @@ def test_conflict_and_violation_single_deny_names_both(tmp_path: Path) -> None:
     assert "violator.py" in reason
 
 
+def test_stale_self_upstream_still_judges_default_branch(tmp_path: Path) -> None:
+    repository_root = make_stale_self_upstream_conflict_repository(tmp_path)
+    tracked_upstream = run_git(
+        repository_root, "rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"
+    )
+    assert tracked_upstream == "origin/feature", "fixture must track the branch's own remote ref"
+    payload = write_agent_payload("code-verifier", "verify the change", repository_root)
+    result = run_hook(payload, repository_root)
+    assert not is_allow(result)
+    reason = deny_reason(result)
+    assert "shared.py" in reason
+    assert "Merge conflicts vs" in reason
+
+
+def test_staged_resolved_merge_allows(tmp_path: Path) -> None:
+    repository_root = make_merge_in_progress_repository(tmp_path)
+    start_conflicting_merge(repository_root)
+    write_working_tree_file(repository_root, "shared.py", SHARED_FEATURE_SOURCE)
+    run_git(repository_root, "add", "shared.py")
+    remaining_unmerged = run_git(repository_root, "diff", "--name-only", "--diff-filter=U")
+    assert remaining_unmerged == "", "the staged resolution must clear every unmerged index entry"
+    merge_head_sha = run_git(repository_root, "rev-parse", "--verify", "--quiet", "MERGE_HEAD")
+    assert merge_head_sha, "a merge must still be in progress so MERGE_HEAD is present"
+    payload = write_agent_payload("code-verifier", "verify the change", repository_root)
+    result = run_hook(payload, repository_root)
+    assert is_allow(result)
+
+
+def test_unresolved_merge_keeps_denying(tmp_path: Path) -> None:
+    repository_root = make_merge_in_progress_repository(tmp_path)
+    start_conflicting_merge(repository_root)
+    remaining_unmerged = run_git(repository_root, "diff", "--name-only", "--diff-filter=U")
+    assert "shared.py" in remaining_unmerged, "the merge must leave shared.py unmerged"
+    payload = write_agent_payload("code-verifier", "verify the change", repository_root)
+    result = run_hook(payload, repository_root)
+    assert not is_allow(result)
+    reason = deny_reason(result)
+    assert "shared.py" in reason
+
+
 def test_hook_imports_real_config_when_parent_holds_shadowing_config(
     tmp_path: Path,
 ) -> None: