claude-dev-env 1.79.0 → 1.81.0

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/blocking/test_code_rules_js_returns_object_schemaless.py

@@ -0,0 +1,167 @@
+"""Tests for check_js_returns_object_schemaless_branch.
+
+The check catches the JS/.mjs Category O6 docstring-prose-vs-implementation
+drift PR #807 surfaced: a ``function`` whose JSDoc ``@returns {Promise<object>}``
+promises a structured object, while one branch returns the agent-spawn helper
+with an options object that omits ``schema``. A schema-less agent call resolves
+to a transcript string, not the object the JSDoc claims, so the contract drifts
+for that branch while a sibling branch that does pass ``schema`` returns a real
+object.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import pathlib
+import sys
+
+_HOOK_DIRECTORY = pathlib.Path(__file__).parent
+if str(_HOOK_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(_HOOK_DIRECTORY))
+
+_module_spec = importlib.util.spec_from_file_location(
+    "code_rules_imports_logging",
+    _HOOK_DIRECTORY / "code_rules_imports_logging.py",
+)
+assert _module_spec is not None
+assert _module_spec.loader is not None
+_imports_logging_module = importlib.util.module_from_spec(_module_spec)
+_module_spec.loader.exec_module(_imports_logging_module)
+
+check_js_returns_object_schemaless_branch = (
+    _imports_logging_module.check_js_returns_object_schemaless_branch
+)
+
+_MJS_PATH = "skills/autoconverge/workflow/converge.mjs"
+
+_SHIPPED_CONVERGE_MJS = (
+    _HOOK_DIRECTORY.parents[1] / "skills" / "autoconverge" / "workflow" / "converge.mjs"
+)
+
+
+def _mixed_schema_source() -> str:
+    return (
+        "/**\n"
+        " * Spawn a git-utility agent for a task.\n"
+        " * @returns {Promise<object>} the structured output\n"
+        " */\n"
+        "function runGitTask(task, head) {\n"
+        "  if (task === 'resolve-head') {\n"
+        "    return convergeAgent(\n"
+        "      `Print the HEAD SHA of ${prCoordinates}.`,\n"
+        "      { label: 'git-utility', phase: 'Converge', schema: HEAD_SCHEMA, agentType: 'Explore' },\n"
+        "    )\n"
+        "  }\n"
+        "  if (task === 'prefetch-main') {\n"
+        "    return convergeAgent(\n"
+        "      `Refresh the base ref for ${prCoordinates}.`,\n"
+        "      { label: 'git-utility', phase: 'Converge', agentType: 'Explore' },\n"
+        "    )\n"
+        "  }\n"
+        "  return convergeAgent(\n"
+        "    `Report conflicts for ${prCoordinates}.`,\n"
+        "    { label: 'git-utility', phase: 'Converge', schema: MERGE_CONFLICT_SCHEMA, agentType: 'Explore' },\n"
+        "  )\n"
+        "}\n"
+    )
+
+
+def _all_schema_source() -> str:
+    return _mixed_schema_source().replace(
+        "      { label: 'git-utility', phase: 'Converge', agentType: 'Explore' },\n",
+        "      { label: 'git-utility', phase: 'Converge', schema: FETCH_SCHEMA, agentType: 'Explore' },\n",
+    )
+
+
+def _plain_object_return_source() -> str:
+    return (
+        "/**\n"
+        " * Joined fixer recovery loop.\n"
+        " * @returns {Promise<object>} FIX_SCHEMA result\n"
+        " */\n"
+        "async function fixerWithRecovery(head, findings, sourceLabel) {\n"
+        "  if (!verdictPassed) {\n"
+        "    return {\n"
+        "      newSha: head,\n"
+        "      pushed: false,\n"
+        "      summary: `verify step did not pass ${sourceLabel}`,\n"
+        "    }\n"
+        "  }\n"
+        "  return commitWithRecovery({\n"
+        "    runCommit: () => runFixerTask('commit', { head }),\n"
+        "    runVerify: () => runVerifierTask('fix-verify', { head }),\n"
+        "  })\n"
+        "}\n"
+    )
+
+
+def _transcript_typed_source() -> str:
+    return _mixed_schema_source().replace(
+        " * @returns {Promise<object>} the structured output\n",
+        " * @returns {Promise<*>} the agent() result\n",
+    )
+
+
+def _destructured_parameter_mixed_schema_source() -> str:
+    return (
+        "/**\n"
+        " * Commit and verify with recovery.\n"
+        " * @returns {Promise<object>} the structured verify output\n"
+        " */\n"
+        "async function commitWithRecovery({ runCommit, runVerify, head }) {\n"
+        "  if (runVerify) {\n"
+        "    return convergeAgent(\n"
+        "      `Verify the commit for ${head}.`,\n"
+        "      { label: 'commit-recovery', phase: 'Converge', schema: VERIFY_SCHEMA, agentType: 'Explore' },\n"
+        "    )\n"
+        "  }\n"
+        "  return convergeAgent(\n"
+        "    `Commit ${head} without verification.`,\n"
+        "    { label: 'commit-recovery', phase: 'Converge', agentType: 'Explore' },\n"
+        "  )\n"
+        "}\n"
+    )
+
+
+def test_flags_schema_less_branch_under_returns_object_claim() -> None:
+    issues = check_js_returns_object_schemaless_branch(_mixed_schema_source(), _MJS_PATH)
+    assert len(issues) == 1
+    assert "runGitTask" in issues[0]
+    assert "convergeAgent" in issues[0]
+
+
+def test_flags_schema_less_branch_with_destructured_parameter() -> None:
+    issues = check_js_returns_object_schemaless_branch(
+        _destructured_parameter_mixed_schema_source(), _MJS_PATH
+    )
+    assert len(issues) == 1
+    assert "commitWithRecovery" in issues[0]
+    assert "convergeAgent" in issues[0]
+
+
+def test_accepts_function_when_every_branch_passes_a_schema() -> None:
+    issues = check_js_returns_object_schemaless_branch(_all_schema_source(), _MJS_PATH)
+    assert issues == []
+
+
+def test_accepts_plain_object_returns_with_no_schema_driven_helper() -> None:
+    issues = check_js_returns_object_schemaless_branch(_plain_object_return_source(), _MJS_PATH)
+    assert issues == []
+
+
+def test_accepts_transcript_typed_returns_clause() -> None:
+    issues = check_js_returns_object_schemaless_branch(_transcript_typed_source(), _MJS_PATH)
+    assert issues == []
+
+
+def test_skips_python_files() -> None:
+    issues = check_js_returns_object_schemaless_branch(
+        _mixed_schema_source(), "workflow/converge.py"
+    )
+    assert issues == []
+
+
+def test_shipped_converge_mjs_passes_its_own_check() -> None:
+    shipped_source = _SHIPPED_CONVERGE_MJS.read_text(encoding="utf-8")
+    issues = check_js_returns_object_schemaless_branch(shipped_source, _MJS_PATH)
+    assert issues == []

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
@@ -45,6 +47,7 @@ ALL_IMPORT_BLOCK_SORT_RUFF_COMMAND_PREFIX: tuple[str, ...] = (
     "json",
 )
 MAX_JS_RESUME_TASK_ENUMERATION_ISSUES: int = 5
+MAX_JS_RETURNS_OBJECT_SCHEMALESS_ISSUES: int = 5
 MINIMUM_RESUME_TASK_ENUMERATION_ITEMS: int = 2
 DOCSTRING_TRIVIAL_FUNCTION_BODY_LINE_LIMIT: int = 3
 MAX_DOCSTRING_FALLBACK_BRANCH_ISSUES: int = 3
@@ -238,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/code_rules_enforcer_constants.py

@@ -222,6 +222,20 @@ ENUMERATION_TASK_ITEM_PATTERN: re.Pattern[str] = re.compile(
 HYPHENATED_TASK_ITEM_PATTERN: re.Pattern[str] = re.compile(
     r"^[a-z0-9]+(?:-[a-z0-9]+)+$"
 )
+FUNCTION_WITH_JSDOC_PATTERN: re.Pattern[str] = re.compile(
+    r"/\*\*(?P<jsdoc>(?:(?!\*/).)*?)\*/\s*"
+    r"(?:async\s+)?function\s+(?P<name>\w+)\s*\(",
+    re.DOTALL,
+)
+JSDOC_RETURNS_STRUCTURED_OBJECT_PROMISE_PATTERN: re.Pattern[str] = re.compile(
+    r"@returns?\s*\{[^}]*Promise\s*<\s*[Oo]bject\s*>[^}]*\}"
+)
+RETURN_CALL_OPENING_PARENTHESIS_PATTERN: re.Pattern[str] = re.compile(
+    r"\breturn\s+(?:await\s+)?(?P<callee>\w+)\s*\("
+)
+SCHEMA_OPTIONS_PROPERTY_KEY_PATTERN: re.Pattern[str] = re.compile(
+    r"(?<![A-Za-z0-9_])schema\s*:"
+)
 ALL_BUILTIN_DICT_METHOD_NAMES: frozenset[str] = frozenset({
     "get", "items", "keys", "values", "update", "pop",
     "setdefault", "copy", "clear",

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/hooks/hooks_constants/test_code_rules_enforcer_constants.py

@@ -0,0 +1,93 @@
+"""Behavior tests for the JS returns-object schema-less detection patterns.
+
+These regexes drive ``check_js_returns_object_schemaless_branch``: they locate a
+JSDoc-documented ``function`` declaration, decide whether its ``@returns`` clause
+promises a ``Promise<object>``, find each ``return`` that calls a helper, and spot
+a ``schema`` key inside an options object. Each test pins one pattern against the
+shapes it must accept and the near-misses it must reject.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+_HOOKS_ROOT = Path(__file__).resolve().parent.parent
+if str(_HOOKS_ROOT) not in sys.path:
+    sys.path.insert(0, str(_HOOKS_ROOT))
+
+from hooks_constants.code_rules_enforcer_constants import (
+    FUNCTION_WITH_JSDOC_PATTERN,
+    JSDOC_RETURNS_STRUCTURED_OBJECT_PROMISE_PATTERN,
+    RETURN_CALL_OPENING_PARENTHESIS_PATTERN,
+    SCHEMA_OPTIONS_PROPERTY_KEY_PATTERN,
+)
+
+
+def test_function_with_jsdoc_pattern_captures_name_and_jsdoc() -> None:
+    source = (
+        "/**\n * @returns {Promise<object>} the structured output\n */\n"
+        "function runGitTask(task, head) {\n"
+    )
+    match = FUNCTION_WITH_JSDOC_PATTERN.search(source)
+    assert match is not None
+    assert match.group("name") == "runGitTask"
+    assert "@returns" in match.group("jsdoc")
+
+
+def test_function_with_jsdoc_pattern_captures_async_declaration() -> None:
+    source = "/** @returns {Promise<object>} */\nasync function fixerWithRecovery(head) {\n"
+    match = FUNCTION_WITH_JSDOC_PATTERN.search(source)
+    assert match is not None
+    assert match.group("name") == "fixerWithRecovery"
+
+
+def test_returns_object_promise_pattern_matches_structured_object_claim() -> None:
+    lowercase_match = JSDOC_RETURNS_STRUCTURED_OBJECT_PROMISE_PATTERN.search(
+        "@returns {Promise<object>} the structured output"
+    )
+    assert lowercase_match is not None
+    assert lowercase_match.group(0) == "@returns {Promise<object>}"
+    capitalized_match = JSDOC_RETURNS_STRUCTURED_OBJECT_PROMISE_PATTERN.search(
+        "@return {Promise<Object>}"
+    )
+    assert capitalized_match is not None
+    assert capitalized_match.group(0) == "@return {Promise<Object>}"
+
+
+def test_returns_object_promise_pattern_rejects_string_and_array_claims() -> None:
+    assert JSDOC_RETURNS_STRUCTURED_OBJECT_PROMISE_PATTERN.search("@returns {Promise<*>}") is None
+    assert (
+        JSDOC_RETURNS_STRUCTURED_OBJECT_PROMISE_PATTERN.search("@returns {Promise<string>}") is None
+    )
+    assert (
+        JSDOC_RETURNS_STRUCTURED_OBJECT_PROMISE_PATTERN.search("@returns {Promise<object[]>}")
+        is None
+    )
+
+
+def test_return_call_pattern_captures_plain_and_awaited_callees() -> None:
+    plain_match = RETURN_CALL_OPENING_PARENTHESIS_PATTERN.search(
+        "  return convergeAgent(prompt, {})"
+    )
+    assert plain_match is not None
+    assert plain_match.group("callee") == "convergeAgent"
+    awaited_match = RETURN_CALL_OPENING_PARENTHESIS_PATTERN.search(
+        "  return await commitWithRecovery({})"
+    )
+    assert awaited_match is not None
+    assert awaited_match.group("callee") == "commitWithRecovery"
+
+
+def test_return_call_pattern_ignores_identifiers_beginning_with_return() -> None:
+    assert RETURN_CALL_OPENING_PARENTHESIS_PATTERN.search("const x = returnValue(payload)") is None
+
+
+def test_schema_property_key_pattern_matches_only_the_options_key() -> None:
+    assert (
+        SCHEMA_OPTIONS_PROPERTY_KEY_PATTERN.search("{ label: 'x', schema: HEAD_SCHEMA }")
+        is not None
+    )
+    assert SCHEMA_OPTIONS_PROPERTY_KEY_PATTERN.search("{ label: 'x', schema : X }") is not None
+    assert SCHEMA_OPTIONS_PROPERTY_KEY_PATTERN.search("{ agentType, phase }, HEAD_SCHEMA") is None
+    assert SCHEMA_OPTIONS_PROPERTY_KEY_PATTERN.search("{ myschema: X }") is None

