claude-dev-env 2.5.0 → 2.7.0

package/CLAUDE.md

@@ -1,88 +1,51 @@
 # Development Assistant
 
-## Advisor consultation
-
-When the `advisor()` tool is available, reference `~/.claude/docs/references/advisor-tool.md`. For complex tasks, reference `~/.claude/docs/references/team-advisor-skill.md` and use the `/team-advisor` skill.
-
 ## Communication
 
-Use direct affirmative framing that states the desired action clearly and positively. Contrastive negation is banned.
-
-Write concise, ADHD-friendly responses.
-
-- Always say what is, rather than what is not.
-- Lead with the outcome.
-- Use short, active sentences with one idea each.
-- Put meaning before mechanism.
-- Explain jargon on first use.
-- Use plain-claim headings and bold leads.
-- Limit bullets to two sentences and paragraphs to three.
-- Omit repetition, narration, unnecessary options, and trailing notes.
-- End with what the reader must know or decide.
-
-## Execution and security
-
-For code tasks, execute available steps directly and minimize manual work.
+Reply shape and length: follow `~/.claude/rules/eli11-replies.md`. Word choice: follow `~/.claude/rules/plain-language.md`. State claims affirmatively.
 
-Always execute as many parallel workers as you can, when tasks do not overlap or conflict.
+## Security
 
-Ask when ambiguity materially changes scope or implementation. Collect credentials through secure UI only; never request secrets in chat.
+Collect credentials through secure UI only; never request secrets in chat.
 
 A runtime value that is itself private — a host, an SSH user or port, an owner scope, an account ID — lives in git-ignored local configuration with a committed placeholder in its place. Source files never carry the real value.
 
-## Documentation
+## Advisors
 
-Describe only the current system state. Keep documentation self-contained and free of historical, transitional, conversational, or version-transition language. Never use negative prose or antipatterns. Always state what to do, specifically.
-
-Follow:
-
-- `~/.claude/rules/no-historical-clutter.md`
-- `~/.claude/rules/self-contained-docs.md`
-- `~/.claude/skills/condensing-instructions/SKILL.md`
-
-## File edits
-
-`Edit` changes an existing file. `Write` creates a new file. Default to `Edit`; reach for `Write` only when the path is genuinely new.
+When the `advisor()` tool is available, read `~/.claude/docs/references/advisor-tool.md`. For complex tasks use the `/team-advisor` skill.
 
 ## Files and workspaces
 
-Put all work in an isolated git worktree, created outside the primary checkout.
-
-### Code and tests
+Put all work in an isolated worktree under the repo's `.claude/worktrees/`.
 
-Tests exercise real behavior, real data, and production paths.
+Default to Edit for existing files; reach for Write only when the path is genuinely new.
 
-For multi-step code tasks:
+## Code and tests
 
-- Assign each scope to its own coder agent.
-- A coder consults a tool-less advisor agent when blocked.
-- A fresh-context verifier agent runs named gates, baseline checks, and a two-way task-to-diff review.
-- Repair only reported findings, then re-verify after every repair.
+Tests must exercise real behavior, real data, and production paths.
 
-Do not commit, push, or open a PR until verification is clean and the verified-commit gate covers the current diff. The verification requirement is waived only for a non-code diff, or when the Python AST is unchanged after removing docstrings.
+Keep changes within scope. Prefer durable systemic fixes for reusable behavior.
 
-Keep changes within scope. Prefer durable systemic fixes for reusable behavior. Do not rewrite entire files or rename public parameters without need.
+Do not rewrite entire files or rename public parameters without need.
 
-### Reviews and convergence
+## Reviews
 
-Report only findings verified against the code. Verify every sub-agent file list, count, description, and finding against the repository and the diff before using it.
+Verify every sub-agent file list, count, description, and finding against the repository and diff.
 
 Do not commit untracked files unless explicitly instructed.
 
-### Research and delegation
-
-Delegate fact extraction when multiple files or search patterns are required. Request precise file-and-line answers.
+## Delegation
 
-Use fresh parallel subagents, each named for its task, for unrelated questions at whatever effort level the task needs.
+Request precise file-and-line answers from research subagents.
 
