claude-dev-env 1.70.0 → 1.72.0

package/CLAUDE.md

@@ -27,6 +27,14 @@ When making code changes, make sure you are working in the proper worktree path
 
 `Edit` changes existing files; `Write` creates new ones. Default to `Edit` — reach for `Write` only for a genuinely new path. For a true full rewrite, delete the file first, then `Write`.
 
+## Showing Files: Open Them, Don't Print the Path
+
+When I ask you to "show me", "open", "display", "let me see", or "pull up" a file — an image, PDF, HTML page, document, anything — open it on my screen. Launch the viewer so each image window matches the asset's size:
+
+`Start-Process pwsh -WindowStyle Hidden -ArgumentList '-NoProfile','-File',"$HOME\.claude\scripts\Show-Asset.ps1",'<path 1>','<path 2>'`
+
+It sizes each image window to the image (scaled down to fit the screen) and opens non-image files in their default app; pass every path I name. Printing a path or attaching the file is not showing it — do that only when the file truly cannot be opened, and say why.
+
 ## Test Philosophy
 
 When writing tests, always write tests that actually test the behavior of the function against actual, real data and environments.

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

@@ -594,11 +594,11 @@ def check_wrapper_plumb_through(content: str, file_path: str) -> list[str]:
     Args:
         content: File content as a single string for AST parsing.
         file_path: Repository-relative POSIX path of the file (used to
-            skip non-Python code extensions early).
+            skip non-Python code extensions and test files early).
 
     Returns:
