prizmkit 1.1.130 → 1.1.134

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

@@ -2,10 +2,14 @@
 """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 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,
@@ -35,13 +39,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 +141,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,7 +326,14 @@ def validate_external_targets(value: Any) -> list[dict[str, Any]]:
     return value
 
 
-def validate_execution_request(request: Any) -> dict[str, Any]:
+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 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",
@@ -175,7 +357,24 @@ 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")
+    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 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 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 {}
+        invalid_layer = sorted(
+            test_id for test_id in 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")
@@ -215,11 +414,60 @@ def collect_matches(project_root: Path, patterns: list[str], exclusions: set[str
     entries = []
     for candidate in sorted(paths):
         relative = candidate.relative_to(project_root).as_posix()
-        if relative not in exclusions:
+        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,
@@ -257,28 +505,49 @@ 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)
     missing_from_inventory = sorted({
         relative
         for files in module_root_files.values()
@@ -290,6 +559,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 +569,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 +663,7 @@ 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 = validate_execution_request(load_json(request_path), plan=plan_for_execution(evidence_dir))
     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 +774,61 @@ 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 = validate_execution_request(
+        request["execution_request"], plan=plan_for_execution(evidence_dir),
+    )
     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 +919,379 @@ 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 normalize_test_snapshots(project_root: Path, evidence_dir: Path, plan: dict[str, Any]) -> None:
+    tests = plan.get("tests")
+    if not isinstance(tests, list):
+        return
+    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 = 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')}")
+        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"}:
+        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", {}))
+    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", "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 +1301,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,6 +1374,12 @@ 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")
@@ -692,6 +1389,11 @@ def main() -> int:
     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 +1405,19 @@ 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 == "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 +1431,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,