claude-dev-env 2.9.0 → 2.11.0

package/docs/references/prose-style-enforcement.md

@@ -0,0 +1,25 @@
+# Prose-style enforcement
+
+Opinionated prose gates (heavy-word swaps, hedging, historical state phrasing, intent-only endings, hook prose-detector consistency) are **off by default**.
+
+## Opt-in
+
+Set `CLAUDE_PROSE_STYLE_ENFORCEMENT` to `1`, `true`, `yes`, or `on` (case and spaces ignored). Any other value, and an unset variable, leave those gates off.
+
+The flag is `PROSE_STYLE_ENFORCEMENT_ENABLED` in `hooks/blocking/config/prose_style_enforcement_constants.py`.
+
+## Always on
+
+Structural AskUserQuestion lean-block validation in `plain_language_blocker` (chat detail, length caps on question blocks) stays active regardless of the flag. Code-rules and security blockers are out of scope for this switch.
+
+## Advisory precision measurement (OP-07B)
+
+When the flag is off, heavy-word and hedging hits still emit privacy-safe advisory candidates to `~/.claude/logs/prose-matcher-advisory.jsonl` (matcher id, surface, hashed context fingerprint, optional label). Classification (`keep` / `narrow` / `drop` / `advisory`) uses a labeled sample floor of 30 and precision floors 0.7 / 0.4. Matchers below the floor stay advisory. No matcher becomes hard-blocking from historical labels alone. See `hooks/observability/prose_matcher_advisory.py`.
+
+## Explicit uncertainty (OP-07C)
+
+With enforcement on, a hedge word in a sentence that also labels the claim (`unverified`, `I don't know`, `no source for this claim`, …) passes. A bare hedge in a different sentence still blocks. Detail: `rules/hedging-claims.md`.
+
+## Plain-language advisory (OP-07D)
+
+Heavy-word matches never hard-deny a Write/Edit or AskUserQuestion. With enforcement on, the hook allows the call and returns a `systemMessage` that names everyday swaps for both AskUserQuestion and `.md` writes. Lean-block structure denials stay hard. Detail: `rules/plain-language.md`.

package/docs/references/team-advisor-skill.md

@@ -1,6 +1,6 @@
 # Team-Advisor Skill
 
-`/team-advisor` binds one standing warm advisor for this session at the strongest reachable tier. Use it when `advisor()` is absent, or when you want a standing four-signal reviewer across many decision points.
+`/team-advisor` binds one standing warm advisor for this session at the strongest reachable tier. This skill is the selected custom reproduction path for advisor behavior: it forwards explicit packets to a warm Agent/SendMessage advisor or the read-only `codex_sol_advisor.py` path across many decision points.
 
 ## Refs
 
@@ -15,6 +15,6 @@
 
 Follow the call rules in `advisor-tool.md` (orientation first, then consult before substantive work; durable deliverable before the completion consult; stuck or reapproach; long tasks twice).
 
-## Relation to `advisor()`
+## Selected path
 
-`/team-advisor` works with no `advisor()` tool. When both exist: `advisor()` for a fast history-forwarded check; `/team-advisor` for a standing named reviewer consulted at the same cadence.
+`/team-advisor` is the repository's advisor implementation. It provides explicit first-consult packets, delta consults, a standing warm reviewer, and a read-only Sol CLI option.

package/docs/references/weak-executor-advisor.md

