claude-dev-env 1.71.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/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/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]