claude-dev-env 1.74.0 → 1.76.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/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 |
@@ -63,6 +63,7 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `convergence_gate_blocker.py` | PreToolUse (Bash) | Convergence workflow actions on a conflicting PR |
 | `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 |
 | `es_exe_path_rewriter.py` | PreToolUse | Rewrites paths referencing `.exe` under the Everything search path |
 | `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 |

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)