claude-dev-env 1.80.0 → 1.81.0

package/hooks/blocking/test_code_rules_enforcer_banned_identifier.py

@@ -95,10 +95,18 @@ def test_should_not_flag_name_containing_banned_substring() -> None:
     assert issues == []
 
 
-def test_should_skip_test_files() -> None:
+def test_should_scope_test_file_banned_identifier_to_changed_lines() -> None:
+    content = "def test_thing():\n    result = compute()\n    assert result\n"
+    unchanged_only = check_banned_identifiers(content, TEST_FILE_PATH, {1, 3})
+    assert unchanged_only == []
+    on_changed_line = check_banned_identifiers(content, TEST_FILE_PATH, {2})
+    assert any("result" in each_issue for each_issue in on_changed_line)
+
+
+def test_should_flag_newly_written_test_file_banned_identifier() -> None:
     content = "def test_thing():\n    result = compute()\n    assert result\n"
     issues = check_banned_identifiers(content, TEST_FILE_PATH)
-    assert issues == []
+    assert any("'result'" in each_issue for each_issue in issues)
 
 
 def test_should_skip_hook_infrastructure() -> None:

package/hooks/blocking/test_code_rules_enforcer_banned_import_alias.py

@@ -117,11 +117,15 @@ def test_should_flag_btn_assignment() -> None:
     )
 
 
-def test_should_not_flag_import_alias_in_test_file() -> None:
+def test_should_scope_import_alias_in_test_file_to_changed_lines() -> None:
     content = "from config import rebase_constants as rc\n"
