claude-dev-env 1.79.0 → 1.80.0

package/hooks/blocking/test_code_rules_enforcer_unused_imports.py

@@ -5,9 +5,12 @@ ALL_REPOSITORY_ROOT_MARKER_FILENAMES, VENV_DIRECTORY_NAME and other
 imports that survived into a PR without ever being referenced.
 
 The detector is intentionally narrow: it only flags `from X import Y`
-or `import X` where Y/X is never referenced in the file body, the file
-does not declare `__all__`, and the file does not use TYPE_CHECKING
-conditional imports. The narrow scope keeps false positives low.
+or `import X` where Y/X is never referenced in the file body and the
+file does not declare `__all__`. A `TYPE_CHECKING` guard block no longer
+exempts the whole file — its guarded imports live nested inside the
+`if TYPE_CHECKING:` node so they are never flag candidates, while a
+genuinely dead top-level runtime import in the same file is still
+flagged. The narrow scope keeps false positives low.
 """
 
 from __future__ import annotations
@@ -102,7 +105,7 @@ def test_should_skip_file_with_dunder_all_annotated_assignment() -> None:
     )
 
 
-def test_should_skip_file_using_type_checking_block() -> None:
+def test_should_flag_dead_top_level_import_in_type_checking_file() -> None:
     source = (
         "from typing import TYPE_CHECKING\n"
         "from hooks_constants.constants import UNUSED_NAME\n"
@@ -114,8 +117,76 @@ def test_should_skip_file_using_type_checking_block() -> None:
         "    return None\n"
     )
     issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH)
+    assert any("UNUSED_NAME" in each_issue for each_issue in issues), (
+        "A dead top-level runtime import must be flagged even when the file "
+        f"also declares a TYPE_CHECKING block, got: {issues}"
+    )
+    assert not any("OtherName" in each_issue for each_issue in issues), (
+        "A TYPE_CHECKING-guarded import is nested inside the if block and is "
+        f"never a flag candidate, got: {issues}"
+    )
+
+
+def test_should_not_flag_standard_type_checking_idiom() -> None:
+    source = (
+        "from typing import TYPE_CHECKING\n"
+        "from hooks_constants.constants import RUNTIME_NAME\n"
+        "\n"
+        "if TYPE_CHECKING:\n"
+        "    from somewhere import TypeOnly\n"
+        "\n"
+        "def run(node: TypeOnly) -> None:\n"
+        "    RUNTIME_NAME()\n"
+    )
+    issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH)
     assert issues == [], (
-        f"TYPE_CHECKING-using files have annotation-only imports — skip, got: {issues}"
+        "The standard TYPE_CHECKING idiom — TYPE_CHECKING referenced by the "
+        "guard, the runtime import used in the body, and the guarded import "
+        f"used in an annotation — must produce no findings, got: {issues}"
+    )
+
+
+def test_should_flag_dead_import_beside_type_checking_string_annotation() -> None:
+    source = (
+        "from typing import TYPE_CHECKING\n"
+        "from shared_utils.config import portal_specific_timeouts\n"
+        "\n"
+        "if TYPE_CHECKING:\n"
+        "    from shared_utils.base import BaseAutomation\n"
+        "\n"
+        'async def run(automation: "BaseAutomation") -> None:\n'
+        "    return None\n"
+    )
+    issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH)
+    assert any("portal_specific_timeouts" in each_issue for each_issue in issues), (
+        "A dead top-level import in a module that guards its annotation-only "
+        f"import under TYPE_CHECKING must still be flagged, got: {issues}"
+    )
+    assert not any("BaseAutomation" in each_issue for each_issue in issues), (
+        "The TYPE_CHECKING-guarded import used in a string annotation must not "
+        f"be flagged, got: {issues}"
+    )
+
+
+def test_should_flag_dead_import_in_workflow_handler_file() -> None:
+    workflow_handler_path = (
+        "shared_utils/web_automation/samsung_portal/workflow/binary/delete_handlers.py"
+    )
+    source = (
+        "from typing import TYPE_CHECKING\n"
+        "from shared_utils.config import portal_specific_timeouts\n"
+        "\n"
+        "if TYPE_CHECKING:\n"
+        "    from shared_utils.base import BaseAutomation\n"
+        "\n"
+        'async def run(automation: "BaseAutomation") -> None:\n'
+        "    return None\n"
+    )
+    issues = check_unused_module_level_imports(source, workflow_handler_path)
+    assert any("portal_specific_timeouts" in each_issue for each_issue in issues), (
+        "A handler file under a workflow/ directory is not a state/module "
+        "registry; a dead import in it must be flagged, not exempted by the "
+        f"workflow path, got: {issues}"
     )
 
 
@@ -364,7 +435,7 @@ def test_should_skip_when_full_file_declares_dunder_all() -> None:
     )
 
 
-def test_should_skip_when_full_file_uses_type_checking_gate() -> None:
+def test_should_flag_dead_fragment_import_when_full_file_uses_type_checking() -> None:
     fragment = "from hooks_constants.constants import NEW_NAME\n"
     full_file = (
         "from typing import TYPE_CHECKING\n"
@@ -379,9 +450,9 @@ def test_should_skip_when_full_file_uses_type_checking_gate() -> None:
     issues = check_unused_module_level_imports(
         fragment, PRODUCTION_FILE_PATH, full_file_content=full_file,
     )
-    assert issues == [], (
-        "TYPE_CHECKING gate in the post-edit file must skip the scan, "
-        f"got: {issues}"
+    assert any("NEW_NAME" in each_issue for each_issue in issues), (
+        "A TYPE_CHECKING block in the post-edit file must not exempt a dead "
+        f"import added by the edit fragment, got: {issues}"
     )
 
 
@@ -472,7 +543,7 @@ def test_should_flag_import_when_only_shadowed_local_name_is_loaded() -> None:
     )
 
 
-def test_should_skip_when_type_checking_uses_imported_alias() -> None:
+def test_should_not_flag_guarded_import_under_imported_type_checking_alias() -> None:
     source = (
         "from typing import TYPE_CHECKING as IS_TYPE_CHECKING\n"
         "from hooks_constants.constants import UNUSED_NAME\n"
@@ -484,12 +555,17 @@ def test_should_skip_when_type_checking_uses_imported_alias() -> None:
         "    return None\n"
     )
     issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH)
-    assert issues == [], (
-        f"TYPE_CHECKING imported aliases must skip annotation-only files, got: {issues}"
+    assert not any("OtherName" in each_issue for each_issue in issues), (
+        "An import guarded under an aliased TYPE_CHECKING is nested in the if "
+        f"block and is never a flag candidate, got: {issues}"
+    )
+    assert any("UNUSED_NAME" in each_issue for each_issue in issues), (
+        "A dead top-level import beside an aliased TYPE_CHECKING guard is still "
+        f"flagged, got: {issues}"
     )
 
 
-def test_should_skip_when_type_checking_uses_module_alias() -> None:
+def test_should_not_flag_guarded_import_under_module_type_checking_alias() -> None:
     source = (
         "import typing as t\n"
         "from hooks_constants.constants import UNUSED_NAME\n"
@@ -501,8 +577,13 @@ def test_should_skip_when_type_checking_uses_module_alias() -> None:
         "    return None\n"
     )
     issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH)
-    assert issues == [], (
-        f"TYPE_CHECKING module aliases must skip annotation-only files, got: {issues}"
+    assert not any("OtherName" in each_issue for each_issue in issues), (
+        "An import guarded under a module-qualified TYPE_CHECKING is nested in "
+        f"the if block and is never a flag candidate, got: {issues}"
+    )
+    assert any("UNUSED_NAME" in each_issue for each_issue in issues), (
+        "A dead top-level import beside a module-qualified TYPE_CHECKING guard "
+        f"is still flagged, got: {issues}"
     )
 
 

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/blocking_check_limits.py

@@ -45,6 +45,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

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/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.80.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

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

@@ -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.

package/skills/autoconverge/SKILL.md

@@ -97,6 +97,18 @@ PR's owner.
    prompt can add a standing Bash permission allow-rule for that script in their
    settings.
 
+5. **Copilot quota pre-check.** Before the `Workflow` call, run once:
+   `python "$HOME/.claude/_shared/pr-loop/scripts/copilot_quota.py"`
+   It reads the account's remaining Copilot premium-request quota via
+   `gh api copilot_internal/user` and prints one line — log that line. Exit 0
+   means Copilot has quota to run, so pass `copilotDisabled: false`. Any non-zero
+   exit means skip Copilot for this run — the account is out of quota, the quota
+   API or account access is down, or no account is set — so pass
+   `copilotDisabled: true`; the workflow then skips the Copilot gate with no agent
+   spawned. The account comes from the `COPILOT_QUOTA_ACCOUNT` environment
+   variable or a git-ignored `.env` file, and the no-account line names the exact
+   `.env` path and key to set.
+
 ## Run the workflow
 
 Call the `Workflow` tool against the colocated script:
@@ -104,7 +116,7 @@ Call the `Workflow` tool against the colocated script:
 ```
 Workflow({
   scriptPath: "<this skill dir>/workflow/converge.mjs",
-  args: { owner: "<O>", repo: "<R>", prNumber: <N>, bugbotDisabled: false }
+  args: { owner: "<O>", repo: "<R>", prNumber: <N>, bugbotDisabled: false, copilotDisabled: false }
 })
 ```
 
@@ -113,8 +125,10 @@ own directory (on this install,
 `<home>/.claude/skills/autoconverge/workflow/converge.mjs`). Set
 `bugbotDisabled: true` only when the user has opted Cursor Bugbot out for the
 run; otherwise the workflow detects an opt-out or an unreachable Bugbot on its
-own. The workflow runs in the background and notifies this session on
-completion. Watch live progress with `/workflows`.
+own. Set `copilotDisabled: true` when the step 5 quota pre-check exits non-zero,
+and `false` when it exits 0; on `true` the workflow skips the Copilot gate with
+no agent spawned. The workflow runs in the background and notifies this session
+on completion. Watch live progress with `/workflows`.
 
 The workflow returns
 `{ converged, rounds, finalSha, blocker, standardsNote, copilotNote, reuseNote }`.
@@ -341,6 +355,13 @@ each PR its own checkout with `git worktree add`. For each PR the user named:
 4. **Grant project permissions once per repository** — the single-PR pre-flight
    step 4 grant covers every worktree of the same repo, so run it one time for
    the repo the PRs live in.
+5. **Copilot quota pre-check once for the whole run** — run the single-PR
+   pre-flight step 5 check one time:
+   `python "$HOME/.claude/_shared/pr-loop/scripts/copilot_quota.py"`. Every PR in
+   the run shares one account's Copilot premium-request quota, so one check covers
+   them all. Exit 0 sets `copilotDisabled: false` on every PR entry below; any
+   non-zero exit sets `copilotDisabled: true` on every entry, so each child skips
+   the Copilot gate with no agent spawned.
 
 ### Launch the multi-PR workflow
 
@@ -353,8 +374,8 @@ Workflow({
   args: {
     convergeScriptPath: "<this skill dir>/workflow/converge.mjs",
     prs: [
-      { owner: "<O>", repo: "<R>", prNumber: <N1>, repoPath: "<abs worktree 1>", bugbotDisabled: false },
-      { owner: "<O>", repo: "<R>", prNumber: <N2>, repoPath: "<abs worktree 2>", bugbotDisabled: false }
+      { owner: "<O>", repo: "<R>", prNumber: <N1>, repoPath: "<abs worktree 1>", bugbotDisabled: false, copilotDisabled: false },
+      { owner: "<O>", repo: "<R>", prNumber: <N2>, repoPath: "<abs worktree 2>", bugbotDisabled: false, copilotDisabled: false }
     ]
   }
 })

package/skills/autoconverge/workflow/converge.clean-audit.test.mjs

@@ -40,8 +40,8 @@ test('cleanAuditBlocker falls back to a no-result reason when the post agent die
   assert.match(message, /the post agent returned no result/);
 });
 
-test('the post-clean-audit task in resumeGeneralUtilityAgent returns the CLEAN_AUDIT_SCHEMA result rather than an unused transcript', () => {
-  const body = functionBody('resumeGeneralUtilityAgent');
+test('the post-clean-audit task in runGeneralUtilityTask returns the CLEAN_AUDIT_SCHEMA result rather than an unused transcript', () => {
+  const body = functionBody('runGeneralUtilityTask');
   assert.match(body, /task === 'post-clean-audit'/);
   assert.match(body, /schema: CLEAN_AUDIT_SCHEMA/);
   assert.doesNotMatch(body, /agent transcript \(unused\)/);
@@ -59,7 +59,7 @@ test('the standards-only call site breaks with a clean-audit blocker when the po
     convergeSource.indexOf('if (isStandardsOnlyRound(findings)) {'),
     convergeSource.indexOf('if (findings.length > 0) {'),
   );
-  assert.match(branch, /resumeGeneralUtilityAgent\(.*'post-clean-audit'/);
+  assert.match(branch, /runGeneralUtilityTask\(.*'post-clean-audit'/);
   assert.match(branch, /if \(!auditResult\?\.posted\)/);
   assert.match(branch, /blocker = cleanAuditBlocker\(head, auditResult\)/);
   assert.match(branch, /\bbreak\b/);
@@ -70,7 +70,7 @@ test('the all-clean call site breaks with a clean-audit blocker when the post do
     convergeSource.indexOf('all lenses clean on'),
     convergeSource.indexOf("if (phase === 'COPILOT') {"),
   );
-  assert.match(branch, /resumeGeneralUtilityAgent\(.*'post-clean-audit'/);
+  assert.match(branch, /runGeneralUtilityTask\(.*'post-clean-audit'/);
   assert.match(branch, /if \(!auditResult\?\.posted\)/);
   assert.match(branch, /blocker = cleanAuditBlocker\(head, auditResult\)/);
   assert.match(branch, /\bbreak\b/);