prizmkit 1.1.130 → 1.1.131

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

@@ -1,37 +1,29 @@
 #!/usr/bin/env python3
-"""Safely update a workflow-checkpoint.json step status.
-
-Instead of having the AI hand-write JSON, this script reads the checkpoint,
-validates the update, and writes it back atomically.
-
-Usage:
-  python3 update-checkpoint.py --checkpoint-path <path> --step <skill-or-id> --status <status>
-  python3 update-checkpoint.py --checkpoint-path <path> --step prizmkit-implement --status completed
-  python3 update-checkpoint.py --checkpoint-path <path> --step S04 --status in_progress
-  python3 update-checkpoint.py --checkpoint-path <path> --step prizmkit-code-review --status failed --note "max rounds exhausted"
-
-Exit codes:
-  0 = success
-  1 = validation error (step not found, invalid status, ambiguous skill, etc.)
-  2 = file error (not found, corrupted JSON)
-
-Output (stdout): JSON with {ok: true, step_id, skill, old_status, new_status} or {ok: false, error}
-"""
+"""Atomically update one semantic L4 workflow checkpoint."""
 
 import argparse
 import json
 import os
 import sys
 import tempfile
+from pathlib import Path
 
 _PIPELINE_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
 if _PIPELINE_ROOT not in sys.path:
     sys.path.insert(0, _PIPELINE_ROOT)
 
 from prizmkit_runtime.checkpoint_state import (  # noqa: E402
+    MAX_OUTER_REPAIR_ROUNDS,
+    REVIEW_RESULTS,
     STEP_ID_PATTERN,
+    TERMINAL_STEP_STATUSES,
+    TEST_RESULTS,
     VALID_CHECKPOINT_STATUSES,
+    VALID_REPAIR_SCOPES,
+    VALID_TERMINAL_STATUSES,
     load_checkpoint_state,
+    semantic_state_key,
+    validate_checkpoint_data,
 )
 
 VALID_STATUSES = VALID_CHECKPOINT_STATUSES
@@ -48,15 +40,15 @@ def _load_checkpoint(path):
     try:
         with open(path, "r", encoding="utf-8") as f:
             data = json.load(f)
-    except json.JSONDecodeError as e:
-        return None, "Corrupted JSON: {}".format(e)
-    except IOError as e:
-        return None, "Cannot read file: {}".format(e)
+    except json.JSONDecodeError as exc:
+        return None, "Corrupted JSON: {}".format(exc)
+    except IOError as exc:
+        return None, "Cannot read file: {}".format(exc)
     return data, None
 
 
 def _write_checkpoint(path, data):
-    """Write checkpoint JSON atomically using a temp file + rename."""
+    """Write checkpoint JSON atomically using a temp file and rename."""
     parent = os.path.dirname(os.path.abspath(path))
     if parent and not os.path.isdir(parent):
         os.makedirs(parent, exist_ok=True)
@@ -70,24 +62,24 @@ def _write_checkpoint(path, data):
             json.dump(data, f, indent=2, ensure_ascii=False)
             f.write("\n")
         os.replace(tmp_path, os.path.abspath(path))
-    except (IOError, OSError) as e:
+    except (IOError, OSError) as exc:
         if tmp_path is not None and os.path.exists(tmp_path):
             os.unlink(tmp_path)
-        return "Cannot write file: {}".format(e)
+        return "Cannot write file: {}".format(exc)
     return None
 
 
 def _find_step(steps, identifier):
     """Find a step by exact ID or unambiguous skill name."""
     if STEP_ID_PATTERN.match(identifier):
-        for i, step in enumerate(steps):
+        for index, step in enumerate(steps):
             if step.get("id") == identifier:
-                return i, step, None
+                return index, step, None
         return None, None, "Step '{}' not found.".format(identifier)
 
     matches = [
-        (i, step)
-        for i, step in enumerate(steps)
+        (index, step)
+        for index, step in enumerate(steps)
         if step.get("skill") == identifier
     ]
     if len(matches) == 1:
@@ -103,11 +95,161 @@ def _find_step(steps, identifier):
     return None, None, "Step '{}' not found.".format(identifier)
 
 
