claude-dev-env 1.67.1 → 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.1",
+    "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/anthropic-plan/SKILL.md

@@ -7,6 +7,12 @@ description: Workflow-backed implementation planning that creates a deep repo-lo
 
 Create a source-grounded plan packet through the Claude Code Workflow runtime. The output is a repo-local `docs/plans/<slug>/` folder with context, spec, implementation, validation, and handoff docs. Stop before implementation.
 
+## Isolate first
+
+The workflow's background subagents write the packet into the working tree. A background session that has not isolated into a worktree cannot write a shared checkout — the background-isolation guard rejects the write. So put the session in a worktree before launching the workflow:
+
+If the working directory is not already inside a worktree — its path does not contain `.claude/worktrees/` — call `EnterWorktree` to create one. The session switches into the worktree, the packet is written under `docs/plans/<slug>/` there, and the build then proceeds in the same worktree. A session already inside a worktree skips this step.
+
 ## Launch
 
 Call the workflow with the user request and current working directory. The payload goes in `args` — the Workflow tool exposes `args` to the script as its global `args`, and substitutes the user's full request for `$ARGUMENTS`:

package/skills/anthropic-plan/test_skill_contract.py

@@ -31,7 +31,14 @@ def test_skill_no_longer_mentions_single_home_plan_file() -> None:
     skill_text = SKILL_PATH.read_text(encoding="utf-8")
 
     assert "~/.claude/plans/<slug>.md" not in skill_text
-    assert "single-file" not in skill_text.lower()
+    assert "single-file plan" not in skill_text.lower()
+
+
+def test_skill_isolates_into_a_worktree_before_launch() -> None:
+    skill_text = SKILL_PATH.read_text(encoding="utf-8")
+
+    assert "EnterWorktree" in skill_text
+    assert ".claude/worktrees/" in skill_text
 
 
 def test_skill_documents_self_healing_writes() -> None:

package/skills/anthropic-plan/workflow/plan-packet.contract.test.mjs

@@ -159,6 +159,24 @@ test('workflow runs the reuse audit after writing the packet', () => {
   assert.ok(writeIndex < reuseAuditIndex);
 });
 
+test('reuse audit prompt self-heals a blocked write by staging and copying into place', () => {
+  const reuseAuditPromptBody = functionBody('reuseAuditPrompt');
+  assert.match(reuseAuditPromptBody, /stag/i);
+  assert.match(reuseAuditPromptBody, /copy/i);
+  assert.match(reuseAuditPromptBody, /recover/i);
+});
+
+test('reuse audit schema carries the recovery signal', () => {
+  const reuseAuditSchemaBody = functionBody('reuseAuditSchema');
+  assert.match(reuseAuditSchemaBody, /recovered/);
+  assert.match(reuseAuditSchemaBody, /recoveryNote/);
+});
+
+test('workflow folds reuse-audit recovery into the top-level recovered signal', () => {
+  const runBody = functionBody('runPlanPacketWorkflow');
+  assert.match(runBody, /recordRecovery\(reuseAudit\)/);
+});
+
 test('workflow folds the reuse audit gate into the clean validation check', () => {
   const runBody = functionBody('runPlanPacketWorkflow');
   assert.match(runBody, /reuseAudit\.allJustified/);
@@ -188,6 +206,24 @@ test('visual html prompt names the template and the output file', () => {
   assert.match(visualHtmlPromptBody, /visual-plan\.html/);
 });
 
+test('visual html prompt self-heals a blocked write by staging and copying into place', () => {
+  const visualHtmlPromptBody = functionBody('visualHtmlPrompt');
+  assert.match(visualHtmlPromptBody, /stag/i);
+  assert.match(visualHtmlPromptBody, /copy/i);
+  assert.match(visualHtmlPromptBody, /recover/i);
+});
+
+test('visual html schema carries the recovery signal', () => {
+  const visualHtmlSchemaBody = functionBody('visualHtmlSchema');
+  assert.match(visualHtmlSchemaBody, /recovered/);
+  assert.match(visualHtmlSchemaBody, /recoveryNote/);
+});
+
+test('workflow folds visual-html recovery into the top-level recovered signal', () => {
+  const runBody = functionBody('runPlanPacketWorkflow');
+  assert.match(runBody, /recordRecovery\(visualHtml\)/);
+});
+
 test('workflow returns the visual html path', () => {
   const runBody = functionBody('runPlanPacketWorkflow');
   assert.match(runBody, /visualHtmlPath/);

package/skills/anthropic-plan/workflow/plan-packet.mjs

@@ -105,8 +105,10 @@ function reuseAuditSchema() {
         },
       },
       summary: { type: 'string' },
+      recovered: { type: 'boolean' },
+      recoveryNote: { type: 'string' },
     },
-    required: ['allJustified', 'findings', 'summary'],
+    required: ['allJustified', 'findings', 'summary', 'recovered', 'recoveryNote'],
   }
 }
 
@@ -118,8 +120,10 @@ function visualHtmlSchema() {
       htmlPath: { type: 'string' },
       sectionsBuilt: { type: 'array', items: { type: 'string' } },
       summary: { type: 'string' },
+      recovered: { type: 'boolean' },
+      recoveryNote: { type: 'string' },
     },
-    required: ['htmlPath', 'sectionsBuilt', 'summary'],
+    required: ['htmlPath', 'sectionsBuilt', 'summary', 'recovered', 'recoveryNote'],
   }
 }
 
