claude-dev-env 1.67.2 → 1.68.0

package/audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md

@@ -25,7 +25,7 @@ Decomposition is by the **kind of docstring claim** that needs to be cross-check
 | O3 | Predicate-name and -docstring vs body breadth | A boolean helper's name and docstring promise a narrow predicate. Walk the body's branches: every branch's `return True` path is consistent with the promised name. Bodies that accept inputs broader than the name (`_dir_value_resolves_to_shared_temp` also accepting HOME/TMP env-derived paths) are O3 findings. |
 | O4 | Step-ordering narrative | A docstring describes processing as `A then B then C`. Walk the body and confirm the call order matches. Mismatched order is an O4 finding regardless of whether the final output is the same. |
 | O5 | Named-sentinel / filename references | A docstring names a sentinel marker, environment variable, filename, or magic string. Confirm the named token actually exists in the module body or in the repo's naming convention. |
-| O6 | Free-form `Args:`-adjacent claims | A docstring's `Returns:` / `Raises:` / `Note:` / `Example:` sections make claims (`returns shared-temp only`, `raises ValueError on missing key`). Verify each claim against the body. When a docstring enumerates the inputs a body counts (a "field counts as read when ..." list, a list of conditions treated as a match, a list of cases the body skips), list every union member and every suppressor the body applies (`read_names = a | b | c`, each early-return guard) and confirm each appears in the prose enumeration. A union member or suppressor the body applies but the prose omits is an O6 finding. A `Returns:` that names the mechanism, tool, or output format the function produces (`instructing a StructuredOutput summary`, `returns a YAML document`, `emits a JSON object`) matches the artifact the body actually builds: a prompt body that asks the agent to "Return strictly a JSON object" while the docstring claims it "instruct[s] a StructuredOutput" summary is an O6 finding, because the named tool appears nowhere in the emitted text. See `../../rules/docstring-prose-matches-implementation.md`. |
+| O6 | Free-form `Args:`-adjacent claims | A docstring's `Returns:` / `Raises:` / `Note:` / `Example:` sections make claims (`returns shared-temp only`, `raises ValueError on missing key`). Verify each claim against the body. When a docstring enumerates the inputs a body counts (a "field counts as read when ..." list, a list of conditions treated as a match, a list of cases the body skips), list every union member and every suppressor the body applies (`read_names = a | b | c`, each early-return guard) and confirm each appears in the prose enumeration. A union member or suppressor the body applies but the prose omits is an O6 finding. The single-condition shared-fallback shape of this drift — a summary that scopes a fallback call to one condition while the body routes to that same call from two or more early-return guards — is gated deterministically at Write/Edit time by `check_docstring_fallback_branch_coverage`, so the audit lane focuses on the O6 shapes the gate cannot match. A `Returns:` that names the mechanism, tool, or output format the function produces (`instructing a StructuredOutput summary`, `returns a YAML document`, `emits a JSON object`) matches the artifact the body actually builds: a prompt body that asks the agent to "Return strictly a JSON object" while the docstring claims it "instruct[s] a StructuredOutput" summary is an O6 finding, because the named tool appears nowhere in the emitted text. See `../../rules/docstring-prose-matches-implementation.md`. |
 | O7 | Module-doc-vs-split-module after refactor | When a refactor moves a responsibility to a sibling module, the originating module's docstring and the receiving module's docstring both describe the home of that responsibility. A module docstring should describe only the responsibilities it owns. |
 
 ---

package/hooks/blocking/code_rules_docstrings.py

@@ -20,10 +20,14 @@ from code_rules_shared import (  # noqa: E402
 )
 
 from hooks_constants.blocking_check_limits import (  # noqa: E402
+    ALL_DOCSTRING_EXCLUSIVE_SCOPE_PHRASES,
     ALL_DOCSTRING_EXEMPT_DECORATOR_NAMES,
     ALL_DOCSTRING_IMPLICIT_INSTANCE_PARAMETER_NAMES,
+    ALL_DOCSTRING_MULTIPLE_CONDITION_JOINING_PHRASES,
+    DOCSTRING_FALLBACK_BRANCH_MINIMUM_ROUTE_COUNT,
     DOCSTRING_TRIVIAL_FUNCTION_BODY_LINE_LIMIT,
     MAX_DOCSTRING_ARGS_SIGNATURE_ISSUES,
+    MAX_DOCSTRING_FALLBACK_BRANCH_ISSUES,
     MAX_DOCSTRING_FORMAT_ISSUES,
 )
 from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