-def update_checkpoint(checkpoint_path, step_identifier, new_status, note=None):
-    """Update a single step's status in the checkpoint file.
+def _predecessors_terminal(steps, index):
+    return all(step.get("status") in TERMINAL_STEP_STATUSES for step in steps[:index])
+
+
+
+def _mandatory_predecessor_verdict_error(steps, index, workflow_type):
+    if workflow_type not in {"feature-pipeline", "bugfix-pipeline", "refactor-pipeline"}:
+        return None
+    preceding = steps[:index]
+    review = next((item for item in preceding if item.get("skill") == "prizmkit-code-review"), None)
+    test = next((item for item in preceding if item.get("skill") == "prizmkit-test"), None)
+    if review is None and test is None:
+        return None
+    skill = steps[index].get("skill")
+    if skill == "prizmkit-test":
+        if not review or review.get("status") != "completed" or review.get("stage_result") != "REVIEW_PASS":
+            return "Test stage requires a completed REVIEW_PASS predecessor"
+    if skill in {"prizmkit-retrospective", "prizmkit-committer", "completion-summary", "bug-report", "refactor-report"}:
+        if not review or review.get("status") != "completed" or review.get("stage_result") != "REVIEW_PASS":
+            return "Finalization requires a completed REVIEW_PASS predecessor"
+        if not test or test.get("status") != "completed" or test.get("stage_result") != "TEST_PASS":
+            return "Finalization requires a completed TEST_PASS predecessor"
+    return None
+
+def _normalize_semantic_update(semantic_update):
+    values = dict(semantic_update or {})
+    evidence = values.pop("authoritative_evidence_paths", None)
+    if evidence is not None:
+        evidence = {key: value for key, value in evidence.items() if value}
+        if evidence:
+            values["authoritative_evidence_paths"] = evidence
+    return {key: value for key, value in values.items() if value is not None}
+
+
+def _validate_semantic_update(step, semantic_update):
+    stage_result = semantic_update.get("stage_result")
+    skill = step.get("skill")
+    if stage_result in REVIEW_RESULTS and skill != "prizmkit-code-review":
+        return "Review verdicts may only be recorded on prizmkit-code-review"
+    if stage_result in TEST_RESULTS and skill != "prizmkit-test":
+        return "Test verdicts may only be recorded on prizmkit-test"
+    repair_scope = semantic_update.get("repair_scope")
+    if repair_scope is not None and repair_scope not in VALID_REPAIR_SCOPES:
+        return "Invalid repair_scope '{}'".format(repair_scope)
+    repair_round = semantic_update.get("repair_round")
+    if repair_round is not None and not 0 <= repair_round <= MAX_OUTER_REPAIR_ROUNDS:
+        return "repair_round must be between 0 and {}".format(MAX_OUTER_REPAIR_ROUNDS)
+    terminal_status = semantic_update.get("terminal_status")
+    if terminal_status is not None and terminal_status not in VALID_TERMINAL_STATUSES:
+        return "Invalid terminal_status '{}'".format(terminal_status)
+    evidence = semantic_update.get("authoritative_evidence_paths")
+    if evidence is not None and set(evidence) != {"manifest", "verdict", "validation"}:
+        return "Authoritative test evidence requires manifest, verdict, and validation paths"
+    if terminal_status == "WORKFLOW_BLOCKED" and not semantic_update.get("blocked_reason"):
+        return "WORKFLOW_BLOCKED requires blocked_reason"
+    return None
+
 
-    Returns a result dict: {ok, step_id, skill, old_status, new_status} or {ok, error}.
-    """
+def _apply_repair_policy(l4_state, stage_result, repair_scope):
+    if stage_result not in {"REVIEW_NEEDS_FIXES", "TEST_FAIL", "TEST_BLOCKED"}:
+        return
+    current_round = l4_state.get("repair_round", 0)
+    if not isinstance(current_round, int) or isinstance(current_round, bool):
+        current_round = MAX_OUTER_REPAIR_ROUNDS
+    if stage_result == "TEST_BLOCKED":
+        l4_state.update(
+            terminal_status="WORKFLOW_BLOCKED",
+            blocked_reason="test_blocked",
+            current_stage=None,
+            next_stage=None,
+        )
+        return
+    if current_round >= MAX_OUTER_REPAIR_ROUNDS:
+        l4_state.update(
+            repair_round=MAX_OUTER_REPAIR_ROUNDS,
+            terminal_status="WORKFLOW_BLOCKED",
+            blocked_reason="repair_round_limit",
+            current_stage=None,
+            next_stage=None,
+        )
+        return
+    if repair_scope not in VALID_REPAIR_SCOPES:
+        l4_state.update(
+            terminal_status="WORKFLOW_BLOCKED",
+            blocked_reason="unsafe_repair_scope",
+            current_stage=None,
+            next_stage=None,
+        )
+        return
+    l4_state["repair_round"] = current_round + 1
+    l4_state["terminal_status"] = None
+    l4_state["blocked_reason"] = None
+    l4_state["next_stage"] = "prizmkit-implement"
+
+
+def _sync_cursor(data, l4_state):
+    active = next(
+        (step for step in data["steps"] if step.get("status") not in TERMINAL_STEP_STATUSES),
+        None,
+    )
+    if l4_state.get("terminal_status"):
+        l4_state["current_stage"] = None
+        l4_state["next_stage"] = None
+        return
+    l4_state["current_stage"] = active.get("skill") if active else None
+    l4_state["next_stage"] = active.get("skill") if active else None
+
+
+
+
+def _checkpoint_project_root(checkpoint_path):
+    """Resolve the project root from a conventional .prizmkit checkpoint path."""
+    path = Path(os.path.abspath(checkpoint_path))
+    for parent in (path.parent, *path.parents):
+        if parent.name == ".prizmkit":
+            return str(parent.parent)
+    return str(path.parent)
+
+def _finalize_semantics(checkpoint_path, data, state_key):
+    """Derive a deterministic terminal status after an atomic mutation."""
+    candidate = validate_checkpoint_data(
+        data,
+        path=checkpoint_path,
+        exists=True,
+        project_root=_checkpoint_project_root(checkpoint_path),
+    )
+    l4_state = data[state_key]
+    if candidate.valid and candidate.semantic.completion_ready:
+        l4_state.update(
+            terminal_status="WORKFLOW_COMPLETED",
+            blocked_reason=None,
+            current_stage=None,
+            next_stage=None,
+        )
+        return
+    all_terminal = all(
+        step.get("status") in TERMINAL_STEP_STATUSES for step in data["steps"]
+    )
+    if all_terminal and not l4_state.get("terminal_status"):
+        l4_state.update(
+            terminal_status="WORKFLOW_BLOCKED",
+            blocked_reason=candidate.semantic.error_code or "incomplete_semantic_evidence",
+            current_stage=None,
+            next_stage=None,
+        )
+
+
+def update_checkpoint(
+    checkpoint_path,
+    step_identifier,
+    new_status,
+    note=None,
+    semantic_update=None,
+):
+    """Update one step and its cohesive semantic L4 state atomically."""
     if new_status not in VALID_STATUSES:
         return {
             "ok": False,
@@ -120,23 +262,106 @@ def update_checkpoint(checkpoint_path, step_identifier, new_status, note=None):
     if err:
         return {"ok": False, "error": err}
 
-    idx, step, find_error = _find_step(data["steps"], step_identifier)
+    index, step, find_error = _find_step(data["steps"], step_identifier)
     if step is None:
         available = [
-            "{} ({})".format(s.get("id", "?"), s.get("skill", "?"))
-            for s in data["steps"]
+            "{} ({})".format(item.get("id", "?"), item.get("skill", "?"))
+            for item in data["steps"]
         ]
         suffix = " Available: {}".format(", ".join(available)) if available else ""
+        return {"ok": False, "error": "{}{}".format(find_error or "Step not found.", suffix)}
+
+    if new_status in {"in_progress", "completed", "skipped"} and not _predecessors_terminal(data["steps"], index):
         return {
             "ok": False,
-            "error": "{}{}".format(find_error or "Step not found.", suffix),
+            "error": "Step '{}' cannot become {} before all predecessors are completed or skipped".format(
+                step.get("id"), new_status
+            ),
         }
+    if new_status in {"in_progress", "completed"}:
+        verdict_error = _mandatory_predecessor_verdict_error(
+            data["steps"], index, str(data.get("workflow_type") or "")
+        )
+        if verdict_error:
+            return {"ok": False, "error": verdict_error}
+
+    semantic_update = _normalize_semantic_update(semantic_update)
+    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 new_status == "completed" and step.get("skill") == "prizmkit-code-review":
+        stage_result = stage_result or step.get("stage_result")
+        if stage_result != "REVIEW_PASS":
+            return {"ok": False, "error": "Code Review completion requires REVIEW_PASS"}
+    if new_status == "completed" and step.get("skill") == "prizmkit-test":
+        stage_result = stage_result or step.get("stage_result")
+        if stage_result != "TEST_PASS":
+            return {"ok": False, "error": "Test completion requires TEST_PASS"}
+        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": "Test completion requires all authoritative evidence paths"}
 
     old_status = step.get("status", "unknown")
     step["status"] = new_status
-
     if note:
         step["note"] = note
+    if stage_result:
+        step["stage_result"] = stage_result
+    if semantic_update.get("authoritative_evidence_paths"):
+        step["authoritative_evidence_paths"] = semantic_update["authoritative_evidence_paths"]
+    if new_status == "completed" and step.get("skill") == "prizmkit-test":
+        candidate = validate_checkpoint_data(
+            data,
+            path=checkpoint_path,
+            exists=True,
+            project_root=_checkpoint_project_root(checkpoint_path),
+        )
+        if not candidate.valid or not candidate.semantic.evidence_valid:
+            return {
+                "ok": False,
+                "error": "Test completion requires validator-attested authoritative evidence",
+            }
+
+    workflow_type = str(data.get("workflow_type") or "")
+    state_key = semantic_state_key(workflow_type)
+    l4_state = data.setdefault(state_key, {})
+    if not isinstance(l4_state, dict):
+        return {"ok": False, "error": "Invalid semantic state object '{}'".format(state_key)}
+    for key in (
+        "stage_result",
+        "repair_scope",
+        "repair_round",
+        "authoritative_evidence_paths",
+        "blocked_reason",
+        "terminal_status",
+    ):
+        if key in semantic_update:
+            l4_state[key] = semantic_update[key]
+    l4_state["schema_version"] = 1
+    l4_state["orchestrator"] = "prizmkit-l4"
+    if stage_result:
+        l4_state["stage_result"] = stage_result
+    if semantic_update.get("authoritative_evidence_paths"):
+        l4_state["authoritative_evidence_paths"] = semantic_update["authoritative_evidence_paths"]
+    _apply_repair_policy(l4_state, stage_result, semantic_update.get("repair_scope") or l4_state.get("repair_scope"))
+    _sync_cursor(data, l4_state)
+    _finalize_semantics(checkpoint_path, data, state_key)
+
+    final_state = validate_checkpoint_data(
+        data,
+        path=checkpoint_path,
+        exists=True,
+        project_root=_checkpoint_project_root(checkpoint_path),
+    )
+    if not final_state.valid:
+        return {
+            "ok": False,
+            "error": "Update would create invalid checkpoint ({}): {}".format(
+                final_state.error_code, final_state.error_message
+            ),
+        }
 
     err = _write_checkpoint(checkpoint_path, data)
     if err:
@@ -148,46 +373,46 @@ def update_checkpoint(checkpoint_path, step_identifier, new_status, note=None):
         "skill": step.get("skill"),
         "old_status": old_status,
         "new_status": new_status,
+        "semantic": final_state.semantic_snapshot,
     }
 
 
 def main():
     parser = argparse.ArgumentParser(
-        description="Safely update a workflow-checkpoint.json step status.",
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-        epilog=(
-            "Examples:\n"
-            "  %(prog)s --checkpoint-path .prizmkit/specs/my-feature/workflow-checkpoint.json "
-            "--step prizmkit-implement --status completed\n"
-            "  %(prog)s --checkpoint-path .prizmkit/bugfix/B-001/workflow-checkpoint.json "
-            "--step S04 --status in_progress\n"
-            "  %(prog)s --checkpoint-path .prizmkit/refactor/R-001/workflow-checkpoint.json "
-            "--step prizmkit-code-review --status failed --note 'max rounds exhausted'"
-        ),
-    )
-    parser.add_argument(
-        "--checkpoint-path", required=True, help="Path to workflow-checkpoint.json"
-    )
-    parser.add_argument(
-        "--step",
-        required=True,
-        help="Step identifier (skill name like 'prizmkit-implement' or step ID like 'S04')",
-    )
-    parser.add_argument(
-        "--status",
-        required=True,
-        choices=sorted(VALID_STATUSES),
-        help="New status for the step",
-    )
-    parser.add_argument(
-        "--note",
-        default=None,
-        help="Optional note to attach to the step (e.g., failure reason)",
+        description="Safely update a semantic workflow-checkpoint.json step status."
     )
