claude-dev-env 1.82.0 → 1.84.0

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}"
+    )

package/hooks/blocking/test_code_rules_enforcer_docstring_prose_wall_illustration.py

@@ -0,0 +1,197 @@
+"""Behavioural checks for the show-don't-tell narrative gate.
+
+A readable summary earns its place by painting a concrete scene: a sample
+input, an annotated outcome, an OK/FLAG contrast a reader pictures at once. A
+summary that runs many short sentences with no worked example tells without
+showing. The gate flags that wall in a top-level, class, or callable summary,
+and stays quiet the moment the narrative carries a '::' listing or a '>>>'
+doctest.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+from types import ModuleType
+
+_HOOKS_DIRECTORY = str(Path(__file__).resolve().parent.parent)
+if _HOOKS_DIRECTORY not in sys.path:
+    sys.path.insert(0, _HOOKS_DIRECTORY)
+
+
+def _load_enforcer_module() -> ModuleType:
+    enforcer_module_name = "code_rules_enforcer"
+    enforcer_path = Path(__file__).parent / (enforcer_module_name + ".py")
+    spec = importlib.util.spec_from_file_location(enforcer_module_name, enforcer_path)
+    assert spec is not None
+    assert spec.loader is not None
+    loaded_module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(loaded_module)
+    return loaded_module
+
+
+code_rules_enforcer = _load_enforcer_module()
+
+
+def check_docstring_prose_wall_without_illustration(content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_docstring_prose_wall_without_illustration(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/tally.py"
+SUITE_FILE_PATH = "/project/src/test_tally.py"
+INFRA_PATH = "/home/user/.claude/hooks/blocking/example.py"
+
+
+def _fixture_top_level_wall() -> str:
+    return (
+        '"""Assemble the nightly voyage tally from the harbor scans.\n'
+        "\n"
+        "A scan names one vessel and where it dropped anchor.\n"
+        "The tally walks the scans in arrival order and keeps that order.\n"
+        "A calm voyage ends well for every vessel it carried.\n"
+        "A halted voyage marks the vessel it was near when the storm arrived.\n"
+        "A wrecked voyage marks the vessel that sank and stops the walk there.\n"
+        "The tally groups the vessels by their final port for the harbor.\n"
+        "The harbor reads the tally and sees every arrival at a glance.\n"
+        '"""\n'
+        "\n"
+        "def emit_tally() -> None:\n"
+        "    return None\n"
+    )
+
+
+def _fixture_callable_wall() -> str:
+    return (
+        "def emit_tally() -> None:\n"
+        '    """Post the voyage tally to the harbor board.\n'
+        "\n"
+        "    A scan names one vessel and where it dropped anchor.\n"
+        "    The tally walks the scans in arrival order and keeps that order.\n"
+        "    A calm voyage ends well for every vessel it carried.\n"
+        "    A halted voyage marks the vessel it was near when the storm arrived.\n"
+        "    A wrecked voyage marks the vessel that sank and stops the walk there.\n"
+        "    The tally groups the vessels by their final port for the reader.\n"
+        "    The reader reads the whole tally at a single glance.\n"
+        '    """\n'
+        "    return None\n"
+    )
+
+
+def _fixture_wall_with_listing() -> str:
+    return (
+        "def emit_tally() -> None:\n"
+        '    """Post the voyage tally to the harbor board.\n'
+        "\n"
+        "    A scan names one vessel and where it dropped anchor::\n"
+        "\n"
+        "        vessel 42 -- halted -> marked mid-voyage\n"
+        "        OK:   a calm voyage ends well for every vessel\n"
+        "        FLAG: a wrecked voyage reads the same as a calm one\n"
+        "\n"
+        "    The reader reads the whole tally at a single glance.\n"
+        '    """\n'
+        "    return None\n"
+    )
+
+
+def _fixture_wall_with_doctest() -> str:
+    return (
+        "def emit_tally() -> None:\n"
+        '    """Post the voyage tally to the harbor board.\n'
+        "\n"
+        "    A calm voyage ends well for every vessel it carried.\n"
+        "    A halted voyage marks the vessel it was near when the storm arrived.\n"
+        "    A wrecked voyage marks the vessel that sank and stops the walk there.\n"
+        "\n"
+        "    >>> emit_tally()\n"
+        "    vessel 42 halted\n"
+        "    vessel 43 calm\n"
+        "\n"
+        "    The reader reads the whole tally at a single glance.\n"
+        '    """\n'
+        "    return None\n"
+    )
+
+
+def _fixture_short_summary() -> str:
+    return (
+        "def emit_tally() -> None:\n"
+        '    """Post the voyage tally to the harbor board.\n'
+        "\n"
+        "    A scan names one vessel and where it dropped anchor.\n"
+        "    A calm voyage ends well for every vessel it carried.\n"
+        "    A halted voyage marks the vessel it was near when it stopped.\n"
+        "    The reader reads the whole tally at a single glance.\n"
+        '    """\n'
+        "    return None\n"
+    )
+
+
+def test_should_flag_prose_wall_with_no_illustration() -> None:
+    issues = check_docstring_prose_wall_without_illustration(
+        _fixture_top_level_wall(), PRODUCTION_FILE_PATH
+    )
+    assert any("worked example" in each for each in issues), (
+        f"A top-level wall must flag, got: {issues!r}"
+    )
+    assert any("module" in each for each in issues)
+    assert len(issues) == 1
+
+
+def test_should_flag_function_prose_wall() -> None:
+    issues = check_docstring_prose_wall_without_illustration(
+        _fixture_callable_wall(), PRODUCTION_FILE_PATH
+    )
+    assert any("emit_tally" in each for each in issues), (
+        f"A callable wall must flag, got: {issues!r}"
+    )
+    assert len(issues) == 1
+
+
+def test_should_not_flag_wall_with_literal_block() -> None:
+    issues = check_docstring_prose_wall_without_illustration(
+        _fixture_wall_with_listing(), PRODUCTION_FILE_PATH
+    )
+    assert issues == [], f"A '::' listing must pass, got: {issues!r}"
+
+
+def test_should_not_flag_wall_with_doctest() -> None:
+    issues = check_docstring_prose_wall_without_illustration(
+        _fixture_wall_with_doctest(), PRODUCTION_FILE_PATH
+    )
+    assert issues == [], f"A '>>>' doctest must pass, got: {issues!r}"
+
+
+def test_should_not_flag_short_narrative() -> None:
+    issues = check_docstring_prose_wall_without_illustration(
+        _fixture_short_summary(), PRODUCTION_FILE_PATH
+    )
+    assert issues == [], f"A summary at the sentence limit must pass, got: {issues!r}"
+
+
+def test_should_skip_test_file() -> None:
+    issues = check_docstring_prose_wall_without_illustration(_fixture_top_level_wall(), SUITE_FILE_PATH)
+    assert issues == [], f"A suite path stays exempt, got: {issues!r}"
+
+
+def test_should_skip_hook_infrastructure() -> None:
+    issues = check_docstring_prose_wall_without_illustration(
+        _fixture_top_level_wall(), INFRA_PATH
+    )
+    assert issues == [], f"An infra path stays exempt, got: {issues!r}"
+
+
+def test_should_handle_syntax_error_gracefully() -> None:
+    issues = check_docstring_prose_wall_without_illustration("def broken(\n", PRODUCTION_FILE_PATH)
+    assert issues == [], f"A syntax error yields no issues, got: {issues!r}"
+
+
+def test_validate_content_surfaces_prose_wall() -> None:
+    issues = validate_content(_fixture_top_level_wall(), PRODUCTION_FILE_PATH, old_content="")
+    matching_issues = [each for each in issues if "worked example" in each]
+    assert matching_issues, f"validate_content must surface the wall, got: {issues!r}"

