claude-dev-env 1.82.0 → 1.83.0

package/hooks/blocking/state_description_blocker.py

@@ -1,11 +1,14 @@
 #!/usr/bin/env python3
-"""PreToolUse hook: blocks Write/Edit containing historical/comparative language in comments and .md files.
+"""PreToolUse hook: blocks Write/Edit containing historical/comparative language in comments, Python docstrings, and .md files.
 
 Enforces the "describe current state only" rule — no "instead of", "previously",
-"now uses", or similar transitional framing. Comments and documentation should
-describe what IS, not what WAS or what CHANGED.
+"now uses", or similar transitional framing. Comments, docstrings, and
+documentation should describe what IS, not what WAS or what CHANGED. Inside a
+docstring, a phrase wrapped in double quotes or backticks is a mention rather
+than a use, so quoted spans are stripped before the scan.
 """
 
+import ast
 import json
 import os
 import sys
@@ -23,11 +26,15 @@ from hooks_constants.state_description_blocker_constants import (  # noqa: E402
     ALL_BLOCK_COMMENT_ONLY_EXTENSIONS,
     ALL_COMMENT_BEARING_EXTENSIONS,
     ALL_COMMENT_TRANSITION_PATTERNS,
+    ALL_DEFINITION_HEADER_PREFIXES,
     ALL_HASH_AND_SLASH_EXTENSIONS,
     ALL_HASH_ONLY_EXTENSIONS,
     ALL_MARKDOWN_EXTENSIONS,
     CODE_FENCE_PATTERN,
+    DOUBLE_QUOTED_SPAN_PATTERN,
     INLINE_CODE_PATTERN,
+    PYTHON_EXTENSION,
+    TRIPLE_QUOTED_BLOCK_PATTERN,
 )
 
 
@@ -131,17 +138,101 @@ def _find_inline_comment_start(stripped: str, all_markers: tuple[str, ...]) -> i
     return best_position
 
 
+def _extract_parsed_docstrings(tree: ast.Module) -> list[str]:
+    """Collect the module, class, and function docstrings from a parsed tree.
+
+    Args:
+        tree: The parsed module tree to walk.
+
+    Returns:
+        Every docstring found on the module and its class/function definitions.
+    """
+    all_found_docstrings: list[str] = []
+    for each_node in ast.walk(tree):
+        if not isinstance(
+            each_node, (ast.Module, ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)
+        ):
+            continue
+        maybe_docstring = ast.get_docstring(each_node, clean=False)
+        if maybe_docstring:
+            all_found_docstrings.append(maybe_docstring)
+    return all_found_docstrings
+
+
+def _extract_fragment_docstrings(text: str) -> list[str]:
+    """Collect docstring-positioned triple-quoted blocks from an unparseable fragment.
+
+    A triple-quoted block counts as a docstring when it opens the fragment
+    (only whitespace before it) or when the nearest preceding non-blank line is
+    a def/class header ending in a colon. A block assigned to a name or sitting
+    elsewhere in the fragment is data and is skipped.
+
+    Args:
+        text: The Python source fragment that failed to parse.
+
+    Returns:
+        The body text of each docstring-positioned triple-quoted block.
+    """
+    all_found_docstrings: list[str] = []
+    for each_match in TRIPLE_QUOTED_BLOCK_PATTERN.finditer(text):
+        body = each_match.group(1) if each_match.group(1) is not None else each_match.group(2)
+        leading_text = text[: each_match.start()]
+        if not leading_text.strip():
+            all_found_docstrings.append(body)
+            continue
+        if leading_text.rpartition("\n")[2].strip():
+            continue
+        all_preceding_lines = [
+            each_line for each_line in leading_text.splitlines() if each_line.strip()
+        ]
+        last_preceding_line = all_preceding_lines[-1].strip()
+        if last_preceding_line.startswith(
+            ALL_DEFINITION_HEADER_PREFIXES
+        ) and last_preceding_line.endswith(":"):
+            all_found_docstrings.append(body)
+    return all_found_docstrings
+
+
+def _extract_python_docstring_text(text: str) -> str:
+    """Return the scannable docstring prose from Python source.
+
+    Parses the source when valid, or falls back to the docstring-positioned
+    triple-quoted blocks of a mid-edit fragment. Double-quoted and backticked
+    spans inside each docstring are mentions rather than uses, so both are
+    stripped from the returned prose.
+
+    Args:
+        text: The Python source or fragment under scan.
+
+    Returns:
+        The docstring prose joined into one scannable string.
+    """
+    try:
+        all_found_docstrings = _extract_parsed_docstrings(ast.parse(text))
+    except (SyntaxError, ValueError):
+        all_found_docstrings = _extract_fragment_docstrings(text)
+    all_docstring_prose = [
+        DOUBLE_QUOTED_SPAN_PATTERN.sub("", INLINE_CODE_PATTERN.sub("", each_docstring))
+        for each_docstring in all_found_docstrings
+    ]
+    return "\n".join(all_docstring_prose)
+
+
 def find_violations(text: str, file_path: str) -> list[str]:
     """Return all violated patterns found in text for the given file.
 
