claude-dev-env 1.26.4 → 1.27.0

package/hooks/blocking/hedging_language_blocker.py

@@ -11,6 +11,9 @@ import os
 import re
 import sys
 
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "config"))
+from messages import USER_FACING_NOTICE
+
 PLUGIN_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
 
 RESEARCH_MODE_SKILL_SEARCH_PATHS = [
@@ -99,14 +102,19 @@ def main() -> None:
 
     formatted_term_list = ", ".join(f'"{term}"' for term in found_hedging_terms)
 
-    research_mode_content = "(Could not load research-mode skill file)"
+    resolved_skill_path: str | None = None
     for each_skill_path in RESEARCH_MODE_SKILL_SEARCH_PATHS:
-        try:
-            with open(each_skill_path, encoding="utf-8") as skill_file:
-                research_mode_content = skill_file.read()
-                break
-        except OSError:
-            continue
+        if os.path.exists(each_skill_path):
+            resolved_skill_path = each_skill_path
+            break
+
+    if resolved_skill_path is not None:
+        skill_reference = f"under the research-mode constraints defined in:\n\n{resolved_skill_path}"
+    else:
+        skill_reference = (
+            "under research-mode constraints "
+            "(no research-mode skill installed; verify with sources or reply 'I don't know')"
+        )
 
     block_response = {
         "decision": "block",
@@ -114,12 +122,13 @@ def main() -> None:
             f"ANTI-HALLUCINATION GUARDRAIL: Your response contains hedging language: "
             f"{formatted_term_list}. "
             f"These words signal unverified claims. You MUST rewrite your response "
-            f"with these constraints active:\n\n"
-            f"{research_mode_content}\n\n"
+            f"{skill_reference}\n\n"
             f"Do NOT simply remove the hedging word and keep the unverified claim. "
             f"Either VERIFY it with a source or replace it with 'I don't know'.\n\n"
             f"You MUST re-output the complete, revised response with the corrections applied."
         ),
+        "systemMessage": USER_FACING_NOTICE,
+        "suppressOutput": True,
     }
 
     print(json.dumps(block_response))

package/hooks/blocking/tdd_enforcer.py