-    issues = check_banned_identifiers(content, TEST_FILE_PATH)
-    assert issues == [], (
-        f"Test files are exempt from banned-identifier checks, got: {issues}"
+    unchanged_only = check_banned_identifiers(content, TEST_FILE_PATH, {2})
+    assert unchanged_only == [], (
+        f"A banned alias on an untouched line must not block, got: {unchanged_only}"
+    )
+    on_changed_line = check_banned_identifiers(content, TEST_FILE_PATH, {1})
+    assert any("'rc'" in each_issue for each_issue in on_changed_line), (
+        f"A newly written banned alias in a test file must flag, got: {on_changed_line}"
     )
 
 

package/hooks/blocking/test_code_rules_enforcer_dispatch_wiring.py

@@ -10,8 +10,12 @@ orphan CSS class slip past the gate again.
 This module reads ``validate_content``'s source and asserts every ``check_*``
 attribute on the enforcer module appears in it. A check that is intentionally
 not wired must be listed in ``KNOWN_UNDISPATCHED_CHECKS`` with a reason in this
-docstring; no such checks exist today. The companion ``test_code_rules_enforcer_
-cap_meta.py`` guards the payload-cap convention; this module guards the wiring.
+docstring. ``check_unanchored_command_dispatch`` is listed there: it guards a
+``hooks/blocking`` command classifier, and the whole ``validate_content`` verdict
+stays off hook-infrastructure files, so the enforcer dispatches it from
+``_hook_infrastructure_blocking_issues`` instead. The companion
+``test_code_rules_enforcer_cap_meta.py`` guards the payload-cap convention; this
+module guards the wiring.
 """
 
 from __future__ import annotations
@@ -34,7 +38,9 @@ assert _hook_specification.loader is not None
 _hook_module = importlib.util.module_from_spec(_hook_specification)
 _hook_specification.loader.exec_module(_hook_module)
 
-KNOWN_UNDISPATCHED_CHECKS: frozenset[str] = frozenset()
+KNOWN_UNDISPATCHED_CHECKS: frozenset[str] = frozenset(
+    {"check_unanchored_command_dispatch"}
+)
 
 
 def _all_check_function_names() -> list[str]:

package/hooks/blocking/test_code_rules_enforcer_docstring_type_checking_gate.py

@@ -0,0 +1,164 @@
+"""Tests for check_docstring_names_absent_type_checking_gate — Category O6.
+
+A module or function docstring that names a ``TYPE_CHECKING`` gate-detection step,
+or a ``type-checking-gate`` helper family, drifts once no identifier in the body
+handles TYPE_CHECKING: the prose points a reader at machinery the module does not
+hold. This is the deterministic slice of Category O6 (docstring prose versus
+implementation drift) for a TYPE_CHECKING gate claim. The check covers hook
+infrastructure, where the import-scan gates that carry this drift class live.
+"""
+
+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_type_checking_gate(content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_docstring_names_absent_type_checking_gate(content, file_path)
+
+
+PRODUCTION_HOOK_PATH = "/home/user/.claude/hooks/blocking/code_rules_unused_imports.py"
+TEST_FILE_PATH = "/home/user/.claude/hooks/blocking/test_code_rules_unused_imports.py"
+MYPY_GATE_PRODUCTION_PATH = "/home/user/project/scripts/run_mypy_gate.py"
+
+
+def test_flags_module_docstring_naming_type_checking_gate_helpers() -> None:
+    content = (
+        '"""Unused module-level import check and its import-range and '
+        'type-checking-gate helpers."""\n'
+        "\n"
+        "import ast\n"
+        "\n"
+        "\n"
+        "def check_unused(content: str) -> list[str]:\n"
+        '    """Flag unused imports."""\n'
+        "    return []\n"
+    )
+    issues = check_type_checking_gate(content, PRODUCTION_HOOK_PATH)
+    assert len(issues) == 1
+    assert issues[0].startswith("Line 1:")
+    assert "type-checking-gate" in issues[0]
+
+
+def test_flags_function_docstring_naming_type_checking_gate_detection() -> None:
+    content = (
+        "import ast\n"
+        "\n"
+        "\n"
+        "def check_unused_module_level_imports(content: str) -> list[str]:\n"
+        '    """Flag module-level imports never referenced.\n'
+        "\n"
+        "    When ``full_file_content`` is provided, the ``__all__`` /\n"
+        "    ``TYPE_CHECKING`` gate detection and reference scanning run against\n"
+        "    ``full_file_content``.\n"
+        '    """\n'
+        "    return []\n"
+    )
+    issues = check_type_checking_gate(content, PRODUCTION_HOOK_PATH)
+    assert len(issues) == 1
+    assert "type_checking gate" in issues[0]
+
+
+def test_flags_both_module_and_function_docstrings_on_the_real_drift() -> None:
+    content = (
+        '"""Unused module-level import check and its import-range and '
+        'type-checking-gate helpers."""\n'
+        "\n"
+        "import ast\n"
+        "\n"
+        "\n"
+        "def check_unused_module_level_imports(content: str) -> list[str]:\n"
+        '    """Flag module-level imports never referenced.\n'
+        "\n"
+        "    The ``__all__`` / ``TYPE_CHECKING`` gate detection and reference\n"
+        "    scanning run against ``full_file_content``.\n"
+        '    """\n'
+        "    return []\n"
+    )
+    issues = check_type_checking_gate(content, PRODUCTION_HOOK_PATH)
+    assert len(issues) == 2
+
+
+def test_passes_when_code_declares_a_type_checking_gate_helper() -> None:
+    content = (
+        '"""Unused module-level import check and its type-checking-gate helpers."""\n'
+        "\n"
+        "import ast\n"
+        "\n"
+        "\n"
+        "def _module_body_declares_type_checking_gate(tree: ast.Module) -> bool:\n"
+        '    """Return True when the module guards imports behind TYPE_CHECKING."""\n'
+        "    return False\n"
+    )
+    assert check_type_checking_gate(content, PRODUCTION_HOOK_PATH) == []
+
+
+def test_passes_when_body_names_type_checking_guard() -> None:
+    content = (
+        "import ast\n"
+        "from typing import TYPE_CHECKING\n"
+        "\n"
+        "\n"
+        "def check_unused(content: str) -> list[str]:\n"
+        '    """Skip imports the ``TYPE_CHECKING`` gate detection guards."""\n'
+        "    if TYPE_CHECKING:\n"
+        "        return []\n"
+        "    return []\n"
+    )
+    assert check_type_checking_gate(content, PRODUCTION_HOOK_PATH) == []
+
+
+def test_passes_when_no_docstring_names_the_gate() -> None:
+    content = (
+        '"""Unused module-level import check and its import-range helpers."""\n'
+        "\n"
+        "import ast\n"
+        "\n"
+        "\n"
+        "def check_unused(content: str) -> list[str]:\n"
+        '    """Flag module-level imports never referenced."""\n'
+        "    return []\n"
+    )
+    assert check_type_checking_gate(content, PRODUCTION_HOOK_PATH) == []
+
+
+def test_passes_on_mypy_static_type_checker_gate_docstring() -> None:
+    content = (
+        "\"\"\"Run the project's type-checking gate and report failures.\"\"\"\n"
+        "\n"
+        "import subprocess\n"
+        "\n"
+        "\n"
+        "def run_gate() -> int:\n"
+        '    return subprocess.run(["mypy", "hooks"]).returncode\n'
+    )
+    assert check_type_checking_gate(content, MYPY_GATE_PRODUCTION_PATH) == []
+
+
+def test_test_files_are_exempt() -> None:
+    content = (
+        '"""Unused module-level import check and its type-checking-gate helpers."""\n'
+        "\n"
+        "import ast\n"
+        "\n"
+        "\n"
+        "def check_unused(content: str) -> list[str]:\n"
+        '    """Flag unused imports."""\n'
+        "    return []\n"
+    )
+    assert check_type_checking_gate(content, TEST_FILE_PATH) == []