-    For .md files, scans the entire text. For code files, scans only comment lines.
+    For .md files, scans the entire text. For code files, scans comment lines,
+    and for Python files also scans module/class/function docstrings.
     Returns a list of matched pattern source strings.
     """
+    extension = _get_file_extension(file_path)
     if is_markdown_file(file_path):
         scan_text = text
     elif is_comment_bearing_file(file_path):
-        all_comment_lines = _extract_comment_lines(text, _get_file_extension(file_path))
+        all_comment_lines = _extract_comment_lines(text, extension)
         scan_text = "\n".join(all_comment_lines)
+        if extension == PYTHON_EXTENSION:
+            scan_text = "\n".join([scan_text, _extract_python_docstring_text(text)])
     else:
         return []
 

package/hooks/blocking/test_code_rules_config_duplicate_path_anchor.py

@@ -0,0 +1,132 @@
+"""Tests for check_config_duplicate_path_anchor.
+
+Directories come from ``tmp_path_factory.mktemp`` with a neutral name because
+the per-test ``tmp_path`` embeds the test function name, and that name would
+make the test-path exemption inside the validator swallow every case.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+from types import ModuleType
+
+import pytest
+
+ENFORCER_FILENAME = "code_rules_enforcer.py"
+ENFORCER_MODULE_NAME = "code_rules_enforcer_duplicate_anchor_tests"
+SIBLING_MODULE_SOURCE = """\
+from pathlib import Path
+
+NEON_SUBMISSION_LOG_DIRECTORY = Path(__file__).resolve().parents[2] / "logs" / "theme_submissions"
+"""
+WRITTEN_MODULE_SOURCE = """\
+from pathlib import Path
+
+LOG_BASE_DIR = Path(__file__).resolve().parents[2] / "logs"
+THEME_SUBMISSIONS_LOG_FOLDER = "theme_submissions"
+"""
+
+
+def load_enforcer_module() -> ModuleType:
+    loader_path = Path(__file__).parent / ENFORCER_FILENAME
+    module_spec = importlib.util.spec_from_file_location(ENFORCER_MODULE_NAME, loader_path)
+    assert module_spec is not None
+    assert module_spec.loader is not None
+    loaded_module = importlib.util.module_from_spec(module_spec)
+    module_spec.loader.exec_module(loaded_module)
+    return loaded_module
+
+
+enforcer = load_enforcer_module()
+
+
+def _config_directory_with_sibling(
+    tmp_path_factory: pytest.TempPathFactory, sibling_source: str
+) -> Path:
+    config_directory = tmp_path_factory.mktemp("workspace_home") / "config"
+    config_directory.mkdir()
+    (config_directory / "neon_submission.py").write_text(sibling_source, encoding="utf-8")
+    return config_directory
+
+
+def test_should_flag_reanchored_base_already_built_by_sibling(
+    tmp_path_factory: pytest.TempPathFactory,
+) -> None:
+    config_directory = _config_directory_with_sibling(tmp_path_factory, SIBLING_MODULE_SOURCE)
+    written_path = str(config_directory / "derived_paths.py")
+    issues = enforcer.check_config_duplicate_path_anchor(WRITTEN_MODULE_SOURCE, written_path)
+    assert len(issues) == 1
+    assert "neon_submission.py" in issues[0]
+
+
+def test_should_flag_parent_chain_anchor_matching_sibling_parents_index(
+    tmp_path_factory: pytest.TempPathFactory,
+) -> None:
+    config_directory = _config_directory_with_sibling(tmp_path_factory, SIBLING_MODULE_SOURCE)
+    written_source = """\
+from pathlib import Path
+
+LOG_BASE_DIR = Path(__file__).resolve().parent.parent.parent / "logs"
+"""
+    written_path = str(config_directory / "derived_paths.py")
+    issues = enforcer.check_config_duplicate_path_anchor(written_source, written_path)
+    assert len(issues) == 1
+
+
+def test_should_allow_anchor_with_different_first_segment(
+    tmp_path_factory: pytest.TempPathFactory,
+) -> None:
+    config_directory = _config_directory_with_sibling(tmp_path_factory, SIBLING_MODULE_SOURCE)
+    written_source = """\
+from pathlib import Path
+
+SNAPSHOT_BASE_DIR = Path(__file__).resolve().parents[2] / "snapshots"
+"""
+    written_path = str(config_directory / "derived_paths.py")
+    issues = enforcer.check_config_duplicate_path_anchor(written_source, written_path)
+    assert issues == []
+
+
+def test_should_allow_anchor_with_different_depth(
+    tmp_path_factory: pytest.TempPathFactory,
+) -> None:
+    config_directory = _config_directory_with_sibling(tmp_path_factory, SIBLING_MODULE_SOURCE)
+    written_source = """\
+from pathlib import Path
+
+LOG_BASE_DIR = Path(__file__).resolve().parents[3] / "logs"
+"""
+    written_path = str(config_directory / "derived_paths.py")
+    issues = enforcer.check_config_duplicate_path_anchor(written_source, written_path)
+    assert issues == []
+
+
+def test_should_allow_module_with_no_sibling_config_files(
+    tmp_path_factory: pytest.TempPathFactory,
+) -> None:
+    config_directory = tmp_path_factory.mktemp("workspace_home") / "config"
+    config_directory.mkdir()
+    written_path = str(config_directory / "derived_paths.py")
+    issues = enforcer.check_config_duplicate_path_anchor(WRITTEN_MODULE_SOURCE, written_path)
+    assert issues == []
+
+
+def test_should_skip_modules_outside_config_directories(
+    tmp_path_factory: pytest.TempPathFactory,
+) -> None:
+    plain_directory = tmp_path_factory.mktemp("workspace_home") / "services"
+    plain_directory.mkdir()
+    (plain_directory / "neon_submission.py").write_text(SIBLING_MODULE_SOURCE, encoding="utf-8")
+    written_path = str(plain_directory / "derived_paths.py")
+    issues = enforcer.check_config_duplicate_path_anchor(WRITTEN_MODULE_SOURCE, written_path)
+    assert issues == []
+
+
+def test_should_skip_unparseable_sibling_modules(
+    tmp_path_factory: pytest.TempPathFactory,
+) -> None:
+    config_directory = _config_directory_with_sibling(tmp_path_factory, "def broken(:\n")
+    written_path = str(config_directory / "derived_paths.py")
+    issues = enforcer.check_config_duplicate_path_anchor(WRITTEN_MODULE_SOURCE, written_path)
+    assert issues == []