+    parser.add_argument("--checkpoint-path", required=True)
+    parser.add_argument("--step", required=True)
+    parser.add_argument("--status", required=True, choices=sorted(VALID_STATUSES))
+    parser.add_argument("--note", default=None)
+    parser.add_argument("--stage-result", choices=sorted(REVIEW_RESULTS | TEST_RESULTS), default=None)
+    parser.add_argument("--repair-scope", choices=sorted(VALID_REPAIR_SCOPES), default=None)
+    parser.add_argument("--repair-round", type=int, default=None)
+    parser.add_argument("--manifest-path", default=None)
+    parser.add_argument("--verdict-path", default=None)
+    parser.add_argument("--validation-path", default=None)
+    parser.add_argument("--blocked-reason", default=None)
+    parser.add_argument("--terminal-status", choices=sorted(VALID_TERMINAL_STATUSES), default=None)
 
     args = parser.parse_args()
+    semantic_update = {
+        "stage_result": args.stage_result,
+        "repair_scope": args.repair_scope,
+        "repair_round": args.repair_round,
+        "authoritative_evidence_paths": {
+            "manifest": args.manifest_path,
+            "verdict": args.verdict_path,
+            "validation": args.validation_path,
+        },
+        "blocked_reason": args.blocked_reason,
+        "terminal_status": args.terminal_status,
+    }
     result = update_checkpoint(
-        args.checkpoint_path, args.step, args.status, args.note
+        args.checkpoint_path,
+        args.step,
+        args.status,
+        args.note,
+        semantic_update,
     )
     print(json.dumps(result, indent=2, ensure_ascii=False))
     error = result.get("error", "")

