prizmkit 1.1.130 → 1.1.134

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

@@ -38,6 +38,7 @@ LAYER_ORDER = {
     "regression-ring": 4,
 }
 FINAL_RECORDS = {"validation.json", "verdict.json", "test-report.md"}
+ATTESTATION_MUTABLE = {"validation.json"}
 COMMON_RECORDS = {
     "change-classification.json", "scope.json", "target-inventory.json",
     "environment.json", "executions.json", "verdict.json", "validation.json",
@@ -54,9 +55,13 @@ BLOCKED_EXTERNAL_CLASSES = {"production", "unknown"}
 SNAPSHOT_VOLATILE_ROOTS = (
     ".prizmkit/state",
     ".prizmkit/test/evidence",
+    ".prizmkit/" + "dev-" + "pipeline",
     ".claude/worktrees",
+    ".agents/worktrees",
+    ".codebuddy/worktrees",
+    ".codex/worktrees",
 )
-SNAPSHOT_VOLATILE_NAMES = {".git", "__pycache__"}
+SNAPSHOT_VOLATILE_NAMES = {".git", "__pycache__", ".pytest_cache", ".mypy_cache"}
 RISK_CONFLICT_PATTERNS = {
     "permission": re.compile(r"auth|tenant|role|permission|access|acl|rbac", re.I),
     "concurrency": re.compile(r"lock|shared[ _-]?state|worker|queue|concurr|parallel|race", re.I),
@@ -219,6 +224,18 @@ def validate_schema(
     """Validate the strict JSON-Schema subset used by skill-owned schemas."""
     schema = resolve_ref(schema, root_schema)
 
+    one_of = schema.get("oneOf")
+    if isinstance(one_of, list):
+        matching = 0
+        for branch in one_of:
+            if not isinstance(branch, dict):
+                continue
+            branch_errors: list[str] = []
+            validate_schema(value, branch, root_schema, location, branch_errors)
+            if not branch_errors:
+                matching += 1
+        require(matching == 1, f"{location}: value must match exactly one schema branch", errors)
+
     for child in schema.get("allOf", []):
         if isinstance(child, dict):
             validate_schema(value, child, root_schema, location, errors)
@@ -341,6 +358,31 @@ def require_manifest_entry(
     return path
 
 
+def validate_differential_na(
+    value: Any,
+    location: str,
+    errors: list[str],
+) -> None:
+    """Validate the differential-only N/A shape without weakening risk-cell N/A."""
+    if not isinstance(value, dict):
+        errors.append(f"{location}: differential N/A must be an object")
+        return
+    required = {"reason", "rationale", "evidence", "considered_signals", "conflicts"}
+    require(set(value) == required, f"{location}: differential N/A fields are incomplete", errors)
+    require(value.get("reason") in {"new-behavior", "textual-contract"}, f"{location}: invalid differential N/A reason", errors)
+    rationale = value.get("rationale")
+    require(isinstance(rationale, str) and len(rationale.strip()) >= 16, f"{location}: differential N/A rationale is too short", errors)
+    if value.get("reason") == "new-behavior" and isinstance(rationale, str):
+        require("no stable pre-change observable" in rationale.lower(), f"{location}: new behavior N/A lacks baseline rationale", errors)
+    if value.get("reason") == "textual-contract" and isinstance(rationale, str):
+        require("textual" in rationale.lower(), f"{location}: textual contract N/A lacks textual rationale", errors)
+    evidence = value.get("evidence")
+    require(isinstance(evidence, list) and bool(evidence) and all(isinstance(item, str) and item.strip() for item in evidence), f"{location}: differential N/A needs evidence strings", errors)
+    signals = value.get("considered_signals")
+    require(isinstance(signals, list) and bool(signals) and all(isinstance(item, str) and item.strip() for item in signals), f"{location}: differential N/A needs considered signals", errors)
+    require(isinstance(value.get("conflicts"), list), f"{location}: differential N/A conflicts must be an array", errors)
+
+
 def structured_na(
     value: Any,
     records_schema: dict[str, Any],
@@ -503,6 +545,25 @@ def validate_manifest(
     return entry_map
 
 
+def get_captured_deleted_paths(root: Path) -> set[str]:
+    capture_path = root / "change-capture.json"
+    if not capture_path.is_file():
+        return set()
+    try:
+        capture = load_json(capture_path)
+    except EvidenceError:
+        return set()
+    if not isinstance(capture, dict):
+        return set()
+    return {
+        item["path"]
+        for item in capture.get("changed_files", [])
+        if isinstance(item, dict)
+        and isinstance(item.get("path"), str)
+        and (item.get("status", "").strip() == "D" or item.get("role") == "source")
+    }
+
+
 def validate_inventory(
     root: Path,
     project_root: Path,
@@ -569,6 +630,7 @@ def validate_inventory(
         require(plan.get("plan_inputs") == plan_inputs, "test plan inputs do not match target inventory", errors)
 
     patch = require_manifest_entry("source-change.patch", entry_map, root, errors, "source-change patch")
+    captured_deleted_paths = get_captured_deleted_paths(root)
     if patch is not None:
         require(manifest.get("working_diff_sha256") == file_sha256(patch), "working_diff_sha256 does not match source-change.patch", errors)
 
@@ -579,7 +641,19 @@ def validate_inventory(
         request = load_json(request_path)
         if isinstance(request, dict):
             require(request.get("changed_files") == inventory.get("changed_files"), "inventory request changed_files mismatch", errors)
-            require(request.get("module_roots") == inventory.get("module_roots"), "inventory request module_roots mismatch", errors)
+            request_roots = request.get("module_roots")
+            normalized_request_roots = []
+            if isinstance(request_roots, list):
+                for item in request_roots:
+                    if isinstance(item, str):
+                        normalized_request_roots.append(item)
+                    elif isinstance(item, dict) and isinstance(item.get("path"), str):
+                        normalized_request_roots.append(item["path"])
+            require(
+                normalized_request_roots == inventory.get("module_roots"),
+                "inventory request module_roots mismatch",
+                errors,
+            )
             require(request.get("exclusions") == scope.get("exclusions"), "inventory request exclusions mismatch", errors)
             require(request.get("plan_inputs") == plan_inputs, "inventory request plan_inputs mismatch", errors)
         else:
@@ -594,6 +668,7 @@ def validate_scope(
     inventory_by_category: dict[str, dict[str, str]],
     project_root: Path,
     evidence_root: Path,
+    captured_deleted_paths: set[str],
     errors: list[str],
 ) -> None:
     changed_files = scope.get("changed_files")
@@ -614,8 +689,14 @@ def validate_scope(
         if relative in exclusion_paths:
             require(relative not in inventory_paths, f"excluded changed file is also inventoried: {relative}", errors)
         else:
-            require(candidate is not None and candidate.is_file(), f"changed file is not live: {relative}", errors)
-            require(relative in inventory_paths, f"changed file is neither inventoried nor excluded: {relative}", errors)
+            candidate = safe_path(project_root, relative, errors, "changed file")
+            deleted = relative in captured_deleted_paths
+            require(
+                deleted or (candidate is not None and candidate.is_file()),
+                f"changed file is not live: {relative}",
+                errors,
+            )
+            require(relative in inventory_paths or deleted, f"changed file is neither inventoried nor excluded: {relative}", errors)
 
     roots = scope.get("module_roots")
     require(isinstance(roots, list) and bool(roots), "scope module_roots is empty", errors)
@@ -695,7 +776,13 @@ def validate_requests_and_receipts(
             if not isinstance(request, dict):
                 errors.append(f"request must be an object: {relative}")
                 continue
-            if "execution_request" in request:
+            if request.get("method") == "not-applicable":
+                validate_definition(request, "differentialRequest", records_schema, relative, errors)
+                not_applicable = request.get("not_applicable")
+                if isinstance(not_applicable, dict):
+                    validate_differential_na(not_applicable, f"{relative}.not_applicable", errors)
+                differential_requests[relative] = request
+            elif "execution_request" in request:
                 validate_definition(request, "differentialRequest", records_schema, relative, errors)
                 nested = request.get("execution_request")
                 if isinstance(nested, dict):
@@ -707,6 +794,17 @@ def validate_requests_and_receipts(
                 validate_execution_request_semantics(request, relative, errors)
                 validate_external_targets(request.get("external_targets"), f"{relative}.external_targets", errors)
                 execution_requests[relative] = request
+            elif set(request) == {
+                "request_version", "change_class", "artifact_dir",
+            } or (
+                "request_version" in request
+                and "change_class" in request
+                and set(request) <= {
+                    "request_version", "change_class", "baseline_commit", "scope_path",
+                    "environment_path", "artifact_dir", "blockers", "repair_scope",
+                }
+            ):
+                require(request.get("request_version", "1.0") == "1.0", f"unsupported finalize request version: {relative}", errors)
             elif set(request) == {
                 "request_version", "categories", "changed_files", "module_roots",
                 "exclusions", "discovery_evidence", "plan_inputs",
@@ -922,12 +1020,18 @@ def validate_plan_and_scope_bindings(
         project_relative = test.get("project_path")
         inventory_relative = test.get("inventory_path")
         snapshot_relative = test.get("snapshot_path")
+        change_status = test.get("change_status", "modified" if isinstance(snapshot_relative, str) else "existing")
+        require(change_status in {"existing", "added", "modified"}, f"planned test has invalid change_status: {test_id}", errors)
         project_path = safe_path(project_root, project_relative, errors, f"planned test {test_id} project_path")
         require(project_path is not None and project_path.is_file(), f"planned test live path is missing: {test_id}", errors)
         require(inventory_relative == project_relative, f"planned test inventory path differs from live project path: {test_id}", errors)
         require(inventory_relative in inventory_by_category.get("tests", {}), f"planned test is not in the test inventory: {test_id}", errors)
-        snapshot_path = require_manifest_entry(snapshot_relative, entry_map, root, errors, f"planned test snapshot {test_id}") if isinstance(snapshot_relative, str) else None
-        require(isinstance(snapshot_relative, str) and path_under(snapshot_relative, "generated-tests"), f"planned test snapshot must be under generated-tests/: {test_id}", errors)
+        if change_status == "existing":
+            require(snapshot_relative is None, f"existing test must not have a generated snapshot: {test_id}", errors)
+            snapshot_path = None
+        else:
+            snapshot_path = require_manifest_entry(snapshot_relative, entry_map, root, errors, f"planned test snapshot {test_id}") if isinstance(snapshot_relative, str) else None
+            require(isinstance(snapshot_relative, str) and path_under(snapshot_relative, "generated-tests"), f"planned test snapshot must be under generated-tests/: {test_id}", errors)
         if project_path is not None and project_path.is_file() and snapshot_path is not None and snapshot_path.is_file():
             require(file_sha256(project_path) == file_sha256(snapshot_path), f"generated test snapshot differs from live test: {test_id}", errors)
         test_layers = test.get("layers")
@@ -1082,7 +1186,7 @@ def validate_differential_proofs(
             proof_by_behavior[behavior_id] = item
         classification = item.get("classification")
         if classification == "NOT_APPLICABLE":
-            structured_na(item.get("not_applicable"), records_schema, f"differential proof {behavior_id} not_applicable", errors)
+            validate_differential_na(item.get("not_applicable"), f"differential proof {behavior_id} not_applicable", errors)
             for key in (
                 "method", "differential_request_path", "differential_request_sha256", "baseline_commit",
                 "current_tree_sha256", "baseline_execution_id", "mutation_execution_id", "current_execution_id",
@@ -1245,6 +1349,13 @@ def validate_verdict_and_attestation(
         require(bool(verdict_record.get("blockers")), "TEST_BLOCKED lacks blocker reasons", errors)
     elif verdict == "TEST_FAIL":
         require(bool(verdict_record.get("reproduced_failures")), "TEST_FAIL lacks reproduced failures", errors)
+        require(
+            verdict_record.get("repair_scope") in {
+                "test-infrastructure", "production", "runtime", "schema", "dependency", "public-interface",
+            },
+            "TEST_FAIL lacks a valid evidence-backed repair_scope",
+            errors,
+        )
 
     if verify_attestation:
         validate_definition(validation, "validation", records_schema, "validation", errors)
@@ -1264,6 +1375,10 @@ def validate_verdict_and_attestation(
         require(validation.get("semantics") == "integrity-and-protocol-validation-not-hostile-producer-proof", "validation attestation semantics exceed integrity/protocol validation", errors)
         require(validation.get("replay_receipt_ids") == replayed_ids, "validation replay receipt IDs do not match actual replay executions", errors)
 
+    if root.joinpath("lifecycle.json").is_file():
+        expected_report = render_report_text(root, manifest, verdict_record, validation)
+        require(report == expected_report, "derived report does not match canonical rendering", errors)
+
     fragments = [
         f"Verdict: {verdict}", f"Evidence ID: {manifest.get('evidence_id')}",
         "Derived from structured evidence", "sensitivity=project-controlled",
@@ -1299,7 +1414,10 @@ def validate_evidence(
 
     entry_map = validate_manifest(root, manifest, manifest_schema, records_schema, errors, ignored_hash_paths)
     change_class = manifest.get("change_class")
-    required = COMMON_RECORDS | (BEHAVIOR_RECORDS if change_class == "behavior" else LIGHTWEIGHT_RECORDS)
+    final_verdict = manifest.get("final_verdict")
+    required = COMMON_RECORDS
+    if final_verdict != "TEST_BLOCKED":
+        required = required | (BEHAVIOR_RECORDS if change_class == "behavior" else LIGHTWEIGHT_RECORDS)
     for relative in required:
         require(relative in entry_map, f"required evidence record not hashed: {relative}", errors)
     validate_definition(classification, "changeClassification", records_schema, "change-classification", errors)
@@ -1322,7 +1440,10 @@ def validate_evidence(
 
     inventory_by_category, _ = validate_inventory(root, project_root, manifest, inventory, scope, plan, entry_map, errors)
     require(manifest.get("evidence_id_inputs", {}).get("scope_sha256") == canonical_sha256(scope), "scope identity hash mismatch", errors)
-    validate_scope(scope, inventory, inventory_by_category, project_root, root, errors)
+    validate_scope(
+        scope, inventory, inventory_by_category, project_root, root,
+        get_captured_deleted_paths(root), errors,
+    )
     execution_requests, differential_requests, executions = validate_requests_and_receipts(root, entry_map, records_schema, errors)
 
     if change_class == "behavior":
@@ -1373,6 +1494,64 @@ def validate_evidence(
     return errors
 
 
+def atomic_write_text(path: Path, value: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, temporary_name = tempfile.mkstemp(prefix=f".{path.name}.", suffix=".tmp", dir=path.parent)
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            handle.write(value)
+        os.replace(temporary_name, path)
+    except BaseException:
+        try:
+            os.unlink(temporary_name)
+        except FileNotFoundError:
+            pass
+        raise
+
+
+def render_report_text(
+    root: Path,
+    manifest: dict[str, Any],
+    verdict: dict[str, Any],
+    validation: dict[str, Any],
+) -> str:
+    lifecycle_path = root / "lifecycle.json"
+    lifecycle = load_json(lifecycle_path) if lifecycle_path.exists() else {}
+    proof_path = root / "differential-proof.json"
+    proof_record = load_json(proof_path) if proof_path.exists() else {}
+    executions_record = load_json(root / "executions.json")
+    proofs = proof_record.get("proofs", []) if isinstance(proof_record, dict) else []
+    executions = executions_record if isinstance(executions_record, list) else []
+    artifact_dir = lifecycle.get("artifact_dir") if isinstance(lifecycle, dict) else None
+    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', '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)}",
+        f"Differential proofs: {len(proofs) if isinstance(proofs, list) else 0}",
+        "The legacy test-report interface is not supported.",
+        "",
+    ]
+    return "\n".join(lines)
+
+
+def refresh_final_record_hashes(root: Path, manifest: dict[str, Any]) -> None:
+    for entry in manifest.get("files", []):
+        if isinstance(entry, dict) and entry.get("path") in FINAL_RECORDS:
+            entry["sha256"] = file_sha256(root / entry["path"])
+    atomic_write_json(root / "manifest.json", manifest)
+
+
 def main() -> int:
     parser = argparse.ArgumentParser(description="Validate a PrizmKit test evidence package")
     parser.add_argument("--evidence-dir", required=True, help="Path to .prizmkit/test/evidence/<evidence-id>")
@@ -1388,7 +1567,7 @@ def main() -> int:
     except IndexError:
         print("Test evidence validation: FAIL\n- cannot infer project root from evidence directory")
         return 1
-    errors = validate_evidence(root, project_root, FINAL_RECORDS if args.attest else None)
+    errors = validate_evidence(root, project_root, ATTESTATION_MUTABLE if args.attest else None)
     if errors:
         print("Test evidence validation: FAIL")
         for error in errors:
@@ -1396,6 +1575,7 @@ def main() -> int:
         return 1
 
     manifest = load_json(root / "manifest.json")
+    verdict_record = load_json(root / "verdict.json")
     if args.attest:
         executions = load_json(root / "executions.json")
         replayed_ids = [
@@ -1421,10 +1601,9 @@ def main() -> int:
             "replay_receipt_ids": replayed_ids,
         }
         atomic_write_json(root / "validation.json", validation)
-        for entry in manifest["files"]:
-            if entry["path"] in FINAL_RECORDS:
-                entry["sha256"] = file_sha256(root / entry["path"])
-        atomic_write_json(root / "manifest.json", manifest)
+        report_text = render_report_text(root, manifest, verdict_record, validation)
+        atomic_write_text(root / "test-report.md", report_text)
+        refresh_final_record_hashes(root, manifest)
         errors = validate_evidence(root, project_root)
         if errors:
             print("Test evidence validation: FAIL")

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

@@ -0,0 +1,266 @@
+---
+name: "prizmkit-workflow"
+description: "Coordinate one explicitly requested formal software requirement through the complete PrizmKit lifecycle from plan to confirmed commit. Use when the user invokes prizmkit-workflow or explicitly asks for the full six-stage lifecycle, a plan-to-commit workflow, or one formal requirement completed end to end. Do not trigger on generic build, implement, feature, bug, or refactor requests; those belong to the applicable individual skill or an external integration. (project)"
+---
+
+# PrizmKit Workflow
+
+`/prizmkit-workflow` is the optional composite entry point for one interactive formal software requirement. The user describes the requirement once; this skill coordinates the six atomic lifecycle skills in order and preserves the same requirement context throughout. It does not replace or reimplement any atomic stage.
+
+```text
+prizmkit-plan
+  → prizmkit-implement
+  → prizmkit-code-review
+  → prizmkit-test
+  → prizmkit-retrospective
+  → prizmkit-committer
+```
+
+The six stages are mandatory for a formal requirement. The order is not a suggestion and no stage is silently optional.
+
+## When to Use
+
+Use this composite entry point when the user:
+
+- explicitly invokes `/prizmkit-workflow`;
+- explicitly asks for the full six-stage PrizmKit lifecycle;
+- asks for one formal requirement to be coordinated from plan through commit;
+- asks for a plan-to-commit or single-requirement full lifecycle;
+- wants the workflow to continue automatically after each successful stage.
+
+Generic "implement", "build", "add feature", "fix bug", or "refactor" requests do not select this workflow by themselves. Use the applicable individual skill unless the user explicitly asks for this complete lifecycle; external integrations may also invoke individual skills through their published contracts.
+
+Use an individual atomic stage skill when the user explicitly wants only planning, implementation, review, testing, documentation maintenance, or committing.
+
+Do not use this skill for:
+
+- a typo, pure formatting change, or explicitly low-risk direct edit;
+- first-time project initialization only; recommend `/prizmkit-init`;
+- standalone Prizm documentation repair; use `/prizmkit-prizm-docs`;
+- deployment or operations; use `/prizmkit-deploy` separately;
+- multiple requirements in one invocation; this composite handles one requirement only.
+
+## Inputs
+
+Accept:
+
+- `description`: the natural-language formal requirement;
+- `artifact_dir`: optional explicit requirement artifact root;
+- `execution_mode`: `interactive` by default; headless only when a trusted host explicitly authorizes it;
+- `resume`: optional workflow state path or requirement slug for recovery.
+
+If `description` is missing and no resumable workflow is supplied, ask for the requirement before invoking `prizmkit-plan`. External automation must invoke atomic stages directly with its own execution checkpoint rather than nesting this composite workflow.
+
+## Core Orchestration Rules
+
+### 1. Start with Plan
+
+Invoke `/prizmkit-plan` with the requirement and any explicit `artifact_dir`. Do not write a second plan in this orchestrator.
+
+If initialization context is missing, allow `prizmkit-plan` to recommend initialization and continue with source fallback when the user chooses to proceed. Initialization is a soft prerequisite, not a hidden lifecycle stage.
+
+### 2. Preserve Requirement Identity
+
+Once `prizmkit-plan` resolves an `artifact_dir`, capture it and pass the exact same value to every later stage. The artifact root is generic and is not restricted to one directory family:
+
+```text
+.prizmkit/specs/<requirement-slug>/
+.prizmkit/bugfix/<bug-id>/
+.prizmkit/refactor/<refactor-id>/
+```
+
+Never select a different most-recent plan when resuming or handing off. The workflow state path is:
+
+```text
+.prizmkit/state/workflows/<requirement-slug>.json
+```
+
+Read `${SKILL_DIR}/references/workflow-state-protocol.md` for the shared state contract. This workflow state remains distinct from any external host execution checkpoint. The target project controls whether generated `.prizmkit/` files are committed, ignored, or shared; do not modify its Git policy.
+
+### 3. Advance Only on Truthful Success
+
+After each atomic stage:
+
+1. Read the stage's actual output and terminal status.
+2. Validate the expected authoritative artifact or evidence and workflow-state transition.
+3. Preserve the same `artifact_dir`.
+4. Continue only on the permitted success status.
+5. Because this composite is the active orchestrator, atomic skills return terminal state and `next_stage` to it; they must not invoke the next stage recursively.
+6. If the host cannot invoke another skill automatically, stop with exactly one deterministic next skill, its `artifact_dir`, and the workflow-state path.
+
+Expected transitions:
+
+| Stage | Required success | Next stage |
+|---|---|---|
+| `prizmkit-plan` | `PLAN_READY` | `prizmkit-implement` |
+| `prizmkit-implement` | `IMPLEMENTED` | `prizmkit-code-review` |
+| `prizmkit-code-review` | `REVIEW_PASS` | `prizmkit-test` |
+| `prizmkit-test` | `TEST_PASS` | `prizmkit-retrospective` |
+| `prizmkit-retrospective` | `status=RETRO_COMPLETE` with result `DOCS_UPDATED` or `NO_DOC_CHANGE` | `prizmkit-committer` |
+| `prizmkit-committer` | explicit interactive confirmation, then `COMMITTED` | end |
+
+`TEST_NOT_APPLICABLE` is not a valid lifecycle success. Lightweight changes must execute deterministic verification and return `TEST_PASS`.
+
+### 4. Do Not Duplicate Stage Responsibilities
+
+The composite must not:
+
+- reinterpret a plan as implementation;
+- repair production code outside `prizmkit-implement` or the Main-Agent review loop;
+- claim tests passed without validated authoritative test evidence;
+- treat a derived Markdown report as the test source of truth;
+- perform retrospective documentation changes itself;
+- stage or commit before `prizmkit-committer` applies the current execution's authorization boundary;
+- invoke `prizmkit-deploy` as a hidden seventh stage.
+
+## Failure and Repair Routing
+
+Use the shared workflow state and authoritative stage evidence to determine routing. Do not blindly retry every failure.
+
+### Review Failure
+
+`REVIEW_NEEDS_FIXES` maps from the final review report result `NEEDS_FIXES`. Route to:
+
+```text
+prizmkit-implement
+  → prizmkit-code-review
+  → prizmkit-test
+```
+
+The Main-Agent review skill owns its internal review repairs and its internal ten-round limit before returning its terminal result. The outer workflow repair counter is separate.
+
+### Test Failure
+
+`TEST_FAIL` must come from the validated authoritative evidence verdict and include `repair_scope`:
+
+TEST_FAIL affecting only tests, fixtures, test-runner configuration, or evidence infrastructure uses `repair_scope=test-infrastructure`:
+
+```text
+TEST_FAIL with repair_scope=test-infrastructure
+  → prizmkit-implement
+  → prizmkit-test
+```
+
+Test infrastructure includes tests, fixtures, test-runner configuration, and evidence infrastructure only.
+
+TEST_FAIL affecting production code, runtime configuration, schema, dependencies, or public interfaces uses the matching production-family scope:
+
+```text
+TEST_FAIL with repair_scope=production | runtime | schema | dependency | public-interface
+  → prizmkit-implement
+  → prizmkit-code-review
+  → prizmkit-test
+```
+
+Production-affecting repair after `REVIEW_PASS` must receive another review. A test-infrastructure-only repair may return directly to testing. Unknown scope uses the conservative production route only when safe; otherwise the workflow is blocked.
+
+### Environment Block
+
+`TEST_BLOCKED` means trustworthy evidence is unavailable because of environment, permission, dependency, external-service, scope, evidence, reliability, cleanup, or budget problems.
+
+Interactive behavior:
+
+```text
+TEST_BLOCKED
+  → persist the blocker
+  → do not make speculative production edits
+  → stop with a deterministic prizmkit-test resume entry
+```
+
+A trusted headless host performs its own bounded automatic environment recovery when invoking atomic stages. It does not invoke this composite workflow or silently turn a blocked result into success.
+
+### Repair Limit
+
+The outer orchestrator allows at most three automatic repair rounds. These are cross-stage rounds: one repair route from `implement` through all gates required by the repair scope.
+
+```text
+repair_round: 0 → 1 → 2 → 3
+```
+
+When the limit is reached:
+
+- set workflow status to `WORKFLOW_BLOCKED`;
+- preserve the latest authoritative failure evidence;
+- report completed rounds and unresolved cause;
+- report the exact skill, `artifact_dir`, and state path from which a user may resume after resolving the cause or explicitly authorizing another attempt;
+- do not claim the requirement is complete.
+
+The internal `prizmkit-code-review` limit of ten completed review rounds remains separate and does not increment `repair_round`.
+
+## Commit Authorization Boundary
+
+The composite may automatically reach `/prizmkit-committer`, but it must not silently create a Git commit.
+
+Interactive execution requires the committer to:
+
+1. verify all five preceding stage results for the same `artifact_dir`;
+2. inspect the final workspace;
+3. present intended files, diff summary, sensitive-file warnings, and the proposed Conventional Commit message;
+4. wait for explicit user confirmation from the current user;
+5. create and verify the local commit only after confirmation.
+
+Trusted headless execution is a separate atomic-stage path. It requires a host-defined non-interactive `mode`, a trusted `owner` identifier, and `local_commit_authorized=true`; it does not ask or wait. Unknown headless contexts are blocked. Remote publication is a separate host-runtime operation and is never decided by this composite workflow.
+
+## Automatic Handoff and Manual Fallback
+
+When the host supports semantic skill-to-skill invocation, the active composite invokes the next atomic stage after each permitted success transition.
+
+When it does not:
+
+1. update or verify workflow state;
+2. stop without claiming the next stage ran;
+3. print one exact recovery instruction:
+
+```text
+Next stage: /prizmkit-<skill>
+artifact_dir: <same resolved artifact_dir>
+workflow_state: .prizmkit/state/workflows/<requirement-slug>.json
+```
+
+The user can invoke that one atomic skill and this composite can resume with `resume` later.
+
+## Resume Protocol
+
+On resume:
+
+1. Read the workflow state specified by `resume` or discover the target project's active workflow state.
+2. Read `${SKILL_DIR}/references/workflow-state-protocol.md`.
+3. Verify `spec.md`, `plan.md`, review report, authoritative test evidence, retrospective result, and current workspace against state.
+4. If state is missing or stale, reconstruct the safest recoverable predecessor and report the reconstruction.
+5. Continue from the first incomplete stage; never bypass a required gate based only on stale state.
+6. Preserve the same `artifact_dir` and repair-round count.
+7. When an external host is involved, let it validate its own checkpoint independently; never merge that checkpoint into workflow state.
+
+## Completion Report
+
+At successful completion, report:
+
+```text
+WORKFLOW_COMPLETE
+artifact_dir: <path>
+stages:
+  - PLAN_READY
+  - IMPLEMENTED
+  - REVIEW_PASS
+  - TEST_PASS
+  - RETRO_COMPLETE (DOCS_UPDATED | NO_DOC_CHANGE)
+  - COMMITTED
+commit: <hash>
+push: not performed automatically
+next_action: invoke /prizmkit-deploy separately if deployment is needed
+```
+
+If the user declines interactive commit confirmation, report `COMMIT_PENDING` rather than `WORKFLOW_COMPLETE` and provide the exact `/prizmkit-committer` resume entry.
+
+If blocked, report:
+
+```text
+WORKFLOW_BLOCKED
+stage: <stage>
+reason: <evidence-backed reason>
+repair_round: <0..3>
+resume_from: <skill>
+artifact_dir: <same path>
+```
+
+Never report success for a stage that did not produce its required terminal result.