claude-dev-env 1.83.0 → 1.84.0

package/bin/install.test.mjs

@@ -718,12 +718,13 @@ const OLD_FOLDED_HOOKS_SETTINGS = {
 };
 
 
-test('FOLDED_HOOK_RELATIVE_PATHS contains all 16 hooks removed from hooks.json', () => {
-    assert.equal(FOLDED_HOOK_RELATIVE_PATHS.size, 16);
+test('FOLDED_HOOK_RELATIVE_PATHS contains all 16 hooks removed from hooks.json plus the retired md_to_html_blocker', () => {
+    assert.equal(FOLDED_HOOK_RELATIVE_PATHS.size, 17);
     assert.ok(FOLDED_HOOK_RELATIVE_PATHS.has('blocking/write_existing_file_blocker.py'));
     assert.ok(FOLDED_HOOK_RELATIVE_PATHS.has('blocking/plain_language_blocker.py'));
     assert.ok(FOLDED_HOOK_RELATIVE_PATHS.has('blocking/code_rules_enforcer.py'));
     assert.ok(FOLDED_HOOK_RELATIVE_PATHS.has('blocking/pytest_testpaths_orphan_blocker.py'));
+    assert.ok(FOLDED_HOOK_RELATIVE_PATHS.has('blocking/md_to_html_blocker.py'));
 });
 
 
@@ -746,16 +747,25 @@ test('FOLDED_HOOK_RELATIVE_PATHS lists every hook the PreToolUse dispatcher host
         'blocking/open_questions_in_plans_blocker.py',
         'blocking/plain_language_blocker.py',
     ];
+    const retiredHooks = [
+        'blocking/md_to_html_blocker.py',
+    ];
     for (const hostedPath of dispatcherHostedHooks) {
         assert.ok(
             FOLDED_HOOK_RELATIVE_PATHS.has(hostedPath),
             `dispatcher-hosted hook ${hostedPath} must be in FOLDED_HOOK_RELATIVE_PATHS so a reinstall prunes its stale standalone entry and it does not double-run`
         );
     }
+    for (const retiredPath of retiredHooks) {
+        assert.ok(
+            FOLDED_HOOK_RELATIVE_PATHS.has(retiredPath),
+            `retired hook ${retiredPath} must be in FOLDED_HOOK_RELATIVE_PATHS so a reinstall prunes its stale standalone entry pointing at a script no longer on disk`
+        );
+    }
     assert.equal(
         FOLDED_HOOK_RELATIVE_PATHS.size,
-        dispatcherHostedHooks.length,
-        'FOLDED_HOOK_RELATIVE_PATHS must hold exactly the dispatcher-hosted hooks, no more, no fewer'
+        dispatcherHostedHooks.length + retiredHooks.length,
+        'FOLDED_HOOK_RELATIVE_PATHS must hold exactly the dispatcher-hosted hooks plus the retired hooks, no more, no fewer'
     );
 });
 
@@ -887,11 +897,12 @@ const OLD_POST_FOLDED_HOOKS_SETTINGS = {
 };
 
 