@@ -0,0 +1,91 @@
+# Weak-Executor Advisor Profile
+
+Consult profile for an executor spawned below the advisor's own tier — a
+Sonnet or Haiku model carrying an advisor bind. `advisor-tool.md` sets the
+canonical cadence for every consumer; this file adds the deltas a below-tier
+executor needs on top of it.
+
+Source: [Anthropic Advisor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool)
+(Suggested system prompt for coding tasks). The distilled facts behind each
+section live in
+`skills/team-advisor/reference/advisor-docs-review.md`.
+
+## Scope
+
+Applies to any executor running below the advisor's tier. A same-tier or
+stronger executor follows `advisor-tool.md` alone. The paste-ready form of
+this profile is the **Weak-executor add-on** block in
+`~/.claude/_shared/advisor/reference/advisor-block.md`.
+
+## Steering lives in the spawn prompt
+
+The advisor rules sit at the top of the spawn prompt, ahead of every other
+sentence that mentions the advisor — the spawn prompt is the one steering
+surface with measured effect on Sonnet.
+
+## Context packaging
+
+Everything the advisor learns arrives inside the consult. Each consult
+carries its own packet:
+
+- **First consult** — use the complete packet in
+  `~/.claude/_shared/advisor/reference/consult-format.md`: assignment,
+  desired outcome, constraints and exclusions, actions taken in order, real
+  output and current state, decision or blocker, validation evidence,
+  unresolved risks, and load-bearing paths or excerpts.
+- **Later consults** — the delta since the last consult.
+- **Ordering** — stable role and charter text first, volatile detail last.
+
+## Two-timing rule
+
+Two consult moments carry the measured gain:
+
+1. **Early** — after a few exploratory reads land in the transcript, before
+   the first write. This is the hard rule `advisor-tool.md` §Hard rule
+   states for every consumer.
+2. **Final** — after file writes and test output exist to forward. Make the
+   deliverable durable first (write the file, save the result, commit the
+   change), then consult.
+
+## Planner funnel
+
+Consult the advisor before any task-list or planner tool. The advisor's plan
+becomes the task list.
+
+## Consult budget
+
+Aim for two consults per task: early orientation and completion review. Reserve a third for advisory recovery or reconciliation guidance, and add a consult when a material fork produces new evidence. This is a planning target that leaves the task free to follow its evidence.
+
+## Advice weight
+
+Advice is binding absent empirical contradiction. A conflict between the
+executor's own evidence and the advisor's guidance goes back to the advisor
+as a reconcile consult. See `advisor-tool.md` §How to treat advice for the
+full weighing rule.
+
+## Long-run reminder
+
+On a run past roughly 20 advisor-free turns, the executor re-reads its
+advisor rules before the next substantive step — the re-read keeps the
+advisor visible across a long horizon.
+
+## Failure branches
+
+- **Transient advisor failure** — retry once, then carry on with the
+  evidence in hand and record the gap in the result.
+- **Advisor unreachable** — report upward and hold the decision for the
+  owning session; re-binding belongs to that session alone.
+
+## Pairing invariant
+
+The advisor binds at or above the strongest consumer's tier. The floor
+holds at that tier whichever executor joins the pairing.
+
+## Related
+
+| Doc | Holds |
+|---|---|
+| `advisor-tool.md` | Canonical consult cadence, hard rule, brevity cue |
+| `~/.claude/_shared/advisor/advisor-protocol.md` | Host bind, model floor, and the Advisor-block assembly rule |
+| `~/.claude/_shared/advisor/reference/advisor-block.md` | The paste parts — transport preambles, shared core, weak-executor add-on |
+| `skills/team-advisor/reference/advisor-docs-review.md` | Distilled source facts behind each section above |

package/hooks/blocking/CLAUDE.md

@@ -82,16 +82,16 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `destructive_command_blocker.py` | PreToolUse (Bash/PowerShell) | Shell commands with destructive literals (`rm -rf`, `git reset --hard`, etc.) |
 | `docstring_rule_gate_count_blocker.py` | PreToolUse (Write/Edit/MultiEdit) | A stale spelled-out gate-validator count in `docstring-prose-matches-implementation.md` — the "N more gate validators" / "M gated slices" count drifting from the `check_docstring_*` validators the prose names |
 | `duplicate_rmtree_helper_blocker.py` | PreToolUse (Write/Edit) | A local re-definition of the Windows-safe rmtree helper trio (`_strip_read_only_and_retry`, `_force_remove_tree` / `force_rmtree`) in place of importing a shared helper |
