claude-dev-env 1.76.0 → 1.77.0

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

@@ -28,6 +28,7 @@ Decomposition is by the **kind of docstring claim** that needs to be cross-check
 | 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. When a docstring sentence excludes a named category of input from what the function flags (`X are not dispatch steps`, `Y is not a match`), confirm the axis the prose excludes on is the axis the body's branch condition actually keys on. A body that flags a call when it sits inside an `If.test` guard, paired with prose that excludes by the call's receiver shape (`method-on-local calls inside a branch are not dispatch steps`), is an O6 finding: a guarded method-on-local call is flagged even though the prose lists it as excluded — the exclusion is keyed to the wrong axis. 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. The exception-guard shape of this drift — a docstring that promises a malformed payload `resolves to None` while a payload subscript (`payload["key"]`, `float(payload["key"])`) sits outside the try/except whose handler returns None, so a present-but-malformed payload raises rather than resolving to None — is gated deterministically at Write/Edit time by `check_docstring_unguarded_malformed_payload_claim`, so the audit lane focuses on the wider Raises/None-on-failure claims 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. |
 | O8 | Companion-doc ordering/content vs producer | When a PR changes a producer function's ordering or union, read that skill's companion `SKILL.md` and sibling `.md` docs for any sentence naming the same produced artifact (a file path, a JSON key, a named list). A doc sentence that claims the artifact is `sorted` / `alphabetical` / `in sorted order`, or holds `just the at-risk names` / `only the current set`, while the producer merges stored names with new names and appends — preserving file order, not re-sorting the union — is an O8 finding on both counts (wrong order claim, hidden merged-in entries). The finding stands even when the PR diff never touched the `.md` file, because the behavior change orphaned the doc claim. See `../../rules/docstring-prose-matches-implementation.md`. |
+| O9 | Python docstring plainness for a general developer | A changed module / class / public-function docstring's narrative prose — the summary and description before the first `Args:` / `Returns:` / `Raises:` / `Yields:` section — reads plainly and paints a concrete scene a general developer follows on first read. Flag a narrative that stacks abstract machinery nouns into a wall (`the SIGINT install/restore/installability check, the atexit terminal-record registration, and the interrupted-run finalizer`), that defines a thing by what it is not (`the non-promoter-specific machinery`), or that runs one sentence long while joining clauses with an em-dash or a semicolon. The deterministic run-on mark is gated at Write/Edit time by `check_docstring_runon_sentence` in `code_rules_docstrings.py`, so this lane carries the illustrative-and-brief judgment the gate cannot: whether a stranger to the code pictures the moment, the input, and the outcome after one read. See `../../rules/plain-illustrative-docstrings.md`. |
 
 ---
 

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

