claude-dev-env 1.76.0 → 1.78.0

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

@@ -28,6 +28,7 @@ Decomposition is by the **kind of docstring claim** that needs to be cross-check
 | O6 | Free-form `Args:`-adjacent claims | A docstring's `Returns:` / `Raises:` / `Note:` / `Example:` sections make claims (`returns shared-temp only`, `raises ValueError on missing key`). Verify each claim against the body. When a docstring enumerates the inputs a body counts (a "field counts as read when ..." list, a list of conditions treated as a match, a list of cases the body skips), list every union member and every suppressor the body applies (`read_names = a | b | c`, each early-return guard) and confirm each appears in the prose enumeration. A union member or suppressor the body applies but the prose omits is an O6 finding. When a docstring sentence excludes a named category of input from what the function flags (`X are not dispatch steps`, `Y is not a match`), confirm the axis the prose excludes on is the axis the body's branch condition actually keys on. A body that flags a call when it sits inside an `If.test` guard, paired with prose that excludes by the call's receiver shape (`method-on-local calls inside a branch are not dispatch steps`), is an O6 finding: a guarded method-on-local call is flagged even though the prose lists it as excluded — the exclusion is keyed to the wrong axis. The single-condition shared-fallback shape of this drift — a summary that scopes a fallback call to one condition while the body routes to that same call from two or more early-return guards — is gated deterministically at Write/Edit time by `check_docstring_fallback_branch_coverage`, so the audit lane focuses on the O6 shapes the gate cannot match. The exception-guard shape of this drift — a docstring that promises a malformed payload `resolves to None` while a payload subscript (`payload["key"]`, `float(payload["key"])`) sits outside the try/except whose handler returns None, so a present-but-malformed payload raises rather than resolving to None — is gated deterministically at Write/Edit time by `check_docstring_unguarded_malformed_payload_claim`, so the audit lane focuses on the wider Raises/None-on-failure claims the gate cannot match. A `Returns:` that names the mechanism, tool, or output format the function produces (`instructing a StructuredOutput summary`, `returns a YAML document`, `emits a JSON object`) matches the artifact the body actually builds: a prompt body that asks the agent to "Return strictly a JSON object" while the docstring claims it "instruct[s] a StructuredOutput" summary is an O6 finding, because the named tool appears nowhere in the emitted text. See `../../rules/docstring-prose-matches-implementation.md`. |
 | O7 | Module-doc-vs-split-module after refactor | When a refactor moves a responsibility to a sibling module, the originating module's docstring and the receiving module's docstring both describe the home of that responsibility. A module docstring should describe only the responsibilities it owns. |
 | O8 | Companion-doc ordering/content vs producer | When a PR changes a producer function's ordering or union, read that skill's companion `SKILL.md` and sibling `.md` docs for any sentence naming the same produced artifact (a file path, a JSON key, a named list). A doc sentence that claims the artifact is `sorted` / `alphabetical` / `in sorted order`, or holds `just the at-risk names` / `only the current set`, while the producer merges stored names with new names and appends — preserving file order, not re-sorting the union — is an O8 finding on both counts (wrong order claim, hidden merged-in entries). The finding stands even when the PR diff never touched the `.md` file, because the behavior change orphaned the doc claim. See `../../rules/docstring-prose-matches-implementation.md`. |
+| O9 | Python docstring plainness for a general developer | A changed module / class / public-function docstring's narrative prose — the summary and description before the first `Args:` / `Returns:` / `Raises:` / `Yields:` section — reads plainly and paints a concrete scene a general developer follows on first read. Flag a narrative that stacks abstract machinery nouns into a wall (`the SIGINT install/restore/installability check, the atexit terminal-record registration, and the interrupted-run finalizer`), that defines a thing by what it is not (`the non-promoter-specific machinery`), or that runs one sentence long while joining clauses with an em-dash or a semicolon. The deterministic run-on mark is gated at Write/Edit time by `check_docstring_runon_sentence` in `code_rules_docstrings.py`, so this lane carries the illustrative-and-brief judgment the gate cannot: whether a stranger to the code pictures the moment, the input, and the outcome after one read. See `../../rules/plain-illustrative-docstrings.md`. |
 
 ---
 

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

