claude-dev-env 1.82.0 → 1.84.0

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

@@ -133,3 +133,215 @@ def test_path_contains_glob_metacharacters_accepts_windows_paths_with_parens() -
     assert common.path_contains_glob_metacharacters("C:/Users/Jon (Admin)/project") is False
     assert common.path_contains_glob_metacharacters("C:/Projects/a,b/file.py") is False
 
+
+def test_get_mode_to_preserve_returns_existing_file_mode(tmp_path: Path) -> None:
+    """When the file exists, the actual filesystem mode must be returned (not the default)."""
+    target_path = tmp_path / "settings.json"
+    target_path.write_text("{}", encoding="utf-8")
+    actual_filesystem_mode = target_path.stat().st_mode & 0o777
+    returned_mode = common.get_mode_to_preserve(target_path)
+    assert returned_mode == actual_filesystem_mode
+
+
+def test_get_mode_to_preserve_returns_secure_default_when_file_missing(
+    tmp_path: Path,
+) -> None:
+    """A missing settings file must fall back to the secure 0o600 default mode."""
+    missing_settings_path = tmp_path / "no_such_file.json"
+    returned_mode = common.get_mode_to_preserve(missing_settings_path)
+    assert returned_mode == 0o600
+
+
+def test_write_atomically_with_mode_raises_oserror_when_open_fails(
+    tmp_path: Path,
+) -> None:
+    """OSError from os.open must propagate to the caller."""
+    target_path = tmp_path / "subdirectory" / "missing" / "settings.json.tmp"
+    with pytest.raises(OSError):
+        common.write_atomically_with_mode(target_path, "payload", file_mode=0o600)
+
+
+def test_write_atomically_with_mode_unlinks_temp_when_fdopen_raises(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A failure inside os.fdopen must remove the on-disk temp file.
+
+    The file exists the moment os.open returns; closing only the raw
+    descriptor would leave an empty temp sibling on disk after the
+    exception propagates to the caller.
+    """
+
+    def failing_fdopen(*_args: object, **_kwargs: object) -> object:
+        raise MemoryError("fdopen failure")
+
+    monkeypatch.setattr(common.os, "fdopen", failing_fdopen)
+    target_path = tmp_path / "settings.json.tmp"
+    with pytest.raises(MemoryError):
+        common.write_atomically_with_mode(target_path, "payload", file_mode=0o600)
+    assert not target_path.exists(), (
+        "the temp file created by os.open must be unlinked before re-raising"
+    )
+
+
+def test_save_settings_warns_on_stderr_when_temp_unlink_fails(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """A swallowed unlink in the finally block must surface to stderr.
+
+    Forces a write success followed by os.replace failure so the temp file
+    survives into the finally branch, then makes Path.unlink raise.
+    """
+    settings_path = tmp_path / "settings.json"
+    settings_path.write_text('{"existing": true}\n', encoding="utf-8")
+
+    def failing_replace(*_args: object, **_kwargs: object) -> None:
+        raise OSError("replace blocked by AV")
+
+    def failing_unlink(_self: Path, *_args: object, **_kwargs: object) -> None:
+        raise PermissionError("temp file held by AV")
+
+    monkeypatch.setattr(common.os, "replace", failing_replace)
+    monkeypatch.setattr(Path, "unlink", failing_unlink)
+    with pytest.raises(SystemExit):
+        common.save_settings(settings_path, {"new_key": "value"})
+    captured = capsys.readouterr()
+    assert ".tmp" in captured.err
+    assert "PermissionError" in captured.err or "held by AV" in captured.err
+
+
+def test_save_settings_finally_skips_unlink_when_no_temp_was_created(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """When this invocation never created the temp file, finally must not unlink it."""
+    settings_path = tmp_path / "settings.json"
+    settings_path.write_text('{"existing": true}\n', encoding="utf-8")
+
+    unlink_call_paths: list[Path] = []
+    original_unlink = Path.unlink
+
+    def recording_unlink(unlink_target: Path, *args: object, **kwargs: object) -> None:
+        unlink_call_paths.append(unlink_target)
+        original_unlink(unlink_target, *args, **kwargs)
+
+    def write_raises(*_args: object, **_kwargs: object) -> None:
+        raise FileExistsError("another writer's temp")
+
+    monkeypatch.setattr(common, "write_atomically_with_mode", write_raises)
+    monkeypatch.setattr(Path, "unlink", recording_unlink)
+    with pytest.raises(SystemExit):
+        common.save_settings(settings_path, {"new_key": "value"})
+    assert not any(
+        ".tmp." in each_path.name for each_path in unlink_call_paths
+    ), "finally must not unlink a temp file this invocation never created"
+
+
+def test_exit_with_error_prints_prefixed_message_and_exits_nonzero(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    with pytest.raises(SystemExit) as raised_exit:
+        common.exit_with_error("boom")
+    assert raised_exit.value.code == 1
+    assert "Error: boom" in capsys.readouterr().err
+
+
+def test_build_permission_rules_builds_one_rule_per_tool() -> None:
+    built_rules = common.build_permission_rules("/proj", ("Edit", "Read"))
+    assert built_rules == ["Edit(/proj/.claude/**)", "Read(/proj/.claude/**)"]
+
+
+def test_build_agent_config_deny_rule_embeds_tool_path_and_pattern() -> None:
+    built_rule = common.build_agent_config_deny_rule("Write", "/proj", "hooks/**")
+    assert built_rule == "Write(/proj/.claude/hooks/**)"
+
+
+def test_remove_matching_entries_from_list_filters_in_place_and_counts() -> None:
+    all_entries: list[object] = ["keep", "drop", "drop", 7]
+    removed_count = common.remove_matching_entries_from_list(
+        all_entries, lambda each_entry: each_entry == "drop"
+    )
+    assert removed_count == 2
+    assert all_entries == ["keep", 7]
+
+
+def test_load_settings_returns_empty_dict_when_file_missing(tmp_path: Path) -> None:
+    assert common.load_settings(tmp_path / "absent.json") == {}
+
+
+def test_load_settings_parses_existing_json_object(tmp_path: Path) -> None:
+    settings_path = tmp_path / "settings.json"
+    settings_path.write_text('{"permissions": {"allow": []}}', encoding="utf-8")
+    assert common.load_settings(settings_path) == {"permissions": {"allow": []}}
+
+
+def test_load_settings_exits_when_file_holds_invalid_json(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    settings_path = tmp_path / "settings.json"
+    settings_path.write_text("not json", encoding="utf-8")
+    with pytest.raises(SystemExit):
+        common.load_settings(settings_path)
+    assert "not valid JSON" in capsys.readouterr().err
+
+
+def test_serialize_settings_to_json_text_sorts_keys() -> None:
+    serialized_text = common.serialize_settings_to_json_text({"b": 1, "a": 2})
+    assert serialized_text.index('"a"') < serialized_text.index('"b"')
+    assert json.loads(serialized_text) == {"a": 2, "b": 1}
+
+
+def test_append_if_missing_appends_only_new_values() -> None:
+    all_entries: list[object] = ["existing"]
+    assert common.append_if_missing(all_entries, "fresh") is True
+    assert common.append_if_missing(all_entries, "fresh") is False
+    assert all_entries == ["existing", "fresh"]
+
+
+def test_ensure_dict_section_creates_missing_and_returns_existing() -> None:
+    all_settings: dict[str, object] = {}
+    created_section = common.ensure_dict_section(all_settings, "permissions")
+    assert created_section == {}
+    assert all_settings["permissions"] is created_section
+    assert common.ensure_dict_section(all_settings, "permissions") is created_section
+
+
+def test_ensure_dict_section_exits_on_non_dict_value(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    all_settings: dict[str, object] = {"permissions": "oops"}
+    with pytest.raises(SystemExit):
+        common.ensure_dict_section(all_settings, "permissions")
+    assert "not a JSON object" in capsys.readouterr().err
+
+
+def test_ensure_list_entry_creates_missing_and_returns_existing() -> None:
+    permissions_section: dict[str, object] = {}
+    created_entry = common.ensure_list_entry(permissions_section, "allow")
+    assert created_entry == []
+    assert permissions_section["allow"] is created_entry
+    assert common.ensure_list_entry(permissions_section, "allow") is created_entry
+
+
+def test_ensure_list_entry_exits_on_non_list_value(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    permissions_section: dict[str, object] = {"allow": {}}
+    with pytest.raises(SystemExit):
+        common.ensure_list_entry(permissions_section, "allow")
+    assert "not a JSON array" in capsys.readouterr().err
+
+
+def test_prune_empty_list_then_empty_section_removes_empty_structures() -> None:
+    all_settings: dict[str, object] = {"permissions": {"allow": []}}
+    common.prune_empty_list_then_empty_section(all_settings, "permissions", "allow")
+    assert all_settings == {}
+
+
+def test_prune_empty_list_then_empty_section_keeps_populated_structures() -> None:
+    all_settings: dict[str, object] = {
+        "permissions": {"allow": ["Edit(/proj/.claude/**)"], "deny": []}
+    }
+    common.prune_empty_list_then_empty_section(all_settings, "permissions", "deny")
+    assert all_settings == {"permissions": {"allow": ["Edit(/proj/.claude/**)"]}}
+

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

@@ -355,6 +355,24 @@ def test_is_trust_entry_rejects_cross_project_path_suffix_collision() -> None:
     )
 
 
+def test_is_valid_project_root_shared_by_grant_and_revoke_modules(
+    tmp_path: Path,
+) -> None:
+    """Grant and revoke import the same helper, so both agree on the marker contract."""
+    grant_module = _load_grant_module()
+    revoke_module = _load_revoke_module()
+    git_marker_project_root = tmp_path / "git_project"
+    (git_marker_project_root / ".git").mkdir(parents=True)
+    claude_marker_project_root = tmp_path / "claude_project"
+    (claude_marker_project_root / ".claude").mkdir(parents=True)
+    bare_directory = tmp_path / "no_marker"
+    bare_directory.mkdir()
+    for each_module in (grant_module, revoke_module):
+        assert each_module.is_valid_project_root(git_marker_project_root) is True
+        assert each_module.is_valid_project_root(claude_marker_project_root) is True
+        assert each_module.is_valid_project_root(bare_directory) is False
+
+
 def test_second_grant_is_idempotent_when_no_other_settings_changed(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
 ) -> None:

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

@@ -160,6 +160,24 @@ def test_path_contains_glob_metacharacters_local_tuple_uses_all_collection_prefi
     )
 
 
+def test_is_valid_project_root_detects_git_marker(tmp_path: Path) -> None:
+    git_project_root = tmp_path / "git_project"
+    (git_project_root / ".git").mkdir(parents=True)
+    assert common.is_valid_project_root(git_project_root) is True
+
+
+def test_is_valid_project_root_detects_claude_marker(tmp_path: Path) -> None:
+    claude_project_root = tmp_path / "claude_project"
+    (claude_project_root / ".claude").mkdir(parents=True)
+    assert common.is_valid_project_root(claude_project_root) is True
+
+
+def test_is_valid_project_root_rejects_unmarked_directory(tmp_path: Path) -> None:
+    unmarked_directory = tmp_path / "no_marker"
+    unmarked_directory.mkdir()
+    assert common.is_valid_project_root(unmarked_directory) is False
+
+
 def test_is_valid_project_root_uses_extracted_directory_marker_constants() -> None:
     """is_valid_project_root must reference extracted constants, not inline string literals."""
     source_text = inspect.getsource(common.is_valid_project_root)

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

@@ -9,6 +9,7 @@ Covers:
 
 import importlib.util
 import inspect
+import os
 import subprocess
 import sys
 import unittest.mock
@@ -93,6 +94,13 @@ def stage_file(repository_root: Path, relative_path: str) -> None:
     run_git_in_repository(repository_root, "add", "--", relative_path)
 
 
+@pytest.fixture(autouse=True)
+def isolated_git_environment(monkeypatch: pytest.MonkeyPatch) -> None:
+    for each_variable_name in list(os.environ):
+        if each_variable_name.startswith("GIT_"):
+            monkeypatch.delenv(each_variable_name, raising=False)
+
+
 @pytest.fixture()
 def temporary_git_repository(tmp_path: Path) -> Path:
     repository_root = tmp_path / "repository_under_test"
@@ -320,6 +328,35 @@ def test_main_staged_mode_exits_zero_when_nothing_staged(
     assert exit_code == 0
 
 
+def test_main_staged_mode_passes_when_only_terminology_findings_exist(
+    temporary_git_repository: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    write_file(temporary_git_repository / "quota.py", "first_count = 1\n")
+    commit_all_files(temporary_git_repository, "initial")
+    write_file(
+        temporary_git_repository / "quota.py",
+        "first_count = 1\npremium_interactions = 1\n",
+    )
+    write_file(
+        temporary_git_repository / "README.md",
+        "The premium-request budget gates the run.\n",
+    )
+    stage_file(temporary_git_repository, "quota.py")
+    stage_file(temporary_git_repository, "README.md")
+
+    monkeypatch.chdir(temporary_git_repository)
+    terminology_findings = gate_module.staged_terminology_findings(
+        temporary_git_repository
+    )
+    exit_code = gate_module.main(["--staged"])
+
+    assert any(
+        "premium-request" in each_finding for each_finding in terminology_findings
+    )
+    assert exit_code == 0
+
+
 def test_added_lines_for_staged_file_returns_empty_for_modified_file_with_no_additions(
     temporary_git_repository: Path,
 ) -> None:

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

@@ -0,0 +1,159 @@
+"""Direct unit tests for the unified reviewer_availability pre-check.
+
+Every case drives the production ``main`` path through
+``evaluate_reviewer_availability``. Copilot cases stub only the ``gh``
+subprocess boundary inside ``copilot_quota`` (``_run_gh``), reusing the same
+captured fixture ``test_copilot_quota.py`` drives. Opt-out cases set or clear
+``CLAUDE_REVIEWS_DISABLED`` directly.
+"""
+
+import importlib.util
+import json
+import sys
+from pathlib import Path
+from types import ModuleType
+
+import pytest
+
+
+def _load_module(module_name: str) -> ModuleType:
+    scripts_directory = Path(__file__).parent.parent
+    if str(scripts_directory) not in sys.path:
+        sys.path.insert(0, str(scripts_directory))
+    module_path = scripts_directory / f"{module_name}.py"
+    specification = importlib.util.spec_from_file_location(module_name, module_path)
+    assert specification is not None
+    assert specification.loader is not None
+    module = importlib.util.module_from_spec(specification)
+    sys.modules[specification.name] = module
+    specification.loader.exec_module(module)
+    return module
+
+
+copilot_quota = _load_module("copilot_quota")
+reviewer_availability = _load_module("reviewer_availability")
+
+FIXTURE_PATH = Path(__file__).parent / "fixtures" / "copilot_internal_user_jonecho.json"
+AVAILABLE_USER_JSON = FIXTURE_PATH.read_text(encoding="utf-8")
+FAKE_TOKEN_RESULT = (0, "ghp_faketoken_value\n")
+
+
+def _exhausted_user_json() -> str:
+    user = json.loads(AVAILABLE_USER_JSON)
+    premium = user["quota_snapshots"]["premium_interactions"]
+    premium["remaining"] = 0
+    premium["quota_remaining"] = 0.0
+    premium["percent_remaining"] = 0.0
+    return json.dumps(user)
+
+
+def _gh_stub(token_result: tuple[int, str], api_result: tuple[int, str]):
+    def _fake_run_gh(
+        command_arguments: list[str],
+        extra_environment: dict[str, str] | None = None,
+    ) -> tuple[int, str]:
+        if command_arguments and command_arguments[0] == "auth":
+            return token_result
+        if command_arguments and command_arguments[0] == "api":
+            return api_result
+        raise AssertionError(f"unexpected gh command {command_arguments}")
+
+    return _fake_run_gh
+
+
+@pytest.fixture(autouse=True)
+def _isolate_reviewer_environment(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    monkeypatch.delenv("COPILOT_QUOTA_ACCOUNT", raising=False)
+    monkeypatch.delenv("CLAUDE_REVIEWS_DISABLED", raising=False)
+    monkeypatch.setattr(
+        reviewer_availability, "COPILOT_QUOTA_DEFAULT_ENV_FILE_PATH", tmp_path / ".env"
+    )
+
+
+def test_main_reports_copilot_available_when_quota_confirmed_available(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    monkeypatch.setenv("COPILOT_QUOTA_ACCOUNT", "jonecho")
+    monkeypatch.setattr(
+        copilot_quota, "_run_gh", _gh_stub(FAKE_TOKEN_RESULT, (0, AVAILABLE_USER_JSON))
+    )
+    exit_code = reviewer_availability.main(["--reviewer", "copilot"])
+    captured = capsys.readouterr()
+    assert exit_code == reviewer_availability.EXIT_CODE_REVIEWER_AVAILABLE
+    assert "running Copilot" in captured.out
+
+
+def test_main_reports_copilot_down_when_opted_out_via_env(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "copilot")
+
+    def _fail_if_called(
+        command_arguments: list[str],
+        extra_environment: dict[str, str] | None = None,
+    ) -> tuple[int, str]:
+        raise AssertionError("gh must not run once copilot is opted out")
+
+    monkeypatch.setattr(copilot_quota, "_run_gh", _fail_if_called)
+    exit_code = reviewer_availability.main(["--reviewer", "copilot"])
+    captured = capsys.readouterr()
+    assert exit_code == reviewer_availability.EXIT_CODE_REVIEWER_DOWN
+    assert "CLAUDE_REVIEWS_DISABLED" in captured.err
+
+
+def test_main_reports_copilot_down_when_out_of_quota(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    monkeypatch.setenv("COPILOT_QUOTA_ACCOUNT", "jonecho")
+    monkeypatch.setattr(
+        copilot_quota,
+        "_run_gh",
+        _gh_stub(FAKE_TOKEN_RESULT, (0, _exhausted_user_json())),
+    )
+    exit_code = reviewer_availability.main(["--reviewer", "copilot"])
+    captured = capsys.readouterr()
+    assert exit_code == reviewer_availability.EXIT_CODE_REVIEWER_DOWN
+    assert "scenario A" in captured.err
+
+
+def test_main_reports_copilot_down_when_quota_api_is_down(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    monkeypatch.setenv("COPILOT_QUOTA_ACCOUNT", "jonecho")
+    monkeypatch.setattr(
+        copilot_quota, "_run_gh", _gh_stub(FAKE_TOKEN_RESULT, (0, "not json at all"))
+    )
+    exit_code = reviewer_availability.main(["--reviewer", "copilot"])
+    captured = capsys.readouterr()
+    assert exit_code == reviewer_availability.EXIT_CODE_REVIEWER_DOWN
+    assert "scenario B" in captured.err
+
+
+def test_main_reports_copilot_down_when_no_account_configured(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    exit_code = reviewer_availability.main(["--reviewer", "copilot"])
+    captured = capsys.readouterr()
+    assert exit_code == reviewer_availability.EXIT_CODE_REVIEWER_DOWN
+    assert "scenario C" in captured.err
+
+
+def test_main_reports_bugbot_available_when_not_opted_out(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    exit_code = reviewer_availability.main(["--reviewer", "bugbot"])
+    captured = capsys.readouterr()
+    assert exit_code == reviewer_availability.EXIT_CODE_REVIEWER_AVAILABLE
+    assert "bugbot" in captured.out
+
+
+def test_main_reports_bugbot_down_when_opted_out_via_env(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "bugbot")
+    exit_code = reviewer_availability.main(["--reviewer", "bugbot"])
+    captured = capsys.readouterr()
+    assert exit_code == reviewer_availability.EXIT_CODE_REVIEWER_DOWN
+    assert "CLAUDE_REVIEWS_DISABLED" in captured.err

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

@@ -0,0 +1,36 @@
+"""Tests for reviewer_availability_constants.py extracted constant set."""
+
+import importlib.util
+from pathlib import Path
+from types import ModuleType
+
+
+def _load_constants_module() -> ModuleType:
+    module_path = (
+        Path(__file__).parent.parent
+        / "pr_loop_shared_constants"
+        / "reviewer_availability_constants.py"
+    )
+    specification = importlib.util.spec_from_file_location(
+        "pr_loop_shared_constants.reviewer_availability_constants", module_path
+    )
+    assert specification is not None
+    assert specification.loader is not None
+    module = importlib.util.module_from_spec(specification)
+    specification.loader.exec_module(module)
+    return module
+
+
+constants_module = _load_constants_module()
+
+
+def test_available_exit_code_matches_the_posix_success_convention() -> None:
+    assert constants_module.EXIT_CODE_REVIEWER_AVAILABLE == 0
+
+
+def test_down_exit_code_is_distinct_from_the_available_exit_code() -> None:
+    assert (
+        constants_module.EXIT_CODE_REVIEWER_DOWN
+        != constants_module.EXIT_CODE_REVIEWER_AVAILABLE
+    )
+    assert constants_module.EXIT_CODE_REVIEWER_DOWN != 0

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

@@ -120,3 +120,17 @@ def test_cli_main_supports_bugteam_reviewer(
 ) -> None:
     monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "bugteam")
     assert reviews_disabled.main(["--reviewer", "bugteam"]) == 0
+
+
+def test_cli_main_supports_copilot_reviewer(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "copilot")
+    assert reviews_disabled.main(["--reviewer", "copilot"]) == 0
+
+
+def test_cli_main_returns_one_for_copilot_when_only_bugbot_disabled(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "bugbot")
+    assert reviews_disabled.main(["--reviewer", "copilot"]) == 1

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

@@ -191,7 +191,7 @@ def test_does_not_flag_y_to_ies_plural_variant() -> None:
     assert sweep_diff(diff) == []
 
 
-def test_still_flags_non_plural_divergent_tail() -> None:
+def test_does_not_flag_spaced_prose_sharing_identifier_prefix() -> None:
     diff = (
         "diff --git a/api/quota.py b/api/quota.py\n"
         "--- a/api/quota.py\n"
@@ -204,9 +204,19 @@ def test_still_flags_non_plural_divergent_tail() -> None:
         "@@ -0,0 +1,1 @@\n"
         "+The premium request budget gates the run.\n"
     )
-    findings = sweep_diff(diff)
-    assert len(findings) == 1
-    assert "premium request" in findings[0]
+    assert sweep_diff(diff) == []
+
+
+def test_does_not_flag_ordinary_sentence_sharing_loop_variable_prefix() -> None:
+    diff = (
+        "diff --git a/api/scan.py b/api/scan.py\n"
+        "--- a/api/scan.py\n"
+        "+++ b/api/scan.py\n"
+        "@@ -0,0 +1,2 @@\n"
+        "+each_node = walk(tree)\n"
+        '+DESCRIPTION = "Each attempt polls the review endpoint once."\n'
+    )
+    assert sweep_diff(diff) == []
 
 
 def test_flags_near_miss_inside_code_comment() -> None:

package/agents/clean-coder.md

@@ -1,6 +1,7 @@
 ---
 name: clean-coder
 description: "Use PROACTIVELY for ALL code generation — feature development, bug fixes, refactoring, hook creation, automation scripts, and any task that produces code. Internalizes CODE_RULES.md and the 8-dimension readability standard so thoroughly that /check finds zero issues. The definitive code-writing agent."
+model: opus
 tools: Read, Write, Edit, Bash, Grep, Glob, Task, Skill
 color: green
 ---
@@ -436,6 +437,8 @@ This default is overridden by explicit user instruction such as "refactor this e
 
 Docstrings on functions, methods, classes, and modules are encouraged for public APIs. The self-documenting-names gate inspects inline `#` and block `#` comments only; docstrings are exempt from that gate.
 
+Write a behavior-illustrating docstring in the diagram-first shape: one summary line, then a `::` literal block or a doctest that shows a concrete input and its marked outcome (with `ok:` / `flag:` contrast lines where a pass-and-fail pair helps), then a couple of short neutral prose lines, then the `Args:` / `Returns:` sections. Two hooks back this: `check_docstring_runon_sentence` flags a run-on prose wall, and `check_docstring_prose_wall_without_illustration` flags a narrative that runs long with no diagram. See `../rules/plain-illustrative-docstrings.md` for the shape and a worked example.
+
 ## Audit Awareness
 
 Code clean-coder writes will be audited later against the A–P bug categories from `code-quality-agent`. The hooks listed in this file enforce the Category J slice at write time, but A–I and K–P surface only in audit. For each category's full rubric, sub-bucket decomposition, and concrete checks, see `../audit-rubrics/category_rubrics/` (relative to this agent file). While generating code, anticipate the full A–P surface so the first write clears every audit category.

package/audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md

@@ -28,7 +28,7 @@ Decomposition is by the **kind of docstring claim** that needs to be cross-check
 | O6 | Free-form `Args:`-adjacent claims | A docstring's `Returns:` / `Raises:` / `Note:` / `Example:` sections make claims (`returns shared-temp only`, `raises ValueError on missing key`). Verify each claim against the body. When a docstring enumerates the inputs a body counts (a "field counts as read when ..." list, a list of conditions treated as a match, a list of cases the body skips), list every union member and every suppressor the body applies (`read_names = a | b | c`, each early-return guard) and confirm each appears in the prose enumeration. A union member or suppressor the body applies but the prose omits is an O6 finding. When a docstring sentence excludes a named category of input from what the function flags (`X are not dispatch steps`, `Y is not a match`), confirm the axis the prose excludes on is the axis the body's branch condition actually keys on. A body that flags a call when it sits inside an `If.test` guard, paired with prose that excludes by the call's receiver shape (`method-on-local calls inside a branch are not dispatch steps`), is an O6 finding: a guarded method-on-local call is flagged even though the prose lists it as excluded — the exclusion is keyed to the wrong axis. The single-condition shared-fallback shape of this drift — a summary that scopes a fallback call to one condition while the body routes to that same call from two or more early-return guards — is gated deterministically at Write/Edit time by `check_docstring_fallback_branch_coverage`, so the audit lane focuses on the O6 shapes the gate cannot match. The exception-guard shape of this drift — a docstring that promises a malformed payload `resolves to None` while a payload subscript (`payload["key"]`, `float(payload["key"])`) sits outside the try/except whose handler returns None, so a present-but-malformed payload raises rather than resolving to None — is gated deterministically at Write/Edit time by `check_docstring_unguarded_malformed_payload_claim`, so the audit lane focuses on the wider Raises/None-on-failure claims the gate cannot match. A `Returns:` that names the mechanism, tool, or output format the function produces (`instructing a StructuredOutput summary`, `returns a YAML document`, `emits a JSON object`) matches the artifact the body actually builds: a prompt body that asks the agent to "Return strictly a JSON object" while the docstring claims it "instruct[s] a StructuredOutput" summary is an O6 finding, because the named tool appears nowhere in the emitted text. See `../../rules/docstring-prose-matches-implementation.md`. |
 | O7 | Module-doc-vs-split-module after refactor | When a refactor moves a responsibility to a sibling module, the originating module's docstring and the receiving module's docstring both describe the home of that responsibility. A module docstring should describe only the responsibilities it owns. |
 | O8 | Companion-doc ordering/content vs producer | When a PR changes a producer function's ordering or union, read that skill's companion `SKILL.md` and sibling `.md` docs for any sentence naming the same produced artifact (a file path, a JSON key, a named list). A doc sentence that claims the artifact is `sorted` / `alphabetical` / `in sorted order`, or holds `just the at-risk names` / `only the current set`, while the producer merges stored names with new names and appends — preserving file order, not re-sorting the union — is an O8 finding on both counts (wrong order claim, hidden merged-in entries). The finding stands even when the PR diff never touched the `.md` file, because the behavior change orphaned the doc claim. See `../../rules/docstring-prose-matches-implementation.md`. |
-| O9 | Python docstring plainness for a general developer | A changed module / class / public-function docstring's narrative prose — the summary and description before the first `Args:` / `Returns:` / `Raises:` / `Yields:` section — reads plainly and paints a concrete scene a general developer follows on first read. Flag a narrative that stacks abstract machinery nouns into a wall (`the SIGINT install/restore/installability check, the atexit terminal-record registration, and the interrupted-run finalizer`), that defines a thing by what it is not (`the non-promoter-specific machinery`), or that runs one sentence long while joining clauses with an em-dash or a semicolon. The deterministic run-on mark is gated at Write/Edit time by `check_docstring_runon_sentence` in `code_rules_docstrings.py`, so this lane carries the illustrative-and-brief judgment the gate cannot: whether a stranger to the code pictures the moment, the input, and the outcome after one read. See `../../rules/plain-illustrative-docstrings.md`. |
+| O9 | Python docstring plainness for a general developer | A changed module / class / public-function docstring's narrative prose — the summary and description before the first `Args:` / `Returns:` / `Raises:` / `Yields:` section — reads plainly and paints a concrete scene a general developer follows on first read. Flag a narrative that stacks abstract machinery nouns into a wall (`the SIGINT install/restore/installability check, the atexit terminal-record registration, and the interrupted-run finalizer`), that defines a thing by what it is not (`the non-promoter-specific machinery`), or that runs one sentence long while joining clauses with an em-dash or a semicolon. The diagram-first shape carries this best: a summary line, then a `::` example block or a doctest that shows a concrete input and its marked outcome, then a couple of short prose lines. The deterministic run-on mark is gated at Write/Edit time by `check_docstring_runon_sentence` in `code_rules_docstrings.py`, and a narrative that runs more than six prose lines with no such block is gated by `check_docstring_prose_wall_without_illustration` in the same module, so this lane carries the judgment the gates cannot: whether a stranger to the code pictures the moment, the input, and the outcome after one read, and whether the diagram truly illustrates — a real input, a marked outcome, an `ok:` / `flag:` contrast a reader learns from. See `../../rules/plain-illustrative-docstrings.md`. |
 
 ---
 

package/bin/install.mjs

@@ -294,10 +294,13 @@ function backupClaudeHubBeforeOverwrite(destPath, incomingPath) {
 }
 
 /**
- * Hook script paths that were folded into the PreToolUse dispatcher in Stage 1.
- * These entries no longer appear in hooks.json but must still be recognized as
- * managed so a reinstall from an older settings shape prunes them and they do
- * not double-run alongside the dispatcher.
+ * PreToolUse hook script paths the installer manages even though hooks.json
+ * carries no standalone entry for them. Most were folded into the PreToolUse
+ * dispatcher in Stage 1; md_to_html_blocker is a retired hook with no script on
+ * disk. Each path stays in this set so a reinstall from an older settings shape
+ * prunes its standalone entry — a folded hook would otherwise double-run
+ * alongside the dispatcher, and the retired hook's entry would point at a
+ * missing script.
  */
 export const FOLDED_HOOK_RELATIVE_PATHS = new Set([
     'blocking/write_existing_file_blocker.py',
@@ -316,18 +319,23 @@ export const FOLDED_HOOK_RELATIVE_PATHS = new Set([
     'blocking/pytest_testpaths_orphan_blocker.py',
     'blocking/open_questions_in_plans_blocker.py',
     'blocking/plain_language_blocker.py',
+    'blocking/md_to_html_blocker.py',
 ]);
 
 /**
- * Hook script paths that were folded into the PostToolUse dispatcher. These
- * after-write hooks no longer appear in hooks.json but must still be recognized
- * as managed so a reinstall from an older settings shape prunes them and they do
- * not double-run alongside the PostToolUse dispatcher.
+ * After-write hook script paths the installer manages even though hooks.json
+ * carries no standalone entry for them. mypy_validator and auto_formatter run
+ * hosted inside the PostToolUse dispatcher; doc_gist_auto_publish and
+ * md_to_html_companion are retired hooks with no script on disk. Each path stays
+ * in this set so a reinstall from an older settings shape prunes its standalone
+ * entry — a hosted hook would otherwise double-run alongside the dispatcher, and
+ * a retired hook's entry would point at a missing script.
  */
 export const POST_FOLDED_HOOK_RELATIVE_PATHS = new Set([
     'validation/mypy_validator.py',
     'workflow/auto_formatter.py',
     'workflow/doc_gist_auto_publish.py',
+    'workflow/md_to_html_companion.py',
 ]);
 
 /**