prizmkit 1.1.140 → 1.1.142

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

@@ -1,1930 +0,0 @@
-#!/usr/bin/env python3
-"""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 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,
-timeouts, attempts, concurrency, tool probes, test layers, and framework-specific options come
-from model-authored requests after project inspection.
-"""
-
-from __future__ import annotations
-
-import argparse
-import datetime as dt
-import fnmatch
-import hashlib
-import json
-import os
-import shutil
-import signal
-import subprocess
-import sys
-import uuid
-from pathlib import Path
-from typing import Any
-
-STAGES = [
-    "CHANGE_CLASSIFY", "SCOPE_DISCOVER", "CONTRACT_MODEL", "TEST_PLAN",
-    "INFRA_READY", "TEST_BUILD", "EXECUTE_PROVE", "EVIDENCE_PACKAGE",
-    "EVIDENCE_VALIDATE",
-]
-CATEGORIES = ("source", "tests", "contracts", "lockfiles")
-LAYERS = (
-    "focused", "module-component", "contract-integration",
-    "affected-module-regression", "regression-ring",
-)
-BLOCKED_EXTERNAL_CLASSES = {"production", "unknown"}
-REPAIR_SCOPES = {
-    "test-infrastructure", "production", "runtime", "schema", "dependency", "public-interface",
-}
-INVENTORY_RESERVED_ROOTS = (
-    ".prizmkit/state",
-    ".prizmkit/test/evidence",
-    ".prizmkit/" + "dev-" + "pipeline",
-    ".claude/worktrees",
-    ".agents/worktrees",
-    ".codebuddy/worktrees",
-    ".codex/worktrees",
-)
-
-_IGNORED_DIR_NAMES = {".git", "__pycache__", ".pytest_cache", ".mypy_cache"}
-FINAL_RECORDS = {"manifest.json", "validation.json", "verdict.json", "test-report.md"}
-MAX_PROTOCOL_PACKAGE_ATTEMPTS = 2
-PROTOCOL_STATE_NAME = ".protocol-recovery.json"
-DEFAULT_EXECUTION_TIMEOUT_SECONDS = 300.0
-MAX_EXECUTION_TIMEOUT_SECONDS = 1800.0
-MAX_EXECUTION_OUTPUT_BYTES = 16 * 1024 * 1024
-CANONICAL_EVIDENCE_ROOT = (".prizmkit", "test", "evidence")
-
-
-class RequestError(Exception):
-    """Raised when a request would produce unsafe or ambiguous evidence."""
-
-
-def canonical_bytes(value: Any) -> bytes:
-    return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":")).encode("utf-8")
-
-
-def canonical_sha256(value: Any) -> str:
-    return hashlib.sha256(canonical_bytes(value)).hexdigest()
-
-
-def file_sha256(path: Path) -> str:
-    digest = hashlib.sha256()
-    with path.open("rb") as handle:
-        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
-            digest.update(chunk)
-    return digest.hexdigest()
-
-
-def write_json_atomic(path: Path, value: Any) -> None:
-    path.parent.mkdir(parents=True, exist_ok=True)
-    temporary = path.with_name(f".{path.name}.{uuid.uuid4().hex}.tmp")
-    temporary.write_text(json.dumps(value, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
-    os.replace(temporary, path)
-
-
-def load_json(path: Path) -> Any:
-    try:
-        return json.loads(path.read_text(encoding="utf-8"))
-    except FileNotFoundError as exc:
-        raise RequestError(f"file does not exist: {path}") from exc
-    except json.JSONDecodeError as exc:
-        raise RequestError(f"invalid JSON: {path}: {exc}") from exc
-
-
-def confined(root: Path, value: str, *, must_exist: bool = False, directory: bool = False) -> Path:
-    if not isinstance(value, str) or not value:
-        raise RequestError("path must be a non-empty string")
-    candidate = (root / value).resolve() if not Path(value).is_absolute() else Path(value).resolve()
-    try:
-        candidate.relative_to(root.resolve())
-    except ValueError as exc:
-        raise RequestError(f"path escapes root: {value}") from exc
-    if must_exist and not candidate.exists():
-        raise RequestError(f"path does not exist: {value}")
-    if directory and candidate.exists() and not candidate.is_dir():
-        raise RequestError(f"path is not a directory: {value}")
-    return candidate
-
-
-def canonical_evidence_root(project_root: Path) -> Path:
-    return project_root.joinpath(*CANONICAL_EVIDENCE_ROOT).resolve()
-
-
-def require_canonical_evidence_dir(project_root: Path, evidence_dir: Path) -> None:
-    root = canonical_evidence_root(project_root)
-    try:
-        evidence_dir.resolve().relative_to(root)
-    except ValueError as exc:
-        raise RequestError(
-            "evidence directory must be under .prizmkit/test/evidence"
-        ) from exc
-    if evidence_dir.resolve() == root:
-        raise RequestError("evidence directory must be a package child of .prizmkit/test/evidence")
-
-
-def max_timeout(value: Any) -> float:
-    if value is None:
-        return DEFAULT_EXECUTION_TIMEOUT_SECONDS
-    if isinstance(value, bool) or not isinstance(value, (int, float)) or value <= 0:
-        raise RequestError("timeout_seconds must be a positive number")
-    if value > MAX_EXECUTION_TIMEOUT_SECONDS:
-        raise RequestError(
-            f"timeout_seconds must not exceed {MAX_EXECUTION_TIMEOUT_SECONDS:g} seconds"
-        )
-    return float(value)
-
-
-def evidence_relative(evidence_dir: Path, path: Path) -> str:
-    try:
-        return path.resolve().relative_to(evidence_dir.resolve()).as_posix()
-    except ValueError as exc:
-        raise RequestError(f"evidence output escapes evidence directory: {path}") from exc
-
-
-def request_file(evidence_dir: Path, value: str) -> Path:
-    return confined(evidence_dir, value, must_exist=True)
-
-
-def receipt_file(evidence_dir: Path, value: str) -> Path:
-    direct = confined(evidence_dir, value)
-    if direct.is_file():
-        return direct
-    return confined(evidence_dir, f"receipts/{value}", must_exist=True)
-
-
-def ensure_object(value: Any, label: str) -> dict[str, Any]:
-    if not isinstance(value, dict):
-        raise RequestError(f"{label} must be an object")
-    return value
-
-
-def ensure_string_list(value: Any, label: str, *, allow_empty: bool = True) -> list[str]:
-    if not isinstance(value, list) or (not allow_empty and not value):
-        raise RequestError(f"{label} must be a{' non-empty' if not allow_empty else ''} string array")
-    if any(not isinstance(item, str) or not item for item in value):
-        raise RequestError(f"{label} contains a non-string or empty value")
-    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 _IGNORED_DIR_NAMES for part in path.parts):
-        return True
-    return any(path == Path(prefix) or Path(prefix) in path.parents for prefix in INVENTORY_RESERVED_ROOTS)
-
-
-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")
-    for target in value:
-        if not isinstance(target, dict):
-            raise RequestError("external target must be an object")
-        required = {"name", "external", "classification", "endpoint_evidence", "allow_evidence", "deny_evidence"}
-        if set(target) != required:
-            raise RequestError(f"external target fields must be exactly {sorted(required)}")
-        if not isinstance(target["external"], bool):
-            raise RequestError("external target external flag must be boolean")
-        for key in ("endpoint_evidence", "allow_evidence", "deny_evidence"):
-            ensure_string_list(target[key], f"external target {key}", allow_empty=(key != "endpoint_evidence"))
-        if target["external"] and target["classification"] in BLOCKED_EXTERNAL_CLASSES:
-            raise RequestError(f"execution blocked for external target classified {target['classification']}: {target['name']}")
-        if target["external"] and target["classification"] not in {"isolated", "test", "staging"}:
-            raise RequestError(f"invalid external target classification: {target['classification']}")
-        if target["external"] and not target["allow_evidence"]:
-            raise RequestError(f"external target lacks explicit allow evidence: {target['name']}")
-        if target["external"] and target["deny_evidence"]:
-            raise RequestError(f"external target matched deny evidence: {target['name']}")
-    return value
-
-
-def load_change_capture(
-    project_root: Path,
-    evidence_dir: Path,
-    *,
-    require_fresh: bool = False,
-) -> dict[str, Any]:
-    capture_path = evidence_dir / "change-capture.json"
-    if not capture_path.is_file():
-        raise RequestError("canonical change capture is required; run capture-change first")
-    capture = ensure_object(load_json(capture_path), "change capture")
-    baseline = capture.get("baseline_commit")
-    patch_path = evidence_dir / "source-change.patch"
-    if (
-        capture.get("capture_format") != "prizmkit-canonical-change-v1"
-        or not isinstance(baseline, str)
-        or not patch_path.is_file()
-        or capture.get("patch_path") != "source-change.patch"
-        or capture.get("patch_sha256") != file_sha256(patch_path)
-        or not isinstance(capture.get("changed_files"), list)
-    ):
-        raise RequestError("canonical change capture is incomplete or inconsistent")
-    if require_fresh:
-        live_patch, live_entries = canonical_change_patch(project_root, baseline)
-        live_patch_sha256 = hashlib.sha256(live_patch).hexdigest()
-        if (
-            live_patch_sha256 != capture["patch_sha256"]
-            or live_entries != capture["changed_files"]
-        ):
-            raise RequestError(
-                "canonical change capture is stale; rerun capture-change and inventory after repository changes"
-            )
-    return capture
-
-
-def captured_changed_paths(capture: dict[str, Any]) -> list[str]:
-    paths = {
-        item["path"]
-        for item in capture.get("changed_files", [])
-        if isinstance(item, dict) and isinstance(item.get("path"), str)
-    }
-    return sorted(paths)
-
-
-def plan_for_execution(evidence_dir: Path) -> dict[str, Any] | None:
-    path = evidence_dir / "test-plan.json"
-    if not path.exists():
-        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", "external_targets",
-    }
-    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":
-        raise RequestError("unsupported execution request version")
-    command = ensure_string_list(request["command"], "command", allow_empty=False)
-    if not command[0]:
-        raise RequestError("command executable is empty")
-    if not isinstance(request["cwd"], str):
-        raise RequestError("cwd must be a string")
-    environment = ensure_object(request["environment"], "environment")
-    if any(not isinstance(key, str) or not isinstance(value, str) for key, value in environment.items()):
-        raise RequestError("environment must contain string keys and complete string values")
-    probes = ensure_object(request["tool_version_commands"], "tool_version_commands")
-    for name, probe in probes.items():
-        if not isinstance(name, str):
-            raise RequestError("tool probe names must be strings")
-        ensure_string_list(probe, f"tool probe {name}", allow_empty=False)
-    has_ids = "test_ids" in request
-    has_paths = "test_paths" in request
-    has_auto_bind = "auto_bind" in request
-    if has_auto_bind and not isinstance(request["auto_bind"], bool):
-        raise RequestError("execution request auto_bind must be boolean")
-    binding_modes = int(has_ids) + int(has_paths) + int(request.get("auto_bind") is True)
-    if binding_modes == 0:
-        raise RequestError("execution request must provide test_ids, test_paths, or auto_bind=true")
-    if binding_modes != 1 or (has_auto_bind and request["auto_bind"] is False):
-        raise RequestError("execution request binding modes test_ids, test_paths, and auto_bind=true are mutually exclusive")
-    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 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",
-    }
-    scope_affecting_options = {
-        "-C", "--config", "--config-file", "--project", "--package", "--root", "--rootdir",
-        "--cwd", "--testPathPattern", "--testNamePattern", "--grep", "-k", "--filter", "-t",
-    }
-    for token in command[1:]:
-        option_name = token.split("=", 1)[0]
-        if option_name in scope_affecting_options:
-            raise RequestError(
-                "command scope cannot be inferred when the native command uses a test-selection "
-                f"option: {option_name}"
-            )
-        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(
-            "command scope cannot be inferred from the native command; use a recognized package-wide command or an explicit test path in the 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(
-            "native command scope does not cover any prepared test"
-        )
-    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")
-    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:
-        declared = 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)}")
-        declared = [by_path[path]["id"] for path in request["test_paths"]]
-    else:
-        declared = None
-    inferred = command_scope_test_ids(project_root, request, tests)
-    if declared is not None and set(declared) != set(inferred):
-        raise RequestError(
-            "execution request binding does not exactly match native command scope "
-            f"(declared: {', '.join(sorted(declared))}; inferred: {', '.join(sorted(inferred))})"
-        )
-    resolved = inferred
-    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.pop("test_paths", None)
-    request.pop("auto_bind", None)
-    request["test_ids"] = resolved
-    return request
-
-
-def collect_matches(project_root: Path, patterns: list[str], exclusions: set[str]) -> list[dict[str, str]]:
-    project_resolved = project_root.resolve()
-    paths: set[Path] = set()
-    for pattern in patterns:
-        if Path(pattern).is_absolute() or ".." in Path(pattern).parts:
-            raise RequestError(f"inventory pattern is not project-relative: {pattern}")
-        for candidate in project_root.glob(pattern):
-            if candidate.is_file():
-                paths.add(candidate.resolve())
-    entries = []
-    for candidate in sorted(paths):
-        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:
-        root = confined(project_root, relative, must_exist=True)
-        candidates = [root] if root.is_file() else root.rglob("*")
-        files: list[str] = []
-        for candidate in candidates:
-            if not candidate.is_file() or ".git" in candidate.parts or "__pycache__" in candidate.parts:
-                continue
-            resolved = candidate.resolve()
-            if resolved == evidence_resolved or evidence_resolved in resolved.parents:
-                continue
-            files.append(resolved.relative_to(project_resolved).as_posix())
-        result[relative] = sorted(files)
-    return result
-
-
-def run_inventory(project_root: Path, evidence_dir: Path, request_path: Path, output_name: str) -> Path:
-    request = ensure_object(load_json(request_path), "inventory request")
-    required = {"request_version", "categories", "changed_files", "module_roots", "exclusions", "discovery_evidence", "plan_inputs"}
-    if set(request) != required or request["request_version"] != "1.0":
-        raise RequestError(f"inventory request fields must be exactly {sorted(required)} with version 1.0")
-    categories = ensure_object(request["categories"], "inventory categories")
-    if set(categories) != set(CATEGORIES):
-        raise RequestError(f"inventory categories must be exactly {list(CATEGORIES)}")
-    exclusions = request["exclusions"]
-    if not isinstance(exclusions, list):
-        raise RequestError("inventory exclusions must be an array")
-    exclusion_paths: set[str] = set()
-    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")
-        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(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 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
-    }
-    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()
-        for relative in files
-        if relative not in inventoried_paths and relative not in exclusion_paths
-    })
-    if missing_from_inventory:
-        raise RequestError(
-            "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),
-        "categories": output_categories,
-        "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"),
-    }
-    output_path = confined(evidence_dir, output_name)
-    write_json_atomic(output_path, output)
-    return output_path
-
-
-def run_process(argv: list[str], cwd: Path, environment: dict[str, str], timeout: float | None) -> tuple[int, bytes, bytes]:
-    timeout_value = max_timeout(timeout)
-    creationflags = 0
-    process_kwargs: dict[str, Any] = {}
-    if os.name == "nt":
-        creationflags = getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)
-    else:
-        process_kwargs["start_new_session"] = True
-    process = subprocess.Popen(
-        argv, cwd=cwd, env=environment, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
-        creationflags=creationflags, **process_kwargs,
-    )
-    try:
-        stdout, stderr = process.communicate(timeout=timeout_value)
-        return process.returncode, stdout, stderr
-    except subprocess.TimeoutExpired:
-        if os.name == "nt":
-            subprocess.run(
-                ["taskkill", "/PID", str(process.pid), "/T", "/F"],
-                stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=False,
-            )
-        else:
-            try:
-                os.killpg(process.pid, signal.SIGTERM)
-                process.wait(timeout=1)
-            except (ProcessLookupError, subprocess.TimeoutExpired):
-                try:
-                    os.killpg(process.pid, signal.SIGKILL)
-                except ProcessLookupError:
-                    pass
-        stdout, stderr = process.communicate()
-        return 124, stdout, stderr + f"\nPrizmKit runner timeout after {timeout_value:g} seconds\n".encode()
-
-
-def limit_output(value: bytes, label: str) -> bytes:
-    if len(value) <= MAX_EXECUTION_OUTPUT_BYTES:
-        return value
-    marker = f"\nPrizmKit runner {label} truncated after {MAX_EXECUTION_OUTPUT_BYTES} bytes\n".encode()
-    return value[:MAX_EXECUTION_OUTPUT_BYTES - len(marker)] + marker
-
-
-def run_probe(argv: list[str], cwd: Path, environment: dict[str, str], timeout: float | None) -> dict[str, Any]:
-    try:
-        exit_code, stdout, stderr = run_process(argv, cwd, environment, timeout)
-        return {
-            "command": argv, "exit_code": exit_code,
-            "stdout": limit_output(stdout, "probe stdout").decode(errors="replace"),
-            "stderr": limit_output(stderr, "probe stderr").decode(errors="replace"),
-        }
-    except OSError as exc:
-        return {"command": argv, "error": str(exc)}
-
-
-def append_receipt(evidence_dir: Path, receipt: dict[str, Any]) -> None:
-    receipt_path = evidence_dir / "receipts" / f"{receipt['execution_id']}.json"
-    if receipt_path.exists():
-        raise RequestError(f"receipt already exists: {receipt_path.name}")
-    write_json_atomic(receipt_path, receipt)
-    path = evidence_dir / "executions.json"
-    existing: Any = load_json(path) if path.exists() else []
-    if not isinstance(existing, list):
-        raise RequestError("executions.json must remain an array")
-    existing.append(receipt)
-    write_json_atomic(path, existing)
-
-
-def ensure_runner_snapshot(evidence_dir: Path) -> tuple[str, str]:
-    source = Path(__file__).resolve()
-    digest = file_sha256(source)
-    relative = f"runner/build_test_evidence-{digest}.py"
-    destination = evidence_dir / relative
-    if destination.exists():
-        if file_sha256(destination) != digest:
-            raise RequestError("archived runner snapshot hash mismatch")
-    else:
-        destination.parent.mkdir(parents=True, exist_ok=True)
-        shutil.copy2(source, destination)
-    return relative, digest
-
-
-def execute_request(
-    project_root: Path,
-    evidence_dir: Path,
-    request_path: Path,
-    *,
-    replay_of: str | None = None,
-    selected_execution: bool = True,
-) -> dict[str, Any]:
-    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
-    original_binding_fields = {
-        key for key in ("test_ids", "test_paths", "auto_bind")
-        if isinstance(request_value, dict) and key in request_value
-    }
-    request = validate_execution_request(request_value, plan=plan_for_execution(evidence_dir))
-    request = resolve_execution_test_ids(project_root, evidence_dir, request)
-    if original_binding_fields != {"test_ids"} or original_test_ids != request["test_ids"]:
-        write_json_atomic(request_path, request)
-    cwd = confined(project_root, request["cwd"] or ".", must_exist=True, directory=True)
-    complete_environment = {
-        key: value for key, value in os.environ.items()
-        if key in {"PATH", "HOME", "TMPDIR", "TMP", "TEMP", "GOMODCACHE", "GOPATH", "GOCACHE", "NPM_CONFIG_CACHE", "PIP_CACHE_DIR"}
-    }
-    complete_environment.setdefault("PATH", os.defpath)
-    if os.name == "nt" and os.environ.get("SYSTEMROOT"):
-        complete_environment["SYSTEMROOT"] = os.environ["SYSTEMROOT"]
-    complete_environment.update(request["environment"])
-    timeout = max_timeout(request.get("timeout_seconds"))
-    tools = {
-        name: run_probe(argv, cwd, complete_environment, timeout)
-        for name, argv in request["tool_version_commands"].items()
-    }
-    probes_reliable = all(
-        isinstance(result, dict)
-        and result.get("exit_code") == 0
-        and "error" not in result
-        for result in tools.values()
-    )
-    execution_id = str(uuid.uuid4())
-    runner_path, runner_hash = ensure_runner_snapshot(evidence_dir)
-    raw_dir = evidence_dir / "raw"
-    raw_dir.mkdir(parents=True, exist_ok=True)
-    stdout_path = raw_dir / f"{execution_id}.stdout"
-    stderr_path = raw_dir / f"{execution_id}.stderr"
-    started = dt.datetime.now(dt.timezone.utc).isoformat()
-    timed_out = False
-    output_limited = False
-    execution_error = False
-    try:
-        exit_code, stdout, stderr = run_process(
-            request["command"], cwd, complete_environment, timeout,
-        )
-        timed_out = exit_code == 124 and b"PrizmKit runner timeout" in stderr
-        output_limited = (
-            len(stdout) > MAX_EXECUTION_OUTPUT_BYTES
-            or len(stderr) > MAX_EXECUTION_OUTPUT_BYTES
-        )
-    except OSError as exc:
-        exit_code = 127
-        stdout = b""
-        stderr = f"PrizmKit runner execution error: {exc}\n".encode()
-        execution_error = True
-    stdout_path.write_bytes(limit_output(stdout, "stdout"))
-    stderr_path.write_bytes(limit_output(stderr, "stderr"))
-    finished = dt.datetime.now(dt.timezone.utc).isoformat()
-    existing = load_json(evidence_dir / "executions.json") if (evidence_dir / "executions.json").exists() else []
-    if not isinstance(existing, list):
-        raise RequestError("executions.json must remain an array")
-    same_request_attempts = sum(1 for item in existing if isinstance(item, dict) and item.get("request_sha256") == file_sha256(request_path))
-    receipt = {
-        "receipt_format": "prizmkit-runner-generated-v1",
-        "runner_path": runner_path,
-        "runner_sha256": runner_hash,
-        "execution_id": execution_id,
-        "attempt_index": same_request_attempts + 1,
-        "request_path": evidence_relative(evidence_dir, request_path),
-        "request_sha256": file_sha256(request_path),
-        "purpose": request["purpose"],
-        "command": request["command"],
-        "cwd": request["cwd"],
-        "environment": complete_environment,
-        "tool_versions": tools,
-        "layer": request["layer"],
-        "test_ids": request["test_ids"],
-        "external_targets": request["external_targets"],
-        "timeout_seconds": timeout,
-        "exit_code": exit_code,
-        "stdout_path": evidence_relative(evidence_dir, stdout_path),
-        "stderr_path": evidence_relative(evidence_dir, stderr_path),
-        "stdout_sha256": file_sha256(stdout_path),
-        "stderr_sha256": file_sha256(stderr_path),
-        "selected_execution": selected_execution,
-        "reliable": probes_reliable and not timed_out and not output_limited and not execution_error,
-        "started_at": started,
-        "finished_at": finished,
-        "replay_of": replay_of,
-        "isolation": {"kind": "project-direct"},
-    }
-    append_receipt(evidence_dir, receipt)
-    return receipt
-
-
-def run_capture_change(
-    project_root: Path,
-    evidence_dir: Path,
-    baseline: str | None,
-    output_name: str,
-) -> Path:
-    lifecycle = load_lifecycle(evidence_dir, required=True)
-    expected_baseline = lifecycle.get("baseline_commit")
-    resolved_baseline = git_baseline(project_root, baseline)
-    if isinstance(expected_baseline, str) and resolved_baseline != expected_baseline:
-        raise RequestError(
-            "capture baseline does not match the baseline pinned during init"
-        )
-    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,
-    }
-    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:
-    require_canonical_evidence_dir(project_root, evidence_dir)
-    align_protocol_state(project_root, protocol_run_key(project_root, baseline))
-    require_protocol_budget(project_root, package_initialization=True)
-    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)
-    resolved_baseline = git_baseline(project_root, baseline)
-    update_protocol_state(project_root, event="package-initialized", increment="package_initializations")
-    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 / "lifecycle.json", {
-        "lifecycle_format": "prizmkit-canonical-lifecycle-v1",
-        "status": "initialized",
-        "baseline_commit": resolved_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": resolved_baseline,
-        "next": "capture-change",
-    })
-    return output
-
-
-def protocol_state_path(project_root: Path) -> Path:
-    return canonical_evidence_root(project_root) / PROTOCOL_STATE_NAME
-
-
-def align_protocol_state(project_root: Path, run_key: str) -> None:
-    state_path = protocol_state_path(project_root)
-    if state_path.exists():
-        state = ensure_object(load_json(state_path), "protocol recovery state")
-        if state.get("run_key") == run_key:
-            return
-    write_json_atomic(state_path, {"run_key": run_key})
-
-
-def update_protocol_state(
-    project_root: Path,
-    *,
-    event: str,
-    error: str | None = None,
-    increment: str | None = None,
-) -> dict[str, Any]:
-    state_path = protocol_state_path(project_root)
-    state: dict[str, Any] = {}
-    if state_path.exists():
-        state = ensure_object(load_json(state_path), "protocol recovery state")
-    if increment is not None:
-        count = state.get(increment, 0)
-        if not isinstance(count, int) or isinstance(count, bool):
-            count = 0
-        state[increment] = count + 1
-    state["last_event"] = event
-    state["last_error"] = error
-    state["max_package_initializations"] = MAX_PROTOCOL_PACKAGE_ATTEMPTS
-    state["max_preflight_failures"] = MAX_PROTOCOL_PACKAGE_ATTEMPTS
-    state["blocked"] = (
-        state.get("package_initializations", 0) >= MAX_PROTOCOL_PACKAGE_ATTEMPTS
-        or state.get("preflight_failures", 0) >= MAX_PROTOCOL_PACKAGE_ATTEMPTS
-    )
-    write_json_atomic(state_path, state)
-    return state
-
-
-def require_protocol_budget(project_root: Path, *, package_initialization: bool = False) -> None:
-    state_path = protocol_state_path(project_root)
-    if not state_path.exists():
-        return
-    state = ensure_object(load_json(state_path), "protocol recovery state")
-    if package_initialization and state.get("package_initializations", 0) >= MAX_PROTOCOL_PACKAGE_ATTEMPTS:
-        raise RequestError(
-            "evidence protocol package budget exhausted; stop and return TEST_BLOCKED "
-            "instead of creating another evidence package"
-        )
-    if state.get("preflight_failures", 0) >= MAX_PROTOCOL_PACKAGE_ATTEMPTS:
-        raise RequestError(
-            "evidence protocol preflight budget exhausted; return TEST_BLOCKED "
-            "instead of continuing semantic record repair"
-        )
-
-
-def protocol_run_key(project_root: Path, baseline: str | None) -> str:
-    resolved_baseline = git_baseline(project_root, baseline)
-    patch, _ = canonical_change_patch(project_root, resolved_baseline)
-    return canonical_sha256({
-        "baseline_commit": resolved_baseline,
-        "working_diff_sha256": hashlib.sha256(patch).hexdigest(),
-    })
-
-
-def semantic_record_paths(change_class: str) -> set[str]:
-    common = {"change-classification.json", "scope.json"}
-    if change_class == "behavior":
-        return common | {"behavior-risk-matrix.json", "infrastructure-changes.json"}
-    return common | {"lightweight-verification.json"}
-
-
-def require_semantic_record_files(evidence_dir: Path, change_class: str) -> None:
-    missing = sorted(
-        relative for relative in semantic_record_paths(change_class)
-        if not (evidence_dir / relative).is_file()
-    )
-    if missing:
-        raise RequestError(
-            "pre-finalize semantic records are incomplete: " + ", ".join(missing)
-            + "; keep this package mutable and repair it before finalize"
-        )
-
-
-def preflight_semantic_records(evidence_dir: Path, change_class: str) -> None:
-    require_semantic_record_files(evidence_dir, change_class)
-    validator_path = Path(__file__).resolve().with_name("validate_test_evidence.py")
-    try:
-        import importlib.util
-        spec = importlib.util.spec_from_file_location("prizmkit_test_validator_preflight", validator_path)
-        if spec is None or spec.loader is None:
-            raise RequestError("cannot load semantic preflight validator")
-        module = importlib.util.module_from_spec(spec)
-        spec.loader.exec_module(module)
-        records_schema = module.load_schema("authoritative-records.schema.json")
-        matrix_schema = module.load_schema("behavior-risk-matrix.schema.json")
-        errors: list[str] = []
-        definitions = {
-            "change-classification.json": "changeClassification",
-            "scope.json": "scope",
-            "infrastructure-changes.json": "infrastructureChanges",
-            "lightweight-verification.json": "lightweightVerification",
-        }
-        for relative in sorted(semantic_record_paths(change_class)):
-            value = load_json(evidence_dir / relative)
-            if relative == "behavior-risk-matrix.json":
-                module.validate_schema(value, matrix_schema, matrix_schema, "behavior-risk-matrix", errors)
-            else:
-                module.validate_definition(value, definitions[relative], records_schema, relative, errors)
-        if errors:
-            raise RequestError("semantic preflight failed: " + "; ".join(errors[:20]))
-    except ImportError as exc:
-        raise RequestError(f"cannot run semantic preflight: {exc}") from exc
-
-
-def selected_layer_blockers(plan: dict[str, Any] | None, executions: list[Any]) -> list[str]:
-    if not isinstance(plan, dict):
-        return []
-    selected_layers = {
-        item.get("layer")
-        for item in executions
-        if isinstance(item, dict) and item.get("selected_execution") is True
-    }
-    blockers: list[str] = []
-    for layer in plan.get("layers", []):
-        if not isinstance(layer, dict) or layer.get("required") is not True:
-            continue
-        name = layer.get("name")
-        if name not in selected_layers:
-            blockers.append(f"required layer has no selected execution: {name}")
-    return blockers
-
-
-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 {}
-    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}",
-        "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 == "executions.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, attested: bool = False) -> 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"])
-    stages = []
-    for stage in STAGES:
-        outputs = sorted(outputs_by_stage.get(stage, []))
-        stages.append({
-            "name": stage,
-            "status": "complete" if stage != "EVIDENCE_VALIDATE" or attested else "pending",
-            "outputs": outputs,
-            "not_applicable": None,
-        })
-    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:
-    require_canonical_evidence_dir(project_root, evidence_dir)
-    require_protocol_budget(project_root)
-    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")
-    if request.get("repair_scope") is not None and request.get("repair_scope") not in REPAIR_SCOPES:
-        raise RequestError("repair_scope must identify an evidence-backed repair domain")
-    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 = load_change_capture(project_root, evidence_dir, require_fresh=True)
-    lifecycle_baseline = lifecycle.get("baseline_commit")
-    baseline = capture.get("baseline_commit")
-    if not isinstance(lifecycle_baseline, str) or baseline != lifecycle_baseline:
-        raise RequestError("canonical change capture baseline does not match init baseline")
-    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")
-    try:
-        require_semantic_record_files(evidence_dir, change_class)
-    except RequestError as exc:
-        state = update_protocol_state(
-            project_root,
-            event="preflight-failed",
-            error=str(exc),
-            increment="preflight_failures",
-        )
-        if state.get("blocked"):
-            raise RequestError(
-                str(exc) + "; evidence protocol recovery budget exhausted; return TEST_BLOCKED "
-                "and do not initialize another package"
-            ) from exc
-        raise
-
-    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)
-    try:
-        preflight_semantic_records(evidence_dir, change_class)
-    except RequestError as exc:
-        state = update_protocol_state(
-            project_root,
-            event="preflight-failed",
-            error=str(exc),
-            increment="preflight_failures",
-        )
-        if state.get("blocked"):
-            raise RequestError(
-                str(exc) + "; evidence protocol recovery budget exhausted; return TEST_BLOCKED "
-                "and do not initialize another package"
-            ) from exc
-        raise
-    identity = {
-        "baseline_commit": baseline,
-        "working_diff_sha256": file_sha256(patch_path),
-        "scope_sha256": canonical_sha256(scope),
-    }
-    evidence_id = canonical_sha256(identity)
-    destination = evidence_dir.parent / evidence_id
-    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 []
-    blockers.extend(selected_layer_blockers(plan, executions if isinstance(executions, 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",
-        })
-    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:
-        state = update_protocol_state(
-            project_root,
-            event="finalize-precondition-failed",
-            error="required evidence records are missing: " + ", ".join(missing_records),
-            increment="preflight_failures",
-        )
-        suffix = ""
-        if state.get("blocked"):
-            suffix = "; evidence protocol recovery budget exhausted; return TEST_BLOCKED"
-        raise RequestError(
-            "pre-finalize package records are incomplete: " + ", ".join(missing_records) + suffix
-        )
-    selected_unreliable = [
-        item for item in executions
-        if isinstance(item, dict)
-        and item.get("selected_execution") is True
-        and item.get("reliable") is not True
-    ]
-    for execution in selected_unreliable:
-        blockers.append(
-            "selected execution is unreliable: "
-            + str(execution.get("execution_id", "unknown-execution"))
-        )
-    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_BLOCKED" if blockers
-        else "TEST_FAIL" if selected_failures and request.get("repair_scope")
-        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,
-    })
-    # First manifest: pinned before render-report so the report can reference it.
-    manifest = build_manifest(
-        evidence_dir, evidence_id=evidence_id, identity=identity,
-        target_hashes=target_hashes, change_class=change_class,
-        baseline_commit=baseline, final_verdict=verdict,
-        attested=False,
-    )
-    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": "payload-finalized",
-        "finalized": False,
-        "immutable_identity": identity,
-    })
-    output = confined(evidence_dir, output_name)
-    final_evidence_relative = destination.relative_to(project_root).as_posix()
-    write_json_atomic(output, {
-        "command": "finalize",
-        "evidence_id": evidence_id,
-        "evidence_dir": final_evidence_relative,
-        "manifest_path": f"{final_evidence_relative}/manifest.json",
-        "verdict_path": f"{final_evidence_relative}/verdict.json",
-        "report_path": f"{final_evidence_relative}/test-report.md",
-        "validation_path": f"{final_evidence_relative}/validation.json",
-        "next": "validate_test_evidence.py --attest",
-    })
-    # Second manifest: re-hashes after render-report produces test-report.md.
-    manifest = build_manifest(
-        evidence_dir, evidence_id=evidence_id, identity=identity,
-        target_hashes=target_hashes, change_class=change_class,
-        baseline_commit=baseline, final_verdict=verdict,
-        attested=False,
-    )
-    write_json_atomic(evidence_dir / "manifest.json", manifest)
-    if destination != evidence_dir:
-        if destination.exists():
-            try:
-                existing_man = load_json(destination / "manifest.json")
-                if isinstance(existing_man, dict) and existing_man.get("final_verdict") == "TEST_PASS":
-                    write_handoff_pointer(destination, lifecycle.get("artifact_dir"), project_root)
-                    return destination / output_name
-            except Exception:
-                pass
-            raise RequestError(
-                f"evidence identity already exists at {destination}; re-init a new package"
-            )
-        os.replace(evidence_dir, destination)
-    final_evidence_dir = destination if destination != evidence_dir else evidence_dir
-    write_handoff_pointer(final_evidence_dir, lifecycle.get("artifact_dir"), project_root)
-    update_protocol_state(
-        project_root,
-        event="finalized",
-        error="; ".join(verdict_record.get("blockers", [])) if verdict == "TEST_BLOCKED" else None,
-    )
-    return final_evidence_dir / output_name
-
-
-def run_resume(
-    project_root: Path,
-    evidence_dir: Path,
-    manifest_path: Path,
-    inventory_path: Path,
-    output_name: str,
-) -> 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 {}
-    aggregate = lambda entries: canonical_sha256(sorted(entries, key=lambda item: item["path"]))
-    live_categories: dict[str, list[dict[str, str]]] = {}
-    for category in CATEGORIES:
-        live_entries: list[dict[str, str]] = []
-        for entry in categories.get(category, []):
-            if not isinstance(entry, dict) or not isinstance(entry.get("path"), str):
-                raise RequestError(f"invalid resume inventory entry: {category}")
-            candidate = confined(project_root, entry["path"], must_exist=True)
-            live_entries.append({"path": entry["path"], "sha256": file_sha256(candidate)})
-        live_categories[category] = live_entries
-    current = {
-        "source": aggregate(live_categories["source"]),
-        "tests": aggregate(live_categories["tests"]),
-        "contracts": aggregate(live_categories["contracts"]),
-        "lockfiles": aggregate(live_categories["lockfiles"]),
-        "environment": canonical_sha256(environment),
-        "plan": canonical_sha256(inventory.get("plan_inputs", {})),
-    }
-    changed = sorted(key for key, value in current.items() if manifest.get("target_hashes", {}).get(key) != value)
-    first_invalid: str | None = None
-    reasons: list[str] = []
-    dependency_stage = {
-        "source": "SCOPE_DISCOVER", "tests": "TEST_PLAN", "contracts": "CONTRACT_MODEL",
-        "lockfiles": "INFRA_READY", "environment": "INFRA_READY", "plan": "TEST_PLAN",
-    }
-    if changed:
-        first_invalid = min((dependency_stage[key] for key in changed), key=STAGES.index)
-        reasons.append(f"target hashes changed: {', '.join(changed)}")
-    files = {entry.get("path"): entry for entry in manifest.get("files", []) if isinstance(entry, dict)}
-    for stage in manifest.get("stages", []):
-        if not isinstance(stage, dict):
-            continue
-        for relative in stage.get("outputs", []):
-            candidate = confined(evidence_dir, relative)
-            entry = files.get(relative)
-            if not candidate.is_file() or not entry or file_sha256(candidate) != entry.get("sha256"):
-                stage_name = stage.get("name")
-                if stage_name in STAGES and (first_invalid is None or STAGES.index(stage_name) < STAGES.index(first_invalid)):
-                    first_invalid = stage_name
-                reasons.append(f"missing or drifted stage output: {relative}")
-    invalidated = STAGES[STAGES.index(first_invalid):] if first_invalid else []
-    decision = {
-        "decision_format": "prizmkit-resume-invalidation-v1",
-        "manifest_path": evidence_relative(evidence_dir, manifest_path),
-        "manifest_sha256": file_sha256(manifest_path),
-        "inventory_path": evidence_relative(evidence_dir, inventory_path),
-        "inventory_sha256": file_sha256(inventory_path),
-        "current_target_hashes": current,
-        "changed_hashes": changed,
-        "first_invalid_stage": first_invalid,
-        "invalidated_stages": invalidated,
-        "preserve_prior_executions": True,
-        "reasons": reasons,
-        "semantic_review_required": True,
-    }
-    output = confined(evidence_dir, output_name)
-    write_json_atomic(output, decision)
-    return output
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser(description="Build trusted, request-driven test evidence")
-    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")
-    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)
-    resume.add_argument("--output", default="resume-decision.json")
-    args = parser.parse_args()
-    project_root = Path(args.project_root).resolve()
-    evidence_dir = Path(args.evidence_dir).resolve()
-    try:
-        if not project_root.is_dir():
-            raise RequestError(f"project root does not exist: {project_root}")
-        require_canonical_evidence_dir(project_root, evidence_dir)
-        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:
-                prior_path = receipt_file(evidence_dir, args.replay_receipt)
-                prior = ensure_object(load_json(prior_path), "replay receipt")
-                if prior.get("receipt_format") != "prizmkit-runner-generated-v1":
-                    raise RequestError("replay source is not a runner-generated receipt")
-                original_request = request_file(evidence_dir, prior.get("request_path", ""))
-                if file_sha256(original_request) != prior.get("request_sha256"):
-                    raise RequestError("recorded request hash no longer matches replay source")
-                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 == "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,
-            )
-            print(f"Resume decision written: {output}")
-        return 0
-    except (RequestError, OSError, ValueError) as exc:
-        print(f"Test evidence builder: BLOCKED\n- {exc}", file=sys.stderr)
-        return 2
-
-
-if __name__ == "__main__":
-    sys.exit(main())