claude-dev-env 1.72.0 → 1.73.0

package/hooks/blocking/pytest_testpaths_orphan_blocker.py

@@ -0,0 +1,358 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: blocks a test file written outside a package's explicit pytest testpaths allowlist.
+
+A package whose ``pyproject.toml`` declares ``[tool.pytest.ini_options]`` with an
+explicit ``testpaths`` list runs only the directories that list names. A new
+``test_*.py`` written into a directory that no ``testpaths`` entry covers is
+collected by no default ``pytest`` run, so the test silently never executes and a
+regression in the code it guards passes the standard suite undetected. This hook
+fires on Write, Edit, and MultiEdit that create a ``test_*.py`` file, walks up
+from the file to the nearest ``pyproject.toml`` that declares an explicit
+``testpaths`` allowlist, and blocks the write when the file's directory (relative
+to that package root) is covered by no entry. A package whose pyproject declares
+no pytest section, or a pytest section with no explicit ``testpaths`` list, is out
+of scope, since pytest then discovers tests by recursive default and the file is
+collected wherever it lands.
+"""
+
+import fnmatch
+import json
+import sys
+import tomllib
+from pathlib import Path
+from typing import TextIO
+
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
+from hooks_constants.pytest_testpaths_orphan_blocker_constants import (  # noqa: E402
+    ALL_PRUNED_PARENT_DIRECTORY_NAMES,
+    GLOB_METACHARACTERS,
+    MAX_PARENT_DIRECTORIES_SEARCHED,
+    PACKAGE_ROOT_ENTRY,
+    PACKAGE_ROOT_ENTRY_PREFIX,
+    PYPROJECT_FILENAME,
+    TEST_FILE_BASENAME_PATTERN,
+    TESTPATHS_KEY,
+    UNREGISTERED_TEST_DIRECTORY_ADDITIONAL_CONTEXT,
+    UNREGISTERED_TEST_DIRECTORY_MESSAGE_TEMPLATE,
+    UNREGISTERED_TEST_DIRECTORY_SYSTEM_MESSAGE,
+)
+
+
+def is_test_file(file_path: str) -> bool:
+    """Return whether *file_path* names a pytest-collectable ``test_*.py`` file.
+
+    Args:
+        file_path: The destination path of the write or edit.
+
+    Returns:
+        True when the path's basename matches the ``test_*.py`` pattern.
+    """
+    return TEST_FILE_BASENAME_PATTERN.match(Path(file_path).name) is not None
+
+
+class _PytestPackage:
+    """A pyproject.toml that declares an explicit pytest testpaths allowlist.
+
+    Attributes:
+        package_root: The directory holding the pyproject.toml, against which
+            every testpaths entry and the test file's location are resolved.
+        all_testpaths: Each directory the testpaths list names, as written.
+    """
+
+    def __init__(self, package_root: Path, all_testpaths: list[str]) -> None:
+        self.package_root = package_root
+        self.all_testpaths = all_testpaths
+
+
+def _nested_dict_table(parent_table: dict, table_key: str) -> dict | None:
+    """Return the child table at *table_key*, or None when it is absent or a scalar.
+
+    Args:
+        parent_table: The enclosing TOML table to look the key up in.
+        table_key: The key whose value is expected to be a nested table.
+
+    Returns:
+        The nested table, or None when the key is missing or maps to a non-table.
+    """
+    child_table = parent_table.get(table_key, {})
+    if not isinstance(child_table, dict):
+        return None
+    return child_table
+
+
+def _explicit_testpaths(pyproject_path: Path) -> list[str] | None:
+    """Return the explicit testpaths entries a pyproject declares, when it has them.
+
+    The pyproject declares an explicit allowlist only when its
+    ``[tool.pytest.ini_options]`` table holds a ``testpaths`` key whose value is a
+    non-empty list of strings. A pyproject with no pytest table, no ``testpaths``
+    key, or a malformed value yields None, so the caller treats that package as
+    out of scope (pytest then discovers tests by recursive default). A scalar
+    ``tool``, ``pytest``, or ``ini_options`` value also yields None, since the
+    descent through those nested tables stops at the first non-table.
+
+    Args:
+        pyproject_path: The path of the pyproject.toml to read.
+
+    Returns:
+        The list of testpaths entries, or None when the pyproject declares no
+        explicit list or cannot be parsed.
+    """
+    try:
+        parsed_pyproject = tomllib.loads(pyproject_path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, tomllib.TOMLDecodeError):
+        return None
+    tool_table = _nested_dict_table(parsed_pyproject, "tool")
+    pytest_table = _nested_dict_table(tool_table, "pytest") if tool_table is not None else None
+    pytest_section = (
+        _nested_dict_table(pytest_table, "ini_options") if pytest_table is not None else None
+    )
+    if pytest_section is None:
+        return None
+    declared_testpaths = pytest_section.get(TESTPATHS_KEY)
+    if not isinstance(declared_testpaths, list):
+        return None
+    string_entries = [each for each in declared_testpaths if isinstance(each, str) and each]
+    if not string_entries:
+        return None
+    return string_entries
+
+
+def _find_governing_package(test_file: Path) -> _PytestPackage | None:
+    """Return the nearest ancestor package that governs *test_file* with an allowlist.
+
+    Walks upward from the test file's directory, pruning noise directories, until
+    it reaches a ``pyproject.toml`` that declares an explicit ``testpaths`` list.
+    The first such pyproject governs the file. The walk stops at the budget, so a
+    deeply nested file never searches indefinitely.
+
+    Args:
+        test_file: The resolved path of the test file being written.
+
+    Returns:
+        The governing package paired with its testpaths entries, or None when no
+        ancestor declares an explicit allowlist within the budget.
+    """
+    searched_count = 0
+    for each_directory in test_file.parents:
+        if each_directory.name in ALL_PRUNED_PARENT_DIRECTORY_NAMES:
+            continue
+        searched_count += 1
+        if searched_count > MAX_PARENT_DIRECTORIES_SEARCHED:
+            return None
+        candidate_pyproject = each_directory / PYPROJECT_FILENAME
+        if not candidate_pyproject.is_file():
+            continue
+        all_testpaths = _explicit_testpaths(candidate_pyproject)
+        if all_testpaths is None:
+            continue
+        return _PytestPackage(each_directory, all_testpaths)
+    return None
+
+
+def _is_collected_by_entry(relative_test_path: Path, testpaths_entry: str) -> bool:
+    """Return whether one testpaths entry collects the test at *relative_test_path*.
+
+    The entry and the relative path are normalized to forward-slash posix form
+    (a leading ``./`` is stripped) so a Windows backslash path matches a
+    posix-written testpaths entry. An entry that reduces to ``.`` or empty names
+    the package root, which collects every test recursively, so it collects the
+    file. An entry holding a glob metacharacter is matched as an fnmatch pattern
+    against the file's relative path. Otherwise the entry collects the file when
+    it names the file itself or names a directory the file sits inside (the entry
+    is a path prefix of the file's relative path).
+
+    Args:
+        relative_test_path: The test file's path relative to the package root.
+        testpaths_entry: One entry from the package's testpaths list.
+
+    Returns:
+        True when the entry collects the test file.
+    """
+    normalized_test_path = relative_test_path.as_posix()
+    normalized_entry = testpaths_entry.strip().replace("\\", "/")
+    if normalized_entry.startswith(PACKAGE_ROOT_ENTRY_PREFIX):
+        normalized_entry = normalized_entry[len(PACKAGE_ROOT_ENTRY_PREFIX) :]
+    normalized_entry = normalized_entry.strip("/")
+    if normalized_entry in (PACKAGE_ROOT_ENTRY, ""):
+        return True
+    if any(metacharacter in normalized_entry for metacharacter in GLOB_METACHARACTERS):
+        return _matches_glob_entry(normalized_test_path, normalized_entry)
+    if normalized_test_path == normalized_entry:
+        return True
+    return normalized_test_path.startswith(normalized_entry + "/")
+
+
+def _matches_glob_entry(normalized_test_path: str, normalized_entry: str) -> bool:
+    """Return whether a glob testpaths entry collects the file at *normalized_test_path*.
+
+    A glob entry collects the file when the entry matches the file's relative
+    path, or when the entry matches an ancestor directory the file sits inside —
+    so ``tests/*`` (which fnmatch-matches the directory ``tests/data``) collects
+    ``tests/data/test_x.py``.
+
+    Args:
+        normalized_test_path: The test file's posix relative path.
+        normalized_entry: The glob entry, normalized to posix form.
+
+    Returns:
+        True when the entry matches the file or a directory containing it.
+    """
+    if fnmatch.fnmatch(normalized_test_path, normalized_entry):
+        return True
+    ancestor_path = Path(normalized_test_path).parent
+    while ancestor_path != ancestor_path.parent:
+        if fnmatch.fnmatch(ancestor_path.as_posix(), normalized_entry):
+            return True
+        ancestor_path = ancestor_path.parent
+    return False
+
+
+def _suggested_testpaths_entry(relative_test_path: Path) -> str:
+    """Return the testpaths entry that would collect the test file's directory.
+
+    Args:
+        relative_test_path: The test file's path relative to the package root.
+
+    Returns:
+        The posix-form parent directory of the test file, the entry a maintainer
+        would add to the testpaths list to collect it.
+    """
+    return relative_test_path.parent.as_posix()
+
+
+def find_unregistered_test_directory(file_path: str) -> dict[str, str] | None:
+    """Return the block details when a test file lands outside its package's allowlist.
+
+    Resolves the test file, finds the nearest ancestor pyproject that declares an
+    explicit ``testpaths`` allowlist, and checks whether any entry collects the
+    file. When a governing allowlist exists and no entry covers the file's
+    directory, the details name the file, the pyproject, the uncollected
+    directory, and the entry a maintainer would add. A file under no explicit
+    allowlist, or one already covered by an entry, yields None. A filesystem error
+    yields None (fail open), so an unreadable tree never blocks a write.
+
+    Args:
+        file_path: The destination path of the test file being written.
+
+    Returns:
+        A mapping of message fields when the file is unregistered, or None.
+    """
+    test_file = Path(file_path).resolve()
+    governing_package = _find_governing_package(test_file)
+    if governing_package is None:
+        return None
+    try:
+        relative_test_path = test_file.relative_to(governing_package.package_root)
+    except ValueError:
+        return None
+    for each_entry in governing_package.all_testpaths:
+        if _is_collected_by_entry(relative_test_path, each_entry):
+            return None
+    return {
+        "test_file": relative_test_path.as_posix(),
+        "pyproject": (governing_package.package_root / PYPROJECT_FILENAME).as_posix(),
+        "test_directory": relative_test_path.parent.as_posix(),
+        "suggested_entry": _suggested_testpaths_entry(relative_test_path),
+    }
+
+
+def _creates_file(tool_name: str, tool_input: dict, file_path: str) -> bool:
+    """Return whether the tool call creates the test file rather than editing it.
+
+    The check targets a newly created test file: a Write whose target does not yet
+    exist, or any Edit/MultiEdit whose target file is absent (the harness models a
+    create-via-edit as an edit against a missing path). An edit to an existing test
+    file is out of scope, since the file's collection status was settled when it
+    was first created.
+
+    Args:
+        tool_name: The intercepted tool — ``Write``, ``Edit``, or ``MultiEdit``.
+        tool_input: The tool's input payload.
+        file_path: The destination path of the write or edit.
+
+    Returns:
+        True when the call creates a test file that does not yet exist on disk.
+    """
+    if tool_name not in ("Write", "Edit", "MultiEdit"):
+        return False
+    if not isinstance(tool_input, dict):
+        return False
+    return not Path(file_path).exists()
+
+
+def _build_block_payload(block_details: dict[str, str]) -> dict:
+    """Build the PreToolUse deny payload naming the uncollected test directory.
+
+    Args:
+        block_details: The message fields the find step produced.
+
+    Returns:
+        The hook-result dictionary the harness reads to deny the write.
+    """
+    reason = UNREGISTERED_TEST_DIRECTORY_MESSAGE_TEMPLATE.format(**block_details)
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": reason,
+            "additionalContext": UNREGISTERED_TEST_DIRECTORY_ADDITIONAL_CONTEXT,
+        },
+        "systemMessage": UNREGISTERED_TEST_DIRECTORY_SYSTEM_MESSAGE,
+        "suppressOutput": True,
+    }
+
+
+def _emit_hook_result(all_hook_data: dict, output_stream: TextIO) -> None:
+    """Write the hook result JSON to the given output stream.
+
+    Args:
+        all_hook_data: The hook-result dictionary to serialize.
+        output_stream: The stream the harness reads the decision from.
+    """
+    output_stream.write(json.dumps(all_hook_data) + "\n")
+    output_stream.flush()
+
+
+def main() -> None:
+    """Read the PreToolUse payload from stdin and block an unregistered test file."""
+    try:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    if not isinstance(input_data, dict):
+        sys.exit(0)
+
+    tool_name = input_data.get("tool_name", "")
+    if not isinstance(tool_name, str):
+        sys.exit(0)
+
+    tool_input = input_data.get("tool_input", {})
+    if not isinstance(tool_input, dict):
+        sys.exit(0)
+
+    file_path = tool_input.get("file_path", "")
+    if not isinstance(file_path, str) or not is_test_file(file_path):
+        sys.exit(0)
+
+    if not _creates_file(tool_name, tool_input, file_path):
+        sys.exit(0)
+
+    try:
+        block_details = find_unregistered_test_directory(file_path)
+    except OSError:
+        sys.exit(0)
+    if block_details is None:
+        sys.exit(0)
+
+    block_payload = _build_block_payload(block_details)
+    _emit_hook_result(block_payload, sys.stdout)
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/blocking/state_description_blocker.py

@@ -16,6 +16,7 @@ _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.state_description_blocker_constants import (  # noqa: E402
     ALL_BLOCK_COMMENT_EXTENSIONS,
     ALL_BLOCK_COMMENT_ONLY_EXTENSIONS,
@@ -160,57 +161,85 @@ 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.
+    """
+    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 +252,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/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