claude-dev-env 2.4.0 → 2.5.0

package/_shared/pr-loop/scripts/revoke_project_claude_permissions.py

@@ -15,10 +15,12 @@ if parent_directory not in sys.path:
     sys.path.insert(0, parent_directory)
 
 from _claude_permissions_common import (  # noqa: E402
+    all_project_path_aliases_for_reap,
     build_agent_config_deny_rules,
     build_permission_rules,
     exit_with_error,
     get_current_project_path,
+    is_inert_file_permission_rule,
     is_trust_entry_for_project,
     is_valid_project_root,
     load_settings,
@@ -29,8 +31,12 @@ from _claude_permissions_common import (  # noqa: E402
 from pr_loop_shared_constants.claude_permissions_constants import (
     ALL_AGENT_CONFIG_DENY_TOOLS,
     ALL_AGENT_CONFIG_PATH_PATTERNS,
+    ALL_LEGACY_PERMISSION_REAP_TOOLS,
     ALL_PERMISSION_ALLOW_TOOLS,
     AUTO_MODE_ENVIRONMENT_ENTRY_PREFIX,
+    INERT_RULES_REMOVED_LOG_PREFIX,
+    PROJECT_LOCAL_INERT_RULES_REMOVED_LOG_PREFIX,
+    get_claude_project_local_settings_path,
     get_claude_user_settings_path,
 )
 from pr_loop_shared_constants.claude_settings_keys_constants import (
@@ -46,6 +52,179 @@ from stale_worktree_rule_sweep import (  # noqa: E402
 )
 
 
+def _reap_tool_names(all_mint_tool_names: tuple[str, ...]) -> tuple[str, ...]:
+    """Return mint tool names plus legacy Write/Glob forms a revoke run reaps.
+
+    Keeps mint tuples (Edit/Read) untouched and widens only the revoke surface
+    so inert pre-#158 Write()/Glob() rules are removed with the current mint set.
+    """
+    return all_mint_tool_names + ALL_LEGACY_PERMISSION_REAP_TOOLS
+
+
+def remove_inert_file_permission_rules(all_settings: dict[str, object]) -> int:
+    """Remove Write/Glob/NotebookEdit allow and deny rules path-agnostically.
+
+    ::
+
+        remove_inert_file_permission_rules(
+            {"permissions": {"allow": ["Write(/wt/**)", "Edit(/p/.claude/**)"]}}
+        )  # ok: 1, allow left with Edit only
+
+    Claude only honors Edit for file permission checks; leftover Write, Glob,
+    and NotebookEdit rules from older grants only produce startup warnings.
+
+    Args:
+        all_settings: Parsed Claude user settings dictionary (mutated in place).
+
+    Returns:
+        Number of inert rules removed from allow and deny combined.
+    """
+    permissions_section = all_settings.get(CLAUDE_SETTINGS_PERMISSIONS_KEY)
+    if not isinstance(permissions_section, dict):
+        return 0
+    total_removed_count = 0
+    for each_list_key in (CLAUDE_SETTINGS_ALLOW_KEY, CLAUDE_SETTINGS_DENY_KEY):
+        existing_rule_list = permissions_section.get(each_list_key)
+        if not isinstance(existing_rule_list, list):
+            continue
+        total_removed_count += remove_matching_entries_from_list(
+            existing_rule_list, is_inert_file_permission_rule
+        )
+    return total_removed_count
+
+
+def build_project_scoped_allow_rules_for_reap(project_path: str) -> list[str]:
+    """Build allow rules for every path alias of *project_path* (incl. $HOME).
+
+    ::
+
+        build_project_scoped_allow_rules_for_reap("/repo")
+            # ok: includes Edit(/repo/.claude/**) and Write(/repo/.claude/**)
+
+    Args:
+        project_path: POSIX project root from get_current_project_path.
+
+    Returns:
+        Allow rule strings covering mint plus legacy tools for each path alias.
+    """
+    all_allow_rules: list[str] = []
+    for each_path_alias in all_project_path_aliases_for_reap(project_path):
+        all_allow_rules.extend(
+            build_permission_rules(
+                each_path_alias, _reap_tool_names(ALL_PERMISSION_ALLOW_TOOLS)
+            )
+        )
+    return all_allow_rules
+
+
+def build_project_scoped_deny_rules_for_reap(project_path: str) -> list[str]:
+    """Build agent-config deny rules for every path alias of *project_path*.
+
+    Args:
+        project_path: POSIX project root from get_current_project_path.
+
+    Returns:
+        Deny rule strings for mint plus legacy tools across path aliases.
+    """
+    all_deny_rules: list[str] = []
+    for each_path_alias in all_project_path_aliases_for_reap(project_path):
+        all_deny_rules.extend(
+            build_agent_config_deny_rules(
+                each_path_alias,
+                _reap_tool_names(ALL_AGENT_CONFIG_DENY_TOOLS),
+                ALL_AGENT_CONFIG_PATH_PATTERNS,
+            )
+        )
+    return all_deny_rules
+
+
+def _remove_directory_and_trust_for_path_aliases(
+    all_settings: dict[str, object], project_path: str
+) -> tuple[int, int]:
+    """Remove additionalDirectories and trust entries for each path alias."""
+    directories_removed_count = 0
+    environment_entries_removed_count = 0
+    for each_path_alias in all_project_path_aliases_for_reap(project_path):
+        directories_removed_count += remove_directory_from_additional_directories(
+            all_settings, each_path_alias
+        )
+        environment_entries_removed_count += remove_trust_entries_for_project(
+            all_settings, each_path_alias, AUTO_MODE_ENVIRONMENT_ENTRY_PREFIX
+        )
+    return directories_removed_count, environment_entries_removed_count
+
+
+def strip_inert_rules_from_settings_file(settings_path: Path) -> int:
+    """Load *settings_path*, strip inert tools, save when anything changed.
+
+    ::
+
+        strip_inert_rules_from_settings_file(missing_path)  # ok: 0
+        strip_inert_rules_from_settings_file(local_with_Write)  # ok: N > 0
+
+    Args:
+        settings_path: User or project-local Claude settings JSON path.
+
+    Returns:
+        Number of inert rules removed; 0 when the file is missing or clean.
+    """
+    if not settings_path.is_file():
+        return 0
+    settings = load_settings(settings_path)
+    inert_rules_removed_count = remove_inert_file_permission_rules(settings)
+    if inert_rules_removed_count == 0:
+        return 0
+    prune_empty_list_then_empty_section(
+        settings,
+        CLAUDE_SETTINGS_PERMISSIONS_KEY,
+        CLAUDE_SETTINGS_ALLOW_KEY,
+    )
+    prune_empty_list_then_empty_section(
+        settings,
+        CLAUDE_SETTINGS_PERMISSIONS_KEY,
+        CLAUDE_SETTINGS_DENY_KEY,
+    )
+    save_settings(settings_path, settings)
+    return inert_rules_removed_count
+
+
+def _print_revoke_summary(
+    project_path: str,
+    claude_user_settings_path: Path,
+    allow_rules_removed_count: int,
+    permission_rules_count: int,
+    deny_rules_removed_count: int,
+    agent_config_deny_rules_count: int,
+    inert_rules_removed_count: int,
+    project_local_inert_rules_removed_count: int,
+    directories_removed_count: int,
+    environment_entries_removed_count: int,
+) -> None:
+    """Print the post-revoke summary lines to stdout."""
+    inert_rules_removed_log_prefix = INERT_RULES_REMOVED_LOG_PREFIX
+    project_local_inert_rules_removed_log_prefix = (
+        PROJECT_LOCAL_INERT_RULES_REMOVED_LOG_PREFIX
+    )
+    print(f"Project path: {project_path}")
+    print(f"Settings file: {claude_user_settings_path}")
+    print(
+        f"Allow rules removed: {allow_rules_removed_count} of {permission_rules_count}"
+    )
+    print(
+        f"Deny rules removed: {deny_rules_removed_count} of "
+        f"{agent_config_deny_rules_count}"
+    )
+    print(f"{inert_rules_removed_log_prefix}{inert_rules_removed_count}")
+    print(
+        f"{project_local_inert_rules_removed_log_prefix}"
+        f"{project_local_inert_rules_removed_count}"
+    )
+    print(f"Additional directories removed: {directories_removed_count}")
+    print(
+        f"Auto-mode environment entries removed: {environment_entries_removed_count}"
+    )
+
+
 def remove_values_from_list(
     all_target_list: list[object], all_values_to_remove: set[str]
 ) -> int:
@@ -192,13 +371,79 @@ def prune_settings_after_revoke(all_settings: dict[str, object]) -> None:
     )
 
 
+def _apply_user_settings_revoke(
+    all_settings: dict[str, object],
+    project_path: str,
+    all_permission_rules: list[str],
+    all_agent_config_deny_rules: list[str],
+) -> tuple[int, int, int, int, int, int]:
+    """Apply project-scoped and inert removals to the user settings dict.
+
+    Returns:
+        Counts: allow, deny, directories, environment, worktree_sweep, inert.
+    """
+    worktree_sweep_removed_count = sweep_stale_worktree_rules_from_settings(
+        all_settings
+    )
+    inert_rules_removed_count = remove_inert_file_permission_rules(all_settings)
+    allow_rules_removed_count = remove_rules_from_allow_list(
+        all_settings, all_permission_rules
+    )
+    deny_rules_removed_count = remove_rules_from_deny_list(
+        all_settings, all_agent_config_deny_rules
+    )
+    directories_removed_count, environment_entries_removed_count = (
+        _remove_directory_and_trust_for_path_aliases(all_settings, project_path)
+    )
+    return (
+        allow_rules_removed_count,
+        deny_rules_removed_count,
+        directories_removed_count,
+        environment_entries_removed_count,
+        worktree_sweep_removed_count,
+        inert_rules_removed_count,
+    )
+
+
+def _require_valid_project_root_or_exit() -> Path:
+    """Return cwd when it is a project root, otherwise exit with an error."""
+    project_root_path = Path.cwd()
+    if is_valid_project_root(project_root_path):
+        return project_root_path
+    print(
+        f"ERROR: cwd {project_root_path} is not a project root "
+        f"(no .git or .claude). Run from a project root.",
+        file=sys.stderr,
+    )
+    raise SystemExit(1)
+
+
+def _sum_user_settings_change_counts(
+    allow_rules_removed_count: int,
+    deny_rules_removed_count: int,
+    directories_removed_count: int,
+    environment_entries_removed_count: int,
+    worktree_sweep_removed_count: int,
+    inert_rules_removed_count: int,
+) -> int:
+    """Return the total number of user-settings mutations for this revoke."""
+    return (
+        allow_rules_removed_count
+        + deny_rules_removed_count
+        + directories_removed_count
+        + environment_entries_removed_count
+        + worktree_sweep_removed_count
+        + inert_rules_removed_count
+    )
+
+
 def revoke_permissions_for_current_directory() -> None:
     """Revoke permissions previously granted for the current project directory.
 
-    Reads the current project path, constructs the matching allow and deny
-    permission rules, removes them from ~/.claude/settings.json, removes
-    every trust entry for the project from autoMode.environment, and prunes
-    any newly empty sections.
+    Removes matching allow/deny rules from ~/.claude/settings.json, strips
+    inert Write/Glob/NotebookEdit rules from user settings and project
+    ``.claude/settings.local.json`` when present, clears trust entries, and
+    prunes empty sections.
 
     Raises:
         SystemExit: When the current directory is not a valid project root.
@@ -206,59 +451,56 @@ def revoke_permissions_for_current_directory() -> None:
                     contains glob metacharacters.
     """
     claude_user_settings_path: Path = get_claude_user_settings_path()
-    project_root_path = Path.cwd()
-    if not is_valid_project_root(project_root_path):
-        print(
-            f"ERROR: cwd {project_root_path} is not a project root "
-            f"(no .git or .claude). Run from a project root.",
-            file=sys.stderr,
-        )
-        raise SystemExit(1)
+    project_root_path = _require_valid_project_root_or_exit()
     project_path = get_current_project_path()
-    permission_rules = build_permission_rules(project_path, ALL_PERMISSION_ALLOW_TOOLS)
-    all_agent_config_deny_rules = build_agent_config_deny_rules(
-        project_path,
-        ALL_AGENT_CONFIG_DENY_TOOLS,
-        ALL_AGENT_CONFIG_PATH_PATTERNS,
+    all_permission_rules = build_project_scoped_allow_rules_for_reap(project_path)
+    all_agent_config_deny_rules = build_project_scoped_deny_rules_for_reap(
+        project_path
     )
-    settings = load_settings(claude_user_settings_path)
-    worktree_sweep_removed_count = sweep_stale_worktree_rules_from_settings(settings)
-    allow_rules_removed_count = remove_rules_from_allow_list(settings, permission_rules)
-    deny_rules_removed_count = remove_rules_from_deny_list(
-        settings, all_agent_config_deny_rules
+    all_settings = load_settings(claude_user_settings_path)
+    (
+        allow_rules_removed_count,
+        deny_rules_removed_count,
+        directories_removed_count,
+        environment_entries_removed_count,
+        worktree_sweep_removed_count,
+        inert_rules_removed_count,
+    ) = _apply_user_settings_revoke(
+        all_settings,
+        project_path,
+        all_permission_rules,
+        all_agent_config_deny_rules,
     )
-    directories_removed_count = remove_directory_from_additional_directories(
-        settings, project_path
+    user_settings_changes_count = _sum_user_settings_change_counts(
+        allow_rules_removed_count,
+        deny_rules_removed_count,
+        directories_removed_count,
+        environment_entries_removed_count,
+        worktree_sweep_removed_count,
+        inert_rules_removed_count,
     )
-    environment_entries_removed_count = remove_trust_entries_for_project(
-        settings, project_path, AUTO_MODE_ENVIRONMENT_ENTRY_PREFIX
+    if user_settings_changes_count > 0:
+        prune_settings_after_revoke(all_settings)
+        save_settings(claude_user_settings_path, all_settings)
+    project_local_inert_rules_removed_count = strip_inert_rules_from_settings_file(
+        get_claude_project_local_settings_path(project_root_path)
     )
-    total_changes_count = (
-        allow_rules_removed_count
-        + deny_rules_removed_count
-        + directories_removed_count
-        + environment_entries_removed_count
-        + worktree_sweep_removed_count
-    )
-    if total_changes_count == 0:
+    if user_settings_changes_count + project_local_inert_rules_removed_count == 0:
         print(f"Project path: {project_path}")
         print(f"Settings file: {claude_user_settings_path}")
         print("No changes to revoke; settings file left untouched.")
         return
-    prune_settings_after_revoke(settings)
-    save_settings(claude_user_settings_path, settings)
-    print(f"Project path: {project_path}")
-    print(f"Settings file: {claude_user_settings_path}")
-    print(
-        f"Allow rules removed: {allow_rules_removed_count} of {len(permission_rules)}"
-    )
-    print(
-        f"Deny rules removed: {deny_rules_removed_count} of "
-        f"{len(all_agent_config_deny_rules)}"
-    )
-    print(f"Additional directories removed: {directories_removed_count}")
-    print(
-        f"Auto-mode environment entries removed: {environment_entries_removed_count}"
+    _print_revoke_summary(
+        project_path,
+        claude_user_settings_path,
+        allow_rules_removed_count,
+        len(all_permission_rules),
+        deny_rules_removed_count,
+        len(all_agent_config_deny_rules),
+        inert_rules_removed_count,
+        project_local_inert_rules_removed_count,
+        directories_removed_count,
+        environment_entries_removed_count,
     )
 
 

package/_shared/pr-loop/scripts/tests/test_claude_permissions_common.py

@@ -13,14 +13,23 @@ import pytest
 def _load_common_module() -> ModuleType:
     module_path = Path(__file__).parent.parent / "_claude_permissions_common.py"
     parent_directory = str(module_path.parent.resolve())
-    if parent_directory not in sys.path:
-        sys.path.insert(0, parent_directory)
+    if parent_directory in sys.path:
+        sys.path.remove(parent_directory)
+    sys.path.insert(0, parent_directory)
+    for each_module_name in list(sys.modules):
+        if each_module_name == "pr_loop_shared_constants" or each_module_name.startswith(
+            "pr_loop_shared_constants."
+        ):
+            del sys.modules[each_module_name]
+        if each_module_name == "_claude_permissions_common":
+            del sys.modules[each_module_name]
     spec = importlib.util.spec_from_file_location(
         "_claude_permissions_common", module_path
     )
     assert spec is not None
     assert spec.loader is not None
     module = importlib.util.module_from_spec(spec)
+    sys.modules["_claude_permissions_common"] = module
     spec.loader.exec_module(module)
     return module
 
@@ -187,3 +196,34 @@ def test_is_valid_project_root_uses_extracted_directory_marker_constants() -> No
     assert '".git"' not in source_text
     assert "'.claude'" not in source_text
     assert '".claude"' not in source_text
+
+
+def test_permission_rule_tool_name_extracts_tool_prefix() -> None:
+    assert common.permission_rule_tool_name("Edit(/repo/.claude/**)") == "Edit"
+    assert common.permission_rule_tool_name("Write(c:/Users/jon/.claude/worktrees/x/**)") == (
+        "Write"
+    )
+    assert common.permission_rule_tool_name(None) is None
+    assert common.permission_rule_tool_name("not-a-rule") is None
+
+
+def test_is_inert_file_permission_rule_for_write_glob_notebookedit() -> None:
+    assert common.is_inert_file_permission_rule("Write(/wt/.claude/**)") is True
+    assert common.is_inert_file_permission_rule("Glob(/wt/.claude/hooks/**)") is True
+    assert common.is_inert_file_permission_rule("NotebookEdit(**/.claude/worktrees/**)") is True
+    assert common.is_inert_file_permission_rule("Edit(/repo/.claude/**)") is False
+    assert common.is_inert_file_permission_rule("Bash(echo hi)") is False
+
+
+def test_all_project_path_aliases_for_reap_adds_home_alias_when_project_is_home() -> None:
+    all_aliases = common.all_project_path_aliases_for_reap(
+        "C:/Users/jon", home_directory_path="C:/Users/jon"
+    )
+    assert all_aliases == ("C:/Users/jon", "$HOME")
+
+
+def test_all_project_path_aliases_for_reap_skips_home_alias_for_other_projects() -> None:
+    all_aliases = common.all_project_path_aliases_for_reap(
+        "C:/dev/other", home_directory_path="C:/Users/jon"
+    )
+    assert all_aliases == ("C:/dev/other",)

package/_shared/pr-loop/scripts/tests/test_claude_permissions_constants.py

@@ -36,6 +36,42 @@ def test_exposes_all_agent_config_deny_tools_tuple() -> None:
     assert "Glob" not in constants_module.ALL_PERMISSION_ALLOW_TOOLS
 
 
+def test_exposes_all_legacy_permission_reap_tools_tuple() -> None:
+    assert constants_module.ALL_LEGACY_PERMISSION_REAP_TOOLS == ("Write", "Glob")
+    assert "NotebookEdit" not in constants_module.ALL_LEGACY_PERMISSION_REAP_TOOLS
+    assert "Edit" not in constants_module.ALL_LEGACY_PERMISSION_REAP_TOOLS
+    assert "Read" not in constants_module.ALL_LEGACY_PERMISSION_REAP_TOOLS
+
+
+def test_exposes_all_inert_file_permission_tools_tuple() -> None:
+    assert constants_module.ALL_INERT_FILE_PERMISSION_TOOLS == (
+        "Write",
+        "Glob",
+        "NotebookEdit",
+    )
+    assert "Edit" not in constants_module.ALL_INERT_FILE_PERMISSION_TOOLS
+    assert "Read" not in constants_module.ALL_INERT_FILE_PERMISSION_TOOLS
+    assert "Write" not in constants_module.ALL_PERMISSION_ALLOW_TOOLS
+    assert "NotebookEdit" not in constants_module.ALL_PERMISSION_ALLOW_TOOLS
+    assert "NotebookEdit" not in constants_module.ALL_AGENT_CONFIG_DENY_TOOLS
+
+
+def test_exposes_home_project_path_alias() -> None:
+    assert constants_module.HOME_PROJECT_PATH_ALIAS == "$HOME"
+
+
+def test_get_claude_project_local_settings_path_uses_settings_local_filename() -> None:
+    project_root = Path("C:/dev/Projects/LLM Plugins/claude-dev-env")
+    local_settings_path = constants_module.get_claude_project_local_settings_path(
+        project_root
+    )
+    assert local_settings_path.name == constants_module.CLAUDE_SETTINGS_LOCAL_FILENAME
+    assert local_settings_path.parent.name == (
+        constants_module.CLAUDE_SETTINGS_DIRECTORY_NAME
+    )
+    assert local_settings_path.parent.parent == project_root
+
+
 def test_auto_mode_environment_entry_template_is_format_string() -> None:
     rendered_template_text = (
         constants_module.AUTO_MODE_ENVIRONMENT_ENTRY_TEMPLATE.format(

package/_shared/pr-loop/scripts/tests/test_code_rules_gate.py

@@ -74,6 +74,7 @@ def initialize_git_repository(repository_root: Path) -> None:
     run_git_in_repository(repository_root, "config", "user.email", "test@example.com")
     run_git_in_repository(repository_root, "config", "user.name", "Test")
     run_git_in_repository(repository_root, "config", "commit.gpgsign", "false")
+    run_git_in_repository(repository_root, "config", "core.autocrlf", "false")
     disabled_hooks_directory = repository_root / "disabled-git-hooks"
     disabled_hooks_directory.mkdir()
     run_git_in_repository(
@@ -88,7 +89,7 @@ def commit_all_files(repository_root: Path, commit_message: str) -> None:
 
 def write_file(file_path: Path, content: str) -> None:
     file_path.parent.mkdir(parents=True, exist_ok=True)
-    file_path.write_text(content, encoding="utf-8")
+    file_path.write_text(content, encoding="utf-8", newline="")
 
 
 def stage_file(repository_root: Path, relative_path: str) -> None:
@@ -2799,3 +2800,101 @@ def test_run_pytest_for_group_treats_no_tests_collected_as_a_pass_per_batch(
         "a batch that collects no tests is not a failure; only a real pytest "
         "failure exit code may block the commit"
     )
+
+
+_PNG_SIGNATURE_BYTES = b"\x89PNG\r\n\x1a\n" + b"\x00\x00\x00\rIHDR" + b"\x00" * 16
+_SKIPPING_UNREADABLE_MARKER = "skipping unreadable file"
+
+
+def _write_png(file_path: Path) -> None:
+    """Write a minimal PNG-signature binary file at *file_path*."""
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+    file_path.write_bytes(_PNG_SIGNATURE_BYTES)
+
+
+def _clean_module_source() -> str:
+    """Return Python source the enforcer accepts as a clean new module."""
+    return '"""Clean module for binary-flood gate tests."""\n\n\ndef greet() -> str:\n    return "hello"\n'
+
+
+def test_diff_mode_tracked_new_png_does_not_flood_stderr(
+    temporary_git_repository: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """A newly committed PNG must not emit a UTF-8 skip line on the push surface."""
+    write_file(temporary_git_repository / "anchor.py", "anchor = 1\n")
+    commit_all_files(temporary_git_repository, "baseline")
+    _write_png(temporary_git_repository / "assets" / "icon.png")
+    commit_all_files(temporary_git_repository, "add icon png")
+    monkeypatch.chdir(temporary_git_repository)
+
+    exit_code = gate_module.main(["--base", "HEAD~1"])
+
+    captured = capsys.readouterr()
+    assert exit_code == 0
+    assert _SKIPPING_UNREADABLE_MARKER not in captured.err
+    assert "icon.png" not in captured.err
+
+
+def test_diff_mode_untracked_png_does_not_flood_stderr(
+    temporary_git_repository: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """An untracked PNG joins the combined surface and must not flood stderr."""
+    write_file(temporary_git_repository / "anchor.py", "anchor = 1\n")
+    commit_all_files(temporary_git_repository, "baseline")
+    _write_png(temporary_git_repository / "untracked_icon.png")
+    monkeypatch.chdir(temporary_git_repository)
+
+    exit_code = gate_module.main(["--base", "HEAD"])
+
+    captured = capsys.readouterr()
+    assert exit_code == 0
+    assert _SKIPPING_UNREADABLE_MARKER not in captured.err
+    assert "untracked_icon.png" not in captured.err
+
+
+def test_diff_mode_image_only_surface_exits_zero_not_empty_file_set(
+    temporary_git_repository: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """Git reports image files, yet zero code files means a clean pass (not EMPTY_FILE_SET)."""
+    write_file(temporary_git_repository / "seed.txt", "seed\n")
+    commit_all_files(temporary_git_repository, "seed")
+    _write_png(temporary_git_repository / "only_image.png")
+    commit_all_files(temporary_git_repository, "image only")
+    monkeypatch.chdir(temporary_git_repository)
+
+    exit_code = gate_module.main(["--base", "HEAD~1"])
+
+    captured = capsys.readouterr()
+    assert exit_code == 0
+    assert exit_code != gate_module.EMPTY_FILE_SET_EXIT_CODE
+    assert _SKIPPING_UNREADABLE_MARKER not in captured.err
+    assert gate_module.EMPTY_FILE_SET_MESSAGE not in captured.err
+    assert "inspected 0 file(s)" in captured.err
+
+
+def test_diff_mode_mixed_py_and_png_validates_py_silently_skips_png(
+    temporary_git_repository: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """A mixed surface line-maps and validates the .py; the PNG is skipped with no flood."""
+    write_file(temporary_git_repository / "anchor.py", "anchor = 1\n")
+    commit_all_files(temporary_git_repository, "baseline")
+    write_file(temporary_git_repository / "fresh_module.py", _clean_module_source())
+    _write_png(temporary_git_repository / "mixed_icon.png")
+    commit_all_files(temporary_git_repository, "add py and png")
+    monkeypatch.chdir(temporary_git_repository)
+
+    exit_code = gate_module.main(["--base", "HEAD~1"])
+
+    captured = capsys.readouterr()
+    assert exit_code == 0
+    assert _SKIPPING_UNREADABLE_MARKER not in captured.err
+    assert "inspected 1 file(s)" in captured.err
+    assert "mixed_icon.png" not in captured.err