package/bundled/dev-pipeline/scripts/update-feature-status.py

@@ -50,6 +50,7 @@ SESSION_STATUS_VALUES = [
     "infra_error",
     "context_overflow",
     "stalled_context_continuation",
+    "workflow_blocked",
     "commit_missing",
     "docs_missing",
     "merge_conflict",
@@ -152,6 +153,11 @@ def parse_args():
         default=None,
         help="JSON progress fingerprint captured after the session.",
     )
+    parser.add_argument(
+        "--checkpoint-state",
+        default=None,
+        help="JSON semantic L4 checkpoint snapshot captured after the session.",
+    )
     return parser.parse_args()
 
 
@@ -358,6 +364,37 @@ def _load_progress_fingerprint(raw):
         return {"unparsed": str(raw)}
 
 
+SEMANTIC_CHECKPOINT_FIELDS = (
+    "current_stage",
+    "next_stage",
+    "stage_result",
+    "repair_scope",
+    "repair_round",
+    "authoritative_evidence_paths",
+    "blocked_reason",
+    "terminal_status",
+)
+
+
+def _load_checkpoint_state(raw):
+    if not raw:
+        return {}
+    try:
+        data = json.loads(raw)
+    except (TypeError, ValueError):
+        return {}
+    if not isinstance(data, dict):
+        return {}
+    return {key: data.get(key) for key in SEMANTIC_CHECKPOINT_FIELDS}
+
+
+def _sync_semantic_checkpoint(status_data, args):
+    semantic = _load_checkpoint_state(getattr(args, "checkpoint_state", None))
+    if semantic:
+        status_data.update(semantic)
+    return {key: status_data.get(key) for key in SEMANTIC_CHECKPOINT_FIELDS}
+
+
 def _set_continuation_common(status_data, args, session_id):
     if args.active_dev_branch:
         status_data["active_dev_branch"] = args.active_dev_branch