package/hooks/blocking/test_code_rules_enforcer_unused_imports.py

@@ -190,15 +190,28 @@ def test_should_flag_dead_import_in_workflow_handler_file() -> None:
     )
 
 
-def test_should_skip_test_files() -> None:
+def test_should_flag_unused_import_in_test_file() -> None:
     source = (
-        "from hooks_constants.constants import UNUSED_NAME\n"
+        "import asyncio\n"
         "\n"
         "def test_thing() -> None:\n"
         "    assert True\n"
     )
     issues = check_unused_module_level_imports(source, TEST_FILE_PATH)
-    assert issues == [], f"Test files exempt, got: {issues}"
+    assert any("asyncio" in each_issue for each_issue in issues), (
+        f"Unused import in a test file must be flagged, got: {issues}"
+    )
+
+
+def test_should_not_flag_used_import_in_test_file() -> None:
+    source = (
+        "import asyncio\n"
+        "\n"
+        "def test_thing() -> None:\n"
+        "    asyncio.run(main())\n"
+    )
+    issues = check_unused_module_level_imports(source, TEST_FILE_PATH)
+    assert issues == [], f"Used import in a test file must not be flagged, got: {issues}"
 
 
 def test_should_handle_syntax_error_gracefully() -> None:

package/hooks/blocking/test_code_rules_js_conventions.py