-        List of violation strings, one per dropped optional kwarg. Returns
-        an empty list when the file is not Python or has a syntax error.
+        List of violation strings, one per dropped optional kwarg. Empty for
+        a non-Python file, a test file, or a file with a syntax error.
     """
     non_python_code_extensions = ALL_CODE_FILE_EXTENSIONS - {PYTHON_FILE_EXTENSION}
     lowercase_file_path = file_path.lower()
@@ -607,6 +607,8 @@ def check_wrapper_plumb_through(content: str, file_path: str) -> list[str]:
         for each_extension in non_python_code_extensions
     ):
         return []
+    if is_test_path(file_path):
+        return []
     try:
         tree = ast.parse(content)
     except SyntaxError:

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

@@ -430,6 +430,45 @@ def test_check_wrapper_plumb_through_still_flags_attribute_call() -> None:
     )
 
 
+def test_check_wrapper_plumb_through_exempts_test_files() -> None:
+    source = (
+        "def _helper(name, *, clean_name=None):\n"
+        "    return (name, clean_name)\n"
+        "\n"
+        "def test_uses_helper():\n"
+        "    return _helper('a', clean_name='b')\n"
+    )
+    shared_issues = gate_module.check_wrapper_plumb_through(source, "pkg/test_thing.py")
+    bugteam_gate = _load_bugteam_gate_module()
+    bugteam_issues = bugteam_gate.check_wrapper_plumb_through(source, "pkg/test_thing.py")
+    assert shared_issues == [], (
+        "a test_* function in a test-file path that calls a module-level helper "
+        "exposing an optional kwarg is not a wrapper; the shared gate must exempt "
+        "test files and emit zero findings"
+    )
+    assert bugteam_issues == [], (
+        "the bugteam gate copy must apply the identical test-file exemption"
+    )
+
+
+def test_check_wrapper_plumb_through_still_flags_non_test_path_with_test_shape() -> None:
+    source = (
+        "def _helper(name, *, clean_name=None):\n"
+        "    return (name, clean_name)\n"
+        "\n"
+        "def test_uses_helper():\n"
+        "    return _helper('a', clean_name='b')\n"
+    )
+    issues = gate_module.check_wrapper_plumb_through(source, "pkg/module.py")
+    assert any(
+        "test_uses_helper" in each_issue and "clean_name" in each_issue
+        for each_issue in issues
+    ), (
+        "the test-file exemption is scoped to test paths only; the same wrapper "
+        "shape on a non-test path must still be flagged"
+    )
+
+
 def test_split_violations_by_scope_accepts_all_added_line_numbers_param_name() -> None:
     blocking_issues, advisory_issues = gate_module.split_violations_by_scope(
         ["Line 5: violation"],

package/agents/clean-coder.md

@@ -264,6 +264,7 @@ Tests document behavior. The hook layer enforces several constraints on test fil
 - **No decorators named `skip*` on test functions.** Tests fail with a clear error rather than skip when a system dependency is missing. The hook fires on any decorator (whether `@skip_if_missing_dependency`, `@unittest.skipIf`, `@pytest.mark.skip`, or any custom variant) whose identifier contains the substring `skip`.
 - **No existence-only tests.** A test whose entire body is `assert callable(x)`, `assert hasattr(module, "name")`, or `assert obj is not None` covers no behavior. Replace with an assertion that exercises the behavior — call the function and assert on its return value or side effect.
 - **No constant-equality tests.** A test whose sole assertion is `assert CACHE_DIR == "cache"` (or any `UPPER_SNAKE == LITERAL` pattern) just verifies the constant has not changed. Delete it or replace with a behavior assertion.
+- **No stale test names after a rename.** When you rename a function the tests exercise, rename the test functions in the same edit. The `check_stale_test_name_target` hook fires on a `test_*` name that embeds a snake_case run the file never imports, defines, or calls while the body calls a same-shape sibling — the signature of a producer rename that updated the bodies but left the test identifiers naming the deleted function.
 - **No tautological assertions.** `assert CONSTANT == CONSTANT` and `assert hasattr(module, "name")` pass regardless of the implementation. Replace with assertions that would fail if the implementation regressed.
 - **Test through the public API.** Do not assert on private state, hook return values, internal class fields, `_protected_field`, `__private_field`, or `component.state.X`. If the test needs visibility the public API does not provide, the public API needs a method, not the test.
 - **For React components**, query in this priority order: `getByRole > getByLabelText > getByText > getByTestId`. Use `userEvent` over `fireEvent` (more realistic). Mock at API boundaries (network calls, external services), not internal hooks or utilities.

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

@@ -27,6 +27,7 @@ Decomposition is by the **kind of docstring claim** that needs to be cross-check
 | O5 | Named-sentinel / filename references | A docstring names a sentinel marker, environment variable, filename, or magic string. Confirm the named token actually exists in the module body or in the repo's naming convention. |
 | 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. 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. 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`. |
 
 ---
 

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 7 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 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.
 
 [ARTIFACT METADATA — include every changed module's docstring AND the exported symbols of that module so the audit can compare claim vs body]
 
@@ -47,9 +47,13 @@ ID prefix: `find`.
 - When the diff includes a module split (one file becomes two), verify both modules' docstrings describe the responsibility each one actually owns after the split.
 - Adversarial probes: (a) for each module in the split, list its exported symbols and compare to the docstring's claimed responsibilities; (b) grep the responsibility's verb against the originating module — does the originating docstring still claim what moved; (c) check for cross-module imports that reveal which file hosts each responsibility.
 
+**O8. Companion-doc ordering/content vs producer**
+- 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.
+
 ## Cross-bucket questions to answer at the end
 
-Q1: Across all 7 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 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.
 
 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.
 
@@ -57,13 +61,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-O7, 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-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.
 
 ---
 
 # 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 7 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 8 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`) 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 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_orphan_file_blocker.py

@@ -24,6 +24,7 @@ if _hooks_dir not in sys.path:
     sys.path.insert(0, _hooks_dir)
 
 from hooks_constants.claude_md_orphan_file_blocker_constants import (  # noqa: E402
+    ALL_NOISE_DIRECTORY_NAMES,
     ALL_REFERENCED_FILE_EXTENSIONS,
     CLAUDE_MD_FILENAME,
     CODE_FENCE_PATTERN,
@@ -237,13 +238,35 @@ class _SubtreeScan:
         self.was_scan_complete = was_scan_complete
 
 
+def _is_under_noise_directory(scan_root: Path, candidate_path: Path) -> bool:
+    """Return whether *candidate_path* lies inside a pruned noise directory.
+
+    A noise directory (``.git``, ``__pycache__``, ``node_modules``, and the test
+    and lint caches) holds volatile generated files that no CLAUDE.md table
+    documents, so the walk skips them. This keeps generated files out of the
+    basename set and keeps them from consuming the scan budget.
+
+    Args:
+        scan_root: The directory the walk descends from.
+        candidate_path: A path the walk yielded under the scan root.
+
+    Returns:
+        True when any path segment below *scan_root* names a noise directory.
+    """
+    try:
+        relative_segments = candidate_path.relative_to(scan_root).parts
+    except ValueError:
+        relative_segments = candidate_path.parts
+    return any(each_segment in ALL_NOISE_DIRECTORY_NAMES for each_segment in relative_segments)
+
+
 def _scan_subtree_basenames(scan_root: Path) -> _SubtreeScan:
     """Return the bounded basename scan of *scan_root*, skipping unreadable entries.
 
     Walks the subtree collecting each file's basename, stopping once the scan