@@ -886,6 +923,7 @@ def action_update(args, feature_list_path, state_dir):
     fingerprint = _load_progress_fingerprint(args.progress_fingerprint)
     if fingerprint is not None:
         fs["last_progress_fingerprint"] = fingerprint
+    semantic_checkpoint = _sync_semantic_checkpoint(fs, args)
 
 
     if session_status == "success":
@@ -984,6 +1022,19 @@ def action_update(args, feature_list_path, state_dir):
             if err:
                 error_out("Failed to update .prizmkit/plans/feature-list.json: {}".format(err))
                 return
+    elif session_status == "workflow_blocked":
+        # Semantic terminal state: preserve partial work without consuming any retry budget.
+        new_status = "failed"
+        fs["continuation_pending"] = False
+        fs["needs_attention"] = True
+        fs["terminal_status"] = "WORKFLOW_BLOCKED"
+        fs["blocked_reason"] = (
+            semantic_checkpoint.get("blocked_reason") or "workflow_blocked"
+        )
+        err = update_feature_in_list(feature_list_path, feature_id, new_status)
+        if err:
+            error_out("Failed to update .prizmkit/plans/feature-list.json: {}".format(err))
+            return
     elif session_status == "stalled_context_continuation":
         # No-progress context-overflow stall pauses automation without consuming retry budgets.
         set_stalled_context_continuation_metadata(fs, args, session_id)
