prizmkit 1.1.138 → 1.1.139

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.1.138",
-  "bundledAt": "2026-07-20T06:21:15.560Z",
-  "bundledFrom": "9c4025a"
+  "frameworkVersion": "1.1.139",
+  "bundledAt": "2026-07-20T10:59:24.300Z",
+  "bundledFrom": "a055a29"
 }

package/bundled/dev-pipeline/scripts/prompt_framework.py

@@ -117,6 +117,14 @@ def pipeline_checkpoint_metadata(artifact_dir, evidence=None, stage="plan",
                                  blocked_reason=None, terminal_status=None):
     """Build family-neutral semantic L4 metadata without replacing L1 state."""
     evidence = evidence or {}
+    if evidence:
+        evidence_paths = {
+            "manifest": evidence.get("manifest_path"),
+            "verdict": evidence.get("verdict_path"),
+            "validation": evidence.get("validation_path"),
+        }
+    else:
+        evidence_paths = {"manifest": None, "verdict": None, "validation": None}
     current_stage = None if terminal_status else stage
     semantic_next_stage = None if terminal_status else next_stage
     return {
@@ -129,11 +137,7 @@ def pipeline_checkpoint_metadata(artifact_dir, evidence=None, stage="plan",
         "stage_result": stage_result,
         "repair_scope": repair_scope,
         "repair_round": repair_round,
-        "authoritative_evidence_paths": {
-            "manifest": evidence.get("manifest_path"),
-            "verdict": evidence.get("verdict_path"),
-            "validation": evidence.get("validation_path"),
-        },
+        "authoritative_evidence_paths": evidence_paths,
         "next_stage": semantic_next_stage,
         "resume_from": resume_from,
         "blocked_reason": blocked_reason,

package/bundled/dev-pipeline/scripts/update-checkpoint.py

@@ -213,6 +213,43 @@ def _checkpoint_project_root(checkpoint_path):
             return str(parent.parent)
     return str(path.parent)
 
+def _discover_test_evidence_paths(checkpoint_path, data):
+    """Discover the latest finalized test package from the artifact handoff pointer."""
+    project_root = Path(_checkpoint_project_root(checkpoint_path))
+    candidates = []
+    artifact_dir = data.get("artifact_dir")
+    if isinstance(artifact_dir, str) and artifact_dir:
+        candidates.append(project_root / artifact_dir)
+    for state_key in ("feature_state", "bugfix_state", "refactor_state"):
+        state = data.get(state_key)
+        if isinstance(state, dict) and isinstance(state.get("artifact_dir"), str):
+            candidates.append(project_root / state["artifact_dir"])
+    item_slug = data.get("item_slug")
+    if isinstance(item_slug, str) and item_slug:
+        candidates.append(project_root / ".prizmkit" / "specs" / item_slug)
+        candidates.append(project_root / ".prizmkit" / "bugfix" / item_slug)
+        candidates.append(project_root / ".prizmkit" / "refactor" / item_slug)
+
+    for artifact in candidates:
+        pointer = artifact / "test-report-path.txt"
+        try:
+            report = Path(pointer.read_text(encoding="utf-8").strip()).resolve()
+        except (OSError, ValueError):
+            continue
+        evidence_dir = report.parent
+        paths = {
+            "manifest": str(evidence_dir / "manifest.json"),
+            "verdict": str(evidence_dir / "verdict.json"),
+            "validation": str(evidence_dir / "validation.json"),
+        }
+        if all(Path(value).is_file() for value in paths.values()):
+            return {
+                key: str(Path(value).relative_to(project_root))
+                for key, value in paths.items()
+            }
+    return None
+
+
 def _finalize_semantics(checkpoint_path, data, state_key):
     """Derive a deterministic terminal status after an atomic mutation."""
     candidate = validate_checkpoint_data(
@@ -286,11 +323,25 @@ def update_checkpoint(
             return {"ok": False, "error": verdict_error}
 
     semantic_update = _normalize_semantic_update(semantic_update)
+    if (
+        semantic_update.get("stage_result") == "TEST_BLOCKED"
+        and not semantic_update.get("authoritative_evidence_paths")
+    ):
+        discovered = _discover_test_evidence_paths(checkpoint_path, data)
+        if discovered:
+            semantic_update["authoritative_evidence_paths"] = discovered
     semantic_error = _validate_semantic_update(step, semantic_update)
     if semantic_error:
         return {"ok": False, "error": semantic_error}
 
     stage_result = semantic_update.get("stage_result")
+    if step.get("skill") == "prizmkit-test" and stage_result in TEST_RESULTS:
+        evidence = semantic_update.get("authoritative_evidence_paths") or step.get("authoritative_evidence_paths")
+        if not isinstance(evidence, dict) or set(evidence) != {"manifest", "verdict", "validation"}:
+            return {
+                "ok": False,
+                "error": "Every terminal test verdict requires manifest, verdict, and validation evidence paths",
+            }
     if new_status == "completed" and step.get("skill") == "prizmkit-code-review":
         stage_result = stage_result or step.get("stage_result")
         if stage_result != "REVIEW_PASS":

package/bundled/dev-pipeline/templates/sections/phase-prizmkit-test.md

@@ -33,7 +33,8 @@ Preserve the same artifact directory and update the L1 workflow state plus this
 - `TEST_FAIL` with `repair_scope=test-infrastructure` → `prizmkit-implement` → `prizmkit-test`; do not make speculative production edits.
 - `TEST_FAIL` with `repair_scope=production|runtime|schema|dependency|public-interface` → `prizmkit-implement` → `prizmkit-code-review` → `prizmkit-test`.
 - `TEST_FAIL` with unknown or unsafe scope → do not guess a production edit; record `WORKFLOW_BLOCKED` and a safe resume entry.
-- `TEST_BLOCKED` → preserve all evidence and artifacts, perform only bounded environment recovery, then finish terminal `WORKFLOW_BLOCKED` with `blocked_reason=test_blocked`; never edit production speculatively.
+- `TEST_BLOCKED` → preserve all evidence and artifacts, perform only bounded environment recovery, then finish terminal `WORKFLOW_BLOCKED` with `blocked_reason=test_blocked`; never edit production speculatively. When a finalized blocked package exists, pass its validated `manifest`, `verdict`, and `validation` paths to the checkpoint; do not leave these paths null.
+- The builder's evidence-protocol recovery budget is separate from the outer `repair_round`: after bounded preflight/package attempts, stop creating evidence versions and return `TEST_BLOCKED`.
 - The outer `repair_round` is shared across review/test failures and may not exceed three. The Code Review internal loop limit remains separate and is at most ten completed rounds.
 
 A missing, stale, incomplete, mismatched, tampered, or wrong-scope package is not `TEST_PASS`: preserve the evidence, write `failure-log.md`, and leave the checkpoint resumable or blocked according to headless policy.

package/bundled/dev-pipeline/tests/test_checkpoint_state.py

@@ -440,6 +440,53 @@ def test_declared_final_artifact_must_exist_for_semantic_completion(tmp_path, mo
 
 
 
+def test_blocked_test_handoff_discovers_finalized_evidence_paths(tmp_path):
+    artifact = tmp_path / ".prizmkit" / "specs" / "feature"
+    artifact.mkdir(parents=True)
+    evidence = tmp_path / ".prizmkit" / "test" / "evidence" / "evidence-1"
+    evidence.mkdir(parents=True)
+    for name in ("manifest.json", "verdict.json", "validation.json"):
+        (evidence / name).write_text("{}", encoding="utf-8")
+    report = evidence / "test-report.md"
+    report.write_text("blocked", encoding="utf-8")
+    (artifact / "test-report-path.txt").write_text(str(report), encoding="utf-8")
+
+    payload = _family_checkpoint(
+        "feature-pipeline",
+        [
+            "prizmkit-implement", "prizmkit-code-review", "prizmkit-test",
+            "prizmkit-retrospective", "prizmkit-committer", "completion-summary",
+        ],
+        semantic={"artifact_dir": ".prizmkit/specs/feature"},
+    )
+    payload["feature_state"]["artifact_dir"] = ".prizmkit/specs/feature"
+    payload["steps"][1]["stage_result"] = "REVIEW_PASS"
+    payload["steps"][2]["status"] = "in_progress"
+    payload["steps"][2].pop("stage_result")
+    for step in payload["steps"][3:]:
+        step["status"] = "pending"
+        step.pop("stage_result", None)
+    checkpoint = _write(tmp_path / ".prizmkit" / "specs" / "feature" / "workflow-checkpoint.json", payload)
+
+    result = update_checkpoint(
+        str(checkpoint),
+        "prizmkit-test",
+        "failed",
+        semantic_update={
+            "stage_result": "TEST_BLOCKED",
+            "blocked_reason": "test_blocked",
+            "terminal_status": "WORKFLOW_BLOCKED",
+        },
+    )
+
+    assert result["ok"] is True
+    paths = json.loads(checkpoint.read_text(encoding="utf-8"))["steps"][2]["authoritative_evidence_paths"]
+    assert paths["manifest"] == ".prizmkit/test/evidence/evidence-1/manifest.json"
+    assert paths["verdict"] == ".prizmkit/test/evidence/evidence-1/verdict.json"
+    assert paths["validation"] == ".prizmkit/test/evidence/evidence-1/validation.json"
+
+
+
 def test_update_checkpoint_rejects_test_pass_when_validator_replay_fails(tmp_path, monkeypatch):
     paths = _write_test_evidence(tmp_path)
     payload = _family_checkpoint(

package/bundled/skills/_metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.1.138",
+  "version": "1.1.139",
   "skills": {
     "prizmkit": {
       "description": "Framework introduction and navigation for the formal single-requirement lifecycle, project initialization, Prizm docs, and independent deployment.",

package/bundled/skills/prizmkit-test/SKILL.md

@@ -30,13 +30,13 @@ Use `${SKILL_DIR}/scripts/build_test_evidence.py` for every lifecycle command:
 - `inventory`: hashes current source/tests/contracts/lockfiles, rejects category overlap, excludes runtime-only paths, and validates directory roots plus the complete capture-derived changed-file set.
 - `prepare-tests`: discovers repository-native test files from the canonical capture and inventory, generates stable builder-owned test IDs, derives existing/added/modified status, and snapshots only added/modified live test sources.
 - `execute`: runs native project commands and owns `executions.json`, `receipts/`, and `raw/`. Each request uses exactly one binding mode: `test_ids`, `test_paths`, or `auto_bind=true`. The builder infers recognized package-wide or explicit file/directory/glob command scope, blocks opaque commands or mismatched declarations, and persists verified canonical `test_ids` only.
-- `finalize`: rechecks canonical capture freshness, blocks every selected unreliable execution, and owns manifest, stage hashes, verdict, generated-test snapshots, and evidence identity.
+- `finalize`: runs the pre-finalize semantic-record and required-layer checks, rechecks canonical capture freshness, blocks every selected unreliable execution, and owns manifest, stage hashes, verdict, generated-test snapshots, and evidence identity. If semantic records are incomplete or malformed, finalize fails before creating an immutable package; do not hand-edit a finalized package or start another package after a protocol budget is exhausted.
 - `render-report`: derives `test-report.md`; it is never authoritative.
 - `resume`: preserves prior receipts and refuses to rebind an identity-changing package; create a new package after scope/source identity changes.
 
 `test-plan.json` is the only source of builder-generated test IDs. An execution request provides exactly one of native `test_paths`, `auto_bind=true`, or canonical `test_ids`; the actual command must expose the same deterministic scope, including all prepared tests for recognized package-wide commands. The builder blocks opaque or mismatched command scope and rewrites verified requests to canonical `test_ids` only before execution. Assess all five layers explicitly, but set `required=true` only when risk requires it; every omitted layer needs structured N/A evidence. The same binding applies test ↔ behavior ↔ execution; current-workspace receipts are the execution evidence.
 
-The builder/validator, not the Main Agent, produces or updates `manifest.json`, `executions.json`, `receipts/*`, `validation.json`, `verdict.json`, `test-report.md`, and `source-change.patch`. `validation.json` is produced only by `validate_test_evidence.py --attest`; a package is not a `TEST_PASS` until the second strict validation succeeds.
+The builder/validator, not the Main Agent, produces or updates `manifest.json`, `executions.json`, `receipts/*`, `validation.json`, `verdict.json`, `test-report.md`, and `source-change.patch`. Semantic records are authored through schema-shaped requests and must pass the builder preflight before finalization. `validation.json` is produced only by `validate_test_evidence.py --attest`; a package is not a `TEST_PASS` until the second strict validation succeeds.
 
 
 For a formal requirement, `/prizmkit-test` runs after the Main-Agent code-review stage reaches `PASS` and before retrospective:
@@ -68,7 +68,8 @@ Documentation, comment, and formatting-only scopes use deterministic lightweight
 3. Preserve complete command/environment/output values as requested. Mark the package `sensitivity=project-controlled`; the project owns access control, retention, and upload policy.
 4. Treat code-level dependencies as mock-first. Real deployed test-environment validation is a separate authorized activity.
 5. Never delete existing tests.
-6. For `TEST_FAIL`, classify and persist an evidence-backed `repair_scope` of `test-infrastructure`, `production`, `runtime`, `schema`, `dependency`, `public-interface`, or `unknown`. Test-infrastructure scope routes to implement then test; production-family scope routes to implement, code-review, then test. If evidence cannot support a safe classification, return `TEST_BLOCKED`.
+6. Evidence-protocol recovery is separately bounded: allow at most two package initializations and two semantic preflight failures for one canonical change identity. After the budget is exhausted, return `TEST_BLOCKED`; do not create another versioned package or hand-edit finalized evidence.
+7. For `TEST_FAIL`, classify and persist an evidence-backed `repair_scope` of `test-infrastructure`, `production`, `runtime`, `schema`, `dependency`, `public-interface`, or `unknown`. Test-infrastructure scope routes to implement then test; production-family scope routes to implement, code-review, then test. If evidence cannot support a safe classification, return `TEST_BLOCKED`.
 
 If test infrastructure is missing, the infrastructure preparation state establishes only the necessary project-native infrastructure autonomously. Do not ask the user to install routine test dependencies in a headless run; verify dependency versions before editing manifests.
 
@@ -216,7 +217,7 @@ python3 ${SKILL_DIR}/scripts/validate_test_evidence.py \
   --project-root <target-project-root>
 ```
 
-If this pre-check finds errors, fix them in the package before the second pass. The validator checks every authoritative record against its shipped schema, live target inventories, patch/diff binding, changed-file/module-root/exclusion/Regression Ring cross-links, generated-test snapshots, planned-test execution links, runner-generated receipts/request/raw-output hashes, successful behavior-risk mappings, production/unknown external-target safety, and package integrity.
+If this pre-check finds errors, fix them only while the package remains mutable and before `finalize` relocates it to its content-addressed immutable directory. Never edit `manifest.json`, `verdict.json`, `validation.json`, or any semantic record after finalization. The validator checks every authoritative record against its shipped schema, live target inventories, patch/diff binding, changed-file/module-root/exclusion/Regression Ring cross-links, generated-test snapshots, planned-test execution links, runner-generated receipts/request/raw-output hashes, successful behavior-risk mappings, production/unknown external-target safety, and package integrity.
 
 **Second pass (attestation, with `--attest`):**
 
@@ -255,7 +256,7 @@ No conditional pass exists.
 
 Before writing state, read `${SKILL_DIR}/references/workflow-state-protocol.md`.
 
-On `TEST_PASS`, update the active workflow state with `status=TEST_PASS`, `stage_result=TEST_PASS`, and `next_stage=retrospective`. On `TEST_FAIL`, persist the evidence-backed `repair_scope`, set `status=TEST_FAIL` and `stage_result=TEST_FAIL`, and return to implementation; test-infrastructure scope selects `next_stage=implement` with a direct test resume, while production-family scope selects `next_stage=implement` and requires code review before testing again. On `TEST_BLOCKED`, preserve the blocker, do not modify production code speculatively, and return a blocked result. The authoritative verdict is the validated evidence record; the derived Markdown report is only a compatibility view. If an active orchestrator exists, return the terminal result and `next_stage` to it; do not invoke the next skill independently.
+On `TEST_PASS`, update the active workflow state with `status=TEST_PASS`, `stage_result=TEST_PASS`, and `next_stage=retrospective`. On `TEST_FAIL`, persist the evidence-backed `repair_scope`, set `status=TEST_FAIL` and `stage_result=TEST_FAIL`, and return to implementation; test-infrastructure scope selects `next_stage=implement` with a direct test resume, while production-family scope selects `next_stage=implement` and requires code review before testing again. On `TEST_BLOCKED`, preserve the blocker and any validated finalized evidence paths, do not modify production code speculatively, and return a blocked result. A validator `PASS` means only that the evidence package is structurally valid; it does not mean the testing verdict passed. The authoritative verdict is the validated evidence record; the derived Markdown report is only a compatibility view. If an active orchestrator exists, return the terminal result and `next_stage` to it; do not invoke the next skill independently.
 
 ## Derived Report and Handoff
 

package/bundled/skills/prizmkit-test/assets/evidence-package-template.json

@@ -8,6 +8,7 @@
     "execute",
     "finalize",
     "render-report",
+    "validate --attest",
     "resume"
   ],
   "generated_tests_policy": "Only added or modified repository-native tests are snapshotted; existing tests have no generated snapshot.",

package/bundled/skills/prizmkit-test/references/evidence-protocol.md

@@ -22,7 +22,10 @@ Hashes and validator receipts provide byte-level binding and drift detection, no
 
 `source-change.patch` preserves the complete target diff. Snapshot generated/changed tests under `generated-tests/`, contracts under `contracts/`, and raw stdout/stderr under `raw/`. Never replace old execution/output records.
 
-## Existing Tests and Package Finalization
+## Bounded Protocol Recovery
+
+Evidence-protocol repair is separate from production/test repair. The builder permits only a bounded recovery budget for semantic-record preflight and package initialization. After the budget is exhausted, return `TEST_BLOCKED`; do not create another versioned evidence package, copy requests from a finalized package, or hand-edit `manifest.json`, `verdict.json`, `validation.json`, receipts, hashes, or evidence IDs. A finalized package is immutable. `Evidence validation: PASS` means only that the package is structurally valid; the testing verdict must be read separately from `Testing verdict: TEST_PASS | TEST_FAIL | TEST_BLOCKED`.
+
 
 The evidence package is an audit of repository behavior, not a request to invent a parallel test suite. Discover and execute the smallest relevant native tests before adding anything. Add, modify, or delete tests only in the target repository. The builder's `prepare-tests` command derives stable test IDs and change status from canonical Git capture, and snapshots only added or modified repository-native tests. `generated-tests/` is an evidence archive, never an execution workspace; it may be empty when existing tests cover the behavior.
 

package/bundled/skills/prizmkit-test/references/evidence-request-protocol.md

@@ -15,7 +15,10 @@ The model writes project-semantic requests after inspecting manifests, runner co
 
 Never hand-author `executions.json` receipt fields. Never copy a command's claimed output into `raw/`. Invoke the builder so provenance is linked to the actual process.
 
-## Inventory Request
+## Producer Boundary and Recovery
+
+The model supplies schema-shaped semantic requests and mutable semantic records only before finalization. The builder performs preflight validation before creating an immutable package. Once `finalize` relocates a package to its content-addressed evidence ID, the returned `evidence_dir`, `manifest_path`, `verdict_path`, and `validation_path` are the only valid handoff paths; do not continue using the old staging directory. A validator pass is not a testing pass: read the testing verdict separately.
+
 
 Place a request under `requests/` with:
 

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

@@ -59,6 +59,8 @@ INVENTORY_RESERVED_ROOTS = (
 
 _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"
 
 
 class RequestError(Exception):
@@ -978,11 +980,14 @@ def run_capture_change(
 
 
 def run_init(project_root: Path, evidence_dir: Path, baseline: str | None, output_name: str) -> Path:
+    align_protocol_state(evidence_dir, protocol_run_key(project_root, baseline))
+    require_protocol_budget(evidence_dir, 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)
+    update_protocol_state(evidence_dir, 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", [])
@@ -1004,6 +1009,140 @@ def run_init(project_root: Path, evidence_dir: Path, baseline: str | None, outpu
     return output
 
 
+def protocol_state_path(evidence_dir: Path) -> Path:
+    # Keep recovery accounting outside each package so reinitializing v2/v3
+    # cannot reset the budget by choosing another evidence directory.
+    return evidence_dir.parent / PROTOCOL_STATE_NAME
+
+
+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 align_protocol_state(evidence_dir: Path, run_key: str) -> None:
+    state_path = protocol_state_path(evidence_dir)
+    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(
+    evidence_dir: Path,
+    *,
+    event: str,
+    error: str | None = None,
+    increment: str | None = None,
+) -> dict[str, Any]:
+    state_path = protocol_state_path(evidence_dir)
+    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(evidence_dir: Path, *, package_initialization: bool = False) -> None:
+    state_path = protocol_state_path(evidence_dir)
+    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 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 preflight_semantic_records(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"
+        )
+
+    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():
@@ -1337,6 +1476,7 @@ def write_handoff_pointer(evidence_dir: Path, artifact_dir: str | None, project_
 
 
 def run_finalize(project_root: Path, evidence_dir: Path, request: dict[str, Any], output_name: str) -> Path:
+    require_protocol_budget(evidence_dir)
     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)}")
@@ -1358,6 +1498,21 @@ def run_finalize(project_root: Path, evidence_dir: Path, request: dict[str, Any]
     change_class = request.get("change_class", "behavior")
     if change_class not in {"behavior", "lightweight"}:
         raise RequestError("change_class must be behavior or lightweight")
+    try:
+        preflight_semantic_records(evidence_dir, change_class)
+    except RequestError as exc:
+        state = update_protocol_state(
+            evidence_dir,
+            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")
@@ -1391,8 +1546,10 @@ def run_finalize(project_root: Path, evidence_dir: Path, request: dict[str, Any]
         "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",
@@ -1409,8 +1566,17 @@ def run_finalize(project_root: Path, evidence_dir: Path, request: dict[str, Any]
         if not (evidence_dir / relative).is_file()
     )
     if missing_records:
-        blockers.append(
-            "required evidence records are missing: " + ", ".join(missing_records)
+        state = update_protocol_state(
+            evidence_dir,
+            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
@@ -1472,13 +1638,15 @@ def run_finalize(project_root: Path, evidence_dir: Path, request: dict[str, Any]
         "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,
-        "manifest_path": "manifest.json",
-        "verdict_path": "verdict.json",
-        "report_path": "test-report.md",
-        "validation_path": "validation.json",
+        "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.
@@ -1488,7 +1656,6 @@ def run_finalize(project_root: Path, evidence_dir: Path, request: dict[str, Any]
         baseline_commit=baseline, final_verdict=verdict,
     )
     write_json_atomic(evidence_dir / "manifest.json", manifest)
-    destination = evidence_dir.parent / evidence_id
     if destination != evidence_dir:
         if destination.exists():
             try:
@@ -1502,8 +1669,14 @@ def run_finalize(project_root: Path, evidence_dir: Path, request: dict[str, Any]
                 f"evidence identity already exists at {destination}; re-init a new package"
             )
         os.replace(evidence_dir, destination)
-    write_handoff_pointer(destination, lifecycle.get("artifact_dir"), project_root)
-    return destination / output_name
+    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(
+        final_evidence_dir,
+        event="finalized",
+        error="; ".join(verdict_record.get("blockers", [])) if verdict == "TEST_BLOCKED" else None,
+    )
+    return final_evidence_dir / output_name
 
 
 def run_resume(

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

@@ -1179,9 +1179,32 @@ def validate_plan_and_scope_bindings(
     records_schema: dict[str, Any],
     errors: list[str],
 ) -> dict[str, dict[str, Any]]:
-    require(scope.get("affected_module") == matrix.get("affected_module", {}).get("name"), "matrix affected module does not match scope", errors)
-    require(scope.get("boundary_source") == matrix.get("affected_module", {}).get("boundary_source"), "matrix boundary source does not match scope", errors)
-    require(scope.get("primary_scope") == matrix.get("primary_scope"), "matrix primary scope does not match scope", errors)
+    if not isinstance(scope, dict):
+        errors.append("scope must be an object")
+    if not isinstance(matrix, dict):
+        errors.append("behavior-risk-matrix must be an object")
+    scope_module = scope.get("affected_module") if isinstance(scope, dict) else None
+    matrix_module = matrix.get("affected_module") if isinstance(matrix, dict) else None
+    matrix_module_name = matrix_module.get("name") if isinstance(matrix_module, dict) else None
+    matrix_boundary_source = matrix_module.get("boundary_source") if isinstance(matrix_module, dict) else None
+    require(
+        isinstance(scope_module, str) and scope_module == matrix_module_name,
+        "matrix affected module does not match scope",
+        errors,
+    )
+    require(
+        isinstance(scope.get("boundary_source") if isinstance(scope, dict) else None, str)
+        and scope.get("boundary_source") == matrix_boundary_source,
+        "matrix boundary source does not match scope",
+        errors,
+    )
+    require(
+        scope.get("primary_scope") == matrix.get("primary_scope") if isinstance(scope, dict) and isinstance(matrix, dict) else False,
+        "matrix primary scope does not match scope",
+        errors,
+    )
+    if not isinstance(scope, dict) or not isinstance(matrix, dict) or not isinstance(matrix_module, dict):
+        return {}
     scope_ring = sorted((item.get("name"), item.get("kind")) for item in scope.get("regression_ring", []) if isinstance(item, dict))
     matrix_ring = sorted((item.get("name"), item.get("kind")) for item in matrix.get("regression_ring", []) if isinstance(item, dict))
     require(scope_ring == matrix_ring, "scope and matrix regression rings do not agree", errors)
@@ -1609,17 +1632,21 @@ def validate_evidence(
             errors.append(str(exc))
             matrix = infrastructure = None
         if all(isinstance(item, dict) for item in (matrix, infrastructure, plan)):
+            matrix_error_count = len(errors)
             validate_schema(matrix, matrix_schema, matrix_schema, "behavior-risk-matrix", errors)
             validate_definition(infrastructure, "infrastructureChanges", records_schema, "infrastructure-changes", errors)
-            stages = {item.get("name"): item for item in manifest.get("stages", []) if isinstance(item, dict)}
-            for stage_name in CORE_BEHAVIOR_STAGES:
-                require(stages.get(stage_name, {}).get("status") == "complete", f"behavior protocol stage cannot be N/A: {stage_name}", errors)
-            test_map = validate_plan_and_scope_bindings(
-                root, project_root, manifest, scope, matrix, plan, inventory_by_category, entry_map,
-                executions, records_schema, errors,
-            )
-            validate_matrix_risks(manifest, matrix, test_map, executions, records_schema, errors)
-            validate_infrastructure(manifest, infrastructure, executions, entry_map, root, errors)
+            if len(errors) > matrix_error_count:
+                errors.append("behavior semantic cross-link validation skipped because behavior-risk-matrix schema validation failed")
+            else:
+                stages = {item.get("name"): item for item in manifest.get("stages", []) if isinstance(item, dict)}
+                for stage_name in CORE_BEHAVIOR_STAGES:
+                    require(stages.get(stage_name, {}).get("status") == "complete", f"behavior protocol stage cannot be N/A: {stage_name}", errors)
+                test_map = validate_plan_and_scope_bindings(
+                    root, project_root, manifest, scope, matrix, plan, inventory_by_category, entry_map,
+                    executions, records_schema, errors,
+                )
+                validate_matrix_risks(manifest, matrix, test_map, executions, records_schema, errors)
+                validate_infrastructure(manifest, infrastructure, executions, entry_map, root, errors)
         else:
             errors.append("behavior evidence records must be JSON objects")
     elif change_class == "lightweight":
@@ -1756,9 +1783,9 @@ def main() -> int:
                 print(f"- {error}")
             return 1
 
-    print("Test evidence validation: PASS")
+    print("Evidence validation: PASS")
+    print(f"Testing verdict: {manifest['final_verdict']}")
     print(f"Evidence ID: {manifest['evidence_id']}")
-    print(f"Verdict: {manifest['final_verdict']}")
     return 0
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prizmkit",
-  "version": "1.1.138",
+  "version": "1.1.139",
   "description": "Create a new PrizmKit-powered project with clean initialization — no framework dev files, just what you need.",
   "type": "module",
   "bin": {