-    budget is reached. A per-entry stat error skips that entry. The result records
-    whether the walk completed within the budget, so the caller knows whether the
-    set is authoritative.
+    budget is reached. A path inside a noise directory is pruned, and a per-entry
+    stat error skips that entry. The result records whether the walk completed
+    within the budget, so the caller knows whether the set is authoritative.
 
     Args:
         scan_root: The directory whose subtree bounds the existence search.
@@ -254,6 +277,8 @@ def _scan_subtree_basenames(scan_root: Path) -> _SubtreeScan:
     all_basenames: set[str] = set()
     scanned_count = 0
     for each_path in scan_root.rglob("*"):
+        if _is_under_noise_directory(scan_root, each_path):
+            continue
         try:
             if not each_path.is_file():
                 continue
@@ -270,7 +295,9 @@ def _filename_exists_under(scan_root: Path, filename: str) -> bool:
     """Return whether a file with basename *filename* exists anywhere under root.
 
     A direct probe that resolves one filename deterministically even when the
-    bounded subtree walk was truncated. An unreadable entry mid-walk is skipped.
+    bounded subtree walk was truncated. A match inside a noise directory is pruned
+    so the probe agrees with the bounded walk, and an unreadable entry mid-walk is
+    skipped.
 
     Args:
         scan_root: The directory whose subtree bounds the existence search.
@@ -280,6 +307,8 @@ def _filename_exists_under(scan_root: Path, filename: str) -> bool:
         True when at least one matching file is reachable under the scan root.
     """
     for each_match in scan_root.rglob(filename):
+        if _is_under_noise_directory(scan_root, each_match):
+            continue
         try:
             if each_match.is_file():
                 return True
@@ -327,9 +356,10 @@ def find_missing_filenames(content: str, claude_md_directory: Path) -> list[str]
     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. A filesystem error that