@@ -1,4 +1,4 @@
-Audit [REPO/ARTIFACT] [TARGET_ID] for **Category O only** (docstring / fixture-prose vs implementation drift). Skip A–N, P. Sub-bucket forced-exhaustion mode: Category O is decomposed into 8 sub-buckets below. Each sub-bucket REQUIRES at least one Shape A finding OR exactly one Shape B proof-of-absence with **at least 3 adversarial probes** specific to that sub-bucket. A sub-bucket returning neither is a protocol gap.
+Audit [REPO/ARTIFACT] [TARGET_ID] for **Category O only** (docstring / fixture-prose vs implementation drift). Skip A–N, P. Sub-bucket forced-exhaustion mode: Category O is decomposed into 9 sub-buckets below. Each sub-bucket REQUIRES at least one Shape A finding OR exactly one Shape B proof-of-absence with **at least 3 adversarial probes** specific to that sub-bucket. A sub-bucket returning neither is a protocol gap.
 
 [ARTIFACT METADATA — include every changed module's docstring AND the exported symbols of that module so the audit can compare claim vs body]
 
@@ -51,9 +51,13 @@ ID prefix: `find`.
 - When the diff changes a producer function's ordering or union, read that skill's companion `SKILL.md` and sibling `.md` docs for any sentence naming the same produced artifact (a file path, a JSON key, a named list). A doc sentence that claims the artifact is `sorted` / `alphabetical` / `in sorted order`, or holds `just the at-risk names` / `only the current set`, while the producer merges stored names with new names and appends — preserving file order, not re-sorting the union — is an O8 finding on both counts (wrong order claim, hidden merged-in entries). The finding stands even when the diff never touched the `.md` file, because the behavior change orphaned the doc claim.
 - Adversarial probes: (a) for each changed producer, name the artifact it builds and grep the skill's `SKILL.md` and sibling `.md` files for any sentence naming that artifact; (b) walk the producer body's build step — does it sort, or does it merge stored names and append in file order — and compare against the doc's order word (`sorted`, `alphabetical`); (c) check whether the doc's content claim (`just the at-risk names`, `only the current set`) hides merged-in prior entries the producer carries over from the stored file.
 
+**O9. Python docstring plainness for a general developer**
+- For every changed module / class / public-function docstring, read the narrative prose before the first `Args:` / `Returns:` / `Raises:` / `Yields:` section as a stranger to the code. Flag a narrative that stacks abstract machinery nouns into a single wall, that defines a thing by what it is not (`the non-promoter-specific machinery`), or that runs one sentence past the word limit while joining clauses with an em-dash or a semicolon. The run-on mark is gated at Write/Edit time by `check_docstring_runon_sentence`, so this lane judges the part the gate cannot: whether the prose paints a concrete scene — the moment the code matters, the input it sees, the outcome it produces — that a general developer follows on the first read.
+- Adversarial probes: (a) read each changed narrative and name the concrete moment, input, and outcome it paints — a narrative that names none is an O9 finding; (b) count the longest sentence's words and check for an em-dash or semicolon join — over the limit with a join is the wall mark the gate also catches; (c) rewrite each "is not" clause as a positive statement — a clause that resists rewriting because the body offers no positive description is an O9 finding.
+
 ## Cross-bucket questions to answer at the end
 
-Q1: Across all 8 sub-buckets, which docstring claim is the most misleading — i.e., a future maintainer reading only the docstring would write or change code that contradicts the body? Cite file:line of the docstring AND the body line(s) that contradict it.
+Q1: Across all 9 sub-buckets, which docstring claim is the most misleading — i.e., a future maintainer reading only the docstring would write or change code that contradicts the body? Cite file:line of the docstring AND the body line(s) that contradict it.
 
 Q2: Which docstring claim is at highest risk of becoming load-bearing — i.e., a future caller or test author would rely on the claim to skip reading the body? Cite the claim and the use case.
 
@@ -61,13 +65,13 @@ Q3: Of the changed docstrings, which one most clearly shows a refactor was incom
 
 ## Output
 
-Lead: `Total: N (P0=N, P1=N, P2=N)`. For each sub-bucket O1-O8, produce Shape A or Shape B (with ≥3 probes). Each Shape A finding must cite (a) the docstring file:line, (b) the body file:line that contradicts it, and (c) one sentence describing the contradiction in concrete terms. Cross-bucket Q1-Q3 answers after the per-sub-bucket walk. Adversarial second pass: "assume your first pass missed at least 3 module-level docstring claims whose implementation moved during a refactor — find them." Open Questions section for ambiguities. Read-only. No edits, no commits.
+Lead: `Total: N (P0=N, P1=N, P2=N)`. For each sub-bucket O1-O9, produce Shape A or Shape B (with ≥3 probes). Each Shape A finding must cite (a) the docstring file:line, (b) the body file:line that contradicts it, and (c) one sentence describing the contradiction in concrete terms. Cross-bucket Q1-Q3 answers after the per-sub-bucket walk. Adversarial second pass: "assume your first pass missed at least 3 module-level docstring claims whose implementation moved during a refactor — find them." Open Questions section for ambiguities. Read-only. No edits, no commits.
 
 ---
 
 # Worked example: jl-cmd/claude-code-config PR #522
 
-Audit jl-cmd/claude-code-config PR #522 for **Category O only** (docstring / fixture-prose vs implementation drift). Skip A-N, P. Sub-bucket forced-exhaustion mode: Category O is decomposed into 8 sub-buckets below.
+Audit jl-cmd/claude-code-config PR #522 for **Category O only** (docstring / fixture-prose vs implementation drift). Skip A-N, P. Sub-bucket forced-exhaustion mode: Category O is decomposed into 9 sub-buckets below.
 
 PR #522 split `pr_description_command_parser.py` into two modules — the original parser and a new `pr_description_pr_number.py` — but the originating module's docstring still claims the PR-number recovery responsibility. A sibling change to `pr_description_body_audit.py` introduced a module docstring whose verb (`detects vague language`) overstates the module's actual responsibility (it only exposes `_extract_vague_scan_text()`; detection runs elsewhere).
 

package/hooks/blocking/CLAUDE.md

@@ -29,6 +29,7 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `code_rules_dead_config_field.py` | `*Config` / `*Selectors` dataclass fields with no live references |
 | `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_dead_split_branch.py` | A conditional whose falsy branch is unreachable because the tested value comes from a separator `str.split()`, which never returns an empty list |
 | `code_rules_docstrings.py` | Google-style docstrings; `Args:` section matches signature; fallback-branch coverage |
 | `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 |
@@ -37,6 +38,7 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `code_rules_naming_collection.py` | Collection names must use `all_*` prefix |
 | `code_rules_optional_params.py` | No optional parameters where a required one would do |
 | `code_rules_orphan_css_class.py` | CSS class attributes in Python markup with no matching `.<class>` selector |
+| `code_rules_paired_test.py` | A public function omitted by a module's established paired test suite must get a behavioral test |
 | `code_rules_path_utils.py` | Path utility helpers shared across check modules |
 | `code_rules_paths_syspath.py` | `sys.path.insert` must be guarded |
 | `code_rules_probe_chains.py` | Probe-chain detection logic |
@@ -44,7 +46,7 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `code_rules_probe_recording.py` | Probe recording utilities |
 | `code_rules_scope_binding.py` | Scope/binding analysis utilities |
 | `code_rules_shared.py` | Shared dataclasses and helpers used by multiple check modules |
-| `code_rules_string_magic.py` | Magic string detection with masking and f-string support |
+| `code_rules_string_magic.py` | Magic string detection with masking and f-string support; whitespace-only indentation literals in function bodies |
 | `code_rules_test_assertions.py` | Test assertion style rules |
 | `code_rules_test_branching_except.py` | No bare or broad `except` in test branches |
 | `code_rules_test_isolation.py` | Tests must not rely on home-dir or temp-dir side effects |

package/hooks/blocking/code_rules_dead_module_constant.py

@@ -16,18 +16,26 @@ The scan is deliberately conservative to keep false positives near zero:
 
 - Only dedicated constants modules participate; ordinary production modules,
   whose file-global constants are governed by the use-count rule, are skipped.
-- A module declaring ``__all__`` is skipped: the author has named its export
-  surface explicitly, so a name listed there is live by declaration and a name
-  absent there is the author's stated intent, neither of which this check second
-  guesses.
-- A constant is live when its name appears anywhere the scan reaches —
-  imported, read, listed in ``__all__``, or referenced in a string annotation —
-  in any ``.py`` module, including the constants module itself.
+- A module declaring ``__all__`` narrows the check to the constants its
+  ``__all__`` list names — the explicit export surface. Each exported constant
+  must be imported or read by some other module, since a name an author exports
+  yet no module consumes is dead by §9.8; the module's own ``__all__`` entry
+  never counts as that consumer. A constant the module defines but ``__all__``
+  omits is the author's stated private value and is left alone.
+- A constant is live when its name appears in another ``.py`` module the scan
+  reaches — imported, read, listed in that module's ``__all__``, or referenced
+  in a string annotation — or when the constants module itself reads it in code;
+  a name listed only in the constants module's own ``__all__`` does not keep an
+  exported constant live.
 - When the package-tree scan leaves a constant unreferenced, the scan widens to
-  the repository root (the nearest ``.git`` ancestor) so a consumer in a sibling
-  tree of the same repository counts; a module outside any repository is judged
-  on the package-tree scan alone. The widened pass skips the package subtree the
-  first pass already covered, so no file is read twice.
+  the repository root (the nearest ``.git`` ancestor). The widened pass counts a
+  sibling-tree reference only when a module imports the name through a
+  ``from <module> import`` whose final dotted segment equals the written
+  module's filename stem, so a genuine cross-tree consumer of this constants
+  module keeps the constant live while a same-named constant exported by an
+  unrelated module never masks a dead one. A module outside any repository is
+  judged on the package-tree scan alone, and the widened pass skips the package
+  subtree the first pass already covered, so no file is read twice.
 - The combined file count of the package-tree and widened passes is bounded by a
   cap, so a write under an unexpectedly large tree cannot stall the hook; a write
   whose scan hits the cap is treated as "cannot prove dead" and flags nothing.
@@ -38,6 +46,8 @@ The scan is deliberately conservative to keep false positives near zero:
 import ast
 import os
 import sys
+from collections.abc import Callable
+from functools import partial
 from pathlib import Path
 
 _blocking_directory = str(Path(__file__).resolve().parent)
@@ -146,21 +156,61 @@ def _module_declares_dunder_all(tree: ast.Module) -> bool:
     return any(_statement_binds_dunder_all(each_node) for each_node in tree.body)
 
 
-def _referenced_names_in_source(source: str, load_only: bool = False) -> set[str]:
+def _dunder_all_member_names(tree: ast.Module) -> set[str]:
+    """Return the string member names a module's ``__all__`` sequence lists.
+
+    Reads the value of each ``__all__`` assignment whose value is a list, tuple,
+    or set literal and collects every string element. A non-literal ``__all__``
+    value (built by concatenation or a comprehension) contributes no names, so a
+    constant the check cannot prove is exported stays out of the exported set.
+
+    Args:
+        tree: The parsed constants module.
+
+    Returns:
+        The set of names the module names in its ``__all__`` literal.
+    """
+    member_names: set[str] = set()
+    for each_statement in tree.body:
+        if not _statement_binds_dunder_all(each_statement):
+            continue
+        value_node: ast.expr | None = None
+        if isinstance(each_statement, ast.Assign):
+            value_node = each_statement.value
+        elif isinstance(each_statement, ast.AnnAssign):
+            value_node = each_statement.value
+        if not isinstance(value_node, ast.List | ast.Tuple | ast.Set):
+            continue
+        for each_element in value_node.elts:
+            if isinstance(each_element, ast.Constant) and isinstance(each_element.value, str):
+                member_names.add(each_element.value)
+    return member_names
+
+
+def _referenced_names_in_source(
+    source: str,
+    load_only: bool = False,
+    collect_string_literals: bool = True,
+) -> set[str]:
     """Return every name a module references — imported, read, or re-exported.
 
     Collects imported binding names, ``from`` import member names, name
-    references, attribute roots, and string literals (so a name listed in an
-    ``__all__`` literal or named in a string annotation counts as a reference).
-    A module that fails to parse contributes no names. With ``load_only`` set,
-    only ``Load``-context names count, so a constant's own assignment target in
-    the module being judged does not count as a reference to itself.
+    references, attribute roots, and (when ``collect_string_literals`` is set)
+    string literals, so a name listed in an ``__all__`` literal or named in a
+    string annotation counts as a reference. A module that fails to parse
+    contributes no names. With ``load_only`` set, only ``Load``-context names
+    count, so a constant's own assignment target in the module being judged does
+    not count as a reference to itself.
 
     Args:
         source: The full text of a ``.py`` module under the scan root.
         load_only: When True, count only ``Load``-context name references,
             excluding ``Store``/``Del`` targets. Used for the written constants
             module so a definition is not mistaken for its own consumer.
+        collect_string_literals: When True, count every string literal as a
+            referenced name. Set False for the written module under an ``__all__``
+            export check so the module's own ``__all__`` entry never shields an
+            exported constant that no other module consumes.
 
     Returns:
         The set of names the module references.
@@ -179,11 +229,63 @@ def _referenced_names_in_source(source: str, load_only: bool = False) -> set[str
             for each_alias in each_node.names:
                 referenced_names.add(each_alias.asname or each_alias.name)
                 referenced_names.add(each_alias.name)
-        elif isinstance(each_node, ast.Constant) and isinstance(each_node.value, str):
+        elif (
+            collect_string_literals
+            and isinstance(each_node, ast.Constant)
+            and isinstance(each_node.value, str)
+        ):
             referenced_names.add(each_node.value)
     return referenced_names
 
 
+def _module_final_segment(module_path: str | None) -> str:
+    """Return the final dotted segment of an import module path.
+
+    Args:
+        module_path: The ``module`` attribute of a ``from ... import`` node, or
+            None for a bare relative import (``from . import x``).
+
+    Returns:
+        The text after the last dot, the whole string when it carries no dot, or
+        the empty string when ``module_path`` is None or empty.
+    """
+    if not module_path:
+        return ""
+    return module_path.rsplit(".", 1)[-1]
+
+
+def _qualified_import_member_names(source: str, module_stem: str) -> set[str]:
+    """Return names imported from a module whose filename stem is ``module_stem``.
+
+    A cross-package consumer of an exported constant imports it through an
+    explicit ``from <module> import NAME`` whose module path ends in the defining
+    module's filename stem. Collecting only those member names binds a
+    widened-scan reference to the module that actually defines the constant, so a
+    same-named constant exported by an unrelated module never masks a dead one.
+
+    Args:
+        source: The full text of a ``.py`` module under the repository root.
+        module_stem: The filename stem of the constants module being judged.
+
+    Returns:
+        The member names imported from a module whose final dotted segment equals
+        ``module_stem``. A module that fails to parse contributes no names.
+    """
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return set()
+    member_names: set[str] = set()
+    for each_node in ast.walk(tree):
+        if not isinstance(each_node, ast.ImportFrom):
+            continue
+        if _module_final_segment(each_node.module) != module_stem:
+            continue
+        for each_alias in each_node.names:
+            member_names.add(each_alias.name)
+    return member_names
+
+
 def _scan_root_for_constants_module(file_path: str) -> Path:
     """Return the directory tree to scan for references to the module's constants.
 
@@ -226,41 +328,48 @@ def _is_under_directory(candidate_path: Path, ancestor_directory: Path) -> bool:
     return True
 
 
-def _all_referenced_names_under_root(
+def _collect_names_under_root(
     scan_root: Path,
     written_path: Path,
-    written_content: str,
+    all_seed_names: set[str],
+    extract_names: Callable[[str], set[str]],
     already_scanned_count: int = 0,
     excluded_subtree: Path | None = None,
 ) -> tuple[set[str], int, bool]:
-    """Return referenced names under the scan root, the running count, and a cap flag.
-
-    The written module's on-disk text is replaced by ``written_content`` so the
-    post-edit view is judged, never the stale disk copy. Sibling modules are read
-    from disk. Reading stops once the running file count exceeds the configured
-    cap so a write under an unexpectedly large tree cannot stall the hook; the
-    boolean signals the caller to treat that case as "cannot prove dead". When
-    ``excluded_subtree`` is supplied, every ``.py`` module under that directory is
-    skipped, so the widened repository scan never re-reads a file the
+    """Collect referenced names under the scan root via a per-module extractor.
+
+    Walks every ``.py`` module under ``scan_root`` (excluding the written module
+    itself, and any module under ``excluded_subtree``), applies ``extract_names``
+    to each module's text, and unions the result onto ``all_seed_names``. Reading
+    stops once the running file count exceeds the configured cap so a write under
+    an unexpectedly large tree cannot stall the hook; the boolean signals the
+    caller to treat that case as "cannot prove dead". The ``excluded_subtree``
+    skip keeps the widened repository scan from re-reading a file the
     package-tree scan already covered.
 
     Args:
         scan_root: The directory tree to scan.
-        written_path: The resolved path of the module being written.
-        written_content: The post-edit text of the written module.
+        written_path: The resolved path of the module being written, skipped so
+            its own text is judged through ``all_seed_names`` rather than the
+            stale disk copy.
+        all_seed_names: The names the written module itself contributes, unioned
+            in before the walk begins.
+        extract_names: Maps one module's source text to the set of names it
+            contributes — the generous reference collector for the package-tree
+            pass, the stem-bound import collector for the widened pass.
         already_scanned_count: The file count accumulated by a prior pass, so the
             cap bounds the combined work of the package-tree and widened passes.
         excluded_subtree: A resolved directory whose ``.py`` modules are skipped,
             or None to scan every file under the root.
 
     Returns:
-        A (referenced_names, running_count, cap_was_hit) triple. The name set is
-        the union across every scanned module, unioned with the names the written
-        module itself references; running_count is the cumulative file count
-        including ``already_scanned_count``; cap_was_hit is True when the scan
-        stopped at the configured file cap before scanning the whole tree.
+        A (collected_names, running_count, cap_was_hit) triple. collected_names
+        is ``all_seed_names`` unioned with every scanned module's contribution;
+        running_count is the cumulative file count including
+        ``already_scanned_count``; cap_was_hit is True when the scan stopped at
+        the configured file cap before scanning the whole tree.
     """
-    all_referenced_names = _referenced_names_in_source(written_content, load_only=True)
+    collected_names = set(all_seed_names)
     written_path_key = os.path.normcase(str(written_path))
     scanned_file_count = already_scanned_count
     for each_path in scan_root.rglob("*" + PYTHON_SOURCE_SUFFIX):
@@ -273,13 +382,13 @@ def _all_referenced_names_under_root(
             continue
         scanned_file_count += 1
         if scanned_file_count > MAX_SCAN_ROOT_FILE_COUNT:
-            return all_referenced_names, scanned_file_count, True
+            return collected_names, scanned_file_count, True
         try:
             sibling_source = each_path.read_text(encoding="utf-8")
         except (OSError, UnicodeDecodeError):
             continue
-        all_referenced_names |= _referenced_names_in_source(sibling_source)
-    return all_referenced_names, scanned_file_count, False
+        collected_names |= extract_names(sibling_source)
+    return collected_names, scanned_file_count, False
 
 
 def _repository_root_for(written_path: Path) -> Path | None:
@@ -324,6 +433,37 @@ def _module_is_exempt_from_constant_check(file_path: str) -> bool:
     return not _is_dedicated_constants_module(file_path)
 
 
+def _constants_under_check(tree: ast.Module) -> tuple[list[tuple[str, int]], bool]:
+    """Return the constants to judge and whether the seed counts string literals.
+
+    A module without ``__all__`` judges every module-scope constant and lets its
+    own string literals seed the reference scan. A module declaring ``__all__``
+    judges only the constants its ``__all__`` list names — the explicit export
+    surface — and withholds its own string literals from the seed, so an
+    ``__all__`` entry never counts as the consumer that keeps an exported constant
+    live. A constant the module defines but ``__all__`` omits is the author's
+    stated private value and is left out of the judged set.
+
+    Args:
+        tree: The parsed constants module.
+
+    Returns:
+        A (definitions, seed_collect_string_literals) pair: the (name, line)
+        constants to judge, and whether the written module's string literals seed
+        the referenced-name set.
+    """
+    constant_definitions = _module_constant_definitions(tree)
+    if not _module_declares_dunder_all(tree):
+        return constant_definitions, True
+    exported_names = _dunder_all_member_names(tree)
+    exported_definitions = [
+        (each_name, each_line)
+        for each_name, each_line in constant_definitions
+        if each_name in exported_names
+    ]
+    return exported_definitions, False
+
+
 def check_dead_module_constants(
     content: str,
     file_path: str,
@@ -334,16 +474,23 @@ def check_dead_module_constants(
     Runs only on a dedicated constants module (``*_constants.py`` or a module
     under ``config/``); every other production module's file-global constants
     are governed by the use-count rule instead. A constant is dead when its name
-    appears in no ``.py`` module under the enclosing package tree, nor anywhere
-    in the repository the scan widens to when the package-tree scan leaves the
-    constant unreferenced — not imported, not read, not listed in an ``__all__``
-    literal, not named in a string annotation. A module declaring its own
-    ``__all__`` is skipped so the author's explicit export surface is never
-    second-guessed. A scan whose combined package-tree and widened file count
-    exceeds the configured cap returns ``[]`` (cannot prove dead), bounding the
-    work so the blocking hook cannot stall under a large tree. Whole-file
-    analysis runs against ``full_file_content`` when supplied so an Edit fragment
-    is judged against the reconstructed post-edit file.
+    appears in no ``.py`` module under the enclosing package tree — not imported,
+    not read, not listed in another module's ``__all__`` literal, not named in a
+    string annotation — and, in the repository-wide scan the check widens to when
+    the package-tree scan leaves the constant unreferenced, no module imports the
+    name from a ``from <module> import`` whose final dotted segment equals this
+    module's filename stem. Binding the widened scan to the stem keeps a genuine
+    cross-tree consumer counting while a same-named constant exported by an
+    unrelated module never masks a dead one. A module declaring ``__all__``
+    narrows the check to the constants its ``__all__`` list names: each must be
+    imported or read by another module, and the module's own ``__all__`` entry
+    never counts as that consumer, so an exported constant no module consumes is
+    flagged; a constant the module defines but ``__all__`` omits is the author's
+    private value and is left alone. A scan whose combined package-tree and
+    widened file count exceeds the configured cap returns ``[]`` (cannot prove
+    dead), bounding the work so the blocking hook cannot stall under a large tree.
+    Whole-file analysis runs against ``full_file_content`` when supplied so an
+    Edit fragment is judged against the reconstructed post-edit file.
 
     Args:
         content: The new content under validation (Edit fragment or whole file).
@@ -355,8 +502,9 @@ def check_dead_module_constants(
     Returns:
         One violation message per dead module-level constant, capped at the
         configured maximum. Returns an empty list when the file is exempt, no
-        constant is defined, the module declares ``__all__``, the scan exceeds the
-        file cap, or a SyntaxError prevents parsing.
+        constant is in scope (none defined, or none exported when ``__all__`` is
+        declared), the scan exceeds the file cap, or a SyntaxError prevents
+        parsing.
     """
     if _module_is_exempt_from_constant_check(file_path):
         return []
@@ -365,17 +513,21 @@ def check_dead_module_constants(
         tree = ast.parse(effective_content)
     except SyntaxError:
         return []
-    if _module_declares_dunder_all(tree):
-        return []
-    constant_definitions = _module_constant_definitions(tree)
+    constant_definitions, seed_collect_string_literals = _constants_under_check(tree)
     if not constant_definitions:
         return []
     scan_root = _scan_root_for_constants_module(file_path)
     written_path = Path(file_path).resolve()
-    all_referenced_names, scanned_file_count, cap_was_hit = _all_referenced_names_under_root(
+    written_seed_names = _referenced_names_in_source(
+        effective_content,
+        load_only=True,
+        collect_string_literals=seed_collect_string_literals,
+    )
+    all_referenced_names, scanned_file_count, cap_was_hit = _collect_names_under_root(
         scan_root,
         written_path,
-        effective_content,
+        written_seed_names,
+        _referenced_names_in_source,
     )
     if cap_was_hit:
         return []
@@ -385,10 +537,14 @@ def check_dead_module_constants(
     if has_unreferenced_constant:
         repository_root = _repository_root_for(written_path)
         if repository_root is not None and repository_root != scan_root:
-            widened_names, _widened_count, widened_cap_was_hit = _all_referenced_names_under_root(
+            collect_qualified_imports = partial(
+                _qualified_import_member_names, module_stem=written_path.stem
+            )
+            widened_names, _widened_count, widened_cap_was_hit = _collect_names_under_root(
                 repository_root,
                 written_path,
-                effective_content,
+                set(),
+                collect_qualified_imports,
                 already_scanned_count=scanned_file_count,
                 excluded_subtree=scan_root,
             )