-| `eli11_reply_enforcer.py` | Stop | Final replies breaking the `eli11-replies` shape — more than 120 reader-visible words, more than 6 bullet lines, more than 2 lines carrying over 20 words each, or instruction lines telling the user to act with no numbered step among the lead lines. Code fences, inline code, blockquotes, table rows, and link targets come off before the reply is judged, replies under 60 words always pass, and a reply opening with `Long form:` opts out entirely |
+| `eli11_reply_enforcer.py` | Stop | Final replies breaking the `eli11-replies` shape — more than 6 bullet lines, more than 2 list lines over 20 words each, or multi-line instructions with no numbered step among the lead lines. Code fences, inline code, blockquotes, table rows, and link targets come off before the reply is judged. |
 | `env_var_table_code_drift_blocker.py` | PreToolUse (Write/Edit/MultiEdit) | A markdown env-var summary table row attributing an environment variable to a code file whose source never references that variable name |
 | `es_exe_path_rewriter.py` | PreToolUse | Rewrites paths referencing `.exe` under the Everything search path |
 | `fable_spawn_gate.py` | PreToolUse (Agent/Task) | An `Agent` or `Task` spawn whose prompt carries no `FABLE-SPAWN-AUTHORIZED` token and whose model field reads `fable` in any letter case — the bare alias, or a delimiter segment of a full model id, so `claude-fable-5` is denied too |
 | `gh_body_arg_blocker.py` | PreToolUse (Bash) | `gh` commands passing `--body`/`-b` directly (requires `--body-file` instead) |
 | `gh_pr_author_enforcer.py` | PreToolUse | Enforces PR author identity rules |
 | `gh_pr_author_restore.py` | PostToolUse | Restores PR author after a tool call |