@@ -6,12 +6,19 @@ Blocks writes to production source files when no matching test exists
 or the matching test has not been modified within the configured
 freshness window. Enforces "TDD IS NON-NEGOTIABLE" from CLAUDE.md.
 """
+import ast
 import json
 import re
 import sys
 import time
 from pathlib import Path
 
+_hooks_root_path_string = str(Path(__file__).resolve().parent.parent)
+if _hooks_root_path_string not in sys.path:
+    sys.path.insert(0, _hooks_root_path_string)
+
+from config.messages import USER_FACING_TDD_NOTICE
+
 PRODUCTION_EXTENSIONS = {'.py', '.ts', '.tsx', '.js', '.jsx'}
 SKIP_PATTERNS = {
     'test_', '_test.', '.test.', 'tests/', '__tests__/',
@@ -33,8 +40,41 @@ def _freshness_seconds() -> int:
     return 600
 
 
-def _bypass_sentinel() -> str:
-    return "# pragma: no-tdd-gate"
+def _constants_only_allowed_node_types() -> tuple[type, ...]:
+    return (
+        ast.Import,
+        ast.ImportFrom,
+        ast.Assign,
+        ast.AnnAssign,
+    )
+
+
+def _is_module_docstring_expression(module_level_node: ast.stmt) -> bool:
+    if not isinstance(module_level_node, ast.Expr):
+        return False
+    expression_value = module_level_node.value
+    if not isinstance(expression_value, ast.Constant):
+        return False
+    return isinstance(expression_value.value, str)
+
+
+def _is_constants_only_python_content(content: str) -> bool:
+    if not content.strip():
+        return False
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return False
+    if not parsed_tree.body:
+        return False
+    allowed_node_types = _constants_only_allowed_node_types()
+    for each_top_level_node in parsed_tree.body:
+        if isinstance(each_top_level_node, allowed_node_types):
+            continue
+        if _is_module_docstring_expression(each_top_level_node):
+            continue
+        return False
+    return True
 
 
 def _tests_directory_name() -> str:
@@ -154,13 +194,17 @@ def has_fresh_test(
 
 def build_deny_reason(production_path: Path, all_candidates: list[Path]) -> str:
     candidate_lines = "\n".join(f"  - {each_path}" for each_path in all_candidates)
+    hook_source_path = Path(__file__).resolve()
     return (
         f"[TDD] Blocking write to production file: {production_path}\n"
         f"No matching test file exists, or it has not been modified within the last "
         f"{_freshness_seconds()} seconds.\n"
         f"Expected one of:\n{candidate_lines}\n"
-        f"Write a failing test first (RED), then the minimum code to pass it (GREEN).\n"
-        f"Bypass (discouraged): include the sentinel '{_bypass_sentinel()}' in the file content."
+        f"Write a failing test first (RED), then the minimum code to pass it (GREEN).\n\n"
+        f"If this file legitimately does not need a test (for example, a module containing only "
+        f"module-level constants with no behavior), that is a hook enhancement, not a bypass. "
+        f"Propose an exemption rule in {hook_source_path} so every similar file benefits "
+        f"automatically. Do not add escape-hatch markers to production files."
     )
 
 
@@ -180,7 +224,9 @@ def emit_deny(reason: str) -> None:
             "hookEventName": "PreToolUse",
             "permissionDecision": "deny",
             "permissionDecisionReason": reason,
-        }
+        },
+        "suppressOutput": True,
+        "systemMessage": USER_FACING_TDD_NOTICE,
     }
     print(json.dumps(deny_payload))
 
@@ -252,7 +298,7 @@ def main() -> None:
 
     # Block production code - require confirmation
     written_content = _extract_written_content(tool_name, tool_input)
-    if _bypass_sentinel() in written_content:
+    if tool_name == "Write" and ext == ".py" and _is_constants_only_python_content(written_content):
         emit_allow()
         sys.exit(0)
 

package/hooks/blocking/test_destructive_command_blocker.py

@@ -4,6 +4,7 @@ import json
 import os
 import subprocess
 import sys
+import tempfile
 from pathlib import Path
 
 
@@ -165,3 +166,171 @@ def test_rm_rf_still_asks_when_redirect_env_var_is_unset() -> None:
 
     response = json.loads(result.stdout)
     assert response["hookSpecificOutput"]["permissionDecision"] == "ask"
+
+
+def _run_hook_with_fake_home(
+    payload: dict,
+    fake_home: Path,
+    working_directory: Path,
+    disable_ephemeral_auto_allow: bool = True,
+) -> subprocess.CompletedProcess[str]:
+    child_environment = os.environ.copy()
+    child_environment.pop(GH_REDIRECT_ACTIVE_ENV_VAR, None)
+    child_environment["HOME"] = str(fake_home)
+    child_environment["USERPROFILE"] = str(fake_home)
+    if disable_ephemeral_auto_allow:
+        child_environment["CLAUDE_DESTRUCTIVE_DISABLE_EPHEMERAL_AUTO_ALLOW"] = "1"
+    else:
+        child_environment.pop("CLAUDE_DESTRUCTIVE_DISABLE_EPHEMERAL_AUTO_ALLOW", None)
+    return subprocess.run(
+        [sys.executable, str(SCRIPT_PATH)],
+        input=json.dumps(payload),
+        text=True,
+        capture_output=True,
+        check=False,
+        env=child_environment,
+        cwd=str(working_directory),
+    )
+
+
+def _write_settings_with_allow_list(fake_home: Path, allow_list: list[str]) -> None:
+    claude_directory = fake_home / ".claude"
+    claude_directory.mkdir(parents=True, exist_ok=True)
+    settings_payload = {"hooks": {"allowGitResetHardProjects": allow_list}}
+    (claude_directory / "settings.json").write_text(
+        json.dumps(settings_payload), encoding="utf-8"
+    )
+
+
+def test_git_reset_hard_allowed_when_cwd_matches_settings_allow_list(tmp_path: Path) -> None:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    project_directory = tmp_path / "approved_project"
+    project_directory.mkdir()
+    project_path_forward = str(project_directory).replace("\\", "/")
+    _write_settings_with_allow_list(fake_home, [project_path_forward])
+    payload = _make_bash_payload("git reset --hard origin/main")
+
+    result = _run_hook_with_fake_home(payload, fake_home, project_directory)
+
+    assert result.stdout.strip() == ""
+    assert result.returncode == 0
+
+
+def test_git_reset_hard_asks_when_cwd_not_in_settings_allow_list(tmp_path: Path) -> None:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    approved_directory = tmp_path / "approved_project"
+    approved_directory.mkdir()
+    unapproved_directory = tmp_path / "unapproved_project"
+    unapproved_directory.mkdir()
+    approved_path_forward = str(approved_directory).replace("\\", "/")
+    _write_settings_with_allow_list(fake_home, [approved_path_forward])
+    payload = _make_bash_payload("git reset --hard origin/main")
+
+    result = _run_hook_with_fake_home(payload, fake_home, unapproved_directory)
+
+    response = json.loads(result.stdout)
+    assert response["hookSpecificOutput"]["permissionDecision"] == "ask"
+    assert "git reset --hard" in response["hookSpecificOutput"]["permissionDecisionReason"]
+
+
+def test_git_reset_hard_asks_when_settings_missing(tmp_path: Path) -> None:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    project_directory = tmp_path / "unapproved_project"
+    project_directory.mkdir()
+    payload = _make_bash_payload("git reset --hard origin/main")
+
+    result = _run_hook_with_fake_home(payload, fake_home, project_directory)
+
+    response = json.loads(result.stdout)
+    assert response["hookSpecificOutput"]["permissionDecision"] == "ask"
+
+
+def test_git_reset_hard_asks_when_allow_list_is_empty(tmp_path: Path) -> None:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    project_directory = tmp_path / "some_project"
+    project_directory.mkdir()
+    _write_settings_with_allow_list(fake_home, [])
+    payload = _make_bash_payload("git reset --hard origin/main")
+
+    result = _run_hook_with_fake_home(payload, fake_home, project_directory)
+
+    response = json.loads(result.stdout)
+    assert response["hookSpecificOutput"]["permissionDecision"] == "ask"
+
+
+def test_git_reset_hard_allowed_in_linked_git_worktree(tmp_path: Path) -> None:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    main_repository = tmp_path / "main_repository"
+    main_repository.mkdir()
+    subprocess.run(["git", "init", "-q"], cwd=main_repository, check=True)
+    subprocess.run(["git", "commit", "-q", "--allow-empty", "-m", "init"], cwd=main_repository, check=True)
+    worktree_directory = tmp_path / "worktree_copy"
+    subprocess.run(
+        ["git", "worktree", "add", "-q", "-b", "feature", str(worktree_directory)],
+        cwd=main_repository,
+        check=True,
+    )
+    payload = _make_bash_payload("git reset --hard origin/main")
+
+    result = _run_hook_with_fake_home(payload, fake_home, worktree_directory, disable_ephemeral_auto_allow=False)
+
+    assert result.stdout.strip() == ""
+    assert result.returncode == 0
+
+
+def test_git_reset_hard_allowed_when_path_contains_worktrees_segment(tmp_path: Path) -> None:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    worktree_directory = tmp_path / "worktrees" / "some_feature"
+    worktree_directory.mkdir(parents=True)
+    payload = _make_bash_payload("git reset --hard origin/main")
+
+    result = _run_hook_with_fake_home(payload, fake_home, worktree_directory, disable_ephemeral_auto_allow=False)
+
+    assert result.stdout.strip() == ""
+    assert result.returncode == 0
+
+
+def test_git_reset_hard_allowed_under_os_temp_directory() -> None:
+    fake_home = Path(tempfile.mkdtemp(prefix="home_"))
+    working_directory = Path(tempfile.mkdtemp(prefix="ephemeral_work_"))
+    payload = _make_bash_payload("git reset --hard origin/main")
+
+    result = _run_hook_with_fake_home(payload, fake_home, working_directory, disable_ephemeral_auto_allow=False)
+
+    assert result.stdout.strip() == ""
+    assert result.returncode == 0
+
+
+def test_git_reset_hard_asks_in_plain_directory_with_no_settings(tmp_path: Path) -> None:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    plain_directory = tmp_path / "regular_project"
+    plain_directory.mkdir()
+    payload = _make_bash_payload("git reset --hard origin/main")
+
+    result = _run_hook_with_fake_home(payload, fake_home, plain_directory)
+
+    response = json.loads(result.stdout)
+    assert response["hookSpecificOutput"]["permissionDecision"] == "ask"
+
+
+def test_git_reset_hard_asks_when_settings_file_is_invalid_json(tmp_path: Path) -> None:
+    fake_home = tmp_path / "home"
+    (fake_home / ".claude").mkdir(parents=True)
+    (fake_home / ".claude" / "settings.json").write_text(
+        "{not valid json", encoding="utf-8"
+    )
+    project_directory = tmp_path / "unapproved_project"
+    project_directory.mkdir()
+    payload = _make_bash_payload("git reset --hard origin/main")
+
+    result = _run_hook_with_fake_home(payload, fake_home, project_directory)
+
+    response = json.loads(result.stdout)
+    assert response["hookSpecificOutput"]["permissionDecision"] == "ask"

package/hooks/blocking/test_hedging_language_blocker.py

@@ -0,0 +1,135 @@
+"""Tests for hedging_language_blocker hook response shape."""
+
+import importlib.util
+import json
+import os
+import subprocess
+import sys
+import tempfile
+
+HOOK_SCRIPT_PATH = os.path.join(os.path.dirname(__file__), "hedging_language_blocker.py")
+_HOOKS_DIR = os.path.dirname(HOOK_SCRIPT_PATH)
+_CONFIG_DIR = os.path.join(_HOOKS_DIR, "..", "config")
+if _HOOKS_DIR not in sys.path:
+    sys.path.insert(0, _HOOKS_DIR)
+if _CONFIG_DIR not in sys.path:
+    sys.path.insert(0, _CONFIG_DIR)
+import hedging_language_blocker
+from messages import USER_FACING_NOTICE
+
+RESEARCH_MODE_SKILL_BODY_MARKER = "Three anti-hallucination constraints are ALWAYS active."
+HEDGING_MESSAGE = "This is likely correct."
+CLEAN_MESSAGE = "This is verified by the source document."
+EMPTY_MESSAGE = ""
+
+
+def run_hook_with_message(assistant_message: str) -> subprocess.CompletedProcess:
+    hook_input_payload = json.dumps({"last_assistant_message": assistant_message})
+    return subprocess.run(
+        [sys.executable, HOOK_SCRIPT_PATH],
+        input=hook_input_payload,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+
+def run_hook_with_patched_search_paths(
+    assistant_message: str,
+    search_paths: list[str],
+) -> subprocess.CompletedProcess:
+    """Run the hook with RESEARCH_MODE_SKILL_SEARCH_PATHS overridden via a wrapper script."""
+    wrapper_script = (
+        "import sys, json, os\n"
+        f"sys.path.insert(0, {repr(os.path.dirname(HOOK_SCRIPT_PATH))})\n"
+        "import hedging_language_blocker as blocker\n"
+        f"blocker.RESEARCH_MODE_SKILL_SEARCH_PATHS = {repr(search_paths)}\n"
+        "blocker.main()\n"
+    )
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as wrapper_file:
+        wrapper_file.write(wrapper_script)
+        wrapper_file_path = wrapper_file.name
+
+    hook_input_payload = json.dumps({"last_assistant_message": assistant_message})
+    try:
+        completed_process = subprocess.run(
+            [sys.executable, wrapper_file_path],
+            input=hook_input_payload,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    finally:
+        os.unlink(wrapper_file_path)
+    return completed_process
+
+
+def test_user_facing_notice_importable_from_config_messages():
+    config_messages_path = os.path.join(_CONFIG_DIR, "messages.py")
+    specification = importlib.util.spec_from_file_location("messages", config_messages_path)
+    module = importlib.util.module_from_spec(specification)
+    specification.loader.exec_module(module)
+
+    assert module.USER_FACING_NOTICE == USER_FACING_NOTICE
+
+
+def test_hedging_message_emits_block_with_short_user_notice():
+    completed_process = run_hook_with_message(HEDGING_MESSAGE)
+
+    assert completed_process.returncode == 0
+    parsed_response = json.loads(completed_process.stdout)
+
+    assert parsed_response["decision"] == "block"
+    assert parsed_response["systemMessage"] == USER_FACING_NOTICE
+    assert parsed_response["suppressOutput"] is True
+    assert "likely" in parsed_response["reason"]
+
+
+def test_hedging_reason_contains_not_installed_notice_when_skill_absent():
+    completed_process = run_hook_with_patched_search_paths(
+        HEDGING_MESSAGE,
+        ["/nonexistent/path/one/SKILL.md", "/nonexistent/path/two/SKILL.md"],
+    )
+
+    assert completed_process.returncode == 0
+    parsed_response = json.loads(completed_process.stdout)
+
+    assert parsed_response["decision"] == "block"
+    assert "no research-mode skill installed" in parsed_response["reason"]
+    assert "verify with sources or reply" in parsed_response["reason"]
+    assert "SKILL.md" not in parsed_response["reason"]
+    assert RESEARCH_MODE_SKILL_BODY_MARKER not in parsed_response["reason"]
+
+
+def test_hedging_reason_contains_skill_path_when_skill_present():
+    with tempfile.TemporaryDirectory() as skill_dir:
+        skill_file_path = os.path.join(skill_dir, "SKILL.md")
+        with open(skill_file_path, "w") as skill_file:
+            skill_file.write("# Research Mode Skill\n")
+
+        completed_process = run_hook_with_patched_search_paths(
+            HEDGING_MESSAGE,
+            ["/nonexistent/path/SKILL.md", skill_file_path],
+        )
+
+    assert completed_process.returncode == 0
+    parsed_response = json.loads(completed_process.stdout)
+
+    assert parsed_response["decision"] == "block"
+    assert "SKILL.md" in parsed_response["reason"]
+    assert "no research-mode skill installed" not in parsed_response["reason"]
+    assert RESEARCH_MODE_SKILL_BODY_MARKER not in parsed_response["reason"]
+
+
+def test_clean_message_passes_through_with_no_output():
+    completed_process = run_hook_with_message(CLEAN_MESSAGE)
+
+    assert completed_process.returncode == 0
+    assert completed_process.stdout == ""
+
+
+def test_empty_message_passes_through_with_no_output():
+    completed_process = run_hook_with_message(EMPTY_MESSAGE)
+
+    assert completed_process.returncode == 0
+    assert completed_process.stdout == ""

package/hooks/blocking/test_tdd_enforcer.py

@@ -96,7 +96,7 @@ def test_should_deny_when_test_file_exists_but_is_stale(tmp_path: Path) -> None:
     assert _decision_from(completed) == "deny"
 
 
-def test_should_allow_when_bypass_sentinel_present_in_content(tmp_path: Path) -> None:
+def test_should_deny_when_pragma_no_tdd_gate_sentinel_is_present_without_test(tmp_path: Path) -> None:
     sandbox = _sandbox(tmp_path)
     production_file = sandbox / "orders.py"
     content_with_sentinel = "# pragma: no-tdd-gate\ndef fulfill(): pass\n"
@@ -105,7 +105,7 @@ def test_should_allow_when_bypass_sentinel_present_in_content(tmp_path: Path) ->
         _make_write_payload(production_file, content_with_sentinel)
     )
 
-    assert _decision_from(completed) == "allow"
+    assert _decision_from(completed) == "deny"
 
 
 def test_should_skip_markdown_files_entirely(tmp_path: Path) -> None:
@@ -170,11 +170,12 @@ def test_should_deny_when_test_file_has_no_test_evidence(tmp_path: Path) -> None
     assert _decision_from(completed) == "deny"
 
 
-def test_should_allow_edit_when_bypass_sentinel_present_in_new_string(
+def test_should_deny_edit_when_pragma_sentinel_present_in_new_string_without_test(
     tmp_path: Path,
 ) -> None:
     sandbox = _sandbox(tmp_path)
     production_file = sandbox / "orders.py"
+    production_file.write_text("def fulfill(): pass\n")
     payload = {
         "tool_name": "Edit",
         "tool_input": {
@@ -186,9 +187,131 @@ def test_should_allow_edit_when_bypass_sentinel_present_in_new_string(
 
     completed = _run_hook_with_payload(payload)
 
+    assert _decision_from(completed) == "deny"
+
+
+def test_should_allow_python_file_with_only_module_level_constants(tmp_path: Path) -> None:
+    sandbox = _sandbox(tmp_path)
+    constants_file = sandbox / "constants.py"
+    constants_only_content = (
+        '"""Module-level constants for the widget subsystem."""\n'
+        "import re\n"
+        "MAXIMUM_RETRIES: int = 3\n"
+        "DEFAULT_TIMEOUT_SECONDS: float = 30.0\n"
+        'BANNED_WORDS: tuple[str, ...] = ("foo", "bar")\n'
+    )
+    constants_file.write_text(constants_only_content)
+
+    completed = _run_hook_with_payload(
+        _make_write_payload(constants_file, constants_only_content)
+    )
+
+    assert _decision_from(completed) == "allow"
+
+
+def test_should_deny_python_file_when_any_function_definition_is_present(tmp_path: Path) -> None:
+    sandbox = _sandbox(tmp_path)
+    mixed_file = sandbox / "mixed.py"
+    mixed_content = (
+        "MAXIMUM_RETRIES: int = 3\n"
+        "def do_something() -> None:\n"
+        "    return None\n"
+    )
+    mixed_file.write_text(mixed_content)
+
+    completed = _run_hook_with_payload(
+        _make_write_payload(mixed_file, mixed_content)
+    )
+
+    assert _decision_from(completed) == "deny"
+
+
+def test_should_deny_python_file_when_any_class_definition_is_present(tmp_path: Path) -> None:
+    sandbox = _sandbox(tmp_path)
+    class_file = sandbox / "klass.py"
+    class_content = (
+        "class Widget:\n"
+        "    size: int = 3\n"
+    )
+    class_file.write_text(class_content)
+
+    completed = _run_hook_with_payload(
+        _make_write_payload(class_file, class_content)
+    )
+
+    assert _decision_from(completed) == "deny"
+
+
+def test_deny_response_places_system_message_and_suppress_output_at_top_level(
+    tmp_path: Path,
+) -> None:
+    sandbox = _sandbox(tmp_path)
+    production_file = sandbox / "orders.py"
+    production_file.write_text("def fulfill(): pass\n")
+
+    completed = _run_hook_with_payload(_make_write_payload(production_file))
+
+    parsed = json.loads(completed.stdout)
+    hook_output = parsed["hookSpecificOutput"]
+    assert hook_output["permissionDecision"] == "deny"
+    assert parsed.get("suppressOutput") is True
+    assert isinstance(parsed.get("systemMessage"), str)
+    assert parsed["systemMessage"]
+    assert "suppressOutput" not in hook_output
+    assert "systemMessage" not in hook_output
+    verbose_reason = hook_output["permissionDecisionReason"]
+    assert "propose" in verbose_reason.lower() or "enhancement" in verbose_reason.lower()
+
+
+def test_should_deny_python_file_that_calls_function_at_module_level(tmp_path: Path) -> None:
+    sandbox = _sandbox(tmp_path)
+    side_effect_file = sandbox / "side_effects.py"
+    side_effect_content = (
+        "import sys\n"
+        "sys.exit(1)\n"
+    )
+    side_effect_file.write_text(side_effect_content)
+
+    completed = _run_hook_with_payload(
+        _make_write_payload(side_effect_file, side_effect_content)
+    )
+
+    assert _decision_from(completed) == "deny"
+
+
+def test_should_allow_python_file_with_module_docstring_plus_constants(tmp_path: Path) -> None:
+    sandbox = _sandbox(tmp_path)
+    constants_file = sandbox / "constants.py"
+    constants_content = (
+        '"""Module-level constants for the widget subsystem."""\n'
+        "import re\n"
+        "MAXIMUM_RETRIES: int = 3\n"
+    )
+    constants_file.write_text(constants_content)
+
+    completed = _run_hook_with_payload(
+        _make_write_payload(constants_file, constants_content)
+    )
+
     assert _decision_from(completed) == "allow"
 
 
+def test_should_deny_python_file_that_mutates_module_state_via_aug_assign(tmp_path: Path) -> None:
+    sandbox = _sandbox(tmp_path)
+    mutation_file = sandbox / "mutation.py"
+    mutation_content = (
+        "COUNTER: int = 0\n"
+        "COUNTER += 1\n"
+    )
+    mutation_file.write_text(mutation_content)
+
+    completed = _run_hook_with_payload(
+        _make_write_payload(mutation_file, mutation_content)
+    )
+
+    assert _decision_from(completed) == "deny"
+
+
 def test_should_deny_production_file_inside_directory_containing_skip_substring(
     tmp_path: Path,
 ) -> None:

package/hooks/config/__init__.py

@@ -0,0 +1 @@
+# pragma: no-tdd-gate

package/hooks/config/messages.py

@@ -0,0 +1,4 @@
+"""User-facing notice messages for blocking hooks."""
+
+USER_FACING_NOTICE = "Agent was found guessing - sourcing opinions..."
+USER_FACING_TDD_NOTICE = "TDD gate held - writing the failing test first..."

package/hooks/config/test_messages.py

@@ -0,0 +1,13 @@
+"""Smoke tests for hooks.config.messages — verify user-facing notice constants exist."""
+
+from config import messages
+
+
+def test_user_facing_notice_is_nonempty_string() -> None:
+    assert isinstance(messages.USER_FACING_NOTICE, str)
+    assert messages.USER_FACING_NOTICE
+
+
+def test_user_facing_tdd_notice_is_nonempty_string() -> None:
+    assert isinstance(messages.USER_FACING_TDD_NOTICE, str)
+    assert messages.USER_FACING_TDD_NOTICE