claude-dev-env 1.79.0 → 1.81.0

package/docs/CODE_RULES.md

@@ -23,7 +23,7 @@ Compact reference for agents. ⚡ marks rules enforced by `code_rules_enforcer.p
 
 `code_rules_enforcer.py` blocks each of these at Write/Edit and explains the specific violation when it fires; exact patterns and exemption lists live in the hook:
 
-no new comments · imports at top · logging format args (`log_*("...", arg)`) · no `%s`/`%d` printf tokens in a `str.format`-logger message (`log_*` imported from `automation_logging`; `str.format` drops the args — use `{}`) · no magic values in production bodies (0, 1, -1 exempt) · UPPER_SNAKE constants only in `config/` (exempt: `config/*`, `/migrations/`, workflow registries `/workflow/` + `_tab.py` + `/states.py` + `/modules.py`, test files) · no hardcoded user home paths · guarded `sys.path.insert` · no unused module-level imports · banned identifiers (`ctx`, `cfg`, `msg`, `btn`, `idx`, `cnt`, `tmp`, `elem`, `val`) · banned function prefixes (`handle_`, `process_`, `manage_`, `do_`) · no type escape hatches (`Any` import, `cast()`, inline `Any`, a parameter typed bare `object` whose body reads `param.attribute`) outside boundary files · no bare/broad `except` · no `Any` in signatures or class attributes · no stub bodies (`pass`/`...`/`raise NotImplementedError`) outside abstract/Protocol · TypedDict `_encode_*`/`_decode_*` companions in the same module · no test-mode branching in production (use dependency injection) · no thin wrapper modules · Google-style docstrings on public functions with `Args:` matching the signature · boolean names prefixed `is_`/`has_`/`should_`/`can_`/`was_`/`did_` (assignments AND bool-typed parameters) · must-check returns (`find_and_click`, `write_outcome`) assigned and checked · known pytest fixture parameters in test files annotated with their single documented type (`tmp_path: Path`, `monkeypatch: pytest.MonkeyPatch`, `capsys`, `caplog`, `request`, …) · known pytest fixture parameters a test function declares but never references (drop the unused parameter — pytest still pays its setup cost)
+no new comments · imports at top · logging format args (`log_*("...", arg)`) · no `%s`/`%d` printf tokens in a `str.format`-logger message (`log_*` imported from `automation_logging`; `str.format` drops the args — use `{}`) · no magic values in production bodies (0, 1, -1 exempt) · UPPER_SNAKE constants only in `config/` (exempt: `config/*`, `/migrations/`, workflow registries `/workflow/` + `_tab.py` + `/states.py` + `/modules.py`, test files) · no hardcoded user home paths · guarded `sys.path.insert` · no unused module-level imports · banned identifiers (`ctx`, `cfg`, `msg`, `btn`, `idx`, `cnt`, `tmp`, `elem`, `val`) · banned function prefixes (`handle_`, `process_`, `manage_`, `do_`) · no type escape hatches (`Any` import, `cast()`, inline `Any`, a parameter typed bare `object` whose body reads `param.attribute`) outside boundary files · no bare/broad `except` · no `Any` in signatures or class attributes · no stub bodies (`pass`/`...`/`raise NotImplementedError`) outside abstract/Protocol · TypedDict `_encode_*`/`_decode_*` companions in the same module · no test-mode branching in production (use dependency injection) · no thin wrapper modules · Google-style docstrings on public functions with `Args:` matching the signature · boolean names prefixed `is_`/`has_`/`should_`/`can_`/`was_`/`did_` (assignments AND bool-typed parameters) · must-check returns (`find_and_click`, `write_outcome`) assigned and checked · known pytest fixture parameters in test files annotated with their single documented type (`tmp_path: Path`, `monkeypatch: pytest.MonkeyPatch`, `capsys`, `caplog`, `request`, …) · known pytest fixture parameters a test function declares but never references (drop the unused parameter — pytest still pays its setup cost) · JavaScript/TypeScript boolean declarations (`const`/`let`/`var` bound to a boolean literal or negation) and `@param {boolean}` JSDoc names prefixed `is`/`has`/`should`/`can`/`was`/`did` (camelCase forms) · banned identifiers as `.mjs`/`.js` declaration names (`result`, `data`, `ctx`, `msg`, …), scoped to changed lines · in test files, banned identifiers and unused module-level imports fire on changed lines, and pytest-collectable `test_*` functions need a return annotation · a `hooks/blocking/` command classifier anchors its multi-word command regex to the command start (`^`/`\A`) or tokenizes the first word (`shlex.split`), never matching a command as a bare substring
 
 Test files are exempt from most checks. The one annotation the test-file exemption does NOT cover is a known pytest builtin fixture parameter: `tmp_path`, `monkeypatch`, `capsys`, `capfd`, `caplog`, `request`, and `tmp_path_factory` each have a single documented injected type, so the gate requires that annotation (`tmp_path: Path`) even inside a test file. The same set of fixtures is also subject to a use check: a pytest-collected test function that declares one of these parameters and never references it in its body fails the gate, because pytest materializes the fixture's setup (the temp directory, the monkeypatch context, the output capture) on every run whether or not the body reads the value — drop the unused parameter. A parameter counts as referenced when its name is read, augmented-assigned, or deleted anywhere in the body, including inside a nested function or comprehension. Only pytest-collectable functions are inspected — those at module top level or defined directly in a class body; a function nested inside another function's body is a local helper pytest never collects, so its fixture-named parameter is exempt. A `@pytest.fixture`-decorated function is exempt from the use check, since injecting one fixture into another purely to order its setup is intentional. Ordinary test parameters stay exempt from both checks. See also the file-global constants use-count rule: [`rules/file-global-constants.md`](../rules/file-global-constants.md).
 
@@ -94,4 +94,4 @@ If you already have the data, don't fetch it again.
 
 ## 11. ENFORCEMENT SURFACES
 
-⚡ **Hooks** block pattern-matchable violations at Write/Edit time. 🤖 **Prompt context** carries judgment principles (SRP, Right-Sized Engineering, conservative-action, BDD discovery, docstring-prose-matches-implementation; the `/code` skill prepends strict mode for a session: no `Any`/`cast()`, immutable TypedDicts with `_encode_*`/`_decode_*` + `require_*` validation, per-module `_test_hooks.py` DI, 100% statement + branch coverage, zero mocks). 👥 **Audit rubrics** (`/check`, `packages/claude-dev-env/audit-rubrics/` categories A–P) cover cross-file architectural concerns. Rules with documented-but-pending hook coverage live in `~/.claude/rules/*.md` and `skills/code/SKILL.md`; each names its own promotion path. The docstring-prose standard (free-form enumerations match the body) lives in `packages/claude-dev-env/rules/docstring-prose-matches-implementation.md`, enforced via Category O6 audit.
+⚡ **Hooks** block pattern-matchable violations at Write/Edit time. 🤖 **Prompt context** carries judgment principles (SRP, Right-Sized Engineering, conservative-action, BDD discovery, docstring-prose-matches-implementation; the `/code` skill prepends strict mode for a session: no `Any`/`cast()`, immutable TypedDicts with `_encode_*`/`_decode_*` + `require_*` validation, per-module `_test_hooks.py` DI, 100% statement + branch coverage, zero mocks). 👥 **Audit rubrics** (`/check`, `packages/claude-dev-env/audit-rubrics/` categories A–Q) cover cross-file architectural concerns. Rules with documented-but-pending hook coverage live in `~/.claude/rules/*.md` and `skills/code/SKILL.md`; each names its own promotion path. The docstring-prose standard (free-form enumerations match the body) lives in `packages/claude-dev-env/rules/docstring-prose-matches-implementation.md`, enforced via Category O6 audit.

package/hooks/blocking/CLAUDE.md

@@ -23,6 +23,7 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `code_rules_annotations_length.py` | Parameter/return annotations, function length, pytest fixture annotation requirements |
 | `code_rules_banned_identifiers.py` | Banned short names (`ctx`, `cfg`, `msg`, etc.), banned prefixes (`handle_`, `process_`, etc.) |
 | `code_rules_boolean_mustcheck.py` | Boolean naming (`is_`/`has_`/… prefixes) and must-check return values |
+| `code_rules_command_dispatch.py` | A `hooks/blocking/` command classifier matching a multi-word command regex without a start anchor or first-word tokenization |
 | `code_rules_comments.py` | No new inline comments; no deletion of existing ones |
 | `code_rules_constants_config.py` | Constants must live in `config/`; file-global constant use-count |
 | `code_rules_dead_argparse_argument.py` | Argparse arguments with no references in the same file |
@@ -33,6 +34,7 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `code_rules_docstrings.py` | Google-style docstrings; `Args:` section matches signature; fallback-branch coverage |
 | `code_rules_duplicate_body.py` | A function body copied from a sibling module, or a helper body inlined as a block inside a larger function in the same file |
 | `code_rules_imports_logging.py` | Imports at top of file; logging format-arg style; printf tokens in `str.format`-logger messages |
+| `code_rules_js_conventions.py` | Boolean-prefix naming and banned identifiers for JavaScript/TypeScript declarations and `@param {boolean}` JSDoc, scoped to changed lines |
 | `code_rules_magic_values.py` | No magic numbers or strings in production code bodies |
 | `code_rules_mock_completeness.py` | Mock calls that skip required arguments |
 | `code_rules_naming_collection.py` | Collection names must use `all_*` prefix |

package/hooks/blocking/code_rules_annotations_length.py

@@ -384,24 +384,72 @@ def check_unused_known_pytest_fixture_parameters(
     return issues
 
 
-def check_return_annotations(content: str, file_path: str) -> list[str]:
-    if is_test_file(file_path):
-        return []
+def check_return_annotations(
+    content: str,
+    file_path: str,
+    all_changed_lines: set[int] | None = None,
+    defer_scope_to_caller: bool = False,
+) -> list[str]:
+    """Flag functions missing a return type annotation, scoped to changed lines.
+
+    In a production file every function definition needs a return annotation. In
+    a test file the requirement narrows to pytest-collectable test functions —
+    ``test_*`` at module top level or in a class body — which typically declare
+    ``-> None``; an ordinary helper in a test file stays exempt. Findings scope
+    to *all_changed_lines* so a pre-existing unannotated function on an untouched
+    line never blocks while a newly written one does.
+
+    Args:
+        content: The source text to inspect — the reconstructed full file on an
+            Edit so the parse succeeds.
+        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 the function's definition line is among 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 function missing a return type annotation, scoped to the
+        changed lines unless *defer_scope_to_caller* is True or *all_changed_lines*
+        is None.
+    """
     if is_workflow_registry_file(file_path) or is_migration_file(file_path):
         return []
     try:
         tree = ast.parse(content)
     except SyntaxError:
         return []
-    issues: list[str] = []
-    for each_node in ast.walk(tree):
-        if not isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+    if is_test_file(file_path):
+        candidate_functions: list[ast.FunctionDef | ast.AsyncFunctionDef] = [
+            each_node
+            for each_node in _collect_pytest_collectable_functions(tree)
+            if _is_pytest_test_function(each_node)
+        ]
+    else:
+        candidate_functions = [
+            each_node
+            for each_node in ast.walk(tree)
+            if isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef))
+        ]
+    all_violations_in_source_order: list[tuple[range, str]] = []
+    for each_node in candidate_functions:
+        if each_node.returns is not None:
             continue
-        if each_node.returns is None:
-            issues.append(
-                f"Line {each_node.lineno}: function {each_node.name!r} missing return type annotation (CODE_RULES §6)"
-            )
-    return issues
+        message = (
+            f"Line {each_node.lineno}: function {each_node.name!r} missing "
+            "return type annotation (CODE_RULES §6)"
+        )
+        all_violations_in_source_order.append(
+            (range(each_node.lineno, each_node.lineno + 1), message)
+        )
+    return _scope_violations_to_changed_lines(
+        all_violations_in_source_order,
+        all_changed_lines,
+        defer_scope_to_caller,
+    )
 
 
 def check_function_length(

package/hooks/blocking/code_rules_banned_identifiers.py

@@ -118,9 +118,39 @@ def _collect_banned_names_from_node(node: ast.AST) -> list[ast.Name]:
     return []
 
 
-def check_banned_identifiers(content: str, file_path: str) -> list[str]:
-    """Flag assignments to identifiers banned by the project Naming rules."""
-    if is_test_file(file_path) or is_hook_infrastructure(file_path):
+def check_banned_identifiers(
+    content: str,
+    file_path: str,
+    all_changed_lines: set[int] | None = None,
+    defer_scope_to_caller: bool = False,
+) -> list[str]:
+    """Flag assignments to identifiers banned by the project Naming rules.
+
+    Test files are scoped rather than exempt: a banned identifier a test binds
+    is flagged only when its binding line is among the changed lines, so a
+    pre-existing ``result`` on an untouched line never blocks an edit while a
+    newly written one does. Production files scope the same way, and a new-file
+    or full-file write treats every line as changed. Hook infrastructure stays
+    exempt.
+
+    Args:
+        content: The source text to inspect — the reconstructed full file on an
+            Edit so the parse succeeds and the diff scoping is meaningful.
+        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 binding line is among 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 binding, scoped to the changed lines unless
+        *defer_scope_to_caller* is True or *all_changed_lines* is None. The
+        terminal result is capped at the module limit; the deferred result is
+        uncapped so the gate can scope by added line and apply its own ceiling.
+    """
+    if is_hook_infrastructure(file_path):
         return []
 
     try:
@@ -135,15 +165,24 @@ def check_banned_identifiers(content: str, file_path: str) -> list[str]:
 
     banned_name_nodes.sort(key=lambda each_name: (each_name.lineno, each_name.col_offset))
 
-    issues: list[str] = []
+    all_violations_in_source_order: list[tuple[range, str]] = []
     for each_name in banned_name_nodes:
-        issues.append(
-            f"Line {each_name.lineno}: Banned identifier '{each_name.id}' - {BANNED_IDENTIFIER_MESSAGE_SUFFIX}"
+        message = (
+            f"Line {each_name.lineno}: Banned identifier '{each_name.id}' - "
+            f"{BANNED_IDENTIFIER_MESSAGE_SUFFIX}"
+        )
+        all_violations_in_source_order.append(
+            (range(each_name.lineno, each_name.lineno + 1), message)
         )
-        if len(issues) >= MAX_BANNED_IDENTIFIER_ISSUES:
-            break
 
-    return issues
+    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_BANNED_IDENTIFIER_ISSUES]
 
 
 def _identifier_word_parts(identifier: str) -> list[str]:

package/hooks/blocking/code_rules_command_dispatch.py

@@ -0,0 +1,140 @@
+"""Meta-gate flagging an unanchored multi-word command pattern in a blocker.
+
+A hook that classifies a shell command reads the command text and matches it
+against a regex. When that regex names a multi-word command such as
+``gh\\s+pr\\s+(create|edit)`` and is matched with a bare ``re.search`` — no
+start anchor and no first-word tokenization — the pattern matches the command
+as a substring anywhere in the string. A benign command like
+``echo gh pr create --title x`` then trips the gate. This check flags that shape
+at write time on files under ``hooks/blocking/`` so a new blocker anchors its
+command match to the start of the command or tokenizes the first word.
+"""
+
+import ast
+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_shared import (  # noqa: E402
+    _scope_violations_to_changed_lines,
+    is_test_file,
+)
+
+from hooks_constants.command_dispatch_constants import (  # noqa: E402
+    ALL_REGEX_START_ANCHOR_TOKENS,
+    COMMAND_DISPATCH_LITERAL_PATTERN,
+    COMMAND_DISPATCH_MESSAGE_SUFFIX,
+    COMMAND_DISPATCH_PATH_MARKER,
+    COMMAND_KEY_ACCESS_PATTERN,
+    FIRST_TOKEN_TOKENIZATION_PATTERN,
+    MAX_COMMAND_DISPATCH_ISSUES,
+)
+
+
+def _is_under_hooks_blocking(file_path: str) -> bool:
+    """Return whether the path sits under the ``hooks/blocking`` directory."""
+    return COMMAND_DISPATCH_PATH_MARKER in file_path.replace("\\", "/")
+
+
+def _command_literal_is_anchored(literal_value: str, match_start: int) -> bool:
+    """Return whether a start anchor precedes the command word in the pattern.
+
+    Args:
+        literal_value: The regex string literal the command word appears in.
+        match_start: The index where the command word match begins.
+
+    Returns:
+        True when a ``^`` or ``\\A`` anchor appears before the command word, so
+        the pattern binds the command to the start of the string.
+    """
+    prefix = literal_value[:match_start]
+    return any(each_anchor in prefix for each_anchor in ALL_REGEX_START_ANCHOR_TOKENS)
+
+
+def _unanchored_command_literals(
+    parsed_tree: ast.AST,
+) -> list[tuple[range, str]]:
+    """Return one span-tagged violation per unanchored command-regex literal.
+
+    Args:
+        parsed_tree: The parsed module to scan for string-constant nodes.
+
+    Returns:
+        ``(line_range, message)`` pairs in source order.
+    """
+    all_violations: list[tuple[range, str]] = []
+    for each_node in ast.walk(parsed_tree):
+        if not isinstance(each_node, ast.Constant) or not isinstance(
+            each_node.value, str
+        ):
+            continue
+        literal_match = COMMAND_DISPATCH_LITERAL_PATTERN.search(each_node.value)
+        if literal_match is None:
+            continue
+        if _command_literal_is_anchored(each_node.value, literal_match.start()):
+            continue
+        end_line = each_node.end_lineno or each_node.lineno
+        message = (
+            f"Line {each_node.lineno}: command pattern {each_node.value!r} "
+            f"{COMMAND_DISPATCH_MESSAGE_SUFFIX}"
+        )
+        all_violations.append((range(each_node.lineno, end_line + 1), message))
+    return all_violations
+
+
+def check_unanchored_command_dispatch(
+    content: str,
+    file_path: str,
+    all_changed_lines: set[int] | None = None,
+    defer_scope_to_caller: bool = False,
+) -> list[str]:
+    """Flag an unanchored multi-word command regex in a hooks/blocking file.
+
+    The check fires only on a file under ``hooks/blocking/`` that reads a
+    ``command`` key (a shell-command classifier) and does not tokenize the
+    command's first word (no ``shlex.split`` or ``.split(`` nearby). Under those
+    conditions, a regex string literal naming a known command word followed by
+    ``\\s+`` without a leading ``^``/``\\A`` anchor is flagged. Findings scope to
+    *all_changed_lines* so a pre-existing pattern on an untouched line does not
+    block an edit while a newly written one does.
+
+    Args:
+        content: The source text to inspect — the reconstructed full file on an
+            Edit so the parse succeeds.
+        file_path: The path the source will be written to, used for scoping to
+            ``hooks/blocking`` and skipping test files.
+        all_changed_lines: Post-edit line numbers the current edit touched, or
+            None to treat the whole file as in scope.
+        defer_scope_to_caller: When True, return every violation so a downstream
+            scoper classifies by added line.
+
+    Returns:
+        One issue per unanchored command-regex literal, scoped to the changed
+        lines unless *defer_scope_to_caller* is True or *all_changed_lines* is
+        None, capped at the module limit.
+    """
+    if is_test_file(file_path) or not _is_under_hooks_blocking(file_path):
+        return []
+    if COMMAND_KEY_ACCESS_PATTERN.search(content) is None:
+        return []
+    if FIRST_TOKEN_TOKENIZATION_PATTERN.search(content) is not None:
+        return []
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    all_violations_in_source_order = _unanchored_command_literals(parsed_tree)
+    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_COMMAND_DISPATCH_ISSUES]

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,
@@ -102,11 +106,16 @@ from code_rules_imports_logging import (  # noqa: E402
     check_import_block_sorted,
     check_imports_at_top,
     check_js_resume_task_enumeration_coverage,
+    check_js_returns_object_schemaless_branch,
     check_library_print,
     check_logging_fstrings,
     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,
@@ -283,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,
@@ -367,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)
         )
@@ -427,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,
@@ -465,9 +491,28 @@ 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)
         )
+        all_issues.extend(
+            check_js_returns_object_schemaless_branch(content, file_path)
+        )
 
     if extension in ALL_CODE_EXTENSIONS:
         advise_file_line_count(content, file_path)
@@ -575,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.
@@ -609,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