claude-dev-env 1.65.0 → 1.65.1

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/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}"
+    )

package/hooks/hooks_constants/dead_module_constant_constants.py

@@ -10,6 +10,7 @@ DUNDER_INIT_FILENAME: str = "__init__.py"
 CONSTANTS_MODULE_SUFFIX: str = "_constants.py"
 CONFIG_DIRECTORY_SEGMENT: str = "config"
 DUNDER_ALL_NAME: str = "__all__"
+GIT_DIRECTORY_NAME: str = ".git"
 MINIMUM_UPPER_SNAKE_LENGTH: int = 2
 MAX_DEAD_MODULE_CONSTANT_ISSUES: int = 25
 MAX_SCAN_ROOT_FILE_COUNT: int = 2000

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.65.0",
+    "version": "1.65.1",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/skills/autoconverge/workflow/converge.fix-recovery.test.mjs

@@ -96,7 +96,7 @@ test('FIX_SCHEMA requires blockedNeedingEdit and blockerDetail', () => {
 });
 
 test('FIX_RECOVERY_MAX_ATTEMPTS is declared and bounds the recovery loop at 2', () => {
-  assert.match(constantLine('FIX_RECOVERY_MAX_ATTEMPTS'), /=\s*2/);
+  assert.match(constantLine('FIX_RECOVERY_MAX_ATTEMPTS'), /=\s*2\s*$/);
 });
 
 for (const commitFunctionName of ['commitVerifiedFixes', 'commitRepairFixes']) {
@@ -154,6 +154,13 @@ test('commitWithRecovery bounds the loop, re-verifies, and retries the commit on
     editGuardIndex < verifyGateIndex,
     'expected the no-edit break to precede the re-verify gate',
   );
+  const recoverEditIndex = recoveryBody.search(/runRecoverEdit\(/);
+  const reverifyIndex = recoveryBody.search(/runVerify\(/);
+  const retryCommitIndex = recoveryBody.lastIndexOf('runCommit(');
+  assert.ok(
+    recoverEditIndex < reverifyIndex && reverifyIndex < retryCommitIndex,
+    'expected order recover-edit -> re-verify -> retry commit, so a verify/commit swap fails',
+  );
 });
 
 test('applyFixes routes its commit through commitWithRecovery wired to the fix-path steps', () => {

package/skills/autoconverge/workflow/converge.mjs

@@ -808,7 +808,7 @@ function recoverCommitBlockEdit(head, blockerDetail, sourceLabel, attempt) {
   )
 }
 
-const FIX_RECOVERY_MAX_ATTEMPTS = 4
+const FIX_RECOVERY_MAX_ATTEMPTS = 2
 
 /**
  * Run a commit step and, when it is blocked by a commit-time hook or gate that
@@ -858,6 +858,8 @@ async function applyFixes(head, findings, sourceLabel) {
       pushed: false,
       resolvedWithoutCommit: true,
       summary: editResult?.summary || 'fixes resolved without a code change',
+      blockedNeedingEdit: false,
+      blockerDetail: '',
     }
   }
   const verifyTranscript = await verifyFixesInWorkingTree(head, findings, sourceLabel)
@@ -867,6 +869,8 @@ async function applyFixes(head, findings, sourceLabel) {
       pushed: false,
       resolvedWithoutCommit: false,
       summary: `verify step did not pass the working-tree fixes for ${findings.length} finding(s) — not committing`,
+      blockedNeedingEdit: false,
+      blockerDetail: '',
     }
   }
   return commitWithRecovery({
@@ -1091,6 +1095,8 @@ async function repairConvergence(head, failures) {
       pushed: false,
       resolvedWithoutCommit: true,
       summary: editResult?.summary || 'convergence gates resolved without a code change or rebase',
+      blockedNeedingEdit: false,
+      blockerDetail: '',
     }
   }
   const verifyTranscript = await verifyRepairChanges(head, failures)
@@ -1100,6 +1106,8 @@ async function repairConvergence(head, failures) {
       pushed: false,
       resolvedWithoutCommit: false,
       summary: `repair verify step did not pass the working-tree repair on HEAD ${head} — not pushing`,
+      blockedNeedingEdit: false,
+      blockerDetail: '',
     }
   }
   const wasRebased = editResult?.rebased === true