claude-dev-env 1.75.0 → 1.77.0

package/_shared/pr-loop/scripts/code_rules_gate.py

@@ -39,6 +39,13 @@ from pr_loop_shared_constants.code_rules_gate_constants import (  # noqa: E402
     TEST_FILENAME_PREFIX,
     TESTS_PATH_SEGMENT,
 )
+from pr_loop_shared_constants.inline_duplicate_body_span_constants import (  # noqa: E402
+    INLINE_DUPLICATE_BODY_ENCLOSING_LINE_GROUP_INDEX,
+    INLINE_DUPLICATE_BODY_ENCLOSING_SPAN_GROUP_INDEX,
+    INLINE_DUPLICATE_BODY_HELPER_LINE_GROUP_INDEX,
+    INLINE_DUPLICATE_BODY_HELPER_SPAN_GROUP_INDEX,
+    INLINE_DUPLICATE_BODY_VIOLATION_PATTERN,
+)
 
 
 ValidateContentCallable = Callable[..., list[str]]
@@ -1038,6 +1045,43 @@ def duplicate_body_span_range(violation_text: str) -> range | None:
     return range(definition_line, definition_line + line_span)
 
 
+def inline_duplicate_body_span_lines(violation_text: str) -> frozenset[int] | None:
+    """Return the union of both spans of a same-file inline-duplicate issue, or None.
+
+    The same-file inline-duplicate message names two functions that share a body —
+    the helper and the enclosing function carrying the inline copy — and the live
+    Write/Edit hook scopes the violation by the UNION of both spans, blocking when
+    an edit touches either function. So the message carries both spans: ``(inline
+    duplicate body spans: helper at line H spanning P lines, enclosing at line E
+    spanning Q lines)``. The two spans can be disjoint (an unrelated function may
+    sit between the helper and its inline copy), so this returns the union as a
+    line-number set rather than a single contiguous range — a range covering the
+    gap would wrongly block an edit confined to that intervening function, which
+    the PreToolUse path leaves unflagged.
+
+    Args:
+        violation_text: A single violation string emitted by the enforcer.
+
+    Returns:
+        The frozenset of every line in the helper span and the enclosing span, or
+        None when the text is not a same-file inline-duplicate violation.
+    """
+    span_match = INLINE_DUPLICATE_BODY_VIOLATION_PATTERN.search(violation_text)
+    if span_match is None:
+        return None
+    helper_line = int(span_match.group(INLINE_DUPLICATE_BODY_HELPER_LINE_GROUP_INDEX))
+    helper_span = int(span_match.group(INLINE_DUPLICATE_BODY_HELPER_SPAN_GROUP_INDEX))
+    enclosing_line = int(
+        span_match.group(INLINE_DUPLICATE_BODY_ENCLOSING_LINE_GROUP_INDEX)
+    )
+    enclosing_span = int(
+        span_match.group(INLINE_DUPLICATE_BODY_ENCLOSING_SPAN_GROUP_INDEX)
+    )
+    helper_lines = range(helper_line, helper_line + helper_span)
+    enclosing_lines = range(enclosing_line, enclosing_line + enclosing_span)
+    return frozenset(helper_lines) | frozenset(enclosing_lines)
+
+
 def _all_span_range_extractors() -> tuple[Callable[[str], range | None], ...]:
     return (
         function_length_span_range,
@@ -1084,11 +1128,15 @@ def split_violations_by_scope(
 
     Returns:
         Tuple ``(blocking, advisory)``. When *all_added_line_numbers* is
-        None, every issue is blocking. Every diff-scoped violation
-        (function-length, HOME/TMP isolation, banned-noun, duplicate-body)
-        carries an enclosing-unit span fragment that ``enclosing_span_range``
-        reconstructs through one shared extractor registry; such a violation is
-        blocking
+        None, every issue is blocking. A same-file inline-duplicate violation
+        carries both the helper span and the enclosing span;
+        ``inline_duplicate_body_span_lines`` reconstructs their union as a
+        line-number set, and the violation is blocking when an added line falls
+        in either span — matching the live Write/Edit hook's union scoping. Every
+        other diff-scoped violation (function-length, HOME/TMP isolation,
+        banned-noun, cross-file duplicate-body) carries one enclosing-unit span
+        fragment that ``enclosing_span_range`` reconstructs through one shared
+        extractor registry; such a violation is blocking
         when its declared span intersects the added lines (the unit grew or its
         signature changed in this diff) and advisory otherwise (a pre-existing
         untouched unit). Every other issue is blocking when its ``Line N:``
@@ -1099,6 +1147,13 @@ def split_violations_by_scope(
     blocking: list[str] = []
     advisory: list[str] = []
     for each_issue in all_issues:
+        inline_duplicate_lines = inline_duplicate_body_span_lines(each_issue)
+        if inline_duplicate_lines is not None:
+            if inline_duplicate_lines & all_added_line_numbers:
+                blocking.append(each_issue)
+            else:
+                advisory.append(each_issue)
+            continue
         span_range = enclosing_span_range(each_issue)
         if span_range is not None:
             if any(each_line in all_added_line_numbers for each_line in span_range):

package/_shared/pr-loop/scripts/pr_loop_shared_constants/CLAUDE.md

@@ -9,6 +9,7 @@ Named constants for every script in `_shared/pr-loop/scripts/`. Each module owns
 | `claude_permissions_constants.py` | `grant_project_claude_permissions.py` and `revoke_project_claude_permissions.py` — permission rule strings and settings.json keys |
 | `claude_settings_keys_constants.py` | Top-level `~/.claude/settings.json` key names used across the permission helpers |
 | `code_rules_gate_constants.py` | `code_rules_gate.py` — file extensions, git diff subcommands, test filename patterns |
+| `inline_duplicate_body_span_constants.py` | `code_rules_gate.py` — regex and capture-group indices for the same-file inline-duplicate message, which carries both the helper and the enclosing span the gate reconstructs the union from |
 | `fix_hookspath_constants.py` | `fix_hookspath.py` — verification suffix and related strings |
 | `post_audit_thread_constants.py` | `post_audit_thread.py` — HTTP status codes, retry counts, GitHub API paths |
 | `preflight_constants.py` | `preflight.py` — env-var names, git subcommands, pytest exit codes, test discovery patterns |

package/_shared/pr-loop/scripts/pr_loop_shared_constants/inline_duplicate_body_span_constants.py

@@ -0,0 +1,22 @@
+"""Pattern and capture-group constants for the same-file inline-duplicate span.
+
+The same-file inline-duplicate enforcer message names two functions that share a
+body — the helper and the enclosing function carrying the inline copy — and the
+live Write/Edit hook scopes the violation by the UNION of both spans. So the
+message carries both spans, and ``code_rules_gate.inline_duplicate_body_span_lines``
+parses them to reconstruct that union when the commit/push gate scopes a deferred
+violation by added line. These constants describe the message suffix the enforcer
+emits: ``(inline duplicate body spans: helper at line H spanning P lines,
+enclosing at line E spanning Q lines)``.
+"""
+
+import re
+
+INLINE_DUPLICATE_BODY_VIOLATION_PATTERN: re.Pattern[str] = re.compile(
+    r"\(inline duplicate body spans: helper at line (\d+) spanning (\d+) lines, "
+    r"enclosing at line (\d+) spanning (\d+) lines\)"
+)
+INLINE_DUPLICATE_BODY_HELPER_LINE_GROUP_INDEX: int = 1
+INLINE_DUPLICATE_BODY_HELPER_SPAN_GROUP_INDEX: int = 2
+INLINE_DUPLICATE_BODY_ENCLOSING_LINE_GROUP_INDEX: int = 3
+INLINE_DUPLICATE_BODY_ENCLOSING_SPAN_GROUP_INDEX: int = 4

package/_shared/pr-loop/scripts/tests/test_code_rules_gate.py

@@ -32,7 +32,7 @@ def _load_gate_module() -> ModuleType:
 gate_module = _load_gate_module()
 
 
-def _load_duplicate_body_check() -> Callable[..., list[str]]:
+def _load_duplicate_body_module() -> ModuleType:
     package_root = gate_module.resolve_claude_dev_env_root(
         Path(gate_module.__file__).resolve()
     )
@@ -42,10 +42,16 @@ def _load_duplicate_body_check() -> Callable[..., list[str]]:
     assert spec.loader is not None
     module = importlib.util.module_from_spec(spec)
     spec.loader.exec_module(module)
-    return module.check_duplicate_function_body_across_files
+    return module
 
 
-check_duplicate_function_body_across_files = _load_duplicate_body_check()
+_duplicate_body_module = _load_duplicate_body_module()
+check_duplicate_function_body_across_files = (
+    _duplicate_body_module.check_duplicate_function_body_across_files
+)
+check_same_file_inline_duplicate_body = (
+    _duplicate_body_module.check_same_file_inline_duplicate_body
+)
 
 
 def run_git_in_repository(repository_root: Path, *arguments: str) -> str:
@@ -767,6 +773,144 @@ def test_split_violations_advises_duplicate_body_when_span_misses_added_lines(
     assert blocking == []
 
 
+_INLINE_DUPLICATE_MESSAGE_HELPER_FIRST = (
+    "Function '_wait_for_render' duplicates an inline block in '_navigate_then_wait'"
+    " — this function body is also present inline (Reuse before create / DRY) "
+    "(inline duplicate body spans: helper at line 4 spanning 10 lines, "
+    "enclosing at line 16 spanning 11 lines)"
+)
+
+
+def test_inline_duplicate_body_span_lines_unions_helper_and_enclosing_spans() -> None:
+    """The same-file inline-duplicate message carries both spans, and the gate
+    recovers their union as a line-number set so a touch of either function blocks —
+    mirroring the live Write/Edit hook's union scoping."""
+    span_lines = gate_module.inline_duplicate_body_span_lines(
+        _INLINE_DUPLICATE_MESSAGE_HELPER_FIRST
+    )
+    assert span_lines == frozenset(range(4, 14)) | frozenset(range(16, 27))
+
+
+def test_inline_duplicate_body_span_lines_returns_none_for_other_messages() -> None:
+    """A cross-file duplicate-body message carries the single-span suffix, which the
+    inline-duplicate extractor must not claim — so the gate routes it to the
+    single-range extractor registry instead."""
+    cross_file_message = (
+        "Function 'strip' duplicates existing_helper.py::strip — extract a shared "
+        "helper (duplicate body span at line 3, spanning 5 lines)"
+    )
+    assert gate_module.inline_duplicate_body_span_lines(cross_file_message) is None
+
+
+def test_inline_duplicate_blocks_when_only_enclosing_copy_added() -> None:
+    """The finding's real-world shape: the helper pre-exists (untouched) and a copy
+    is added INTO a growing enclosing function. An added line in the enclosing span
+    alone must block, because the live Write/Edit hook scopes by the union of both
+    spans and blocks the same edit."""
+    added_line_in_enclosing_only = 18
+    blocking, advisory = gate_module.split_violations_by_scope(
+        [_INLINE_DUPLICATE_MESSAGE_HELPER_FIRST],
+        all_added_line_numbers={added_line_in_enclosing_only},
+    )
+    assert blocking == [_INLINE_DUPLICATE_MESSAGE_HELPER_FIRST]
+    assert advisory == []
+
+
+def test_inline_duplicate_blocks_when_only_helper_copy_added() -> None:
+    """The mirror case: an edit touching only the helper span blocks too, since the
+    union covers both functions."""
+    added_line_in_helper_only = 5
+    blocking, advisory = gate_module.split_violations_by_scope(
+        [_INLINE_DUPLICATE_MESSAGE_HELPER_FIRST],
+        all_added_line_numbers={added_line_in_helper_only},
+    )
+    assert blocking == [_INLINE_DUPLICATE_MESSAGE_HELPER_FIRST]
+    assert advisory == []
+
+
+def test_inline_duplicate_advises_when_gap_line_added() -> None:
+    """An edit confined to an unrelated function that sits strictly between the
+    helper (lines 4-13) and the enclosing copy (lines 16-26) — line 14, in the gap —
+    must not block, matching the live hook that leaves such an edit unflagged. A
+    single contiguous range over both spans would wrongly block this; the union set
+    keeps the gap out of scope."""
+    gap_line_between_spans = 14
+    blocking, advisory = gate_module.split_violations_by_scope(
+        [_INLINE_DUPLICATE_MESSAGE_HELPER_FIRST],
+        all_added_line_numbers={gap_line_between_spans},
+    )
+    assert advisory == [_INLINE_DUPLICATE_MESSAGE_HELPER_FIRST]
+    assert blocking == []
+
+
+_INLINE_DUPLICATE_END_TO_END_SOURCE = (
+    "import asyncio\n"
+    "\n"
+    "\n"
+    "async def _wait_for_render(automation: object) -> None:\n"
+    "    assert automation.detector is not None\n"
+    "    try:\n"
+    "        await automation.detector.wait_for_element(selector)\n"
+    "    except (TimeoutError, RuntimeError) as render_error:\n"
+    "        logger.warning('did not render: %s', render_error)\n"
+    "\n"
+    "\n"
+    "async def _navigate_then_wait(automation: object) -> None:\n"
+    "    await automation.cdp.navigate(url)\n"
+    "    assert automation.detector is not None\n"
+    "    try:\n"
+    "        await automation.detector.wait_for_element(selector)\n"
+    "    except (TimeoutError, RuntimeError) as render_error:\n"
+    "        logger.warning('did not render: %s', render_error)\n"
+)
+
+
+def test_gate_blocks_inline_duplicate_when_only_enclosing_copy_is_added() -> None:
+    """End-to-end parity check for the finding's real-world shape. The helper is
+    defined first (pre-existing, untouched) and the inline copy lives in a later
+    enclosing function; an edit that adds only the enclosing copy lines makes the
+    live Write/Edit hook BLOCK. The deferred message the commit/push gate re-scopes
+    must produce the same verdict — blocking, not advisory — so the two enforcement
+    surfaces agree.
+    """
+    enclosing_definition_line = (
+        _INLINE_DUPLICATE_END_TO_END_SOURCE.splitlines().index(
+            "async def _navigate_then_wait(automation: object) -> None:"
+        )
+        + 1
+    )
+    enclosing_added_lines = set(range(enclosing_definition_line, enclosing_definition_line + 6))
+
+    pretooluse_issues = check_same_file_inline_duplicate_body(
+        _INLINE_DUPLICATE_END_TO_END_SOURCE,
+        "account_switcher.py",
+        all_changed_lines=enclosing_added_lines,
+    )
+    assert any("_wait_for_render" in each_issue for each_issue in pretooluse_issues), (
+        "The live Write/Edit path must block when the enclosing copy is added, "
+        f"got: {pretooluse_issues}"
+    )
+
+    deferred_issues = check_same_file_inline_duplicate_body(
+        _INLINE_DUPLICATE_END_TO_END_SOURCE,
+        "account_switcher.py",
+        all_changed_lines=enclosing_added_lines,
+        defer_scope_to_caller=True,
+    )
+    blocking, advisory = gate_module.split_violations_by_scope(
+        deferred_issues, enclosing_added_lines
+    )
+    assert any("_wait_for_render" in each_issue for each_issue in blocking), (
+        "The commit/push gate must reconstruct the union scope and BLOCK the same "
+        f"enclosing-only edit the live hook blocks, got blocking: {blocking}, "
+        f"advisory: {advisory}"
+    )
+    assert advisory == [], (
+        "No inline-duplicate violation may land in advisory when the gate and the "
+        f"live hook agree on blocking, got advisory: {advisory}"
+    )
+
+
 def test_collect_partitioned_violations_advises_pre_existing_sibling_duplicate(
     temporary_git_repository: Path,
 ) -> None:

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/docs/CODE_RULES.md

@@ -23,7 +23,7 @@ Compact reference for agents. ⚡ marks rules enforced by `code_rules_enforcer.p
 
 `code_rules_enforcer.py` blocks each of these at Write/Edit and explains the specific violation when it fires; exact patterns and exemption lists live in the hook:
 
-no new comments · imports at top · logging format args (`log_*("...", arg)`) · no magic values in production bodies (0, 1, -1 exempt) · UPPER_SNAKE constants only in `config/` (exempt: `config/*`, `/migrations/`, workflow registries `/workflow/` + `_tab.py` + `/states.py` + `/modules.py`, test files) · no hardcoded user home paths · guarded `sys.path.insert` · no unused module-level imports · banned identifiers (`ctx`, `cfg`, `msg`, `btn`, `idx`, `cnt`, `tmp`, `elem`, `val`) · banned function prefixes (`handle_`, `process_`, `manage_`, `do_`) · no type escape hatches (`Any` import, `cast()`, inline `Any`, a parameter typed bare `object` whose body reads `param.attribute`) outside boundary files · no bare/broad `except` · no `Any` in signatures or class attributes · no stub bodies (`pass`/`...`/`raise NotImplementedError`) outside abstract/Protocol · TypedDict `_encode_*`/`_decode_*` companions in the same module · no test-mode branching in production (use dependency injection) · no thin wrapper modules · Google-style docstrings on public functions with `Args:` matching the signature · boolean names prefixed `is_`/`has_`/`should_`/`can_`/`was_`/`did_` (assignments AND bool-typed parameters) · must-check returns (`find_and_click`, `write_outcome`) assigned and checked · known pytest fixture parameters in test files annotated with their single documented type (`tmp_path: Path`, `monkeypatch: pytest.MonkeyPatch`, `capsys`, `caplog`, `request`, …) · known pytest fixture parameters a test function declares but never references (drop the unused parameter — pytest still pays its setup cost)
+no new comments · imports at top · logging format args (`log_*("...", arg)`) · no `%s`/`%d` printf tokens in a `str.format`-logger message (`log_*` imported from `automation_logging`; `str.format` drops the args — use `{}`) · no magic values in production bodies (0, 1, -1 exempt) · UPPER_SNAKE constants only in `config/` (exempt: `config/*`, `/migrations/`, workflow registries `/workflow/` + `_tab.py` + `/states.py` + `/modules.py`, test files) · no hardcoded user home paths · guarded `sys.path.insert` · no unused module-level imports · banned identifiers (`ctx`, `cfg`, `msg`, `btn`, `idx`, `cnt`, `tmp`, `elem`, `val`) · banned function prefixes (`handle_`, `process_`, `manage_`, `do_`) · no type escape hatches (`Any` import, `cast()`, inline `Any`, a parameter typed bare `object` whose body reads `param.attribute`) outside boundary files · no bare/broad `except` · no `Any` in signatures or class attributes · no stub bodies (`pass`/`...`/`raise NotImplementedError`) outside abstract/Protocol · TypedDict `_encode_*`/`_decode_*` companions in the same module · no test-mode branching in production (use dependency injection) · no thin wrapper modules · Google-style docstrings on public functions with `Args:` matching the signature · boolean names prefixed `is_`/`has_`/`should_`/`can_`/`was_`/`did_` (assignments AND bool-typed parameters) · must-check returns (`find_and_click`, `write_outcome`) assigned and checked · known pytest fixture parameters in test files annotated with their single documented type (`tmp_path: Path`, `monkeypatch: pytest.MonkeyPatch`, `capsys`, `caplog`, `request`, …) · known pytest fixture parameters a test function declares but never references (drop the unused parameter — pytest still pays its setup cost)
 
 Test files are exempt from most checks. The one annotation the test-file exemption does NOT cover is a known pytest builtin fixture parameter: `tmp_path`, `monkeypatch`, `capsys`, `capfd`, `caplog`, `request`, and `tmp_path_factory` each have a single documented injected type, so the gate requires that annotation (`tmp_path: Path`) even inside a test file. The same set of fixtures is also subject to a use check: a pytest-collected test function that declares one of these parameters and never references it in its body fails the gate, because pytest materializes the fixture's setup (the temp directory, the monkeypatch context, the output capture) on every run whether or not the body reads the value — drop the unused parameter. A parameter counts as referenced when its name is read, augmented-assigned, or deleted anywhere in the body, including inside a nested function or comprehension. Only pytest-collectable functions are inspected — those at module top level or defined directly in a class body; a function nested inside another function's body is a local helper pytest never collects, so its fixture-named parameter is exempt. A `@pytest.fixture`-decorated function is exempt from the use check, since injecting one fixture into another purely to order its setup is intentional. Ordinary test parameters stay exempt from both checks. See also the file-global constants use-count rule: [`rules/file-global-constants.md`](../rules/file-global-constants.md).
 

package/hooks/blocking/CLAUDE.md

@@ -30,8 +30,8 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `code_rules_dead_dataclass_field.py` | Dataclass fields with no consuming references |
 | `code_rules_dead_module_constant.py` | `UPPER_SNAKE` constants in `*_constants.py` modules with no importers |
 | `code_rules_docstrings.py` | Google-style docstrings; `Args:` section matches signature; fallback-branch coverage |
-| `code_rules_duplicate_body.py` | Functions whose bodies match another function's body in the same file |
-| `code_rules_imports_logging.py` | Imports at top of file; logging format-arg style |
+| `code_rules_duplicate_body.py` | A function body copied from a sibling module, or a helper body inlined as a block inside a larger function in the same file |
+| `code_rules_imports_logging.py` | Imports at top of file; logging format-arg style; printf tokens in `str.format`-logger messages |
 | `code_rules_magic_values.py` | No magic numbers or strings in production code bodies |
 | `code_rules_mock_completeness.py` | Mock calls that skip required arguments |
 | `code_rules_naming_collection.py` | Collection names must use `all_*` prefix |

package/hooks/blocking/claude_md_orphan_file_blocker.py

@@ -1,16 +1,20 @@
 #!/usr/bin/env python3
-"""PreToolUse hook: blocks a per-directory CLAUDE.md table that names a file absent from its subtree.
+"""PreToolUse hook: blocks a per-directory CLAUDE.md that names a file absent from its subtree.
 
 A per-directory ``CLAUDE.md`` documents the files reachable from its own
-directory in a markdown table whose first column names each file in backticks.
-When a first-column cell names a bare filename that exists nowhere under the scan
+directory in a markdown table whose first column names each file in backticks,
+and shows run commands inside fenced code blocks that invoke those files. When a
+first-column cell, or an interpreter invocation inside a fenced run command
+(``python script.py``), names a bare filename that exists nowhere under the scan
 root (the CLAUDE.md directory's parent, which covers the directory, its
-subdirectories, and its siblings), the table points a reader at a file that is
-not there. This hook fires on Write, Edit, and MultiEdit targeting a file named
-``CLAUDE.md`` and blocks the write when any such cell names a file absent from
-the scan root. A table block whose own region declares an explicit relative-path
-source (a ``../`` token) documents files outside the subtree, so that block's
-rows are left alone — the exemption is scoped to the block, not the whole file.
+subdirectories, and its siblings), the doc points a reader at a file that is not
+there. This hook fires on Write, Edit, and MultiEdit targeting a file named
+``CLAUDE.md`` and blocks the write when any such cell or run command names a file
+absent from the scan root. A table block or a run-command fence whose own region
+declares an explicit relative-path source (a ``../`` token, in the rows/fence or
+the prose that introduces it) documents files outside the subtree, so that block's
+rows or that fence's commands are left alone — the exemption is scoped to the
+region, not the whole file.
 """
 
 import json
@@ -26,6 +30,7 @@ if _hooks_dir not in sys.path:
 from hooks_constants.claude_md_orphan_file_blocker_constants import (  # noqa: E402
     ALL_NOISE_DIRECTORY_NAMES,
     ALL_REFERENCED_FILE_EXTENSIONS,
+    ALL_RUN_COMMAND_SCRIPT_EXTENSIONS,
     CLAUDE_MD_FILENAME,
     CODE_FENCE_PATTERN,
     FIRST_COLUMN_BACKTICK_PATTERN,
@@ -36,6 +41,7 @@ from hooks_constants.claude_md_orphan_file_blocker_constants import (  # noqa: E
     ORPHAN_FILE_SYSTEM_MESSAGE,
     REGION_BOUNDARY_PATTERN,
     RELATIVE_PATH_SOURCE_PATTERN,
+    RUN_COMMAND_SCRIPT_PATTERN,
     SEPARATOR_CELL_PATTERN,
     TABLE_ROW_PATTERN,
 )
@@ -210,6 +216,147 @@ def _block_filenames(all_region_lines: list[str], all_block_lines: list[str]) ->
     return block_filenames
 
 
+def _script_basename_from_token(script_token: str) -> str | None:
+    """Return the bare basename one captured script token names, when it has one.
+
+    A path-qualified script keeps only its final segment, so ``tools/build_bundle.mjs``
+    yields ``build_bundle.mjs`` — the basename the directory file would match. A
+    script named by an explicit relative-path source (a ``../`` token in the token
+    itself, as in ``../shared/preflight.py``) lives outside the subtree by design, so
+    it is exempt and yields None. This token-scoped ``../`` check is one of two
+    relative-path exemptions: ``find_run_command_filenames`` also skips a whole fence
+    whose introducing prose region declares a ``../`` source, which is the
+    region-scoped counterpart to the table-cell exemption. A token whose basename
+    carries no recognized script extension yields None.
+
+    Args:
+        script_token: One script path captured from an interpreter invocation.
+
+    Returns:
+        The bare script basename, or None when the token is relative-path-sourced
+        or carries no recognized extension.
+    """
+    if _declares_relative_path_source(script_token):
+        return None
+    basename = os.path.basename(script_token.replace("\\", "/").rstrip("/"))
+    if not basename:
+        return None
+    _, extension = os.path.splitext(basename)
+    if extension.lower() not in ALL_RUN_COMMAND_SCRIPT_EXTENSIONS:
+        return None
+    return basename
+
+
+def _command_text_before_comment(fenced_line: str) -> str:
+    """Return the runnable portion of a fenced line, with any shell comment removed.
+
+    A shell comment starts at a ``#`` that begins a word — at the line's start or
+    after whitespace — outside any quoted span, and runs to end of line. The text
+    after it documents a removed or alternative command rather than a runnable
+    contract, so it is dropped: a full-line comment yields an empty string, and an
+    inline trailing comment (``python real.py  # was: python old.py``) yields only
+    the part before the ``#``. A ``#`` inside single or double quotes, or one
+    glued to a preceding non-space character, stays in the runnable text.
+
+    Args:
+        fenced_line: A single line drawn from inside a fenced code block.
+
+    Returns:
+        The line truncated at its first unquoted word-leading ``#``, or the whole
+        line when it carries no such comment marker.
+    """
+    open_quote_character = ""
+    previous_character = ""
+    for each_index, each_character in enumerate(fenced_line):
+        if open_quote_character:
+            if each_character == open_quote_character:
+                open_quote_character = ""
+        elif each_character in ("'", '"'):
+            open_quote_character = each_character
+        elif each_character == "#" and (each_index == 0 or previous_character.isspace()):
+            return fenced_line[:each_index]
+        previous_character = each_character
+    return fenced_line
+
+
+def _run_command_filenames_in_line(fenced_line: str) -> list[str]:
+    """Return each script basename the interpreter invocations on this line name.
+
+    A fenced run-command line such as ``python tools/verify.py --flag`` invokes a
+    script file; this returns that script's bare basename. A line that chains
+    several invocations with a shell separator (``python deploy.py && node build.mjs``,
+    ``python first.py; python second.py``) contributes each invocation's basename in
+    order. A shell comment — a ``#`` that begins a word outside any quoted span,
+    whether it opens the line or trails a command (``python real.py  # was python
+    old.py``) — documents a removed or alternative command rather than a runnable
+    contract, so the text from that ``#`` to end of line contributes nothing. A line
+    with no interpreter invocation contributes nothing.
+
+    Args:
+        fenced_line: A single line drawn from inside a fenced code block.
+
+    Returns:
+        Each bare script basename the line's invocations name, in order; empty when
+        the line is a comment or names no runnable script.
+    """
+    runnable_text = _command_text_before_comment(fenced_line)
+    line_filenames: list[str] = []
+    for each_match in RUN_COMMAND_SCRIPT_PATTERN.finditer(runnable_text):
+        each_basename = _script_basename_from_token(each_match.group(1).strip())
+        if each_basename is not None:
+            line_filenames.append(each_basename)
+    return line_filenames
+
+
+def find_run_command_filenames(content: str) -> list[str]:
+    """Return each script basename a fenced run command invokes, in order.
+
+    Walks the content line by line, inspecting only lines inside a fenced code
+    block (between a ``` or ~~~ fence pair). A fenced run-command line that invokes
+    an interpreter on a script (``python script.py``, ``node bundle.mjs``,
+    ``pwsh build.ps1``) contributes that script's bare basename, and a line that
+    chains several invocations with a shell separator contributes each one. A line
+    outside any fence is prose, not a live command, and contributes nothing — an
+    inline ``python x.py`` in a sentence is documentation, not a runnable contract.
+    A fence whose introducing region declares an explicit relative-path source (a
+    ``../`` token in the prose accumulated since the prior fence or heading)
+    documents commands that run scripts in a sibling tree, so that fence's run
+    commands are skipped — mirroring the region-scoped table-cell ``../``
+    exemption. The region resets when a fence closes, so the exemption is scoped to
+    that fence alone: a second fence under the same heading, introduced by prose
+    that names no ``../`` source, is still inspected.
+
+    Args:
+        content: The CLAUDE.md content being written.
+
+    Returns:
+        Each script basename a fenced run command names, in the order it appears;
+        duplicates preserved.
+    """
+    run_command_filenames: list[str] = []
+    pending_region: list[str] = []
+    is_inside_code_fence = False
+    is_region_relative_path_sourced = False
+    for each_line in content.splitlines():
+        if CODE_FENCE_PATTERN.match(each_line) is not None:
+            if not is_inside_code_fence:
+                is_region_relative_path_sourced = _declares_relative_path_source(
+                    "\n".join(pending_region)
+                )
+            else:
+                pending_region = []
+            is_inside_code_fence = not is_inside_code_fence
+            continue
+        if is_inside_code_fence:
+            if not is_region_relative_path_sourced:
+                run_command_filenames.extend(_run_command_filenames_in_line(each_line))
+            continue
+        if REGION_BOUNDARY_PATTERN.match(each_line) is not None:
+            pending_region = []
+        pending_region.append(each_line)
+    return run_command_filenames
+
+
 def _resolve_scan_root(claude_md_directory: Path) -> Path:
     """Return the directory whose subtree bounds the filename existence search.
 
@@ -358,16 +505,17 @@ def _present_referenced_filenames(
 def find_missing_filenames(content: str, claude_md_directory: Path) -> list[str]:
     """Return the referenced filenames absent from the CLAUDE.md's scan root.
 
-    A referenced filename is missing when it exists nowhere under the scan root
-    — the CLAUDE.md directory's parent (or the directory itself when it has no
-    distinct parent), which covers the directory, its subdirectories, and its
-    siblings. A table block that declares an explicit relative-path source (a
-    ``../`` token in the block or the prose that introduces it) yields no findings
-    for that block's rows, since those files legitimately live elsewhere; an
-    unrelated block in the same file is still checked. When the content references
-    no bare filename, no findings result and the subtree walk is skipped. A
-    filesystem error that halts the whole subtree walk yields no findings (fail
-    open), so an unreadable tree never blocks a write.
+    A referenced filename comes from two sources: a bare filename a table cell
+    names, and a script a fenced run command invokes (``python script.py``). It is
+    missing when it exists nowhere under the scan root — the CLAUDE.md directory's
+    parent (or the directory itself when it has no distinct parent), which covers
+    the directory, its subdirectories, and its siblings. A table block that
+    declares an explicit relative-path source (a ``../`` token in the block or the
+    prose that introduces it) yields no findings for that block's rows, since those
+    files legitimately live elsewhere; an unrelated block in the same file is still
+    checked. When the content references no bare filename, no findings result and
+    the subtree walk is skipped. A filesystem error that halts the whole subtree
+    walk yields no findings (fail open), so an unreadable tree never blocks a write.
 
     Args:
         content: The CLAUDE.md content being written.
@@ -377,7 +525,9 @@ def find_missing_filenames(content: str, claude_md_directory: Path) -> list[str]
         Each referenced filename with no matching file under the scan root, in
         first-seen order with duplicates removed, capped at the issue budget.
     """
-    referenced_filenames = find_referenced_filenames(content)
+    referenced_filenames = find_referenced_filenames(content) + find_run_command_filenames(
+        content
+    )
     if not referenced_filenames:
         return []
     scan_root = _resolve_scan_root(claude_md_directory)