package/hooks/hooks_constants/unused_module_import_constants.py

@@ -14,7 +14,6 @@ UNUSED_IMPORT_GUIDANCE: str = (
     "remove unused import; if kept for side effects, mark with `# noqa: F401`"
 )
 TYPE_CHECKING_IDENTIFIER: str = "TYPE_CHECKING"
-ALL_TYPING_MODULE_NAMES: frozenset[str] = frozenset({"typing", "typing_extensions"})
 
 
 def _comment_text_from_line(line_text: str) -> str | None:

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.79.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
 
@@ -17,6 +17,7 @@ Read the body and the docstring side by side:
 - **Shared fallback routes.** A summary that scopes a fallback call to one condition names every condition that reaches that call. When the body routes to the same fallback from two or more early-return guards (`if a is None: fallback(); return` and `if random() < p: fallback(); return`), the prose enumerates both guards. The `check_docstring_fallback_branch_coverage` gate blocks the single-condition form of this drift at Write/Edit time.
 - **Step order.** A docstring that says `A then B then C` matches the call order in the body. A step enumeration that names the body's linear steps also names every corrective step the body guards inside an `if`/`elif` branch (`if not await cancel_and_reinitiate_update(...): return`). The `check_docstring_step_enumeration_dispatch_coverage` gate blocks the branch-guarded-dispatch form of this drift — a step-enumeration docstring that omits a two-or-more-token dispatch step the body guards inside a branch — at Write/Edit time.
 - **JS/`.mjs` resume-task enumerations.** A `spawn<Role>Agent` JSDoc that enumerates its sibling `resume<Role>Agent`'s resume tasks in a parenthetical `resume (repair-verify, hardening-verify)` list names every `task === '<name>'` branch the resume body dispatches on. The `check_js_resume_task_enumeration_coverage` gate blocks the JavaScript form of this drift — a spawn JSDoc whose resume enumeration omits a dispatched task — at Write/Edit time. This is the `.mjs` slice of the same Category O6 standard the Python gates carry; the Python AST docstring gates never inspect JavaScript source.