@@ -306,3 +310,155 @@ def check_docstring_args_match_signature(content: str, file_path: str) -> list[s
             if len(issues) >= MAX_DOCSTRING_ARGS_SIGNATURE_ISSUES:
                 return issues[:MAX_DOCSTRING_ARGS_SIGNATURE_ISSUES]
     return issues[:MAX_DOCSTRING_ARGS_SIGNATURE_ISSUES]
+
+
+def _callee_expression_name(expression: ast.expr) -> str:
+    if isinstance(expression, ast.Name):
+        return expression.id
+    if isinstance(expression, ast.Attribute):
+        receiver_name = _callee_expression_name(expression.value)
+        if not receiver_name:
+            return ast.unparse(expression)
+        return f"{receiver_name}.{expression.attr}"
+    return ""
+
+
+def _call_callee_name(call_node: ast.Call) -> str:
+    return _callee_expression_name(call_node.func)
+
+
+def _branch_routes_directly_to_call(branch_node: ast.If) -> str:
+    """Return the callee name an early-return guard routes to, or empty string.
+
+    A guard counts when its block contains exactly one call expression and then
+    returns. A second call expression disqualifies the block; non-call
+    statements such as an assignment or a loop are skipped and do not
+    disqualify it. The await wrapper around an async call is unwrapped first.
+    """
+    routed_callee = ""
+    saw_return = False
+    for each_statement in branch_node.body:
+        candidate_expression: ast.expr | None = None
+        if isinstance(each_statement, ast.Expr):
+            candidate_expression = each_statement.value
+        elif isinstance(each_statement, ast.Return):
+            saw_return = True
+            continue
+        if candidate_expression is None:
+            continue
+        if isinstance(candidate_expression, ast.Await):
+            candidate_expression = candidate_expression.value
+        if not isinstance(candidate_expression, ast.Call):
+            return ""
+        if routed_callee:
+            return ""
+        routed_callee = _call_callee_name(candidate_expression)
+    if not saw_return:
+        return ""
+    return routed_callee
+
+
+def _shared_fallback_route_count(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> tuple[str, int]:
+    route_count_by_callee: dict[str, int] = {}
+    for each_statement in function_node.body:
+        if not isinstance(each_statement, ast.If):
+            continue
+        routed_callee = _branch_routes_directly_to_call(each_statement)
+        if not routed_callee:
+            continue
+        route_count_by_callee[routed_callee] = (
+            route_count_by_callee.get(routed_callee, 0) + 1
+        )
+    if not route_count_by_callee:
+        return "", 0
+    busiest_callee = max(route_count_by_callee, key=lambda name: route_count_by_callee[name])
+    return busiest_callee, route_count_by_callee[busiest_callee]
+
+
+def _summary_contains_phrase_at_word_boundary(summary_text: str, phrase: str) -> bool:
+    search_start = 0
+    while True:
+        match_index = summary_text.find(phrase, search_start)
+        if match_index == -1:
+            return False
+        preceding_is_boundary = (
+            match_index == 0 or not summary_text[match_index - 1].isalnum()
+        )
+        following_index = match_index + len(phrase)
+        following_is_boundary = (
+            following_index >= len(summary_text)
+            or not summary_text[following_index].isalnum()
+        )
+        if preceding_is_boundary and following_is_boundary:
+            return True
+        search_start = match_index + 1
+
+
+def _summary_joins_multiple_conditions(summary_text: str) -> bool:
+    return any(
+        joining_phrase in summary_text
+        for joining_phrase in ALL_DOCSTRING_MULTIPLE_CONDITION_JOINING_PHRASES
+    )
+
+
+def _docstring_summary_scopes_a_single_condition(docstring_text: str) -> bool:
+    summary_text = docstring_text.split("\n\n", 1)[0].lower()
+    has_scope_phrase = any(
+        _summary_contains_phrase_at_word_boundary(summary_text, each_phrase)
+        for each_phrase in ALL_DOCSTRING_EXCLUSIVE_SCOPE_PHRASES
+    )
+    if not has_scope_phrase:
+        return False
+    return not _summary_joins_multiple_conditions(summary_text)
+
+
+def check_docstring_fallback_branch_coverage(content: str, file_path: str) -> list[str]:
+    """Flag a fallback docstring that scopes a branch the body reaches twice.
+
+    The drift this catches: a function whose summary describes a fallback
+    action under 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. The second guard fires under a condition the prose
+    never names, so the enumeration the reader trusts is incomplete. This is
+    the deterministic slice of Category O6 (docstring prose vs implementation
+    drift): a structural branch-count-versus-prose-condition mismatch.
+
+    Args:
+        content: The source text to inspect.
+        file_path: The path the source will be written to, used for exemptions.
+
+    Returns:
+        One issue per function whose fallback prose omits a second route to the
+        same call, capped at the module limit.
+    """
+    if is_test_file(file_path) or is_hook_infrastructure(file_path):
+        return []
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    issues: list[str] = []
+    for each_node in _walk_skipping_type_checking_blocks(parsed_tree):
+        if not isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if _function_has_exempt_decorator(each_node):
+            continue
+        docstring_text = _function_docstring_text(each_node)
+        if not docstring_text:
+            continue
+        if not _docstring_summary_scopes_a_single_condition(docstring_text):
+            continue
+        fallback_callee, route_count = _shared_fallback_route_count(each_node)
+        if route_count < DOCSTRING_FALLBACK_BRANCH_MINIMUM_ROUTE_COUNT:
+            continue
+        issues.append(
+            f"Line {each_node.lineno}: {each_node.name}() docstring scopes a fallback to "
+            f"one condition, but the body routes to {fallback_callee}() from {route_count} "
+            "distinct branches — enumerate every condition that reaches the fallback "
+            "(Category O6 docstring-vs-implementation drift)"
+        )
+        if len(issues) >= MAX_DOCSTRING_FALLBACK_BRANCH_ISSUES:
+            break
+    return issues[:MAX_DOCSTRING_FALLBACK_BRANCH_ISSUES]

package/hooks/blocking/code_rules_enforcer.py

@@ -66,6 +66,7 @@ from code_rules_dead_module_constant import (  # noqa: E402
 )
 from code_rules_docstrings import (  # noqa: E402
     check_docstring_args_match_signature,
+    check_docstring_fallback_branch_coverage,
     check_docstring_format,
 )
 from code_rules_duplicate_body import (  # noqa: E402
@@ -248,6 +249,7 @@ def validate_content(
         all_issues.extend(check_boundary_types(effective_content, file_path))
         all_issues.extend(check_docstring_format(effective_content, file_path))
         all_issues.extend(check_docstring_args_match_signature(effective_content, file_path))
+        all_issues.extend(check_docstring_fallback_branch_coverage(effective_content, file_path))
         all_issues.extend(
             check_boolean_naming(
                 effective_content,

package/hooks/blocking/test_code_rules_enforcer_docstring_fallback_branch.py

@@ -0,0 +1,398 @@
+"""Tests for check_docstring_fallback_branch_coverage — O6 fallback-branch drift.
+
+A function whose summary scopes a fallback to one condition while the body
+routes to that same fallback call from two or more distinct early-return guards
+hides the second condition from the reader. This is the deterministic slice of
+Category O6 (docstring prose vs implementation drift).
+"""
+
+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_docstring_fallback_branch_coverage(content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_docstring_fallback_branch_coverage(content, file_path)
+
+
+def validate_content(content: str, file_path: str, old_content: str) -> list[str]:
+    return code_rules_enforcer.validate_content(content, file_path, old_content)
+
+
+PRODUCTION_FILE_PATH = "/project/src/human_actions.py"
+TEST_FILE_PATH = "/project/src/test_human_actions.py"
+HOOK_INFRASTRUCTURE_PATH = "/home/user/.claude/hooks/blocking/example.py"
+
+
+def _drifted_scroll_method() -> str:
+    return (
+        "class HumanActions:\n"
+        "    async def _scroll_once_toward_target(\n"
+        "        self, all_container_screen_bounds: object\n"
+        "    ) -> None:\n"
+        '        """Drive one scrollbar pass, falling back to the keyboard when'
+        ' the bar has no geometry."""\n'
+        "        if all_container_screen_bounds is None:\n"
+        "            await self._activate_then_press_right_arrow(None)\n"
+        "            return\n"
+        "        if random.random() < wheel_scroll_config.keyboard_scroll_fallback_probability:\n"
+        "            await self._activate_then_press_right_arrow(all_container_screen_bounds)\n"
+        "            return\n"
+        "        await self._drive_scrollbar_gesture(all_container_screen_bounds)\n"
+    )
+
+
+def _enumerated_scroll_method() -> str:
+    return (
+        "class HumanActions:\n"
+        "    async def _scroll_once_toward_target(\n"
+        "        self, all_container_screen_bounds: object\n"
+        "    ) -> None:\n"
+        '        """Drive one scrollbar pass.\n'
+        "\n"
+        "        Route to the Right-Arrow keyboard burst either when the bar has\n"
+        "        no geometry or, on a random keyboard_scroll_fallback_probability\n"
+        "        fraction of passes, when geometry is available.\n"
+        '        """\n'
+        "        if all_container_screen_bounds is None:\n"
+        "            await self._activate_then_press_right_arrow(None)\n"
+        "            return\n"
+        "        if random.random() < wheel_scroll_config.keyboard_scroll_fallback_probability:\n"
+        "            await self._activate_then_press_right_arrow(all_container_screen_bounds)\n"
+        "            return\n"
+        "        await self._drive_scrollbar_gesture(all_container_screen_bounds)\n"
+    )
+
+
+def test_should_flag_two_branches_routing_to_one_scoped_fallback() -> None:
+    issues = check_docstring_fallback_branch_coverage(
+        _drifted_scroll_method(), PRODUCTION_FILE_PATH
+    )
+    assert any("_activate_then_press_right_arrow" in each for each in issues), (
+        f"Expected the second fallback route to be flagged, got: {issues!r}"
+    )
+    assert len(issues) == 1
+
+
+def test_should_report_the_route_count_in_the_message() -> None:
+    issues = check_docstring_fallback_branch_coverage(
+        _drifted_scroll_method(), PRODUCTION_FILE_PATH
+    )
+    assert any("2 distinct branches" in each for each in issues), (
+        f"Expected the branch count in the message, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_when_both_conditions_are_enumerated() -> None:
+    issues = check_docstring_fallback_branch_coverage(
+        _enumerated_scroll_method(), PRODUCTION_FILE_PATH
+    )
+    assert issues == [], (
+        f"A docstring that enumerates both routes must not be flagged, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_single_branch_fallback() -> None:
+    source = (
+        "def render(view: object) -> str:\n"
+        '    """Render the view, falling back to the empty string when absent."""\n'
+        "    if view is None:\n"
+        "        return ''\n"
+        "    return view.body\n"
+    )
+    issues = check_docstring_fallback_branch_coverage(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"One fallback route under one named condition is correct, got: {issues!r}"
+
+
+def test_should_not_flag_two_branches_to_different_callees() -> None:
+    source = (
+        "def dispatch(event: object) -> None:\n"
+        '    """Dispatch the event, falling back to the logger when unroutable."""\n'
+        "    if event is None:\n"
+        "        log_warning('empty')\n"
+        "        return\n"
+        "    if event.is_stale:\n"
+        "        drop_event(event)\n"
+        "        return\n"
+        "    route_event(event)\n"
+    )
+    issues = check_docstring_fallback_branch_coverage(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"Distinct callees per branch are not a shared-fallback drift, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_when_docstring_has_no_scope_phrase() -> None:
+    source = (
+        "def select(target: object) -> None:\n"
+        '    """Pick the first matching candidate from the registry."""\n'
+        "    if target is None:\n"
+        "        await _press(None)\n"
+        "        return\n"
+        "    if target.is_idle:\n"
+        "        await _press(target)\n"
+        "        return\n"
+        "    await _drive(target)\n"
+    )
+    issues = check_docstring_fallback_branch_coverage(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"No exclusive-scope phrase means no fallback claim to check, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_when_scope_phrase_is_a_substring_of_another_word() -> None:
+    source = (
+        "def refresh(cache: object) -> None:\n"
+        '    """Rebuild the cache; commonly when idle it reuses the warm copy."""\n'
+        "    if cache is None:\n"
+        "        rebuild_cache(None)\n"
+        "        return\n"
+        "    if cache.is_cold:\n"
+        "        rebuild_cache(cache)\n"
+        "        return\n"
+        "    serve_cache(cache)\n"
+    )
+    issues = check_docstring_fallback_branch_coverage(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        "'commonly when' must not match the 'only when' scope phrase as a bare "
+        f"substring, got: {issues!r}"
+    )
+
+
+def test_should_still_flag_word_boundary_scope_phrase() -> None:
+    source = (
+        "def refresh(cache: object) -> None:\n"
+        '    """Rebuild the cache only when it is invalid."""\n'
+        "    if cache is None:\n"
+        "        rebuild_cache(None)\n"
+        "        return\n"
+        "    if cache.is_cold:\n"
+        "        rebuild_cache(cache)\n"
+        "        return\n"
+        "    serve_cache(cache)\n"
+    )
+    issues = check_docstring_fallback_branch_coverage(source, PRODUCTION_FILE_PATH)
+    assert any("rebuild_cache" in each for each in issues), (
+        f"A genuine 'only when' scope phrase must still be flagged, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_when_summary_enumerates_both_conditions_inline() -> None:
+    source = (
+        "def scroll(bar: object) -> None:\n"
+        '    """Drive a scrollbar pass, falling back to the keyboard when the bar'
+        ' lacks geometry or on a random fraction of passes."""\n'
+        "    if bar is None:\n"
+        "        _keyboard(None)\n"
+        "        return\n"
+        "    if bar.is_random:\n"
+        "        _keyboard(bar)\n"
+        "        return\n"
+        "    _drive(bar)\n"
+    )
+    issues = check_docstring_fallback_branch_coverage(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        "A summary that enumerates both fallback conditions inline with 'or' is not "
+        f"a single-condition scope and must not be flagged, got: {issues!r}"
+    )
+
+
+def test_should_still_flag_single_condition_fallback_with_two_routes() -> None:
+    source = (
+        "def scroll(bar: object) -> None:\n"
+        '    """Drive a scrollbar pass, falling back to the keyboard when the bar'
+        ' lacks geometry."""\n'
+        "    if bar is None:\n"
+        "        _keyboard(None)\n"
+        "        return\n"
+        "    if bar.is_random:\n"
+        "        _keyboard(bar)\n"
+        "        return\n"
+        "    _drive(bar)\n"
+    )
+    issues = check_docstring_fallback_branch_coverage(source, PRODUCTION_FILE_PATH)
+    assert any("_keyboard" in each for each in issues), (
+        "A summary scoping the fallback to one named condition while two routes reach "
+        f"it must still be flagged, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_when_scope_phrase_is_a_left_anchored_prefix() -> None:
+    source = (
+        "def forward(packet: object) -> None:\n"
+        '    """Forward the packet; falls back toward the default sink when both'
+        ' checks miss."""\n'
+        "    if packet is None:\n"
+        "        send_to_sink(None)\n"
+        "        return\n"
+        "    if packet.is_stale:\n"
+        "        send_to_sink(packet)\n"
+        "        return\n"
+        "    deliver(packet)\n"
+    )
+    issues = check_docstring_fallback_branch_coverage(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        "'falls back toward' must not match the 'falls back to' scope phrase as a "
+        f"left-anchored prefix, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_only_whenever_left_anchored_prefix() -> None:
+    source = (
+        "def refresh(cache: object) -> None:\n"
+        '    """Rebuild the cache only whenever it is invalid or stale."""\n'
+        "    if cache is None:\n"
+        "        rebuild_cache(None)\n"
+        "        return\n"
+        "    if cache.is_cold:\n"
+        "        rebuild_cache(cache)\n"
+        "        return\n"
+        "    serve_cache(cache)\n"
+    )
+    issues = check_docstring_fallback_branch_coverage(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        "'only whenever' must not match the 'only when' scope phrase as a "
+        f"left-anchored prefix, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_two_branches_to_same_method_on_distinct_indexed_receivers() -> None:
+    source = (
+        "class Pool:\n"
+        "    def shutdown(self, signal: object) -> None:\n"
+        '        """Close resources only when a shutdown signal arrives."""\n'
+        "        if signal is None:\n"
+        "            self.pool[0].close(signal)\n"
+        "            return\n"
+        "        if signal.is_secondary:\n"
+        "            self.pool[1].close(signal)\n"
+        "            return\n"
+        "        self.pool[2].drain(signal)\n"
+    )
+    issues = check_docstring_fallback_branch_coverage(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        "Distinct indexed receivers calling the same method name are different "
+        f"fallbacks, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_two_branches_to_same_named_method_on_distinct_receivers() -> None:
+    source = (
+        "class Closer:\n"
+        "    def shutdown(self, signal: object) -> None:\n"
+        '        """Close resources only when a shutdown signal arrives."""\n'
+        "        if signal is None:\n"
+        "            self.primary.close(signal)\n"
+        "            return\n"
+        "        if signal.is_secondary:\n"
+        "            self.secondary.close(signal)\n"
+        "            return\n"
+        "        self.tertiary.close(signal)\n"
+    )
+    issues = check_docstring_fallback_branch_coverage(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        "Distinct receivers calling the same method name are different fallbacks, "
+        f"got: {issues!r}"
+    )
+
+
+def test_should_flag_two_branches_to_same_method_on_one_receiver() -> None:
+    source = (
+        "class Closer:\n"
+        "    def shutdown(self, signal: object) -> None:\n"
+        '        """Close resources only when a shutdown signal arrives."""\n'
+        "        if signal is None:\n"
+        "            self.primary.close(signal)\n"
+        "            return\n"
+        "        if signal.is_secondary:\n"
+        "            self.primary.close(signal)\n"
+        "            return\n"
+        "        self.primary.drain(signal)\n"
+    )
+    issues = check_docstring_fallback_branch_coverage(source, PRODUCTION_FILE_PATH)
+    assert any("self.primary.close" in each for each in issues), (
+        f"Two routes to the same receiver.method must be flagged, got: {issues!r}"
+    )
+
+
+def test_should_flag_multi_statement_guard_with_one_call_before_return() -> None:
+    source = (
+        "def select(target: object) -> None:\n"
+        '    """Pick a candidate, falling back to the press action when idle."""\n'
+        "    if target is None:\n"
+        "        attempt = 1\n"
+        "        _press(None)\n"
+        "        return\n"
+        "    if target.is_idle:\n"
+        "        attempt = 1\n"
+        "        _press(target)\n"
+        "        return\n"
+        "    _drive(target)\n"
+    )
+    issues = check_docstring_fallback_branch_coverage(source, PRODUCTION_FILE_PATH)
+    assert any("_press" in each for each in issues), (
+        "A guard with a non-call statement before its single call still routes "
+        f"to that call, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_guard_with_a_second_call_expression() -> None:
+    source = (
+        "def select(target: object) -> None:\n"
+        '    """Pick a candidate, falling back to the press action when idle."""\n'
+        "    if target is None:\n"
+        "        _press(None)\n"
+        "        _press(None)\n"
+        "        return\n"
+        "    if target.is_idle:\n"
+        "        _press(target)\n"
+        "        _press(target)\n"
+        "        return\n"
+        "    _drive(target)\n"
+    )
+    issues = check_docstring_fallback_branch_coverage(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"A second call expression disqualifies the block as a route, got: {issues!r}"
+    )
+
+
+def test_should_skip_test_file() -> None:
+    issues = check_docstring_fallback_branch_coverage(_drifted_scroll_method(), TEST_FILE_PATH)
+    assert issues == [], f"Test files exempt, got: {issues!r}"
+
+
+def test_should_skip_hook_infrastructure() -> None:
+    issues = check_docstring_fallback_branch_coverage(
+        _drifted_scroll_method(), HOOK_INFRASTRUCTURE_PATH
+    )
+    assert issues == [], f"Hook infrastructure exempt, got: {issues!r}"
+
+
+def test_should_handle_syntax_error_gracefully() -> None:
+    issues = check_docstring_fallback_branch_coverage("def fetch(\n", PRODUCTION_FILE_PATH)
+    assert issues == [], f"Syntax error must yield no issues, got: {issues!r}"
+
+
+def test_validate_content_surfaces_fallback_branch_drift() -> None:
+    issues = validate_content(_drifted_scroll_method(), PRODUCTION_FILE_PATH, old_content="")
+    matching_issues = [
+        each for each in issues if "_activate_then_press_right_arrow" in each and "O6" in each
+    ]
+    assert matching_issues, (
+        f"Expected validate_content to surface the O6 fallback-branch drift, got: {issues!r}"
+    )

package/hooks/hooks_constants/blocking_check_limits.py

@@ -25,6 +25,22 @@ MAX_LOGGING_FSTRING_ISSUES: int = 3
 MAX_WINDOWS_API_NONE_ISSUES: int = 3
 MAX_E2E_TEST_NAMING_ISSUES: int = 3
 DOCSTRING_TRIVIAL_FUNCTION_BODY_LINE_LIMIT: int = 3
+MAX_DOCSTRING_FALLBACK_BRANCH_ISSUES: int = 3
+DOCSTRING_FALLBACK_BRANCH_MINIMUM_ROUTE_COUNT: int = 2
+
+ALL_DOCSTRING_EXCLUSIVE_SCOPE_PHRASES: tuple[str, ...] = (
+    "only when",
+    "only if",
+    "falls back to",
+    "falling back to",
+    "fall back to",
+)
+
+ALL_DOCSTRING_MULTIPLE_CONDITION_JOINING_PHRASES: tuple[str, ...] = (
+    " or ",
+    "either",
+    "both",
+)
 
 ALL_BARE_EXCEPT_BANNED_HANDLER_NAMES: frozenset[str] = frozenset({"Exception", "BaseException"})
 ALL_BOUNDARY_TYPE_EXEMPT_FILENAMES: frozenset[str] = frozenset({"protocols.py", "types.py"})

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.67.2",
+    "version": "1.68.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. Free-form prose — `"a field counts as read when ..."`, `"resolves to shared temp only"`, `"strip ceremony, then drop blockquotes"` — has no signature to compare against, so the gate cannot catch its drift. This rule is the judgment standard for that prose. It carries documented-but-pending hook coverage; the audit lane below is the enforcement until a deterministic gate check exists.
+The gate validator `check_docstring_args_match_signature` covers the `Args:` section parameter names. A second gate validator, `check_docstring_fallback_branch_coverage`, covers one deterministic slice of the free-form prose: 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. The remaining free-form prose — `"a field counts as read when ..."`, `"resolves to shared temp only"`, `"strip ceremony, then drop blockquotes"` — has no signature and no 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 two gated slices.
 
 ## What to check before you write the docstring
 
@@ -14,6 +14,7 @@ Read the body and the docstring side by side:
 
 - **Read-source / match-source unions.** A body that computes `read_names = a | b | c` (or any union of "what counts") names each union member in the prose enumeration. A union member the code applies but the prose omits is a gap.
 - **Suppressor / skip lists.** A body with several early returns that suppress the check names each suppressor in the prose.
+- **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.
 - **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.
 
@@ -36,7 +37,7 @@ A docstring that enumerates "attribute read, augmented-assignment target, class-
 
 ## Enforcement (audit lane)
 
-This drift class is sub-bucket **O6** in `packages/claude-dev-env/audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md` (free-form `Note:` / `Returns:` / responsibility-list claims). The audit teammate lists every prose enumeration in a changed docstring and verifies each item against the body, and lists every union member / suppressor / step in the body and verifies each appears in the prose. A union member or suppressor in the body that the prose omits is an O6 finding.
+This drift class is sub-bucket **O6** in `packages/claude-dev-env/audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md` (free-form `Note:` / `Returns:` / responsibility-list claims). The audit teammate lists every prose enumeration in a changed docstring and verifies each item against the body, and lists every union member / suppressor / step in the body and verifies each appears in the prose. A union member or suppressor in the body that the prose omits is an O6 finding. The single-condition shared-fallback shape of this drift is gated deterministically by `check_docstring_fallback_branch_coverage` (`packages/claude-dev-env/hooks/blocking/code_rules_docstrings.py`); the audit lane covers every O6 shape the gate cannot match.
 
 ## Why
 

package/skills/autoconverge/workflow/converge.fix-recovery.test.mjs

@@ -183,3 +183,138 @@ test('the round-loop fix-stalled blockers survive the recovery wiring', () => {
   assert.match(convergeSource, /fix lens landed no push for/);
   assert.match(convergeSource, /copilot fix lens landed no push for/);
 });
+
+const verifyObjectionModule = new Function(
+  `${constantLine('VERIFY_OBJECTION_FALLBACK')}\n` +
+    `${functionSource('renderVerifyObjectionLine')}\n` +
+    `${functionSource('extractVerifyObjection')}\n` +
+    'return { extractVerifyObjection, VERIFY_OBJECTION_FALLBACK };',
+)();
+
+const { extractVerifyObjection, VERIFY_OBJECTION_FALLBACK } = verifyObjectionModule;
+
+test('extractVerifyObjection falls back for a non-string transcript', () => {
+  assert.equal(extractVerifyObjection(null), VERIFY_OBJECTION_FALLBACK);
+});
+
+test('extractVerifyObjection falls back when no verdict fence is present', () => {
+  assert.equal(
+    extractVerifyObjection('the verifier wrote prose with no verdict fence'),
+    VERIFY_OBJECTION_FALLBACK,
+  );
+});
+
+test('extractVerifyObjection falls back when the verdict fence carries no findings', () => {
+  const transcript = '```verdict\n{"all_pass": false, "findings": []}\n```';
+  assert.equal(extractVerifyObjection(transcript), VERIFY_OBJECTION_FALLBACK);
+});
+
+test('extractVerifyObjection renders each verdict finding as check then detail', () => {
+  const transcript =
+    '```verdict\n{"all_pass": false, "findings": [{"check": "Finding 1", "detail": "still over-blocks"}, {"check": "Finding 2", "detail": "boundary unchecked"}]}\n```';
+  const objection = extractVerifyObjection(transcript);
+  assert.match(objection, /1\. Finding 1 — still over-blocks/);
+  assert.match(objection, /2\. Finding 2 — boundary unchecked/);
+});
+
+test('extractVerifyObjection reads the LAST verdict fence', () => {
+  const transcript =
+    '```verdict\n{"all_pass": false, "findings": [{"check": "stale", "detail": "old"}]}\n```\nretry\n```verdict\n{"all_pass": false, "findings": [{"check": "fresh", "detail": "new"}]}\n```';
+  const objection = extractVerifyObjection(transcript);
+  assert.match(objection, /fresh — new/);
+  assert.doesNotMatch(objection, /stale/);
+});
+
+test('extractVerifyObjection renders bare string findings as their text', () => {
+  const transcript =
+    '```verdict\n{"all_pass": false, "findings": ["boundary still over-blocks", "missing test for empty input"]}\n```';
+  const objection = extractVerifyObjection(transcript);
+  assert.match(objection, /1\. boundary still over-blocks/);
+  assert.match(objection, /2\. missing test for empty input/);
+  assert.doesNotMatch(objection, /unnamed check/);
+});
+
+test('extractVerifyObjection renders alternate-keyed objects (title, message, description, issue)', () => {
+  const transcript =
+    '```verdict\n{"all_pass": false, "findings": [{"title": "over-blocks", "detail": "boundary unchecked"}, {"message": "regex too broad"}, {"description": "no fallback path"}, {"issue": "stale fixture"}]}\n```';
+  const objection = extractVerifyObjection(transcript);
+  assert.match(objection, /over-blocks — boundary unchecked/);
+  assert.match(objection, /regex too broad/);
+  assert.match(objection, /no fallback path/);
+  assert.match(objection, /stale fixture/);
+  assert.doesNotMatch(objection, /unnamed check/);
+  assert.doesNotMatch(objection, /no detail/);
+});
+
+test('extractVerifyObjection renders mixed string and object findings', () => {
+  const transcript =
+    '```verdict\n{"all_pass": false, "findings": ["plain concern", {"check": "named", "detail": "explained"}]}\n```';
+  const objection = extractVerifyObjection(transcript);
+  assert.match(objection, /1\. plain concern/);
+  assert.match(objection, /2\. named — explained/);
+});
+
+test('extractVerifyObjection stringifies an object whose keys it does not recognize', () => {
+  const transcript = '```verdict\n{"all_pass": false, "findings": [{"severity": "P1", "line": 42}]}\n```';
+  const objection = extractVerifyObjection(transcript);
+  assert.match(objection, /severity/);
+  assert.match(objection, /42/);
+  assert.doesNotMatch(objection, /unnamed check/);
+});
+
+test('extractVerifyObjection falls back when no finding yields usable text', () => {
+  const transcript = '```verdict\n{"all_pass": false, "findings": [null, {}, ""]}\n```';
+  assert.equal(extractVerifyObjection(transcript), VERIFY_OBJECTION_FALLBACK);
+});
+
+test('recoverVerifyFailEdit is a clean-coder edit step bound to the verifier objection and leaves changes uncommitted', () => {
+  const recoverBody = functionSource('recoverVerifyFailEdit');
+  assert.match(recoverBody, /agentType:\s*'clean-coder'/, 'expected the fixer to use clean-coder');
+  assert.match(recoverBody, /schema:\s*EDIT_SCHEMA/, 'expected the fixer to reuse EDIT_SCHEMA');
+  assert.match(recoverBody, /label:\s*`fix-verify-recover:/, 'expected the fix-verify-recover label');
+  assert.match(recoverBody, /objection/, 'expected the fixer prompt to consume the verifier objection');
+  assert.match(
+    recoverBody,
+    /do not commit and do not push|Do NOT commit|leave .*uncommitted|uncommitted/i,
+    'expected the fixer to leave its fix uncommitted for the re-verify and retry commit',
+  );
+});
+
+test('verifyWithRecovery bounds the loop, re-fixes on a failed verdict, and re-verifies', () => {
+  const recoveryBody = functionSource('verifyWithRecovery');
+  assert.match(recoveryBody, /verdictPassed\(/, 'expected the loop guard to call verdictPassed');
+  assert.match(
+    recoveryBody,
+    /attempt\s*<\s*FIX_RECOVERY_MAX_ATTEMPTS/,
+    'expected the loop to be bounded by FIX_RECOVERY_MAX_ATTEMPTS',
+  );
+  assert.match(recoveryBody, /runRecoverEdit\(/, 'expected the loop to spawn the verify-recovery fixer');
+  assert.match(recoveryBody, /runVerify\(/, 'expected the loop to re-verify after the fixer edit');
+  assert.match(
+    recoveryBody,
+    /extractVerifyObjection\(/,
+    'expected the loop to feed the fixer the verifier objection',
+  );
+  const editGuardIndex = recoveryBody.search(/edited\s*!==\s*true/);
+  assert.notEqual(editGuardIndex, -1, 'expected an early break when the fixer made no edit');
+  const recoverEditIndex = recoveryBody.search(/runRecoverEdit\(/);
+  const reverifyIndex = recoveryBody.lastIndexOf('runVerify(');
+  assert.ok(recoverEditIndex < reverifyIndex, 'expected order recover-edit -> re-verify, so a swap fails');
+});
+
+test('applyFixes routes its verify through verifyWithRecovery before commitWithRecovery', () => {
+  const applyFixesBody = functionSource('applyFixes');
+  assert.match(applyFixesBody, /verifyWithRecovery\(/, 'expected applyFixes to call verifyWithRecovery');
+  assert.match(applyFixesBody, /runVerify:\s*\(\)\s*=>\s*verifyFixesInWorkingTree\(/);
+  assert.match(applyFixesBody, /runRecoverEdit:[\s\S]*?recoverVerifyFailEdit\(/);
+  const verifyIndex = applyFixesBody.search(/verifyWithRecovery\(/);
+  const commitIndex = applyFixesBody.search(/commitWithRecovery\(/);
+  assert.ok(verifyIndex < commitIndex, 'expected verify-recovery to precede commit-recovery');
+});
+
+test('repairConvergence routes its verify through verifyWithRecovery wired to the repair verify step', () => {
+  const repairBody = functionSource('repairConvergence');
+  assert.match(repairBody, /verifyWithRecovery\(/, 'expected repairConvergence to call verifyWithRecovery');
+  assert.match(repairBody, /runVerify:\s*\(\)\s*=>\s*verifyRepairChanges\(/);
+  assert.match(repairBody, /runRecoverEdit:[\s\S]*?recoverVerifyFailEdit\(/);
+});

package/skills/autoconverge/workflow/converge.mjs

@@ -406,6 +406,68 @@ function verdictPassed(verifyTranscript) {
   }
 }
 
+const VERIFY_OBJECTION_FALLBACK = 'The verify step rejected the working-tree fixes without a parseable verdict; re-read the fix-verify transcript above and address every concern it raised.'
+
+/**
+ * Render one verdict finding as a single objection line, tolerant of the shapes a
+ * verifier realistically emits: a bare string, an object keyed by any of
+ * check/title/message/description/issue for the headline and detail/description
+ * for the body, or any other object (stringified so its content survives). A
+ * headline and a detail render as "headline — detail"; a headline alone renders
+ * as the headline; an entry that yields no usable text returns null so the caller
+ * can fall back rather than emit a content-free placeholder.
+ * @param {unknown} eachFinding one entry from the verdict findings array
+ * @returns {string|null} the rendered objection line, or null when unusable
+ */
+function renderVerifyObjectionLine(eachFinding) {
+  if (typeof eachFinding === 'string') {
+    const trimmedFinding = eachFinding.trim()
+    return trimmedFinding.length > 0 ? trimmedFinding : null
+  }
+  if (eachFinding === null || typeof eachFinding !== 'object') return null
+  const headline =
+    eachFinding.check || eachFinding.title || eachFinding.message || eachFinding.description || eachFinding.issue
+  const detail = eachFinding.detail || (headline === eachFinding.description ? '' : eachFinding.description)
+  if (typeof headline === 'string' && headline.length > 0) {
+    return typeof detail === 'string' && detail.length > 0 ? `${headline} — ${detail}` : headline
+  }
+  const stringifiedFinding = JSON.stringify(eachFinding)
+  return stringifiedFinding === '{}' ? null : stringifiedFinding
+}
+
+/**
+ * Pull the verifier's stated objections out of a failed verify transcript so the
+ * re-fix step knows what the verdict rejected. Reads the last fenced verdict JSON
+ * (the same block verdictPassed reads) and renders each finding through
+ * renderVerifyObjectionLine into a numbered list. A missing fence, a parse
+ * failure, an empty findings list, or a findings list where no entry yields
+ * usable text falls back to a generic re-read instruction, so the re-fix step
+ * always receives actionable text.
+ * @param {string|null|undefined} verifyTranscript the failed verifier transcript text
+ * @returns {string} a human-readable block of the verifier's objections
+ */
+function extractVerifyObjection(verifyTranscript) {
+  if (typeof verifyTranscript !== 'string') return VERIFY_OBJECTION_FALLBACK
+  const fencePattern = /```verdict\s*\n([\s\S]*?)```/g
+  let lastFenceBody = null
+  let eachMatch
+  while ((eachMatch = fencePattern.exec(verifyTranscript)) !== null) {
+    lastFenceBody = eachMatch[1]
+  }
+  if (lastFenceBody === null) return VERIFY_OBJECTION_FALLBACK
+  try {
+    const verdictRecord = JSON.parse(lastFenceBody)
+    const allObjections = Array.isArray(verdictRecord?.findings) ? verdictRecord.findings : []
+    const renderedObjections = allObjections
+      .map((eachFinding) => renderVerifyObjectionLine(eachFinding))
+      .filter((eachLine) => eachLine !== null)
+    if (renderedObjections.length === 0) return VERIFY_OBJECTION_FALLBACK
+    return renderedObjections.map((eachLine, position) => `${position + 1}. ${eachLine}`).join('\n')
+  } catch {
+    return VERIFY_OBJECTION_FALLBACK
+  }
+}
+
 /**
  * Decide whether a fix lens actually advanced the round: a pushed fix that moved
  * HEAD progressed, and so did an all-stale round whose findings were every one
@@ -808,6 +870,32 @@ function recoverCommitBlockEdit(head, blockerDetail, sourceLabel, attempt) {
   )
 }
 
+/**
+ * Verify-recovery fixer: when the verify step rejects the working-tree fixes, one
+ * clean-coder re-fixes against the verdict's stated objections, test-first, and
+ * leaves the work uncommitted so the re-verify step can bind a fresh verdict. The
+ * objection text names which findings the verifier judged unresolved and why, so
+ * the fixer addresses those concerns; it does not touch GitHub review threads —
+ * the edit step already replied to and resolved those.
+ * @param {string} head PR HEAD SHA the fixes were raised against
+ * @param {string} objection the verifier's rendered objections from the failed verdict
+ * @param {string} sourceLabel short description of where the findings came from
+ * @param {number} attempt the 1-based recovery attempt number
+ * @returns {Promise<object>} EDIT_SCHEMA result
+ */
+function recoverVerifyFailEdit(head, objection, sourceLabel, attempt) {
+  return convergeAgent(
+    `You are the VERIFY-RECOVERY fixer (attempt ${attempt}) for fixes (${sourceLabel}) on ${prCoordinates}, HEAD ${head}. The verify step rejected the working-tree fixes; its verdict named what is still unresolved. A separate verify step then a separate commit step run after you.\n\n` +
+      `The verify step's objections:\n${objection}\n\n` +
+      `Rules:\n` +
+      `- Confirm the working tree is on the PR branch at HEAD ${head} with the prior fixes still present.\n` +
+      `- Address every objection above test-first (failing test, then minimum code to pass) per CODE_RULES, so each named concern is genuinely resolved the way the verdict requires. Do not touch GitHub review threads — the edit step already handled those.\n` +
+      `- Leave the corrected fixes in the working tree. Do NOT commit and do NOT push — the verify step re-binds a verdict and the commit step pushes after you.\n\n` +
+      `Return values: edited=true with a one-line summary when you changed code to address the objections; edited=false, resolvedWithoutCommit=false when the objections cannot be cleared with a code change.`,
+    { label: `fix-verify-recover:${sourceLabel}`, phase: 'Converge', schema: EDIT_SCHEMA, agentType: 'clean-coder' },
+  )
+}
+
 const FIX_RECOVERY_MAX_ATTEMPTS = 2
 
 /**
@@ -836,6 +924,29 @@ async function commitWithRecovery({ runCommit, runVerify, runRecoverEdit }) {
   return commitResult
 }
 
+/**
+ * Run the verify step and, when its verdict fails, route back to a fixer: re-fix
+ * against the verifier's objection, then re-verify — bounded by
+ * FIX_RECOVERY_MAX_ATTEMPTS. The loop breaks early when the fixer makes no edit,
+ * returning the last failed verify transcript so the caller's verdict-failed
+ * handling still applies; a verify that passes on any attempt returns its passing
+ * transcript so the caller proceeds to commit.
+ * @param {{runVerify: function, runRecoverEdit: function}} steps the verify and verify-recovery-edit thunks
+ * @returns {Promise<string>} the final verify transcript — passing, or the last failed one
+ */
+async function verifyWithRecovery({ runVerify, runRecoverEdit }) {
+  let verifyTranscript = await runVerify()
+  let attempt = 0
+  while (!verdictPassed(verifyTranscript) && attempt < FIX_RECOVERY_MAX_ATTEMPTS) {
+    attempt += 1
+    const objection = extractVerifyObjection(verifyTranscript)
+    const recoverEdit = await runRecoverEdit(objection, attempt)
+    if (recoverEdit?.edited !== true) break
+    verifyTranscript = await runVerify()
+  }
+  return verifyTranscript
+}
+
 /**
  * Fix lens: edit (clean-coder, no commit) -> verify (code-verifier emits a
  * verdict fence binding the working tree) -> commit (clean-coder, one commit +
@@ -862,7 +973,10 @@ async function applyFixes(head, findings, sourceLabel) {
       blockerDetail: '',
     }
   }
-  const verifyTranscript = await verifyFixesInWorkingTree(head, findings, sourceLabel)
+  const verifyTranscript = await verifyWithRecovery({
+    runVerify: () => verifyFixesInWorkingTree(head, findings, sourceLabel),
+    runRecoverEdit: (objection, attempt) => recoverVerifyFailEdit(head, objection, sourceLabel, attempt),
+  })
   if (!verdictPassed(verifyTranscript)) {
     return {
       newSha: head,
@@ -1099,7 +1213,10 @@ async function repairConvergence(head, failures) {
       blockerDetail: '',
     }
   }
-  const verifyTranscript = await verifyRepairChanges(head, failures)
+  const verifyTranscript = await verifyWithRecovery({
+    runVerify: () => verifyRepairChanges(head, failures),
+    runRecoverEdit: (objection, attempt) => recoverVerifyFailEdit(head, objection, 'repair', attempt),
+  })
   if (!verdictPassed(verifyTranscript)) {
     return {
       newSha: head,