@@ -1,4 +1,4 @@
-Audit [REPO/ARTIFACT] [TARGET_ID] for **Category O only** (docstring / fixture-prose vs implementation drift). Skip A–N, P. Sub-bucket forced-exhaustion mode: Category O is decomposed into 8 sub-buckets below. Each sub-bucket REQUIRES at least one Shape A finding OR exactly one Shape B proof-of-absence with **at least 3 adversarial probes** specific to that sub-bucket. A sub-bucket returning neither is a protocol gap.
+Audit [REPO/ARTIFACT] [TARGET_ID] for **Category O only** (docstring / fixture-prose vs implementation drift). Skip A–N, P. Sub-bucket forced-exhaustion mode: Category O is decomposed into 9 sub-buckets below. Each sub-bucket REQUIRES at least one Shape A finding OR exactly one Shape B proof-of-absence with **at least 3 adversarial probes** specific to that sub-bucket. A sub-bucket returning neither is a protocol gap.
 
 [ARTIFACT METADATA — include every changed module's docstring AND the exported symbols of that module so the audit can compare claim vs body]
 
@@ -51,9 +51,13 @@ ID prefix: `find`.
 - When the diff changes a producer function's ordering or union, read that skill's companion `SKILL.md` and sibling `.md` docs for any sentence naming the same produced artifact (a file path, a JSON key, a named list). A doc sentence that claims the artifact is `sorted` / `alphabetical` / `in sorted order`, or holds `just the at-risk names` / `only the current set`, while the producer merges stored names with new names and appends — preserving file order, not re-sorting the union — is an O8 finding on both counts (wrong order claim, hidden merged-in entries). The finding stands even when the diff never touched the `.md` file, because the behavior change orphaned the doc claim.
 - Adversarial probes: (a) for each changed producer, name the artifact it builds and grep the skill's `SKILL.md` and sibling `.md` files for any sentence naming that artifact; (b) walk the producer body's build step — does it sort, or does it merge stored names and append in file order — and compare against the doc's order word (`sorted`, `alphabetical`); (c) check whether the doc's content claim (`just the at-risk names`, `only the current set`) hides merged-in prior entries the producer carries over from the stored file.
 
+**O9. Python docstring plainness for a general developer**
+- For every changed module / class / public-function docstring, read the narrative prose before the first `Args:` / `Returns:` / `Raises:` / `Yields:` section as a stranger to the code. Flag a narrative that stacks abstract machinery nouns into a single wall, that defines a thing by what it is not (`the non-promoter-specific machinery`), or that runs one sentence past the word limit while joining clauses with an em-dash or a semicolon. The run-on mark is gated at Write/Edit time by `check_docstring_runon_sentence`, so this lane judges the part the gate cannot: whether the prose paints a concrete scene — the moment the code matters, the input it sees, the outcome it produces — that a general developer follows on the first read.
+- Adversarial probes: (a) read each changed narrative and name the concrete moment, input, and outcome it paints — a narrative that names none is an O9 finding; (b) count the longest sentence's words and check for an em-dash or semicolon join — over the limit with a join is the wall mark the gate also catches; (c) rewrite each "is not" clause as a positive statement — a clause that resists rewriting because the body offers no positive description is an O9 finding.
+
 ## Cross-bucket questions to answer at the end
 
-Q1: Across all 8 sub-buckets, which docstring claim is the most misleading — i.e., a future maintainer reading only the docstring would write or change code that contradicts the body? Cite file:line of the docstring AND the body line(s) that contradict it.
+Q1: Across all 9 sub-buckets, which docstring claim is the most misleading — i.e., a future maintainer reading only the docstring would write or change code that contradicts the body? Cite file:line of the docstring AND the body line(s) that contradict it.
 
 Q2: Which docstring claim is at highest risk of becoming load-bearing — i.e., a future caller or test author would rely on the claim to skip reading the body? Cite the claim and the use case.
 
@@ -61,13 +65,13 @@ Q3: Of the changed docstrings, which one most clearly shows a refactor was incom
 
 ## Output
 
-Lead: `Total: N (P0=N, P1=N, P2=N)`. For each sub-bucket O1-O8, produce Shape A or Shape B (with ≥3 probes). Each Shape A finding must cite (a) the docstring file:line, (b) the body file:line that contradicts it, and (c) one sentence describing the contradiction in concrete terms. Cross-bucket Q1-Q3 answers after the per-sub-bucket walk. Adversarial second pass: "assume your first pass missed at least 3 module-level docstring claims whose implementation moved during a refactor — find them." Open Questions section for ambiguities. Read-only. No edits, no commits.
+Lead: `Total: N (P0=N, P1=N, P2=N)`. For each sub-bucket O1-O9, produce Shape A or Shape B (with ≥3 probes). Each Shape A finding must cite (a) the docstring file:line, (b) the body file:line that contradicts it, and (c) one sentence describing the contradiction in concrete terms. Cross-bucket Q1-Q3 answers after the per-sub-bucket walk. Adversarial second pass: "assume your first pass missed at least 3 module-level docstring claims whose implementation moved during a refactor — find them." Open Questions section for ambiguities. Read-only. No edits, no commits.
 
 ---
 
 # Worked example: jl-cmd/claude-code-config PR #522
 
-Audit jl-cmd/claude-code-config PR #522 for **Category O only** (docstring / fixture-prose vs implementation drift). Skip A-N, P. Sub-bucket forced-exhaustion mode: Category O is decomposed into 8 sub-buckets below.
+Audit jl-cmd/claude-code-config PR #522 for **Category O only** (docstring / fixture-prose vs implementation drift). Skip A-N, P. Sub-bucket forced-exhaustion mode: Category O is decomposed into 9 sub-buckets below.
 
 PR #522 split `pr_description_command_parser.py` into two modules — the original parser and a new `pr_description_pr_number.py` — but the originating module's docstring still claims the PR-number recovery responsibility. A sibling change to `pr_description_body_audit.py` introduced a module docstring whose verb (`detects vague language`) overstates the module's actual responsibility (it only exposes `_extract_vague_scan_text()`; detection runs elsewhere).
 

package/hooks/blocking/code_rules_docstrings.py

@@ -31,23 +31,34 @@ from hooks_constants.blocking_check_limits import (  # noqa: E402
     ALL_DOCSTRING_NO_CONSUMER_CLAIM_PHRASES,
     ALL_DOCSTRING_NO_INLINE_LITERAL_CLAIM_PHRASES,
     ALL_DOCSTRING_NON_CONSTANT_REFERENCE_MARKERS,
+    ALL_DOCSTRING_RUNON_JOINER_MARKERS,
     ALL_GENERIC_CHECK_NAME_TOKENS,
     ALL_NAMING_CONVENTION_DESCRIPTOR_TOKENS,
     DOCSTRING_FALLBACK_BRANCH_MINIMUM_ROUTE_COUNT,
     DOCSTRING_REFERENCE_MARKER_WINDOW,
+    DOCSTRING_RUNON_SENTENCE_BOUNDARY_PATTERN,
+    DOCSTRING_RUNON_SENTENCE_WORD_LIMIT,
     DOCSTRING_TRIVIAL_FUNCTION_BODY_LINE_LIMIT,
     MAX_CLASS_DOCSTRING_PUBLIC_METHOD_ISSUES,
     MAX_DOCSTRING_ARGS_SIGNATURE_ISSUES,
+    MAX_DOCSTRING_CARDINAL_FAMILY_ISSUES,
     MAX_DOCSTRING_FALLBACK_BRANCH_ISSUES,
     MAX_DOCSTRING_FORMAT_ISSUES,
     MAX_DOCSTRING_INLINE_LITERAL_CLAIM_ISSUES,
     MAX_DOCSTRING_NO_CONSUMER_CLAIM_ISSUES,
+    MAX_DOCSTRING_RUNON_SENTENCE_ISSUES,
+    ALL_DOCSTRING_SINGLE_LINE_SCOPE_PHRASES,
+    ALL_DOCSTRING_SPAN_RANGE_BODY_CALLEE_NAMES,
+    ALL_DOCSTRING_SPAN_SCOPE_OVERRIDE_PHRASES,
+    MAX_DOCSTRING_ARGS_SPAN_SCOPE_ISSUES,
     MAX_DOCSTRING_STEP_DISPATCH_ISSUES,
     MAX_DOCSTRING_RETURNS_PLURAL_CARDINALITY_ISSUES,
     MAX_DOCSTRING_TUPLE_ENUMERATION_ISSUES,
     MAX_DOCSTRING_UNDEFINED_CONSTANT_ISSUES,
     MAX_DOCSTRING_UNGUARDED_PAYLOAD_CLAIM_ISSUES,
     MAX_MODULE_DOCSTRING_CHECK_ROSTER_ISSUES,
+    MINIMUM_CONSTANT_FAMILY_MEMBERS_FOR_CARDINAL_CHECK,
+    MINIMUM_DOCSTRING_FAMILY_OVERLAP_FOR_CARDINAL_CHECK,
     MINIMUM_NAMED_LINEAR_STEPS_FOR_DISPATCH_CHECK,
     MINIMUM_PUBLIC_CHECKS_FOR_MODULE_DOCSTRING_ROSTER,
     MINIMUM_PUBLIC_METHODS_FOR_CLASS_DOCSTRING_BREADTH,
@@ -57,10 +68,13 @@ from hooks_constants.blocking_check_limits import (  # noqa: E402
 )
 from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     ALL_CAPS_WITH_UNDERSCORE_PATTERN,
+    ALL_CARDINAL_NUMBER_WORD_VALUES,
     ALL_DOCSTRING_ARGS_SECTION_HEADERS,
     ALL_DOCSTRING_TERMINATING_SECTION_HEADERS,
     ALL_SELF_AND_CLS_PARAMETER_NAMES,
     DOCSTRING_ARG_ENTRY_PATTERN,
+    DOCSTRING_CARDINAL_OUTCOME_PHRASE_PATTERN,
+    DOCSTRING_MULTI_SEGMENT_SNAKE_TOKEN_PATTERN,
     DOCSTRING_PLURAL_FAMILY_STOP_PATTERN,
     IDENTIFIER_SHAPED_TUPLE_MEMBER_PATTERN,
     INLINE_CODE_TOKEN_PATTERN,
@@ -1111,6 +1125,122 @@ def check_docstring_returns_plural_cardinality(content: str, file_path: str) ->
     return issues[:MAX_DOCSTRING_RETURNS_PLURAL_CARDINALITY_ISSUES]
 
 
+def _referenced_constant_families(parsed_tree: ast.Module) -> dict[str, set[str]]:
+    members_by_family: dict[str, set[str]] = {}
+    for each_node in ast.walk(parsed_tree):
+        if not isinstance(each_node, ast.Name):
+            continue
+        if not isinstance(each_node.ctx, ast.Load):
+            continue
+        if not ALL_CAPS_WITH_UNDERSCORE_PATTERN.match(each_node.id):
+            continue
+        family_prefix, _, member_suffix = each_node.id.partition("_")
+        if not member_suffix:
+            continue
+        members_by_family.setdefault(family_prefix, set()).add(member_suffix.lower())
+    return members_by_family
+
+
+def _eligible_constant_families(parsed_tree: ast.Module) -> dict[str, set[str]]:
+    return {
+        each_family: each_members
+        for each_family, each_members in _referenced_constant_families(parsed_tree).items()
+        if len(each_members) >= MINIMUM_CONSTANT_FAMILY_MEMBERS_FOR_CARDINAL_CHECK
+    }
+
+
+def _docstring_snake_case_tokens(docstring_text: str) -> set[str]:
+    return set(DOCSTRING_MULTI_SEGMENT_SNAKE_TOKEN_PATTERN.findall(docstring_text))
+
+
+def _docstring_stated_outcome_cardinals(docstring_text: str) -> set[int]:
+    return {
+        ALL_CARDINAL_NUMBER_WORD_VALUES[each_match.group(1).lower()]
+        for each_match in DOCSTRING_CARDINAL_OUTCOME_PHRASE_PATTERN.finditer(docstring_text)
+    }
+
+
+def _documentable_docstrings_with_line(parsed_tree: ast.Module) -> list[tuple[int, str]]:
+    docstrings_with_line: list[tuple[int, str]] = []
+    module_docstring = ast.get_docstring(parsed_tree) or ""
+    if module_docstring:
+        docstrings_with_line.append((1, module_docstring))
+    for each_node in ast.walk(parsed_tree):
+        if not isinstance(
+            each_node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)
+        ):
+            continue
+        node_docstring = ast.get_docstring(each_node) or ""
+        if node_docstring:
+            docstrings_with_line.append((each_node.lineno, node_docstring))
+    return docstrings_with_line
+
+
+def check_docstring_cardinal_count_matches_constant_family(
+    content: str, file_path: str
+) -> list[str]:
+    """Flag a docstring cardinal count that under-names a referenced constant family.
+
+    The drift this catches: a docstring states a cardinal count of an outcome
+    family (``Covers the four outcome branches: ...``) and enumerates that
+    family's members in prose, while the module references more members of the
+    same ``UPPER_SNAKE`` constant family than the count names. The prose
+    under-describes the code — a reader trusts the count and the enumeration to
+    be the full set, but the module imports and exercises an outcome the summary
+    omits. The check binds only when the docstring states a cardinal beside an
+    outcome noun, names two or more members of one referenced family, leaves at
+    least one referenced family member unnamed, and the family member count
+    differs from every stated cardinal; a complete enumeration, a count that
+    matches the family, and a single passing mention are all left alone. This is
+    the deterministic cardinal-count slice of Category O6
+    docstring-prose-vs-implementation drift. The check runs on test files too,
+    since the drift class lives in a test-module summary.
+
+    Args:
+        content: The source text to inspect.
+        file_path: The path the source will be written to, used for exemptions.
+
+    Returns:
+        One issue per docstring whose cardinal count and enumeration omit a
+        referenced constant-family member, capped at the module limit.
+    """
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    eligible_families = _eligible_constant_families(parsed_tree)
+    if not eligible_families:
+        return []
+    issues: list[str] = []
+    for each_line, each_docstring in _documentable_docstrings_with_line(parsed_tree):
+        stated_cardinals = _docstring_stated_outcome_cardinals(each_docstring)
+        if not stated_cardinals:
+            continue
+        docstring_tokens = _docstring_snake_case_tokens(each_docstring)
+        if not docstring_tokens:
+            continue
+        for each_family in sorted(eligible_families):
+            family_members = eligible_families[each_family]
+            named_members = docstring_tokens & family_members
+            if len(named_members) < MINIMUM_DOCSTRING_FAMILY_OVERLAP_FOR_CARDINAL_CHECK:
+                continue
+            omitted_members = family_members - docstring_tokens
+            if not omitted_members:
+                continue
+            if len(family_members) in stated_cardinals:
+                continue
+            issues.append(
+                f"Line {each_line}: docstring names {sorted(stated_cardinals)} as the "
+                f"{each_family}_ count but the module references {len(family_members)} "
+                f"{each_family}_ constants — omits {sorted(omitted_members)}; match the "
+                "count and enumeration to the referenced family "
+                "(Category O6 docstring-vs-implementation drift)"
+            )
+            if len(issues) >= MAX_DOCSTRING_CARDINAL_FAMILY_ISSUES:
+                return issues[:MAX_DOCSTRING_CARDINAL_FAMILY_ISSUES]
+    return issues[:MAX_DOCSTRING_CARDINAL_FAMILY_ISSUES]
+
+
 def _called_callee_name(statement: ast.stmt) -> str:
     candidate_expression: ast.expr | None = None
     if isinstance(statement, ast.Expr):
@@ -1458,3 +1588,251 @@ def check_docstring_names_undefined_constant(content: str, file_path: str) -> li
             if len(issues) >= MAX_DOCSTRING_UNDEFINED_CONSTANT_ISSUES:
                 return issues[:MAX_DOCSTRING_UNDEFINED_CONSTANT_ISSUES]
     return issues[:MAX_DOCSTRING_UNDEFINED_CONSTANT_ISSUES]
+
+
+def _args_entry_prose_by_argument(docstring_text: str) -> dict[str, str]:
+    docstring_lines = docstring_text.splitlines()
+    args_section_index = _find_args_section_index(docstring_lines)
+    if args_section_index is None:
+        return {}
+    prose_by_argument: dict[str, list[str]] = {}
+    current_argument_name: str | None = None
+    entry_indent: int | None = None
+    for each_line in docstring_lines[args_section_index + 1:]:
+        stripped_line = each_line.strip()
+        if not stripped_line:
+            continue
+        if _is_docstring_terminating_section_header(stripped_line):
+            break
+        current_indent = len(each_line) - len(each_line.lstrip())
+        if current_indent == 0:
+            break
+        if entry_indent is None:
+            entry_indent = current_indent
+        if current_indent <= entry_indent:
+            entry_match = DOCSTRING_ARG_ENTRY_PATTERN.match(stripped_line)
+            if entry_match is not None:
+                current_argument_name = entry_match.group(1)
+                prose_by_argument[current_argument_name] = [stripped_line]
+                continue
+        if current_argument_name is not None:
+            prose_by_argument[current_argument_name].append(stripped_line)
+    return {
+        each_name: " ".join(each_lines).lower()
+        for each_name, each_lines in prose_by_argument.items()
+    }
+
+
+def _argument_prose_scopes_a_single_line(argument_prose: str) -> bool:
+    if any(
+        each_phrase in argument_prose for each_phrase in ALL_DOCSTRING_SPAN_SCOPE_OVERRIDE_PHRASES
+    ):
+        return False
+    return any(
+        each_phrase in argument_prose for each_phrase in ALL_DOCSTRING_SINGLE_LINE_SCOPE_PHRASES
+    )
+
+
+def _call_node_builds_two_argument_range(call_node: ast.Call) -> bool:
+    callee = call_node.func
+    return (
+        isinstance(callee, ast.Name)
+        and callee.id == "range"
+        and len(call_node.args) >= MINIMUM_TOKENS_FOR_DISPATCH_CALLEE
+    )
+
+
+def _function_body_scopes_a_span_by_intersection(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> bool:
+    builds_range_span = False
+    calls_span_scoper = False
+    for each_node in ast.walk(function_node):
+        if not isinstance(each_node, ast.Call):
+            continue
+        if _call_node_builds_two_argument_range(each_node):
+            builds_range_span = True
+        if _call_callee_name(each_node) in ALL_DOCSTRING_SPAN_RANGE_BODY_CALLEE_NAMES:
+            calls_span_scoper = True
+    return builds_range_span and calls_span_scoper
+
+
+def check_docstring_args_single_line_scope_vs_span(content: str, file_path: str) -> list[str]:
+    """Flag a docstring Args entry scoping a finding to one line over a span body.
+
+    The drift this catches: an ``Args:`` entry whose prose says a finding blocks
+    "only when its block-anchor line is among the changed lines" (a single named
+    line) while the function body builds a ``range(...)`` span over the finding's
+    source lines and routes it through a span-intersection scoper that blocks when
+    ANY line of the span is among the changed lines. The Args sentence claims a
+    narrower single-line scope than the body applies, so an edit touching a
+    non-anchor line of the span still blocks — contradicting the Args entry. This
+    is the deterministic slice of Category O6 docstring-vs-implementation drift
+    for an Args single-line scope claim disagreeing with a span-intersection body.
+
+    An entry is left alone when its prose says "any line of" / "any line in" its
+    span, since that wording matches the span body. The body is judged a
+    span-intersection scoper only when it both builds a two-argument ``range(...)``
+    and calls a known span scoper, so a body that scopes by a single line never
+    trips the check. Hook infrastructure is in scope here — the import-sort gate
+    that carries this drift class is itself a hook — and test files are exempt.
+
+    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 Args single-line scope claim disagrees with
+        its span-intersection body, capped at the module limit.
+    """
+    if is_test_file(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 _function_body_scopes_a_span_by_intersection(each_node):
+            continue
+        for each_argument, each_prose in _args_entry_prose_by_argument(docstring_text).items():
+            if not _argument_prose_scopes_a_single_line(each_prose):
+                continue
+            issues.append(
+                f"Line {each_node.lineno}: {each_node.name}() Args entry '{each_argument}' "
+                "scopes a finding to a single line ('anchor line is among the changed lines') "
+                "while the body builds a range() span and scopes by span intersection — an "
+                "edit touching any non-anchor line of the span still blocks; restate the Args "
+                "entry as 'any line of its span is among the changed lines' (Category O6 "
+                "docstring-vs-implementation drift)"
+            )
+            if len(issues) >= MAX_DOCSTRING_ARGS_SPAN_SCOPE_ISSUES:
+                return issues[:MAX_DOCSTRING_ARGS_SPAN_SCOPE_ISSUES]
+    return issues[:MAX_DOCSTRING_ARGS_SPAN_SCOPE_ISSUES]
+
+
+def _is_narrative_cut_header(stripped_line: str) -> bool:
+    return (
+        stripped_line in ALL_DOCSTRING_TERMINATING_SECTION_HEADERS
+        or stripped_line in ALL_DOCSTRING_ARGS_SECTION_HEADERS
+    )
+
+
+def _docstring_narrative_text(docstring_text: str) -> str:
+    narrative_lines: list[str] = []
+    for each_line in docstring_text.splitlines():
+        stripped_line = each_line.strip()
+        if _is_narrative_cut_header(stripped_line):
+            break
+        narrative_lines.append(stripped_line)
+    return " ".join(narrative_lines)
+
+
+def _sentence_word_count(sentence_text: str) -> int:
+    return sum(
+        1
+        for each_token in sentence_text.split()
+        if any(each_character.isalnum() for each_character in each_token)
+    )
+
+
+def _sentence_carries_joiner_marker(sentence_text: str) -> bool:
+    return any(
+        each_marker in sentence_text for each_marker in ALL_DOCSTRING_RUNON_JOINER_MARKERS
+    )
+
+
+def _runon_sentences(narrative_text: str) -> list[str]:
+    flagged_sentences: list[str] = []
+    for each_sentence in DOCSTRING_RUNON_SENTENCE_BOUNDARY_PATTERN.split(narrative_text):
+        stripped_sentence = each_sentence.strip()
+        if not stripped_sentence:
+            continue
+        if _sentence_word_count(stripped_sentence) <= DOCSTRING_RUNON_SENTENCE_WORD_LIMIT:
+            continue
+        if not _sentence_carries_joiner_marker(stripped_sentence):
+            continue
+        flagged_sentences.append(stripped_sentence)
+    return flagged_sentences
+
+
+def _documentable_docstring_targets(
+    parsed_tree: ast.Module,
+) -> list[tuple[int, str, str]]:
+    documentable_targets: list[tuple[int, str, str]] = []
+    module_docstring = ast.get_docstring(parsed_tree)
+    if module_docstring and parsed_tree.body:
+        documentable_targets.append((parsed_tree.body[0].lineno, "module", module_docstring))
+    for each_node in _walk_skipping_type_checking_blocks(parsed_tree):
+        if isinstance(each_node, ast.ClassDef):
+            class_docstring = ast.get_docstring(each_node)
+            if class_docstring:
+                documentable_targets.append((each_node.lineno, each_node.name, class_docstring))
+            continue
+        if not isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if _function_is_private_or_dunder(each_node.name):
+            continue
+        if _function_has_exempt_decorator(each_node):
+            continue
+        function_docstring = _function_docstring_text(each_node)
+        if function_docstring:
+            documentable_targets.append(
+                (each_node.lineno, f"{each_node.name}()", function_docstring)
+            )
+    return documentable_targets
+
+
+def check_docstring_runon_sentence(content: str, file_path: str) -> list[str]:
+    """Flag a docstring narrative sentence that reads as a dense run-on wall.
+
+    A readable docstring breaks its narrative into short sentences a general
+    developer follows on the first read. The one mechanical mark of a wall is a
+    single sentence that runs past the word limit while chaining clauses with an
+    em-dash or a semicolon. This check inspects the narrative prose of module,
+    class, and public-function docstrings — the text before the first structured
+    section header (``Args:``, ``Arguments:``, ``Returns:``, ``Yields:``,
+    ``Raises:``, ``Note:``, ``Notes:``, ``Example:``, or ``Examples:``) — and
+    reports a sentence that is both over the word limit and joined by one of those
+    marks.
+    Whether the prose paints a concrete, illustrative picture is judgment the
+    plain-illustrative-docstrings audit lane carries; this gate catches only the
+    run-on mark.
+
+    Args:
+        content: The source text to inspect.
+        file_path: The path the source will be written to, used for exemptions.
+
+    Returns:
+        One issue per docstring whose narrative carries a run-on sentence, 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_line_number, each_label, each_docstring in _documentable_docstring_targets(
+        parsed_tree
+    ):
+        flagged_sentences = _runon_sentences(_docstring_narrative_text(each_docstring))
+        if not flagged_sentences:
+            continue
+        run_on_word_count = _sentence_word_count(flagged_sentences[0])
+        issues.append(
+            f"Line {each_line_number}: {each_label} docstring carries a {run_on_word_count}-word "
+            "run-on sentence — break the narrative into short, illustrative sentences a general "
+            "developer reads in one pass (plain-illustrative-docstrings)"
+        )
+        if len(issues) >= MAX_DOCSTRING_RUNON_SENTENCE_ISSUES:
+            break
+    return issues[:MAX_DOCSTRING_RUNON_SENTENCE_ISSUES]

package/hooks/blocking/code_rules_enforcer.py

@@ -67,12 +67,15 @@ from code_rules_dead_module_constant import (  # noqa: E402
 from code_rules_docstrings import (  # noqa: E402
     check_class_docstring_names_public_methods,
     check_docstring_args_match_signature,
+    check_docstring_args_single_line_scope_vs_span,
+    check_docstring_cardinal_count_matches_constant_family,
     check_docstring_fallback_branch_coverage,
     check_docstring_format,
     check_docstring_names_undefined_constant,
     check_docstring_no_consumer_claim,
     check_docstring_no_inline_literal_claim,
     check_docstring_returns_plural_cardinality,
+    check_docstring_runon_sentence,
     check_docstring_step_enumeration_dispatch_coverage,
     check_docstring_tuple_enumeration_match,
     check_docstring_unguarded_malformed_payload_claim,
@@ -295,6 +298,7 @@ def validate_content(
         all_issues.extend(
             check_class_docstring_names_public_methods(effective_content, file_path)
         )
+        all_issues.extend(check_docstring_runon_sentence(effective_content, file_path))
         all_issues.extend(
             check_module_docstring_names_public_checks(effective_content, file_path)
         )
@@ -309,9 +313,17 @@ def validate_content(
         all_issues.extend(
             check_docstring_returns_plural_cardinality(effective_content, file_path)
         )
+        all_issues.extend(
+            check_docstring_cardinal_count_matches_constant_family(
+                effective_content, file_path
+            )
+        )
         all_issues.extend(
             check_docstring_names_undefined_constant(effective_content, file_path)
         )
+        all_issues.extend(
+            check_docstring_args_single_line_scope_vs_span(effective_content, file_path)
+        )
         all_issues.extend(
             check_boolean_naming(
                 effective_content,