package/hooks/blocking/test_code_rules_enforcer_cap_meta.py

@@ -71,10 +71,12 @@ KNOWN_UNCAPPED_CHECKS_PENDING_REVIEW: frozenset[str] = frozenset(
         "check_file_global_constants_use_count",
         "check_imports_at_top",
         "check_inline_literal_collections",
+        "check_join_separator_string_magic",
         "check_known_pytest_fixture_annotations",
         "check_library_print",
         "check_loop_variable_naming",
         "check_parameter_annotations",
+        "check_referenced_underscore_loop_variable",
         "check_return_annotations",
         "check_skip_decorators_in_tests",
         "check_string_literal_magic",

package/hooks/blocking/test_code_rules_enforcer_docstring_delegation_summary.py

@@ -0,0 +1,385 @@
+"""Tests for check_docstring_delegation_summary_enumeration_drift (O6).
+
+A thin wrapper docstring that enumerates its actions and points at the home
+of the real body drifts when the same-named function in that named neighbor
+carries a summary enumeration omitting one of those actions. The gate fires
+from both sides: saving the wrapper compares it against the named neighbor on
+disk, and saving the delegated body compares it against every neighboring
+wrapper docstring pointing at it.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+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_delegation_summary_enumeration_drift(
+    content: str, file_path: str
+) -> list[str]:
+    return code_rules_enforcer.check_docstring_delegation_summary_enumeration_drift(
+        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)
+
+
+HOOK_INFRASTRUCTURE_PATH = "/home/user/.claude/hooks/blocking/example.py"
+TARGET_FLOW_STEM = "listing_edit_flow"
+PROCESSOR_FILE_NAME = "portal_processor.py"
+
+
+def _drifted_processor_source() -> str:
+    return (
+        "class PortalProcessor:\n"
+        "    async def _refresh_store_sections(self, page: object) -> bool:\n"
+        '        """Apply App Info, Russia, review note, publication edits;'
+        " full doc on ``listing_edit_flow``.\"\"\"\n"
+        "        return await _refresh_store_sections(self, page)\n"
+    )
+
+
+def _matching_processor_source() -> str:
+    return (
+        "class PortalProcessor:\n"
+        "    async def _refresh_store_sections(self, page: object) -> bool:\n"
+        '        """Apply Russia, review note, publication edits;'
+        " full doc on ``listing_edit_flow``.\"\"\"\n"
+        "        return await _refresh_store_sections(self, page)\n"
+    )
+
+
+def _target_flow_source() -> str:
+    return (
+        "async def _refresh_store_sections(processor: object, page: object) -> bool:\n"
+        '    """Apply Russia uncheck, review note, and Publication edits.\n'
+        "\n"
+        "    The App Info edit runs earlier in the binary phase and never\n"
+        "    repeats here.\n"
+        '    """\n'
+        "    return True\n"
+    )
+
+
+def _target_flow_plain_summary() -> str:
+    return (
+        "async def _refresh_store_sections(processor: object, page: object) -> bool:\n"
+        '    """Drive one theme end to end."""\n'
+        "    return True\n"
+    )
+
+
+def _create_target_flow(directory: Path, source: str) -> Path:
+    created_path = directory / (TARGET_FLOW_STEM + ".py")
+    created_path.write_text(source, encoding="utf-8")
+    return created_path
+
+
+def test_should_flag_listed_action_absent_from_the_named_neighbor(tmp_path: Path) -> None:
+    _create_target_flow(tmp_path, _target_flow_source())
+    checked_path = str(tmp_path / PROCESSOR_FILE_NAME)
+    issues = check_docstring_delegation_summary_enumeration_drift(
+        _drifted_processor_source(), checked_path
+    )
+    assert any("App Info" in each for each in issues), (
+        f"Expected 'App Info' to be flagged, got: {issues!r}"
+    )
+
+
+def test_should_pass_matching_summaries(tmp_path: Path) -> None:
+    _create_target_flow(tmp_path, _target_flow_source())
+    checked_path = str(tmp_path / PROCESSOR_FILE_NAME)
+    issues = check_docstring_delegation_summary_enumeration_drift(
+        _matching_processor_source(), checked_path
+    )
+    assert issues == [], f"Aligned summaries pass, got: {issues!r}"
+
+
+def test_should_flag_saved_body_that_strands_a_pointing_neighbor(tmp_path: Path) -> None:
+    checked_path = tmp_path / PROCESSOR_FILE_NAME
+    checked_path.write_text(_drifted_processor_source(), encoding="utf-8")
+    created_path = str(tmp_path / (TARGET_FLOW_STEM + ".py"))
+    issues = check_docstring_delegation_summary_enumeration_drift(
+        _target_flow_source(), created_path
+    )
+    assert any(
+        "App Info" in each and PROCESSOR_FILE_NAME in each for each in issues
+    ), f"Expected the stranded caller to be flagged, got: {issues!r}"
+
+
+def test_should_pass_plain_one_purpose_summary(tmp_path: Path) -> None:
+    _create_target_flow(tmp_path, _target_flow_plain_summary())
+    checked_path = str(tmp_path / PROCESSOR_FILE_NAME)
+    issues = check_docstring_delegation_summary_enumeration_drift(
+        _drifted_processor_source(), checked_path
+    )
+    assert issues == [], (
+        f"A comma-free summary compares against nothing, got: {issues!r}"
+    )
+
+
+def test_should_pass_when_the_named_neighbor_does_not_exist(tmp_path: Path) -> None:
+    checked_path = str(tmp_path / PROCESSOR_FILE_NAME)
+    issues = check_docstring_delegation_summary_enumeration_drift(
+        _drifted_processor_source(), checked_path
+    )
+    assert issues == [], f"Nothing on disk to compare against, got: {issues!r}"
+
+
+def test_should_pass_single_listed_action(tmp_path: Path) -> None:
+    _create_target_flow(tmp_path, _target_flow_source())
+    solo_source = (
+        "class PortalProcessor:\n"
+        "    async def _refresh_store_sections(self, page: object) -> bool:\n"
+        '        """Apply the App Info edit;'
+        " full doc on ``listing_edit_flow``.\"\"\"\n"
+        "        return await _refresh_store_sections(self, page)\n"
+    )
+    checked_path = str(tmp_path / PROCESSOR_FILE_NAME)
+    issues = check_docstring_delegation_summary_enumeration_drift(
+        solo_source, checked_path
+    )
+    assert issues == [], f"A lone named action never fires, got: {issues!r}"
+
+
+def test_should_skip_strict_test_paths(tmp_path: Path) -> None:
+    _create_target_flow(tmp_path, _target_flow_source())
+    skipped_path = str(tmp_path / "test_portal_processor.py")
+    issues = check_docstring_delegation_summary_enumeration_drift(
+        _drifted_processor_source(), skipped_path
+    )
+    assert issues == [], f"Exempt, got: {issues!r}"
+
+
+def test_should_skip_hook_infrastructure() -> None:
+    issues = check_docstring_delegation_summary_enumeration_drift(
+        _drifted_processor_source(), HOOK_INFRASTRUCTURE_PATH
+    )
+    assert issues == [], f"Exempt, got: {issues!r}"
+
+
+def test_should_handle_syntax_error_gracefully(tmp_path: Path) -> None:
+    checked_path = str(tmp_path / PROCESSOR_FILE_NAME)
+    issues = check_docstring_delegation_summary_enumeration_drift(
+        "def fetch(\n", checked_path
+    )
+    assert issues == [], f"A syntax error yields no issues, got: {issues!r}"
+
+
+def test_should_handle_unparseable_neighbor(tmp_path: Path) -> None:
+    _create_target_flow(tmp_path, "def broken(\n")
+    checked_path = str(tmp_path / PROCESSOR_FILE_NAME)
+    issues = check_docstring_delegation_summary_enumeration_drift(
+        _drifted_processor_source(), checked_path
+    )
+    assert issues == [], f"Unparseable neighbors yield no issues, got: {issues!r}"
+
+
+def test_validate_content_surfaces_the_drift(tmp_path: Path) -> None:
+    _create_target_flow(tmp_path, _target_flow_source())
+    checked_path = str(tmp_path / PROCESSOR_FILE_NAME)
+    issues = validate_content(_drifted_processor_source(), checked_path, old_content="")
+    matching_issues = [each for each in issues if "App Info" in each and "O6" in each]
+    assert matching_issues, (
+        f"Expected validate_content to surface the O6 finding, got: {issues!r}"
+    )
+
+
+def _drifted_processor_source_with_wrapped_summary() -> str:
+    return (
+        "class PortalProcessor:\n"
+        "    async def _refresh_store_sections(self, page: object) -> bool:\n"
+        '        """Apply App Info, Russia, review note, publication\n'
+        " edits; full doc on ``listing_edit_flow``.\"\"\"\n"
+        "        return await _refresh_store_sections(self, page)\n"
+    )
+
+
+def test_should_flag_listed_action_when_the_summary_wraps_a_physical_line(
+    tmp_path: Path,
+) -> None:
+    _create_target_flow(tmp_path, _target_flow_source())
+    checked_path = str(tmp_path / PROCESSOR_FILE_NAME)
+    issues = check_docstring_delegation_summary_enumeration_drift(
+        _drifted_processor_source_with_wrapped_summary(), checked_path
+    )
+    assert any("App Info" in each for each in issues), (
+        f"A summary wrapped onto a second physical line still names 'App Info', "
+        f"got: {issues!r}"
+    )
+
+
+def _drifted_processor_source_with_capitalized_and_uneven_whitespace() -> str:
+    return (
+        "class PortalProcessor:\n"
+        "    async def _refresh_store_sections(self, page: object) -> bool:\n"
+        '        """Apply App Info, Russia, review note,  And  publication'
+        " edits; full doc on ``listing_edit_flow``.\"\"\"\n"
+        "        return await _refresh_store_sections(self, page)\n"
+    )
+
+
+def test_should_flag_listed_action_when_the_conjunction_is_capitalized_with_uneven_whitespace(
+    tmp_path: Path,
+) -> None:
+    _create_target_flow(tmp_path, _target_flow_source())
+    checked_path = str(tmp_path / PROCESSOR_FILE_NAME)
+    issues = check_docstring_delegation_summary_enumeration_drift(
+        _drifted_processor_source_with_capitalized_and_uneven_whitespace(), checked_path
+    )
+    assert any("App Info" in each for each in issues), (
+        f"A capitalized 'And' with uneven whitespace still splits into its own "
+        f"listed entry, got: {issues!r}"
+    )
+
+
+def _write_filler_neighbor_modules(directory: Path, filler_count: int) -> None:
+    for each_index in range(filler_count):
+        filler_path = directory / f"filler_module_{each_index:03d}.py"
+        filler_path.write_text("PLACEHOLDER_VALUE = 1\n", encoding="utf-8")
+
+
+def test_should_stop_scanning_neighbors_past_the_configured_limit(
+    tmp_path: Path,
+) -> None:
+    neighbor_scan_limit = sys.modules["code_rules_docstrings"].NEIGHBOR_SCAN_FILE_LIMIT
+    _write_filler_neighbor_modules(tmp_path, filler_count=neighbor_scan_limit + 5)
+    stranded_wrapper_path = tmp_path / "zzz_stranded_processor.py"
+    stranded_wrapper_path.write_text(_drifted_processor_source(), encoding="utf-8")
+    created_path = str(tmp_path / (TARGET_FLOW_STEM + ".py"))
+    issues = check_docstring_delegation_summary_enumeration_drift(
+        _target_flow_source(), created_path
+    )
+    assert issues == [], (
+        "The alphabetically-last wrapper sits past the neighbor scan limit, so "
+        f"the scan must stop before reaching it, got: {issues!r}"
+    )
+
+
+def test_should_still_flag_a_stranded_wrapper_within_the_scan_limit(
+    tmp_path: Path,
+) -> None:
+    neighbor_scan_limit = sys.modules["code_rules_docstrings"].NEIGHBOR_SCAN_FILE_LIMIT
+    stranded_wrapper_path = tmp_path / "aaa_stranded_processor.py"
+    stranded_wrapper_path.write_text(_drifted_processor_source(), encoding="utf-8")
+    _write_filler_neighbor_modules(tmp_path, filler_count=neighbor_scan_limit + 5)
+    created_path = str(tmp_path / (TARGET_FLOW_STEM + ".py"))
+    issues = check_docstring_delegation_summary_enumeration_drift(
+        _target_flow_source(), created_path
+    )
+    assert any(
+        "App Info" in each and "aaa_stranded_processor.py" in each for each in issues
+    ), (
+        "The alphabetically-first wrapper sits within the neighbor scan limit "
+        f"and stays flagged even with extra filler neighbors, got: {issues!r}"
+    )
+
+
+def _target_flow_source_with_nested_duplicate_name() -> str:
+    return (
+        "async def _refresh_store_sections(processor: object, page: object) -> bool:\n"
+        '    """Apply Russia uncheck, review note, and Publication edits.\n'
+        "\n"
+        "    The App Info edit runs earlier in the binary phase and never\n"
+        "    repeats here.\n"
+        '    """\n'
+        "    return True\n"
+        "\n"
+        "\n"
+        "def _outer_helper() -> bool:\n"
+        "    def _refresh_store_sections() -> bool:\n"
+        '        """A same-named nested helper that must not shadow the'
+        ' top-level entry."""\n'
+        "        return True\n"
+        "\n"
+        "    return _refresh_store_sections()\n"
+    )
+
+
+def test_should_not_let_a_nested_duplicate_name_hide_the_top_level_entry(
+    tmp_path: Path,
+) -> None:
+    _create_target_flow(tmp_path, _target_flow_source_with_nested_duplicate_name())
+    checked_path = str(tmp_path / PROCESSOR_FILE_NAME)
+    issues = check_docstring_delegation_summary_enumeration_drift(
+        _drifted_processor_source(), checked_path
+    )
+    assert any("App Info" in each for each in issues), (
+        "A nested helper sharing the top-level function's name must not "
+        f"delete the top-level entry from comparison, got: {issues!r}"
+    )
+
+
+def _processor_source_with_nested_pointer_wrapper() -> str:
+    return (
+        "class PortalProcessor:\n"
+        "    async def _refresh_store_sections(self, page: object) -> bool:\n"
+        '        """Drive one theme end to end."""\n'
+        "        return True\n"
+        "\n"
+        "    def _run_nested_helper(self) -> bool:\n"
+        "        async def _refresh_store_sections() -> bool:\n"
+        '            """Apply App Info, Russia, review note, publication'
+        ' edits; full doc on ``listing_edit_flow``.\"\"\"\n'
+        "            return True\n"
+        "        return True\n"
+    )
+
+
+def test_should_not_flag_a_nested_wrapper_pointing_at_a_delegate(
+    tmp_path: Path,
+) -> None:
+    _create_target_flow(tmp_path, _target_flow_source())
+    checked_path = str(tmp_path / PROCESSOR_FILE_NAME)
+    issues = check_docstring_delegation_summary_enumeration_drift(
+        _processor_source_with_nested_pointer_wrapper(), checked_path
+    )
+    assert issues == [], (
+        "A function-local wrapper is not a top-level function or class "
+        f"method, so it must never be compared, got: {issues!r}"
+    )
+
+
+def _neighbor_source_with_nested_pointer_wrapper() -> str:
+    return (
+        "def _run_nested_helper() -> bool:\n"
+        "    async def _refresh_store_sections() -> bool:\n"
+        '        """Apply App Info, Russia, review note, publication edits;'
+        ' full doc on ``listing_edit_flow``.\"\"\"\n'
+        "        return True\n"
+        "    return True\n"
+    )
+
+
+def test_should_not_flag_a_nested_neighbor_wrapper_as_a_stranded_caller(
+    tmp_path: Path,
+) -> None:
+    neighbor_path = tmp_path / "portal_helpers.py"
+    neighbor_path.write_text(
+        _neighbor_source_with_nested_pointer_wrapper(), encoding="utf-8"
+    )
+    created_path = str(tmp_path / (TARGET_FLOW_STEM + ".py"))
+    issues = check_docstring_delegation_summary_enumeration_drift(
+        _target_flow_source(), created_path
+    )
+    assert issues == [], (
+        "A function-local wrapper in a neighbor module is not a pointing "
+        f"caller, so it must never be treated as stranded, got: {issues!r}"
+    )