@@ -252,7 +256,8 @@ function reuseAuditPrompt(packetPath) {
     `Read implementation/file-plan.md, spec/interfaces.md, implementation/tdd-plan.md, and spec/scope.md in the packet to enumerate every new file, public symbol, helper, and constant the build introduces.\n\n` +
     `For each item, search the codebase with grep, serena, or zoekt — repo-wide and specifically under shared_utils — for an existing implementation or near-equivalent behavior.\n\n` +
     `Assign exactly one verdict per item from: reused (an existing public helper is used), extract-to-shared (an equivalent exists but is not shared or public and should be extracted), new-justified (genuinely new, with the reason reuse or extract was rejected), config-local (a constant living in config/), or unjustified-reproduction (reproduces existing behavior that could be made public or extracted, with no recorded justification).\n\n` +
-    `Write validation/reuse-audit.md into the packet: a markdown table with columns Item, Kind, Verdict, Searched, Found, Decision, Evidence using real file:line evidence, plus a one-line summary of verdict counts. Write concrete content only — no angle-bracket placeholder tokens and no todo, tbd, or placeholder words.\n\n` +
+    `Write validation/reuse-audit.md into the packet with the Write tool: a markdown table with columns Item, Kind, Verdict, Searched, Found, Decision, Evidence using real file:line evidence, plus a one-line summary of verdict counts. Write concrete content only — no angle-bracket placeholder tokens and no todo, tbd, or placeholder words.\n\n` +
+    `If the Write tool is blocked by a worktree or isolation guard, recover automatically: write validation/reuse-audit.md under a writable temporary directory such as $CLAUDE_JOB_DIR/tmp/anthropic-plan/<slug>/validation with the Write tool (so the content checks still run), then copy it into the packet path with a filesystem copy (cp -r, Copy-Item, or equivalent). Set recovered=true with recoveryNote describing the staging path and copy; otherwise set recovered=false with an empty recoveryNote.\n\n` +
     `Return the structured object. Set allJustified=false when any finding has verdict unjustified-reproduction.`
   )
 }
@@ -266,7 +271,7 @@ function visualHtmlPrompt(packetPath) {
     `Write for the reviewer — a person reading the plan, not the computer that runs the code. State every label as what a step accomplishes, in plain language. Drop code symbols from the picture: no function names, selector strings, call traces, or snake_case test names in the visible diagram — those stay in the packet markdown for the build agent. Keep each touched file's repo-relative path, but dim it (the .rpath / .ap style) so it sits quietly beneath the human description.\n\n` +
     `Render the change (section 05) as edit-recipe step sequences, one recipe per touched file: a plain-language title for what the file accomplishes, the dimmed repo-relative path, then an ordered row of colored steps — reused (green), modified (violet), new (amber). Fold a trivial one-line change into the recipe it supports as an "Also adds" line rather than giving it its own card. Name each test by the behavior it proves, not its function name.\n\n` +
     `Surface validation/reuse-audit.md as a Reuse audit section with one verdict badge per item (reused, extract-to-shared, new-justified, config-local, unjustified-reproduction), each item titled in plain language with its file path dimmed.\n\n` +
-    `Write the result to ${packetPath}/visual-plan.html. Inline all CSS and JavaScript; make no network calls and reference no external assets, so the file opens offline. If the Write tool is blocked by a worktree or isolation guard, stage the file under $CLAUDE_JOB_DIR/tmp with the Write tool, then copy it to the packet path.\n\n` +
+    `Write the result to ${packetPath}/visual-plan.html. Inline all CSS and JavaScript; make no network calls and reference no external assets, so the file opens offline. If the Write tool is blocked by a worktree or isolation guard, recover automatically: stage the file under a writable temporary directory such as $CLAUDE_JOB_DIR/tmp/anthropic-plan/<slug> with the Write tool, then copy it to the packet path with a filesystem copy (cp -r, Copy-Item, or equivalent). Set recovered=true with recoveryNote describing the staging path and copy; otherwise set recovered=false with an empty recoveryNote.\n\n` +
     `Return htmlPath set to the written file path, sectionsBuilt listing the section names you included, and a one-line summary.`
   )
 }
@@ -360,6 +365,7 @@ async function runPlanPacketWorkflow(rawInput) {
     packetWrite = await writePacket(runInput, packetPath, discoverySummary)
     recordRecovery(packetWrite)
     reuseAudit = await runReuseAudit(packetPath)
+    recordRecovery(reuseAudit)
     deterministicValidation = await runDeterministicValidation(packetPath)
     semanticValidation = await runSemanticValidator(packetPath)
     const hasCleanValidation = () =>
@@ -374,6 +380,7 @@ async function runPlanPacketWorkflow(rawInput) {
       const repair = await repairPacket(packetPath, deterministicValidation, semanticValidation, reuseAudit)
       recordRecovery(repair)
       reuseAudit = await runReuseAudit(packetPath)
+      recordRecovery(reuseAudit)
       deterministicValidation = await runDeterministicValidation(packetPath)
       semanticValidation = await runSemanticValidator(packetPath)
     }
@@ -381,6 +388,7 @@ async function runPlanPacketWorkflow(rawInput) {
     const passed = hasCleanValidation()
     try {
       const visualHtml = await runVisualHtml(packetPath)
+      recordRecovery(visualHtml)
       visualHtmlPath = visualHtml?.htmlPath || ''
     } catch (visualHtmlError) {
       visualHtmlFindings.push(String(visualHtmlError?.message || visualHtmlError))

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,