-Read or search directly only in files you will actually modify this turn. Delegate broader fact-finding to a subagent instead of reading widely yourself.
+## Task tracking
 
-For code navigation, prefer a semantic code-navigation tool (an MCP server such as Serena, when available) or a fast file-search tool (such as Everything's `es.exe` on Windows, when available), then fall back to content search or globbing. Scope every search to a project directory. Never scan an entire drive or network share.
+Track multi-step work with the `task-build` skill.
 
-### Task tracking
+## Repository rule
 
-Track every task with the harness's task tool (TaskCreate/TaskUpdate) or the `task-build` skill: `~/.claude/skills/task-build/SKILL.md`.
+Before changing skill, rule, or hook installation in the claude-dev-env repo, read `docs/references/skill-install-system.md`.
 
 ## Definitions
 
-Warm agent: any agent who has acted within the past 30 minutes.
+Warm agent: active within the past 59 minutes.

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

@@ -32,6 +32,7 @@ try:
         gate_running,
         git_blob_readers,
         git_file_sets,
+        staged_test_regression,
         staged_test_running,
         violation_scoping,
         wrapper_plumb_check,
@@ -136,7 +137,7 @@ def _report_partitioned_violations(
         is_whole_file_scope,
     )
 
-run_staged_test_files = staged_test_running.run_staged_test_files
+run_staged_test_files = staged_test_regression.run_staged_test_files
 _staged_test_file_paths = staged_test_running._staged_test_file_paths
 _resolve_owning_test_root = staged_test_running._resolve_owning_test_root
 _group_staged_tests_by_root = staged_test_running._group_staged_tests_by_root

package/_shared/pr-loop/scripts/code_rules_gate_parts/CLAUDE.md

@@ -15,15 +15,25 @@ surface for the test suite.
 | `violation_scoping.py` | Recovers a violation's line span from the enforcer message and partitions violations into blocking versus advisory |
 | `wrapper_plumb_check.py` | Flags a public wrapper that drops a same-file delegate's optional keyword arguments; holds the code-path and test-path classifiers |
 | `gate_running.py` | Validates the eligible file set, reports the inspected-file count, and prints the partitioned violation report |
-| `staged_test_running.py` | Runs the staged Python test files, grouped by their owning pytest config, in command-line-length-safe batches |
+| `staged_test_running.py` | Runs one staged-test group, grouped by its owning pytest config and by top-level directory when no config owns it, in command-line-length-safe pytest batches, optionally writing a JUnit XML report per batch |
+| `staged_test_regression.py` | Discovers the staged test files, runs every group, and blocks only on a failure the staged change introduces — a group that fails is re-run against the HEAD baseline (a throwaway detached checkout made with `git worktree add --detach` under the OS temp root, deleted with `git worktree remove --force`) and only a failure absent there blocks |
+| `baseline_import_isolation.py` | Points the baseline run's imports at the baseline worktree — rebases every repository import root onto the front of its `PYTHONPATH` — and installs the pytest plugin that reports which modules the run loaded out of the user's own tree, so a route that survives the rebase is measured and the baseline discarded |
 | `gate_arguments.py` | Parses the gate's command-line arguments |
 | `__init__.py` | Package marker |
 
+## Staged-test grouping boundaries
+
+The top-level fallback in `staged_test_running.py` fires only in a repository
+whose root holds no pytest config, and it splits top-level neighbors alone:
+
+- Config-less packages that sit deeper under one shared top-level directory, such as `pkgs/alpha` and `pkgs/beta`, share that directory's single pytest session, so a module name they both expose still shadows.
+- A `conftest.py` at the repository root stays unloaded for those groups, because each session works from the top-level directory and the root file falls outside the tree pytest treats as its root.
+
 ## Subdirectory
 
 | Entry | Description |
 |---|---|
-| `tests/` | pytest suite with one test module per module above |
+| `tests/` | pytest suite with one test module per module above, plus `_repo_test_helpers.py` (shared real-git-repository builders) |
 
 ## Running tests
 

package/_shared/pr-loop/scripts/code_rules_gate_parts/baseline_import_isolation.py

@@ -0,0 +1,309 @@
+"""Make the HEAD baseline run import from the baseline worktree, and prove that it did.
+
+::
+
+    repository_root   = /repo            (working tree, staged edits)
+    baseline_worktree = /tmp/base/tree   (detached HEAD, clean)
+
+    ok:   PYTHONPATH=/repo/packages   -> PYTHONPATH=/tmp/base/tree/packages
+    ok:   editable root /repo/src     -> /tmp/base/tree/src prepended
+    flag: import hook ahead of the path scan still serving /repo/src/foo.py
+          -> reported by the leak plugin, baseline discarded
+
+Rebasing the working directory alone does not move imports. An absolute route
+into the user's own checkout keeps serving staged code to the baseline run.
+Two shapes reach it: a ``PYTHONPATH`` entry under the repository root, and an
+editable install pointing at it. The baseline then fails the way the staged run
+failed, and the two failures cancel a real regression out.
+
+Two halves close that. Every import root inside the repository is rewritten to
+its baseline-worktree equivalent and put at the front of ``PYTHONPATH``. That
+beats every ``.pth`` entry and every setuptools editable style. Then the
+baseline pytest session loads a plugin that records which modules it imported
+out of the user's tree. A route that survives the rewrite is measured, never
+assumed.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from pr_loop_shared_constants.code_rules_gate_constants import (
+    BASELINE_IMPORT_PROBE_REJECTED_MESSAGE,
+    BASELINE_IMPORT_PROBE_TIMED_OUT_MESSAGE,
+    BASELINE_IMPORT_PROBE_TIMEOUT_SECONDS,
+    BASELINE_IMPORT_PROBE_UNSTARTABLE_MESSAGE,
+    BASELINE_IMPORT_ROOT_PROBE_SOURCE,
+    BASELINE_LEAK_PLUGIN_MODULE_NAME,
+    BASELINE_LEAK_PLUGIN_SOURCE,
+    BASELINE_LEAK_REPORT_ENV_VAR,
+    BASELINE_PRIMARY_ROOT_ENV_VAR,
+    PYTEST_PLUGINS_ENV_VAR,
+    PYTEST_PLUGINS_SEPARATOR,
+    PYTHON_FILE_EXTENSION,
+    PYTHON_INTERPRETER_COMMAND_FLAG,
+    PYTHONPATH_ENV_VAR,
+)
+
+
+def _resolved_directory(path_text: str) -> Path | None:
+    """Return *path_text* resolved to an absolute path, or None when it is unusable."""
+    if not path_text:
+        return None
+    try:
+        return Path(path_text).resolve()
+    except OSError:
+        return None
+
+
+def _is_under(candidate: Path, root: Path) -> bool:
+    """Return True when *candidate* is *root* itself or sits anywhere beneath it."""
+    return candidate == root or root in candidate.parents
+
+
+def rebased_into_baseline(
+    original_path: Path, repository_root: Path, baseline_worktree: Path
+) -> Path | None:
+    """Return *original_path* moved into the baseline worktree, or None when outside the repo.
+
+    ::
+
+        repository_root = /repo
+        ok:   /repo/packages -> /tmp/base/tree/packages
+        ok:   /repo          -> /tmp/base/tree
+        flag: /elsewhere/lib -> None (nothing in the baseline tree answers for it)
+
+    Args:
+        original_path: An already-resolved filesystem path.
+        repository_root: The user's own repository root.
+        baseline_worktree: The detached-HEAD worktree the baseline run uses.
+
+    Returns:
+        The same repository-relative location inside *baseline_worktree*, or
+        None when *original_path* lies outside the repository.
+    """
+    if not _is_under(original_path, repository_root):
+        return None
+    return baseline_worktree / original_path.relative_to(repository_root)
+
+
+def discover_import_roots(
+    python_executable: str,
+    all_environment_settings: dict[str, str],
+    working_directory: Path,
+) -> list[Path]:
+    """Return every directory the interpreter would resolve imported packages from.
+
+    Covers ``sys.path`` — which carries ``PYTHONPATH`` and every ``.pth``-added
+    entry — plus the package roots an editable install registers through an
+    import hook, which never appear on ``sys.path`` at all.
+
+    Args:
+        python_executable: The interpreter the staged and baseline runs use.
+        all_environment_settings: The environment the probe runs under.
+        working_directory: A directory outside the repository, so the probe's
+            own working directory never reads as a repository import root.
+
+    Returns:
+        The resolved import roots, or an empty list when the probe times out,
+        cannot start, or exits non-zero. Each of those says so on stderr, and
+        the run continues into the baseline with its leak report still armed.
+    """
+    probe = _completed_import_root_probe(
+        python_executable, all_environment_settings, working_directory
+    )
+    if probe is None:
+        return []
+    if probe.returncode != 0:
+        sys.stderr.write(
+            BASELINE_IMPORT_PROBE_REJECTED_MESSAGE.format(status=probe.returncode) + "\n"
+        )
+        return []
+    return _probed_roots(probe.stdout)
+
+
+def _completed_import_root_probe(
+    python_executable: str,
+    all_environment_settings: dict[str, str],
+    working_directory: Path,
+) -> subprocess.CompletedProcess[str] | None:
+    """Run the probe interpreter to completion, or report on stderr why it produced nothing.
+
+    ::
+
+        ok:   probe exits 0        -> CompletedProcess carrying its output
+        flag: probe hangs          -> None, "did not finish within 120 seconds"
+        flag: interpreter missing  -> None, "did not start (...)"
+
+    A probe that outlives its limit is the same situation as a probe that fails:
+    no roots were learned, so the caller carries on without them rather than
+    raising a traceback out of a pre-commit hook.
+    """
+    try:
+        return subprocess.run(
+            [python_executable, PYTHON_INTERPRETER_COMMAND_FLAG, BASELINE_IMPORT_ROOT_PROBE_SOURCE],
+            cwd=str(working_directory),
+            env=all_environment_settings,
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=BASELINE_IMPORT_PROBE_TIMEOUT_SECONDS,
+        )
+    except subprocess.TimeoutExpired:
+        sys.stderr.write(
+            BASELINE_IMPORT_PROBE_TIMED_OUT_MESSAGE.format(
+                seconds=BASELINE_IMPORT_PROBE_TIMEOUT_SECONDS
+            )
+            + "\n"
+        )
+        return None
+    except OSError as probe_failure:
+        sys.stderr.write(
+            BASELINE_IMPORT_PROBE_UNSTARTABLE_MESSAGE.format(reason=probe_failure) + "\n"
+        )
+        return None
+
+
+def _probed_roots(probe_text: str) -> list[Path]:
+    """Return the resolved directories named on the probe's final output line."""
+    all_probe_lines = probe_text.strip().splitlines()
+    if not all_probe_lines:
+        return []
+    try:
+        all_root_texts = json.loads(all_probe_lines[-1])
+    except ValueError:
+        return []
+    all_roots = [_resolved_directory(str(each_text)) for each_text in all_root_texts]
+    return [each_root for each_root in all_roots if each_root is not None]
+
+
+def _baseline_path_entries(
+    all_import_roots: list[Path], repository_root: Path, baseline_worktree: Path
+) -> list[str]:
+    """Return the baseline-worktree equivalent of every import root inside the repository."""
+    all_entries: list[str] = []
+    for each_root in all_import_roots:
+        rebased_root = rebased_into_baseline(each_root, repository_root, baseline_worktree)
+        if rebased_root is not None:
+            all_entries.append(str(rebased_root))
+    return all_entries
+
+
+def _rebased_pythonpath_entries(
+    all_staged_environment_settings: dict[str, str],
+    repository_root: Path,
+    baseline_worktree: Path,
+) -> list[str]:
+    """Return the staged ``PYTHONPATH`` with every repository entry moved into the baseline."""
+    all_entries: list[str] = []
+    staged_pythonpath = all_staged_environment_settings.get(PYTHONPATH_ENV_VAR, "")
+    for each_entry in staged_pythonpath.split(os.pathsep):
+        resolved_entry = _resolved_directory(each_entry)
+        rebased_entry = (
+            None
+            if resolved_entry is None
+            else rebased_into_baseline(resolved_entry, repository_root, baseline_worktree)
+        )
+        all_entries.append(each_entry if rebased_entry is None else str(rebased_entry))
+    return [each_entry for each_entry in all_entries if each_entry]
+
+
+def install_leak_plugin(plugin_directory: Path) -> None:
+    """Write the import-origin reporting pytest plugin into its own directory.
+
+    Args:
+        plugin_directory: The directory the plugin module is written to, which
+            the baseline run puts on its ``PYTHONPATH`` so pytest loads it.
+    """
+    plugin_directory.mkdir(parents=True, exist_ok=True)
+    plugin_path = plugin_directory / f"{BASELINE_LEAK_PLUGIN_MODULE_NAME}{PYTHON_FILE_EXTENSION}"
+    plugin_path.write_text(
+        BASELINE_LEAK_PLUGIN_SOURCE.format(
+            primary_root_env_var=BASELINE_PRIMARY_ROOT_ENV_VAR,
+            report_path_env_var=BASELINE_LEAK_REPORT_ENV_VAR,
+        ),
+        encoding="utf-8",
+    )
+
+
+def _pytest_plugins_setting(all_staged_environment_settings: dict[str, str]) -> str:
+    """Return the ``PYTEST_PLUGINS`` value with the leak plugin added to any existing list."""
+    existing_setting = all_staged_environment_settings.get(PYTEST_PLUGINS_ENV_VAR, "")
+    if not existing_setting:
+        return BASELINE_LEAK_PLUGIN_MODULE_NAME
+    return PYTEST_PLUGINS_SEPARATOR.join([BASELINE_LEAK_PLUGIN_MODULE_NAME, existing_setting])
+
+
+def baseline_pytest_environment(
+    all_staged_environment_settings: dict[str, str],
+    repository_root: Path,
+    baseline_worktree: Path,
+    all_import_roots: list[Path],
+    plugin_directory: Path,
+    leak_report_path: Path,
+) -> dict[str, str]:
+    """Return the environment the baseline pytest run uses.
+
+    Every repository import root leads with its baseline-worktree equivalent,
+    the plugin directory follows, and the staged ``PYTHONPATH`` (itself rebased
+    entry by entry) trails behind, so a module that exists at HEAD always
+    resolves out of the baseline tree.
+
+    Args:
+        all_staged_environment_settings: The environment the staged run used.
+        repository_root: The user's own repository root.
+        baseline_worktree: The detached-HEAD worktree the baseline run uses.
+        all_import_roots: The import roots ``discover_import_roots`` found.
+        plugin_directory: The directory holding the leak-reporting plugin.
+        leak_report_path: Where the plugin writes its import-origin report.
+
+    Returns:
+        A copy of *all_staged_environment_settings* carrying the baseline
+        import path and the leak plugin's three settings.
+    """
+    baseline_environment = dict(all_staged_environment_settings)
+    all_entries = [
+        *_baseline_path_entries(all_import_roots, repository_root, baseline_worktree),
+        str(plugin_directory),
+        *_rebased_pythonpath_entries(
+            all_staged_environment_settings, repository_root, baseline_worktree
+        ),
+    ]
+    baseline_environment[PYTHONPATH_ENV_VAR] = os.pathsep.join(dict.fromkeys(all_entries))
+    baseline_environment[PYTEST_PLUGINS_ENV_VAR] = _pytest_plugins_setting(
+        all_staged_environment_settings
+    )
+    baseline_environment[BASELINE_PRIMARY_ROOT_ENV_VAR] = str(repository_root)
+    baseline_environment[BASELINE_LEAK_REPORT_ENV_VAR] = str(leak_report_path)
+    return baseline_environment
+
+
+def modules_imported_from_primary_tree(leak_report_path: Path) -> list[Path] | None:
+    """Return the user's-tree modules the baseline run imported, or None when unreported.
+
+    ::
+
+        ok:   []                       -> the baseline measured HEAD alone
+        flag: [/repo/packages/foo.py]  -> the baseline read staged code
+        flag: None                     -> the run left no report; nothing is proven
+
+    Args:
+        leak_report_path: The report path the baseline run was given.
+
+    Returns:
+        The resolved module paths, empty when the baseline stayed clean, or None
+        when the report is missing or unreadable.
+    """
+    try:
+        report_text = leak_report_path.read_text(encoding="utf-8")
+    except OSError:
+        return None
+    try:
+        all_module_texts = json.loads(report_text)
+    except ValueError:
+        return None
+    return [Path(str(each_text)) for each_text in all_module_texts]