@@ -0,0 +1,167 @@
+"""Behavioral tests for the JavaScript boolean-naming and banned-identifier checks."""
+
+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_js_conventions import (  # noqa: E402
+    check_js_banned_identifiers,
+    check_js_boolean_naming,
+)
+
+CONVERGE_PATH = "packages/claude-dev-env/skills/autoconverge/workflow/converge.mjs"
+
+
+def test_flags_unprefixed_boolean_let_declaration() -> None:
+    content = "let hardeningPrOpened = false\n"
+    issues = check_js_boolean_naming(content, CONVERGE_PATH)
+    assert len(issues) == 1
+    assert "hardeningPrOpened" in issues[0]
+    assert "Line 1" in issues[0]
+
+
+def test_flags_unprefixed_boolean_negation_declaration() -> None:
+    content = "const readyState = !pending\n"
+    issues = check_js_boolean_naming(content, CONVERGE_PATH)
+    assert len(issues) == 1
+    assert "readyState" in issues[0]
+
+
+def test_flags_pure_negation_declaration() -> None:
+    content = "const ready = !pending;\n"
+    issues = check_js_boolean_naming(content, CONVERGE_PATH)
+    assert len(issues) == 1
+    assert "ready" in issues[0]
+
+
+def test_does_not_flag_ternary_negation_string_declaration() -> None:
+    content = 'const label = !isActive ? "on" : "off";\n'
+    assert check_js_boolean_naming(content, CONVERGE_PATH) == []
+
+
+def test_does_not_flag_ternary_negation_number_declaration() -> None:
+    content = "const count = !arr.length ? 0 : arr.length;\n"
+    assert check_js_boolean_naming(content, CONVERGE_PATH) == []
+
+
+def test_does_not_flag_negation_logical_and_declaration() -> None:
+    content = "const name = !err && getName();\n"
+    assert check_js_boolean_naming(content, CONVERGE_PATH) == []
+
+
+def test_does_not_flag_negation_logical_or_declaration() -> None:
+    content = "const port = !custom || 8080;\n"
+    assert check_js_boolean_naming(content, CONVERGE_PATH) == []
+
+
+def test_flags_unprefixed_boolean_jsdoc_param() -> None:
+    content = (
+        "/**\n"
+        " * @param {boolean} alreadyOpened whether the PR is open\n"
+        " */\n"
+        "function note(alreadyOpened) { return alreadyOpened }\n"
+    )
+    issues = check_js_boolean_naming(content, CONVERGE_PATH)
+    assert len(issues) == 1
+    assert "alreadyOpened" in issues[0]
+    assert "parameter" in issues[0].lower()
+
+
+def test_accepts_prefixed_boolean_declarations() -> None:
+    content = (
+        "let isReady = true\n"
+        "const hasItems = false\n"
+        "let shouldRetry = !done\n"
+        "var wasOpened = true\n"
+    )
+    assert check_js_boolean_naming(content, CONVERGE_PATH) == []
+
+
+def test_accepts_prefixed_boolean_jsdoc_param() -> None:
+    content = (
+        "/**\n"
+        " * @param {boolean} isOpen whether the PR is open\n"
+        " */\n"
+        "function note(isOpen) { return isOpen }\n"
+    )
+    assert check_js_boolean_naming(content, CONVERGE_PATH) == []
+
+
+def test_ignores_boolean_declaration_inside_string_literal() -> None:
+    content = 'const label = "let flagged = false"\n'
+    assert check_js_boolean_naming(content, CONVERGE_PATH) == []
+
+
+def test_ignores_boolean_declaration_inside_line_comment() -> None:
+    content = "// let flagged = false\nconst isReady = true\n"
+    assert check_js_boolean_naming(content, CONVERGE_PATH) == []
+
+
+def test_does_not_flag_falsely_named_non_boolean_declaration() -> None:
+    content = "const counted = falsely()\n"
+    assert check_js_boolean_naming(content, CONVERGE_PATH) == []
+
+
+def test_boolean_naming_scoped_to_changed_lines() -> None:
+    content = "let alreadyRun = false\nconst isReady = true\n"
+    unchanged_only = check_js_boolean_naming(content, CONVERGE_PATH, {2})
+    assert unchanged_only == []
+    changed = check_js_boolean_naming(content, CONVERGE_PATH, {1})
+    assert len(changed) == 1
+    assert "alreadyRun" in changed[0]
+
+
+def test_boolean_naming_defer_scope_returns_all() -> None:
+    content = "let alreadyRun = false\n"
+    deferred = check_js_boolean_naming(content, CONVERGE_PATH, None, True)
+    assert len(deferred) == 1
+
+
+def test_boolean_naming_exempts_test_files() -> None:
+    content = "let alreadyRun = false\n"
+    assert check_js_boolean_naming(content, "workflow/converge.test.mjs") == []
+
+
+def test_flags_banned_identifier_declaration() -> None:
+    content = "let data = fetchThings()\n"
+    issues = check_js_banned_identifiers(content, CONVERGE_PATH)
+    assert len(issues) == 1
+    assert "data" in issues[0]
+    assert "Line 1" in issues[0]
+
+
+def test_accepts_descriptive_identifier_declaration() -> None:
+    content = "let allOrders = fetchThings()\n"
+    assert check_js_banned_identifiers(content, CONVERGE_PATH) == []
+
+
+def test_banned_identifier_message_carries_descriptive_name_guidance() -> None:
+    content = "let data = fetchThings()\n"
+    issues = check_js_banned_identifiers(content, CONVERGE_PATH)
+    assert "use descriptive name (see CODE_RULES Naming section)" in issues[0]
+
+
+def test_flags_each_banned_identifier_name() -> None:
+    content = "const result = compute()\nlet response = call()\nvar ctx = build()\n"
+    issues = check_js_banned_identifiers(content, CONVERGE_PATH)
+    assert len(issues) == 3
+
+
+def test_banned_identifier_ignores_string_literal() -> None:
+    content = 'const label = "let data = 1"\n'
+    assert check_js_banned_identifiers(content, CONVERGE_PATH) == []
+
+
+def test_banned_identifier_scoped_to_changed_lines() -> None:
+    content = "let data = one()\nconst allOrders = two()\n"
+    assert check_js_banned_identifiers(content, CONVERGE_PATH, {2}) == []
+    changed = check_js_banned_identifiers(content, CONVERGE_PATH, {1})
+    assert len(changed) == 1
+
+
+def test_banned_identifier_exempts_test_files() -> None:
+    content = "let data = one()\n"
+    assert check_js_banned_identifiers(content, "workflow/converge.test.mjs") == []

package/hooks/hooks_constants/CLAUDE.md

@@ -16,6 +16,7 @@ Shared constant modules imported by hooks throughout the `hooks/` tree. Each fil
 | `env_var_table_code_drift_constants.py` | Table patterns, env-var-name and code-file recognizers, scan budget, and block-message text for the env-var-table code-drift blocker |
 | `code_rules_path_utils_constants.py` | Path-matching helpers used by the code-rules check modules |
 | `code_verifier_spawn_preflight_gate_constants.py` | Subagent type, merge-tree command flags, timeouts, and deny-message text for the code-verifier spawn pre-flight gate |
+| `command_dispatch_constants.py` | Command-word regex, command-key access pattern, tokenization pattern, and anchors for the unanchored command-dispatch meta-gate |
 | `convergence_branch_constants.py` | Branch and worktree naming patterns for the convergence gate |
 | `dead_argparse_argument_constants.py` | Patterns for detecting unused argparse arguments |
 | `dead_config_field_constants.py` | Patterns for detecting unused `*Config` / `*Selectors` dataclass fields |
@@ -34,6 +35,7 @@ Shared constant modules imported by hooks throughout the `hooks/` tree. Each fil
 | `hook_prose_detector_consistency_constants.py` | Trigger patterns and corrective messages for the hook-prose consistency checker |
 | `html_companion_constants.py` | Blocked URL schemes and other config for the `.md`-to-`.html` companion hook |
 | `inline_tuple_string_magic_constants.py` | Patterns for detecting magic strings in inline tuple literals |
+| `js_conventions_constants.py` | Banned identifier set, boolean-prefix pattern, and declaration/JSDoc patterns for the JavaScript convention checks |
 | `md_to_html_blocker_constants.py` | Path exemptions and trigger patterns for the markdown-to-html blocker |
 | `messages.py` | Short user-facing notice strings shown when a Stop hook redirects agent behavior |
 | `multi_edit_reconstruction.py` | `apply_edits()` / `edits_for_tool()` — shared helpers that reconstruct the post-edit content of an Edit or MultiEdit, imported by the blockers that judge post-edit content |

package/hooks/hooks_constants/blocking_check_limits.py

@@ -10,6 +10,8 @@ from __future__ import annotations
 import re
 
 MAX_BANNED_PREFIX_ISSUES: int = 3
+MAX_POLARITY_CONTRADICTION_ISSUES: int = 3
+MAX_VACUOUS_CLEANUP_ASSERTION_ISSUES: int = 3
 MAX_STUB_IMPLEMENTATION_ISSUES: int = 3
 MAX_TYPED_DICT_PAIR_ISSUES: int = 3
 MAX_TEST_BRANCHING_ISSUES: int = 3
@@ -239,6 +241,13 @@ ALL_PATH_METADATA_ACCESS_METHOD_NAMES: frozenset[str] = frozenset(
     {"is_file", "is_dir", "exists", "stat", "lstat"}
 )
 
