claude-dev-env 1.76.0 → 1.78.0

package/hooks/blocking/code_rules_enforcer.py

@@ -64,15 +64,23 @@ from code_rules_dead_dataclass_field import (  # noqa: E402
 from code_rules_dead_module_constant import (  # noqa: E402
     check_dead_module_constants,
 )
+from code_rules_dead_split_branch import (  # noqa: E402
+    check_dead_split_truthiness_branch,
+)
 from code_rules_docstrings import (  # noqa: E402
     check_class_docstring_names_public_methods,
     check_docstring_args_match_signature,
+    check_docstring_args_single_line_scope_vs_span,
+    check_docstring_cardinal_count_matches_constant_family,
     check_docstring_fallback_branch_coverage,
     check_docstring_format,
     check_docstring_names_undefined_constant,
     check_docstring_no_consumer_claim,
     check_docstring_no_inline_literal_claim,
+    check_docstring_punctuation_mark_enumeration_coverage,
+    check_docstring_raises_unraisable_largezipfile,
     check_docstring_returns_plural_cardinality,
+    check_docstring_runon_sentence,
     check_docstring_step_enumeration_dispatch_coverage,
     check_docstring_tuple_enumeration_match,
     check_docstring_unguarded_malformed_payload_claim,
@@ -113,6 +121,9 @@ from code_rules_optional_params import (  # noqa: E402
 from code_rules_orphan_css_class import (  # noqa: E402
     check_orphan_css_classes,
 )
+from code_rules_paired_test import (  # noqa: E402
+    check_public_function_missing_paired_test,
+)
 from code_rules_paths_syspath import (  # noqa: E402
     check_hardcoded_user_paths,
     check_sys_path_insert_deduplication_guard,
@@ -128,6 +139,7 @@ from code_rules_string_magic import (  # noqa: E402
     check_inline_literal_collections,
     check_inline_tuple_string_magic,
     check_string_literal_magic,
+    check_whitespace_indentation_magic,
 )
 from code_rules_test_assertions import (  # noqa: E402
     check_constant_equality_tests,
@@ -295,12 +307,18 @@ def validate_content(
         all_issues.extend(
             check_class_docstring_names_public_methods(effective_content, file_path)
         )
+        all_issues.extend(check_docstring_runon_sentence(effective_content, file_path))
         all_issues.extend(
             check_module_docstring_names_public_checks(effective_content, file_path)
         )
         all_issues.extend(
             check_docstring_tuple_enumeration_match(effective_content, file_path)
         )
+        all_issues.extend(
+            check_docstring_punctuation_mark_enumeration_coverage(
+                effective_content, file_path
+            )
+        )
         all_issues.extend(
             check_docstring_step_enumeration_dispatch_coverage(
                 effective_content, file_path
@@ -309,9 +327,20 @@ def validate_content(
         all_issues.extend(
             check_docstring_returns_plural_cardinality(effective_content, file_path)
         )
+        all_issues.extend(
+            check_docstring_raises_unraisable_largezipfile(effective_content, file_path)
+        )
+        all_issues.extend(
+            check_docstring_cardinal_count_matches_constant_family(
+                effective_content, file_path
+            )
+        )
         all_issues.extend(
             check_docstring_names_undefined_constant(effective_content, file_path)
         )
+        all_issues.extend(
+            check_docstring_args_single_line_scope_vs_span(effective_content, file_path)
+        )
         all_issues.extend(
             check_boolean_naming(
                 effective_content,
@@ -361,6 +390,7 @@ def validate_content(
         all_issues.extend(
             check_dead_module_constants(content, file_path, full_file_content)
         )
+        all_issues.extend(check_dead_split_truthiness_branch(content, file_path))
         all_issues.extend(check_library_print(content, file_path))
         all_issues.extend(check_parameter_annotations(content, file_path))
         all_issues.extend(check_known_pytest_fixture_annotations(content, file_path))
@@ -376,10 +406,19 @@ def validate_content(
                 defer_scope_to_caller,
             )
         )
+        all_issues.extend(
+            check_public_function_missing_paired_test(
+                effective_content,
+                file_path,
+                all_changed_lines,
+                defer_scope_to_caller,
+            )
+        )
         all_issues.extend(check_loop_variable_naming(content, file_path))
         all_issues.extend(check_inline_literal_collections(content, file_path))
         all_issues.extend(check_inline_tuple_string_magic(content, file_path))
         all_issues.extend(check_string_literal_magic(content, file_path))
+        all_issues.extend(check_whitespace_indentation_magic(content, file_path))
         all_issues.extend(check_orphan_css_classes(effective_content, file_path))
         check_incomplete_mocks(content, file_path)
         check_duplicated_format_patterns(content, file_path)

package/hooks/blocking/code_rules_paired_test.py

@@ -0,0 +1,299 @@
+"""Public-function paired-test coverage check for ``code_rules_enforcer``.
+
+The TDD gate ``tdd_enforcer.py`` requires a fresh test file to exist before a
+production module is written, but it judges coverage at file granularity: a
+module whose dedicated test file exercises some public functions while leaving
+one untested still satisfies it. This check closes that gap. When a production
+module has an established paired test suite — a stem-matched ``test_<stem>.py``
+that already exercises at least one of the module's public functions — a public
+function that suite references nowhere is flagged, so the forgotten function
+gets a behavioral test before the partially-covered module lands.
+
+The check stays conservative to keep false positives near zero:
+
+- It runs only on a production module whose stem-matched test file already
+  exists; a module with no dedicated test file is out of scope and left to the
+  file-level TDD gate.
+- It fires only when the suite already covers at least one public function of
+  the same module — the signature of a maintained per-function suite rather than
+  an unrelated or placeholder test file.
+- A public function counts as covered when its name appears in any test file
+  beside the stem-matched one — imported, called, or named — so a function
+  exercised by a differently-named sibling test still counts.
+- ``main`` and underscore-prefixed functions are never required to carry a test.
+- Test modules, hook infrastructure, config modules, migrations, workflow
+  registries, and ``__init__`` modules are exempt.
+"""
+
+import ast
+import sys
+from pathlib import Path
+
+_blocking_directory = str(Path(__file__).resolve().parent)
+_hooks_directory = str(Path(__file__).resolve().parent.parent)
+if _blocking_directory not in sys.path:
+    sys.path.insert(0, _blocking_directory)
+if _hooks_directory not in sys.path:
+    sys.path.insert(0, _hooks_directory)
+
+from code_rules_path_utils import (  # noqa: E402
+    is_config_file,
+)
+from code_rules_shared import (  # noqa: E402
+    _scope_violations_to_changed_lines,
+    is_hook_infrastructure,
+    is_migration_file,
+    is_test_file,
+    is_workflow_registry_file,
+)
+
+from hooks_constants.paired_test_coverage_constants import (  # noqa: E402
+    ALL_TEST_FILENAME_GLOBS,
+    ANCESTOR_DIRECTORY_WALK_LIMIT,
+    EXEMPT_PUBLIC_FUNCTION_NAMES,
+    INIT_MODULE_FILENAME,
+    MAX_PAIRED_TEST_COVERAGE_ISSUES,
+    MAX_TEST_FILES_SCANNED,
+    MINIMUM_COVERED_PUBLIC_FUNCTIONS,
+    MISSING_PAIRED_TEST_GUIDANCE,
+    PYTHON_SOURCE_SUFFIX,
+    STEM_TEST_FILENAME_PREFIX,
+    STEM_TEST_FILENAME_SUFFIX,
+    TESTS_DIRECTORY_NAME,
+)
+
+
+def _is_public_function_name(function_name: str) -> bool:
+    """Return whether a function name is a public, test-worthy entry point.
+
+    Args:
+        function_name: The bare function name from a module-scope definition.
+
+    Returns:
+        True when the name does not start with an underscore and is not one of
+        the conventionally untested entry points such as ``main``.
+    """
+    if function_name.startswith("_"):
+        return False
+    return function_name not in EXEMPT_PUBLIC_FUNCTION_NAMES
+
+
+def _public_function_definitions(tree: ast.Module) -> list[tuple[str, int]]:
+    """Return ``(name, line)`` for each module-scope public function definition.
+
+    Args:
+        tree: The parsed production module.
+
+    Returns:
+        One ``(name, definition_line)`` pair per module-scope public function,
+        in source order.
+    """
+    all_definitions: list[tuple[str, int]] = []
+    for each_statement in tree.body:
+        if not isinstance(each_statement, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if _is_public_function_name(each_statement.name):
+            all_definitions.append((each_statement.name, each_statement.lineno))
+    return all_definitions
+
+
+def _ancestor_tests_directories(start_directory: Path) -> list[Path]:
+    """Return each ancestor's ``tests`` directory, nearest ancestor first.
+
+    Args:
+        start_directory: The directory holding the production module.
+
+    Returns:
+        Existing ``tests`` directories found by walking from start_directory
+        toward the filesystem root, bounded by the ancestor walk limit.
+    """
+    all_candidate_directories = [start_directory, *start_directory.parents]
+    all_tests_directories: list[Path] = []
+    for each_directory in all_candidate_directories[:ANCESTOR_DIRECTORY_WALK_LIMIT]:
+        candidate_tests_directory = each_directory / TESTS_DIRECTORY_NAME
+        if candidate_tests_directory.is_dir():
+            all_tests_directories.append(candidate_tests_directory)
+    return all_tests_directories
+
+
+def _stem_matched_test_path(module_path: Path) -> Path | None:
+    """Return the first existing stem-matched test file for a module, or None.
+
+    Args:
+        module_path: The resolved path of the production module.
+
+    Returns:
+        The path of the first existing ``test_<stem>.py`` or ``<stem>_test.py``
+        file — beside the module or under an ancestor ``tests`` directory — or
+        None when the module has no dedicated test file.
+    """
+    module_directory = module_path.parent
+    module_stem = module_path.stem
+    flat_prefixed_name = STEM_TEST_FILENAME_PREFIX + module_stem + PYTHON_SOURCE_SUFFIX
+    flat_suffixed_name = module_stem + STEM_TEST_FILENAME_SUFFIX
+    all_candidate_paths = [
+        module_directory / flat_prefixed_name,
+        module_directory / flat_suffixed_name,
+    ]
+    for each_tests_directory in _ancestor_tests_directories(module_directory):
+        all_candidate_paths.append(each_tests_directory / flat_prefixed_name)
+    for each_candidate_path in all_candidate_paths:
+        if each_candidate_path.is_file():
+            return each_candidate_path
+    return None
+
+
+def _collect_referenced_identifiers(source: str) -> set[str]:
+    """Return every identifier a test module references — imported, called, or named.
+
+    Collects ``import`` binding names and ``from``-import member names, every
+    ``Name`` node id, and every attribute access name, so a public function the
+    test imports, calls bare, or reaches through an attribute all count as a
+    reference. A module that fails to parse contributes no identifiers.
+
+    Args:
+        source: The full text of a test module.
+
+    Returns:
+        The set of identifiers the test module references.
+    """
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return set()
+    all_referenced_identifiers: set[str] = set()
+    for each_node in ast.walk(tree):
+        if isinstance(each_node, ast.Name):
+            all_referenced_identifiers.add(each_node.id)
+        elif isinstance(each_node, ast.Attribute):
+            all_referenced_identifiers.add(each_node.attr)
+        elif isinstance(each_node, (ast.Import, ast.ImportFrom)):
+            for each_alias in each_node.names:
+                all_referenced_identifiers.add(each_alias.asname or each_alias.name)
+                all_referenced_identifiers.add(each_alias.name)
+    return all_referenced_identifiers
+
+
+def _suite_referenced_identifiers(stem_test_path: Path) -> set[str]:
+    """Return identifiers referenced across every test file beside the stem test.
+
+    Scans every ``test_*.py`` and ``*_test.py`` file in the directory holding the
+    stem-matched test file, bounded by the scan cap, and unions the identifiers
+    each one references.
+
+    Args:
+        stem_test_path: The stem-matched test file whose directory is scanned.
+
+    Returns:
+        The union of referenced identifiers across the scanned test files.
+    """
+    suite_directory = stem_test_path.parent
+    all_test_file_paths: list[Path] = []
+    for each_glob in ALL_TEST_FILENAME_GLOBS:
+        all_test_file_paths.extend(sorted(suite_directory.glob(each_glob)))
+    all_referenced_identifiers: set[str] = set()
+    for each_test_file_path in all_test_file_paths[:MAX_TEST_FILES_SCANNED]:
+        try:
+            test_source = each_test_file_path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        all_referenced_identifiers |= _collect_referenced_identifiers(test_source)
+    return all_referenced_identifiers
+
+
+def _module_is_exempt(file_path: str) -> bool:
+    """Return whether a path is exempt from the paired-test coverage check.
+
+    Test modules, hook infrastructure, config modules, migrations, workflow
+    registries, and package ``__init__`` re-export modules are all exempt.
+
+    Args:
+        file_path: The destination path of the write or edit.
+
+    Returns:
+        True when the paired-test coverage check must not run on this path.
+    """
+    if is_test_file(file_path):
+        return True
+    if is_hook_infrastructure(file_path):
+        return True
+    if is_config_file(file_path):
+        return True
+    if is_migration_file(file_path):
+        return True
+    if is_workflow_registry_file(file_path):
+        return True
+    return Path(file_path).name == INIT_MODULE_FILENAME
+
+
+def check_public_function_missing_paired_test(
+    content: str,
+    file_path: str,
+    all_changed_lines: set[int] | None = None,
+    defer_scope_to_caller: bool = False,
+) -> list[str]:
+    """Flag a public function the module's established paired test suite omits.
+
+    Runs only on a production module whose stem-matched ``test_<stem>.py`` already
+    exists and already exercises at least one of the module's public functions.
+    Under that established-suite precondition, a public function the suite
+    references nowhere is flagged, so the forgotten function gets a behavioral
+    test before the partially-covered module lands. ``main`` and
+    underscore-prefixed functions are never required to carry a test, and test
+    modules, hook infrastructure, config modules, migrations, workflow
+    registries, and ``__init__`` modules are exempt.
+
+    Args:
+        content: The reconstructed post-edit whole-file content of the module.
+        file_path: The destination path, used for the exemptions and to locate
+            the module's paired test files on disk.
+        all_changed_lines: Post-edit line numbers the current edit touched, or
+            None to treat every public-function definition as in scope.
+        defer_scope_to_caller: When True, return every violation so the
+            commit/push gate scopes by added line.
+
+    Returns:
+        One violation per uncovered public function, capped at the configured
+        maximum, scoped to the changed lines unless deferred or unscoped. Empty
+        when the module is exempt, has no dedicated test file, the suite covers
+        no public function, or the content fails to parse.
+    """
+    if _module_is_exempt(file_path):
+        return []
+    try:
+        tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    all_public_definitions = _public_function_definitions(tree)
+    if not all_public_definitions:
+        return []
+    stem_test_path = _stem_matched_test_path(Path(file_path).resolve())
+    if stem_test_path is None:
+        return []
+    all_referenced_identifiers = _suite_referenced_identifiers(stem_test_path)
+    covered_function_count = sum(
+        1
+        for each_name, _each_line in all_public_definitions
+        if each_name in all_referenced_identifiers
+    )
+    if covered_function_count < MINIMUM_COVERED_PUBLIC_FUNCTIONS:
+        return []
+    all_violations_in_walk_order: list[tuple[range, str]] = []
+    for each_name, each_definition_line in all_public_definitions:
+        if each_name in all_referenced_identifiers:
+            continue
+        message = (
+            f"Line {each_definition_line}: public function {each_name!r} "
+            f"{MISSING_PAIRED_TEST_GUIDANCE}"
+        )
+        all_violations_in_walk_order.append(
+            (range(each_definition_line, each_definition_line + 1), message)
+        )
+        if len(all_violations_in_walk_order) >= MAX_PAIRED_TEST_COVERAGE_ISSUES:
+            break
+    return _scope_violations_to_changed_lines(
+        all_violations_in_walk_order,
+        all_changed_lines,
+        defer_scope_to_caller,
+    )
+

package/hooks/blocking/code_rules_string_magic.py

@@ -1,4 +1,4 @@
-"""Bare string-literal magic, inline literal-collection, and inline tuple string-magic checks."""
+"""Bare string-literal magic, inline literal-collection, inline tuple string-magic, and whitespace-indentation magic checks."""
 
 import ast
 import re
@@ -25,7 +25,11 @@ from code_rules_shared import (  # noqa: E402
 from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     ALL_CAPS_WITH_UNDERSCORE_PATTERN,
     DOTTED_SEGMENT_PATTERN,
+    INDENTATION_MAGIC_MINIMUM_SPACE_RUN,
+    INDENTATION_MAGIC_MINIMUM_TAB_RUN,
     INLINE_COLLECTION_MIN_LENGTH,
+    MAX_WHITESPACE_INDENTATION_MAGIC_ISSUES,
+    WHITESPACE_INDENTATION_MAGIC_MESSAGE_SUFFIX,
 )
 from hooks_constants.inline_tuple_string_magic_constants import (  # noqa: E402
     ALL_SNAKE_CASE_KEYWORD_EXEMPTIONS,
@@ -205,3 +209,69 @@ def check_inline_tuple_string_magic(content: str, file_path: str) -> list[str]:
                 if len(issues) >= MAX_INLINE_TUPLE_STRING_MAGIC_ISSUES:
                     return issues
     return issues
+
+
+def _is_whitespace_indentation_literal(string_value: str) -> bool:
+    if not string_value:
+        return False
+    if string_value.strip():
+        return False
+    if "\t" * INDENTATION_MAGIC_MINIMUM_TAB_RUN in string_value:
+        return True
+    return " " * INDENTATION_MAGIC_MINIMUM_SPACE_RUN in string_value
+
+
+def check_whitespace_indentation_magic(content: str, file_path: str) -> list[str]:
+    """Flag a whitespace-only indentation literal in a function body.
+
+    A string literal that is entirely whitespace and carries a run of at least
+    ``INDENTATION_MAGIC_MINIMUM_SPACE_RUN`` spaces, or a run of at least
+    ``INDENTATION_MAGIC_MINIMUM_TAB_RUN`` tabs, is a formatting default — the
+    indentation an output builder prepends — so it belongs in a
+    named constant in ``config/`` that one definition feeds to every call site.
+    Both a standalone string constant (``"            "``) and the literal
+    fragment of an f-string (``f"\\n            {value}"``) are inspected, so an
+    indent embedded beside an interpolation is caught too. Config files, test
+    files, workflow-registry files, and migration files are exempt.
+
+    Args:
+        content: The source text to inspect.
+        file_path: The path the source will be written to, used for exemptions.
+
+    Returns:
+        One issue per whitespace-only indentation literal found in a function
+        body, capped at the module limit.
+    """
+    if is_test_file(file_path):
+        return []
+    if is_config_file(file_path):
+        return []
+    if is_workflow_registry_file(file_path) or is_migration_file(file_path):
+        return []
+    try:
+        tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    issues: list[str] = []
+    flagged_node_ids: set[int] = set()
+    for each_function_node in ast.walk(tree):
+        if not isinstance(each_function_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        for each_body_statement in each_function_node.body:
+            for each_descendant in _walk_skipping_nested_function_defs(each_body_statement):
+                if not isinstance(each_descendant, ast.Constant):
+                    continue
+                if not isinstance(each_descendant.value, str):
+                    continue
+                if id(each_descendant) in flagged_node_ids:
+                    continue
+                if not _is_whitespace_indentation_literal(each_descendant.value):
+                    continue
+                flagged_node_ids.add(id(each_descendant))
+                issues.append(
+                    f"Line {each_descendant.lineno}: {each_descendant.value!r} "
+                    f"{WHITESPACE_INDENTATION_MAGIC_MESSAGE_SUFFIX}"
+                )
+                if len(issues) >= MAX_WHITESPACE_INDENTATION_MAGIC_ISSUES:
+                    return issues
+    return issues

package/hooks/blocking/convergence_gate_blocker.py

@@ -68,6 +68,27 @@ def _resolve_owner_repo(cwd: str | None) -> tuple[str, str] | None:
     return parts[0], parts[1]
 
 
+def _run_convergence_check(
+    script: str, owner: str, repo: str, pr_number: int, cwd: str | None
+) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        [
+            sys.executable,
+            script,
+            "--owner",
+            owner,
+            "--repo",
+            repo,
+            "--pr-number",
+            str(pr_number),
+        ],
+        capture_output=True,
+        text=True,
+        cwd=cwd or None,
+        check=False,
+    )
+
+
 def main() -> None:
     check_convergence_script = str(
         Path.home() / ".claude/skills/pr-converge/scripts/check_convergence.py"
@@ -90,7 +111,7 @@ def main() -> None:
     if not gh_pr_ready_pattern.search(command):
         sys.exit(0)
 
-    cwd = hook_input.get("tool_input", {}).get("cwd")
+    cwd = hook_input.get("cwd")
     pr_number = _resolve_pr_number(command, cwd)
     if pr_number is None:
         sys.exit(0)
@@ -100,20 +121,8 @@ def main() -> None:
         sys.exit(0)
     owner, repo = owner_repo
 
-    completed_process = subprocess.run(
-        [
-            sys.executable,
-            check_convergence_script,
-            "--owner",
-            owner,
-            "--repo",
-            repo,
-            "--pr-number",
-            str(pr_number),
-        ],
-        capture_output=True,
-        text=True,
-        check=False,
+    completed_process = _run_convergence_check(
+        check_convergence_script, owner, repo, pr_number, cwd
     )
 
     if completed_process.returncode in (0, 2):

package/hooks/blocking/test_code_rules_enforcer_dead_module_constant.py

@@ -152,7 +152,7 @@ def test_does_not_flag_constant_imported_one_directory_up(neutral_root: Path) ->
     assert issues == [], f"No constant is dead when all are imported, got: {issues}"
 
 
-def test_does_not_flag_when_module_declares_dunder_all(neutral_root: Path) -> None:
+def test_does_not_flag_dunder_all_member_with_a_live_consumer(neutral_root: Path) -> None:
     constants_body = CONSTANTS_BODY + '__all__ = ["MEDIUM_TERMINAL"]\n'
     consumer_body = (
         "from report_constants.render_report_constants import MEDIUM_TERMINAL\n"
@@ -164,7 +164,35 @@ def test_does_not_flag_when_module_declares_dunder_all(neutral_root: Path) -> No
         neutral_root / "workflow", constants_body, consumer_body
     )
     issues = _check(constants_body, str(constants_path))
-    assert issues == [], f"__all__ surface suppresses the check, got: {issues}"
+    assert issues == [], f"An __all__ member a consumer imports stays live, got: {issues}"
+
+
+def test_dunder_all_narrows_check_to_exported_constants(neutral_root: Path) -> None:
+    constants_body = (
+        'JSONL_APPEND_OPEN_MODE = "a"\n'
+        'ZIPFILE_READ_OPEN_MODE = "r"\n'
+        "PRIVATE_BUFFER_BYTES = 1024\n"
+        '__all__ = ["JSONL_APPEND_OPEN_MODE", "ZIPFILE_READ_OPEN_MODE"]\n'
+    )
+    consumer_body = (
+        "from report_constants.render_report_constants import JSONL_APPEND_OPEN_MODE\n"
+        "\n"
+        "def open_mode() -> str:\n"
+        "    return JSONL_APPEND_OPEN_MODE\n"
+    )
+    constants_path = _build_constants_package(
+        neutral_root / "workflow", constants_body, consumer_body
+    )
+    issues = _check(constants_body, str(constants_path))
+    assert any("ZIPFILE_READ_OPEN_MODE" in each_issue for each_issue in issues), (
+        f"An exported constant no module imports is dead, got: {issues}"
+    )
+    assert not any("JSONL_APPEND_OPEN_MODE" in each_issue for each_issue in issues), (
+        f"An exported constant a consumer imports must not be flagged, got: {issues}"
+    )
+    assert not any("PRIVATE_BUFFER_BYTES" in each_issue for each_issue in issues), (
+        f"A constant __all__ omits is the author's private value and is exempt, got: {issues}"
+    )
 
 
 def test_does_not_run_on_ordinary_production_module(neutral_root: Path) -> None:
@@ -264,6 +292,65 @@ def test_does_not_flag_constant_used_only_in_a_sibling_tree(neutral_root: Path)
     )
 
 
+def _build_name_collision_repository(
+    repository_root: Path,
+    promoter_timing_body: str,
+    promoter_consumer_body: str,
+    harness_constants_body: str,
+    harness_consumer_body: str,
+) -> Path:
+    promoter_config = repository_root / "promoter" / "config"
+    promoter_config.mkdir(parents=True)
+    timing_path = promoter_config / "timing.py"
+    timing_path.write_text(promoter_timing_body, encoding="utf-8")
+    (repository_root / "promoter" / "runtime.py").write_text(
+        promoter_consumer_body, encoding="utf-8"
+    )
+    harness_config = repository_root / "harness" / "config"
+    harness_config.mkdir(parents=True)
+    (harness_config / "lockfile_constants.py").write_text(
+        harness_constants_body, encoding="utf-8"
+    )
+    (repository_root / "harness" / "lockfile.py").write_text(
+        harness_consumer_body, encoding="utf-8"
+    )
+    return timing_path
+
+
+def test_same_named_constant_in_an_unrelated_module_does_not_mask_a_dead_one(
+    neutral_root: Path,
+) -> None:
+    promoter_timing_body = "LOCKFILE_ACQUIRE_BYTE_LENGTH = 1\nSWEEP_INTERVAL_SECONDS = 30\n"
+    promoter_consumer_body = (
+        "from config.timing import SWEEP_INTERVAL_SECONDS\n"
+        "\n"
+        "def deadline() -> int:\n"
+        "    return SWEEP_INTERVAL_SECONDS\n"
+    )
+    harness_constants_body = "LOCKFILE_ACQUIRE_BYTE_LENGTH = 1\n"
+    harness_consumer_body = (
+        "from harness.config.lockfile_constants import LOCKFILE_ACQUIRE_BYTE_LENGTH\n"
+        "\n"
+        "def acquire() -> int:\n"
+        "    return LOCKFILE_ACQUIRE_BYTE_LENGTH\n"
+    )
+    timing_path = _build_name_collision_repository(
+        neutral_root,
+        promoter_timing_body,
+        promoter_consumer_body,
+        harness_constants_body,
+        harness_consumer_body,
+    )
+    issues = _check(promoter_timing_body, str(timing_path))
+    assert any("LOCKFILE_ACQUIRE_BYTE_LENGTH" in each_issue for each_issue in issues), (
+        "A constant whose only same-named twin lives in an unrelated module's "
+        f"import must still be flagged dead, got: {issues}"
+    )
+    assert not any("SWEEP_INTERVAL_SECONDS" in each_issue for each_issue in issues), (
+        f"A constant consumed within its own package must not be flagged, got: {issues}"
+    )
+
+
 def test_returns_empty_list_at_file_cap(
     neutral_root: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None: