claude-dev-env 1.80.0 → 1.81.0

package/hooks/blocking/code_rules_docstrings.py

@@ -22,6 +22,7 @@ from code_rules_shared import (  # noqa: E402
 )
 
 from hooks_constants.blocking_check_limits import (  # noqa: E402
+    ALL_ABSENT_TYPE_CHECKING_GATE_DOCSTRING_PHRASES,
     ALL_DATA_SCHEMA_CONSTANT_NAME_MARKERS,
     ALL_DATA_SCHEMA_DOCSTRING_ACKNOWLEDGEMENT_PHRASES,
     ALL_DOCSTRING_EXCLUSIVE_SCOPE_PHRASES,
@@ -74,6 +75,7 @@ from hooks_constants.blocking_check_limits import (  # noqa: E402
     MAX_DOCSTRING_RUNON_SENTENCE_ISSUES,
     MAX_DOCSTRING_STEP_DISPATCH_ISSUES,
     MAX_DOCSTRING_TUPLE_ENUMERATION_ISSUES,
+    MAX_DOCSTRING_TYPE_CHECKING_GATE_ISSUES,
     MAX_DOCSTRING_UNDEFINED_CONSTANT_ISSUES,
     MAX_DOCSTRING_UNGUARDED_PAYLOAD_CLAIM_ISSUES,
     MAX_LENGTH_CONSTANT_SUPERLATIVE_ISSUES,
@@ -90,6 +92,7 @@ from hooks_constants.blocking_check_limits import (  # noqa: E402
     MODULE_DOCSTRING_DATA_SCHEMA_CONSTANT_SAMPLE_LIMIT,
     PYTHON_MODULE_FILE_SUFFIX,
     SINGLE_DICT_KEY_COUNT_FOR_PLURAL_CARDINALITY_DRIFT,
+    TYPE_CHECKING_IDENTIFIER_MARKER,
     WORD_BOUNDARY_REGEX,
     ZIPFILE_ALLOW_ZIP64_KEYWORD,
     ZIPFILE_ALLOW_ZIP64_POSITIONAL_INDEX,
@@ -959,6 +962,96 @@ def check_docstring_no_network_claim_with_metadata_access(
     return issues[:MAX_DOCSTRING_NO_NETWORK_CLAIM_ISSUES]
 
 
+def _module_code_references_type_checking(parsed_tree: ast.Module) -> bool:
+    """Return True when a code identifier in the module handles TYPE_CHECKING.
+
+    A module that names TYPE_CHECKING in code genuinely gates on it. That covers
+    a Name reference (any context — load, store, or delete), an import alias, an
+    attribute access, or a function or class definition whose name carries the
+    type_checking marker. Docstring text is an ast.Constant and never counts, so
+    the check can still flag a gate the prose names while the body performs none.
+    """
+    for each_node in ast.walk(parsed_tree):
+        if isinstance(each_node, ast.Name) and (
+            TYPE_CHECKING_IDENTIFIER_MARKER in each_node.id.lower()
+        ):
+            return True
+        if isinstance(each_node, ast.Attribute) and (
+            TYPE_CHECKING_IDENTIFIER_MARKER in each_node.attr.lower()
+        ):
+            return True
+        if isinstance(each_node, ast.alias) and any(
+            each_alias_name and TYPE_CHECKING_IDENTIFIER_MARKER in each_alias_name.lower()
+            for each_alias_name in (each_node.name, each_node.asname)
+        ):
+            return True
+        if isinstance(
+            each_node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)
+        ) and TYPE_CHECKING_IDENTIFIER_MARKER in each_node.name.lower():
+            return True
+    return False
+
+
+def _docstring_names_absent_type_checking_gate(docstring_text: str) -> str:
+    collapsed_docstring = " ".join(docstring_text.replace("`", " ").lower().split())
+    for each_phrase in ALL_ABSENT_TYPE_CHECKING_GATE_DOCSTRING_PHRASES:
+        if each_phrase in collapsed_docstring:
+            return each_phrase
+    return ""
+
+
+def check_docstring_names_absent_type_checking_gate(
+    content: str, file_path: str
+) -> list[str]:
+    """Flag a docstring naming a TYPE_CHECKING gate the module's code never runs.
+
+    Picture a hook whose docstring advertises a `TYPE_CHECKING` gate-detection
+    step, or a module summary that names `type-checking-gate` helpers, while no
+    identifier in the body handles TYPE_CHECKING. A reader trusts the prose and
+    looks for the gate, but the code performs none, so the claim points at
+    machinery the module does not hold.
+
+    This is the deterministic slice of Category O6 docstring-prose-vs-
+    implementation drift for a TYPE_CHECKING gate claim. The check reads the
+    module docstring and every function and class docstring. It fires only when
+    a docstring names a `TYPE_CHECKING` gate or a `type-checking-gate` helper
+    family while no code identifier in the module carries the `type_checking`
+    marker, so a module that genuinely gates on TYPE_CHECKING is left alone.
+    Hook infrastructure is in scope, since the import-scan hooks that carry this
+    drift class are themselves hooks. Test files are exempt.
+
+    Args:
+        content: The source text to inspect.
+        file_path: The path the source will be written to, used for exemptions.
+
+    Returns:
+        One issue per docstring naming a TYPE_CHECKING gate the code never
+        performs, capped at the module limit.
+    """
+    if is_strict_test_file(file_path):
+        return []
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    if _module_code_references_type_checking(parsed_tree):
+        return []
+    issues: list[str] = []
+    for each_line_number, each_docstring in _documentable_nodes_with_docstrings(parsed_tree):
+        matched_phrase = _docstring_names_absent_type_checking_gate(each_docstring)
+        if not matched_phrase:
+            continue
+        issues.append(
+            f"Line {each_line_number}: docstring names a '{matched_phrase}' the module's "
+            "code never performs — no identifier in the body handles TYPE_CHECKING, so the "
+            "gate-detection claim is stale; drop the TYPE_CHECKING gate wording or add the "
+            "detection (Category O6 docstring-vs-implementation drift)"
+        )
+        if len(issues) >= MAX_DOCSTRING_TYPE_CHECKING_GATE_ISSUES:
+            break
+    return issues[:MAX_DOCSTRING_TYPE_CHECKING_GATE_ISSUES]
+
+
 def _module_docstring_claims_no_inline_literal(module_docstring: str) -> str:
     collapsed_docstring = " ".join(module_docstring.lower().split())
     for each_phrase in ALL_DOCSTRING_NO_INLINE_LITERAL_CLAIM_PHRASES:

package/hooks/blocking/code_rules_enforcer.py

@@ -44,6 +44,9 @@ from code_rules_boolean_mustcheck import (  # noqa: E402
     check_boolean_naming,
     check_ignored_must_check_return,
 )
+from code_rules_command_dispatch import (  # noqa: E402
+    check_unanchored_command_dispatch,
+)
 from code_rules_comments import (  # noqa: E402
     check_comment_changes,
 )
@@ -77,6 +80,7 @@ from code_rules_docstrings import (  # noqa: E402
     check_docstring_field_runmode_outcome,
     check_docstring_format,
     check_docstring_length_constant_superlative_vs_exact_gate,
+    check_docstring_names_absent_type_checking_gate,
     check_docstring_names_undefined_constant,
     check_docstring_no_consumer_claim,
     check_docstring_no_inline_literal_claim,
@@ -108,6 +112,10 @@ from code_rules_imports_logging import (  # noqa: E402
     check_logging_printf_tokens,
     check_windows_api_none,
 )
+from code_rules_js_conventions import (  # noqa: E402
+    check_js_banned_identifiers,
+    check_js_boolean_naming,
+)
 from code_rules_magic_values import (  # noqa: E402
     check_fstring_structural_literals,
     check_magic_values,
@@ -284,7 +292,14 @@ def validate_content(
             )
         )
         all_issues.extend(check_type_escape_hatches(effective_content, file_path))
-        all_issues.extend(check_banned_identifiers(content, file_path))
+        all_issues.extend(
+            check_banned_identifiers(
+                effective_content,
+                file_path,
+                all_changed_lines,
+                defer_scope_to_caller,
+            )
+        )
         all_issues.extend(
             check_banned_noun_word_boundary(
                 effective_content,
@@ -368,6 +383,9 @@ def validate_content(
         all_issues.extend(
             check_docstring_names_undefined_constant(effective_content, file_path)
         )
+        all_issues.extend(
+            check_docstring_names_absent_type_checking_gate(effective_content, file_path)
+        )
         all_issues.extend(
             check_docstring_args_single_line_scope_vs_span(effective_content, file_path)
         )
@@ -428,7 +446,14 @@ def validate_content(
         all_issues.extend(
             check_unused_known_pytest_fixture_parameters(content, file_path)
         )
-        all_issues.extend(check_return_annotations(content, file_path))
+        all_issues.extend(
+            check_return_annotations(
+                effective_content,
+                file_path,
+                all_changed_lines,
+                defer_scope_to_caller,
+            )
+        )
         all_issues.extend(
             check_function_length(
                 effective_content,
@@ -466,6 +491,22 @@ def validate_content(
         if not is_test_file(file_path):
             all_issues.extend(check_comment_changes(old_content, content, file_path))
         all_issues.extend(check_e2e_test_naming(content, file_path))
+        all_issues.extend(
+            check_js_boolean_naming(
+                effective_content,
+                file_path,
+                all_changed_lines,
+                defer_scope_to_caller,
+            )
+        )
+        all_issues.extend(
+            check_js_banned_identifiers(
+                effective_content,
+                file_path,
+                all_changed_lines,
+                defer_scope_to_caller,
+            )
+        )
         all_issues.extend(
             check_js_resume_task_enumeration_coverage(content, file_path)
         )
@@ -579,8 +620,10 @@ def _hook_infrastructure_blocking_issues(
     runs the checks that must still guard them: the cross-file duplicate-body
     check and the same-file inline-duplicate-body check, each span-scoped to the
     lines an edit touched exactly as ``validate_content`` scopes it for production
-    code; and the zero-payload alias check, whose docstring names hook modules as
-    its motivating case, run over the whole post-edit file.
+    code; the zero-payload alias check, whose docstring names hook modules as
+    its motivating case, run over the whole post-edit file; and the
+    unanchored command-dispatch check, which guards a ``hooks/blocking``
+    command classifier against matching a multi-word command as a substring.
 
     Args:
         content: The fragment or whole-file body under validation.
@@ -613,6 +656,13 @@ def _hook_infrastructure_blocking_issues(
         )
     )
     all_issues.extend(check_zero_payload_function_alias(effective_content, file_path))
+    all_issues.extend(
+        check_unanchored_command_dispatch(
+            effective_content,
+            file_path,
+            all_changed_lines,
+        )
+    )
     return all_issues
 
 

package/hooks/blocking/code_rules_js_conventions.py

@@ -0,0 +1,246 @@
+"""Boolean-naming and banned-identifier checks for JavaScript and TypeScript source.
+
+These mirror the Python ``check_boolean_naming`` and ``check_banned_identifiers``
+rules for the ``.mjs`` / ``.js`` family so a JavaScript declaration receives the
+same naming discipline the Python checks apply. Detection is line-regex based
+over a copy of the source whose string, comment, and regex regions are blanked,
+so a boolean assignment inside a prompt string or a comment never fires. The
+``@param {boolean}`` scan reads the raw source instead, because JSDoc lives
+inside a block comment the blanking step removes.
+"""
+
+import sys
+from pathlib import Path
+
+_blocking_directory = str(Path(__file__).resolve().parent)
+_hooks_directory = str(Path(__file__).resolve().parent.parent)
+if _blocking_directory not in sys.path:
+    sys.path.insert(0, _blocking_directory)
+if _hooks_directory not in sys.path:
+    sys.path.insert(0, _hooks_directory)
+
+from code_rules_imports_logging import (  # noqa: E402
+    _blank_non_code_regions,
+)
+from code_rules_shared import (  # noqa: E402
+    _scope_violations_to_changed_lines,
+    get_file_extension,
+    is_hook_infrastructure,
+    is_test_file,
+)
+
+from hooks_constants.banned_identifiers_constants import (  # noqa: E402
+    BANNED_IDENTIFIER_MESSAGE_SUFFIX,
+)
+from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
+    ALL_JAVASCRIPT_EXTENSIONS,
+)
+from hooks_constants.js_conventions_constants import (  # noqa: E402
+    ALL_JAVASCRIPT_BANNED_IDENTIFIERS,
+    BOOLEAN_PREFIX_GUIDANCE,
+    JAVASCRIPT_BOOLEAN_DECLARATION_PATTERN,
+    JAVASCRIPT_BOOLEAN_JSDOC_PARAMETER_PATTERN,
+    JAVASCRIPT_BOOLEAN_PREFIX_PATTERN,
+    JAVASCRIPT_DECLARATION_NAME_PATTERN,
+    MAX_JAVASCRIPT_BANNED_IDENTIFIER_ISSUES,
+    MAX_JAVASCRIPT_BOOLEAN_NAMING_ISSUES,
+    SINGLE_CHARACTER_NAME_LENGTH,
+)
+
+
+def _is_javascript_target(file_path: str) -> bool:
+    """Return whether a check should run on this path.
+
+    Args:
+        file_path: The destination path of the write or edit.
+
+    Returns:
+        True when the path carries a JavaScript extension and is neither a test
+        file nor hook infrastructure; False for every exempt path.
+    """
+    if is_test_file(file_path) or is_hook_infrastructure(file_path):
+        return False
+    return get_file_extension(file_path) in ALL_JAVASCRIPT_EXTENSIONS
+
+
+def _boolean_name_lacks_prefix(name: str) -> bool:
+    """Return whether a boolean name needs a naming prefix it does not carry.
+
+    A single-character name, an all-uppercase constant name, and a name already
+    carrying an ``is``/``has``/``should``/``can``/``was``/``did`` prefix are all
+    accepted.
+
+    Args:
+        name: The declared boolean identifier.
+
+    Returns:
+        True when the name should carry a boolean prefix and does not.
+    """
+    if len(name) <= SINGLE_CHARACTER_NAME_LENGTH:
+        return False
+    if name.isupper():
+        return False
+    return JAVASCRIPT_BOOLEAN_PREFIX_PATTERN.match(name) is None
+
+
+def _boolean_declaration_violations(
+    blanked_content: str,
+) -> list[tuple[range, str]]:
+    """Return one span-tagged violation per unprefixed boolean declaration.
+
+    Args:
+        blanked_content: The source with string, comment, and regex regions
+            replaced by spaces so only structural code is scanned.
+
+    Returns:
+        ``(line_range, message)`` pairs in source order.
+    """
+    all_violations: list[tuple[range, str]] = []
+    for each_line_number, each_line in enumerate(blanked_content.split("\n"), 1):
+        for each_match in JAVASCRIPT_BOOLEAN_DECLARATION_PATTERN.finditer(each_line):
+            name = each_match.group("name")
+            if not _boolean_name_lacks_prefix(name):
+                continue
+            message = (
+                f"Line {each_line_number}: Boolean {name} - {BOOLEAN_PREFIX_GUIDANCE}"
+            )
+            all_violations.append(
+                (range(each_line_number, each_line_number + 1), message)
+            )
+    return all_violations
+
+
+def _boolean_jsdoc_parameter_violations(content: str) -> list[tuple[range, str]]:
+    """Return one span-tagged violation per unprefixed ``@param {boolean}`` name.
+
+    The raw source is scanned rather than the blanked copy because JSDoc lives
+    inside a block comment the blanking step removes.
+
+    Args:
+        content: The raw source text.
+
+    Returns:
+        ``(line_range, message)`` pairs in source order.
+    """
+    all_violations: list[tuple[range, str]] = []
+    for each_line_number, each_line in enumerate(content.split("\n"), 1):
+        for each_match in JAVASCRIPT_BOOLEAN_JSDOC_PARAMETER_PATTERN.finditer(
+            each_line
+        ):
+            name = each_match.group("name")
+            if not _boolean_name_lacks_prefix(name):
+                continue
+            message = (
+                f"Line {each_line_number}: Boolean parameter {name} - "
+                f"{BOOLEAN_PREFIX_GUIDANCE}"
+            )
+            all_violations.append(
+                (range(each_line_number, each_line_number + 1), message)
+            )
+    return all_violations
+
+
+def check_js_boolean_naming(
+    content: str,
+    file_path: str,
+    all_changed_lines: set[int] | None = None,
+    defer_scope_to_caller: bool = False,
+) -> list[str]:
+    """Flag JavaScript boolean declarations and JSDoc params lacking a prefix.
+
+    A ``const``/``let``/``var`` declaration whose right-hand side is a boolean
+    literal, or a negation that is the entire right-hand side (``= !ready;`` or
+    ``= !obj.prop`` or ``= !call(...)``, ending the statement with no ``?``,
+    ``&&``, ``||``, or ``,`` combining the negated operand), and a
+    ``@param {boolean}`` JSDoc entry, all name a boolean. A ``!``-headed side
+    that a ternary or logical operator continues (``!active ? "on" : "off"``,
+    ``!err && getName()``) is an ordinary expression, not a boolean, and is left
+    alone. When the boolean name lacks an ``is``/``has``/``should``/``can``/
+    ``was``/``did`` prefix (camelCase forms such as ``isReady``), the check flags
+    it, so a reader learns a value is a boolean from its name. Findings scope to
+    *all_changed_lines* so an edit blocks on the unprefixed boolean it just
+    introduced while a pre-existing one on an untouched line does not block.
+
+    Args:
+        content: The source text to inspect.
+        file_path: The path the source will be written to, used for exemptions.
+        all_changed_lines: Post-edit line numbers the current edit touched, or
+            None to treat the whole file as in scope. When provided, a violation
+            blocks only when its line intersects the changed lines.
+        defer_scope_to_caller: When True, return every violation so the
+            commit/push gate scopes by added line through its ``Line N:``
+            partitioning.
+
+    Returns:
+        One issue per unprefixed boolean declaration and JSDoc parameter, scoped
+        to the changed lines unless *defer_scope_to_caller* is True or
+        *all_changed_lines* is None, capped at the module limit.
+    """
+    if not _is_javascript_target(file_path):
+        return []
+    blanked_content = _blank_non_code_regions(content)
+    all_violations_in_source_order = _boolean_declaration_violations(blanked_content)
+    all_violations_in_source_order.extend(_boolean_jsdoc_parameter_violations(content))
+    scoped_issues = _scope_violations_to_changed_lines(
+        all_violations_in_source_order,
+        all_changed_lines,
+        defer_scope_to_caller,
+    )
+    if defer_scope_to_caller:
+        return scoped_issues
+    return scoped_issues[:MAX_JAVASCRIPT_BOOLEAN_NAMING_ISSUES]
+
+
+def check_js_banned_identifiers(
+    content: str,
+    file_path: str,
+    all_changed_lines: set[int] | None = None,
+    defer_scope_to_caller: bool = False,
+) -> list[str]:
+    """Flag JavaScript declarations bound to a banned identifier name.
+
+    A ``const``/``let``/``var`` declaration whose name is one of the banned
+    placeholder names (``result``, ``data``, ``response``, ``ctx``, and the rest)
+    is flagged so the author picks a domain-specific name. Findings scope to
+    *all_changed_lines* so a pre-existing ``result`` on an untouched line never
+    blocks while a newly written one does.
+
+    Args:
+        content: The source text to inspect.
+        file_path: The path the source will be written to, used for exemptions.
+        all_changed_lines: Post-edit line numbers the current edit touched, or
+            None to treat the whole file as in scope. When provided, a violation
+            blocks only when its line intersects the changed lines.
+        defer_scope_to_caller: When True, return every violation so the
+            commit/push gate scopes by added line through its ``Line N:``
+            partitioning.
+
+    Returns:
+        One issue per banned declaration name, scoped to the changed lines unless
+        *defer_scope_to_caller* is True or *all_changed_lines* is None, capped at
+        the module limit.
+    """
+    if not _is_javascript_target(file_path):
+        return []
+    blanked_content = _blank_non_code_regions(content)
+    all_violations_in_source_order: list[tuple[range, str]] = []
+    for each_line_number, each_line in enumerate(blanked_content.split("\n"), 1):
+        for each_match in JAVASCRIPT_DECLARATION_NAME_PATTERN.finditer(each_line):
+            name = each_match.group("name")
+            if name not in ALL_JAVASCRIPT_BANNED_IDENTIFIERS:
+                continue
+            message = (
+                f"Line {each_line_number}: Banned identifier '{name}' - "
+                f"{BANNED_IDENTIFIER_MESSAGE_SUFFIX}"
+            )
+            all_violations_in_source_order.append(
+                (range(each_line_number, each_line_number + 1), message)
+            )
+    scoped_issues = _scope_violations_to_changed_lines(
+        all_violations_in_source_order,
+        all_changed_lines,
+        defer_scope_to_caller,
+    )
+    if defer_scope_to_caller:
+        return scoped_issues
+    return scoped_issues[:MAX_JAVASCRIPT_BANNED_IDENTIFIER_ISSUES]

package/hooks/blocking/code_rules_naming_collection.py

@@ -33,6 +33,9 @@ from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     POLARITY_TOKEN_BOUNDARY_PATTERN,
     UPPER_SNAKE_CONSTANT_PATTERN,
 )
+from hooks_constants.blocking_check_limits import (  # noqa: E402
+    MAX_POLARITY_CONTRADICTION_ISSUES,
+)
 from hooks_constants.stuttering_check_config import (  # noqa: E402
     MAX_STUTTERING_PREFIX_ISSUES,
     STUTTERING_ALL_PREFIX_PATTERN,
@@ -336,4 +339,6 @@ def check_polarity_name_contradiction(content: str, file_path: str) -> list[str]
             f" {called_name!r} (says {called_token!r}) - the name contradicts the value; rename the"
             f" callee to a neutral form so each call site reads truthfully (CODE_RULES §5)"
         )
+        if len(issues) >= MAX_POLARITY_CONTRADICTION_ISSUES:
+            break
     return issues

package/hooks/blocking/code_rules_test_assertions.py

@@ -51,6 +51,7 @@ from code_rules_shared import (  # noqa: E402
 
 from hooks_constants.blocking_check_limits import (  # noqa: E402
     MAX_STALE_TEST_NAME_TARGET_ISSUES,
+    MAX_VACUOUS_CLEANUP_ASSERTION_ISSUES,
     STALE_TEST_NAME_MINIMUM_SHARED_TOKEN_COUNT,
 )
 from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
@@ -387,6 +388,8 @@ def check_vacuous_cleanup_assertion_tests(content: str, file_path: str) -> list[
             f" failure (e.g. monkeypatch os.replace to raise after the temp exists)"
             f" then assert the temp was removed"
         )
+        if len(issues) >= MAX_VACUOUS_CLEANUP_ASSERTION_ISSUES:
+            break
 
     return issues
 

package/hooks/blocking/code_rules_unused_imports.py

@@ -19,7 +19,6 @@ from code_rules_scope_binding import (  # noqa: E402
 from code_rules_shared import (  # noqa: E402
     _build_parent_map,
     is_migration_file,
-    is_test_file,
 )
 
 from hooks_constants.unused_module_import_constants import (  # noqa: E402
@@ -149,8 +148,6 @@ def check_unused_module_level_imports(
     Edit applies). This prevents false-positive flags on imports added in the
     same Edit as their consumers.
     """
-    if is_test_file(file_path):
-        return []
     if is_migration_file(file_path):
         return []
     try:

package/hooks/blocking/duplicate_rmtree_helper_blocker.py

@@ -39,6 +39,7 @@ from hooks_constants.duplicate_rmtree_helper_blocker_constants import (  # noqa:
     PYTHON_FILE_EXTENSION,
     TRIPLE_QUOTED_STRING_PATTERN,
 )
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin  # noqa: E402
 
 
@@ -146,6 +147,12 @@ def main() -> None:
             "permissionDecisionReason": corrective_message,
         }
     }
+    log_hook_block(
+        calling_hook_name="duplicate_rmtree_helper_blocker.py",
+        hook_event="PreToolUse",
+        block_reason=corrective_message,
+        tool_name=tool_name,
+    )
     print(json.dumps(deny_response))
     sys.stdout.flush()
     sys.exit(0)

package/hooks/blocking/test_code_rules_command_dispatch.py

@@ -0,0 +1,95 @@
+"""Behavioral tests for the unanchored command-dispatch meta-gate."""
+
+import sys
+from pathlib import Path
+
+_blocking_directory = str(Path(__file__).resolve().parent)
+if _blocking_directory not in sys.path:
+    sys.path.insert(0, _blocking_directory)
+
+from code_rules_command_dispatch import (  # noqa: E402
+    check_unanchored_command_dispatch,
+)
+
+GATE_PATH = "packages/claude-dev-env/hooks/blocking/conventional_pr_title_gate.py"
+
+UNANCHORED_SOURCE = (
+    "import re\n"
+    "def run(tool_input):\n"
+    '    command_text = tool_input["command"]\n'
+    '    if re.search(r"gh\\s+pr\\s+(create|edit)", command_text):\n'
+    "        return True\n"
+    "    return False\n"
+)
+
+
+def test_flags_unanchored_multi_word_command_pattern() -> None:
+    issues = check_unanchored_command_dispatch(UNANCHORED_SOURCE, GATE_PATH)
+    assert len(issues) == 1
+    assert "gh" in issues[0]
+
+
+def test_accepts_anchored_command_pattern() -> None:
+    source = (
+        "import re\n"
+        "def run(tool_input):\n"
+        '    command_text = tool_input["command"]\n'
+        '    if re.search(r"^gh\\s+pr\\s+(create|edit)", command_text):\n'
+        "        return True\n"
+        "    return False\n"
+    )
+    assert check_unanchored_command_dispatch(source, GATE_PATH) == []
+
+
+def test_accepts_pattern_when_first_word_is_tokenized() -> None:
+    source = (
+        "import re\n"
+        "import shlex\n"
+        "def run(tool_input):\n"
+        '    command_text = tool_input["command"]\n'
+        "    first_word = shlex.split(command_text)[0]\n"
+        '    if first_word == "gh" and re.search(r"gh\\s+pr\\s+create", command_text):\n'
+        "        return True\n"
+        "    return False\n"
+    )
+    assert check_unanchored_command_dispatch(source, GATE_PATH) == []
+
+
+def test_ignores_file_that_does_not_read_a_command_key() -> None:
+    source = (
+        "import re\n"
+        "def run(text):\n"
+        '    if re.search(r"gh\\s+pr\\s+create", text):\n'
+        "        return True\n"
+        "    return False\n"
+    )
+    assert check_unanchored_command_dispatch(source, GATE_PATH) == []
+
+
+def test_ignores_single_word_command_literal() -> None:
+    source = (
+        "import re\n"
+        "def run(tool_input):\n"
+        '    command_text = tool_input["command"]\n'
+        '    if re.search(r"gh", command_text):\n'
+        "        return True\n"
+        "    return False\n"
+    )
+    assert check_unanchored_command_dispatch(source, GATE_PATH) == []
+
+
+def test_ignores_file_outside_hooks_blocking() -> None:
+    other_path = "packages/claude-dev-env/skills/thing/helper.py"
+    assert check_unanchored_command_dispatch(UNANCHORED_SOURCE, other_path) == []
+
+
+def test_ignores_test_file() -> None:
+    test_path = "packages/claude-dev-env/hooks/blocking/test_conventional_pr_title_gate.py"
+    assert check_unanchored_command_dispatch(UNANCHORED_SOURCE, test_path) == []
+
+
+def test_scoped_to_changed_lines() -> None:
+    unchanged = check_unanchored_command_dispatch(UNANCHORED_SOURCE, GATE_PATH, {1, 2, 3})
+    assert unchanged == []
+    on_pattern_line = check_unanchored_command_dispatch(UNANCHORED_SOURCE, GATE_PATH, {4})
+    assert len(on_pattern_line) == 1

package/hooks/blocking/test_code_rules_enforcer_annotations.py

@@ -89,10 +89,28 @@ def test_should_flag_async_function_without_return_annotation() -> None:
     )
 
 
-def test_should_skip_return_check_in_test_files() -> None:
+def test_should_skip_return_check_for_test_file_helper() -> None:
     source = "def fetch(url: str):\n    return url\n"
     issues = code_rules_enforcer.check_return_annotations(source, TEST_FILE_PATH)
-    assert issues == [], f"Test files must be exempt, got: {issues}"
+    assert issues == [], f"Non-test helper in a test file must be exempt, got: {issues}"
+
+
+def test_should_flag_test_function_missing_return_annotation() -> None:
+    source = "def test_loads():\n    assert True\n"
+    issues = code_rules_enforcer.check_return_annotations(source, TEST_FILE_PATH)
+    assert any("test_loads" in each_issue for each_issue in issues), (
+        f"Pytest test function must require a return annotation, got: {issues}"
+    )
+
+
+def test_should_scope_test_function_return_annotation_to_changed_lines() -> None:
+    source = "def helper():\n    return 1\n\n\ndef test_uses_it():\n    assert helper()\n"
+    unchanged = code_rules_enforcer.check_return_annotations(source, TEST_FILE_PATH, {2})
+    assert unchanged == []
+    on_definition = code_rules_enforcer.check_return_annotations(
+        source, TEST_FILE_PATH, {5}
+    )
+    assert any("test_uses_it" in each_issue for each_issue in on_definition)
 
 
 def test_should_flag_unannotated_known_fixture_in_test_file() -> None: