claude-dev-env 1.42.0 → 1.44.0

package/hooks/validators/run_all_validators.py

@@ -293,14 +293,25 @@ def run_test_safety_checks(files: List[Path]) -> ValidatorResult:
 
 
 def get_project_root() -> Optional[Path]:
-    """Get project root by finding git root."""
-    result = subprocess.run(
-        ["git", "rev-parse", "--show-toplevel"],
+    """Get project root by finding git root.
+
+    Uses ``git -C <hooks_dir>`` to pin git's working tree to the hooks
+    directory without setting the subprocess cwd. On Windows, ``CreateProcess``
+    rejects some UNC working directories, so setting ``cwd=hooks_dir`` would
+    fail when ``hooks_dir`` resolves to a UNC path. The ``-C`` flag tells git
+    to operate as if started in that directory while the subprocess itself
+    inherits a normal cwd from the caller. Anchoring git to ``hooks_dir`` is
+    required so the lookup resolves to this repo even when the caller's cwd
+    points at an unrelated git checkout (e.g., the user's home), avoiding
+    validators that ``rglob`` over tens of thousands of unrelated files.
+    """
+    completed_git_lookup = subprocess.run(
+        ["git", "-C", str(hooks_dir), "rev-parse", "--show-toplevel"],
         capture_output=True,
         text=True,
     )
-    if result.returncode == 0:
-        return Path(result.stdout.strip())
+    if completed_git_lookup.returncode == 0:
+        return Path(completed_git_lookup.stdout.strip())
     return None
 
 

package/hooks/validators/test_output_formatter.py

@@ -14,6 +14,7 @@ from .output_formatter import (
     ViolationDict,
     ValidatorResultDict,
 )
+from . import run_all_validators
 from .run_all_validators import run_validators_entrypoint_subprocess
 
 
@@ -100,6 +101,51 @@ class TestJsonFlag:
         assert "results" in parsed
         assert isinstance(parsed["results"], list)
 
+    def test_get_project_root_anchored_under_unrelated_cwd(
+        self, tmp_path, monkeypatch
+    ) -> None:
+        """``get_project_root`` anchors git to the hooks tree, not the caller cwd.
+
+        Regression for the defect where ``get_project_root`` ran
+        ``git rev-parse --show-toplevel`` without anchoring to the hooks
+        directory; under a subprocess fallback cwd outside this repo, git
+        returned an unrelated checkout and the File Structure validator
+        rglob'd tens of thousands of unrelated files. This test calls the
+        helper in-process from a non-git ``tmp_path`` to directly exercise
+        the anchoring behavior provided by ``git -C <hooks_dir>``.
+        """
+        monkeypatch.chdir(tmp_path)
+        resolved_project_root = run_all_validators.get_project_root()
+
+        assert resolved_project_root is not None
+        assert resolved_project_root != tmp_path
+        hooks_directory_resolved = run_all_validators.hooks_dir.resolve()
+        assert hooks_directory_resolved.is_relative_to(resolved_project_root.resolve())
+
+    def test_file_structure_validator_output_is_bounded(self) -> None:
+        """File Structure validator output stays under 10 kB end-to-end.
+
+        Smoke check that the validators entrypoint subprocess returns
+        bounded File Structure output (<10 kB). The unrelated-cwd
+        anchoring behavior itself is exercised in-process by
+        ``test_get_project_root_anchored_under_unrelated_cwd``; this
+        subprocess test verifies the integrated entrypoint stays within
+        a bounded output budget. ``run_validators_entrypoint_subprocess``
+        sets its own ``cwd`` via
+        ``_hooks_subprocess_working_directory_and_environment``, so the
+        subprocess cwd is fixed regardless of the test runner's cwd.
+        """
+        completed_validation_run = run_validators_entrypoint_subprocess(["--json"])
+
+        parsed = json.loads(completed_validation_run.stdout.strip())
+        file_structure_results = [
+            each_validator_result
+            for each_validator_result in parsed["results"]
+            if each_validator_result["name"] == "File Structure"
+        ]
+        assert len(file_structure_results) == 1
+        assert len(file_structure_results[0]["output"]) < 10000
+
 
 class TestGroupViolationsByFile:
     def test_groups_violations_by_file_path(self) -> None:

package/hooks/workflow/doc_gist_auto_publish.py

@@ -32,7 +32,7 @@ _hooks_directory = str(Path(__file__).resolve().parent.parent)
 if _hooks_directory not in sys.path:
     sys.path.insert(0, _hooks_directory)
 
-from config.doc_gist_auto_publish_constants import (  # noqa: E402
+from hooks_constants.doc_gist_auto_publish_constants import (  # noqa: E402
     ALL_TARGET_TOOL_NAMES,
     HOOK_SUBPROCESS_TIMEOUT_SECONDS,
     HTML_FILE_EXTENSION,

package/hooks/workflow/md_to_html_companion.py

@@ -18,11 +18,15 @@ from urllib.parse import urlparse
 
 logging.basicConfig(stream=sys.stderr, level=logging.WARNING, format="%(message)s")
 
-_hook_dir = str(Path(__file__).absolute().parent.parent)
+_hook_dir = str(Path(__file__).resolve().parent.parent)
 if _hook_dir not in sys.path:
     sys.path.insert(0, _hook_dir)
 
-from config.html_companion_constants import (  # noqa: E402
+_blocking_dir = str(Path(__file__).resolve().parent.parent / "blocking")
+if _blocking_dir not in sys.path:
+    sys.path.insert(0, _blocking_dir)
+
+from hooks_constants.html_companion_constants import (  # noqa: E402
     BLOCKED_URL_SCHEMES,
     CSS_ACCENT_COLOR,
     CSS_BG_COLOR,
@@ -41,18 +45,7 @@ from config.html_companion_constants import (  # noqa: E402
     CSS_TABLE_WIDTH,
     CSS_TH_WEIGHT,
 )
-
-
-def _is_exempt_path(file_path: str) -> bool:
-    normalized = file_path.replace("\\", "/")
-    if "/.claude/" in normalized or normalized.startswith(".claude/"):
-        return True
-    if normalized.startswith("./"):
-        normalized = normalized[2:]
-    stripped = normalized.lstrip("/")
-    if "/" not in stripped:
-        return stripped.lower() in ("readme.md", "changelog.md")
-    return False
+from md_path_exemptions import is_exempt_path  # noqa: E402
 
 
 def _md_to_html(markdown_text: str) -> str:
@@ -330,7 +323,7 @@ def main() -> None:
     if not file_path or not file_path.lower().endswith(".md"):
         sys.exit(0)
 
-    if _is_exempt_path(file_path):
+    if is_exempt_path(file_path):
         sys.exit(0)
 
     if not os.path.exists(file_path):

package/hooks/workflow/test_md_to_html_companion.py

@@ -3,18 +3,73 @@
 This test suite validates that the md-to-html companion hook correctly
 generates HTML from markdown input, handles edge cases, and produces
 valid HTML output.
+
+Sandbox parent is created lazily by a session-scoped fixture rather than at
+module import time, so test collection has no side effect on the filesystem.
+The sandbox is rooted in a per-session unique directory created via
+`tempfile.mkdtemp` so the OS-temp exemption (which the companion shares with
+the blocker) does not silently skip the hook during tests.
 """
 
+import functools
 import json
 import os
+import shutil
+import stat
 import subprocess
 import sys
 import tempfile
+from pathlib import Path
+
+import pytest
 
 
 HOOK_SCRIPT_PATH = os.path.join(os.path.dirname(__file__), "md_to_html_companion.py")
 
 
+def _strip_read_only_and_retry(removal_function, target_path, *_exc_info):
+    try:
+        os.chmod(target_path, stat.S_IWRITE)
+        removal_function(target_path)
+    except OSError:
+        pass
+
+
+def _force_rmtree(target_path: str) -> None:
+    handler_kw = (
+        {"onexc": _strip_read_only_and_retry}
+        if sys.version_info >= (3, 12)
+        else {"onerror": _strip_read_only_and_retry}
+    )
+    try:
+        shutil.rmtree(target_path, **handler_kw)
+    except OSError:
+        pass
+
+
+@functools.lru_cache(maxsize=1)
+def _get_sandbox_parent_directory() -> str:
+    return tempfile.mkdtemp(prefix="pytest_md_companion_", dir=str(Path.home()))
+
+
+@pytest.fixture(scope="session", autouse=True)
+def _cleanup_sandbox_parent_directory():
+    yield
+    if _get_sandbox_parent_directory.cache_info().currsize:
+        _force_rmtree(_get_sandbox_parent_directory())
+        _get_sandbox_parent_directory.cache_clear()
+
+
+def _make_sandbox() -> tempfile.TemporaryDirectory:
+    """Return a TemporaryDirectory rooted outside the OS temp directory.
+
+    The companion exempts the OS temp directory (mirroring the blocker), so
+    the default `tempfile.TemporaryDirectory()` would prevent the test hook
+    invocation generating any HTML sidecar at all.
+    """
+    return tempfile.TemporaryDirectory(dir=_get_sandbox_parent_directory())
+
+
 class _RunHook:
     def __call__(self, tool_name: str, tool_input: dict) -> subprocess.CompletedProcess:
         payload = json.dumps({"tool_name": tool_name, "tool_input": tool_input})
@@ -31,7 +86,7 @@ _run_hook = _RunHook()
 
 
 def test_generates_html_companion():
-    with tempfile.TemporaryDirectory() as tmp:
+    with _make_sandbox() as tmp:
         md_path = os.path.join(tmp, "guide.md")
         html_path = os.path.join(tmp, "guide.html")
 
@@ -47,7 +102,7 @@ def test_generates_html_companion():
 
 
 def test_html_contains_heading():
-    with tempfile.TemporaryDirectory() as tmp:
+    with _make_sandbox() as tmp:
         md_path = os.path.join(tmp, "guide.md")
         with open(md_path, "w", encoding="utf-8") as f:
             f.write("# Hello World")
@@ -61,7 +116,7 @@ def test_html_contains_heading():
 
 
 def test_html_wraps_in_template():
-    with tempfile.TemporaryDirectory() as tmp:
+    with _make_sandbox() as tmp:
         md_path = os.path.join(tmp, "guide.md")
         with open(md_path, "w", encoding="utf-8") as f:
             f.write("plain text")
@@ -75,7 +130,7 @@ def test_html_wraps_in_template():
 
 
 def test_skips_non_md_files():
-    with tempfile.TemporaryDirectory() as tmp:
+    with _make_sandbox() as tmp:
         py_path = os.path.join(tmp, "main.py")
         html_path = os.path.join(tmp, "main.html")
 
@@ -89,7 +144,7 @@ def test_skips_non_md_files():
 
 
 def test_skips_claude_dir():
-    with tempfile.TemporaryDirectory() as tmp:
+    with _make_sandbox() as tmp:
         claude_dir = os.path.join(tmp, ".claude")
         md_path = os.path.join(claude_dir, "CLAUDE.md")
         html_path = os.path.join(claude_dir, "CLAUDE.html")
@@ -124,7 +179,7 @@ def test_nonexistent_md_passes():
 
 
 def test_converts_code_fence():
-    with tempfile.TemporaryDirectory() as tmp:
+    with _make_sandbox() as tmp:
         md_path = os.path.join(tmp, "guide.md")
         with open(md_path, "w", encoding="utf-8") as f:
             f.write("```python\nprint('hi')\n```")
@@ -141,7 +196,7 @@ def test_converts_code_fence():
 
 
 def test_converts_bold():
-    with tempfile.TemporaryDirectory() as tmp:
+    with _make_sandbox() as tmp:
         md_path = os.path.join(tmp, "guide.md")
         with open(md_path, "w", encoding="utf-8") as f:
             f.write("This is **bold** text.")
@@ -154,7 +209,7 @@ def test_converts_bold():
 
 
 def test_escapes_html_special_chars():
-    with tempfile.TemporaryDirectory() as tmp:
+    with _make_sandbox() as tmp:
         md_path = os.path.join(tmp, "guide.md")
         with open(md_path, "w", encoding="utf-8") as f:
             f.write("Use <div> for layout & choose \"text\" for quotes.")
@@ -175,7 +230,7 @@ def test_escapes_html_special_chars():
 
 
 def test_escapes_code_block_content():
-    with tempfile.TemporaryDirectory() as tmp:
+    with _make_sandbox() as tmp:
         md_path = os.path.join(tmp, "guide.md")
         with open(md_path, "w", encoding="utf-8") as f:
             f.write("```\nif x < 5 and y > 3:\n    print('hello')\n```")
@@ -195,7 +250,7 @@ def test_escapes_code_block_content():
 
 
 def test_lists_are_wrapped_in_ul():
-    with tempfile.TemporaryDirectory() as tmp:
+    with _make_sandbox() as tmp:
         md_path = os.path.join(tmp, "guide.md")
         with open(md_path, "w", encoding="utf-8") as f:
             f.write("- item one\n- item two\n- item three")
@@ -217,7 +272,7 @@ def test_lists_are_wrapped_in_ul():
 
 
 def test_ordered_lists_are_wrapped_in_ol():
-    with tempfile.TemporaryDirectory() as tmp:
+    with _make_sandbox() as tmp:
         md_path = os.path.join(tmp, "guide.md")
         with open(md_path, "w", encoding="utf-8") as f:
             f.write("1. first\n2. second")
@@ -234,7 +289,7 @@ def test_ordered_lists_are_wrapped_in_ol():
 
 
 def test_handles_curly_braces_in_body():
-    with tempfile.TemporaryDirectory() as tmp:
+    with _make_sandbox() as tmp:
         md_path = os.path.join(tmp, "guide.md")
         with open(md_path, "w", encoding="utf-8") as f:
             f.write("# JS Example\n\nUse `{ foo: 1 }` in code.")
@@ -255,7 +310,7 @@ def test_handles_curly_braces_in_body():
 
 
 def test_escapes_title_in_html_output():
-    with tempfile.TemporaryDirectory() as tmp:
+    with _make_sandbox() as tmp:
         md_path = os.path.join(tmp, "guide.md")
         with open(md_path, "w", encoding="utf-8") as f:
             f.write("# Hackers <3 Markdown & <scripts>")
@@ -275,7 +330,8 @@ def test_escapes_title_in_html_output():
 
 
 def test_skips_root_readme():
-    with tempfile.TemporaryDirectory() as tmp:
+    with _make_sandbox() as tmp:
+        Path(tmp, ".git").touch()
         original_cwd = os.getcwd()
         try:
             os.chdir(tmp)
@@ -293,7 +349,8 @@ def test_skips_root_readme():
 
 
 def test_skips_root_changelog():
-    with tempfile.TemporaryDirectory() as tmp:
+    with _make_sandbox() as tmp:
+        Path(tmp, ".git").touch()
         original_cwd = os.getcwd()
         try:
             os.chdir(tmp)
@@ -311,7 +368,7 @@ def test_skips_root_changelog():
 
 
 def test_language_class_valid():
-    with tempfile.TemporaryDirectory() as tmp:
+    with _make_sandbox() as tmp:
         md_path = os.path.join(tmp, "guide.md")
         with open(md_path, "w", encoding="utf-8") as f:
             f.write("```python\nx = 1\n```")
@@ -324,7 +381,7 @@ def test_language_class_valid():
 
 
 def test_language_class_skips_invalid():
-    with tempfile.TemporaryDirectory() as tmp:
+    with _make_sandbox() as tmp:
         md_path = os.path.join(tmp, "guide.md")
         with open(md_path, "w", encoding="utf-8") as f:
             f.write("```my lang\nx = 1\n```")
@@ -338,7 +395,7 @@ def test_language_class_skips_invalid():
 
 
 def test_language_class_allows_valid_chars():
-    with tempfile.TemporaryDirectory() as tmp:
+    with _make_sandbox() as tmp:
         md_path = os.path.join(tmp, "guide.md")
         with open(md_path, "w", encoding="utf-8") as f:
             f.write("```c++\nint x = 1;\n```")
@@ -351,7 +408,7 @@ def test_language_class_allows_valid_chars():
 
 
 def test_link_text_asterisks_remain_literal():
-    with tempfile.TemporaryDirectory() as tmp:
+    with _make_sandbox() as tmp:
         md_path = os.path.join(tmp, "guide.md")
         with open(md_path, "w", encoding="utf-8") as f:
             f.write("See [text *not italic*](url).")
@@ -368,7 +425,7 @@ def test_link_text_asterisks_remain_literal():
 
 
 def test_handles_parentheses_in_links():
-    with tempfile.TemporaryDirectory() as tmp:
+    with _make_sandbox() as tmp:
         md_path = os.path.join(tmp, "guide.md")
         with open(md_path, "w", encoding="utf-8") as f:
             f.write(
@@ -394,7 +451,7 @@ def test_handles_parentheses_in_links():
 
 
 def test_does_not_skip_nested_readme():
-    with tempfile.TemporaryDirectory() as tmp:
+    with _make_sandbox() as tmp:
         nested_dir = os.path.join(tmp, "docs")
         os.makedirs(nested_dir)
         md_path = os.path.join(nested_dir, "README.md")
@@ -412,7 +469,7 @@ def test_does_not_skip_nested_readme():
 
 
 def test_inline_code_preserves_asterisks():
-    with tempfile.TemporaryDirectory() as tmp:
+    with _make_sandbox() as tmp:
         md_path = os.path.join(tmp, "guide.md")
         with open(md_path, "w", encoding="utf-8") as f:
             f.write("Type `**bold**` in a docstring.")
@@ -432,7 +489,7 @@ def test_inline_code_preserves_asterisks():
 
 
 def test_blocks_javascript_url_scheme():
-    with tempfile.TemporaryDirectory() as tmp:
+    with _make_sandbox() as tmp:
         md_path = os.path.join(tmp, "guide.md")
         with open(md_path, "w", encoding="utf-8") as f:
             f.write("[click me](javascript:alert(1))")
@@ -450,3 +507,107 @@ def test_blocks_javascript_url_scheme():
         assert "javascript:" not in html
         assert "click me" in html
         assert "<a" not in html
+
+
+def test_companion_skips_home_session_log_directory(tmp_path, monkeypatch):
+    synthetic_home_directory = tmp_path / "synthetic_home"
+    synthetic_home_directory.mkdir()
+    monkeypatch.setenv("HOME", str(synthetic_home_directory))
+    monkeypatch.setenv("USERPROFILE", str(synthetic_home_directory))
+    session_log_directory = synthetic_home_directory / "SessionLog" / "decisions"
+    session_log_directory.mkdir(parents=True)
+    md_path = str(session_log_directory / "companion_exempt_test.md")
+    html_path = str(session_log_directory / "companion_exempt_test.html")
+    with open(md_path, "w", encoding="utf-8") as f:
+        f.write("# Note")
+    result = _run_hook(
+        "Write",
+        {"file_path": md_path, "content": "# Note"},
+    )
+    assert result.returncode == 0
+    assert not os.path.exists(html_path)
+
+
+def test_companion_skips_skill_md_anywhere():
+    with _make_sandbox() as tmp:
+        nested_directory = os.path.join(tmp, "packages", "dev-env", "skills", "foo")
+        os.makedirs(nested_directory, exist_ok=True)
+        md_path = os.path.join(nested_directory, "SKILL.md")
+        html_path = os.path.join(nested_directory, "SKILL.html")
+        with open(md_path, "w", encoding="utf-8") as f:
+            f.write("# Skill")
+        result = _run_hook(
+            "Write",
+            {"file_path": md_path, "content": "# Skill"},
+        )
+        assert result.returncode == 0
+        assert not os.path.exists(html_path)
+
+
+def test_companion_skips_agents_directory_anywhere():
+    with _make_sandbox() as tmp:
+        agents_directory = os.path.join(tmp, "packages", "dev-env", "agents")
+        os.makedirs(agents_directory, exist_ok=True)
+        md_path = os.path.join(agents_directory, "pr-description-writer.md")
+        html_path = os.path.join(
+            agents_directory, "pr-description-writer.html"
+        )
+        with open(md_path, "w", encoding="utf-8") as f:
+            f.write("# Agent")
+        result = _run_hook(
+            "Write",
+            {"file_path": md_path, "content": "# Agent"},
+        )
+        assert result.returncode == 0
+        assert not os.path.exists(html_path)
+
+
+def test_companion_skips_claude_plugin_directory():
+    with _make_sandbox() as tmp:
+        plugin_directory = os.path.join(tmp, ".claude-plugin")
+        os.makedirs(plugin_directory, exist_ok=True)
+        md_path = os.path.join(plugin_directory, "manifest.md")
+        html_path = os.path.join(plugin_directory, "manifest.html")
+        with open(md_path, "w", encoding="utf-8") as f:
+            f.write("# Manifest")
+        result = _run_hook(
+            "Write",
+            {"file_path": md_path, "content": "# Manifest"},
+        )
+        assert result.returncode == 0
+        assert not os.path.exists(html_path)
+
+
+def test_companion_still_fires_for_ordinary_docs_md_file():
+    with _make_sandbox() as tmp:
+        docs_directory = os.path.join(tmp, "docs")
+        os.makedirs(docs_directory, exist_ok=True)
+        md_path = os.path.join(docs_directory, "regular.md")
+        html_path = os.path.join(docs_directory, "regular.html")
+        with open(md_path, "w", encoding="utf-8") as f:
+            f.write("# Regular")
+        result = _run_hook(
+            "Write",
+            {"file_path": md_path, "content": "# Regular"},
+        )
+        assert result.returncode == 0
+        assert os.path.exists(html_path)
+
+
+def test_companion_skips_system_temp_directory():
+    temp_directory = tempfile.gettempdir()
+    md_path = os.path.join(temp_directory, "companion_temp_exempt_test.md")
+    html_path = os.path.join(temp_directory, "companion_temp_exempt_test.html")
+    try:
+        with open(md_path, "w", encoding="utf-8") as f:
+            f.write("# Scratch")
+        result = _run_hook(
+            "Write",
+            {"file_path": md_path, "content": "# Scratch"},
+        )
+        assert result.returncode == 0
+        assert not os.path.exists(html_path)
+    finally:
+        for each_path in (md_path, html_path):
+            if os.path.exists(each_path):
+                os.remove(each_path)

package/package.json

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

package/rules/ask-user-question-required.md

@@ -40,5 +40,5 @@ When a question is genuinely for the user, call the tool with:
 
 - Hook: `packages/claude-dev-env/hooks/blocking/question_to_user_enforcer.py`, registered on the `Stop` matcher in `packages/claude-dev-env/hooks/hooks.json`.
 - Loop prevention: the hook honors Claude Code's `stop_hook_active` flag and does not re-block on retry.
-- User-facing notice: `USER_FACING_ASKUSERQUESTION_NOTICE` in `packages/claude-dev-env/hooks/config/messages.py`.
+- User-facing notice: `USER_FACING_ASKUSERQUESTION_NOTICE` in `packages/claude-dev-env/hooks/hooks_constants/messages.py`.
 - Related rule: `packages/claude-dev-env/rules/verify-before-asking.md` gates whether the question belongs to the user in the first place.

package/rules/vault-context.md

@@ -10,7 +10,7 @@ An Obsidian vault stores session reports, decisions, and research documents acro
 
 ## Vault Structure
 
-- `sessions/` -- session reports with frontmatter: `type: session-report`, `project`, `session`, `date`, `status`, `blocked`, `tags`
+- `sessions/` -- session reports with frontmatter: `type: session-report`, `project`, `session`, `date`, `status`, `blocked`, `vault_context_retrieved`, `tags`
 - `decisions/` -- decision notes with frontmatter: `type: decision|procedural|fact|gotcha`, `project`, `date`, `status: Active|Superseded`, `tags`
 - `Research/` -- deep research documents
 

package/scripts/{config → dev_env_scripts_constants}/timing.py

@@ -1,7 +1,7 @@
 """Timing constants for sweep_empty_dirs.
 
 Per the project's configuration conventions, timeouts, delays, and retries
-live in config/timing.py.
+live in dev_env_scripts_constants/timing.py.
 """
 
 DEFAULT_AGE_SECONDS: int = 120

package/scripts/setup_project_paths.py

@@ -18,17 +18,12 @@ import subprocess
 import sys
 from pathlib import Path
 
-_hooks_dir_string = str(Path(__file__).resolve().parent.parent / "hooks")
-while _hooks_dir_string in sys.path:
-    sys.path.remove(_hooks_dir_string)
-sys.path.insert(0, _hooks_dir_string)
+_hooks_dir = str(Path(__file__).resolve().parent.parent / "hooks")
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
 
-for _cached_module_name in list(sys.modules):
-    if _cached_module_name == "config" or _cached_module_name.startswith("config."):
-        del sys.modules[_cached_module_name]
-
-from config.project_paths_reader import registry_file_path
-from config.setup_project_paths_constants import (
+from hooks_constants.project_paths_reader import registry_file_path  # noqa: E402
+from hooks_constants.setup_project_paths_constants import (  # noqa: E402
     ABORTED_NOTHING_WRITTEN_MESSAGE,
     CONFIRMATION_PROMPT_TEXT,
     ES_EXE_BINARY_NAME,
@@ -85,6 +80,13 @@ def filter_to_git_roots(all_es_exe_paths: list[str]) -> list[str]:
 
     Rejects siblings like ``.gitignore``, ``.github``, ``.gitattributes`` that
     share the ``.git`` prefix but are not the canonical git metadata directory.
+
+    Args:
+        all_es_exe_paths: Raw folder paths emitted by es.exe.
+
+    Returns:
+        Parent directory paths of every entry whose final segment is exactly
+        ``.git``.
     """
     all_repo_roots: list[str] = []
     for each_es_path in all_es_exe_paths:
@@ -102,6 +104,12 @@ def apply_exclusion_filter(all_candidate_paths: list[str]) -> list[str]:
     Whole-segment matching preserves legitimate names that merely contain an
     excluded substring (for example ``template`` is retained even though
     ``temp`` is excluded).
+
+    Args:
+        all_candidate_paths: Repo-root paths discovered by es.exe.
+
+    Returns:
+        Subset of *all_candidate_paths* with no segment in the exclusion set.
     """
     all_retained_paths: list[str] = []
     for each_candidate_path in all_candidate_paths:
@@ -134,6 +142,13 @@ def merge_registries(
     Pre-existing entries not in the new set are preserved. On name collisions
     the newly discovered entry wins. The ``_meta.last_scan`` timestamp is
     refreshed to the current UTC time.
+
+    Args:
+        existing_registry: Existing on-disk registry contents.
+        new_path_by_name: Newly discovered name-to-path entries.
+
+    Returns:
+        Merged registry with refreshed ``_meta.last_scan`` timestamp.
     """
     merged_registry: dict = {
         each_key: each_value
@@ -191,6 +206,11 @@ def write_registry_atomically(registry_to_write: dict, target_file: Path) -> Non
     Caller is responsible for reading the existing registry, verifying the
     schema version, and merging before calling this function. This function
     performs no file reads and no schema checks.
+
+    Args:
+        registry_to_write: Registry content to serialize.
+        target_file: Final destination path; the temp sibling is created
+            adjacent and renamed over the destination.
     """
     target_file.parent.mkdir(parents=True, exist_ok=True)
     temp_suffix = ".tmp"
@@ -228,7 +248,11 @@ def _run_es_exe_folders_query() -> list[str]:
 
 
 def discover_repo_roots_via_everything() -> list[str]:
-    """Run es.exe, filter to genuine git roots, deduplicate, and sort."""
+    """Run es.exe, filter to genuine git roots, deduplicate, and sort.
+
+    Returns:
+        Deduplicated, sorted list of repo-root paths discovered by es.exe.
+    """
     all_raw_paths = _run_es_exe_folders_query()
     all_git_roots = filter_to_git_roots(all_raw_paths)
     all_included = apply_exclusion_filter(all_git_roots)
@@ -291,6 +315,11 @@ def prompt_and_write(
 
     Reads and validates the existing registry BEFORE prompting so the user
     learns of any schema or read error early. Declining writes nothing.
+
+    Args:
+        path_by_name: Proposed name-to-path mapping to present to the user.
+        save_path: Registry destination path used for the schema check
+            and atomic write target.
     """
     existing_registry = _load_and_validate_registry(save_path)
     _display_proposed_mapping(path_by_name, save_path)
@@ -319,6 +348,15 @@ def _build_path_by_name_from_roots(all_repo_roots: list[str]) -> dict[str, str]:
 
 
 def main() -> int:
+    """Run the discovery, prompt, and atomic-write flow for the registry.
+
+    Returns:
+        ``0`` on success or when no candidate repositories were found.
+
+    Raises:
+        SystemExit: When es.exe scan fails or the existing registry is
+            malformed.
+    """
     if not _everything_binary_is_available():
         print(
             f"ERROR: {ES_EXE_BINARY_NAME} not found on PATH. Install Everything "