claude-dev-env 2.4.0 → 2.7.0

package/CLAUDE.md

@@ -1,84 +1,51 @@
-# Claude Development Assistant
+# Development Assistant
 
-The user is short on time and appreciates brevity in replies. When you reply, always assume they'll only read your first few sentences and final sentences. Anything else is skimmed at best. Frame your replies accordingly.
+## Communication
 
-The user delegates execution to you and expects zero manual steps unless strictly necessary. Execute every command you can directly. Only instruct the user to do something manually when you are technically unable to do it yourself. When a task involves credentials or other sensitive input, display a minimal secure UI (e.g., a password dialog) to collect it rather than asking the user to paste it into chat or run the command themselves. When direction is ambiguous, use AskUserQuestion to clarify before acting.
+Reply shape and length: follow `~/.claude/rules/eli11-replies.md`. Word choice: follow `~/.claude/rules/plain-language.md`. State claims affirmatively.
 
-## Timeless Documentation (all `.md` files)
+## Security
 
-Docs describe the current state only. Full rule set and enforcement: `~/.claude/rules/no-historical-clutter.md` (hook `state-description-blocker`) and `~/.claude/rules/self-contained-docs.md`.
+Collect credentials through secure UI only; never request secrets in chat.
 
-## Private values stay out of the committed tree
+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.
 
-A value the code needs at run time that is itself private — a host, ssh user or port, owner scope, or id — lives in git-ignored local config with a committed placeholder, not in the source.
+## Advisors
 
-## Choosing Edit vs Write
+When the `advisor()` tool is available, read `~/.claude/docs/references/advisor-tool.md`. For complex tasks use the `/team-advisor` skill.
 
-`Edit` changes existing files; `Write` creates new ones. Default to `Edit` — reach for `Write` only for a genuinely new path. For a true full rewrite, delete the file first, then `Write`.
+## Files and workspaces
 
-## Showing Files: Open Them, Don't Print the Path
+Put all work in an isolated worktree under the repo's `.claude/worktrees/`.
 
-When I ask you to "show me", "open", "display", "let me see", or "pull up" a file — an image, PDF, HTML page, document, anything — open it on my screen. Launch the viewer so each image window matches the asset's size:
+Default to Edit for existing files; reach for Write only when the path is genuinely new.
 
-`Start-Process pwsh -WindowStyle Hidden -ArgumentList '-NoProfile','-File',"$HOME\.claude\scripts\Show-Asset.ps1",'<path 1>','<path 2>'`
+## Code and tests
 
-## Test Philosophy
+Tests must exercise real behavior, real data, and production paths.
 
-When writing tests, always write tests that actually test the behavior of the function against actual, real data and environments.
+Keep changes within scope. Prefer durable systemic fixes for reusable behavior.
 
-When writing tests, always ensure you utilize the production code paths instead of duplicating explicitly for the test.
+Do not rewrite entire files or rename public parameters without need.
 
-## Research via Subagents
+## Reviews
 
-Delegate exploration whose raw content you won't directly edit or reuse. If you'd `Read` more than one file or `Grep` more than one pattern just to extract a fact, dispatch an `Explore` subagent.
+Verify every sub-agent file list, count, description, and finding against the repository and diff.
 
-Ask the subagent for a specific answer: "return the file:line where X is defined." For multiple unrelated questions, fan out parallel subagents — issue several `Agent` calls in a single response.
+Do not commit untracked files unless explicitly instructed.
 
-Reserve `Read`/`Grep`/`Glob` for files you will actually touch this turn. Compose subagent prompts via the protocol in `agent-spawn-protocol`.
+## Delegation
 
-## Target Execution Workflow for Code Tasks
+Request precise file-and-line answers from research subagents.
 
-Run every multi-step code task in three ordered phases:
+## Task tracking
 
-1. **Coders** — one coder agent per scoped assignment writes the code. A coder that hits a decision it can't reasonably solve consults the advisor (see beginning of this file).
-2. **Commit-gate preflight** — before spawning `code-verifier`, the branch must be merge-clean vs base and CODE_RULES-clean on added working-tree lines (committed on the branch or uncommitted). The `code_verifier_spawn_preflight_gate` enforces this on Agent/Task spawns with `subagent_type` `code-verifier`; do not spawn the verifier until those gates are green.
-3. **Verification** — the main session spawns the `code-verifier` agent in a fresh context, but you must first verify that their work is based on upstream's origin main (aka: the commit live on github). 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. Before it emits the verdict, it puts the draft through one strongest-tier validation subagent — selected per the advisor protocol's host detection and tier ladder — that tries to refute it, and it re-checks and corrects any part the validator overturns. 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.
+Track multi-step work with the `task-build` skill.
 
-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. One exemption is mechanical, not discretionary: a diff whose every changed file is non-code (docs, images), a pytest test file by name (`test_*.py`, `*_test.py`, or `conftest.py`), or a Python file whose docstring-stripped AST is unchanged (docstring, comment, or formatting-only edits). One escape hatch is manual and narrow: appending `# verify-skip` as a trailing shell comment (outside every quoted region) to the blocked commit or push command bypasses the gate for that one command — allowed only when the branch surface is the same code a code-verifier already passed clean and the gate is blocking on a verdict that doesn't cover it (an unminted verdict, staging churn, a reverted concurrent write); any real code change since the clean verdict runs a fresh verification instead. Full rule: `~/.claude/rules/verified-commit-gate-skip.md`.
+## Repository rule
 
-## Sub-agent Output Validation
+Before changing skill, rule, or hook installation in the claude-dev-env repo, read `docs/references/skill-install-system.md`.
 
-After any sub-agent returns a PR description, file list, or counts, verify each claim against the actual diff and repo state before using it. Flag and correct any invented paths, fabricated counts, or out-of-scope changes before they land in commits or PR bodies.
+## Definitions
 
-## Task Tracking
-
-Track every task with the task tool, always — for all sessions and all tasks. Capture each task with `TaskCreate` as it arrives, mark it `in_progress` with `TaskUpdate` when you start, and `completed` when it is done. Run `/task-build` to gather any open tasks and add them to the list in one pass.
-
-## Working in the claude-dev-env Repo
-
-When changing how skills, rules, or hooks install or sync in this repo (for example adding a skill), read `docs/references/skill-install-system.md` — it maps the install pipeline in `packages/claude-dev-env/bin/install.mjs`.
-
-## Additional Non-overlapping Rules
-
-- **disambiguate_overloaded_terms:** When a word in the request has two different technical meanings — "conflict" (git-merge versus functional/behavioral), "sync" (fast-forward versus commit), and the like — confirm which one is meant via AskUserQuestion before analyzing or acting.
-
-## Serena (Code Intelligence MCP)
-
-The `mcp__serena__*` tools expose LSP-level code intelligence for any activated project.
-
-### CRITICAL: Call `initial_instructions` first
-Before any coding task, call the `initial_instructions` tool to load the Serena Instructions Manual.
-
-### When to use Serena
-- **Symbol declaration** → `mcp__serena__find_declaration`
-- **All references to a symbol** → `mcp__serena__find_referencing_symbols`
-- **Implementations of an interface/class** → `mcp__serena__find_implementations`
-- **Rename across codebase** → `mcp__serena__rename_symbol`
-- **Targeted body replacement / insertion** → `replace_symbol_body`, `insert_after_symbol`, `insert_before_symbol`
-- **Safe symbol removal (no references)** → `mcp__serena__safe_delete_symbol`
-- **File diagnostics** → `mcp__serena__get_diagnostics_for_file`
-
-### Tool hierarchy for code navigation
-1. **Serena** — symbol-level navigation (declarations, references, implementations, rename)
-2. **es.exe** — file-system search by name/path/extension/size/date (Everything CLI)
-3. **Grep/Glob** — content and pattern matching
+Warm agent: active within the past 59 minutes.

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

@@ -18,9 +18,11 @@ from pathlib import Path
 from typing import NoReturn
 
 from pr_loop_shared_constants.claude_permissions_constants import (
+    ALL_INERT_FILE_PERMISSION_TOOLS,
     ALL_TRUST_ENTRY_PROJECT_PATH_BOUNDARY_QUOTE_CHARACTERS,
     CLAUDE_SETTINGS_DIRECTORY_NAME,
     GIT_DIRECTORY_NAME,
+    HOME_PROJECT_PATH_ALIAS,
     TEXT_FILE_ENCODING as TEXT_FILE_ENCODING,
     UNIQUE_TEMPORARY_SUFFIX_BYTE_LENGTH,
 )
@@ -80,6 +82,88 @@ def get_current_project_path() -> str:
     return normalized_project_path
 
 