package/hooks/blocking/test_code_rules_enforcer_docstring_runon_sentence.py

@@ -252,6 +252,33 @@ def test_should_flag_spaced_double_hyphen_joiner() -> None:
     assert len(issues) == 1
 
 
+def _diagram_first_literal_block() -> str:
+    return (
+        "def emit_tally() -> None:\n"
+        '    """Post the voyage tally so the reader sees how the run ended.\n'
+        "\n"
+        "    A calm voyage versus a halted one::\n"
+        "\n"
+        "        vessel 42 -- halted -> marked mid-voyage while it sailed\n"
+        "        calm — every vessel it carried shows a clean recorded outcome\n"
+        "        OK:   a calm run and a sunk run read differently in the log\n"
+        "        FLAG: a sunk run looks identical to a calm finished run here\n"
+        "    The reader reads the final outcome at a glance.\n"
+        '    """\n'
+        "    return None\n"
+    )
+
+
+def test_should_not_flag_diagram_first_literal_block() -> None:
+    issues = check_docstring_runon_sentence(
+        _diagram_first_literal_block(), PRODUCTION_FILE_PATH
+    )
+    assert issues == [], (
+        "A '::' listing's arrow, em-dash, and OK/FLAG rows sit outside the "
+        f"narrative and must not inflate the run-on count, got: {issues!r}"
+    )
+
+
 def test_docstring_names_every_inspected_section_header() -> None:
     docstring = code_rules_enforcer.check_docstring_runon_sentence.__doc__
     assert docstring is not None