+MAX_DOCSTRING_TYPE_CHECKING_GATE_ISSUES: int = 3
+TYPE_CHECKING_IDENTIFIER_MARKER: str = "type_checking"
+ALL_ABSENT_TYPE_CHECKING_GATE_DOCSTRING_PHRASES: tuple[str, ...] = (
+    "type_checking gate",
+    "type-checking-gate",
+)
+
 MAX_DOCSTRING_INLINE_LITERAL_CLAIM_ISSUES: int = 3
 ALL_DOCSTRING_NO_INLINE_LITERAL_CLAIM_PHRASES: tuple[str, ...] = (
     "no literals appear inline",

package/hooks/hooks_constants/command_dispatch_constants.py

@@ -0,0 +1,28 @@
+"""Constants for the unanchored command-dispatch meta-gate."""
+
+import re
+
+COMMAND_DISPATCH_PATH_MARKER: str = "hooks/blocking"
+
+COMMAND_DISPATCH_LITERAL_PATTERN: re.Pattern[str] = re.compile(
+    r"\b(?:gh|git|npm|npx|node|python3?|pwsh|powershell|docker|kubectl|pip|cargo"
+    r"|yarn|pnpm)\\s[+*]"
+)
+
+COMMAND_KEY_ACCESS_PATTERN: re.Pattern[str] = re.compile(
+    r"""(?:\[\s*|\.get\(\s*)["']command["']"""
+)
+
+FIRST_TOKEN_TOKENIZATION_PATTERN: re.Pattern[str] = re.compile(
+    r"shlex\.split|\.split\("
+)
+
+ALL_REGEX_START_ANCHOR_TOKENS: tuple[str, ...] = ("^", "\\A")
+
+COMMAND_DISPATCH_MESSAGE_SUFFIX: str = (
+    "matches a multi-word command as a substring - anchor the pattern to the "
+    "start of the command (^) or tokenize the first word (shlex.split) so a "
+    "command like 'echo gh pr create' is not matched"
+)
+
+MAX_COMMAND_DISPATCH_ISSUES: int = 20

package/hooks/hooks_constants/js_conventions_constants.py

@@ -0,0 +1,54 @@
+"""Configuration constants for the JavaScript convention checks in code_rules_enforcer."""
+
+import re
+
+ALL_JAVASCRIPT_BANNED_IDENTIFIERS: frozenset[str] = frozenset(
+    {
+        "result",
+        "data",
+        "output",
+        "response",
+        "value",
+        "item",
+        "temp",
+        "ctx",
+        "cfg",
+        "msg",
+        "btn",
+        "idx",
+        "cnt",
+        "tmp",
+        "elem",
+        "val",
+    }
+)
+
+_JAVASCRIPT_NEGATION_OPERAND: str = (
+    r"[A-Za-z_$][\w$]*"
+    r"(?:\s*\.\s*[A-Za-z_$][\w$]*|\s*\((?:[^()]|\([^()]*\))*\))*"
+)
+
+JAVASCRIPT_BOOLEAN_DECLARATION_PATTERN: re.Pattern[str] = re.compile(
+    r"\b(?:const|let|var)\s+(?P<name>[A-Za-z_$][\w$]*)\s*=\s*"
+    r"(?:(?:true|false)\b|!\s*" + _JAVASCRIPT_NEGATION_OPERAND + r"\s*(?:;|$))"
+)
+
+JAVASCRIPT_BOOLEAN_JSDOC_PARAMETER_PATTERN: re.Pattern[str] = re.compile(
+    r"@param\s*\{\s*boolean\s*\}\s+(?P<name>[A-Za-z_$][\w$]*)"
+)
+
+JAVASCRIPT_DECLARATION_NAME_PATTERN: re.Pattern[str] = re.compile(
+    r"\b(?:const|let|var)\s+(?P<name>[A-Za-z_$][\w$]*)\s*="
+)
+
+JAVASCRIPT_BOOLEAN_PREFIX_PATTERN: re.Pattern[str] = re.compile(
+    r"^(?:is|has|should|can|was|did)(?:[A-Z0-9_]|$)"
+)
+
+BOOLEAN_PREFIX_GUIDANCE: str = "prefix with is/has/should/can/was/did"
+
+SINGLE_CHARACTER_NAME_LENGTH: int = 1
+
+MAX_JAVASCRIPT_BOOLEAN_NAMING_ISSUES: int = 20
+
+MAX_JAVASCRIPT_BANNED_IDENTIFIER_ISSUES: int = 20

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.80.0",
+    "version": "1.81.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/rules/docstring-prose-matches-implementation.md

@@ -6,7 +6,7 @@
 
 When a docstring enumerates the behaviors a body applies, the enumeration covers every behavior the body applies. A reader trusts the list to be complete: an item the code applies but the prose omits is a silent gap that misleads every future reader and reviewer.
 
-The gate validator `check_docstring_args_match_signature` covers the `Args:` section parameter names. Nine more gate validators each cover one deterministic slice of the free-form prose. `check_docstring_length_constant_superlative_vs_exact_gate` covers a length-constant module whose docstring describes an integer `*_LENGTH` constant with a superlative or range word (`the longest color string the swatch accepts`) while the only code consuming the constant compares `len(...)` against it with `==`/`!=` — an exact-length gate that rejects every other length — and never with an ordered operator; the check scans the constant module's package tree (its own directory, or the parent package when the module sits in a `config/` subdirectory), so the mismatching consumer may sit in a sibling module. `check_docstring_fallback_branch_coverage` covers a summary that scopes a fallback to a single condition (`only when`, `falls back to ... when`) while the body routes to that same fallback call from two or more distinct early-return guards. `check_class_docstring_names_public_methods` covers a class whose docstring is a single summary line while the class exposes two or more public methods whose names the summary never spells out — the drift where a one-line class summary keeps naming its first feature after the class grows a second public entry point. `check_docstring_no_consumer_claim` covers a producer docstring asserting that no consumer reads its output yet (`producer-only artifact`, `no submission-run consumer reads it yet`) — a transitional claim that drifts the moment a reader lands and contradicts any companion `SKILL.md` that documents the consumer; this is the deterministic slice of the O8 companion-doc producer/consumer drift below. `check_docstring_returns_plural_cardinality` covers a `Returns:` clause that names a dict-key prefix family with a plural noun (`the sheen stops`) while the returned dict literal holds exactly one key in that family (`sheen_mid`) — the drift where a single-key family carries a plural noun, so the prose claims a cardinality of two or more that the dict does not hold. `check_docstring_args_single_line_scope_vs_span` covers an `Args:` entry whose prose scopes a finding to a single named line (`only when its block-anchor line is among the changed lines`) while the body builds a `range(...)` span over the finding's source lines and scopes it through a span-intersection scoper — the drift where the Args entry claims a narrower single-line scope than the span-intersection body applies, so an edit touching any non-anchor line of the span still blocks. `check_docstring_cardinal_count_matches_constant_family` covers a docstring that states a cardinal count of an outcome family (`Covers the four outcome branches: ...`) and lists those members, while the module references more members of the same `UPPER_SNAKE` constant family than the count names (`OUTCOME_OFFENDER_UNREADABLE` is imported and exercised, yet the summary stops at four) — the drift where a summary keeps the old count after the code grows another branch; this gate runs on test modules as well as production modules. `check_docstring_raises_unraisable_largezipfile` covers a `Raises:` clause that names `zipfile.LargeZipFile` while the function opens its `zipfile.ZipFile` writer in a write mode (`w`/`a`/`x`) with `allowZip64` left at its default of True — `zipfile` raises `LargeZipFile` only when an entry needs ZIP64 and `allowZip64` is False, so a writer that allows ZIP64 documents an exception the body cannot produce. `check_docstring_no_network_claim_with_metadata_access` covers a function docstring promising a code path returns `without touching the network` (or a sibling no-network phrase) while the body calls a path-metadata method (`is_file`, `is_dir`, `exists`, `stat`, `lstat`) — on a network share each metadata call is a round-trip over the wire, so a cache-hit path the docstring swore avoids the network still pays a stat on every call; reword the claim to state the path is stat-checked on every call, or short-circuit to the cached path before the share is touched. The remaining free-form prose — `"a field counts as read when ..."`, `"resolves to shared temp only"`, `"strip ceremony, then drop blockquotes"`, and the broader module-responsibility paragraph outside the user-facing-text-scope slice the checklist below names — has no signature, method roster, or single structural shape to compare against, so the gate cannot catch its drift. This rule is the judgment standard for that prose; the audit lane below is the enforcement for everything outside the ten gated slices.
+The gate validator `check_docstring_args_match_signature` covers the `Args:` section parameter names. Ten more gate validators each cover one deterministic slice of the free-form prose. `check_docstring_names_absent_type_checking_gate` covers a module or function docstring that names a `TYPE_CHECKING` gate-detection step, or a `type-checking-gate` helper family, while no identifier in the module's code carries the `type_checking` marker — the drift where the prose points a reader at a gate the body never performs; drop the `TYPE_CHECKING` gate wording, or add the detection the prose describes. `check_docstring_length_constant_superlative_vs_exact_gate` covers a length-constant module whose docstring describes an integer `*_LENGTH` constant with a superlative or range word (`the longest color string the swatch accepts`) while the only code consuming the constant compares `len(...)` against it with `==`/`!=` — an exact-length gate that rejects every other length — and never with an ordered operator; the check scans the constant module's package tree (its own directory, or the parent package when the module sits in a `config/` subdirectory), so the mismatching consumer may sit in a sibling module. `check_docstring_fallback_branch_coverage` covers a summary that scopes a fallback to a single condition (`only when`, `falls back to ... when`) while the body routes to that same fallback call from two or more distinct early-return guards. `check_class_docstring_names_public_methods` covers a class whose docstring is a single summary line while the class exposes two or more public methods whose names the summary never spells out — the drift where a one-line class summary keeps naming its first feature after the class grows a second public entry point. `check_docstring_no_consumer_claim` covers a producer docstring asserting that no consumer reads its output yet (`producer-only artifact`, `no submission-run consumer reads it yet`) — a transitional claim that drifts the moment a reader lands and contradicts any companion `SKILL.md` that documents the consumer; this is the deterministic slice of the O8 companion-doc producer/consumer drift below. `check_docstring_returns_plural_cardinality` covers a `Returns:` clause that names a dict-key prefix family with a plural noun (`the sheen stops`) while the returned dict literal holds exactly one key in that family (`sheen_mid`) — the drift where a single-key family carries a plural noun, so the prose claims a cardinality of two or more that the dict does not hold. `check_docstring_args_single_line_scope_vs_span` covers an `Args:` entry whose prose scopes a finding to a single named line (`only when its block-anchor line is among the changed lines`) while the body builds a `range(...)` span over the finding's source lines and scopes it through a span-intersection scoper — the drift where the Args entry claims a narrower single-line scope than the span-intersection body applies, so an edit touching any non-anchor line of the span still blocks. `check_docstring_cardinal_count_matches_constant_family` covers a docstring that states a cardinal count of an outcome family (`Covers the four outcome branches: ...`) and lists those members, while the module references more members of the same `UPPER_SNAKE` constant family than the count names (`OUTCOME_OFFENDER_UNREADABLE` is imported and exercised, yet the summary stops at four) — the drift where a summary keeps the old count after the code grows another branch; this gate runs on test modules as well as production modules. `check_docstring_raises_unraisable_largezipfile` covers a `Raises:` clause that names `zipfile.LargeZipFile` while the function opens its `zipfile.ZipFile` writer in a write mode (`w`/`a`/`x`) with `allowZip64` left at its default of True — `zipfile` raises `LargeZipFile` only when an entry needs ZIP64 and `allowZip64` is False, so a writer that allows ZIP64 documents an exception the body cannot produce. `check_docstring_no_network_claim_with_metadata_access` covers a function docstring promising a code path returns `without touching the network` (or a sibling no-network phrase) while the body calls a path-metadata method (`is_file`, `is_dir`, `exists`, `stat`, `lstat`) — on a network share each metadata call is a round-trip over the wire, so a cache-hit path the docstring swore avoids the network still pays a stat on every call; reword the claim to state the path is stat-checked on every call, or short-circuit to the cached path before the share is touched. The remaining free-form prose — `"a field counts as read when ..."`, `"resolves to shared temp only"`, `"strip ceremony, then drop blockquotes"`, and the broader module-responsibility paragraph outside the user-facing-text-scope slice the checklist below names — has no signature, method roster, or single structural shape to compare against, so the gate cannot catch its drift. This rule is the judgment standard for that prose; the audit lane below is the enforcement for everything outside the eleven gated slices.
 
 ## What to check before you write the docstring
 
@@ -28,6 +28,7 @@ Read the body and the docstring side by side:
 - **Predicate breadth.** A boolean helper whose prose promises a narrow check accepts only the inputs the prose names — no broader input class the name and prose do not mention.
 - **Exclusion-clause distinguisher.** A docstring sentence that says a named category of input "are not" / "is not" the thing the function flags (`plain logging, screenshot, or method-on-local calls inside a branch are not dispatch steps`) keys the exclusion to the same axis the body's classification keys on. When the body decides on one axis (a call sits in an `If.test` guard versus a plain statement) but the prose excludes on a different axis (the call's receiver shape — a method on a local), the exclusion clause names a category the body still flags: a guarded method-on-local call is flagged even though the prose lists method-on-local calls as excluded. Read the body's actual branch condition, then state the exclusion on that same axis (`plain (unguarded) calls inside a branch body are not dispatch steps`), so every member the prose excludes is a member the body also excludes.
 - **Companion-doc ordering and content claims.** A `SKILL.md` (or sibling `.md`) sentence that names a produced artifact and claims its order (`sorted`, `alphabetical`, `in sorted order`) or its content (`the at-risk names`, `just the current set`) matches the producer function's docstring and body for that same artifact. A producer that builds the artifact by merging stored names with new names and appending — preserving file order, not re-sorting the union — leaves a doc that still says `sorted` drifted on both counts: the order claim is wrong, and the content claim hides the merged-in prior entries. When the producer's ordering or union changes, the same change updates the companion doc. The two move together in one commit, even when the producer edit does not touch the `.md` file.
+- **TYPE_CHECKING gate claim vs code.** A docstring that names a `TYPE_CHECKING` gate-detection step, or a `type-checking-gate` helper family, matches a module whose code handles TYPE_CHECKING. When no identifier in the body carries the `type_checking` marker — no `TYPE_CHECKING` load, import alias, attribute, or helper name — the prose points a reader at a gate the module never performs. State what the module does, or add the detection the prose describes. The `check_docstring_names_absent_type_checking_gate` gate blocks this drift at Write/Edit time, and covers hook infrastructure, where the import-scan gates that carry this drift class live.
 
 When the body changes the set of behaviors it applies, the same edit updates the prose enumeration. The two move together in one commit.