claude-dev-env 1.65.0 → 1.66.0

package/agents/plan-packet-validator.md

@@ -0,0 +1,34 @@
+---
+name: plan-packet-validator
+description: Fresh-context validator for workflow-generated plan packets. Use after a plan packet is written under docs/plans/<slug>/ to verify source accuracy, completeness, TDD readiness, scope control, handoff quality, and no invented repo behavior. Read-only; never edits files.
+tools: Read, Grep, Glob, Bash
+model: inherit
+color: purple
+---
+
+You validate plan packets. You are not the planner and you do not repair docs.
+
+## Rules
+
+- Never edit files.
+- Require each material claim to be source-backed, user-confirmed, or explicitly listed as a packet assumption.
+- Treat every packet claim as untrusted until you verify it against source files, repo docs, user-confirmed decisions, or packet assumptions.
+- Return findings only for problems that would make a blind build agent implement the wrong thing or need to rediscover core context.
+- Do not raise style-only findings.
+
+## Checks
+
+1. Read `README.md`, `packet.json`, `context/source-map.md`, `implementation/steps.md`, `implementation/tdd-plan.md`, `spec/acceptance.md`, and `handoff/build-prompt.md`.
+2. Read or search the source files named in `source-map.md` and `packet.json`.
+3. Verify referenced paths exist unless the packet clearly labels them as new files.
+4. Verify source facts match actual files.
+5. Verify the implementation steps are enough for a blind build agent.
+6. Verify the TDD sequence starts with failing tests and names the behavior those tests prove.
+7. Verify scope matches the user request and non-goals.
+8. Verify no commands, APIs, schemas, hooks, workflows, agents, or repo conventions are invented.
+9. Verify acceptance criteria prove the requested behavior end to end.
+10. Verify `handoff/build-prompt.md` stands alone without chat history.
+
+## Output
+
+Return the requested structured schema. Set `allPassed` to true only when every check is clean. Each finding must name the packet file, the check, and the exact source-grounded problem.

package/audit-rubrics/category_rubrics/category-n-test-name-scenario-verifier.md

@@ -37,6 +37,12 @@ Customize per-artifact: a pure-function test corpus with no scenario claims redu
 
 ---
 
+## Write-time advisory for the flag-gated N1 slice
+
+`check_flag_gated_scenario_test_naming` in `code_rules_test_assertions.py` (wired into `code_rules_enforcer.py`) catches the deterministic N1 slice at Write/Edit time. When two or more sibling tests in a file `monkeypatch.setattr` the same module-level UPPER_SNAKE flag, that flag governs which branch the code under test runs. A `test_*` whose name carries a scenario clause (`_when_`, `_passes`, `_succeeds`, `_on_clean`) but never patches that flag runs under the flag's default value, so its named condition may not be in effect. The check prints an advisory to stderr and never blocks the write — the breadth of the sibling-pattern heuristic suits a judgment lane, where the author decides whether to patch the flag (and assert the gated path runs) or rename the test. The audit still owns the full N1–N10 surface; the advisory only surfaces this one mechanically-detectable shape early.
+
+---
+
 ## Sample prompt
 
 The reusable Variant C template for Category N is in [`../prompts/category-n-test-name-scenario-verifier.md`](../prompts/category-n-test-name-scenario-verifier.md). Inline every changed test function under `## Source material` along with the production function it claims to cover, so the audit can compare the named scenario against the body's act phase.

package/commands/plan.md

@@ -1,60 +1,14 @@
-Plan a feature with full validation workflow.
+Plan a feature through the workflow-backed `anthropic-plan` skill.
 
-> **MANDATORY:** Load `~/.claude/docs/CODE_RULES.md` for all code standards.
+Invoke `anthropic-plan` with the user request. The skill launches the Claude Code Workflow at:
 
-## Workflow (MANDATORY - NO SKIPPING STEPS)
+`$HOME/.claude/skills/anthropic-plan/workflow/plan-packet.mjs`
 
-### Phase 1: Design
-1. **Invoke `plan` skill** - Discover configs, design through dialogue
+The workflow creates a validated `docs/plans/<slug>/` packet, spawns the fresh `plan-packet-validator` agent, repairs packet findings, and stops before implementation.
 
-### Phase 2: Plan
-2. **Invoke `write-plan` skill** - Create detailed TDD implementation plan (CODE_RULES.md compliant)
-3. **Invoke `review-plan` skill** - Validate plan against CODE_RULES.md standards
-4. **Fix violations** - If review-plan finds issues, fix before proceeding
+Usage:
 
-### Phase 3: Approval (NEW PRs only)
-5. **Invoke `plan-checkpoint` skill** - Generate summary gist for reviewer approval
-6. **Wait for approval** - Do not proceed until approved
-
-### Phase 4: Execute
-7. **Invoke `plan-executor` agent** - Execute with full standards enforcement
-8. **Invoke `readability-review` skill** - Validate written code against CODE_RULES.md
-
-### Phase 5: Commit & Review
-9. **Invoke `/commit`** - Create atomic commits
-10. **Push branch** - Push to GitHub (NO PR yet); the git pre-push hook installed via `npx claude-dev-env` fires automatically and blocks on any violation
-11. **Wait for commit review** - User reviews on GitHub
-12. **Create PR** - Only after user approves commit
-
-## Key Rules
-
-- NEVER offer execution until review-plan passes with ZERO violations
-- For NEW PRs: wait for reviewer approval on checkpoint before implementing
-- For PR REVIEW FIXES: skip checkpoint, proceed directly to execution
-- NEVER push if the git pre-push hook fails (it fires automatically via `npx claude-dev-env`)
-- NEVER create PR until user explicitly approves pushed commit
-
-## Skills & Agents Reference
-
-| Step | Tool | Purpose |
-|------|------|---------|
-| Design | `plan` skill | Collaborative design with config discovery |
-| Write | `write-plan` skill | TDD plan with CODE_RULES.md compliance |
-| Review Plan | `review-plan` skill | Validate plan against standards |
-
-## Standards Reference
-
-All code quality standards are in `~/.claude/docs/CODE_RULES.md`:
-- Self-documenting code (no comments)
-- Centralized configs (reuse existing)
-- No magic values
-- No abbreviations
-- Complete type hints
-- All imports shown
-
-## Usage
-
-```
+```text
 /plan add user authentication
 /plan refactor the payment system
 ```

package/hooks/blocking/code_rules_dead_module_constant.py

@@ -6,8 +6,10 @@ project, so a constant defined there is never proven dead by a single-file scan
 alone. This check resolves the enclosing package tree — the scan root — and
 flags an UPPER_SNAKE constant defined in the written module whose name appears
 in no ``.py`` module anywhere under that root: not as an imported name, not as a
-read, not as a re-export. That is the ``MEDIUM_TEXT``-style dead constant the
-CODE_RULES §9.8 dead-code rule targets, caught at Write/Edit time before the
+read, not as a re-export. When a constant looks dead in the package tree, the
+scan widens to the whole repository so a consumer in a sibling tree counts
+before the constant is flagged. That is the ``MEDIUM_TEXT``-style dead constant
+the CODE_RULES §9.8 dead-code rule targets, caught at Write/Edit time before the
 unused constant lands.
 
 The scan is deliberately conservative to keep false positives near zero:
@@ -18,11 +20,19 @@ The scan is deliberately conservative to keep false positives near zero:
   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 under the scan root —
+- 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.
-- Test modules under the scan root still count as references, so a constant used
-  only by a test stays 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 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.
+- Test modules under the scanned tree still count as references, so a constant
+  used only by a test stays live.
 """
 
 import ast
@@ -48,6 +58,7 @@ from hooks_constants.dead_module_constant_constants import (  # noqa: E402
     DEAD_MODULE_CONSTANT_GUIDANCE,
     DUNDER_ALL_NAME,
     DUNDER_INIT_FILENAME,
+    GIT_DIRECTORY_NAME,
     MAX_DEAD_MODULE_CONSTANT_ISSUES,
     MAX_SCAN_ROOT_FILE_COUNT,
     MINIMUM_UPPER_SNAKE_LENGTH,
@@ -197,46 +208,100 @@ def _scan_root_for_constants_module(file_path: str) -> Path:
     return enclosing_directory
 
 
+def _is_under_directory(candidate_path: Path, ancestor_directory: Path) -> bool:
+    """Return whether a resolved path lies inside a resolved ancestor directory.
+
+    Args:
+        candidate_path: The resolved file path to test.
+        ancestor_directory: The resolved directory that may contain the path.
+
+    Returns:
+        True when ``candidate_path`` is the ancestor directory itself or a
+        descendant of it, False otherwise.
+    """
+    try:
+        candidate_path.relative_to(ancestor_directory)
+    except ValueError:
+        return False
+    return True
+
+
 def _all_referenced_names_under_root(
     scan_root: Path,
     written_path: Path,
     written_content: str,
-) -> tuple[set[str], bool]:
-    """Return referenced names under the scan root and whether the file cap was hit.
+    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 after the configured file 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".
+    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
+    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.
+        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, cap_was_hit) pair. The name set is the union across
-        every scanned module; cap_was_hit is True when the scan stopped at the
-        configured file cap before scanning the whole tree.
+        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.
     """
     all_referenced_names = _referenced_names_in_source(written_content, load_only=True)
     written_path_key = os.path.normcase(str(written_path))
-    scanned_file_count = 1
+    scanned_file_count = already_scanned_count
     for each_path in scan_root.rglob("*" + PYTHON_SOURCE_SUFFIX):
         if not each_path.is_file():
             continue
-        if os.path.normcase(str(each_path.resolve())) == written_path_key:
+        resolved_path = each_path.resolve()
+        if os.path.normcase(str(resolved_path)) == written_path_key:
+            continue
+        if excluded_subtree is not None and _is_under_directory(resolved_path, excluded_subtree):
             continue
         scanned_file_count += 1
         if scanned_file_count > MAX_SCAN_ROOT_FILE_COUNT:
-            return all_referenced_names, True
+            return all_referenced_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, False
+    return all_referenced_names, scanned_file_count, False
+
+
+def _repository_root_for(written_path: Path) -> Path | None:
+    """Return the nearest ancestor directory that holds a ``.git`` entry.
+
+    Walks upward from the written module toward the filesystem root. A normal
+    checkout carries a ``.git`` directory and a git worktree carries a ``.git``
+    file; both satisfy ``exists()``. The repository root bounds the widened
+    cross-tree reference scan.
+
+    Args:
+        written_path: The resolved path of the constants module being written.
+
+    Returns:
+        The repository root directory, or ``None`` when no ancestor carries a
+        ``.git`` entry, so a module outside any repository triggers no widened
+        scan.
+    """
+    for each_ancestor in written_path.parents:
+        if (each_ancestor / GIT_DIRECTORY_NAME).exists():
+            return each_ancestor
+    return None
 
 
 def _module_is_exempt_from_constant_check(file_path: str) -> bool:
@@ -269,10 +334,14 @@ 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 anywhere under the enclosing package tree — 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. Whole-file
+    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.
 
@@ -285,7 +354,9 @@ def check_dead_module_constants(
 
     Returns:
         One violation message per dead module-level constant, capped at the
-        configured maximum.
+        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.
     """
     if _module_is_exempt_from_constant_check(file_path):
         return []
@@ -301,13 +372,29 @@ def check_dead_module_constants(
         return []
     scan_root = _scan_root_for_constants_module(file_path)
     written_path = Path(file_path).resolve()
-    all_referenced_names, cap_was_hit = _all_referenced_names_under_root(
+    all_referenced_names, scanned_file_count, cap_was_hit = _all_referenced_names_under_root(
         scan_root,
         written_path,
         effective_content,
     )
     if cap_was_hit:
         return []
+    has_unreferenced_constant = any(
+        each_name not in all_referenced_names for each_name, _ in constant_definitions
+    )
+    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(
+                repository_root,
+                written_path,
+                effective_content,
+                already_scanned_count=scanned_file_count,
+                excluded_subtree=scan_root,
+            )
+            if widened_cap_was_hit:
+                return []
+            all_referenced_names |= widened_names
     issues: list[str] = []
     for each_name, each_line in constant_definitions:
         if each_name in all_referenced_names:

package/hooks/blocking/code_rules_enforcer.py

@@ -117,6 +117,7 @@ from code_rules_string_magic import (  # noqa: E402
 from code_rules_test_assertions import (  # noqa: E402
     check_constant_equality_tests,
     check_existence_check_tests,
+    check_flag_gated_scenario_test_naming,
     check_skip_decorators_in_tests,
 )
 from code_rules_test_branching_except import (  # noqa: E402
@@ -274,6 +275,7 @@ def validate_content(
         )
         all_issues.extend(check_existence_check_tests(content, file_path))
         all_issues.extend(check_constant_equality_tests(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))
         all_issues.extend(check_stuttering_collection_prefix(content, file_path))

package/hooks/blocking/code_rules_test_assertions.py

@@ -1,9 +1,12 @@
-"""Skip-decorator, existence-only, and constant-equality test-quality checks."""
+"""Skip-decorator, existence-only, constant-equality, and flag-gated scenario test-quality checks."""
 
 import ast
 import sys
 from pathlib import Path
 
+_SCENARIO_NAME_CLAUSES = ("_when_", "_passes", "_succeeds", "_on_clean")
+_MINIMUM_SIBLING_PATCH_COUNT = 2
+
 _BLOCKING_DIRECTORY = str(Path(__file__).resolve().parent)
 _HOOKS_DIRECTORY = str(Path(__file__).resolve().parent.parent)
 if _BLOCKING_DIRECTORY not in sys.path:
@@ -224,3 +227,122 @@ def check_constant_equality_tests(content: str, file_path: str) -> list[str]:
             )
 
     return issues
+
+
+def _flag_symbol_from_setattr_target(target_node: ast.expr) -> str | None:
+    """Return the UPPER_SNAKE flag symbol a monkeypatch.setattr target names.
+
+    Accepts both target shapes monkeypatch.setattr supports: a dotted string
+    path (``"pkg.module.FLAG"``) and an attribute access (``module.FLAG``). The
+    flag is the final dotted segment when that segment is UPPER_SNAKE_CASE; any
+    other segment shape returns None so only module-level boolean flags qualify.
+
+    Args:
+        target_node: The first positional argument of a ``monkeypatch.setattr``
+            call.
+
+    Returns:
+        The UPPER_SNAKE flag name, or None when the target names no such symbol.
+    """
+    if isinstance(target_node, ast.Constant) and isinstance(target_node.value, str):
+        final_segment = target_node.value.rsplit(".", 1)[-1]
+        return final_segment if _is_upper_snake_name(final_segment) else None
+    if isinstance(target_node, ast.Attribute):
+        return target_node.attr if _is_upper_snake_name(target_node.attr) else None
+    return None
+
+
+def _is_monkeypatch_setattr(call_node: ast.Call) -> bool:
+    """Return True when a Call node is a ``monkeypatch.setattr(...)`` invocation."""
+    function_reference = call_node.func
+    return (
+        isinstance(function_reference, ast.Attribute)
+        and function_reference.attr == "setattr"
+        and isinstance(function_reference.value, ast.Name)
+        and function_reference.value.id == "monkeypatch"
+    )
+
+
+def _flags_patched_in_test(function_node: ast.FunctionDef | ast.AsyncFunctionDef) -> set[str]:
+    """Return the set of UPPER_SNAKE flag symbols a test patches via monkeypatch.setattr."""
+    patched_flags: set[str] = set()
+    for each_node in ast.walk(function_node):
+        if not isinstance(each_node, ast.Call):
+            continue
+        if not _is_monkeypatch_setattr(each_node) or not each_node.args:
+            continue
+        flag_symbol = _flag_symbol_from_setattr_target(each_node.args[0])
+        if flag_symbol is not None:
+            patched_flags.add(flag_symbol)
+    return patched_flags
+
+
+def _name_encodes_scenario(test_name: str) -> bool:
+    """Return True when a test name carries a scenario clause asserting a condition."""
+    return any(each_clause in test_name for each_clause in _SCENARIO_NAME_CLAUSES)
+
+
+def check_flag_gated_scenario_test_naming(content: str, file_path: str) -> list[str]:
+    """Flag a scenario-named test that omits a flag its siblings establish.
+
+    When two or more sibling tests in a file monkeypatch the same module-level
+    UPPER_SNAKE flag, that flag governs which branch the code under test runs.
+    A test whose name asserts a scenario (``_when_``, ``_passes``, ``_succeeds``,
+    ``_on_clean``) but never patches that flag runs under the flag's default
+    value, so its named condition may not be in effect — the audit category N
+    test-name-scenario mismatch. Advisory only; emitted to stderr, never blocks.
+    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:
+        An empty list; advisories print to stderr so the write proceeds.
+    """
+    if not is_test_file(file_path):
+        return []
+
+    try:
+        syntax_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+
+    test_functions = [
+        each_node
+        for each_node in ast.walk(syntax_tree)
+        if isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef))
+        and each_node.name.startswith("test")
+    ]
+    flags_patched_by_test = {
+        each_test.name: _flags_patched_in_test(each_test) for each_test in test_functions
+    }
+    sibling_patch_count_by_flag: dict[str, int] = {}
+    for patched_flags in flags_patched_by_test.values():
+        for each_flag in patched_flags:
+            sibling_patch_count_by_flag[each_flag] = (
+                sibling_patch_count_by_flag.get(each_flag, 0) + 1
+            )
+    established_flags = {
+        each_flag
+        for each_flag, patch_count in sibling_patch_count_by_flag.items()
+        if patch_count >= _MINIMUM_SIBLING_PATCH_COUNT
+    }
+    if not established_flags:
+        return []
+
+    for each_test in test_functions:
+        if not _name_encodes_scenario(each_test.name):
+            continue
+        unpatched_flags = established_flags - flags_patched_by_test[each_test.name]
+        if unpatched_flags:
+            flag_list = ", ".join(sorted(unpatched_flags))
+            print(
+                f"ADVISORY [CODE_RULES] Line {each_test.lineno}: scenario test"
+                f" {each_test.name!r} never patches {flag_list}, which sibling tests"
+                f" establish — the named scenario may run under the flag default."
+                f" Patch the flag (and assert the gated path runs) or rename the test.",
+                file=sys.stderr,
+            )
+
+    return []

package/hooks/blocking/open_questions_in_plans_blocker.py

@@ -1,7 +1,8 @@
 #!/usr/bin/env python3
 """PreToolUse:Write|Edit|MultiEdit hook — blocks plan files that contain an "Open Questions" section.
 
-Plans under `~/.claude/plans/` (or any `.claude/plans/` directory) must not be
+Plans under `~/.claude/plans/` (or any `.claude/plans/` directory) and packet
+docs under any repo-local `docs/plans/` directory must not be
 written with an unresolved "Open Questions" section. When detected, the agent is
 forced to (1) investigate the codebase for answers itself first, then (2) confirm
 its interpretations via the AskUserQuestion tool in plain everyday language, and
@@ -20,6 +21,8 @@ if _hooks_dir not in sys.path:
 
 from hooks_constants.open_questions_in_plans_blocker_constants import (  # noqa: E402
     CODE_FENCE_PATTERN,
+    DOCS_PLANS_PATH_PREFIX,
+    DOCS_PLANS_PATH_SEGMENT,
     INLINE_CODE_PATTERN,
     MARKDOWN_EXTENSION,
     OPEN_QUESTIONS_HEADING_PATTERN,
@@ -41,6 +44,10 @@ def _is_inside_plans_directory(file_path: str) -> bool:
         return True
     if normalized.startswith(PLANS_PATH_PREFIX):
         return True
+    if DOCS_PLANS_PATH_SEGMENT in normalized:
+        return True
+    if normalized.startswith(DOCS_PLANS_PATH_PREFIX):
+        return True
     return False
 
 

package/hooks/blocking/test_code_rules_enforcer_dead_module_constant.py

@@ -39,8 +39,13 @@ def neutral_root() -> Iterator[Path]:
     own ``tmp_path`` directory name embeds the test name, which would make every
     synthetic constants path look like a test file. A neutral ``mkdtemp`` root
     mirrors how a production constants module path looks.
+
+    A ``.git`` marker is planted at the root so the cross-tree widening resolves
+    the repository root to this synthetic tree, never an enclosing real
+    checkout, keeping every test bounded and deterministic.
     """
     neutral_directory = Path(tempfile.mkdtemp(prefix="deadconst-")).resolve()
+    (neutral_directory / ".git").mkdir()
     try:
         yield neutral_directory
     finally:
@@ -186,3 +191,86 @@ def test_is_skipped_on_a_constants_test_file(neutral_root: Path) -> None:
     test_constants_path.write_text(body, encoding="utf-8")
     issues = _check(body, str(test_constants_path))
     assert issues == [], f"Test files are exempt, got: {issues}"
+
+
+def _build_cross_tree_repository(
+    repository_root: Path,
+    constants_body: str,
+    sibling_consumer_body: str,
+) -> Path:
+    config_directory = repository_root / "shared" / "theme_db" / "config"
+    config_directory.mkdir(parents=True)
+    constants_path = config_directory / "constants.py"
+    constants_path.write_text(constants_body, encoding="utf-8")
+    sibling_directory = repository_root / "cdp"
+    sibling_directory.mkdir(parents=True)
+    (sibling_directory / "tally.py").write_text(sibling_consumer_body, encoding="utf-8")
+    return constants_path
+
+
+def test_does_not_flag_constant_used_only_in_a_sibling_tree(neutral_root: Path) -> None:
+    constants_body = 'CROSS_TREE_CONSTANT = "cross"\nLOCALLY_DEAD_CONSTANT = "dead"\n'
+    sibling_consumer_body = (
+        "from shared.theme_db.config.constants import CROSS_TREE_CONSTANT\n"
+        "\n"
+        "def tally() -> str:\n"
+        "    return CROSS_TREE_CONSTANT\n"
+    )
+    constants_path = _build_cross_tree_repository(
+        neutral_root, constants_body, sibling_consumer_body
+    )
+    issues = _check(constants_body, str(constants_path))
+    assert not any("CROSS_TREE_CONSTANT" in each_issue for each_issue in issues), (
+        f"A constant consumed by a sibling tree in the repository must not be flagged, got: {issues}"
+    )
+    assert any("LOCALLY_DEAD_CONSTANT" in each_issue for each_issue in issues), (
+        f"A constant referenced nowhere in the repository stays flagged, got: {issues}"
+    )
+
+
+def test_returns_empty_list_at_file_cap(
+    neutral_root: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setattr("code_rules_dead_module_constant.MAX_SCAN_ROOT_FILE_COUNT", 0)
+    constants_path = _build_constants_package(
+        neutral_root / "workflow",
+        CONSTANTS_BODY,
+        "def noop() -> None:\n    pass\n",
+    )
+    issues = _check(CONSTANTS_BODY, str(constants_path))
+    assert issues == [], f"File cap hit must return [] (cannot prove dead), got: {issues}"
+
+
+def test_widened_scan_reads_each_file_at_most_once(
+    neutral_root: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    constants_body = 'CROSS_TREE_CONSTANT = "cross"\nLOCALLY_DEAD_CONSTANT = "dead"\n'
+    sibling_consumer_body = (
+        "from shared.theme_db.config.constants import CROSS_TREE_CONSTANT\n"
+        "\n"
+        "def tally() -> str:\n"
+        "    return CROSS_TREE_CONSTANT\n"
+    )
+    constants_path = _build_cross_tree_repository(
+        neutral_root, constants_body, sibling_consumer_body
+    )
+    package_tree_neighbor = constants_path.parent.parent / "neighbor.py"
+    package_tree_neighbor.write_text(
+        "def neighbor() -> int:\n    return 1\n", encoding="utf-8"
+    )
+    read_counts: dict[str, int] = {}
+    original_read_text = Path.read_text
+
+    def counting_read_text(self: Path, *positional: object, **keyword: object) -> str:
+        normalized_key = os.path.normcase(str(self.resolve()))
+        read_counts[normalized_key] = read_counts.get(normalized_key, 0) + 1
+        return original_read_text(self, *positional, **keyword)  # type: ignore[arg-type]  # forwards args
+
+    monkeypatch.setattr(Path, "read_text", counting_read_text)
+    _check(constants_body, str(constants_path))
+    over_read_paths = {
+        each_path: each_count for each_path, each_count in read_counts.items() if each_count > 1
+    }
+    assert not over_read_paths, (
+        f"Widening must read each .py file at most once, got over-reads: {over_read_paths}"
+    )