package/hooks/blocking/test_code_rules_enforcer_join_separator_magic.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from pathlib import Path
+import importlib.util
+
+ENFORCER_PATH = Path(__file__).resolve().parent / "code_rules_enforcer.py"
+specification = importlib.util.spec_from_file_location("code_rules_enforcer", ENFORCER_PATH)
+code_rules_enforcer = importlib.util.module_from_spec(specification)
+specification.loader.exec_module(code_rules_enforcer)
+
+PRODUCTION_FILE_PATH = "packages/app/services/foo.py"
+TEST_FILE_PATH = "packages/app/tests/test_foo.py"
+CONFIG_FILE_PATH = "packages/app/config/constants.py"
+
+
+def test_should_flag_literal_delimiter_join_separator_in_function_body() -> None:
+    source = (
+        "def render(all_paths: list) -> str:\n"
+        "    return ', '.join(str(each_path) for each_path in all_paths)\n"
+    )
+    issues = code_rules_enforcer.check_join_separator_string_magic(source, PRODUCTION_FILE_PATH)
+    assert any("join" in each_issue for each_issue in issues), (
+        f"Expected literal join separator flagged, got: {issues}"
+    )
+
+
+def test_should_not_flag_named_constant_join_separator() -> None:
+    source = (
+        "from config.constants import JOIN_DELIMITER\n"
+        "\n"
+        "def render(all_paths: list) -> str:\n"
+        "    return JOIN_DELIMITER.join(all_paths)\n"
+    )
+    issues = code_rules_enforcer.check_join_separator_string_magic(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Named constant separator must pass, got: {issues}"
+
+
+def test_should_not_flag_empty_string_join_concatenation() -> None:
+    source = "def concatenate(all_parts: list) -> str:\n    return ''.join(all_parts)\n"
+    issues = code_rules_enforcer.check_join_separator_string_magic(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"Empty-string join concatenation is idiomatic and must pass, got: {issues}"
+    )
+
+
+def test_should_skip_join_separator_in_test_files() -> None:
+    source = "def test_render() -> None:\n    assert ', '.join(['a', 'b']) == 'a, b'\n"
+    issues = code_rules_enforcer.check_join_separator_string_magic(source, TEST_FILE_PATH)
+    assert issues == [], f"Test files exempt, got: {issues}"
+
+
+def test_should_skip_join_separator_in_config_files() -> None:
+    source = "def build_message(all_names: list) -> str:\n    return ', '.join(all_names)\n"
+    issues = code_rules_enforcer.check_join_separator_string_magic(source, CONFIG_FILE_PATH)
+    assert issues == [], f"Config files exempt, got: {issues}"
+
+
+def test_should_report_join_separator_line_number() -> None:
+    source = (
+        "def render(all_paths: list) -> str:\n"
+        "    joined = '; '.join(all_paths)\n"
+        "    return joined\n"
+    )
+    issues = code_rules_enforcer.check_join_separator_string_magic(source, PRODUCTION_FILE_PATH)
+    assert any("Line 2" in each_issue for each_issue in issues), (
+        f"Expected line 2 reported, got: {issues}"
+    )