@@ -1052,6 +1103,7 @@ def action_update(args, feature_list_path, state_dir):
         "infra_error_count": fs.get("infra_error_count", 0),
         "max_infra_retries": max_infra_retries,
         "resume_from_phase": fs.get("resume_from_phase"),
+        "checkpoint_state": semantic_checkpoint,
         "updated_at": fs["updated_at"],
     }
     if auto_skipped_features:
@@ -1068,6 +1120,11 @@ def action_update(args, feature_list_path, state_dir):
         summary["restart_policy"] = "context_overflow_continuation"
         summary.update(continuation_metadata_summary(fs))
         summary["artifacts_preserved"] = True
+    elif session_status == "workflow_blocked":
+        summary["restart_policy"] = "terminal_blocked"
+        summary.update(continuation_metadata_summary(fs))
+        summary["checkpoint_state"] = semantic_checkpoint
+        summary["artifacts_preserved"] = True
     elif session_status == "stalled_context_continuation":
         summary["restart_policy"] = "needs_attention"
         summary.update(continuation_metadata_summary(fs))

package/bundled/dev-pipeline/scripts/update-refactor-status.py

@@ -47,6 +47,7 @@ SESSION_STATUS_VALUES = [
     "infra_error",
     "context_overflow",
     "stalled_context_continuation",
+    "workflow_blocked",
     "commit_missing",
     "docs_missing",
     "merge_conflict",
@@ -100,6 +101,7 @@ def parse_args():
     parser.add_argument("--continuation-summary-path", default=None, help="Optional continuation summary artifact path.")
     parser.add_argument("--no-progress-count", type=int, default=None, help="Consecutive context-overflow sessions without objective progress.")
     parser.add_argument("--progress-fingerprint", default=None, help="JSON progress fingerprint captured after the session.")
+    parser.add_argument("--checkpoint-state", default=None, help="JSON semantic L4 checkpoint snapshot captured after the session.")
     return parser.parse_args()
 
 
@@ -252,6 +254,37 @@ def _load_progress_fingerprint(raw):
         return {"unparsed": str(raw)}
 
 
+SEMANTIC_CHECKPOINT_FIELDS = (
+    "current_stage",
+    "next_stage",
+    "stage_result",
+    "repair_scope",
+    "repair_round",
+    "authoritative_evidence_paths",
+    "blocked_reason",
+    "terminal_status",
+)
+
+
+def _load_checkpoint_state(raw):
+    if not raw:
+        return {}
+    try:
+        data = json.loads(raw)
+    except (TypeError, ValueError):
+        return {}
+    if not isinstance(data, dict):
+        return {}
+    return {key: data.get(key) for key in SEMANTIC_CHECKPOINT_FIELDS}
+
+
+def _sync_semantic_checkpoint(status_data, args):
+    semantic = _load_checkpoint_state(getattr(args, "checkpoint_state", None))
+    if semantic:
+        status_data.update(semantic)
+    return {key: status_data.get(key) for key in SEMANTIC_CHECKPOINT_FIELDS}
+
+
 def _set_continuation_common(status_data, args, session_id):
     if args.active_dev_branch:
         status_data["active_dev_branch"] = args.active_dev_branch
@@ -498,6 +531,7 @@ def action_update(args, refactor_list_path, state_dir):
     fingerprint = _load_progress_fingerprint(args.progress_fingerprint)
     if fingerprint is not None:
         rs["last_progress_fingerprint"] = fingerprint
+    semantic_checkpoint = _sync_semantic_checkpoint(rs, args)
 
 
     if session_status == "success":
@@ -564,6 +598,19 @@ def action_update(args, refactor_list_path, state_dir):
             if err:
                 error_out("Failed to update .prizmkit/plans/refactor-list.json: {}".format(err))
                 return
+    elif session_status == "workflow_blocked":
+        # Semantic terminal state: preserve partial work without consuming any retry budget.
+        new_status = "failed"
+        rs["continuation_pending"] = False
+        rs["needs_attention"] = True
+        rs["terminal_status"] = "WORKFLOW_BLOCKED"
+        rs["blocked_reason"] = (
+            semantic_checkpoint.get("blocked_reason") or "workflow_blocked"
+        )
+        err = update_refactor_in_list(refactor_list_path, refactor_id, new_status)
+        if err:
+            error_out("Failed to update .prizmkit/plans/refactor-list.json: {}".format(err))
+            return
     elif session_status == "stalled_context_continuation":
         # No-progress context-overflow stall pauses automation without consuming retry budgets.
         set_stalled_context_continuation_metadata(rs, args, session_id)
@@ -627,6 +674,7 @@ def action_update(args, refactor_list_path, state_dir):
         "infra_error_count": rs.get("infra_error_count", 0),
         "max_infra_retries": max_infra_retries,
         "resume_from_phase": rs.get("resume_from_phase"),
+        "checkpoint_state": semantic_checkpoint,
         "updated_at": rs["updated_at"],
     }
     if auto_skipped_refactors:
