prizmkit 1.1.134 → 1.1.136

package/bundled/skills/prizmkit-test/scripts/build_test_evidence.py

@@ -5,6 +5,7 @@ Usage:
   python3 build_test_evidence.py --project-root ROOT --evidence-dir DIR init [--baseline COMMIT]
   python3 build_test_evidence.py --project-root ROOT --evidence-dir DIR capture-change
   python3 build_test_evidence.py --project-root ROOT --evidence-dir DIR inventory --request REQUEST
+  python3 build_test_evidence.py --project-root ROOT --evidence-dir DIR prepare-tests --request REQUEST
   python3 build_test_evidence.py --project-root ROOT --evidence-dir DIR execute --request REQUEST
   python3 build_test_evidence.py --project-root ROOT --evidence-dir DIR execute --replay-receipt RECEIPT
   python3 build_test_evidence.py --project-root ROOT --evidence-dir DIR differential --request REQUEST
@@ -21,6 +22,7 @@ from __future__ import annotations
 
 import argparse
 import datetime as dt
+import fnmatch
 import hashlib
 import json
 import os
@@ -44,7 +46,7 @@ LAYERS = (
     "affected-module-regression", "regression-ring",
 )
 BLOCKED_EXTERNAL_CLASSES = {"production", "unknown"}