+- **JS/`.mjs` `@returns` object with a schema-less branch.** A `function` whose JSDoc `@returns {Promise<object>}` promises a structured object names a return type every branch honors. When the body returns one agent-spawn helper both with a `schema` options object and without one, the schema-less branch resolves to a transcript string, not the object the JSDoc claims. The `check_js_returns_object_schemaless_branch` gate blocks this drift — a `Promise<object>` JSDoc whose body returns the same helper with and without a `schema` key — at Write/Edit time. This is the `.mjs` slice of the same Category O6 standard the Python gates carry; the Python AST docstring gates never inspect JavaScript source.
 - **Returns-clause cardinality.** A `Returns:` clause that names a dict-key prefix family with a plural noun (`the sheen stops`) matches the count of keys in that family in the returned dict literal. When the dict holds one key in the family (`sheen_mid`), the noun is singular (`the sheen stop`); a plural noun there claims two or more entries the dict does not hold. The `check_docstring_returns_plural_cardinality` gate blocks the single-key-with-plural-noun form of this drift at Write/Edit time.
 - **Length-constant superlative vs exact gate.** A module docstring that describes an integer `*_LENGTH` constant with a superlative or range word (`the longest color string the swatch accepts`, `no longer than`) matches how the code consumes the constant. When the only consumer compares `len(...)` against the constant with `==`/`!=` — an exact-length gate where every other length is rejected, not accepted at a shorter length — the superlative prose claims a range of accepted lengths the code never allows. State the exact required length (`the exact #AARRGGBB length`), not a longest/range form. The `check_docstring_length_constant_superlative_vs_exact_gate` gate blocks this drift at Write/Edit time, scanning the constant module's package tree so it sees a consumer that lives in a sibling module; a constant genuinely used as a ceiling (`len(x) <= LIMIT`) is left alone.
 - **Args single-line scope vs span body.** An `Args:` entry that scopes a finding to one named line (`a finding blocks only when its block-anchor line is among the changed lines`) matches the line breadth the body scopes by. When the body builds a `range(...)` span over the finding's source lines and scopes it through a span-intersection scoper that blocks when any line of the span is among the changed lines, the single-line Args wording understates the scope: an edit touching a non-anchor line of the span still blocks. State the Args entry on the same span breadth the body uses (`a finding blocks when any line of its block span is among the changed lines`). The `check_docstring_args_single_line_scope_vs_span` gate blocks the single-line-Args-over-span-body form of this drift at Write/Edit time.
@@ -27,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.