claude-dev-env 1.58.0 → 1.59.0

package/CLAUDE.md

@@ -45,8 +45,8 @@ Reserve `Read`/`Grep`/`Glob` for files you will actually touch this turn. Compos
 
 Run every multi-step code task in two phases:
 
-1. **Coders** — one Sonnet agent per scoped assignment writes the code. A coder that hits a decision it can't reasonably solve consults the tool-less `fable-advisor` agent — which returns a plan, a correction, or a stop signal — and resumes. Source: Anthropic's advisor strategy (https://claude.com/blog/the-advisor-strategy).
-2. **Verification** — when the coders finish, the main session spawns the `fable-verifier` agent in a fresh context. It derives and runs the checks itself rather than trusting coder reports: the task's named gates, tests against baselines recorded before the coders ran, and a two-way diff-vs-assignment reading (every task item maps to a hunk, every hunk maps to a task item, nothing missing). A finding must cite a failing command or a named task item. Source: the fresh-context review step in Claude Code best practices (https://code.claude.com/docs/en/best-practices) — the agent doing the work isn't the one grading it.
+1. **Coders** — one coder agent per scoped assignment writes the code. A coder that hits a decision it can't reasonably solve consults the tool-less `code-advisor` agent — which returns a plan, a correction, or a stop signal — and resumes. Source: Anthropic's advisor strategy (https://claude.com/blog/the-advisor-strategy).
+2. **Verification** — when the coders finish, the main session spawns the `code-verifier` agent in a fresh context. It derives and runs the checks itself rather than trusting coder reports: the task's named gates, tests against baselines recorded before the coders ran, and a two-way diff-vs-assignment reading (every task item maps to a hunk, every hunk maps to a task item, nothing missing). A finding must cite a failing command or a named task item. Source: the fresh-context review step in Claude Code best practices (https://code.claude.com/docs/en/best-practices) — the agent doing the work isn't the one grading it.
 
 Repair agents run only on reported findings; the verifier re-checks after each repair. Work lands (commit, push, draft PR) only on a clean verdict — enforced by the `verified_commit_gate` hook, which blocks `git commit`/`git push` unless a hook-minted verdict covers the current branch diff. The one exemption is mechanical, not discretionary: a diff whose every changed file is non-code or has an unchanged Python AST once docstrings are stripped (docs, docstrings, comments).
 

package/_shared/pr-loop/scripts/code_rules_gate.py

@@ -22,6 +22,9 @@ from pr_loop_shared_constants.code_rules_gate_constants import (  # noqa: E402
     BANNED_NOUN_DEFINITION_LINE_GROUP_INDEX,
     BANNED_NOUN_SPAN_GROUP_INDEX,
     BANNED_NOUN_VIOLATION_PATTERN,
+    DUPLICATE_BODY_DEFINITION_LINE_GROUP_INDEX,
+    DUPLICATE_BODY_SPAN_GROUP_INDEX,
+    DUPLICATE_BODY_VIOLATION_PATTERN,
     FUNCTION_LENGTH_DEFINITION_LINE_GROUP_INDEX,
     FUNCTION_LENGTH_SPAN_GROUP_INDEX,
     FUNCTION_LENGTH_VIOLATION_PATTERN,
@@ -1006,11 +1009,39 @@ def banned_noun_span_range(violation_text: str) -> range | None:
     return range(definition_line, definition_line + line_span)
 
 
+def duplicate_body_span_range(violation_text: str) -> range | None:
+    """Return the copied function's source line range of a duplicate-body issue.
+
+    The duplicate-body message carries the copied function's definition line and
+    its full body span: ``Function 'NAME' duplicates location.py::name — ...
+    (duplicate body span at line X, spanning Y lines)``. The function occupies
+    lines ``X`` through ``X + Y - 1`` inclusive, so a duplicate of a sibling helper
+    is blocking only when the diff touches the copied function and advisory when an
+    unrelated edit leaves a pre-existing copy untouched — matching the span-scoped
+    PreToolUse Write/Edit behavior rather than blocking every duplicate-body
+    message unconditionally.
+
+    Args:
+        violation_text: A single violation string emitted by the enforcer.
+
+    Returns:
+        A ``range`` covering the copied function's declared line span, or None
+        when the text is not a duplicate-body violation.
+    """
+    span_match = DUPLICATE_BODY_VIOLATION_PATTERN.search(violation_text)
+    if span_match is None:
+        return None
+    definition_line = int(span_match.group(DUPLICATE_BODY_DEFINITION_LINE_GROUP_INDEX))
+    line_span = int(span_match.group(DUPLICATE_BODY_SPAN_GROUP_INDEX))
+    return range(definition_line, definition_line + line_span)
+
+
 def _all_span_range_extractors() -> tuple[Callable[[str], range | None], ...]:
     return (
         function_length_span_range,
         isolation_span_range,
         banned_noun_span_range,
+        duplicate_body_span_range,
     )
 
 
@@ -1052,9 +1083,10 @@ def split_violations_by_scope(
     Returns:
         Tuple ``(blocking, advisory)``. When *all_added_line_numbers* is
         None, every issue is blocking. Every diff-scoped violation
-        (function-length, HOME/TMP isolation, banned-noun) carries an
-        enclosing-unit span fragment that ``enclosing_span_range`` reconstructs
-        through one shared extractor registry; such a violation is blocking
+        (function-length, HOME/TMP isolation, banned-noun, duplicate-body)
+        carries an enclosing-unit span fragment that ``enclosing_span_range``
+        reconstructs through one shared extractor registry; such a violation is
+        blocking
         when its declared span intersects the added lines (the unit grew or its
         signature changed in this diff) and advisory otherwise (a pre-existing
         untouched unit). Every other issue is blocking when its ``Line N:``
@@ -1256,6 +1288,7 @@ def _scoped_violations_for_file(
         relative_posix,
         prior_content,
         defer_scope_to_caller=True,
+        sibling_directory=resolved_path.parent,
     )
     issues.extend(check_wrapper_plumb_through(content, relative_posix))
     if not issues:

package/_shared/pr-loop/scripts/pr_loop_shared_constants/code_rules_gate_constants.py

@@ -23,6 +23,12 @@ BANNED_NOUN_VIOLATION_PATTERN: re.Pattern[str] = re.compile(
 BANNED_NOUN_DEFINITION_LINE_GROUP_INDEX: int = 1
 BANNED_NOUN_SPAN_GROUP_INDEX: int = 2
 
+DUPLICATE_BODY_VIOLATION_PATTERN: re.Pattern[str] = re.compile(
+    r"\(duplicate body span at line (\d+), spanning (\d+) lines\)"
+)
+DUPLICATE_BODY_DEFINITION_LINE_GROUP_INDEX: int = 1
+DUPLICATE_BODY_SPAN_GROUP_INDEX: int = 2
+
 ALL_CODE_FILE_EXTENSIONS: frozenset[str] = frozenset(
     {".py", ".js", ".ts", ".tsx", ".jsx"}
 )

package/_shared/pr-loop/scripts/pr_loop_shared_constants/reviews_disabled_constants.py

@@ -6,4 +6,5 @@ CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME: str = "CLAUDE_REVIEWS_DISABLED"
 CLAUDE_REVIEWS_DISABLED_TOKEN_SEPARATOR: str = ","
 CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN: str = "bugteam"
 CLAUDE_REVIEWS_DISABLED_BUGBOT_TOKEN: str = "bugbot"
+CLAUDE_REVIEWS_DISABLED_COPILOT_TOKEN: str = "copilot"
 EXIT_CODE_BUGTEAM_DISABLED_VIA_ENV: int = 7

package/_shared/pr-loop/scripts/reviews_disabled.py

@@ -14,6 +14,7 @@ import sys
 from pr_loop_shared_constants.reviews_disabled_constants import (
     CLAUDE_REVIEWS_DISABLED_BUGBOT_TOKEN,
     CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN,
+    CLAUDE_REVIEWS_DISABLED_COPILOT_TOKEN,
     CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME,
     CLAUDE_REVIEWS_DISABLED_TOKEN_SEPARATOR,
     EXIT_CODE_BUGTEAM_DISABLED_VIA_ENV,
@@ -23,11 +24,13 @@ from pr_loop_shared_constants.reviews_disabled_constants import (
 __all__ = [
     "CLAUDE_REVIEWS_DISABLED_BUGBOT_TOKEN",
     "CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN",
+    "CLAUDE_REVIEWS_DISABLED_COPILOT_TOKEN",
     "CLAUDE_REVIEWS_DISABLED_ENV_VAR_NAME",
     "CLAUDE_REVIEWS_DISABLED_TOKEN_SEPARATOR",
     "EXIT_CODE_BUGTEAM_DISABLED_VIA_ENV",
     "is_bugbot_disabled_via_env",
     "is_bugteam_disabled_via_env",
+    "is_copilot_disabled_via_env",
     "main",
 ]
 
@@ -73,6 +76,15 @@ def is_bugbot_disabled_via_env() -> bool:
     return _is_reviewer_disabled_via_env(CLAUDE_REVIEWS_DISABLED_BUGBOT_TOKEN)
 
 
+def is_copilot_disabled_via_env() -> bool:
+    """Check whether CLAUDE_REVIEWS_DISABLED opts GitHub Copilot out.
+
+    Returns:
+        True when the env var lists the ``copilot`` token.
+    """
+    return _is_reviewer_disabled_via_env(CLAUDE_REVIEWS_DISABLED_COPILOT_TOKEN)
+
+
 def parse_arguments(all_argv: list[str]) -> argparse.Namespace:
     """Parse command-line arguments for the reviewer opt-out check.
 

package/_shared/pr-loop/scripts/tests/test_code_rules_gate.py

@@ -12,6 +12,7 @@ import inspect
 import subprocess
 import sys
 import unittest.mock
+from collections.abc import Callable
 from pathlib import Path
 from types import ModuleType
 
@@ -31,6 +32,22 @@ def _load_gate_module() -> ModuleType:
 gate_module = _load_gate_module()
 
 
+def _load_duplicate_body_check() -> Callable[..., list[str]]:
+    package_root = gate_module.resolve_claude_dev_env_root(
+        Path(gate_module.__file__).resolve()
+    )
+    module_path = package_root / "hooks" / "blocking" / "code_rules_duplicate_body.py"
+    spec = importlib.util.spec_from_file_location("code_rules_duplicate_body", module_path)
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module.check_duplicate_function_body_across_files
+
+
+check_duplicate_function_body_across_files = _load_duplicate_body_check()
+
+
 def run_git_in_repository(repository_root: Path, *arguments: str) -> str:
     completion = subprocess.run(
         ["git", *arguments],
@@ -560,6 +577,254 @@ def test_collect_partitioned_violations_counts_unreadable_sibling_as_skip(
     assert skipped_unreadable_count == 1
 
 
+_DUPLICATE_HELPER_SOURCE = (
+    "import re\n"
+    "\n"
+    "def strip_code_and_quotes(text: str) -> str:\n"
+    '    """Strip fences, inline code, and quoted lines from text.\n'
+    "\n"
+    "    Args:\n"
+    "        text: The raw text to clean.\n"
+    "\n"
+    "    Returns:\n"
+    "        The cleaned text.\n"
+    '    """\n'
+    "    without_fences = re.sub(r'```.*?```', '', text, flags=re.DOTALL)\n"
+    "    without_inline = re.sub(r'`[^`]*`', '', without_fences)\n"
+    "    without_quotes = re.sub(r'(?m)^>.*$', '', without_inline)\n"
+    "    return without_quotes.strip()\n"
+)
+
+
+def test_run_gate_flags_copied_sibling_when_cwd_is_outside_repo_root(
+    temporary_git_repository: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """The duplicate-body sibling scan must anchor to the repo, not process CWD.
+
+    The duplicate-body check reads sibling modules from disk to flag a copied
+    helper. When the gate runs with a working directory above the repository
+    root, resolving the sibling directory against the process CWD points at the
+    wrong place and the copied helper slips through. Driving the gate's per-file
+    validation from a parent directory with a nested byte-identical sibling
+    proves sibling resolution is anchored to the absolute file location rather
+    than the inherited CWD — the duplicate message must appear in the blocking
+    set.
+    """
+    package_directory = temporary_git_repository / "package"
+    package_directory.mkdir()
+    existing_file = package_directory / "existing_helper.py"
+    copied_file = package_directory / "copied_helper.py"
+    existing_file.write_text(_DUPLICATE_HELPER_SOURCE, encoding="utf-8")
+    copied_file.write_text(_DUPLICATE_HELPER_SOURCE, encoding="utf-8")
+    validate_content = gate_module.load_validate_content()
+
+    monkeypatch.chdir(temporary_git_repository.parent)
+    blocking_by_file, _advisory_by_file, _skipped = (
+        gate_module._collect_partitioned_violations(
+            validate_content,
+            [copied_file],
+            temporary_git_repository,
+            None,
+        )
+    )
+
+    all_blocking_messages = [
+        each_message
+        for each_file_messages in blocking_by_file.values()
+        for each_message in each_file_messages
+    ]
+    assert any(
+        "duplicates existing_helper.py" in each_message
+        for each_message in all_blocking_messages
+    ), (
+        "A copied sibling helper must be flagged even when the gate runs from a "
+        f"CWD above the repository root, got: {all_blocking_messages}"
+    )
+
+
+def _duplicate_body_issue_for_copied_sibling(base_directory: Path) -> str:
+    """Return the enforcer's duplicate-body message for a copied sibling helper.
+
+    Writes the shared helper into a ``blocking`` subdirectory of *base_directory*
+    as an existing module, then validates a second module carrying the
+    byte-identical body with scope deferred to the caller, so the returned message
+    is exactly the one the commit/push gate re-scopes. The destination is passed as
+    a neutral relative path with the sibling directory supplied explicitly, because
+    any test marker anywhere in the path exempts the file from the duplicate scan
+    and a pytest temporary directory carries one. The single duplicate-body
+    violation is returned for span assertions.
+
+    Args:
+        base_directory: A directory under which the sibling module directory is
+            created.
+
+    Returns:
+        The duplicate-body violation string the enforcer emits for the copy.
+    """
+    sibling_directory = base_directory / "blocking"
+    sibling_directory.mkdir()
+    (sibling_directory / "existing_helper.py").write_text(
+        _DUPLICATE_HELPER_SOURCE, encoding="utf-8"
+    )
+    duplicate_body_issues = check_duplicate_function_body_across_files(
+        _DUPLICATE_HELPER_SOURCE,
+        "blocking/copied_helper.py",
+        defer_scope_to_caller=True,
+        sibling_directory=sibling_directory,
+    )
+    matching_issues = [
+        each_issue
+        for each_issue in duplicate_body_issues
+        if "duplicates existing_helper.py" in each_issue
+    ]
+    assert matching_issues, f"expected a duplicate-body issue, got {duplicate_body_issues!r}"
+    return matching_issues[0]
+
+
+def test_duplicate_body_span_range_covers_the_definition_through_last_body_line(
+    tmp_path: Path,
+) -> None:
+    """The reconstructed span starts at the copied function's definition line and
+    covers its full body, so a changed-line set intersects the span only when the
+    edit touches the duplicated function — mirroring the enforcer's own span."""
+    duplicate_body_issue = _duplicate_body_issue_for_copied_sibling(tmp_path)
+    definition_line = 3
+    last_body_line = 15
+    span = gate_module.duplicate_body_span_range(duplicate_body_issue)
+    assert span == range(definition_line, last_body_line + 1)
+
+
+def test_split_violations_blocks_duplicate_body_when_span_intersects_added_lines(
+    tmp_path: Path,
+) -> None:
+    """A duplicate-body issue whose copied-function span overlaps the diff's added
+    lines is blocking — this commit introduced or touched the copy, exactly the
+    case the live Write/Edit hook flags."""
+    duplicate_body_issue = _duplicate_body_issue_for_copied_sibling(tmp_path)
+    inside_span_line = 4
+    blocking, advisory = gate_module.split_violations_by_scope(
+        [duplicate_body_issue],
+        all_added_line_numbers={inside_span_line},
+    )
+    assert blocking == [duplicate_body_issue]
+    assert advisory == []
+
+
+def test_split_violations_advises_duplicate_body_when_span_misses_added_lines(
+    tmp_path: Path,
+) -> None:
+    """A duplicate-body issue for an untouched pre-existing copy — whose span does
+    not overlap any added line — is advisory, not blocking. Editing an unrelated
+    region of a file that already carries a sibling-duplicate helper must not
+    block the commit gate, matching the span-scoped Write/Edit behavior."""
+    duplicate_body_issue = _duplicate_body_issue_for_copied_sibling(tmp_path)
+    line_far_outside_span = 5000
+    blocking, advisory = gate_module.split_violations_by_scope(
+        [duplicate_body_issue],
+        all_added_line_numbers={line_far_outside_span},
+    )
+    assert advisory == [duplicate_body_issue]
+    assert blocking == []
+
+
+def test_collect_partitioned_violations_advises_pre_existing_sibling_duplicate(
+    temporary_git_repository: Path,
+) -> None:
+    """A committed file already carrying a sibling-duplicate helper, edited only in
+    an unrelated region, yields the duplicate-body violation as advisory — never
+    blocking. Without a parseable span the gate forces every duplicate-body message
+    into the blocking payload, which would wedge a convergence loop the author
+    cannot clear by editing the touched lines.
+    """
+    package_directory = temporary_git_repository / "package"
+    package_directory.mkdir()
+    existing_file = package_directory / "existing_helper.py"
+    existing_file.write_text(_DUPLICATE_HELPER_SOURCE, encoding="utf-8")
+    copied_file = package_directory / "copied_helper.py"
+    copied_file.write_text(
+        _DUPLICATE_HELPER_SOURCE + "unrelated_constant = 1\n", encoding="utf-8"
+    )
+    unrelated_added_line = _DUPLICATE_HELPER_SOURCE.count("\n") + 1
+    validate_content = gate_module.load_validate_content()
+
+    resolved_copied = copied_file.resolve()
+    blocking_by_file, advisory_by_file, _skipped = (
+        gate_module._collect_partitioned_violations(
+            validate_content,
+            [copied_file],
+            temporary_git_repository,
+            {resolved_copied: {unrelated_added_line}},
+        )
+    )
+
+    all_blocking_messages = [
+        each_message
+        for each_file_messages in blocking_by_file.values()
+        for each_message in each_file_messages
+    ]
+    all_advisory_messages = [
+        each_message
+        for each_file_messages in advisory_by_file.values()
+        for each_message in each_file_messages
+    ]
+    assert not any(
+        "duplicates existing_helper.py" in each_message
+        for each_message in all_blocking_messages
+    ), (
+        "An unrelated edit to a file carrying a pre-existing sibling-duplicate "
+        f"helper must not block, got blocking: {all_blocking_messages}"
+    )
+    assert any(
+        "duplicates existing_helper.py" in each_message
+        for each_message in all_advisory_messages
+    ), (
+        "The untouched pre-existing duplicate must surface as advisory, got "
+        f"advisory: {all_advisory_messages}"
+    )
+
+
+def test_collect_partitioned_violations_blocks_sibling_duplicate_in_added_region(
+    temporary_git_repository: Path,
+) -> None:
+    """When the diff's added lines fall inside the copied function, the duplicate
+    body is blocking — staging an edit that touches the copied helper still denies
+    the commit, matching the live Write/Edit hook."""
+    package_directory = temporary_git_repository / "package"
+    package_directory.mkdir()
+    existing_file = package_directory / "existing_helper.py"
+    existing_file.write_text(_DUPLICATE_HELPER_SOURCE, encoding="utf-8")
+    copied_file = package_directory / "copied_helper.py"
+    copied_file.write_text(_DUPLICATE_HELPER_SOURCE, encoding="utf-8")
+    definition_line = 3
+    last_body_line = 15
+    all_copied_function_lines = set(range(definition_line, last_body_line + 1))
+    validate_content = gate_module.load_validate_content()
+
+    resolved_copied = copied_file.resolve()
+    blocking_by_file, _advisory_by_file, _skipped = (
+        gate_module._collect_partitioned_violations(
+            validate_content,
+            [copied_file],
+            temporary_git_repository,
+            {resolved_copied: all_copied_function_lines},
+        )
+    )
+
+    all_blocking_messages = [
+        each_message
+        for each_file_messages in blocking_by_file.values()
+        for each_message in each_file_messages
+    ]
+    assert any(
+        "duplicates existing_helper.py" in each_message
+        for each_message in all_blocking_messages
+    ), (
+        "An edit whose added lines touch the copied helper must still block, got "
+        f"blocking: {all_blocking_messages}"
+    )
+
+
 def test_run_gate_skips_non_utf8_source_without_crashing(
     temporary_git_repository: Path,
     monkeypatch: pytest.MonkeyPatch,

package/_shared/pr-loop/scripts/tests/test_reviews_disabled.py

@@ -65,6 +65,35 @@ def test_is_bugbot_disabled_via_env_true_when_both_tokens_listed_mixed_case(
     assert reviews_disabled.is_bugteam_disabled_via_env() is True
 
 
+def test_is_copilot_disabled_via_env_returns_true_when_env_lists_copilot(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "copilot")
+    assert reviews_disabled.is_copilot_disabled_via_env() is True
+
+
+def test_is_copilot_disabled_via_env_returns_false_when_env_is_empty(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("CLAUDE_REVIEWS_DISABLED", raising=False)
+    assert reviews_disabled.is_copilot_disabled_via_env() is False
+
+
+def test_is_copilot_disabled_via_env_returns_false_when_only_bugbot_listed(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "bugbot")
+    assert reviews_disabled.is_copilot_disabled_via_env() is False
+
+
+def test_is_copilot_disabled_via_env_true_when_listed_among_other_tokens(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", " BugBot , CoPilot ")
+    assert reviews_disabled.is_copilot_disabled_via_env() is True
+    assert reviews_disabled.is_bugbot_disabled_via_env() is True
+
+
 def test_cli_main_returns_zero_when_named_reviewer_disabled(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:

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

@@ -25,7 +25,7 @@ Decomposition is by the **kind of docstring claim** that needs to be cross-check
 | O3 | Predicate-name and -docstring vs body breadth | A boolean helper's name and docstring promise a narrow predicate. Walk the body's branches: every branch's `return True` path is consistent with the promised name. Bodies that accept inputs broader than the name (`_dir_value_resolves_to_shared_temp` also accepting HOME/TMP env-derived paths) are O3 findings. |
 | O4 | Step-ordering narrative | A docstring describes processing as `A then B then C`. Walk the body and confirm the call order matches. Mismatched order is an O4 finding regardless of whether the final output is the same. |
 | O5 | Named-sentinel / filename references | A docstring names a sentinel marker, environment variable, filename, or magic string. Confirm the named token actually exists in the module body or in the repo's naming convention. |
-| 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. |
+| 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. 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. |
 
 ---

package/bin/install.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync, copyFileSync, unlinkSync, rmSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync, copyFileSync, unlinkSync, rmSync, realpathSync } from 'node:fs';
 import { join, dirname, resolve, relative } from 'node:path';
 import { homedir } from 'node:os';
 import { execSync, execFileSync } from 'node:child_process';
@@ -188,14 +188,53 @@ export function pythonCandidatesForPlatform(platform) {
     return platform === 'win32' ? windowsOrder : defaultOrder;
 }
 
+/**
+ * Reports whether a resolved interpreter path belongs to the Microsoft Store
+ * Python, whose `python.exe` App Execution Alias reparse stub cannot be spawned
+ * as a hook subprocess. Both the alias under `Microsoft\WindowsApps` and the
+ * package executable under `Program Files\WindowsApps` sit beneath a
+ * `WindowsApps` directory, so the installer skips any candidate resolving there.
+ *
+ * @param {string} executablePath Absolute interpreter path from sys.executable.
+ * @returns {boolean} True when the path lives under a WindowsApps directory.
+ */
+export function isWindowsStorePythonStub(executablePath) {
+    return /[\\/]windowsapps[\\/]/i.test(executablePath);
+}
+
+/**
+ * Formats an absolute interpreter path as a settings.json hook command prefix:
+ * forward-slash separators, double-quoted when the path contains a space so the
+ * harness parses the interpreter as a single argument.
+ *
+ * @param {string} executablePath Absolute interpreter path from sys.executable.
+ * @returns {string} The command-prefix form of the interpreter path.
+ */
+export function interpreterCommandFromPath(executablePath) {
+    const forwardSlashedPath = executablePath.replace(/\\/g, '/');
+    return forwardSlashedPath.includes(' ') ? `"${forwardSlashedPath}"` : forwardSlashedPath;
+}
+
+/**
+ * Picks the interpreter command baked into every managed hook in settings.json.
+ * On win32 the first working candidate is resolved to its absolute
+ * sys.executable and that path is baked in, so a later PATH change or Microsoft
+ * Store update that re-points the `py`/`python` launcher cannot silently break
+ * the hooks; candidates resolving to the non-spawnable WindowsApps stub are
+ * skipped. Other platforms keep the bare command (e.g. `python3`).
+ *
+ * @returns {string|null} The interpreter command, or null when none is usable.
+ */
 function detectPython() {
     const candidates = pythonCandidatesForPlatform(process.platform);
     for (const { command, versionFlag } of candidates) {
         try {
             const version = execSync(`${command} ${versionFlag}`, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
-            if (version.includes('Python 3.')) {
-                return command;
-            }
+            if (!version.includes('Python 3.')) continue;
+            if (process.platform !== 'win32') return command;
+            const executablePath = execSync(`${command} -c "import sys; print(sys.executable)"`, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+            if (!executablePath || isWindowsStorePythonStub(executablePath)) continue;
+            return interpreterCommandFromPath(executablePath);
         } catch { /* try next */ }
     }
     return null;
@@ -501,7 +540,7 @@ function install(selectedGroups, options = {}) {
     abortWhenPackageSourceHasConflicts(PACKAGE_ROOT);
     const pythonCommand = detectPython();
     if (!pythonCommand) {
-        console.error('ERROR: Python 3 not found. Install Python 3.8+ and ensure python3, python, or py is on PATH.');
+        console.error('ERROR: No usable Python 3 found. Install Python 3.8+ from python.org and ensure py, python3, or python is on PATH. On Windows the Microsoft Store python.exe alias is rejected because it cannot run hooks.');
         process.exit(1);
     }
     console.log(`  Python: ${pythonCommand}`);
@@ -815,28 +854,62 @@ writes the previous contents to ~/.claude/backups/CLAUDE.md.<timestamp>.bak firs
 `);
 }
 
-const rawArgs = process.argv.slice(2);
-const args = rawArgs.filter((flag) => flag !== '--update');
-const isUpdateRefresh = rawArgs.includes('--update');
-if (args.includes('--help') || args.includes('-h')) {
-    printHelp();
-} else if (args.includes('--uninstall')) {
-    uninstall();
-} else {
-    const onlyIndex = args.indexOf('--only');
-    let selectedGroups = null;
-    if (onlyIndex !== -1) {
-        const onlyValue = args[onlyIndex + 1];
-        if (!onlyValue || onlyValue.startsWith('--')) {
-            console.error(`ERROR: --only requires a comma-separated list of groups.\nAvailable groups: ${Object.keys(INSTALL_GROUPS).join(', ')}`);
-            process.exit(1);
-        }
-        selectedGroups = onlyValue.split(',').map(name => name.trim());
-        const invalidGroups = selectedGroups.filter(name => !INSTALL_GROUPS[name]);
-        if (invalidGroups.length > 0) {
-            console.error(`ERROR: Unknown group(s): ${invalidGroups.join(', ')}\nAvailable groups: ${Object.keys(INSTALL_GROUPS).join(', ')}`);
-            process.exit(1);
+/**
+ * Reports whether this module is the process entry point (run as
+ * `node install.mjs`, or through a bin symlink such as the npm-installed
+ * `claude-dev-env` launcher) rather than imported by another module such as the
+ * test suite. The install/uninstall dispatch runs only when true, so importing
+ * the module carries no side effects.
+ *
+ * Both sides resolve to their real on-disk paths before comparison, so a
+ * symlinked launcher whose target is this module still counts as the entry
+ * point even though `process.argv[1]` keeps the symlink path while
+ * `import.meta.url` reports the resolved target. When either path cannot be
+ * resolved on disk (for example a synthetic path in a unit test), the raw
+ * paths are compared instead.
+ *
+ * @param {string} moduleUrl The module's import.meta.url.
+ * @param {string|undefined} entryScriptPath The invoked script path (process.argv[1]).
+ * @returns {boolean} True when the module is the process entry point.
+ */
+export function invokedAsEntryPoint(moduleUrl, entryScriptPath) {
+    if (!entryScriptPath) return false;
+    const modulePath = fileURLToPath(moduleUrl);
+    return realPathOrSelf(modulePath) === realPathOrSelf(entryScriptPath);
+}
+
+function realPathOrSelf(filesystemPath) {
+    try {
+        return realpathSync(filesystemPath);
+    } catch {
+        return filesystemPath;
+    }
+}
+
+if (invokedAsEntryPoint(import.meta.url, process.argv[1])) {
+    const rawArgs = process.argv.slice(2);
+    const args = rawArgs.filter((flag) => flag !== '--update');
+    const isUpdateRefresh = rawArgs.includes('--update');
+    if (args.includes('--help') || args.includes('-h')) {
+        printHelp();
+    } else if (args.includes('--uninstall')) {
+        uninstall();
+    } else {
+        const onlyIndex = args.indexOf('--only');
+        let selectedGroups = null;
+        if (onlyIndex !== -1) {
+            const onlyValue = args[onlyIndex + 1];
+            if (!onlyValue || onlyValue.startsWith('--')) {
+                console.error(`ERROR: --only requires a comma-separated list of groups.\nAvailable groups: ${Object.keys(INSTALL_GROUPS).join(', ')}`);
+                process.exit(1);
+            }
+            selectedGroups = onlyValue.split(',').map(name => name.trim());
+            const invalidGroups = selectedGroups.filter(name => !INSTALL_GROUPS[name]);
+            if (invalidGroups.length > 0) {
+                console.error(`ERROR: Unknown group(s): ${invalidGroups.join(', ')}\nAvailable groups: ${Object.keys(INSTALL_GROUPS).join(', ')}`);
+                process.exit(1);
+            }
         }
+        install(selectedGroups, { isUpdateRefresh });
     }
-    install(selectedGroups, { isUpdateRefresh });
 }