-SNAPSHOT_VOLATILE_ROOTS = (
+INVENTORY_RESERVED_ROOTS = (
     ".prizmkit/state",
     ".prizmkit/test/evidence",
     ".prizmkit/" + "dev-" + "pipeline",
@@ -53,8 +55,8 @@ SNAPSHOT_VOLATILE_ROOTS = (
     ".codebuddy/worktrees",
     ".codex/worktrees",
 )
-SNAPSHOT_VOLATILE_NAMES = {".git", "__pycache__", ".pytest_cache", ".mypy_cache"}
-INVENTORY_RESERVED_ROOTS = SNAPSHOT_VOLATILE_ROOTS
+
+_IGNORED_DIR_NAMES = {".git", "__pycache__", ".pytest_cache", ".mypy_cache"}
 FINAL_RECORDS = {"manifest.json", "validation.json", "verdict.json", "test-report.md"}
 
 
@@ -150,7 +152,7 @@ def normalize_relative(value: str) -> str:
 
 def is_reserved_inventory_path(relative: str) -> bool:
     path = Path(relative)
-    if any(part in SNAPSHOT_VOLATILE_NAMES for part in path.parts):
+    if any(part in _IGNORED_DIR_NAMES for part in path.parts):
         return True
     return any(path == Path(prefix) or Path(prefix) in path.parents for prefix in INVENTORY_RESERVED_ROOTS)
 
@@ -326,6 +328,49 @@ def validate_external_targets(value: Any) -> list[dict[str, Any]]:
     return value
 
 
+def load_change_capture(
+    project_root: Path,
+    evidence_dir: Path,
+    *,
+    require_fresh: bool = False,
+) -> dict[str, Any]:
+    capture_path = evidence_dir / "change-capture.json"
+    if not capture_path.is_file():
+        raise RequestError("canonical change capture is required; run capture-change first")
+    capture = ensure_object(load_json(capture_path), "change capture")
+    baseline = capture.get("baseline_commit")
+    patch_path = evidence_dir / "source-change.patch"
+    if (
+        capture.get("capture_format") != "prizmkit-canonical-change-v1"
+        or not isinstance(baseline, str)
+        or not patch_path.is_file()
+        or capture.get("patch_path") != "source-change.patch"
+        or capture.get("patch_sha256") != file_sha256(patch_path)
+        or not isinstance(capture.get("changed_files"), list)
+    ):
+        raise RequestError("canonical change capture is incomplete or inconsistent")
+    if require_fresh:
+        live_patch, live_entries = canonical_change_patch(project_root, baseline)
+        live_patch_sha256 = hashlib.sha256(live_patch).hexdigest()
+        if (
+            live_patch_sha256 != capture["patch_sha256"]
+            or live_entries != capture["changed_files"]
+        ):
+            raise RequestError(
+                "canonical change capture is stale; rerun capture-change and inventory after repository changes"
+            )
+    return capture
+
+
+def captured_changed_paths(capture: dict[str, Any]) -> list[str]:
+    paths = {
+        item["path"]
+        for item in capture.get("changed_files", [])
+        if isinstance(item, dict) and isinstance(item.get("path"), str)
+    }
+    return sorted(paths)
+
+
 def plan_for_execution(evidence_dir: Path) -> dict[str, Any] | None:
     path = evidence_dir / "test-plan.json"
     if not path.exists():
@@ -333,13 +378,22 @@ def plan_for_execution(evidence_dir: Path) -> dict[str, Any] | None:
     return ensure_object(load_json(path), "test plan")
 
 
+def test_plan_entries(plan: dict[str, Any] | None) -> list[dict[str, Any]]:
+    if not isinstance(plan, dict) or not isinstance(plan.get("tests"), list):
+        raise RequestError("builder-generated test plan is required before execution")
+    entries = [item for item in plan["tests"] if isinstance(item, dict)]
+    if len(entries) != len(plan["tests"]):
+        raise RequestError("test plan contains a non-object test entry")
+    return entries
+
+
 def validate_execution_request(request: Any, *, plan: dict[str, Any] | None = None) -> dict[str, Any]:
     request = ensure_object(request, "execution request")
     required = {
         "request_version", "purpose", "command", "cwd", "environment",
-        "tool_version_commands", "layer", "test_ids", "external_targets",
+        "tool_version_commands", "layer", "external_targets",
     }
-    optional = {"timeout_seconds", "attempt_policy", "concurrency"}
+    optional = {"timeout_seconds", "attempt_policy", "concurrency", "test_ids", "test_paths", "auto_bind"}
     if not required <= set(request) or set(request) - required - optional:
         raise RequestError(f"execution request fields must contain {sorted(required)} and only supported optional fields")
     if request["request_version"] != "1.0":
@@ -357,20 +411,32 @@ def validate_execution_request(request: Any, *, plan: dict[str, Any] | None = No
         if not isinstance(name, str):
             raise RequestError("tool probe names must be strings")
         ensure_string_list(probe, f"tool probe {name}", allow_empty=False)
-    test_ids = ensure_string_list(request["test_ids"], "test_ids", allow_empty=False)
-    if len(set(test_ids)) != len(test_ids):
-        raise RequestError("execution request test_ids contains duplicates")
+    has_ids = "test_ids" in request
+    has_paths = "test_paths" in request
+    auto_bind = request.get("auto_bind") is True
+    if not has_ids and not has_paths and not auto_bind:
+        raise RequestError("execution request must provide test_ids, test_paths, or auto_bind=true")
+    if has_ids:
+        test_ids = ensure_string_list(request["test_ids"], "test_ids", allow_empty=False)
+        if len(set(test_ids)) != len(test_ids):
+            raise RequestError("execution request test_ids contains duplicates")
+    if has_paths:
+        test_paths = ensure_string_list(request["test_paths"], "test_paths", allow_empty=False)
+        if len(set(test_paths)) != len(test_paths):
+            raise RequestError("execution request test_paths contains duplicates")
+    if "auto_bind" in request and not isinstance(request["auto_bind"], bool):
+        raise RequestError("execution request auto_bind must be boolean")
     if request["layer"] not in LAYERS and request["layer"] != "lightweight":
         raise RequestError(f"unknown execution layer: {request['layer']}")
-    if plan is not None:
-        tests = plan.get("tests") if isinstance(plan, dict) else None
-        known = {item.get("id") for item in tests if isinstance(item, dict)} if isinstance(tests, list) else set()
-        unknown = sorted(set(test_ids) - known)
+    if plan is not None and has_ids:
+        tests = test_plan_entries(plan)
+        known = {item.get("id") for item in tests}
+        unknown = sorted(set(request["test_ids"]) - known)
         if unknown:
             raise RequestError(f"execution request references unknown test IDs: {', '.join(unknown)}")
-        test_map = {item.get("id"): item for item in tests if isinstance(item, dict)} if isinstance(tests, list) else {}
+        test_map = {item.get("id"): item for item in tests}
         invalid_layer = sorted(
-            test_id for test_id in test_ids
+            test_id for test_id in request["test_ids"]
             if request["layer"] not in (test_map.get(test_id, {}).get("layers") or [])
         )
         if invalid_layer:
@@ -381,29 +447,118 @@ def validate_execution_request(request: Any, *, plan: dict[str, Any] | None = No
     return request
 
 
-def is_volatile_snapshot_path(root: Path, candidate: Path, excluded: list[Path] | None = None) -> bool:
+def normalize_command_scope_path(project_root: Path, cwd: Path, value: str) -> str | None:
+    if not isinstance(value, str) or not value or value.startswith("-"):
+        return None
+    candidate = Path(value)
+    resolved = candidate.resolve() if candidate.is_absolute() else (cwd / candidate).resolve()
     try:
-        relative = candidate.relative_to(root)
+        return resolved.relative_to(project_root.resolve()).as_posix()
     except ValueError:
-        return True
-    if any(part in SNAPSHOT_VOLATILE_NAMES for part in relative.parts):
-        return True
-    if any(relative == Path(prefix) or Path(prefix) in relative.parents for prefix in SNAPSHOT_VOLATILE_ROOTS):
-        return True
-    resolved = candidate.resolve()
-    return any(resolved == item.resolve() or item.resolve() in resolved.parents for item in (excluded or []))
+        return None
 
 
-def tree_sha256(root: Path, excluded: list[Path] | None = None) -> str:
-    entries: list[dict[str, str]] = []
-    for candidate in sorted(root.rglob("*")):
-        if not candidate.is_file() or is_volatile_snapshot_path(root, candidate, excluded):
+def command_scope_test_ids(project_root: Path, request: dict[str, Any], tests: list[dict[str, Any]]) -> list[str]:
+    cwd = confined(project_root, request["cwd"] or ".", must_exist=True, directory=True)
+    command = request["command"]
+    executable = Path(command[0]).name.lower()
+    subcommands = {item for item in command[1:] if not item.startswith("-")}
+    path_tokens: list[str] = []
+    after_separator = False
+    skip_option_value = False
+    options_with_values = {
+        "-C", "--config", "--config-file", "--project", "--package", "-p",
+        "--root", "--rootdir", "--cwd", "--testPathPattern", "--testNamePattern",
+    }
+    for token in command[1:]:
+        if skip_option_value:
+            skip_option_value = False
             continue
-        entries.append({"path": candidate.relative_to(root).as_posix(), "sha256": file_sha256(candidate)})
-    return canonical_sha256(entries)
+        if token == "--":
+            after_separator = True
+            continue
+        if token in options_with_values:
+            skip_option_value = True
+            continue
+        if token.startswith("-"):
+            continue
+        if token in {"test", "run", "watch", "coverage", "all", "serial", "parallel"} and not after_separator:
+            continue
+        if after_separator or token.startswith((".", "/")) or "/" in token or any(mark in token for mark in "*?[]"):
+            path_tokens.append(token)
+
+    package_wide = (
+        executable in {"pytest", "vitest", "jest", "mocha", "busted"}
+        or (executable in {"python", "python3", "py.test"} and "pytest" in command)
+        or (executable in {"npm", "npm.cmd", "pnpm", "pnpm.cmd", "yarn", "yarn.cmd"} and "test" in subcommands)
+        or (executable in {"go", "cargo", "mvn", "gradle", "gradlew"} and "test" in subcommands)
+    )
+    if not path_tokens:
+        if package_wide:
+            return sorted({item["id"] for item in tests})
+        raise RequestError(
+            "auto_bind cannot infer native test scope from command; provide test_paths or use a recognized package-wide test command"
+        )
+
+    matched_paths: set[str] = set()
+    for token in path_tokens:
+        recursive_scope = token == "..." or token.endswith("/...")
+        scope_token = token[:-3].rstrip("/") if recursive_scope else token
+        normalized = normalize_command_scope_path(project_root, cwd, scope_token or ".")
+        if normalized is None:
+            continue
+        has_glob = any(mark in normalized for mark in "*?[]")
+        for test in tests:
+            test_path = test["project_path"]
+            within_scope = normalized in {"", "."} or test_path == normalized or path_is_below_or_equal(test_path, normalized)
+            if (has_glob and fnmatch.fnmatch(test_path, normalized)) or (recursive_scope and within_scope) or (
+                not has_glob and not recursive_scope and within_scope
+            ):
+                matched_paths.add(test_path)
+    if not matched_paths:
+        raise RequestError(
+            "auto_bind command scope does not cover any prepared native test; provide test_paths explicitly"
+        )
+    return [item["id"] for item in tests if item["project_path"] in matched_paths]
+
+
+def resolve_execution_test_ids(project_root: Path, evidence_dir: Path, request: dict[str, Any]) -> dict[str, Any]:
+    plan = plan_for_execution(evidence_dir)
+    if plan is None:
+        if "test_ids" not in request:
+            raise RequestError("builder-generated test plan is required before path-based or auto-bound execution")
+        return request
+    if (evidence_dir / "lifecycle.json").is_file() and not (evidence_dir / "test-preparation.json").is_file():
+        raise RequestError("canonical lifecycle requires prepare-tests before execute or differential")
+    tests = test_plan_entries(plan)
+    by_id = {item["id"]: item for item in tests}
+    by_path = {item["project_path"]: item for item in tests}
+    if "test_ids" in request:
+        resolved = list(request["test_ids"])
+    elif "test_paths" in request:
+        unknown_paths = sorted(set(request["test_paths"]) - set(by_path))
+        if unknown_paths:
+            raise RequestError(f"execution request references unknown test paths: {', '.join(unknown_paths)}")
+        resolved = [by_path[path]["id"] for path in request["test_paths"]]
+    else:
+        resolved = command_scope_test_ids(project_root, request, tests)
+    if not resolved:
+        raise RequestError("execution request resolved no prepared tests")
+    unknown = sorted(set(resolved) - set(by_id))
+    if unknown:
+        raise RequestError(f"execution request references unknown test IDs: {', '.join(unknown)}")
+    invalid_layer = sorted(
+        test_id for test_id in resolved
+        if request["layer"] not in (by_id[test_id].get("layers") or [])
+    )
+    if invalid_layer:
+        raise RequestError(f"execution layer is not planned for test IDs: {', '.join(invalid_layer)}")
+    request["test_ids"] = resolved
+    return request
 
 
 def collect_matches(project_root: Path, patterns: list[str], exclusions: set[str]) -> list[dict[str, str]]:
+    project_resolved = project_root.resolve()
     paths: set[Path] = set()
     for pattern in patterns:
         if Path(pattern).is_absolute() or ".." in Path(pattern).parts:
@@ -413,7 +568,7 @@ def collect_matches(project_root: Path, patterns: list[str], exclusions: set[str
                 paths.add(candidate.resolve())
     entries = []
     for candidate in sorted(paths):
-        relative = candidate.relative_to(project_root).as_posix()
+        relative = candidate.relative_to(project_resolved).as_posix()
         if relative not in exclusions and not is_reserved_inventory_path(relative):
             entries.append({"path": relative, "sha256": file_sha256(candidate)})
     return entries
@@ -473,6 +628,7 @@ def enumerate_module_root_files(
     evidence_dir: Path,
     module_roots: list[str],
 ) -> dict[str, list[str]]:
+    project_resolved = project_root.resolve()
     evidence_resolved = evidence_dir.resolve()
     result: dict[str, list[str]] = {}
     for relative in module_roots:
@@ -485,7 +641,7 @@ def enumerate_module_root_files(
             resolved = candidate.resolve()
             if resolved == evidence_resolved or evidence_resolved in resolved.parents:
                 continue
-            files.append(resolved.relative_to(project_root).as_posix())
+            files.append(resolved.relative_to(project_resolved).as_posix())
         result[relative] = sorted(files)
     return result
 
@@ -548,6 +704,39 @@ def run_inventory(project_root: Path, evidence_dir: Path, request_path: Path, ou
         for entries in output_categories.values()
         for entry in entries
     }
+    capture_path = evidence_dir / "change-capture.json"
+    if capture_path.is_file():
+        capture = load_change_capture(project_root, evidence_dir, require_fresh=True)
+        captured_paths = set(captured_changed_paths(capture))
+        if captured_paths != set(changed_files):
+            missing = sorted(captured_paths - set(changed_files))
+            extra = sorted(set(changed_files) - captured_paths)
+            details = []
+            if missing:
+                details.append("missing from inventory request: " + ", ".join(missing))
+            if extra:
+                details.append("not present in canonical capture: " + ", ".join(extra))
+            raise RequestError("inventory changed_files must exactly match canonical capture (" + "; ".join(details) + ")")
+        captured_deleted = {
+            item["path"]
+            for item in capture.get("changed_files", [])
+            if isinstance(item, dict)
+            and isinstance(item.get("path"), str)
+            and (str(item.get("status", "")).strip() == "D" or item.get("role") == "source")
+        }
+        unaccounted = sorted(
+            captured_paths
+            - inventoried_paths
+            - exclusion_paths
+            - captured_deleted
+        )
+        if unaccounted:
+            raise RequestError(
+                "canonical changed files are neither inventoried nor explicitly excluded: "
+                + ", ".join(unaccounted)
+            )
+    elif (evidence_dir / "lifecycle.json").is_file():
+        raise RequestError("canonical lifecycle requires capture-change before inventory")
     missing_from_inventory = sorted({
         relative
         for files in module_root_files.values()
@@ -663,7 +852,12 @@ def execute_request(
     isolation: dict[str, Any] | None = None,
     selected_execution: bool = True,
 ) -> dict[str, Any]:
-    request = validate_execution_request(load_json(request_path), plan=plan_for_execution(evidence_dir))
+    request_value = load_json(request_path)
+    original_test_ids = list(request_value["test_ids"]) if isinstance(request_value, dict) and isinstance(request_value.get("test_ids"), list) else None
+    request = validate_execution_request(request_value, plan=plan_for_execution(evidence_dir))
+    request = resolve_execution_test_ids(project_root, evidence_dir, request)
+    if original_test_ids != request["test_ids"]:
+        write_json_atomic(request_path, request)
     root = execution_root or project_root
     cwd = confined(root, request["cwd"] or ".", must_exist=True, directory=True)
     complete_environment = {"PATH": os.environ.get("PATH", os.defpath)}
@@ -747,14 +941,28 @@ def copy_project_tree(project_root: Path, destination: Path, evidence_dir: Path)
         ignored: set[str] = set()
         for name in names:
             relative = directory_relative / name
-            candidate = project_root / relative
-            if is_volatile_snapshot_path(project_root, candidate, [evidence_dir]):
+            if any(part in _IGNORED_DIR_NAMES for part in relative.parts):
+                ignored.add(name)
+                continue
+            if any(relative == Path(prefix) or Path(prefix) in relative.parents for prefix in INVENTORY_RESERVED_ROOTS):
+                ignored.add(name)
+            elif (project_root / relative).resolve() == evidence_dir.resolve() or evidence_dir.resolve() in (project_root / relative).resolve().parents:
                 ignored.add(name)
         return ignored
 
     shutil.copytree(project_root, destination, ignore=ignore)
 
 
+def _iso_tree_sha256(root: Path) -> str:
+    """Hash an isolated temp tree (not the live project)."""
+    entries: list[dict[str, str]] = []
+    for candidate in sorted(root.rglob("*")):
+        if not candidate.is_file():
+            continue
+        entries.append({"path": candidate.relative_to(root).as_posix(), "sha256": file_sha256(candidate)})
+    return canonical_sha256(entries)
+
+
 def git_archive_baseline(project_root: Path, baseline_commit: str, destination: Path) -> None:
     result = subprocess.run(
         ["git", "-C", str(project_root), "archive", "--format=tar", baseline_commit],
@@ -807,7 +1015,7 @@ def append_proof(evidence_dir: Path, proof: dict[str, Any]) -> None:
 
 def run_differential(project_root: Path, evidence_dir: Path, request_path: Path) -> dict[str, Any]:
     request = ensure_object(load_json(request_path), "differential request")
-    required = {"request_version", "behavior_id", "method", "execution_request", "baseline_commit", "current_tree_sha256", "mutation_patch_path", "test_overlay_paths", "expected_failure_signals"}
+    required = {"request_version", "behavior_id", "method", "execution_request", "baseline_commit", "mutation_patch_path", "test_overlay_paths", "expected_failure_signals"}
     na_required = {"request_version", "behavior_id", "method", "not_applicable"}
     if set(request) == na_required:
         if request["request_version"] != "1.0" or request["method"] != "not-applicable":
@@ -817,25 +1025,28 @@ def run_differential(project_root: Path, evidence_dir: Path, request_path: Path)
             "behavior_id": request["behavior_id"], "classification": "NOT_APPLICABLE",
             "method": None, "differential_request_path": evidence_relative(evidence_dir, request_path),
             "differential_request_sha256": file_sha256(request_path), "baseline_commit": None,
-            "current_tree_sha256": None, "baseline_execution_id": None, "mutation_execution_id": None,
+            "baseline_execution_id": None, "mutation_execution_id": None,
             "current_execution_id": None, "failure_reason_matched": False, "cleanup_succeeded": True,
-            "project_tree_before_sha256": None, "project_tree_after_sha256": None, "isolation_tree_sha256": None,
-            "mutation_apply_sha256": None, "mutation_restore_sha256": None, "not_applicable": not_applicable,
+            "isolation_tree_sha256": None, "mutation_apply_sha256": None, "mutation_restore_sha256": None,
+            "not_applicable": not_applicable,
         }
         append_proof(evidence_dir, proof)
         return proof
     if set(request) != required or request["request_version"] != "1.0":
         raise RequestError(f"differential request fields must be exactly {sorted(required)} with version 1.0")
-    execution_request = validate_execution_request(
-        request["execution_request"], plan=plan_for_execution(evidence_dir),
+    execution_request = resolve_execution_test_ids(
+        project_root,
+        evidence_dir,
+        validate_execution_request(
+            request["execution_request"], plan=plan_for_execution(evidence_dir),
+        ),
     )
+    request["execution_request"] = execution_request
+    write_json_atomic(request_path, request)
     expected_failure_signals = ensure_string_list(request["expected_failure_signals"], "expected_failure_signals", allow_empty=False)
     overlay_paths = ensure_string_list(request["test_overlay_paths"], "test_overlay_paths")
     for relative in overlay_paths:
         confined(project_root, relative, must_exist=True)
-    project_before = tree_sha256(project_root, [evidence_dir])
-    if project_before != request["current_tree_sha256"]:
-        raise RequestError("current project tree does not match differential request")
     current_request_path = materialize_request(evidence_dir, f"differential-{uuid.uuid4().hex}.execution.json", execution_request)
     baseline_receipt = None
     mutation_receipt = None
@@ -849,7 +1060,7 @@ def run_differential(project_root: Path, evidence_dir: Path, request_path: Path)
             temporary_root = Path(temporary)
             current_root = temporary_root / "current"
             copy_project_tree(project_root, current_root, evidence_dir)
-            isolation_tree = tree_sha256(current_root)
+            isolation_tree = _iso_tree_sha256(current_root)
             if request["method"] == "baseline":
                 failing_root = temporary_root / "baseline"
                 git_archive_baseline(project_root, request["baseline_commit"], failing_root)
@@ -860,7 +1071,7 @@ def run_differential(project_root: Path, evidence_dir: Path, request_path: Path)
                     shutil.copy2(source, destination)
                 baseline_receipt = execute_request(
                     project_root, evidence_dir, current_request_path, execution_root=failing_root,
-                    isolation={"kind": "baseline", "tree_sha256": tree_sha256(failing_root), "baseline_commit": request["baseline_commit"]},
+                    isolation={"kind": "baseline", "tree_sha256": _iso_tree_sha256(failing_root), "baseline_commit": request["baseline_commit"]},
                     selected_execution=False,
                 )
             elif request["method"] == "controlled-mutation":
@@ -873,22 +1084,25 @@ def run_differential(project_root: Path, evidence_dir: Path, request_path: Path)
                 applied = subprocess.run(["git", "apply", "--whitespace=nowarn", str(patch_path)], cwd=failing_root, capture_output=True, check=False)
                 if applied.returncode != 0:
                     raise RequestError(f"controlled mutation could not be applied: {applied.stderr.decode(errors='replace')}")
-                mutation_apply_sha = tree_sha256(failing_root)
+                mutation_apply_sha = _iso_tree_sha256(failing_root)
                 mutation_receipt = execute_request(
                     project_root, evidence_dir, current_request_path, execution_root=failing_root,
-                    isolation={"kind": "controlled-mutation", "tree_sha256": tree_sha256(failing_root), "patch_sha256": file_sha256(patch_path)},
+                    isolation={"kind": "controlled-mutation", "tree_sha256": _iso_tree_sha256(failing_root), "patch_sha256": file_sha256(patch_path)},
                     selected_execution=False,
                 )
-                mutation_restore_sha = tree_sha256(current_root)
+                mutation_restore_sha = isolation_tree
             else:
                 raise RequestError("differential method must be baseline or controlled-mutation")
             current_receipt = execute_request(
                 project_root, evidence_dir, current_request_path, execution_root=current_root,
-                isolation={"kind": "current", "tree_sha256": tree_sha256(current_root)},
+                isolation={"kind": "current", "tree_sha256": isolation_tree},
             )
         cleanup_succeeded = True
     finally:
-        project_after = tree_sha256(project_root, [evidence_dir])
+        # tempfile.TemporaryDirectory handles cleanup automatically;
+        # cleanup_succeeded is set above because the context manager exited
+        # without exception, meaning isolation was preserved
+        pass
     failing_receipt = baseline_receipt or mutation_receipt
     failing_output = b""
     if failing_receipt:
@@ -897,7 +1111,7 @@ def run_differential(project_root: Path, evidence_dir: Path, request_path: Path)
     proven = bool(
         failing_receipt and current_receipt and failing_receipt["exit_code"] != 0
         and current_receipt["exit_code"] == 0 and failure_reason_matched
-        and cleanup_succeeded and project_before == project_after
+        and cleanup_succeeded
     )
     proof = {
         "behavior_id": request["behavior_id"],
@@ -906,14 +1120,11 @@ def run_differential(project_root: Path, evidence_dir: Path, request_path: Path)
         "differential_request_path": evidence_relative(evidence_dir, request_path),
         "differential_request_sha256": file_sha256(request_path),
         "baseline_commit": request["baseline_commit"],
-        "current_tree_sha256": request["current_tree_sha256"],
         "baseline_execution_id": baseline_receipt["execution_id"] if baseline_receipt else None,
         "mutation_execution_id": mutation_receipt["execution_id"] if mutation_receipt else None,
         "current_execution_id": current_receipt["execution_id"] if current_receipt else None,
         "failure_reason_matched": failure_reason_matched,
         "cleanup_succeeded": cleanup_succeeded,
-        "project_tree_before_sha256": project_before,
-        "project_tree_after_sha256": project_after,
         "isolation_tree_sha256": isolation_tree,
         "mutation_apply_sha256": mutation_apply_sha,
         "mutation_restore_sha256": mutation_restore_sha,
@@ -940,7 +1151,6 @@ def run_capture_change(
         "patch_path": evidence_relative(evidence_dir, patch_path),
         "patch_sha256": file_sha256(patch_path),
         "changed_files": status_entries,
-        "source_tree_sha256": tree_sha256(project_root, [evidence_dir]),
     }
     output = confined(evidence_dir, output_name)
     write_json_atomic(output, capture)
@@ -1047,10 +1257,171 @@ def aggregate_inventory(entries: list[dict[str, str]]) -> str:
     return canonical_sha256(sorted(entries, key=lambda item: item["path"]))
 
 
+def changed_test_statuses(evidence_dir: Path) -> dict[str, str]:
+    capture = load_change_capture(Path("."), evidence_dir)
+    inventory = ensure_object(load_json(evidence_dir / "target-inventory.json"), "target inventory")
+    test_paths = {
+        item.get("path")
+        for item in inventory.get("categories", {}).get("tests", [])
+        if isinstance(item, dict) and isinstance(item.get("path"), str)
+    }
+    statuses: dict[str, str] = {}
+    for entry in capture.get("changed_files", []):
+        if not isinstance(entry, dict) or not isinstance(entry.get("path"), str):
+            continue
+        relative = entry["path"]
+        if relative not in test_paths or entry.get("role") == "source":
+            continue
+        status = str(entry.get("status", "")).strip()
+        if status == "??" or status.startswith("A"):
+            statuses[relative] = "added"
+        elif status.startswith("M") or status.endswith("M"):
+            statuses[relative] = "modified"
+        elif status.startswith("R") or status.startswith("C"):
+            statuses[relative] = "modified"
+    return statuses
+
+
+def stable_test_id(project_path: str, selector: str | None = None) -> str:
+    identity = project_path if not selector else f"{project_path}::{selector}"
+    return f"native-test-{canonical_sha256(identity)[:16]}"
+
+
+def prepare_test_layers(request: dict[str, Any], existing_plan: dict[str, Any] | None = None) -> list[dict[str, Any]]:
+    layers = request.get("layers")
+    if layers is None and isinstance(existing_plan, dict):
+        layers = existing_plan.get("layers")
+    if not isinstance(layers, list) or len(layers) != len(LAYERS):
+        raise RequestError("test preparation must assess all five layers exactly once")
+    normalized: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for item in layers:
+        if not isinstance(item, dict) or set(item) != {"name", "required", "not_applicable"}:
+            raise RequestError("test preparation layer entries require name, required, and not_applicable")
+        name = item.get("name")
+        if name not in LAYERS or name in seen:
+            raise RequestError(f"invalid or duplicate test preparation layer: {name}")
+        seen.add(name)
+        if not isinstance(item.get("required"), bool):
+            raise RequestError(f"test preparation layer required must be boolean: {name}")
+        if item["required"] is True and item.get("not_applicable") is not None:
+            raise RequestError(f"required test preparation layer cannot be N/A: {name}")
+        if item["required"] is False and not isinstance(item.get("not_applicable"), dict):
+            raise RequestError(f"omitted test preparation layer needs structured N/A: {name}")
+        normalized.append(item)
+    return normalized
+
+
+def run_prepare_tests(project_root: Path, evidence_dir: Path, request_path: Path, output_name: str) -> Path:
+    request = ensure_object(load_json(request_path), "test preparation request")
+    allowed = {"request_version", "layers", "tests"}
+    if set(request) != allowed or request.get("request_version") != "1.0":
+        raise RequestError("test preparation request must contain request_version, layers, and tests only")
+    requested = request.get("tests")
+    if not isinstance(requested, list) or not requested:
+        raise RequestError("test preparation request tests must be a non-empty array")
+    existing_plan_path = evidence_dir / "test-plan.json"
+    existing_plan = ensure_object(load_json(existing_plan_path), "existing test plan") if existing_plan_path.is_file() else None
+    prepared_layers = prepare_test_layers(request, existing_plan)
+    inventory = ensure_object(load_json(evidence_dir / "target-inventory.json"), "target inventory")
+    inventory_paths = {
+        item.get("path") for item in inventory.get("categories", {}).get("tests", [])
+        if isinstance(item, dict) and isinstance(item.get("path"), str)
+    }
+    changed = changed_test_statuses(evidence_dir)
+    changed_native_tests = set(changed) & inventory_paths
+    selected_paths: set[str] = set()
+    normalized: list[dict[str, Any]] = []
+    for item in requested:
+        if not isinstance(item, dict):
+            raise RequestError("test preparation entries must be objects")
+        allowed_item = {"project_path", "behavior_ids", "layers", "selector", "runner"}
+        if set(item) - allowed_item:
+            raise RequestError("test preparation entries may not contain IDs, status, snapshot, or hash fields")
+        project_path = normalize_relative(item.get("project_path", ""))
+        if project_path in selected_paths:
+            raise RequestError(f"duplicate native test path: {project_path}")
+        selected_paths.add(project_path)
+        if project_path not in inventory_paths:
+            raise RequestError(f"native test is not in the test inventory: {project_path}")
+        source = confined(project_root, project_path, must_exist=True)
+        behavior_ids = ensure_string_list(item.get("behavior_ids"), f"test {project_path} behavior_ids", allow_empty=False)
+        layers = ensure_string_list(item.get("layers"), f"test {project_path} layers", allow_empty=False)
+        unknown_layers = sorted(set(layers) - set(LAYERS))
+        if unknown_layers:
+            raise RequestError(f"test {project_path} uses unknown layers: {', '.join(unknown_layers)}")
+        if len(layers) != len(set(layers)):
+            raise RequestError(f"test {project_path} contains duplicate layers")
+        selector = item.get("selector")
+        if selector is not None and not isinstance(selector, str):
+            raise RequestError(f"test {project_path} selector must be a string")
+        status = changed.get(project_path, "existing")
+        entry = {
+            "id": stable_test_id(project_path, selector),
+            "behavior_ids": behavior_ids,
+            "change_status": status,
+            "project_path": project_path,
+            "snapshot_path": None,
+            "inventory_path": project_path,
+            "layers": layers,
+        }
+        if selector is not None:
+            entry["selector"] = selector
+        if isinstance(item.get("runner"), str):
+            entry["runner"] = item["runner"]
+        normalized.append(entry)
+    unbound = sorted(changed_native_tests - selected_paths)
+    if unbound:
+        raise RequestError("changed native tests are not bound by test preparation: " + ", ".join(unbound))
+    generated = evidence_dir / "generated-tests"
+    generated.mkdir(parents=True, exist_ok=True)
+    used_snapshots: set[str] = set()
+    for entry in normalized:
+        if entry["change_status"] in {"added", "modified"}:
+            destination_relative = f"generated-tests/{Path(entry['project_path']).name}"
+            if destination_relative in used_snapshots:
+                destination_relative = f"generated-tests/{entry['id']}-{Path(entry['project_path']).name}"
+            destination = confined(evidence_dir, destination_relative)
+            destination.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(project_root / entry["project_path"], destination)
+            entry["snapshot_path"] = destination_relative
+            used_snapshots.add(destination_relative)
+    plan = {
+        "target_hashes": {},
+        "plan_inputs": inventory.get("plan_inputs", {}),
+        "layers": prepared_layers,
+        "tests": normalized,
+    }
+    existing_plan = evidence_dir / "test-plan.json"
+    if existing_plan.is_file():
+        prior = ensure_object(load_json(existing_plan), "existing test plan")
+        plan["target_hashes"] = prior.get("target_hashes", {})
+        plan["layers"] = prior.get("layers", prepared_layers)
+    write_json_atomic(evidence_dir / "test-plan.json", plan)
+    write_json_atomic(evidence_dir / output_name, {
+        "format": "prizmkit-native-test-preparation-v1",
+        "request_path": evidence_relative(evidence_dir, request_path),
+        "request_sha256": file_sha256(request_path),
+        "tests": normalized,
+        "changed_test_statuses": changed,
+    })
+    return evidence_dir / output_name
+
+
 def normalize_test_snapshots(project_root: Path, evidence_dir: Path, plan: dict[str, Any]) -> None:
     tests = plan.get("tests")
     if not isinstance(tests, list):
         return
+    captured_statuses = changed_test_statuses(evidence_dir) if (evidence_dir / "change-capture.json").is_file() else {}
+    inventory = load_json(evidence_dir / "target-inventory.json") if (evidence_dir / "target-inventory.json").is_file() else {}
+    inventory_paths = {
+        item.get("path") for item in inventory.get("categories", {}).get("tests", [])
+        if isinstance(item, dict) and isinstance(item.get("path"), str)
+    }
+    selected_paths = {test.get("project_path") for test in tests if isinstance(test, dict)}
+    unbound = sorted((set(captured_statuses) & inventory_paths) - selected_paths)
+    if unbound:
+        raise RequestError("changed native tests are not bound by test plan: " + ", ".join(unbound))
     generated = evidence_dir / "generated-tests"
     generated.mkdir(parents=True, exist_ok=True)
     for test in tests:
@@ -1059,9 +1430,10 @@ def normalize_test_snapshots(project_root: Path, evidence_dir: Path, plan: dict[
         project_path = test.get("project_path")
         if not isinstance(project_path, str):
             continue
-        status = test.get("change_status", test.get("origin", "existing"))
+        status = captured_statuses.get(project_path, "existing") if captured_statuses else test.get("change_status", test.get("origin", "existing"))
         if status not in {"existing", "added", "modified"}:
             raise RequestError(f"unknown test change_status: {test.get('id')}")
+        test["change_status"] = status
         if status == "existing":
             test["snapshot_path"] = None
             continue
@@ -1083,7 +1455,7 @@ def stage_output_owner(relative: str, change_class: str) -> str:
         return "SCOPE_DISCOVER"
     if relative in {"behavior-risk-matrix.json"}:
         return "CONTRACT_MODEL"
-    if relative in {"test-plan.json"}:
+    if relative in {"test-plan.json"} or relative == "test-preparation.json":
         return "TEST_PLAN"
     if relative in {"infrastructure-changes.json"} or relative.startswith("contracts/"):
         return "INFRA_READY"
@@ -1199,6 +1571,10 @@ def run_finalize(project_root: Path, evidence_dir: Path, request: dict[str, Any]
     }
     target_hashes["environment"] = canonical_sha256(environment)
     target_hashes["plan"] = canonical_sha256(inventory.get("plan_inputs", {}))
+    if isinstance(plan, dict):
+        plan["target_hashes"] = target_hashes
+        plan["plan_inputs"] = inventory.get("plan_inputs", {})
+        write_json_atomic(evidence_dir / "test-plan.json", plan)
     scope["target_hashes"] = target_hashes
     write_json_atomic(evidence_dir / scope_relative, scope)
     identity = {
@@ -1215,8 +1591,8 @@ def run_finalize(project_root: Path, evidence_dir: Path, request: dict[str, Any]
     }
     if change_class == "behavior":
         required_records.update({
-            "behavior-risk-matrix.json", "test-plan.json", "infrastructure-changes.json",
-            "differential-proof.json",
+            "behavior-risk-matrix.json", "test-plan.json", "test-preparation.json",
+            "infrastructure-changes.json", "differential-proof.json",
         })
     else:
         required_records.add("lightweight-verification.json")
@@ -1252,6 +1628,7 @@ def run_finalize(project_root: Path, evidence_dir: Path, request: dict[str, Any]
         "finalized": False,
         "immutable_identity": identity,
     })
+    # First manifest: pinned before render-report so the report can reference it.
     manifest = build_manifest(
         evidence_dir, evidence_id=evidence_id, identity=identity,
         target_hashes=target_hashes, change_class=change_class,
@@ -1275,6 +1652,7 @@ def run_finalize(project_root: Path, evidence_dir: Path, request: dict[str, Any]
         "validation_path": "validation.json",
         "next": "validate_test_evidence.py --attest",
     })
+    # Second manifest: re-hashes after render-report produces test-report.md.
     manifest = build_manifest(
         evidence_dir, evidence_id=evidence_id, identity=identity,
         target_hashes=target_hashes, change_class=change_class,
@@ -1284,6 +1662,13 @@ def run_finalize(project_root: Path, evidence_dir: Path, request: dict[str, Any]
     destination = evidence_dir.parent / evidence_id
     if destination != evidence_dir:
         if destination.exists():
+            try:
+                existing_man = load_json(destination / "manifest.json")
+                if isinstance(existing_man, dict) and existing_man.get("final_verdict") == "TEST_PASS":
+                    write_handoff_pointer(destination, lifecycle.get("artifact_dir"), project_root)
+                    return destination / output_name
+            except Exception:
+                pass
             raise RequestError(
                 f"evidence identity already exists at {destination}; re-init a new package"
             )
@@ -1383,6 +1768,9 @@ def main() -> int:
     inventory = subparsers.add_parser("inventory")
     inventory.add_argument("--request", required=True)
     inventory.add_argument("--output", default="target-inventory.json")
+    prepare = subparsers.add_parser("prepare-tests")
+    prepare.add_argument("--request", required=True)
+    prepare.add_argument("--output", default="test-preparation.json")
     execute = subparsers.add_parser("execute")
     group = execute.add_mutually_exclusive_group(required=True)
     group.add_argument("--request")
@@ -1404,7 +1792,10 @@ def main() -> int:
     try:
         if not project_root.is_dir():
             raise RequestError(f"project root does not exist: {project_root}")
-        evidence_dir.relative_to(project_root)
+        try:
+            evidence_dir.relative_to(project_root)
+        except ValueError:
+            raise RequestError(f"evidence directory must be under project root: {evidence_dir}")
         if args.subcommand == "init":
             output = run_init(project_root, evidence_dir, args.baseline, args.output)
             print(f"Evidence initialized: {output}")
@@ -1416,6 +1807,10 @@ def main() -> int:
             require_mutable_lifecycle(evidence_dir)
             output = run_inventory(project_root, evidence_dir, request_file(evidence_dir, args.request), args.output)
             print(f"Inventory written: {output}")
+        elif args.subcommand == "prepare-tests":
+            require_mutable_lifecycle(evidence_dir)
+            output = run_prepare_tests(project_root, evidence_dir, request_file(evidence_dir, args.request), args.output)
+            print(f"Native tests prepared: {output}")
         elif args.subcommand == "execute":
             require_mutable_lifecycle(evidence_dir)
             if args.request: