claude-dev-env 1.76.0 → 1.77.0

package/hooks/blocking/test_code_rules_enforcer_docstring_args_span_scope.py

@@ -0,0 +1,174 @@
+"""Tests for check_docstring_args_single_line_scope_vs_span — Category O6 drift.
+
+A docstring Args: entry that scopes a finding to one named line ("only when its
+block-anchor line is among the changed lines") while the body builds a range()
+span and routes it through a span-intersection scoper claims a narrower scope
+than the code applies. The body blocks when ANY line of the span is among the
+changed lines, so an edit touching a non-anchor line of the span still blocks —
+contradicting the single-line Args sentence. This is the deterministic slice of
+Category O6 (free-form docstring-vs-implementation drift) for an Args entry whose
+single-line scope claim disagrees with a span-intersection body.
+"""
+
+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_args_single_line_scope_vs_span(content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_docstring_args_single_line_scope_vs_span(content, file_path)
+
+
+PRODUCTION_FILE_PATH = "/project/scripts/check_import_block_sorted.py"
+TEST_FILE_PATH = "/project/scripts/test_check_import_block_sorted.py"
+HOOK_INFRASTRUCTURE_PATH = "/home/user/.claude/hooks/blocking/example.py"
+
+
+SPAN_SCOPING_BODY = (
+    "    span_range = range(line_number, block_end_line_number + 1)\n"
+    "    all_violations.append((span_range, message))\n"
+    "    return _scope_violations_to_changed_lines(\n"
+    "        all_violations, all_changed_lines, defer_scope_to_caller\n"
+    "    )\n"
+)
+
+
+def test_flags_anchor_line_scope_against_span_intersection_body() -> None:
+    content = (
+        "def check_import_block_sorted(\n"
+        "    content: str, file_path: str, all_changed_lines: set[int] | None\n"
+        ") -> list[str]:\n"
+        '    """Flag an unsorted import block scoped to the changed lines.\n'
+        "\n"
+        "    A finding is returned when any line in that block span is among\n"
+        "    all_changed_lines.\n"
+        "\n"
+        "    Args:\n"
+        "        content: The full file content the write would leave on disk.\n"
+        "        file_path: The destination path used to gate by extension.\n"
+        "        all_changed_lines: Post-edit line numbers the current edit touched, or\n"
+        "            None to treat the whole file as in scope. When provided, a finding\n"
+        "            blocks only when its block-anchor line is among the changed lines.\n"
+        "\n"
+        "    Returns:\n"
+        "        One issue string per detected finding.\n"
+        '    """\n' + SPAN_SCOPING_BODY
+    )
+    issues = check_docstring_args_single_line_scope_vs_span(content, PRODUCTION_FILE_PATH)
+    assert len(issues) == 1
+    assert "check_import_block_sorted" in issues[0]
+    assert "all_changed_lines" in issues[0]
+
+
+def test_flags_the_line_is_among_phrasing() -> None:
+    content = (
+        "def check_block(\n"
+        "    content: str, file_path: str, all_changed_lines: set[int] | None\n"
+        ") -> list[str]:\n"
+        '    """Flag an unsorted block scoped to the diff.\n'
+        "\n"
+        "    Args:\n"
+        "        content: The file content.\n"
+        "        all_changed_lines: When provided, a finding blocks only when the\n"
+        "            anchor line is among the changed lines.\n"
+        '    """\n' + SPAN_SCOPING_BODY
+    )
+    assert len(check_docstring_args_single_line_scope_vs_span(content, PRODUCTION_FILE_PATH)) == 1
+
+
+def test_passes_when_args_says_any_line_of_the_span() -> None:
+    content = (
+        "def check_import_block_sorted(\n"
+        "    content: str, file_path: str, all_changed_lines: set[int] | None\n"
+        ") -> list[str]:\n"
+        '    """Flag an unsorted import block scoped to the changed lines.\n'
+        "\n"
+        "    Args:\n"
+        "        content: The full file content.\n"
+        "        all_changed_lines: Post-edit line numbers the current edit touched, or\n"
+        "            None to treat the whole file as in scope. When provided, a finding\n"
+        "            blocks only when any line of its block span is among the changed lines.\n"
+        '    """\n' + SPAN_SCOPING_BODY
+    )
+    assert check_docstring_args_single_line_scope_vs_span(content, PRODUCTION_FILE_PATH) == []
+
+
+def test_passes_when_body_scopes_by_single_line_not_a_span() -> None:
+    content = (
+        "def check_one_line(\n"
+        "    content: str, file_path: str, all_changed_lines: set[int] | None\n"
+        ") -> list[str]:\n"
+        '    """Flag a violation on a single line scoped to the diff.\n'
+        "\n"
+        "    Args:\n"
+        "        content: The file content.\n"
+        "        all_changed_lines: When provided, a finding blocks only when its\n"
+        "            anchor line is among the changed lines.\n"
+        '    """\n'
+        "    if all_changed_lines is not None and line_number not in all_changed_lines:\n"
+        "        return []\n"
+        "    return [message]\n"
+    )
+    assert check_docstring_args_single_line_scope_vs_span(content, PRODUCTION_FILE_PATH) == []
+
+
+def test_passes_when_no_single_line_scope_phrase() -> None:
+    content = (
+        "def check_import_block_sorted(\n"
+        "    content: str, file_path: str, all_changed_lines: set[int] | None\n"
+        ") -> list[str]:\n"
+        '    """Flag an unsorted import block scoped to the changed lines.\n'
+        "\n"
+        "    Args:\n"
+        "        content: The full file content.\n"
+        "        all_changed_lines: Post-edit line numbers the current edit touched.\n"
+        '    """\n' + SPAN_SCOPING_BODY
+    )
+    assert check_docstring_args_single_line_scope_vs_span(content, PRODUCTION_FILE_PATH) == []
+
+
+def test_test_files_are_exempt() -> None:
+    content = (
+        "def check_import_block_sorted(\n"
+        "    content: str, file_path: str, all_changed_lines: set[int] | None\n"
+        ") -> list[str]:\n"
+        '    """Flag an unsorted import block.\n'
+        "\n"
+        "    Args:\n"
+        "        all_changed_lines: A finding blocks only when its anchor line is\n"
+        "            among the changed lines.\n"
+        '    """\n' + SPAN_SCOPING_BODY
+    )
+    assert check_docstring_args_single_line_scope_vs_span(content, TEST_FILE_PATH) == []
+
+
+def test_hook_infrastructure_is_not_exempt() -> None:
+    content = (
+        "def check_import_block_sorted(\n"
+        "    content: str, file_path: str, all_changed_lines: set[int] | None\n"
+        ") -> list[str]:\n"
+        '    """Flag an unsorted import block.\n'
+        "\n"
+        "    Args:\n"
+        "        all_changed_lines: A finding blocks only when its block-anchor line is\n"
+        "            among the changed lines.\n"
+        '    """\n' + SPAN_SCOPING_BODY
+    )
+    assert (
+        len(check_docstring_args_single_line_scope_vs_span(content, HOOK_INFRASTRUCTURE_PATH)) == 1
+    )

package/hooks/blocking/test_code_rules_enforcer_docstring_cardinal_family.py

@@ -0,0 +1,176 @@
+"""Tests for check_docstring_cardinal_count_matches_constant_family — O6 drift.
+
+A docstring states a cardinal count of an outcome family ("Covers the four
+outcome branches: ...") and enumerates the family members in prose, while the
+module references more members of that constant family than the count names. The
+prose under-describes the code: a reader trusts "four" and the list to be the
+full set, but the module imports and exercises a fifth outcome. This is the
+deterministic cardinal-count slice of Category O6 docstring-prose-vs-
+implementation drift, the shape that appears when a producer adds an outcome
+branch but leaves the test-module summary at the old count. The check runs on
+test files because the drift class lives in a test-module docstring.
+"""
+
+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_cardinal_count_matches_constant_family(
+    content: str, file_path: str
+) -> list[str]:
+    return code_rules_enforcer.check_docstring_cardinal_count_matches_constant_family(
+        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/dropdown_fix_rule.py"
+TEST_FILE_PATH = "/project/src/tests/test_dropdown_fix_rule.py"
+
+
+def _test_module(summary_line: str, enumeration_line: str) -> str:
+    return (
+        '"""Behavioral tests for classify_dropdown_fix.\n'
+        "\n"
+        f"{summary_line}\n"
+        f"{enumeration_line}\n"
+        '"""\n'
+        "\n"
+        "from stp_dropdown_color_fix.config.status_codes import (\n"
+        "    OUTCOME_ALREADY_OK,\n"
+        "    OUTCOME_OFFENDER_LOW_CONTRAST,\n"
+        "    OUTCOME_OFFENDER_MISSING,\n"
+        "    OUTCOME_OFFENDER_UNREADABLE,\n"
+        "    OUTCOME_SKIPPED_NO_SAFE_SOURCE,\n"
+        ")\n"
+        "\n"
+        "def test_skipped() -> None:\n"
+        "    assert classify() == OUTCOME_SKIPPED_NO_SAFE_SOURCE\n"
+        "\n"
+        "def test_missing() -> None:\n"
+        "    assert classify() == OUTCOME_OFFENDER_MISSING\n"
+        "\n"
+        "def test_low_contrast() -> None:\n"
+        "    assert classify() == OUTCOME_OFFENDER_LOW_CONTRAST\n"
+        "\n"
+        "def test_already_ok() -> None:\n"
+        "    assert classify() == OUTCOME_ALREADY_OK\n"
+        "\n"
+        "def test_unreadable() -> None:\n"
+        "    assert classify() == OUTCOME_OFFENDER_UNREADABLE\n"
+    )
+
+
+def _drifted_module() -> str:
+    return _test_module(
+        "Covers the four outcome branches: skipped_no_safe_source,",
+        "offender_missing (case A), offender_low_contrast (case B), already_ok.",
+    )
+
+
+def _matching_module() -> str:
+    return _test_module(
+        "Covers the five outcome branches: skipped_no_safe_source, offender_missing,",
+        "offender_low_contrast, already_ok, offender_unreadable.",
+    )
+
+
+def test_should_flag_test_module_omitting_an_outcome() -> None:
+    issues = check_docstring_cardinal_count_matches_constant_family(
+        _drifted_module(), TEST_FILE_PATH
+    )
+    assert any("offender_unreadable" in each for each in issues), (
+        "A test-module docstring claiming four outcome branches while the module "
+        f"references five OUTCOME_ constants must be flagged, got: {issues!r}"
+    )
+
+
+def test_should_report_category_o6_in_the_message() -> None:
+    issues = check_docstring_cardinal_count_matches_constant_family(
+        _drifted_module(), TEST_FILE_PATH
+    )
+    assert any("O6" in each for each in issues), (
+        f"Expected the Category O6 label in the message, got: {issues!r}"
+    )
+
+
+def test_should_also_flag_production_module() -> None:
+    issues = check_docstring_cardinal_count_matches_constant_family(
+        _drifted_module(), PRODUCTION_FILE_PATH
+    )
+    assert issues != [], (
+        f"The cardinal drift must be flagged on a production file too, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_when_count_and_enumeration_match_family() -> None:
+    issues = check_docstring_cardinal_count_matches_constant_family(
+        _matching_module(), TEST_FILE_PATH
+    )
+    assert issues == [], (
+        f"A docstring naming all five referenced outcomes must not be flagged, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_without_a_cardinal_phrase() -> None:
+    source = _test_module(
+        "Covers these outcome branches: skipped_no_safe_source,",
+        "offender_missing, offender_low_contrast, already_ok.",
+    )
+    issues = check_docstring_cardinal_count_matches_constant_family(source, TEST_FILE_PATH)
+    assert issues == [], (
+        f"An enumeration with no cardinal count word must not bind, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_single_passing_mention() -> None:
+    source = _test_module(
+        "Asserts the four guard paths reach already_ok when the dropdown is",
+        "absent and the dialer keeps its painted swatch.",
+    )
+    issues = check_docstring_cardinal_count_matches_constant_family(source, TEST_FILE_PATH)
+    assert issues == [], f"A single overlapping token must not bind the family, got: {issues!r}"
+
+
+def test_should_not_flag_when_family_has_one_referenced_member() -> None:
+    source = (
+        '"""Covers the four outcome branches: already_ok, more, words, here."""\n'
+        "from status_codes import OUTCOME_ALREADY_OK\n"
+        "\n"
+        "def test_only() -> None:\n"
+        "    assert classify() == OUTCOME_ALREADY_OK\n"
+    )
+    issues = check_docstring_cardinal_count_matches_constant_family(source, TEST_FILE_PATH)
+    assert issues == [], f"A family with one referenced member must not bind, got: {issues!r}"
+
+
+def test_should_handle_syntax_error_gracefully() -> None:
+    issues = check_docstring_cardinal_count_matches_constant_family("def fetch(\n", TEST_FILE_PATH)
+    assert issues == [], f"Syntax error must yield no issues, got: {issues!r}"
+
+
+def test_validate_content_surfaces_cardinal_family_drift() -> None:
+    issues = validate_content(_drifted_module(), TEST_FILE_PATH, old_content="")
+    matching_issues = [each for each in issues if "offender_unreadable" in each and "O6" in each]
+    assert matching_issues, (
+        f"Expected validate_content to surface the O6 cardinal-family drift, got: {issues!r}"
+    )

package/hooks/blocking/test_code_rules_enforcer_docstring_runon_sentence.py

@@ -0,0 +1,267 @@
+"""Tests for check_docstring_runon_sentence — the plain-illustrative-docstrings backstop.
+
+A readable docstring breaks its narrative into short sentences a general developer
+follows on first read. The one mechanical mark of a dense wall is a single run-on
+sentence: many words strung together with an em-dash or a semicolon. This check
+flags that mark in module, class, and public-function docstring narrative prose,
+and leaves the "is it illustrative" judgment to the audit lane.
+"""
+
+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)
+
+from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
+    ALL_DOCSTRING_ARGS_SECTION_HEADERS,
+    ALL_DOCSTRING_TERMINATING_SECTION_HEADERS,
+)
+
+
+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_runon_sentence(content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_docstring_runon_sentence(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/run_lifecycle.py"
+TEST_FILE_PATH = "/project/src/test_run_lifecycle.py"
+HOOK_INFRASTRUCTURE_PATH = "/home/user/.claude/hooks/blocking/example.py"
+
+
+def _run_lifecycle_module() -> str:
+    return (
+        '"""Generic run-lifecycle plumbing for the STP version promoter run.\n'
+        "\n"
+        "Owns the SIGINT install/restore/installability check, the atexit terminal-record\n"
+        "registration, and the interrupted-run finalizer — the non-promoter-specific\n"
+        "machinery that brackets a run so the JSONL artifact always carries a terminal\n"
+        "record and an in-flight theme record on interrupt.\n"
+        '"""\n'
+        "\n"
+        "def install_signal_handler() -> None:\n"
+        "    return None\n"
+    )
+
+
+def _approved_bar_module() -> str:
+    return (
+        '"""Make sure a run\'s log always records how it ended.\n'
+        "\n"
+        "So when you reopen the report, the last line tells you the truth: the run\n"
+        "finished cleanly, or you hit Ctrl-C while theme 42 was processing, or it died\n"
+        "on an unexpected error. Without this, a killed run looks identical to a clean\n"
+        "one — and you're debugging blind.\n"
+        '"""\n'
+        "\n"
+        "def describe_outcome() -> None:\n"
+        "    return None\n"
+    )
+
+
+def _class_docstring_runon() -> str:
+    return (
+        "class RunRecorder:\n"
+        '    """Owns the SIGINT install and restore step, the atexit record hook, and the\n'
+        "    interrupted-run finalizer — the plumbing that brackets a run so the artifact\n"
+        "    always carries a terminal record and an in-flight theme record on interrupt.\n"
+        '    """\n'
+        "\n"
+        "    def record(self) -> None:\n"
+        "        return None\n"
+    )
+
+
+def _normal_short_docstring() -> str:
+    return (
+        "def summarize_run() -> str:\n"
+        '    """Write the run summary.\n'
+        "\n"
+        "    Each line names one theme and its final outcome.\n"
+        '    """\n'
+        '    return ""\n'
+    )
+
+
+def _long_args_line_outside_narrative() -> str:
+    return (
+        "def configure_run(option_name: str) -> None:\n"
+        '    """Set one option for the run.\n'
+        "\n"
+        "    Args:\n"
+        "        option_name: the name of the option to set, described here in a needlessly\n"
+        "            long sentence that runs far past thirty words and even carries an\n"
+        "            em-dash — yet the check stays silent because every word here sits after\n"
+        "            the Args header and therefore outside the inspected narrative entirely.\n"
+        '    """\n'
+        "    return None\n"
+    )
+
+
+def _private_function_runon() -> str:
+    return (
+        "def _install_handlers() -> None:\n"
+        '    """Owns the SIGINT install and restore step, the atexit record hook, and the\n'
+        "    interrupted-run finalizer — the plumbing that brackets a run so the artifact\n"
+        "    always carries a terminal record and an in-flight theme record on interrupt.\n"
+        '    """\n'
+        "    return None\n"
+    )
+
+
+def _property_method_runon() -> str:
+    return (
+        "class Widget:\n"
+        "    @property\n"
+        "    def label(self) -> str:\n"
+        '        """Owns the SIGINT install and restore step, the atexit record hook, and the\n'
+        "        interrupted-run finalizer — the plumbing that brackets a run so the artifact\n"
+        "        always carries a terminal record and an in-flight theme record on interrupt.\n"
+        '        """\n'
+        '        return "label"\n'
+    )
+
+
+def test_should_flag_run_lifecycle_module_docstring_wall() -> None:
+    issues = check_docstring_runon_sentence(_run_lifecycle_module(), PRODUCTION_FILE_PATH)
+    assert any("run-on" in each for each in issues), (
+        f"Expected the module-docstring wall to flag, got: {issues!r}"
+    )
+    assert any("module" in each for each in issues)
+    assert len(issues) == 1
+
+
+def test_should_not_flag_approved_bar_module_docstring() -> None:
+    issues = check_docstring_runon_sentence(_approved_bar_module(), PRODUCTION_FILE_PATH)
+    assert issues == [], f"The approved bar must pass clean, got: {issues!r}"
+
+
+def test_should_flag_class_docstring_wall() -> None:
+    issues = check_docstring_runon_sentence(_class_docstring_runon(), PRODUCTION_FILE_PATH)
+    assert any("RunRecorder" in each for each in issues), (
+        f"Expected the class-docstring wall to flag, got: {issues!r}"
+    )
+    assert len(issues) == 1
+
+
+def test_should_not_flag_normal_short_docstring() -> None:
+    issues = check_docstring_runon_sentence(_normal_short_docstring(), PRODUCTION_FILE_PATH)
+    assert issues == [], f"A short multi-sentence docstring must not flag, got: {issues!r}"
+
+
+def test_should_not_flag_long_args_line_outside_narrative() -> None:
+    issues = check_docstring_runon_sentence(
+        _long_args_line_outside_narrative(), PRODUCTION_FILE_PATH
+    )
+    assert issues == [], f"The Args section is outside the narrative, got: {issues!r}"
+
+
+def test_should_skip_private_function() -> None:
+    issues = check_docstring_runon_sentence(_private_function_runon(), PRODUCTION_FILE_PATH)
+    assert issues == [], f"Private functions are out of scope, got: {issues!r}"
+
+
+def test_should_skip_property_method() -> None:
+    issues = check_docstring_runon_sentence(_property_method_runon(), PRODUCTION_FILE_PATH)
+    assert issues == [], f"@property methods are exempt, got: {issues!r}"
+
+
+def test_should_skip_test_file() -> None:
+    issues = check_docstring_runon_sentence(_run_lifecycle_module(), TEST_FILE_PATH)
+    assert issues == [], f"Test files exempt, got: {issues!r}"
+
+
+def test_should_skip_hook_infrastructure() -> None:
+    issues = check_docstring_runon_sentence(_run_lifecycle_module(), HOOK_INFRASTRUCTURE_PATH)
+    assert issues == [], f"Hook infrastructure exempt, got: {issues!r}"
+
+
+def test_should_handle_syntax_error_gracefully() -> None:
+    issues = check_docstring_runon_sentence("def broken(\n", PRODUCTION_FILE_PATH)
+    assert issues == [], f"Syntax error must yield no issues, got: {issues!r}"
+
+
+def test_validate_content_surfaces_docstring_runon_wall() -> None:
+    issues = validate_content(_run_lifecycle_module(), PRODUCTION_FILE_PATH, old_content="")
+    matching_issues = [each for each in issues if "run-on" in each]
+    assert matching_issues, f"Expected validate_content to surface the run-on wall, got: {issues!r}"
+
+
+def _attached_cli_flag_double_hyphen() -> str:
+    return (
+        "def gather_remote_reviews() -> None:\n"
+        '    """Read every review the bot left across all the pages it produced and\n'
+        "    gather them into one ordered list by paging through the endpoint with the\n"
+        "    --paginate --slurp flags so the newest review across the whole set rises to\n"
+        "    the top of the report for the reader.\n"
+        '    """\n'
+        "    return None\n"
+    )
+
+
+def _spaced_double_hyphen_joiner() -> str:
+    return (
+        "def gather_remote_reviews() -> None:\n"
+        '    """Read every review the bot left across all the pages it produced and\n'
+        "    gather them into one ordered list so the newest review rises to the top of\n"
+        "    the report -- the single line a tired reader scans first to learn how the\n"
+        "    whole run actually ended today.\n"
+        '    """\n'
+        "    return None\n"
+    )
+
+
+def test_should_not_flag_attached_cli_flag_double_hyphen() -> None:
+    issues = check_docstring_runon_sentence(
+        _attached_cli_flag_double_hyphen(), PRODUCTION_FILE_PATH
+    )
+    assert issues == [], (
+        "An attached --flag token is not a clause joiner and must not flag, "
+        f"got: {issues!r}"
+    )
+
+
+def test_should_flag_spaced_double_hyphen_joiner() -> None:
+    issues = check_docstring_runon_sentence(
+        _spaced_double_hyphen_joiner(), PRODUCTION_FILE_PATH
+    )
+    assert any("run-on" in each for each in issues), (
+        f"A spaced double-hyphen joiner past the word limit must flag, got: {issues!r}"
+    )
+    assert len(issues) == 1
+
+
+def test_docstring_names_every_inspected_section_header() -> None:
+    docstring = code_rules_enforcer.check_docstring_runon_sentence.__doc__
+    assert docstring is not None
+    inspected_headers = set(ALL_DOCSTRING_ARGS_SECTION_HEADERS) | set(
+        ALL_DOCSTRING_TERMINATING_SECTION_HEADERS
+    )
+    missing_headers = sorted(
+        each_header for each_header in inspected_headers if each_header not in docstring
+    )
+    assert missing_headers == [], (
+        "The docstring must name every section header the body cuts the narrative on; "
+        f"missing: {missing_headers!r}"
+    )

package/hooks/hooks_constants/blocking_check_limits.py

@@ -7,6 +7,8 @@ under the file-global-constants use-count rule (CODE_RULES §file-global-constan
 
 from __future__ import annotations
 
+import re
+
 MAX_BANNED_PREFIX_ISSUES: int = 3
 MAX_STUB_IMPLEMENTATION_ISSUES: int = 3
 MAX_TYPED_DICT_PAIR_ISSUES: int = 3
@@ -61,6 +63,27 @@ MINIMUM_TOKENS_FOR_DISPATCH_CALLEE: int = 2
 MAX_DOCSTRING_UNDEFINED_CONSTANT_ISSUES: int = 3
 MAX_DOCSTRING_RETURNS_PLURAL_CARDINALITY_ISSUES: int = 5
 SINGLE_DICT_KEY_COUNT_FOR_PLURAL_CARDINALITY_DRIFT: int = 1
+MAX_DOCSTRING_ARGS_SPAN_SCOPE_ISSUES: int = 3
+ALL_DOCSTRING_SINGLE_LINE_SCOPE_PHRASES: tuple[str, ...] = (
+    "anchor line is among the changed lines",
+    "anchor line is among the edited lines",
+    "anchor line is among the changed",
+    "first line is among the changed lines",
+    "start line is among the changed lines",
+)
+ALL_DOCSTRING_SPAN_SCOPE_OVERRIDE_PHRASES: tuple[str, ...] = (
+    "any line of",
+    "any line in",
+    "any of its lines",
+    "any span line",
+)
+ALL_DOCSTRING_SPAN_RANGE_BODY_CALLEE_NAMES: tuple[str, ...] = (
+    "_scope_violations_to_changed_lines",
+    "_scope_violations",
+)
+MAX_DOCSTRING_CARDINAL_FAMILY_ISSUES: int = 5
+MINIMUM_CONSTANT_FAMILY_MEMBERS_FOR_CARDINAL_CHECK: int = 2
+MINIMUM_DOCSTRING_FAMILY_OVERLAP_FOR_CARDINAL_CHECK: int = 2
 ALL_NAMING_CONVENTION_DESCRIPTOR_TOKENS: frozenset[str] = frozenset(
     {
         "UPPER_SNAKE_CASE",
@@ -114,6 +137,10 @@ ALL_FORMAT_LOGGER_FUNCTION_NAMES: frozenset[str] = frozenset(
         "log_background",
     }
 )
+DOCSTRING_RUNON_SENTENCE_WORD_LIMIT: int = 30
+MAX_DOCSTRING_RUNON_SENTENCE_ISSUES: int = 5
+ALL_DOCSTRING_RUNON_JOINER_MARKERS: tuple[str, ...] = ("—", " -- ", ";")
+DOCSTRING_RUNON_SENTENCE_BOUNDARY_PATTERN: re.Pattern[str] = re.compile(r"(?<=[.!?])\s+")
 
 ALL_DOCSTRING_NO_CONSUMER_CLAIM_PHRASES: tuple[str, ...] = (
     "no consumer reads",