-    halts the whole subtree walk yields no findings (fail open), so an unreadable
-    tree never blocks a write.
+    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.
@@ -340,6 +370,8 @@ def find_missing_filenames(content: str, claude_md_directory: Path) -> list[str]
         first-seen order with duplicates removed, capped at the issue budget.
     """
     referenced_filenames = find_referenced_filenames(content)
+    if not referenced_filenames:
+        return []
     scan_root = _resolve_scan_root(claude_md_directory)
     try:
         present_filenames = _present_referenced_filenames(referenced_filenames, scan_root)

package/hooks/blocking/code_rules_docstrings.py

@@ -24,12 +24,14 @@ from hooks_constants.blocking_check_limits import (  # noqa: E402
     ALL_DOCSTRING_EXEMPT_DECORATOR_NAMES,
     ALL_DOCSTRING_IMPLICIT_INSTANCE_PARAMETER_NAMES,
     ALL_DOCSTRING_MULTIPLE_CONDITION_JOINING_PHRASES,
+    ALL_DOCSTRING_NO_CONSUMER_CLAIM_PHRASES,
     DOCSTRING_FALLBACK_BRANCH_MINIMUM_ROUTE_COUNT,
     DOCSTRING_TRIVIAL_FUNCTION_BODY_LINE_LIMIT,
     MAX_CLASS_DOCSTRING_PUBLIC_METHOD_ISSUES,
     MAX_DOCSTRING_ARGS_SIGNATURE_ISSUES,
     MAX_DOCSTRING_FALLBACK_BRANCH_ISSUES,
     MAX_DOCSTRING_FORMAT_ISSUES,
+    MAX_DOCSTRING_NO_CONSUMER_CLAIM_ISSUES,
     MINIMUM_PUBLIC_METHODS_FOR_CLASS_DOCSTRING_BREADTH,
 )
 from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
@@ -559,3 +561,61 @@ def check_class_docstring_names_public_methods(
         if len(issues) >= MAX_CLASS_DOCSTRING_PUBLIC_METHOD_ISSUES:
             break
     return issues[:MAX_CLASS_DOCSTRING_PUBLIC_METHOD_ISSUES]
+
+
+def _docstring_claims_no_consumer(docstring_text: str) -> str:
+    lowered_docstring = docstring_text.lower()
+    for each_phrase in ALL_DOCSTRING_NO_CONSUMER_CLAIM_PHRASES:
+        if each_phrase in lowered_docstring:
+            return each_phrase
+    return ""
+
+
+def check_docstring_no_consumer_claim(content: str, file_path: str) -> list[str]:
+    """Flag a docstring that asserts no consumer reads its produced artifact yet.
+
+    A producer docstring claiming "no consumer reads it yet" (or
+    "producer-only artifact") is a transitional statement that drifts the moment
+    a consumer lands. Once a submission run, gate, or any reader loads the
+    artifact, the claim contradicts both the live behavior and any companion
+    SKILL.md that documents the consumer — the Category O8 docstring /
+    companion-doc producer-consumer drift. The claim is also a no-historical /
+    no-transitional-language violation in its own right: a docstring describes
+    the contract that exists, not a not-yet-wired future. Rephrase to state what
+    reads the artifact, or drop the no-consumer sentence entirely.
+
+    Args:
+        content: The source text to inspect.
+        file_path: The path the source will be written to, used for exemptions.
+
+    Returns:
+        One issue per function whose docstring claims no consumer reads its
+        output, capped at the module limit.
+    """
+    if is_test_file(file_path) or is_hook_infrastructure(file_path):
+        return []
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    issues: list[str] = []
+    for each_node in _walk_skipping_type_checking_blocks(parsed_tree):
+        if not isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if _function_has_exempt_decorator(each_node):
+            continue
+        docstring_text = _function_docstring_text(each_node)
+        if not docstring_text:
+            continue
+        matched_phrase = _docstring_claims_no_consumer(docstring_text)
+        if not matched_phrase:
+            continue
+        issues.append(
+            f"Line {each_node.lineno}: {each_node.name}() docstring claims "
+            f"'{matched_phrase}' — a no-consumer-yet claim drifts the moment a reader "
+            "lands and contradicts any companion SKILL.md; state what reads the artifact "
+            "or drop the sentence (Category O8 docstring / companion-doc drift)"
+        )
+        if len(issues) >= MAX_DOCSTRING_NO_CONSUMER_CLAIM_ISSUES:
+            break
+    return issues[:MAX_DOCSTRING_NO_CONSUMER_CLAIM_ISSUES]

package/hooks/blocking/code_rules_enforcer.py

@@ -69,6 +69,7 @@ from code_rules_docstrings import (  # noqa: E402
     check_docstring_args_match_signature,
     check_docstring_fallback_branch_coverage,
     check_docstring_format,
+    check_docstring_no_consumer_claim,
 )
 from code_rules_duplicate_body import (  # noqa: E402
     advise_cross_skill_duplicate_helper,
@@ -122,6 +123,7 @@ from code_rules_test_assertions import (  # noqa: E402
     check_existence_check_tests,
     check_flag_gated_scenario_test_naming,
     check_skip_decorators_in_tests,
+    check_stale_test_name_target,
 )
 from code_rules_test_branching_except import (  # noqa: E402
     check_bare_except,
@@ -252,6 +254,7 @@ def validate_content(
         all_issues.extend(check_docstring_format(effective_content, file_path))
         all_issues.extend(check_docstring_args_match_signature(effective_content, file_path))
         all_issues.extend(check_docstring_fallback_branch_coverage(effective_content, file_path))
+        all_issues.extend(check_docstring_no_consumer_claim(effective_content, file_path))
         all_issues.extend(
             check_class_docstring_names_public_methods(effective_content, file_path)
         )
@@ -282,6 +285,7 @@ def validate_content(
         )
         all_issues.extend(check_existence_check_tests(content, file_path))
         all_issues.extend(check_constant_equality_tests(content, file_path))
+        all_issues.extend(check_stale_test_name_target(content, file_path))
         check_flag_gated_scenario_test_naming(content, file_path)
         all_issues.extend(check_unused_optional_parameters(content, file_path))
         all_issues.extend(check_collection_prefix(content, file_path))

package/hooks/blocking/code_rules_test_assertions.py

@@ -1,4 +1,4 @@
-"""Skip-decorator, existence-only, constant-equality, and flag-gated scenario test-quality checks."""
+"""Skip-decorator, existence-only, constant-equality, stale-test-name, and flag-gated scenario test-quality checks."""
 
 import ast
 import sys
@@ -18,6 +18,10 @@ from code_rules_shared import (  # noqa: E402
     is_test_file,
 )
 
+from hooks_constants.blocking_check_limits import (  # noqa: E402
+    MAX_STALE_TEST_NAME_TARGET_ISSUES,
+    STALE_TEST_NAME_MINIMUM_SHARED_TOKEN_COUNT,
+)
 from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     UPPER_SNAKE_CONSTANT_PATTERN,
 )
@@ -346,3 +350,150 @@ def check_flag_gated_scenario_test_naming(content: str, file_path: str) -> list[
             )
 
     return []
+
+
+def _called_function_names(function_node: ast.FunctionDef | ast.AsyncFunctionDef) -> set[str]:
+    """Return the bare names of every function the test body calls."""
+    called_names: set[str] = set()
+    for each_node in ast.walk(function_node):
+        if not isinstance(each_node, ast.Call):
+            continue
+        callee = each_node.func
+        if isinstance(callee, ast.Name):
+            called_names.add(callee.id)
+        elif isinstance(callee, ast.Attribute):
+            called_names.add(callee.attr)
+    return called_names
+
+
+def _module_known_callable_names(syntax_tree: ast.Module) -> set[str]:
+    """Return every callable-like name the module imports, defines, or calls.
+
+    A stale test name embeds a function that has been renamed away, so its name
+    appears nowhere as a real symbol. This set is the universe of names that DO
+    exist in the file, used to confirm the embedded name is absent.
+    """
+    known_names: set[str] = set()
+    for each_node in ast.walk(syntax_tree):
+        if isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            known_names.add(each_node.name)
+        elif isinstance(each_node, ast.ImportFrom):
+            for each_alias in each_node.names:
+                known_names.add(each_alias.asname or each_alias.name)
+        elif isinstance(each_node, ast.Import):
+            for each_alias in each_node.names:
+                known_names.add((each_alias.asname or each_alias.name).split(".")[0])
+        elif isinstance(each_node, ast.Call):
+            callee = each_node.func
+            if isinstance(callee, ast.Name):
+                known_names.add(callee.id)
+            elif isinstance(callee, ast.Attribute):
+                known_names.add(callee.attr)
+    return known_names
+
+
+def _leading_token_overlap(first_name: str, second_name: str) -> int:
+    """Return how many leading underscore-separated tokens two names share."""
+    first_tokens = first_name.split("_")
+    second_tokens = second_name.split("_")
+    shared = 0
+    for first_token, second_token in zip(first_tokens, second_tokens):
+        if first_token != second_token:
+            break
+        shared += 1
+    return shared
+
+
+def _renamed_sibling_for_candidate(candidate_name: str, called_names: set[str]) -> str | None:
+    """Return a called function that looks like the renamed form of the candidate.
+
+    A rename keeps the token count and the leading tokens but swaps one or more
+    interior or trailing tokens (``collect_skip_theme_names`` to
+    ``collect_skip_clean_names``). The match requires an equal token count and a
+    shared leading run, which excludes an ordinary descriptive test suffix where
+    the called function is a strict shorter prefix of the embedded name.
+    """
+    candidate_token_count = len(candidate_name.split("_"))
+    for each_called in sorted(called_names):
+        if each_called == candidate_name:
+            continue
+        if len(each_called.split("_")) != candidate_token_count:
+            continue
+        if (
+            _leading_token_overlap(candidate_name, each_called)
+            >= STALE_TEST_NAME_MINIMUM_SHARED_TOKEN_COUNT
+        ):
+            return each_called
+    return None
+
+
+def _embedded_target_candidates(test_name: str) -> list[str]:
+    """Return the function-name candidates a test name embeds after its test_ prefix.
+
+    For ``test_collect_skip_theme_names_keeps_only_sorted_at_risk`` the candidates
+    are the successive leading runs ``collect_skip_theme_names``,
+    ``collect_skip_theme``, ``collect_skip`` — longest first — so the embedded
+    function name is matched before its shorter prefixes.
+    """
+    if not test_name.startswith("test_"):
+        return []
+    remainder_tokens = test_name[len("test_"):].split("_")
+    candidates: list[str] = []
+    for token_count in range(len(remainder_tokens), STALE_TEST_NAME_MINIMUM_SHARED_TOKEN_COUNT - 1, -1):
+        candidates.append("_".join(remainder_tokens[:token_count]))
+    return candidates
+
+
+def check_stale_test_name_target(content: str, file_path: str) -> list[str]:
+    """Flag a test whose name embeds a renamed-away function the body no longer calls.
+
+    When a producer function is renamed (``collect_skip_theme_names`` to
+    ``collect_skip_clean_names``) the test bodies are updated to call the new
+    name but the test function identifiers keep the old one. The result is a test
+    name advertising a function that exists nowhere in the file. This catches that
+    Category N test-name-versus-scenario drift: a ``test_*`` name embeds a
+    snake_case run of at least two tokens that names nothing the module imports,
+    defines, or calls, while the same test body calls a function sharing the
+    embedded run's leading tokens — the renamed sibling. Only applies to test
+    files; production files are exempt.
+
+    Args:
+        content: The file body under validation.
+        file_path: Path to the file, used for the test-file gate.
+
+    Returns:
+        One issue per test whose name embeds a renamed-away target, capped at the
+        module limit.
+    """
+    if not is_test_file(file_path):
+        return []
+    try:
+        syntax_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+
+    known_names = _module_known_callable_names(syntax_tree)
+    issues: list[str] = []
+    for each_node in ast.walk(syntax_tree):
+        if not isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if not each_node.name.startswith("test"):
+            continue
+        called_names = _called_function_names(each_node)
+        for each_candidate in _embedded_target_candidates(each_node.name):
+            if each_candidate in known_names:
+                break
+            renamed_sibling = _renamed_sibling_for_candidate(each_candidate, called_names)
+            if renamed_sibling is None:
+                continue
+            issues.append(
+                f"Line {each_node.lineno}: test {each_node.name!r} names "
+                f"{each_candidate!r}, which the file never imports, defines, or calls; "
+                f"the body calls {renamed_sibling!r} instead — rename the test to match "
+                "the function it exercises (Category N test-name-vs-scenario drift)"
+            )
+            if len(issues) >= MAX_STALE_TEST_NAME_TARGET_ISSUES:
+                return issues[:MAX_STALE_TEST_NAME_TARGET_ISSUES]
+            break
+
+    return issues[:MAX_STALE_TEST_NAME_TARGET_ISSUES]