+def permission_rule_tool_name(permission_rule: object) -> str | None:
+    """Return the tool name prefix of a Claude permission rule, or None.
+
+    ::
+
+        permission_rule_tool_name("Edit(/repo/.claude/**)")  # ok: "Edit"
+        permission_rule_tool_name(42)  # ok: None
+
+    Args:
+        permission_rule: A Claude settings allow/deny rule value.
+
+    Returns:
+        The tool name before the first ``(``, or None when the value is not a
+        well-formed rule string.
+    """
+    if not isinstance(permission_rule, str):
+        return None
+    opening_parenthesis_index = permission_rule.find("(")
+    if opening_parenthesis_index <= 0:
+        return None
+    return permission_rule[:opening_parenthesis_index]
+
+
+def is_inert_file_permission_rule(permission_rule: object) -> bool:
+    """Return True when a rule uses Write/Glob/NotebookEdit (ignored for files).
+
+    ::
+
+        is_inert_file_permission_rule("Write(/wt/.claude/**)")  # ok: True
+        is_inert_file_permission_rule("Edit(/repo/.claude/**)")  # ok: False
+
+    Args:
+        permission_rule: A Claude settings allow/deny rule value.
+
+    Returns:
+        True when the rule's tool is in ALL_INERT_FILE_PERMISSION_TOOLS.
+    """
+    tool_name = permission_rule_tool_name(permission_rule)
+    if tool_name is None:
+        return False
+    return tool_name in ALL_INERT_FILE_PERMISSION_TOOLS
+
+
+def all_project_path_aliases_for_reap(
+    project_path: str,
+    home_directory_path: str | None = None,
+) -> tuple[str, ...]:
+    """Return project path forms a revoke run should match when removing rules.
+
+    ::
+
+        all_project_path_aliases_for_reap("/repo")  # ok: ("/repo",)
+        all_project_path_aliases_for_reap("/home/u", home_directory_path="/home/u")
+            # ok: ("/home/u", "$HOME")
+
+    Always includes the absolute POSIX project path. When that path is the
+    user home directory, also includes ``$HOME`` so grant shapes like
+    ``Edit($HOME/.claude/**)`` are reaped from home cwd.
+
+    Args:
+        project_path: POSIX-style project root path from get_current_project_path.
+        home_directory_path: Optional home path for tests; defaults to Path.home().
+
+    Returns:
+        Ordered unique path aliases used when building project-scoped remove rules.
+    """
+    normalized_project_path = project_path.replace("\\", "/").rstrip("/")
+    resolved_home_directory_path = (
+        home_directory_path
+        if home_directory_path is not None
+        else str(Path.home())
+    ).replace("\\", "/").rstrip("/")
+    all_path_aliases: list[str] = [normalized_project_path]
+    if normalized_project_path.lower() == resolved_home_directory_path.lower():
+        all_path_aliases.append(HOME_PROJECT_PATH_ALIAS)
+    all_unique_path_aliases: list[str] = []
+    for each_path_alias in all_path_aliases:
+        if each_path_alias not in all_unique_path_aliases:
+            all_unique_path_aliases.append(each_path_alias)
+    return tuple(all_unique_path_aliases)
+
+
 def build_permission_rule(tool_name: str, project_path: str) -> str:
     return f"{tool_name}({project_path}/.claude/**)"
 

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
@@ -296,8 +297,9 @@ def _run_diff_mode(
     """Validate the merge-base diff joined with the untracked files.
 
     Zero candidates means nothing was inspected (bad wiring looks the same),
-    so that run refuses loudly. A set emptied only by the ``--only-under``
-    scope flows through ``run_gate`` over zero files and exits clean.
+    so that run refuses loudly. A set emptied by the ``--only-under`` scope or
+    left with no code files after the code-path filter flows through
+    ``run_gate`` over zero files and exits clean.
     """
     all_candidate_paths = _deduplicate_paths(
         paths_from_git_diff(repository_root, arguments.base)
@@ -308,6 +310,7 @@ def _run_diff_mode(
     file_paths = filter_paths_under_prefixes(
         all_candidate_paths, repository_root, arguments.only_under
     )
+    file_paths = [each_path for each_path in file_paths if is_code_path(each_path)]
     scoped_added_lines = (
         added_lines_by_file(repository_root, arguments.base, file_paths) if file_paths else {}
     )

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]