-test('POST_FOLDED_HOOK_RELATIVE_PATHS contains the three after-write hooks folded into the PostToolUse dispatcher', () => {
-    assert.equal(POST_FOLDED_HOOK_RELATIVE_PATHS.size, 3);
+test('POST_FOLDED_HOOK_RELATIVE_PATHS contains the after-write hooks and the retired md_to_html_companion', () => {
+    assert.equal(POST_FOLDED_HOOK_RELATIVE_PATHS.size, 4);
     assert.ok(POST_FOLDED_HOOK_RELATIVE_PATHS.has('validation/mypy_validator.py'));
     assert.ok(POST_FOLDED_HOOK_RELATIVE_PATHS.has('workflow/auto_formatter.py'));
     assert.ok(POST_FOLDED_HOOK_RELATIVE_PATHS.has('workflow/doc_gist_auto_publish.py'));
+    assert.ok(POST_FOLDED_HOOK_RELATIVE_PATHS.has('workflow/md_to_html_companion.py'));
 });
 
 

package/commands/CLAUDE.md

@@ -7,7 +7,6 @@ Slash-command definitions installed into `~/.claude/commands/` by `bin/install.m
 | File | Command | What it does |
 |---|---|---|
 | `commit.md` | `/commit` | Commits and pushes changes to GitHub |
-| `doc-gist.md` | `/doc-gist` | Uploads an HTML file as a secret gist and opens the htmlpreview URL |
 | `docupdate.md` | `/docupdate` | Updates documentation to match current code state |
 | `hook-log-extract.md` | `/hook-log-extract` | Extracts and formats hook log entries for a session |
 | `hook-log-init.md` | `/hook-log-init` | Initializes the Neon Postgres schema that backs the hook-log extractor (one-time per machine) |

package/docs/CODE_RULES.md

@@ -94,4 +94,4 @@ If you already have the data, don't fetch it again.
 
 ## 11. ENFORCEMENT SURFACES
 
-⚡ **Hooks** block pattern-matchable violations at Write/Edit time. 🤖 **Prompt context** carries judgment principles (SRP, Right-Sized Engineering, conservative-action, BDD discovery, docstring-prose-matches-implementation; the `/code` skill prepends strict mode for a session: no `Any`/`cast()`, immutable TypedDicts with `_encode_*`/`_decode_*` + `require_*` validation, per-module `_test_hooks.py` DI, 100% statement + branch coverage, zero mocks). 👥 **Audit rubrics** (`/check`, `packages/claude-dev-env/audit-rubrics/` categories A–Q) cover cross-file architectural concerns. Rules with documented-but-pending hook coverage live in `~/.claude/rules/*.md` and `skills/code/SKILL.md`; each names its own promotion path. The docstring-prose standard (free-form enumerations match the body) lives in `packages/claude-dev-env/rules/docstring-prose-matches-implementation.md`, enforced via Category O6 audit.
+⚡ **Hooks** block pattern-matchable violations at Write/Edit time. 🤖 **Prompt context** carries judgment principles (SRP, Right-Sized Engineering, conservative-action, BDD discovery, docstring-prose-matches-implementation; the `/code` skill prepends strict mode for a session: no `Any`/`cast()`, immutable TypedDicts with `_encode_*`/`_decode_*` + `require_*` validation, per-module `_test_hooks.py` DI, 100% statement + branch coverage, zero mocks). 👥 **Audit rubrics** (`/check`, `packages/claude-dev-env/audit-rubrics/` categories A–Q) cover cross-file architectural concerns. Rules with documented-but-pending hook coverage live in `~/.claude/rules/*.md` and `skills/code/SKILL.md`; each names its own promotion path. The docstring-prose standard (free-form enumerations match the body) lives in `packages/claude-dev-env/rules/docstring-prose-matches-implementation.md`, enforced via Category O6 audit. The diagram-first docstring standard (a summary line, then a `::` example or doctest, then a couple of short prose lines) lives in `packages/claude-dev-env/rules/plain-illustrative-docstrings.md`, enforced by the `check_docstring_runon_sentence` and `check_docstring_prose_wall_without_illustration` backstop hooks and Category O9 audit.

package/hooks/blocking/CLAUDE.md

@@ -77,7 +77,6 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `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 |
-| `md_to_html_blocker.py` | PreToolUse (Write/Edit) | Writing `.md` files when an `.html` companion is required |
 | `open_questions_in_plans_blocker.py` | PreToolUse (Write/Edit) | Plan documents with unresolved open questions |
 | `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 |
 | `plain_language_blocker.py` | PreToolUse (Write/Edit/AskUserQuestion) | Heavy or jargon words in user-facing prose |
@@ -107,8 +106,6 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | File | Role |
 |---|---|
 | `_gh_body_arg_utils.py` | Parsing helpers for `gh_body_arg_blocker.py` |
-| `_md_to_html_blocker_test_support.py` | Test fixtures shared across `md_to_html_blocker` tests |
-| `md_path_exemptions.py` | Path exemption logic for `md_to_html_blocker.py` |
 | `pr_description_body_audit.py` | Body audit logic for `pr_description_enforcer.py` |
 | `pr_description_command_parser.py` | `gh` command parsing for `pr_description_enforcer.py` |
 | `pr_description_pr_number.py` | PR number extraction logic |
@@ -119,4 +116,3 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 
 - Tests live beside each hook as `test_<hookname>.py` or `test_<hookname>_<suffix>.py`. Run with `python -m pytest <test_file>`.
 - Tunable constants live in `hooks_constants/<hook_name>_constants.py`; the verified-commit family uses `blocking/config/verified_commit_constants.py`.
-- `conftest.py` gives shared pytest fixtures for the blocking test suite.

package/hooks/blocking/code_rules_constants_config.py

@@ -23,6 +23,7 @@ from code_rules_path_utils import (  # noqa: E402
 )
 from code_rules_shared import (  # noqa: E402
     _build_parent_map,
+    docstring_line_numbers,
     get_file_extension,
     is_migration_file,
     is_test_file,
@@ -110,6 +111,7 @@ def _scan_function_body_constants(content: str) -> list[str]:
     """
     advisory_issues: list[str] = []
     lines = content.split("\n")
+    all_docstring_line_numbers = docstring_line_numbers(content)
     function_indent_stack: list[int] = []
     constant_pattern = re.compile(r"^([A-Z][A-Z0-9_]{2,})(?:\s*:\s*[^=]+)?\s*=\s*[^=]")
 
@@ -119,6 +121,9 @@ def _scan_function_body_constants(content: str) -> list[str]:
         if not stripped:
             continue
 
+        if each_line_number in all_docstring_line_numbers:
+            continue
+
         indent = len(each_line) - len(each_line.lstrip())
 
         while function_indent_stack and indent <= function_indent_stack[-1] and not stripped.startswith(("#", "@", ")")):

package/hooks/blocking/code_rules_docstrings.py

@@ -53,6 +53,8 @@ from hooks_constants.blocking_check_limits import (  # noqa: E402
     ALL_ZIPFILE_WRITE_MODE_VALUES,
     DOCSTRING_FALLBACK_BRANCH_MINIMUM_ROUTE_COUNT,
     DOCSTRING_LARGE_ZIP_FILE_EXCEPTION_NAME,
+    DOCSTRING_NARRATIVE_LINE_JOIN_SEPARATOR,
+    DOCSTRING_NARRATIVE_PROSE_LINE_LIMIT,
     DOCSTRING_REFERENCE_MARKER_WINDOW,
     DOCSTRING_RUNON_SENTENCE_BOUNDARY_PATTERN,
     DOCSTRING_RUNON_SENTENCE_WORD_LIMIT,
@@ -72,6 +74,7 @@ from hooks_constants.blocking_check_limits import (  # noqa: E402
     MAX_DOCSTRING_MARK_GLYPH_ENUMERATION_ISSUES,
     MAX_DOCSTRING_NO_CONSUMER_CLAIM_ISSUES,
     MAX_DOCSTRING_NO_NETWORK_CLAIM_ISSUES,
+    MAX_DOCSTRING_PROSE_WALL_ISSUES,
     MAX_DOCSTRING_RAISES_LARGEZIPFILE_ISSUES,
     MAX_DOCSTRING_RETURNS_PLURAL_CARDINALITY_ISSUES,
     MAX_DOCSTRING_RUNON_SENTENCE_ISSUES,
@@ -2562,14 +2565,71 @@ def _is_narrative_cut_header(stripped_line: str) -> bool:
     )
 
 
-def _docstring_narrative_text(docstring_text: str) -> str:
-    narrative_lines: list[str] = []
-    for each_line in docstring_text.splitlines():
-        stripped_line = each_line.strip()
+def _docstring_narrative_partition(docstring_text: str) -> tuple[list[str], bool]:
+    """Split a docstring narrative into its prose lines and whether it shows an example.
+
+    Walk the narrative up to the first ``Args:``/``Returns:`` cut header and sort
+    every line into one of two buckets::
+
+        Render the report so the reader sees how it ended.   <- prose line
+        A finished run versus an interrupted one::           <- prose line (opener)
+            theme_42 -- interrupted -> marked in-flight       -- indented example body
+            OK:   a clean run reads differently in the log    -- indented example body
+        The reader reads the final outcome at a glance.      <- prose line
+
+    A ``>>>`` doctest region and a ``::`` block with an indented body both count as
+    an illustration, so their lines never join the prose bucket. The caller reads
+    the prose count to size the wall and the flag to know whether an example is present.
+    """
+    prose_lines: list[str] = []
+    has_illustration = False
+    all_lines = docstring_text.splitlines()
+    total_lines = len(all_lines)
+    line_index = 0
+    while line_index < total_lines:
+        raw_line = all_lines[line_index]
+        stripped_line = raw_line.strip()
         if _is_narrative_cut_header(stripped_line):
             break
-        narrative_lines.append(stripped_line)
-    return " ".join(narrative_lines)
+        if stripped_line.startswith(">>>"):
+            has_illustration = True
+            line_index += 1
+            while line_index < total_lines:
+                inner_stripped = all_lines[line_index].strip()
+                if not inner_stripped or _is_narrative_cut_header(inner_stripped):
+                    break
+                line_index += 1
+            continue
+        if stripped_line.endswith("::"):
+            opener_indent = len(raw_line) - len(raw_line.lstrip())
+            probe_index = line_index + 1
+            has_indented_body = False
+            while probe_index < total_lines:
+                probe_raw = all_lines[probe_index]
+                probe_stripped = probe_raw.strip()
+                if not probe_stripped:
+                    probe_index += 1
+                    continue
+                probe_indent = len(probe_raw) - len(probe_raw.lstrip())
+                if probe_indent > opener_indent:
+                    has_indented_body = True
+                    probe_index += 1
+                    continue
+                break
+            if has_indented_body:
+                has_illustration = True
+                prose_lines.append(stripped_line)
+                line_index = probe_index
+                continue
+        if stripped_line:
+            prose_lines.append(stripped_line)
+        line_index += 1
+    return prose_lines, has_illustration
+
+
+def _docstring_narrative_text(docstring_text: str) -> str:
+    prose_lines, _has_illustration = _docstring_narrative_partition(docstring_text)
+    return DOCSTRING_NARRATIVE_LINE_JOIN_SEPARATOR.join(prose_lines)
 
 
 def _sentence_word_count(sentence_text: str) -> int:
@@ -2675,6 +2735,56 @@ def check_docstring_runon_sentence(content: str, file_path: str) -> list[str]:
     return issues[:MAX_DOCSTRING_RUNON_SENTENCE_ISSUES]
 
 
+def check_docstring_prose_wall_without_illustration(content: str, file_path: str) -> 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
+    no worked example leaves the reader piecing that scene together alone::
+
+        A calm voyage ends well for every vessel.            <- one more line
+        A halted voyage marks the vessel it neared.          <- and another
+        ... more like these, no worked example ...           flag: a wall, no scene
+        A calm voyage versus a halted one::                  ok: a worked example
+            a lone vessel -- halted -> marked mid-voyage
+
+    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.
+
+    Args:
+        content: The source text to inspect.
+        file_path: The path the source will be written to, used for exemptions.
+
+    Returns:
+        One issue per summary that runs a wall of sentences with no worked
+        example, capped at the issue limit for the rule.
+    """
+    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
+    ):
+        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(
+            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]
+
+
 def _raises_section_text(docstring_text: str) -> str:
     docstring_lines = docstring_text.splitlines()
     raises_section_lines: list[str] = []

package/hooks/blocking/code_rules_enforcer.py

@@ -87,6 +87,7 @@ from code_rules_docstrings import (  # noqa: E402
     check_docstring_no_consumer_claim,
     check_docstring_no_inline_literal_claim,
     check_docstring_no_network_claim_with_metadata_access,
+    check_docstring_prose_wall_without_illustration,
     check_docstring_punctuation_mark_enumeration_coverage,
     check_docstring_raises_unraisable_largezipfile,
     check_docstring_returns_plural_cardinality,
@@ -351,6 +352,9 @@ def validate_content(
             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_docstring_prose_wall_without_illustration(effective_content, file_path)
+        )
         all_issues.extend(
             check_module_docstring_names_public_checks(effective_content, file_path)
         )

package/hooks/blocking/code_rules_magic_values.py

@@ -17,6 +17,7 @@ from code_rules_path_utils import (  # noqa: E402
 )
 from code_rules_shared import (  # noqa: E402
     _extract_fstring_literal_parts,
+    docstring_line_numbers,
     is_test_file,
 )
 
@@ -156,6 +157,7 @@ def check_magic_values(content: str, file_path: str) -> list[str]:
 
     issues = []
     lines = content.split("\n")
+    all_docstring_line_numbers = docstring_line_numbers(content)
     is_inside_function = False
 
     number_pattern = re.compile(r"(?<![.\w])(\d+\.?\d*)(?![.\w])")
@@ -167,6 +169,9 @@ def check_magic_values(content: str, file_path: str) -> list[str]:
         if not stripped:
             continue
 
+        if each_line_number in all_docstring_line_numbers:
+            continue
+
         if re.match(r"^(async\s+)?def\s+\w+", stripped):
             is_inside_function = True
             continue

package/hooks/blocking/code_rules_naming_collection.py

@@ -436,12 +436,17 @@ def _contradicting_polarity_pair(target_name: str, called_name: str) -> tuple[st
 def check_polarity_name_contradiction(content: str, file_path: str) -> list[str]:
     """Flag a boolean assignment whose target and callee assert opposite polarity.
 
-    Catches the self-contradicting statement ``is_inside_allowed =
-    _point_hits_any_forbidden(...)`` — a target name carrying one polarity token
-    (``allowed``) assigned directly from a single call whose callee name carries
-    the antonym token (``forbidden``). One side lies about the behavior, so the
-    reader cannot trust either name. Rename the callee to a neutral form that
-    reads truthfully at every call site.
+    ::
+
+        is_inside_allowed = _point_hits_any_forbidden(...)
+                 ^^^^^^^                    ^^^^^^^^^
+                 allowed         vs.        forbidden      ⚠ the two names clash
+        ok:   is_inside_allowed = _point_inside_allowed_region(...)
+        flag: is_inside_allowed = _point_hits_any_forbidden(...)
+
+    The target token and the callee token contradict each other, so the reader
+    cannot tell which name states the truth. Rename the callee to a neutral form
+    the two names agree on at every call site.
     """
     if is_test_file(file_path):
         return []

package/hooks/blocking/code_rules_shared.py

@@ -273,6 +273,40 @@ def is_migration_file(file_path: str) -> bool:
     return any(pattern.replace("\\", "/") in path_lower for pattern in ALL_MIGRATION_PATH_PATTERNS)
 
 
+def docstring_line_numbers(content: str) -> set[int]:
+    """Return every source line that sits inside a string-literal statement.
+
+    A diagram-first docstring often draws its point across several lines, and
+    those lines can hold a bare number (a row marker) or a contrast row
+    (``flag: is_ok = do_thing(...)``). Those are prose, not code, so a
+    line-based lint check that reads them as literals fires a false positive.
+    This walks the parsed source and collects the line numbers spanned by every
+    string-literal expression statement — module, class, and function
+    docstrings, plus any bare string statement — so those checks can skip them.
+    Unparseable source yields an empty set.
+
+    Args:
+        content: The Python source to scan.
+
+    Returns:
+        The 1-indexed line numbers that fall inside a string-literal statement.
+    """
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return set()
+    all_docstring_line_numbers: set[int] = set()
+    for each_node in ast.walk(parsed_tree):
+        if not (isinstance(each_node, ast.Expr) and _statement_is_docstring(each_node)):
+            continue
+        end_line_number = each_node.end_lineno
+        if end_line_number is None:
+            continue
+        for each_line_number in range(each_node.lineno, end_line_number + 1):
+            all_docstring_line_numbers.add(each_line_number)
+    return all_docstring_line_numbers
+
+
 def _build_parent_map(module_tree: ast.Module) -> dict[int, ast.AST]:
     """Map child node id() to its parent node for ancestor walking."""
     parent_by_child_id: dict[int, ast.AST] = {}

package/hooks/blocking/duplicate_rmtree_helper_blocker.py

@@ -72,10 +72,10 @@ def path_is_exempt(file_path: str) -> bool:
     Returns:
         True when the path's basename is the canonical shared-helper home, an
         rmtree-blocker hook source, one of the existing in-repo definition sites
-        (session_env_cleanup.py, _md_to_html_blocker_test_support.py,
-        teardown_worktrees.py), or a test file. A definition there is intentional.
-        Basename equality (not substring containment) prevents a sibling whose name
-        merely contains an exempt fragment from bypassing the block.
+        (session_env_cleanup.py, teardown_worktrees.py), or a test file. A
+        definition there is intentional. Basename equality (not substring
+        containment) prevents a sibling whose name merely contains an exempt
+        fragment from bypassing the block.
     """
     normalized_path = file_path.replace("\\", "/")
     file_name = normalized_path.rsplit("/", 1)[-1]

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