claude-dev-env 1.72.0 → 1.74.0

package/hooks/blocking/state_description_blocker.py

@@ -16,6 +16,8 @@ _hooks_dir = str(Path(__file__).resolve().parent.parent)
 if _hooks_dir not in sys.path:
     sys.path.insert(0, _hooks_dir)
 
+from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin  # noqa: E402
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 from hooks_constants.state_description_blocker_constants import (  # noqa: E402
     ALL_BLOCK_COMMENT_EXTENSIONS,
     ALL_BLOCK_COMMENT_ONLY_EXTENSIONS,
@@ -160,57 +162,90 @@ def find_violations(text: str, file_path: str) -> list[str]:
     return all_detected
 
 
-def main() -> None:
-    try:
-        input_data = json.load(sys.stdin)
-    except json.JSONDecodeError:
-        sys.exit(0)
+def _build_deny_reason(file_path: str, all_detected_patterns: list[str]) -> str:
+    """Build the permissionDecisionReason text for a historical-language denial.
 
-    if not isinstance(input_data, dict):
-        sys.exit(0)
+    Args:
+        file_path: The target file path the violation was found in.
+        all_detected_patterns: The matched historical/comparative phrases.
 
-    tool_name = input_data.get("tool_name", "")
-    if not isinstance(tool_name, str):
-        sys.exit(0)
+    Returns:
+        The deny-reason text naming the file and the detected phrases.
+    """
+    formatted = ", ".join(f'"{each_pattern}"' for each_pattern in all_detected_patterns)
+    return (
+        f"Historical/comparative language detected in {file_path}: "
+        f"{formatted}. Describe current state only — no 'instead of', "
+        f"'previously', 'now uses', etc. The git log tracks what changed. "
+        f"Comments and docs describe what IS."
+    )
 
-    tool_input = input_data.get("tool_input", {})
-    if not isinstance(tool_input, dict):
-        sys.exit(0)
 
-    if tool_name not in ("Write", "Edit"):
-        sys.exit(0)
+def evaluate(payload_by_key: dict[str, object]) -> str | None:
+    """Decide whether a Write/Edit payload carries historical/comparative language.
 
-    file_path = tool_input.get("file_path", "")
-    if not file_path or not (
-        is_markdown_file(file_path) or is_comment_bearing_file(file_path)
-    ):
-        sys.exit(0)
+    Applies the same tool-name gate, file-extension gate, content selection, and
+    pattern scan the standalone hook applies. Returns the deny-reason text when a
+    historical phrase is found, or None to allow.
 
-    content_to_check = ""
-    if tool_name == "Write":
-        content_to_check = tool_input.get("content", "")
-    elif tool_name == "Edit":
-        content_to_check = tool_input.get("new_string", "")
+    Args:
+        payload_by_key: The PreToolUse payload with tool_name and tool_input.
 
+    Returns:
+        The permissionDecisionReason text when the write is denied, or None when
+        the write is allowed.
+    """
+    raw_tool_name = payload_by_key.get("tool_name", "")
+    tool_name = raw_tool_name if isinstance(raw_tool_name, str) else ""
+    if tool_name not in ("Write", "Edit"):
+        return None
+
+    raw_tool_input = payload_by_key.get("tool_input", {})
+    tool_input = raw_tool_input if isinstance(raw_tool_input, dict) else {}
+
+    file_path = tool_input.get("file_path", "")
+    if not isinstance(file_path, str) or not file_path:
+        return None
+    if not (is_markdown_file(file_path) or is_comment_bearing_file(file_path)):
+        return None
+
+    content_key = "content" if tool_name == "Write" else "new_string"
+    raw_content = tool_input.get(content_key, "")
+    content_to_check = raw_content if isinstance(raw_content, str) else ""
     if not content_to_check:
-        sys.exit(0)
+        return None
 
     all_detected_patterns = find_violations(content_to_check, file_path)
     if not all_detected_patterns:
-        sys.exit(0)
+        return None
+
+    return _build_deny_reason(file_path, all_detected_patterns)
+
 
-    formatted = ", ".join(f'"{p}"' for p in all_detected_patterns)
+def build_deny_payload(deny_reason: str) -> dict[str, object]:
+    """Build the full deny payload the hook writes for a deny-reason string.
 
-    block_payload = {
+    The payload carries the core permission decision plus the BAD/GOOD rewrite
+    guidance in additionalContext, the user-facing systemMessage, and output
+    suppression, so a caller routing this hook through a dispatcher reproduces
+    the same deny shape the standalone hook writes.
+
+    Args:
+        deny_reason: The permissionDecisionReason text for the denial.
+
+    Returns:
+        The deny payload dictionary the hook serializes to stdout.
+    """
+    log_hook_block(
+        calling_hook_name="state_description_blocker.py",
+        hook_event="PreToolUse",
+        block_reason=deny_reason,
+    )
+    return {
         "hookSpecificOutput": {
             "hookEventName": "PreToolUse",
             "permissionDecision": "deny",
-            "permissionDecisionReason": (
-                f"Historical/comparative language detected in {file_path}: "
-                f"{formatted}. Describe current state only — no 'instead of', "
-                f"'previously', 'now uses', etc. The git log tracks what changed. "
-                f"Comments and docs describe what IS."
-            ),
+            "permissionDecisionReason": deny_reason,
             "additionalContext": (
                 "Rewrite the affected comments or documentation to describe "
                 "only the current state. For example:\n"
@@ -223,7 +258,17 @@ def main() -> None:
         "suppressOutput": True,
     }
 
-    _emit_hook_result(block_payload, sys.stdout)
+
+def main() -> None:
+    payload_dictionary = read_hook_input_dictionary_from_stdin()
+    if payload_dictionary is None:
+        sys.exit(0)
+
+    deny_reason = evaluate(payload_dictionary)
+    if deny_reason is None:
+        sys.exit(0)
+
+    _emit_hook_result(build_deny_payload(deny_reason), sys.stdout)
     sys.exit(0)
 
 

package/hooks/blocking/subprocess_budget_completeness.py

@@ -44,6 +44,7 @@ if _hooks_dir not in sys.path:
 
 from code_rules_shared import is_test_file  # noqa: E402
 
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 from hooks_constants.pre_tool_use_stdin import (  # noqa: E402
     read_hook_input_dictionary_from_stdin,
 )
@@ -360,15 +361,20 @@ def main() -> None:
         sys.exit(0)
 
     function_name, omitted_values = undercounted_budget
+    deny_reason = format_block_message(file_path, function_name, omitted_values)
+    log_hook_block(
+        calling_hook_name="subprocess_budget_completeness.py",
+        hook_event="PreToolUse",
+        block_reason=deny_reason,
+        offending_input_preview=file_path,
+    )
     print(
         json.dumps(
             {
                 "hookSpecificOutput": {
                     "hookEventName": "PreToolUse",
                     "permissionDecision": "deny",
-                    "permissionDecisionReason": format_block_message(
-                        file_path, function_name, omitted_values
-                    ),
+                    "permissionDecisionReason": deny_reason,
                 }
             }
         )

package/hooks/blocking/tdd_enforcer.py

@@ -24,6 +24,7 @@ if _blocking_directory_path_string not in sys.path:
 
 from code_rules_shared import is_ephemeral_script_path  # noqa: E402
 
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 from hooks_constants.messages import USER_FACING_TDD_NOTICE  # noqa: E402
 
 PRODUCTION_EXTENSIONS = {'.py', '.ts', '.tsx', '.js', '.jsx'}
@@ -538,6 +539,11 @@ def emit_deny(reason: str) -> None:
         "suppressOutput": True,
         "systemMessage": USER_FACING_TDD_NOTICE,
     }
+    log_hook_block(
+        calling_hook_name="tdd_enforcer.py",
+        hook_event="PreToolUse",
+        block_reason=reason,
+    )
     print(json.dumps(deny_payload))
 
 

package/hooks/blocking/test_code_rules_enforcer_dead_config_field.py

@@ -749,6 +749,87 @@ def test_dead_config_field_module_has_no_collection_parameter_naming_violation()
     )
 
 
+SELECTORS_DATACLASS_BODY = (
+    "from dataclasses import dataclass\n"
+    "\n"
+    "@dataclass(frozen=True)\n"
+    "class BinarySelectors:\n"
+    "    show_more_button_active: str = \"a.show_list_btn.active\"\n"
+    "    show_more_row_visible: str = \"tr.show_list_tr:not(.ng-hide)\"\n"
+    "\n"
+    "binary_selectors: BinarySelectors = BinarySelectors()\n"
+)
+
+
+def test_flags_selectors_dataclass_field_read_by_no_production_module(
+    neutral_root: Path,
+) -> None:
+    """A ``*Selectors`` @dataclass field read by no production module is flagged.
+
+    A selectors dataclass is a config-like export surface: defined once, bound to
+    a module-level singleton (``binary_selectors = BinarySelectors()``), and read
+    across files. The cross-module dead-field scan treats it the same as a
+    ``*Config`` dataclass, so a selector field no production module reads —
+    ``show_more_row_visible`` here — is flagged, while a selector a consumer reads
+    (``show_more_button_active``) is not.
+    """
+    consumer_body = (
+        "from selectors_module import binary_selectors\n"
+        "\n"
+        "def expand() -> str:\n"
+        "    return binary_selectors.show_more_button_active\n"
+    )
+    workflow_directory = neutral_root / "workflow"
+    selectors_package = workflow_directory / "selectors"
+    selectors_package.mkdir(parents=True)
+    (selectors_package / "__init__.py").write_text("", encoding="utf-8")
+    selectors_path = selectors_package / "selectors_module.py"
+    selectors_path.write_text(SELECTORS_DATACLASS_BODY, encoding="utf-8")
+    (workflow_directory / "processor.py").write_text(consumer_body, encoding="utf-8")
+    issues = _check(SELECTORS_DATACLASS_BODY, str(selectors_path))
+    assert any("'show_more_row_visible'" in each_issue for each_issue in issues), (
+        f"Selector field read by no production module must be flagged, got: {issues}"
+    )
+    assert not any(
+        "'show_more_button_active'" in each_issue for each_issue in issues
+    ), f"Selector field read in the consumer must not be flagged, got: {issues}"
+    selector_issue = next(
+        each_issue for each_issue in issues if "'show_more_row_visible'" in each_issue
+    )
+    assert "config dataclass field" not in selector_issue, (
+        f"Flagged selectors field must not be mislabelled a config dataclass field, got: {selector_issue}"
+    )
+
+
+def test_does_not_flag_selectors_field_read_in_sibling_module(
+    neutral_root: Path,
+) -> None:
+    """A ``*Selectors`` field read through the singleton in a sibling module is live.
+
+    When every selector field is read by a production consumer, none is flagged.
+    """
+    consumer_body = (
+        "from selectors_module import binary_selectors\n"
+        "\n"
+        "def expand() -> tuple[str, str]:\n"
+        "    return (\n"
+        "        binary_selectors.show_more_button_active,\n"
+        "        binary_selectors.show_more_row_visible,\n"
+        "    )\n"
+    )
+    workflow_directory = neutral_root / "workflow"
+    selectors_package = workflow_directory / "selectors"
+    selectors_package.mkdir(parents=True)
+    (selectors_package / "__init__.py").write_text("", encoding="utf-8")
+    selectors_path = selectors_package / "selectors_module.py"
+    selectors_path.write_text(SELECTORS_DATACLASS_BODY, encoding="utf-8")
+    (workflow_directory / "processor.py").write_text(consumer_body, encoding="utf-8")
+    issues = _check(SELECTORS_DATACLASS_BODY, str(selectors_path))
+    assert issues == [], (
+        f"All selector fields are read in the consumer, none must be flagged, got: {issues}"
+    )
+
+
 def test_validate_content_dispatch_runs_dead_config_field_check(neutral_root: Path) -> None:
     workflow_directory = neutral_root / "workflow"
     config_package = workflow_directory / "os_update_workflow"

package/hooks/blocking/test_code_rules_enforcer_docstring_inline_literal_claim.py

@@ -0,0 +1,93 @@
+"""Tests for check_docstring_no_inline_literal_claim — Category O6 completeness drift.
+
+A constants-module docstring asserting "no literals appear inline in the
+dispatcher" makes an unverifiable completeness claim about a companion file. The
+claim drifts the moment a literal lands inline in that companion — a deny or
+block reason left inline contradicts the docstring even though the file under
+edit never changed. This is the deterministic slice of Category O6 (docstring
+prose vs implementation drift) and a no-transitional-language violation in its
+own right.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+from types import ModuleType
+
+
+def _load_enforcer_module() -> ModuleType:
+    module_path = Path(__file__).parent / "code_rules_enforcer.py"
+    spec = importlib.util.spec_from_file_location("code_rules_enforcer", module_path)
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+code_rules_enforcer = _load_enforcer_module()
+
+
+def check_docstring_no_inline_literal_claim(content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_docstring_no_inline_literal_claim(content, file_path)
+
+
+CONSTANTS_FILE_PATH = "/project/hooks/hooks_constants/example_dispatcher_constants.py"
+TEST_FILE_PATH = "/project/hooks/hooks_constants/test_example_dispatcher_constants.py"
+
+
+def test_flags_no_literals_appear_inline_in_the_dispatcher_claim() -> None:
+    content = (
+        '"""Constants for the dispatcher.\n'
+        "\n"
+        "The dispatcher imports these; no literals appear inline in the dispatcher\n"
+        "script.\n"
+        '"""\n'
+        "\n"
+        'DENY_DECISION = "deny"\n'
+    )
+    issues = check_docstring_no_inline_literal_claim(content, CONSTANTS_FILE_PATH)
+    assert len(issues) == 1
+    assert "no literals appear inline" in issues[0]
+
+
+def test_flags_no_literals_appear_inline_short_form() -> None:
+    content = (
+        '"""Constants module. No literals appear inline in the script."""\n'
+        "\n"
+        'BLOCK_DECISION = "block"\n'
+    )
+    assert len(check_docstring_no_inline_literal_claim(content, CONSTANTS_FILE_PATH)) == 1
+
+
+def test_passes_when_docstring_states_what_is_centralized() -> None:
+    content = (
+        '"""Constants for the dispatcher.\n'
+        "\n"
+        "Holds the deny decision string and the crash deny reason. The dispatcher\n"
+        "imports each of these by name.\n"
+        '"""\n'
+        "\n"
+        'DENY_DECISION = "deny"\n'
+    )
+    assert check_docstring_no_inline_literal_claim(content, CONSTANTS_FILE_PATH) == []
+
+
+def test_test_files_are_exempt() -> None:
+    content = (
+        '"""Constants module. No literals appear inline in the dispatcher script."""\n'
+        "\n"
+        'DENY_DECISION = "deny"\n'
+    )
+    assert check_docstring_no_inline_literal_claim(content, TEST_FILE_PATH) == []
+
+
+def test_hook_infrastructure_is_in_scope() -> None:
+    hook_constants_path = "/home/user/.claude/hooks/hooks_constants/foo_constants.py"
+    content = (
+        '"""Constants module. No literals appear inline in the dispatcher script."""\n'
+        "\n"
+        'DENY_DECISION = "deny"\n'
+    )
+    assert len(check_docstring_no_inline_literal_claim(content, hook_constants_path)) == 1

package/hooks/blocking/test_code_rules_enforcer_docstring_returns_plural_cardinality.py

@@ -0,0 +1,207 @@
+"""Tests for check_docstring_returns_plural_cardinality — O6 plural-stop drift.
+
+A function returns a dict literal whose keys carry prefix families, and its
+Returns clause names one such family with a plural noun ("the sheen stops")
+while only one key in that family exists ("sheen_mid"). The plural prose claims
+two or more entries the dict no longer holds. This is the deterministic
+single-key slice of Category O6 docstring-prose-vs-implementation drift, the
+shape that appears when a producer removes the second key in a family but leaves
+the plural prose untouched.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+from types import ModuleType
+
+
+def _load_enforcer_module() -> ModuleType:
+    module_path = Path(__file__).parent / "code_rules_enforcer.py"
+    spec = importlib.util.spec_from_file_location("code_rules_enforcer", module_path)
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+code_rules_enforcer = _load_enforcer_module()
+
+
+def check_docstring_returns_plural_cardinality(content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_docstring_returns_plural_cardinality(content, file_path)
+
+
+def validate_content(content: str, file_path: str, old_content: str) -> list[str]:
+    return code_rules_enforcer.validate_content(content, file_path, old_content)
+
+
+PRODUCTION_FILE_PATH = "/project/src/phone_handset.py"
+TEST_FILE_PATH = "/project/src/test_phone_handset.py"
+HOOK_INFRASTRUCTURE_PATH = "/home/user/.claude/hooks/blocking/example.py"
+
+
+def _drifted_single_sheen_function() -> str:
+    return (
+        "def _palette_substitutions(colors: PhoneHandsetColors) -> dict[str, str]:\n"
+        '    """Derive every SVG color field from the three theme hero colors.\n'
+        "\n"
+        "    Returns:\n"
+        "        The color substitution fields the SVG template fills: the body form\n"
+        "        stops (highlight, mid, shadow, inner-shadow), the sheen stops, the rim\n"
+        "        highlight, the depth, and the specular core that lights the gloss.\n"
+        '    """\n'
+        "    return {\n"
+        '        "body_highlight": derive_highlight(colors.body),\n'
+        '        "body_mid": colors.body,\n'
+        '        "body_shadow": derive_shadow(colors.body),\n'
+        '        "body_inner_shadow": derive_inner(colors.body),\n'
+        '        "sheen_mid": colors.sheen,\n'
+        '        "rim_highlight": derive_rim(colors.sheen),\n'
+        '        "specular_core": derive_specular(colors.sheen),\n'
+        '        "depth_mid": colors.depth,\n'
+        "    }\n"
+    )
+
+
+def _singular_sheen_function() -> str:
+    return (
+        "def _palette_substitutions(colors: PhoneHandsetColors) -> dict[str, str]:\n"
+        '    """Derive every SVG color field from the three theme hero colors.\n'
+        "\n"
+        "    Returns:\n"
+        "        The color substitution fields the SVG template fills: the body form\n"
+        "        stops (highlight, mid, shadow, inner-shadow), the sheen stop, the rim\n"
+        "        highlight, the depth, and the specular core that lights the gloss.\n"
+        '    """\n'
+        "    return {\n"
+        '        "body_highlight": derive_highlight(colors.body),\n'
+        '        "body_mid": colors.body,\n'
+        '        "body_shadow": derive_shadow(colors.body),\n'
+        '        "body_inner_shadow": derive_inner(colors.body),\n'
+        '        "sheen_mid": colors.sheen,\n'
+        '        "rim_highlight": derive_rim(colors.sheen),\n'
+        '        "specular_core": derive_specular(colors.sheen),\n'
+        '        "depth_mid": colors.depth,\n'
+        "    }\n"
+    )
+
+
+def _plural_family_with_two_keys_function() -> str:
+    return (
+        "def _palette_substitutions(colors: PhoneHandsetColors) -> dict[str, str]:\n"
+        '    """Derive every SVG color field from the three theme hero colors.\n'
+        "\n"
+        "    Returns:\n"
+        "        The color substitution fields the SVG template fills: the body form\n"
+        "        stops (highlight, mid, shadow, inner-shadow), the sheen stops, the rim\n"
+        "        highlight, the depth, and the specular core that lights the gloss.\n"
+        '    """\n'
+        "    return {\n"
+        '        "body_highlight": derive_highlight(colors.body),\n'
+        '        "body_mid": colors.body,\n'
+        '        "sheen_highlight": derive_sheen_highlight(colors.sheen),\n'
+        '        "sheen_mid": colors.sheen,\n'
+        '        "rim_highlight": derive_rim(colors.sheen),\n'
+        '        "specular_core": derive_specular(colors.sheen),\n'
+        "    }\n"
+    )
+
+
+def test_should_flag_plural_stops_with_single_family_key() -> None:
+    issues = check_docstring_returns_plural_cardinality(
+        _drifted_single_sheen_function(), PRODUCTION_FILE_PATH
+    )
+    assert any("sheen" in each for each in issues), (
+        f"The plural 'sheen stops' against a single sheen_mid key must be flagged, got: {issues!r}"
+    )
+
+
+def test_should_report_category_o6_in_the_message() -> None:
+    issues = check_docstring_returns_plural_cardinality(
+        _drifted_single_sheen_function(), PRODUCTION_FILE_PATH
+    )
+    assert any("O6" in each for each in issues), (
+        f"Expected the Category O6 label in the message, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_singular_noun() -> None:
+    issues = check_docstring_returns_plural_cardinality(
+        _singular_sheen_function(), PRODUCTION_FILE_PATH
+    )
+    assert issues == [], (
+        f"A singular 'sheen stop' matching one key must not be flagged, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_plural_family_with_two_keys() -> None:
+    issues = check_docstring_returns_plural_cardinality(
+        _plural_family_with_two_keys_function(), PRODUCTION_FILE_PATH
+    )
+    assert issues == [], (
+        f"A plural 'sheen stops' matching two sheen_ keys must not be flagged, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_family_absent_from_dict() -> None:
+    source = (
+        "def build() -> dict[str, str]:\n"
+        '    """Build the fields.\n'
+        "\n"
+        "    Returns:\n"
+        "        The body stops and the sheen stops the template fills.\n"
+        '    """\n'
+        "    return {\n"
+        '        "body_mid": "a",\n'
+        '        "rim_highlight": "b",\n'
+        "    }\n"
+    )
+    issues = check_docstring_returns_plural_cardinality(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"A plural family with no matching dict keys must not be flagged, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_when_no_returns_section() -> None:
+    source = (
+        "def build() -> dict[str, str]:\n"
+        '    """Build the sheen stops without a Returns section."""\n'
+        "    return {\n"
+        '        "sheen_mid": "a",\n'
+        "    }\n"
+    )
+    issues = check_docstring_returns_plural_cardinality(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"A plural noun outside a Returns section must not be flagged, got: {issues!r}"
+    )
+
+
+def test_should_skip_test_file() -> None:
+    issues = check_docstring_returns_plural_cardinality(
+        _drifted_single_sheen_function(), TEST_FILE_PATH
+    )
+    assert issues == [], f"Test files exempt, got: {issues!r}"
+
+
+def test_should_skip_hook_infrastructure() -> None:
+    issues = check_docstring_returns_plural_cardinality(
+        _drifted_single_sheen_function(), HOOK_INFRASTRUCTURE_PATH
+    )
+    assert issues == [], f"Hook infrastructure exempt, got: {issues!r}"
+
+
+def test_should_handle_syntax_error_gracefully() -> None:
+    issues = check_docstring_returns_plural_cardinality("def fetch(\n", PRODUCTION_FILE_PATH)
+    assert issues == [], f"Syntax error must yield no issues, got: {issues!r}"
+
+
+def test_validate_content_surfaces_plural_cardinality_drift() -> None:
+    issues = validate_content(
+        _drifted_single_sheen_function(), PRODUCTION_FILE_PATH, old_content=""
+    )
+    matching_issues = [each for each in issues if "sheen" in each and "O6" in each]
+    assert matching_issues, (
+        f"Expected validate_content to surface the O6 plural-cardinality drift, got: {issues!r}"
+    )