prizmkit 1.1.131 → 1.1.135

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

@@ -2,10 +2,15 @@
 """Build runner-generated PrizmKit test evidence from schema-shaped requests.
 
 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
+  python3 build_test_evidence.py --project-root ROOT --evidence-dir DIR finalize --request REQUEST
+  python3 build_test_evidence.py --project-root ROOT --evidence-dir DIR render-report
   python3 build_test_evidence.py --project-root ROOT --evidence-dir DIR resume --manifest MANIFEST --inventory INVENTORY
 
 Only locator arguments and evidence mechanics are fixed. Test commands, working directories,
@@ -17,6 +22,7 @@ from __future__ import annotations
 
 import argparse
 import datetime as dt
+import fnmatch
 import hashlib
 import json
 import os
@@ -35,13 +41,23 @@ STAGES = [
     "EVIDENCE_VALIDATE",
 ]
 CATEGORIES = ("source", "tests", "contracts", "lockfiles")
+LAYERS = (
+    "focused", "module-component", "contract-integration",
+    "affected-module-regression", "regression-ring",
+)
 BLOCKED_EXTERNAL_CLASSES = {"production", "unknown"}
 SNAPSHOT_VOLATILE_ROOTS = (
     ".prizmkit/state",
     ".prizmkit/test/evidence",
+    ".prizmkit/" + "dev-" + "pipeline",
     ".claude/worktrees",
+    ".agents/worktrees",
+    ".codebuddy/worktrees",
+    ".codex/worktrees",
 )
-SNAPSHOT_VOLATILE_NAMES = {".git", "__pycache__"}
+SNAPSHOT_VOLATILE_NAMES = {".git", "__pycache__", ".pytest_cache", ".mypy_cache"}
+INVENTORY_RESERVED_ROOTS = SNAPSHOT_VOLATILE_ROOTS
+FINAL_RECORDS = {"manifest.json", "validation.json", "verdict.json", "test-report.md"}
 
 
 class RequestError(Exception):
@@ -127,6 +143,167 @@ def ensure_string_list(value: Any, label: str, *, allow_empty: bool = True) -> l
     return value
 
 
+def normalize_relative(value: str) -> str:
+    normalized = Path(value).as_posix()
+    if normalized == "." or normalized.startswith("../") or "/../" in normalized:
+        raise RequestError(f"path is not project-relative: {value}")
+    return normalized
+
+
+def is_reserved_inventory_path(relative: str) -> bool:
+    path = Path(relative)
+    if any(part in SNAPSHOT_VOLATILE_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)
+
+
+def project_git(project_root: Path, *args: str, check: bool = False) -> subprocess.CompletedProcess[bytes]:
+    result = subprocess.run(
+        ["git", "-C", str(project_root), *args],
+        capture_output=True,
+        check=False,
+    )
+    if check and result.returncode != 0:
+        raise RequestError(f"git {' '.join(args)} failed: {result.stderr.decode(errors='replace')}")
+    return result
+
+
+def git_baseline(project_root: Path, requested: str | None = None) -> str:
+    baseline = requested or "HEAD"
+    result = project_git(project_root, "rev-parse", "--verify", baseline)
+    if result.returncode != 0:
+        raise RequestError(f"baseline commit is not resolvable: {baseline}")
+    return result.stdout.decode().strip()
+
+
+def git_status_entries(project_root: Path) -> list[dict[str, Any]]:
+    result = project_git(project_root, "status", "--porcelain=v1", "-z", "--untracked-files=all", check=True)
+    raw = result.stdout
+    entries: list[dict[str, Any]] = []
+    tokens = raw.split(b"\0")
+    index = 0
+    while index < len(tokens):
+        token = tokens[index]
+        index += 1
+        if not token:
+            continue
+        status = token[:2].decode(errors="replace")
+        path = token[3:].decode(errors="replace")
+        old_path = None
+        if "R" in status or "C" in status:
+            if index >= len(tokens):
+                raise RequestError("git status returned an incomplete rename/copy record")
+            old_path = tokens[index].decode(errors="replace")
+            index += 1
+        relative = normalize_relative(path)
+        if not is_reserved_inventory_path(relative):
+            record: dict[str, Any] = {"path": relative, "status": status, "old_path": old_path}
+            entries.append(record)
+        if old_path is not None:
+            old_relative = normalize_relative(old_path)
+            if not is_reserved_inventory_path(old_relative):
+                entries.append({"path": old_relative, "status": status, "old_path": old_relative, "role": "source"})
+    return sorted(entries, key=lambda item: (item["path"], item.get("old_path") or ""))
+
+
+def git_diff_entries(project_root: Path, baseline: str) -> list[dict[str, Any]]:
+    result = project_git(
+        project_root, "diff", "--name-status", "-z", "--find-renames", "--find-copies",
+        baseline, "--", ".",
+        ":!.prizmkit/state/**", ":!.prizmkit/test/evidence/**", ":!.prizmkit/" + "dev-" + "pipeline/**",
+        ":!.claude/worktrees/**", ":!.agents/worktrees/**", ":!.codebuddy/worktrees/**", ":!.codex/worktrees/**",
+        check=True,
+    )
+    tokens = result.stdout.split(b"\0")
+    entries: list[dict[str, Any]] = []
+    index = 0
+    while index < len(tokens):
+        status_token = tokens[index].decode(errors="replace")
+        index += 1
+        if not status_token:
+            continue
+        if index >= len(tokens):
+            raise RequestError("git diff returned an incomplete changed-file record")
+        first = normalize_relative(tokens[index].decode(errors="replace"))
+        index += 1
+        status = status_token[0]
+        old_path = None
+        if status in {"R", "C"}:
+            if index >= len(tokens):
+                raise RequestError("git diff returned an incomplete rename/copy record")
+            old_path = first
+            first = normalize_relative(tokens[index].decode(errors="replace"))
+            index += 1
+        if not is_reserved_inventory_path(first):
+            entries.append({"path": first, "status": status, "old_path": old_path})
+        if old_path and not is_reserved_inventory_path(old_path):
+            entries.append({"path": old_path, "status": status, "old_path": old_path, "role": "source"})
+    return entries
+
+
+def merge_changed_file_entries(
+    baseline_entries: list[dict[str, Any]],
+    working_entries: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+    merged: dict[tuple[str, str | None, str | None], dict[str, Any]] = {}
+    for entry in baseline_entries + working_entries:
+        key = (entry["path"], entry.get("old_path"), entry.get("role"))
+        existing = merged.get(key)
+        if existing is None:
+            merged[key] = dict(entry)
+            continue
+        statuses = {existing.get("status", "").strip(), entry.get("status", "").strip()}
+        if "D" in statuses:
+            existing["status"] = "D"
+        elif "R" in statuses:
+            existing["status"] = "R"
+        elif "C" in statuses:
+            existing["status"] = "C"
+        elif statuses:
+            existing["status"] = "M"
+    return sorted(merged.values(), key=lambda item: (item["path"], item.get("old_path") or "", item.get("role") or ""))
+
+
+def canonical_change_patch(project_root: Path, baseline: str) -> tuple[bytes, list[dict[str, Any]]]:
+    status_entries = git_status_entries(project_root)
+    baseline_entries = git_diff_entries(project_root, baseline)
+    status_entries = merge_changed_file_entries(baseline_entries, status_entries)
+    tracked = project_git(
+        project_root, "diff", "--binary", "--full-index", "--find-renames", "--find-copies",
+        baseline, "--", ".",
+        ":!.prizmkit/state/**", ":!.prizmkit/test/evidence/**", ":!.prizmkit/" + "dev-" + "pipeline/**",
+        ":!.claude/worktrees/**", ":!.agents/worktrees/**", ":!.codebuddy/worktrees/**", ":!.codex/worktrees/**",
+    )
+    if tracked.returncode != 0:
+        raise RequestError(f"cannot capture git diff: {tracked.stderr.decode(errors='replace')}")
+    chunks = [tracked.stdout]
+    untracked = [
+        item["path"] for item in status_entries
+        if item["status"].strip() == "??" and item.get("old_path") is None
+    ]
+    for relative in sorted(untracked):
+        candidate = confined(project_root, relative, must_exist=True)
+        if candidate.is_file():
+            result = subprocess.run(
+                ["git", "diff", "--no-index", "--binary", "/dev/null", "--", relative],
+                cwd=project_root,
+                capture_output=True,
+                check=False,
+            )
+            if result.returncode not in (0, 1):
+                raise RequestError(f"cannot capture untracked file: {relative}")
+            chunks.append(result.stdout)
+    patch = b"".join(chunk for chunk in chunks if chunk)
+    return patch, status_entries
+
+
+def write_text_atomic(path: Path, value: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_name(f".{path.name}.{uuid.uuid4().hex}.tmp")
+    temporary.write_text(value, encoding="utf-8")
+    os.replace(temporary, path)
+
+
 def validate_external_targets(value: Any) -> list[dict[str, Any]]:
     if not isinstance(value, list):
         raise RequestError("external_targets must be an array")
@@ -151,13 +328,73 @@ def validate_external_targets(value: Any) -> list[dict[str, Any]]:
     return value
 
 
-def validate_execution_request(request: Any) -> dict[str, Any]:
+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"]
+            or tree_sha256(project_root, [evidence_dir]) != capture.get("source_tree_sha256")
+        ):
+            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():
+        return 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":
@@ -175,13 +412,152 @@ def validate_execution_request(request: Any) -> dict[str, Any]:
         if not isinstance(name, str):
             raise RequestError("tool probe names must be strings")
         ensure_string_list(probe, f"tool probe {name}", allow_empty=False)
-    ensure_string_list(request["test_ids"], "test_ids")
+    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 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}
+        invalid_layer = sorted(
+            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:
+            raise RequestError(f"execution layer is not planned for test IDs: {', '.join(invalid_layer)}")
     validate_external_targets(request["external_targets"])
     if "timeout_seconds" in request and (isinstance(request["timeout_seconds"], bool) or not isinstance(request["timeout_seconds"], (int, float)) or request["timeout_seconds"] <= 0):
         raise RequestError("timeout_seconds must be a positive number")
     return request
 
 
+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:
+        return resolved.relative_to(project_root.resolve()).as_posix()
+    except ValueError:
+        return None
+
+
+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
+        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 is_volatile_snapshot_path(root: Path, candidate: Path, excluded: list[Path] | None = None) -> bool:
     try:
         relative = candidate.relative_to(root)
@@ -205,6 +581,7 @@ def tree_sha256(root: Path, excluded: list[Path] | None = None) -> str:
 
 
 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:
@@ -214,17 +591,67 @@ 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()
-        if relative not in exclusions:
+        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
 
 
+def validate_category_disjointness(output_categories: dict[str, list[dict[str, str]]]) -> None:
+    membership: dict[str, str] = {}
+    for category, entries in output_categories.items():
+        for entry in entries:
+            path = entry["path"]
+            previous = membership.get(path)
+            if previous is not None:
+                raise RequestError(f"inventory path appears in multiple categories: {path} ({previous}, {category})")
+            membership[path] = category
+
+
+def validate_module_root_request(
+    project_root: Path,
+    evidence_dir: Path,
+    module_roots: list[Any],
+    changed_files: list[str],
+) -> tuple[list[str], dict[str, list[str]], dict[str, list[str]]]:
+    normalized_roots: list[str] = []
+    explicit_changed: dict[str, list[str]] = {}
+    for item in module_roots:
+        if isinstance(item, str):
+            relative = normalize_relative(item)
+            changed_set: list[str] = []
+        elif isinstance(item, dict) and set(item) <= {"path", "changed_files"} and isinstance(item.get("path"), str):
+            relative = normalize_relative(item["path"])
+            changed_set = ensure_string_list(item.get("changed_files", []), f"module root {relative} changed_files")
+        else:
+            raise RequestError("module_roots entries must be paths or {path, changed_files} objects")
+        confined(project_root, relative, must_exist=True)
+        if relative in normalized_roots:
+            raise RequestError(f"duplicate module root: {relative}")
+        for changed in changed_set:
+            changed = normalize_relative(changed)
+            if not path_is_below_or_equal(changed, relative):
+                raise RequestError(f"module root changed file lies outside root: {changed}")
+            if changed not in changed_files:
+                raise RequestError(f"module root changed file is not in changed_files: {changed}")
+        normalized_roots.append(relative)
+        explicit_changed[relative] = sorted(changed_set)
+    enumerated = enumerate_module_root_files(project_root, evidence_dir, normalized_roots)
+    return normalized_roots, explicit_changed, enumerated
+
+
+def path_is_below_or_equal(path: str, root: str) -> bool:
+    normalized_path = Path(path)
+    normalized_root = Path(root)
+    return normalized_path == normalized_root or normalized_root in normalized_path.parents
+
+
 def enumerate_module_root_files(
     project_root: Path,
     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:
@@ -237,7 +664,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
 
@@ -257,28 +684,82 @@ def run_inventory(project_root: Path, evidence_dir: Path, request_path: Path, ou
     for exclusion in exclusions:
         if not isinstance(exclusion, dict) or set(exclusion) != {"path", "reason", "evidence"}:
             raise RequestError("each inventory exclusion requires path, reason, and evidence")
-        confined(project_root, exclusion["path"])
+        relative = normalize_relative(exclusion["path"])
+        if is_reserved_inventory_path(relative):
+            raise RequestError(f"reserved inventory path must be automatically excluded: {relative}")
+        confined(project_root, relative)
         if not isinstance(exclusion["reason"], str) or len(exclusion["reason"].strip()) < 8:
             raise RequestError("inventory exclusion reason is too short")
         if not isinstance(exclusion["evidence"], list) or not exclusion["evidence"]:
             raise RequestError("inventory exclusion lacks evidence")
-        exclusion_paths.add(Path(exclusion["path"]).as_posix())
-    changed_files = ensure_string_list(request["changed_files"], "changed_files", allow_empty=False)
-    module_roots = ensure_string_list(request["module_roots"], "module_roots", allow_empty=False)
+        exclusion_paths.add(relative)
+    changed_files = sorted({normalize_relative(item) for item in ensure_string_list(request["changed_files"], "changed_files", allow_empty=False)})
+    if len(changed_files) != len(request["changed_files"]):
+        raise RequestError("changed_files contains duplicates")
+    capture_path = evidence_dir / "change-capture.json"
+    captured_deleted: set[str] = set()
+    if capture_path.is_file():
+        capture = ensure_object(load_json(capture_path), "change capture")
+        for entry in capture.get("changed_files", []):
+            if isinstance(entry, dict) and entry.get("status", "").strip() == "D":
+                captured_deleted.add(entry.get("path"))
+            if isinstance(entry, dict) and entry.get("role") == "source":
+                captured_deleted.add(entry.get("path"))
     for relative in changed_files:
-        confined(project_root, relative, must_exist=relative not in exclusion_paths)
-    for relative in module_roots:
-        confined(project_root, relative, must_exist=True)
+        confined(
+            project_root,
+            relative,
+            must_exist=relative not in exclusion_paths and relative not in captured_deleted,
+        )
+    raw_module_roots = request["module_roots"]
+    if not isinstance(raw_module_roots, list) or not raw_module_roots:
+        raise RequestError("module_roots must be a non-empty array")
+    module_roots, explicit_changed, module_root_files = validate_module_root_request(
+        project_root, evidence_dir, raw_module_roots, changed_files,
+    )
     output_categories = {
         name: collect_matches(project_root, ensure_string_list(categories[name], f"category {name}"), exclusion_paths)
         for name in CATEGORIES
     }
+    validate_category_disjointness(output_categories)
     inventoried_paths = {
         entry["path"]
         for entries in output_categories.values()
         for entry in entries
     }
-    module_root_files = enumerate_module_root_files(project_root, evidence_dir, module_roots)
+    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()
@@ -290,6 +771,9 @@ def run_inventory(project_root: Path, evidence_dir: Path, request_path: Path, ou
             "module root contains files that are neither inventoried nor excluded: "
             + ", ".join(missing_from_inventory[:20])
         )
+    for root, changed_set in explicit_changed.items():
+        if changed_set and not set(changed_set) <= set(module_root_files[root]):
+            raise RequestError(f"module root changed_files contains a path outside enumerated root: {root}")
     output = {
         "inventory_request_path": evidence_relative(evidence_dir, request_path),
         "inventory_request_sha256": file_sha256(request_path),
@@ -297,6 +781,7 @@ def run_inventory(project_root: Path, evidence_dir: Path, request_path: Path, ou
         "changed_files": changed_files,
         "module_roots": module_roots,
         "module_root_files": module_root_files,
+        "module_root_changed_files": explicit_changed,
         "exclusions": sorted(exclusion_paths),
         "discovery_evidence": request["discovery_evidence"],
         "plan_inputs": ensure_object(request["plan_inputs"], "plan_inputs"),
@@ -390,7 +875,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))
+    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)}
@@ -501,12 +991,67 @@ def materialize_request(evidence_dir: Path, name: str, request: dict[str, Any])
     return path
 
 
+def validate_not_applicable(value: Any) -> dict[str, Any]:
+    value = ensure_object(value, "differential N/A decision")
+    required = {"reason", "rationale", "evidence", "considered_signals", "conflicts"}
+    if set(value) != required:
+        raise RequestError(f"differential N/A fields must be exactly {sorted(required)}")
+    if value["reason"] not in {"new-behavior", "textual-contract"}:
+        raise RequestError("differential N/A reason must be new-behavior or textual-contract")
+    if not isinstance(value["rationale"], str) or len(value["rationale"].strip()) < 16:
+        raise RequestError("differential N/A rationale is too short")
+    ensure_string_list(value["evidence"], "differential N/A evidence", allow_empty=False)
+    ensure_string_list(value["considered_signals"], "differential N/A considered_signals", allow_empty=False)
+    if not isinstance(value["conflicts"], list):
+        raise RequestError("differential N/A conflicts must be an array")
+    if value["reason"] == "new-behavior" and "no stable pre-change observable" not in value["rationale"].lower():
+        raise RequestError("new-behavior differential N/A must explain that no stable pre-change observable exists")
+    if value["reason"] == "textual-contract" and "textual" not in value["rationale"].lower():
+        raise RequestError("textual-contract differential N/A must explain why behavior is textual")
+    return value
+
+
+def append_proof(evidence_dir: Path, proof: dict[str, Any]) -> None:
+    proof_path = evidence_dir / "differential-proof.json"
+    proof_record = load_json(proof_path) if proof_path.exists() else {"proofs": []}
+    if not isinstance(proof_record, dict) or not isinstance(proof_record.get("proofs"), list):
+        raise RequestError("differential-proof.json has invalid append target")
+    if any(item.get("behavior_id") == proof.get("behavior_id") for item in proof_record["proofs"] if isinstance(item, dict)):
+        raise RequestError(f"duplicate differential proof: {proof.get('behavior_id')}")
+    proof_record["proofs"].append(proof)
+    write_json_atomic(proof_path, proof_record)
+
+
 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"}
+    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":
+            raise RequestError("invalid differential N/A request")
+        not_applicable = validate_not_applicable(request["not_applicable"])
+        proof = {
+            "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,
+            "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,
+        }
+        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"])
+    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:
@@ -597,15 +1142,545 @@ def run_differential(project_root: Path, evidence_dir: Path, request_path: Path)
         "mutation_restore_sha256": mutation_restore_sha,
         "not_applicable": None,
     }
-    proof_path = evidence_dir / "differential-proof.json"
-    proof_record = load_json(proof_path) if proof_path.exists() else {"proofs": []}
-    if not isinstance(proof_record, dict) or not isinstance(proof_record.get("proofs"), list):
-        raise RequestError("differential-proof.json has invalid append target")
-    proof_record["proofs"].append(proof)
-    write_json_atomic(proof_path, proof_record)
+    append_proof(evidence_dir, proof)
     return proof
 
 
+def run_capture_change(
+    project_root: Path,
+    evidence_dir: Path,
+    baseline: str | None,
+    output_name: str,
+) -> Path:
+    resolved_baseline = git_baseline(project_root, baseline)
+    patch, status_entries = canonical_change_patch(project_root, resolved_baseline)
+    patch_path = confined(evidence_dir, "source-change.patch")
+    patch_path.parent.mkdir(parents=True, exist_ok=True)
+    patch_path.write_bytes(patch)
+    capture = {
+        "capture_format": "prizmkit-canonical-change-v1",
+        "baseline_commit": resolved_baseline,
+        "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)
+    return output
+
+
+def run_init(project_root: Path, evidence_dir: Path, baseline: str | None, output_name: str) -> Path:
+    if evidence_dir.exists() and any(evidence_dir.iterdir()):
+        if (evidence_dir / "manifest.json").exists():
+            raise RequestError("evidence package is finalized; initialize a new evidence directory")
+        raise RequestError("evidence directory is not empty; initialize a new evidence directory")
+    evidence_dir.mkdir(parents=True, exist_ok=True)
+    for directory in ("requests", "receipts", "raw", "generated-tests", "contracts", "runner"):
+        (evidence_dir / directory).mkdir(parents=True, exist_ok=True)
+    write_json_atomic(evidence_dir / "executions.json", [])
+    write_json_atomic(evidence_dir / "differential-proof.json", {"proofs": []})
+    write_json_atomic(evidence_dir / "lifecycle.json", {
+        "lifecycle_format": "prizmkit-canonical-lifecycle-v1",
+        "status": "initialized",
+        "baseline_commit": git_baseline(project_root, baseline),
+        "artifact_dir": None,
+        "finalized": False,
+        "immutable_identity": None,
+    })
+    output = confined(evidence_dir, output_name)
+    write_json_atomic(output, {
+        "command": "init",
+        "evidence_dir": ".",
+        "baseline_commit": git_baseline(project_root, baseline),
+        "next": "capture-change",
+    })
+    return output
+
+
+def load_lifecycle(evidence_dir: Path, *, required: bool = False) -> dict[str, Any]:
+    path = evidence_dir / "lifecycle.json"
+    if not path.exists():
+        if required:
+            raise RequestError("evidence package is not initialized; run init first")
+        return {"lifecycle_format": "legacy-compatible", "status": "legacy"}
+    return ensure_object(load_json(path), "lifecycle")
+
+
+def require_mutable_lifecycle(evidence_dir: Path) -> dict[str, Any]:
+    lifecycle_path = evidence_dir / "lifecycle.json"
+    if not lifecycle_path.exists():
+        if (evidence_dir / "manifest.json").exists():
+            raise RequestError(
+                "evidence package is finalized and immutable; re-init a new evidence package"
+            )
+        return {"lifecycle_format": "legacy-compatible", "status": "legacy"}
+    lifecycle = load_lifecycle(evidence_dir, required=True)
+    if lifecycle.get("finalized") is True:
+        raise RequestError(
+            "evidence package is finalized and immutable; re-init a new evidence package"
+        )
+    return lifecycle
+
+
+def run_render_report(evidence_dir: Path, output_name: str) -> Path:
+    manifest = ensure_object(load_json(evidence_dir / "manifest.json"), "manifest")
+    verdict = ensure_object(load_json(evidence_dir / "verdict.json"), "verdict")
+    validation_path = evidence_dir / "validation.json"
+    validation = ensure_object(load_json(validation_path), "validation") if validation_path.exists() else None
+    lifecycle_path = evidence_dir / "lifecycle.json"
+    lifecycle = ensure_object(load_json(lifecycle_path), "lifecycle") if lifecycle_path.exists() else {}
+    proofs_path = evidence_dir / "differential-proof.json"
+    proofs = load_json(proofs_path).get("proofs", []) if proofs_path.exists() else []
+    executions = load_json(evidence_dir / "executions.json")
+    artifact_dir = lifecycle.get("artifact_dir")
+    lines = [
+        "# Test Evidence Report",
+        "",
+        "Derived from structured evidence",
+        f"Evidence ID: {manifest.get('evidence_id')}",
+        f"Verdict: {verdict.get('verdict')}",
+        f"Validator result: {validation.get('result') if validation else 'pending'}",
+        "sensitivity=project-controlled",
+        "The project owns access control, retention, and upload policy.",
+        "Mocked code-level evidence does not verify a real deployed environment.",
+        "",
+        "## Scope",
+        f"- Artifact Dir: {artifact_dir or 'not provided'}",
+        "",
+        f"Execution receipts: {len(executions) if isinstance(executions, list) else 0}",
+        f"Differential proofs: {len(proofs) if isinstance(proofs, list) else 0}",
+        "The legacy test-report interface is not supported.",
+        "",
+    ]
+    output = confined(evidence_dir, output_name)
+    rendered = "\n".join(lines)
+    lifecycle_finalized = lifecycle.get("finalized") is True
+    if lifecycle_finalized:
+        if not output.is_file() or output.read_text(encoding="utf-8") != rendered:
+            raise RequestError(
+                "evidence package is finalized and immutable; re-init a new package before changing the report"
+            )
+        return output
+    write_text_atomic(output, rendered)
+    return output
+
+
+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:
+        if not isinstance(test, dict):
+            continue
+        project_path = test.get("project_path")
+        if not isinstance(project_path, str):
+            continue
+        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
+        source = confined(project_root, project_path, must_exist=True)
+        destination_relative = test.get("snapshot_path")
+        if not isinstance(destination_relative, str) or not destination_relative.startswith("generated-tests/"):
+            destination_relative = f"generated-tests/{Path(project_path).name}"
+        destination = confined(evidence_dir, destination_relative)
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(source, destination)
+        test["snapshot_path"] = destination_relative
+    write_json_atomic(evidence_dir / "test-plan.json", plan)
+
+
+def stage_output_owner(relative: str, change_class: str) -> str:
+    if relative in {"change-classification.json"}:
+        return "CHANGE_CLASSIFY"
+    if relative in {"scope.json", "target-inventory.json", "environment.json", "source-change.patch", "change-capture.json"} or relative.startswith("requests/"):
+        return "SCOPE_DISCOVER"
+    if relative in {"behavior-risk-matrix.json"}:
+        return "CONTRACT_MODEL"
+    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"
+    if relative.startswith("generated-tests/"):
+        return "TEST_BUILD"
+    if relative in {"executions.json", "differential-proof.json"} or relative.startswith("receipts/") or relative.startswith("raw/") or relative.startswith("runner/"):
+        return "EXECUTE_PROVE"
+    if relative in FINAL_RECORDS or relative == "lifecycle.json" or relative == "init.json" or relative == "finalize.json":
+        return "EVIDENCE_PACKAGE"
+    return "EVIDENCE_PACKAGE"
+
+
+def build_manifest(evidence_dir: Path, *, evidence_id: str, identity: dict[str, Any], target_hashes: dict[str, str], change_class: str, baseline_commit: str, final_verdict: str) -> dict[str, Any]:
+    file_paths = sorted(
+        path.relative_to(evidence_dir).as_posix()
+        for path in evidence_dir.rglob("*")
+        if path.is_file() and path.name != "manifest.json"
+    )
+    files = [
+        {"path": relative, "sha256": file_sha256(evidence_dir / relative), "produced_by": stage_output_owner(relative, change_class)}
+        for relative in file_paths
+    ]
+    outputs_by_stage = {stage: [] for stage in STAGES}
+    for entry in files:
+        outputs_by_stage.setdefault(entry["produced_by"], []).append(entry["path"])
+    predecessor_files: list[dict[str, str]] = []
+    stages = []
+    for stage in STAGES:
+        outputs = sorted(outputs_by_stage.get(stage, []))
+        stages.append({
+            "name": stage,
+            "status": "complete",
+            "input_sha256": canonical_sha256({
+                "stage": stage,
+                "target_hashes": target_hashes,
+                "predecessor_outputs": sorted(predecessor_files, key=lambda item: item["path"]),
+            }),
+            "outputs": outputs,
+            "not_applicable": None,
+        })
+        predecessor_files.extend(
+            {"path": output, "sha256": next(item["sha256"] for item in files if item["path"] == output)}
+            for output in outputs if output not in FINAL_RECORDS
+        )
+    return {
+        "protocol_version": "1.0",
+        "evidence_id": evidence_id,
+        "evidence_id_inputs": identity,
+        "sensitivity": "project-controlled",
+        "environment_claim": "mocked-code-level-only",
+        "change_class": change_class,
+        "baseline_commit": baseline_commit,
+        "working_diff_sha256": identity["working_diff_sha256"],
+        "target_hashes": target_hashes,
+        "stages": stages,
+        "files": files,
+        "final_verdict": final_verdict,
+        "compatibility": "legacy-test-report-interface-not-supported",
+    }
+
+
+def write_handoff_pointer(evidence_dir: Path, artifact_dir: str | None, project_root: Path | None = None) -> None:
+    if not artifact_dir:
+        return
+    artifact = Path(artifact_dir)
+    if not artifact.is_absolute() and project_root is not None:
+        artifact = project_root / artifact
+    artifact = artifact.resolve()
+    if not artifact.is_dir():
+        raise RequestError(f"artifact_dir does not exist: {artifact_dir}")
+    pointer = artifact / "test-report-path.txt"
+    write_text_atomic(pointer, str((evidence_dir / "test-report.md").resolve()) + "\n")
+
+
+def run_finalize(project_root: Path, evidence_dir: Path, request: dict[str, Any], output_name: str) -> Path:
+    allowed = {"request_version", "change_class", "baseline_commit", "scope_path", "environment_path", "artifact_dir", "blockers", "repair_scope"}
+    if set(request) - allowed:
+        raise RequestError(f"finalize request contains unsupported fields: {sorted(set(request) - allowed)}")
+    if request.get("request_version", "1.0") != "1.0":
+        raise RequestError("unsupported finalize request version")
+    lifecycle = load_lifecycle(evidence_dir, required=True)
+    if lifecycle.get("finalized") is True:
+        raise RequestError("evidence identity is finalized; re-init a new package before changing scope or source")
+    capture_path = evidence_dir / "change-capture.json"
+    if not capture_path.exists():
+        run_capture_change(project_root, evidence_dir, request.get("baseline_commit"), "change-capture.json")
+    capture = ensure_object(load_json(capture_path), "change capture")
+    baseline = capture.get("baseline_commit")
+    patch_path = evidence_dir / "source-change.patch"
+    if not isinstance(baseline, str) or not patch_path.is_file():
+        raise RequestError("canonical change capture is incomplete")
+    change_class = request.get("change_class", "behavior")
+    if change_class not in {"behavior", "lightweight"}:
+        raise RequestError("change_class must be behavior or lightweight")
+    artifact_dir = request.get("artifact_dir")
+    if artifact_dir is not None and not isinstance(artifact_dir, str):
+        raise RequestError("artifact_dir must be a project-relative directory")
+    if artifact_dir is not None:
+        artifact = confined(project_root, artifact_dir, must_exist=True, directory=True)
+        lifecycle["artifact_dir"] = artifact.relative_to(project_root).as_posix()
+    scope_relative = request.get("scope_path", "scope.json")
+    scope = ensure_object(load_json(request_file(evidence_dir, scope_relative)), "scope")
+    inventory = ensure_object(load_json(evidence_dir / "target-inventory.json"), "target inventory")
+    environment_path = evidence_dir / request.get("environment_path", "environment.json")
+    environment = load_json(environment_path) if environment_path.exists() else {}
+    plan = load_json(evidence_dir / "test-plan.json") if (evidence_dir / "test-plan.json").exists() else None
+    if isinstance(plan, dict):
+        normalize_test_snapshots(project_root, evidence_dir, plan)
+    categories = inventory.get("categories", {})
+    target_hashes = {
+        category: aggregate_inventory(categories.get(category, []))
+        for category in CATEGORIES
+    }
+    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 = {
+        "baseline_commit": baseline,
+        "working_diff_sha256": file_sha256(patch_path),
+        "scope_sha256": canonical_sha256(scope),
+    }
+    evidence_id = canonical_sha256(identity)
+    executions = load_json(evidence_dir / "executions.json") if (evidence_dir / "executions.json").exists() else []
+    blockers = list(request.get("blockers", [])) if isinstance(request.get("blockers", []), list) else []
+    required_records = {
+        "change-classification.json", "scope.json", "target-inventory.json", "environment.json",
+        "source-change.patch",
+    }
+    if change_class == "behavior":
+        required_records.update({
+            "behavior-risk-matrix.json", "test-plan.json", "test-preparation.json",
+            "infrastructure-changes.json", "differential-proof.json",
+        })
+    else:
+        required_records.add("lightweight-verification.json")
+    missing_records = sorted(
+        relative for relative in required_records
+        if not (evidence_dir / relative).is_file()
+    )
+    if missing_records:
+        blockers.append(
+            "required evidence records are missing: " + ", ".join(missing_records)
+        )
+    selected_failures = [item for item in executions if isinstance(item, dict) and item.get("selected_execution") is True and item.get("reliable") is True and item.get("exit_code") != 0]
+    if selected_failures and not request.get("repair_scope"):
+        blockers.append("reliable failure exists but repair_scope is not evidence-backed")
+    verdict = "TEST_FAIL" if selected_failures and request.get("repair_scope") else ("TEST_BLOCKED" if blockers else "TEST_PASS")
+    verdict_record: dict[str, Any] = {
+        "verdict": verdict,
+        "testing_domain_only": True,
+        "authorizes_commit_or_release": False,
+        "real_environment_validated": False,
+        "repairs_business_defects": False,
+        "code_evidence_replayable": verdict == "TEST_PASS",
+        "blockers": blockers if verdict == "TEST_BLOCKED" else [],
+        "reproduced_failures": [item["execution_id"] for item in selected_failures] if verdict == "TEST_FAIL" else [],
+    }
+    if verdict == "TEST_FAIL" and request.get("repair_scope"):
+        verdict_record["repair_scope"] = request["repair_scope"]
+    write_json_atomic(evidence_dir / "verdict.json", verdict_record)
+    write_json_atomic(evidence_dir / "validation.json", {})
+    write_json_atomic(evidence_dir / "lifecycle.json", {
+        **lifecycle,
+        "status": "finalizing",
+        "finalized": False,
+        "immutable_identity": identity,
+    })
+    manifest = build_manifest(
+        evidence_dir, evidence_id=evidence_id, identity=identity,
+        target_hashes=target_hashes, change_class=change_class,
+        baseline_commit=baseline, final_verdict=verdict,
+    )
+    write_json_atomic(evidence_dir / "manifest.json", manifest)
+    run_render_report(evidence_dir, "test-report.md")
+    write_json_atomic(evidence_dir / "lifecycle.json", {
+        **lifecycle,
+        "status": "finalized",
+        "finalized": True,
+        "immutable_identity": identity,
+    })
+    output = confined(evidence_dir, output_name)
+    write_json_atomic(output, {
+        "command": "finalize",
+        "evidence_id": evidence_id,
+        "manifest_path": "manifest.json",
+        "verdict_path": "verdict.json",
+        "report_path": "test-report.md",
+        "validation_path": "validation.json",
+        "next": "validate_test_evidence.py --attest",
+    })
+    manifest = build_manifest(
+        evidence_dir, evidence_id=evidence_id, identity=identity,
+        target_hashes=target_hashes, change_class=change_class,
+        baseline_commit=baseline, final_verdict=verdict,
+    )
+    write_json_atomic(evidence_dir / "manifest.json", manifest)
+    destination = evidence_dir.parent / evidence_id
+    if destination != evidence_dir:
+        if destination.exists():
+            raise RequestError(
+                f"evidence identity already exists at {destination}; re-init a new package"
+            )
+        os.replace(evidence_dir, destination)
+    write_handoff_pointer(destination, lifecycle.get("artifact_dir"), project_root)
+    return destination / output_name
+
+
 def run_resume(
     project_root: Path,
     evidence_dir: Path,
@@ -615,6 +1690,11 @@ def run_resume(
 ) -> Path:
     manifest = ensure_object(load_json(manifest_path), "manifest")
     inventory = ensure_object(load_json(inventory_path), "inventory")
+    lifecycle = load_lifecycle(evidence_dir)
+    if lifecycle.get("finalized") is True:
+        raise RequestError(
+            "evidence package is finalized and immutable; re-init a new evidence package before resume"
+        )
     categories = ensure_object(inventory.get("categories"), "inventory categories")
     environment_path = evidence_dir / "environment.json"
     environment = load_json(environment_path) if environment_path.exists() else {}
@@ -683,15 +1763,29 @@ def main() -> int:
     parser.add_argument("--project-root", required=True)
     parser.add_argument("--evidence-dir", required=True)
     subparsers = parser.add_subparsers(dest="subcommand", required=True)
+    init = subparsers.add_parser("init")
+    init.add_argument("--baseline")
+    init.add_argument("--output", default="init.json")
+    capture = subparsers.add_parser("capture-change")
+    capture.add_argument("--baseline")
+    capture.add_argument("--output", default="change-capture.json")
     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")
     group.add_argument("--replay-receipt")
     differential = subparsers.add_parser("differential")
     differential.add_argument("--request", required=True)
+    finalize = subparsers.add_parser("finalize")
+    finalize.add_argument("--request", required=True, help="semantic finalization request")
+    finalize.add_argument("--output", default="finalize.json")
+    report = subparsers.add_parser("render-report")
+    report.add_argument("--output", default="test-report.md")
     resume = subparsers.add_parser("resume")
     resume.add_argument("--manifest", required=True)
     resume.add_argument("--inventory", required=True)
@@ -703,11 +1797,23 @@ def main() -> int:
         if not project_root.is_dir():
             raise RequestError(f"project root does not exist: {project_root}")
         evidence_dir.relative_to(project_root)
-        evidence_dir.mkdir(parents=True, exist_ok=True)
-        if args.subcommand == "inventory":
+        if args.subcommand == "init":
+            output = run_init(project_root, evidence_dir, args.baseline, args.output)
+            print(f"Evidence initialized: {output}")
+        elif args.subcommand == "capture-change":
+            require_mutable_lifecycle(evidence_dir)
+            output = run_capture_change(project_root, evidence_dir, args.baseline, args.output)
+            print(f"Change captured: {output}")
+        elif args.subcommand == "inventory":
+            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:
                 receipt = execute_request(project_root, evidence_dir, request_file(evidence_dir, args.request))
             else:
@@ -721,9 +1827,20 @@ def main() -> int:
                 receipt = execute_request(project_root, evidence_dir, original_request, replay_of=prior.get("execution_id"))
             print(json.dumps(receipt, ensure_ascii=False))
         elif args.subcommand == "differential":
+            require_mutable_lifecycle(evidence_dir)
             proof = run_differential(project_root, evidence_dir, request_file(evidence_dir, args.request))
             print(json.dumps(proof, ensure_ascii=False))
-        else:
+        elif args.subcommand == "render-report":
+            load_lifecycle(evidence_dir)
+            output = run_render_report(evidence_dir, args.output)
+            print(f"Report rendered: {output}")
+        elif args.subcommand == "finalize":
+            load_lifecycle(evidence_dir, required=True)
+            request = ensure_object(load_json(request_file(evidence_dir, args.request)), "finalize request")
+            output = run_finalize(project_root, evidence_dir, request, args.output)
+            print(f"Evidence finalized: {output}")
+        elif args.subcommand == "resume":
+            load_lifecycle(evidence_dir)
             output = run_resume(
                 project_root, evidence_dir, request_file(evidence_dir, args.manifest),
                 request_file(evidence_dir, args.inventory), args.output,