@@ -643,6 +691,11 @@ def action_update(args, refactor_list_path, state_dir):
         summary["restart_policy"] = "context_overflow_continuation"
         summary.update(continuation_metadata_summary(rs))
         summary["artifacts_preserved"] = True
+    elif session_status == "workflow_blocked":
+        summary["restart_policy"] = "terminal_blocked"
+        summary.update(continuation_metadata_summary(rs))
+        summary["checkpoint_state"] = semantic_checkpoint
+        summary["artifacts_preserved"] = True
     elif session_status == "stalled_context_continuation":
         summary["restart_policy"] = "needs_attention"
         summary.update(continuation_metadata_summary(rs))

package/bundled/dev-pipeline/templates/bootstrap-prompt.md

@@ -30,9 +30,9 @@ Infer what needs to be done from the feature context above and follow the standa
 
 3. **Implement**: Run `/prizmkit-implement` with `artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` to execute the plan using TDD (write tests first, then implement).
 
-4. **Review**: Run `/prizmkit-code-review` with `artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/`. The current Main Agent is the only Code Review executor. It reviews the complete current change for up to ten rounds, directly repairs accepted findings, verifies repairs, and converges when accepted and unresolved findings are both zero. Do not delegate review directly or indirectly, invoke another review skill/workflow, or relabel delegated work as a finder, verifier, audit, compatibility review, verification, or gap sweep. `review-report.md` is the only persisted review artifact. Require the last `## Final Result` verdict before continuing.
+4. **Review**: Run `/prizmkit-code-review` with `artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/`. The current Main Agent is the only Code Review executor. It reviews the complete current change for up to ten internal rounds, directly repairs accepted findings, and requires the last `## Final Result`. `REVIEW_PASS` proceeds to test; `REVIEW_NEEDS_FIXES` increments the shared outer repair round and routes implement → code-review → test. Do not delegate review or use another review entry point.
 
-5. **Test**: Run `/prizmkit-test scope=this-change artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` to generate and verify tests only for this feature's changed scope after review. Do not use bugfix/refactor artifact directories for this gate.
+5. **Test**: After review passes, run `/prizmkit-test scope=this-change artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/`. Treat the Markdown report only as a derived view. Consume `.prizmkit/test/evidence/<evidence-id>/manifest.json`, `verdict.json`, and `validation.json`; verify identity/scope, every manifest hash, verdict/validator agreement, and current target hashes before accepting `TEST_PASS`. `TEST_FAIL/test-infrastructure` routes implement → test; production/runtime/schema/dependency/public-interface routes implement → code-review → test; unknown unsafe scope blocks. `TEST_BLOCKED` allows bounded environment recovery or a test-stage resume but never speculative production edits. Stop outer repairs after three rounds; preserve evidence and truthful recovery metadata.
 
 6. **Retrospective**: Run `/prizmkit-retrospective` to sync `.prizmkit/prizm-docs/` with code changes.