claude-dev-env 1.79.0 → 1.81.0

package/hooks/blocking/code_rules_imports_logging.py

@@ -1,4 +1,4 @@
-"""Imports-at-top, import-block-sorted, logging f-string, win32gui None, E2E spec naming, JS resume-task enumeration coverage, file-length advisory, and library-print checks."""
+"""Imports-at-top, import-block-sorted, logging f-string, win32gui None, E2E spec naming, JS resume-task enumeration coverage, JS returns-object schema-less branch, file-length advisory, and library-print checks."""
 
 import ast
 import json
@@ -34,6 +34,7 @@ from hooks_constants.blocking_check_limits import (  # noqa: E402
     MAX_E2E_TEST_NAMING_ISSUES,
     MAX_IMPORT_BLOCK_SORT_ISSUES,
     MAX_JS_RESUME_TASK_ENUMERATION_ISSUES,
+    MAX_JS_RETURNS_OBJECT_SCHEMALESS_ISSUES,
     MAX_LOGGING_FSTRING_ISSUES,
     MAX_LOGGING_PRINTF_TOKEN_ISSUES,
     MAX_WINDOWS_API_NONE_ISSUES,
@@ -55,17 +56,21 @@ from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     ENUMERATION_LEADING_CONJUNCTION_PATTERN,
     ENUMERATION_LIST_ITEM_SEPARATOR_PATTERN,
     ENUMERATION_TASK_ITEM_PATTERN,
+    FUNCTION_WITH_JSDOC_PATTERN,
     HYPHENATED_TASK_ITEM_PATTERN,
     JAVASCRIPT_BLOCK_COMMENT_CLOSER,
     JAVASCRIPT_BLOCK_COMMENT_OPENER,
     JAVASCRIPT_LINE_COMMENT_OPENER,
     JAVASCRIPT_REGEX_DELIMITER,
     JAVASCRIPT_STRING_ESCAPE_CHARACTER,
+    JSDOC_RETURNS_STRUCTURED_OBJECT_PROMISE_PATTERN,
     LOGGING_FSTRING_PATTERN,
     LOGGING_PRINTF_TOKEN_PATTERN,
     MINIMUM_FORMAT_LOGGER_ARGUMENT_COUNT,
     NOT_INSIDE_TYPE_CHECKING_BLOCK,
     RESUME_TASK_ENUMERATION_PATTERN,
+    RETURN_CALL_OPENING_PARENTHESIS_PATTERN,
+    SCHEMA_OPTIONS_PROPERTY_KEY_PATTERN,
     SPAWN_AGENT_WITH_JSDOC_PATTERN,
     TASK_DISPATCH_NAME_PATTERN,
     TRIPLE_DOUBLE_QUOTE_DELIMITER,
@@ -919,6 +924,136 @@ def check_js_resume_task_enumeration_coverage(
     return issues[:MAX_JS_RESUME_TASK_ENUMERATION_ISSUES]
 
 
+def _parameter_list_end_index(blanked_content: str, after_open_parenthesis_index: int) -> int:
+    """Return the index just past the ``)`` that closes an opened parameter list.
+
+    ``after_open_parenthesis_index`` sits just past the opening ``(``, so the scan
+    starts one level deep and walks paren-balanced. A nested ``(`` inside the list
+    — a default-value call, a destructure default — does not close the list early.
+    """
+    depth = 1
+    for each_position in range(after_open_parenthesis_index, len(blanked_content)):
+        character = blanked_content[each_position]
+        if character == "(":
+            depth += 1
+        elif character == ")":
+            depth -= 1
+            if depth == 0:
+                return each_position + 1
+    return len(blanked_content)
+
+
+def _javascript_function_body(content: str, header_end_index: int) -> str | None:
+    """Return the brace-balanced body of the function whose header ends at the index.
+
+    ``header_end_index`` sits just past the opening ``(`` of the parameter list, so
+    the scan advances past the paren-balanced parameter list before finding the body
+    brace. A destructured parameter (``function f({ ... }) { ... }``) opens a brace
+    inside that list; the body brace is the first ``{`` after the list closes, not
+    the destructure brace.
+    """
+    body_search_index = _parameter_list_end_index(
+        _blank_non_code_regions(content), header_end_index
+    )
+    bounded_content = content[: _next_top_level_function_index(content, body_search_index)]
+    return _balanced_brace_body(bounded_content, body_search_index)
+
+
+def _balanced_parenthesis_span(blanked_content: str, opening_index: int) -> str:
+    """Return the paren-balanced slice of blanked source starting at an opening ``(``."""
+    depth = 0
+    for each_position in range(opening_index, len(blanked_content)):
+        character = blanked_content[each_position]
+        if character == "(":
+            depth += 1
+        elif character == ")":
+            depth -= 1
+            if depth == 0:
+                return blanked_content[opening_index : each_position + 1]
+    return blanked_content[opening_index:]
+
+
+def _mixed_schema_return_callees(function_body: str) -> set[str]:
+    """Return callees a function returns both with and without a schema options object.
+
+    The body is blanked so a brace or keyword inside a prompt string never counts.
+    Each ``return <callee>(...)`` whose argument list carries an object literal is
+    grouped by whether that argument list also carries a ``schema`` key. A callee
+    that appears on both sides marks a function that returns a schema object in one
+    branch and a schema-less transcript in another.
+    """
+    blanked_body = _blank_non_code_regions(function_body)
+    schema_bearing_callees: set[str] = set()
+    schema_less_callees: set[str] = set()
+    for each_return_match in RETURN_CALL_OPENING_PARENTHESIS_PATTERN.finditer(blanked_body):
+        argument_span = _balanced_parenthesis_span(blanked_body, each_return_match.end() - 1)
+        if "{" not in argument_span:
+            continue
+        callee_name = each_return_match.group("callee")
+        if SCHEMA_OPTIONS_PROPERTY_KEY_PATTERN.search(argument_span) is not None:
+            schema_bearing_callees.add(callee_name)
+        else:
+            schema_less_callees.add(callee_name)
+    return schema_bearing_callees & schema_less_callees
+
+
+def check_js_returns_object_schemaless_branch(content: str, file_path: str) -> list[str]:
+    """Flag a JSDoc @returns Promise<object> whose branch returns a transcript string.
+
+    Picture a dispatcher that spawns an agent and returns whatever the agent
+    resolves to. Most branches pass a ``schema`` in the agent options, so the agent
+    resolves to a structured object — and the JSDoc reads
+    ``@returns {Promise<object>}``. But one branch spawns the same agent with no
+    schema, so that branch resolves to a plain transcript string. A caller who
+    trusts the object contract and reads a field off the result gets undefined on
+    that branch.
+
+    The check reads each ``function`` declaration that carries a JSDoc block. When
+    the JSDoc promises a ``Promise<object>`` and the body returns one agent helper
+    both with a ``schema`` options object and without one, the schema-less branch
+    contradicts the object claim and the function is flagged. A function whose every
+    return passes a schema, one that returns plain object literals, and one whose
+    ``@returns`` already admits a string are all left alone. This is the JS/.mjs
+    slice of Category O6 docstring-prose-vs-implementation drift; the Python
+    enforcer's AST docstring checks never inspect JavaScript source.
+
+    Args:
+        content: The source text to inspect.
+        file_path: The path the source will be written to, used for exemptions.
+
+    Returns:
+        One issue per function whose object return-type claim a schema-less branch
+        contradicts, capped at the module limit.
+    """
+    if is_test_file(file_path) or is_hook_infrastructure(file_path):
+        return []
+    if get_file_extension(file_path) not in ALL_JAVASCRIPT_EXTENSIONS:
+        return []
+    issues: list[str] = []
+    for each_match in FUNCTION_WITH_JSDOC_PATTERN.finditer(content):
+        if JSDOC_RETURNS_STRUCTURED_OBJECT_PROMISE_PATTERN.search(each_match.group("jsdoc")) is None:
+            continue
+        function_body = _javascript_function_body(content, each_match.end())
+        if function_body is None:
+            continue
+        mixed_callees = _mixed_schema_return_callees(function_body)
+        if not mixed_callees:
+            continue
+        function_name = each_match.group("name")
+        line_number = content.count("\n", 0, each_match.start("name")) + 1
+        joined_callees = ", ".join(sorted(mixed_callees))
+        issues.append(
+            f"Line {line_number}: {function_name}() JSDoc @returns a Promise<object> but a "
+            f"branch returns {joined_callees}(...) with a schema-less options object — that "
+            "branch resolves to a transcript string, not the structured object the @returns "
+            "claims; widen the @returns type to admit the string transcript, or pass a schema "
+            "(Category O6 docstring-vs-implementation drift)"
+        )
+        if len(issues) >= MAX_JS_RETURNS_OBJECT_SCHEMALESS_ISSUES:
+            break
+    return issues[:MAX_JS_RETURNS_OBJECT_SCHEMALESS_ISSUES]
+
+
 def _is_cli_entry_point(file_path: str) -> bool:
     path_lower = file_path.lower().replace("\\", "/")
     return any(marker.replace("\\", "/") in path_lower for marker in ALL_CLI_FILE_PATH_MARKERS)

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,14 +19,10 @@ from code_rules_scope_binding import (  # noqa: E402
 from code_rules_shared import (  # noqa: E402
     _build_parent_map,
     is_migration_file,
-    is_test_file,
-    is_workflow_registry_file,
 )
 
 from hooks_constants.unused_module_import_constants import (  # noqa: E402
-    ALL_TYPING_MODULE_NAMES,
     MAX_UNUSED_IMPORT_ISSUES,
-    TYPE_CHECKING_IDENTIFIER,
     UNUSED_IMPORT_GUIDANCE,
     line_suppresses_unused_import_via_noqa,
 )
@@ -73,59 +69,6 @@ def _line_number_falls_in_import_ranges(
     return False
 
 
-def _type_checking_guard_aliases(tree: ast.Module) -> tuple[set[str], set[str]]:
-    all_type_checking_names = {TYPE_CHECKING_IDENTIFIER}
-    all_type_checking_module_aliases = set(ALL_TYPING_MODULE_NAMES)
-    for each_statement in tree.body:
-        if isinstance(each_statement, ast.Import):
-            for each_alias in each_statement.names:
-                if each_alias.name in ALL_TYPING_MODULE_NAMES:
-                    all_type_checking_module_aliases.add(
-                        each_alias.asname or each_alias.name
-                    )
-        elif isinstance(each_statement, ast.ImportFrom):
-            if each_statement.module not in ALL_TYPING_MODULE_NAMES:
-                continue
-            for each_alias in each_statement.names:
-                if each_alias.name == TYPE_CHECKING_IDENTIFIER:
-                    all_type_checking_names.add(each_alias.asname or each_alias.name)
-    return all_type_checking_names, all_type_checking_module_aliases
-
-
-def _expression_guards_type_checking_block(
-    test_expression: ast.expr,
-    all_type_checking_names: set[str],
-    all_type_checking_module_aliases: set[str],
-) -> bool:
-    if isinstance(test_expression, ast.Name):
-        return test_expression.id in all_type_checking_names
-    if isinstance(test_expression, ast.Attribute):
-        if test_expression.attr != TYPE_CHECKING_IDENTIFIER:
-            return False
-        receiver = test_expression.value
-        return (
-            isinstance(receiver, ast.Name)
-            and receiver.id in all_type_checking_module_aliases
-        )
-    return False
-
-
-def _module_body_declares_type_checking_gate(tree: ast.Module) -> bool:
-    (
-        all_type_checking_names,
-        all_type_checking_module_aliases,
-    ) = _type_checking_guard_aliases(tree)
-    return any(
-        isinstance(each_statement, ast.If)
-        and _expression_guards_type_checking_block(
-            each_statement.test,
-            all_type_checking_names,
-            all_type_checking_module_aliases,
-        )
-        for each_statement in tree.body
-    )
-
-
 def _collect_load_names_outside_import_ranges(
     tree: ast.Module,
     all_import_line_ranges: list[tuple[int, int]],
@@ -191,10 +134,12 @@ def check_unused_module_level_imports(
 
     References are detected from AST ``Name`` / ``Attribute`` loads outside import
     statements so mentions in comments or string literals do not count. Files
-    declaring ``__all__`` (including annotated assignments) are skipped. Files
-    whose module body includes ``if TYPE_CHECKING:`` (or
-    ``typing[._extensions].TYPE_CHECKING``) are skipped. Suppression honors bare
-    ``# noqa`` or an explicit ``F401`` code in the noqa list only.
+    declaring ``__all__`` (including annotated assignments) are skipped. A
+    ``if TYPE_CHECKING:`` block does not exempt the file: its guarded imports
+    are nested inside the ``If`` node and are never scanned as top-level
+    bindings, while a dead top-level runtime import in the same file is still
+    flagged. Suppression honors bare ``# noqa`` or an explicit ``F401`` code in
+    the noqa list only.
 
     When ``full_file_content`` is provided, ``content`` is treated as an Edit
     fragment containing the imports being added or replaced, while the
@@ -203,9 +148,7 @@ 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_workflow_registry_file(file_path) or is_migration_file(file_path):
+    if is_migration_file(file_path):
         return []
     try:
         fragment_tree = ast.parse(content)
@@ -218,8 +161,6 @@ def check_unused_module_level_imports(
         return []
     if _module_declares_dunder_all(reference_tree):
         return []
-    if _module_body_declares_type_checking_gate(reference_tree):
-        return []
     fragment_lines = content.splitlines()
     reference_import_ranges = _import_statement_line_ranges(reference_tree)
     referenced_names = _collect_load_names_outside_import_ranges(

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