-| `hedging_language_blocker.py` | Stop | Responses with hedging words (`likely`, `probably`, `appears to`) |
-| `hook_prose_detector_consistency.py` | PreToolUse (Write/Edit) | Hook docstrings/messages that claim a trigger the detector cannot fire on |
-| `intent_only_ending_blocker.py` | Stop | Responses that end on a plan or intent without doing the work |
+| `hedging_language_blocker.py` | Stop | Responses with hedging words (`likely`, `probably`, `appears to`); armed only when `CLAUDE_PROSE_STYLE_ENFORCEMENT` is on (default off) |
+| `hook_prose_detector_consistency.py` | PreToolUse (Write/Edit) | Hook docstrings/messages that claim a trigger the detector cannot fire on; armed only when `CLAUDE_PROSE_STYLE_ENFORCEMENT` is on (default off) |
+| `intent_only_ending_blocker.py` | Stop | Responses that end on a plan or intent without doing the work; armed only when `CLAUDE_PROSE_STYLE_ENFORCEMENT` is on (default off) |
 | `open_questions_in_plans_blocker.py` | PreToolUse (Write/Edit) | Plan documents with unresolved open questions |
 | `nas_ssh_binary_enforcer.py` | PreToolUse (Bash) | A bare `ssh`/`scp`/`sftp` command word targeting the NAS (Git Bash's MSYS ssh stalls on an interactive password prompt), or the full `System32/OpenSSH` binary to that host without `-o BatchMode=yes` |
 | `package_inventory_stale_blocker.py` | PreToolUse (Write) | A new production code file created in a directory whose `README.md`/`CLAUDE.md` inventory (or a parent skill's `SKILL.md` Layout table mapping the `scripts/` subdirectory) names two or more sibling files but no entry for the new file |
@@ -100,7 +100,7 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `pii_prevention_blocker.py` | PreToolUse (Write/Edit/MultiEdit/Bash/PowerShell/MCP GitHub) | Entry hook — content that carries high-confidence personal data or secrets (real emails, home-dir paths, private IPs, credential material) on write, durable GitHub posts, or staged commit paths; resolves the staged-commit repository from the command it gates (via `pii_prevention_blocker_parts`), not the session working directory |
 | `pii_scanner.py` | library | Pure text scanners shared by `pii_prevention_blocker.py` |
 | `piped_pytest_blocker.py` | PreToolUse (Bash) | A pytest run whose output feeds a pipe, where the pipeline reports the exit code of the command on the right |
-| `plain_language_blocker.py` | PreToolUse (Write/Edit/AskUserQuestion) | Heavy or jargon words in user-facing prose |
+| `plain_language_blocker.py` | PreToolUse (Write/Edit/AskUserQuestion) | Heavy or jargon words in user-facing prose when `CLAUDE_PROSE_STYLE_ENFORCEMENT` is on (default off); AskUserQuestion lean-block structure stays always on |
 | `pr_converge_bugteam_enforcer.py` | PreToolUse | Enforces that bugteam runs in parallel with bugbot in pr-converge loops |
 | `pr_description_enforcer.py` | PreToolUse (Bash) | `gh pr create`/`edit`/`comment` bodies that fail the Anthropic claude-code style audit, proof-shaped `gh pr comment` bodies missing proof-of-work parts, and `gh pr ready` while the PR carries no passing proof comment |
 | `precommit_code_rules_gate.py` | PreToolUse (Bash) | Staged changes that fail the CODE_RULES gate at commit time |
@@ -113,7 +113,7 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `session_handoff_blocker.py` | Stop | Responses suggesting a new session mid-task |
 | `shell_substitution_blocker.py` | PreToolUse (Bash) | A command carrying `$(...)`, a live backtick, or `<(...)`/`>(...)` process substitution, which the allowlist matcher cannot descend into |
 | `stale_comment_reference_blocker.py` | PreToolUse (Edit) | An Edit that rewrites a Python code line while keeping the standalone comment directly above it, when that comment names an identifier the rewrite removes from the line |
-| `state_description_blocker.py` | PreToolUse (Write/Edit) | Historical/comparative language in documentation |
+| `state_description_blocker.py` | PreToolUse (Write/Edit) | Historical/comparative language in documentation; armed only when `CLAUDE_PROSE_STYLE_ENFORCEMENT` is on (default off) |
 | `subprocess_budget_completeness.py` | PreToolUse | Subprocess calls missing required budget arguments |
 | `tdd_enforcer.py` | PreToolUse (Write/Edit) | Production code written without a matching failing test |
 | `unscoped_search_blocker.py` | PreToolUse (Bash/PowerShell) | A `find` or recursive listing that walks from the filesystem root, a drive root, bare home, or a network share root |

package/hooks/blocking/_path_setup.py

@@ -1,13 +1,17 @@
-"""Add the hooks directory to sys.path for sibling entry-point dispatchers.
+"""Add the hooks and blocking directories to sys.path for sibling imports.
 
 Importing this module inserts the hooks directory (this file's parent's parent)
-at the front of sys.path so a dispatcher that runs as a standalone script from
-blocking/ can import hooks_constants with every import kept at module top.
+and the blocking directory (its own parent) at the front of sys.path, so a
+module that runs as a standalone script from blocking/ can import both
+``hooks_constants`` and its blocking-directory siblings while every import stays
+at module top.
 """
 
 import sys
 from pathlib import Path
 
+_blocking_directory = str(Path(__file__).resolve().parent)
 _hooks_directory = str(Path(__file__).resolve().parent.parent)
-if _hooks_directory not in sys.path:
-    sys.path.insert(0, _hooks_directory)
+for each_directory in (_blocking_directory, _hooks_directory):
+    if each_directory not in sys.path:
+        sys.path.insert(0, each_directory)

package/hooks/blocking/code_rules_docstrings.py

@@ -13,6 +13,7 @@ if _hooks_directory not in sys.path:
     sys.path.insert(0, _hooks_directory)
 
 from code_rules_shared import (  # noqa: E402
+    _scope_violations_to_changed_lines,
     _statement_is_docstring,
     _walk_skipping_nested_functions,
     _walk_skipping_type_checking_blocks,
@@ -2664,18 +2665,53 @@ def _runon_sentences(narrative_text: str) -> list[str]:
     return flagged_sentences
 
 
+def _docstring_owner_span(owner_node: ast.AST, anchor_lineno: int) -> range:
+    """Lines from the owner's anchor through the end of its docstring statement.
+
+    ::
+
+        def clean_helper() -> str:              <- anchor (def / class line)
+            '''run-on narrative across lines''' <- docstring end
+            return "ok"                         <- outside the span
+
+        An edit that only rewrites the docstring body intersects this span and
+        re-grades the finding. An edit to the return line does not.
+    """
+    body = getattr(owner_node, "body", None) or []
+    if not body:
+        return range(anchor_lineno, anchor_lineno + 1)
+    first_statement = body[0]
+    end_lineno = getattr(first_statement, "end_lineno", None) or first_statement.lineno
+    return range(anchor_lineno, end_lineno + 1)
+
+
 def _documentable_docstring_targets(
     parsed_tree: ast.Module,
-) -> list[tuple[int, str, str]]:
-    documentable_targets: list[tuple[int, str, str]] = []
+) -> list[tuple[int, str, str, range]]:
+    documentable_targets: list[tuple[int, str, str, range]] = []
     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))
+        module_anchor = parsed_tree.body[0].lineno
+        documentable_targets.append(
+            (
+                module_anchor,
+                "module",
+                module_docstring,
+                _docstring_owner_span(parsed_tree, module_anchor),
+            )
+        )
     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))
+                documentable_targets.append(
+                    (
+                        each_node.lineno,
+                        each_node.name,
+                        class_docstring,
+                        _docstring_owner_span(each_node, each_node.lineno),
+                    )
+                )
             continue
         if not isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
             continue
@@ -2686,34 +2722,58 @@ def _documentable_docstring_targets(
         function_docstring = _function_docstring_text(each_node)
         if function_docstring:
             documentable_targets.append(
-                (each_node.lineno, f"{each_node.name}()", function_docstring)
+                (
+                    each_node.lineno,
+                    f"{each_node.name}()",
+                    function_docstring,
+                    _docstring_owner_span(each_node, each_node.lineno),
+                )
             )
     return documentable_targets
 
 
-def check_docstring_runon_sentence(content: str, file_path: str) -> list[str]:
+def check_docstring_runon_sentence(
+    content: str,
+    file_path: str,
+    all_changed_lines: set[int] | None = None,
+    defer_scope_to_caller: bool = False,
+) -> 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, a double-hyphen, or a semicolon. This check inspects the narrative prose of module,
-    class, and public-function docstrings — the text before the first structured
+    class, and public-function docstrings - the text before the first structured
     section header (``Args:``, ``Arguments:``, ``Returns:``, ``Yields:``,
-    ``Raises:``, ``Note:``, ``Notes:``, ``Example:``, or ``Examples:``) — and
+    ``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.
 
+    The caller passes the reconstructed full file as *content* so ``ast.parse``
+    sees a complete module. Findings are then scoped to *all_changed_lines* so an
+    Edit blocks on a run-on it just introduced while a pre-existing far-away
+    run-on on an untouched definition does not block the edit.
+
     Args:
-        content: The source text to inspect.
+        content: The source text to inspect - the reconstructed full file on an
+            Edit so the parse succeeds.
         file_path: The path the source will be written to, used for exemptions.
+        all_changed_lines: Post-edit line numbers the current edit touched, or
+            None to treat the whole file as in scope. When provided, a finding
+            blocks only when its definition-through-docstring span intersects
+            the changed lines.
+        defer_scope_to_caller: When True, return every violation so the
+            commit/push gate's ``split_violations_by_scope`` can scope by added
+            line.
 
     Returns:
         One issue per docstring whose narrative carries a run-on sentence, capped
-        at the module limit.
+        at the module limit and scoped to the changed lines unless
+        *defer_scope_to_caller* is True or *all_changed_lines* is None.
     """
     if is_test_file(file_path) or is_hook_infrastructure(file_path):
         return []
@@ -2721,25 +2781,37 @@ def check_docstring_runon_sentence(content: str, file_path: str) -> list[str]:
         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
-    ):
+    all_violations_in_walk_order: list[tuple[range, str]] = []
+    for (
+        each_line_number,
+        each_label,
+        each_docstring,
+        each_span,
+    ) 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(
+        message = (
             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 "
+            "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]
+        all_violations_in_walk_order.append((each_span, message))
+    scoped_issues = _scope_violations_to_changed_lines(
+        all_violations_in_walk_order,
+        all_changed_lines,
+        defer_scope_to_caller,
+    )
+    return scoped_issues[:MAX_DOCSTRING_RUNON_SENTENCE_ISSUES]
 
 
-def check_docstring_prose_wall_without_illustration(content: str, file_path: str) -> list[str]:
+def check_docstring_prose_wall_without_illustration(
+    content: str,
+    file_path: str,
+    all_changed_lines: set[int] | None = None,
+    defer_scope_to_caller: bool = False,
+) -> list[str]:
     """Flag a summary that tells for many sentences and shows nothing.
 
     A reader trusts the opening to paint a scene. A run of short sentences with
@@ -2754,13 +2826,28 @@ def check_docstring_prose_wall_without_illustration(content: str, file_path: str
     Past the prose-line limit with no ``::`` listing and no ``>>>`` doctest, this
     fires. A narrative that shows a worked example, or one at the limit, passes.
 
+    The caller passes the reconstructed full file as *content* so ``ast.parse``
+    sees a complete module. Findings are then scoped to *all_changed_lines* so an
+    Edit blocks on a wall it just introduced while a pre-existing far-away wall
+    on an untouched definition does not block the edit.
+
     Args:
-        content: The source text to inspect.
+        content: The source text to inspect - the reconstructed full file on an
+            Edit so the parse succeeds.
         file_path: The path the source will be written to, used for exemptions.
+        all_changed_lines: Post-edit line numbers the current edit touched, or
+            None to treat the whole file as in scope. When provided, a finding
+            blocks only when its definition-through-docstring span intersects
+            the changed lines.
+        defer_scope_to_caller: When True, return every violation so the
+            commit/push gate's ``split_violations_by_scope`` can scope by added
+            line.
 
     Returns:
         One issue per summary that runs a wall of sentences with no worked
-        example, capped at the issue limit for the rule.
+        example, capped at the issue limit for the rule and scoped to the
+        changed lines unless *defer_scope_to_caller* is True or
+        *all_changed_lines* is None.
     """
     if is_test_file(file_path) or is_hook_infrastructure(file_path):
         return []
@@ -2768,25 +2855,32 @@ def check_docstring_prose_wall_without_illustration(content: str, file_path: str
         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
-    ):
+    all_violations_in_walk_order: list[tuple[range, str]] = []
+    for (
+        each_line_number,
+        each_label,
+        each_docstring,
+        each_span,
+    ) in _documentable_docstring_targets(parsed_tree):
         prose_lines, has_illustration = _docstring_narrative_partition(each_docstring)
         if has_illustration:
             continue
         prose_line_count = len(prose_lines)
         if prose_line_count <= DOCSTRING_NARRATIVE_PROSE_LINE_LIMIT:
             continue
-        issues.append(
+        message = (
             f"Line {each_line_number}: {each_label} summary runs {prose_line_count} "
             "narrative lines with no worked example - show, don't tell: swap the wall for a "
             "'::' listing (a sample input, an annotated outcome, ok/flag contrast rows) and "
             "keep the narrative to a few short lines (plain-illustrative-docstrings)"
         )
-        if len(issues) >= MAX_DOCSTRING_PROSE_WALL_ISSUES:
-            break
-    return issues[:MAX_DOCSTRING_PROSE_WALL_ISSUES]
+        all_violations_in_walk_order.append((each_span, message))
+    scoped_issues = _scope_violations_to_changed_lines(
+        all_violations_in_walk_order,
+        all_changed_lines,
+        defer_scope_to_caller,
+    )
+    return scoped_issues[:MAX_DOCSTRING_PROSE_WALL_ISSUES]
 
 
 def _raises_section_text(docstring_text: str) -> str: