prizmkit 1.1.153 → 1.1.155

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

@@ -9,12 +9,12 @@ Handles eight actions:
   - pause: Save pipeline state for graceful shutdown
   - reset: Reset a bug to pending (status + retry count)
   - clean: Reset + delete session history + delete bugfix artifacts
-  - unskip: Reset skipped bugs back to pending
+  - reset_state: Recover blocking roots and causally recoverable auto-skipped descendants
 
 Usage:
     python3 update-bug-status.py \
         --bug-list <path> --state-dir <path> \
-        --action <get_next|start|update|status|pause|reset|clean|unskip> \
+        --action <get_next|start|update|status|pause|reset|clean|reset_state> \
         [--bug-id <id>] [--session-status <status>] \
         [--session-id <id>] [--max-retries <n>] [--max-infra-retries <n>]
 """
@@ -23,6 +23,7 @@ import argparse
 import json
 import os
 import shutil
+import sys
 from datetime import datetime, timezone
 
 from utils import (
@@ -33,6 +34,7 @@ from utils import (
     _build_progress_bar,
     read_checkpoint_cursor,
     dependency_rank_map,
+    causal_reset_selection,
 )
 
 
@@ -53,7 +55,8 @@ SESSION_STATUS_VALUES = [
     "merge_conflict",
 ]
 
-TERMINAL_STATUSES = {"completed", "failed", "skipped", "needs_info"}
+TERMINAL_STATUSES = {"completed", "failed", "skipped", "needs_info", "auto_skipped"}
+RESET_BLOCKING_ROOT_STATUSES = {"failed", "skipped", "needs_info"}
 
 # Severity priority (lower value = higher priority)
 SEVERITY_PRIORITY = {
@@ -72,7 +75,7 @@ def parse_args():
     parser.add_argument("--state-dir", required=True, help="Path to the state directory (default: .prizmkit/state/bugfix)")
     parser.add_argument(
         "--action", required=True,
-        choices=["get_next", "start", "update", "status", "pause", "reset", "clean", "unskip", "complete"],
+        choices=["get_next", "start", "update", "status", "pause", "reset", "clean", "reset_state", "complete"],
         help="Action to perform",
     )
     parser.add_argument("--bug-id", default=None, help="Bug ID (required for 'update'/'reset'/'clean' actions)")
@@ -383,19 +386,117 @@ def continuation_metadata_summary(status_data):
     }
 
 
+# ---------------------------------------------------------------------------
+# Auto-skip: cascade terminal blockers to pending downstream bugs
+# ---------------------------------------------------------------------------
+
+def auto_skip_blocked_bugs(bug_list_path, state_dir, blocking_bug_id=None):
+    """Mark pending descendants of terminal Bugfix blockers as auto_skipped."""
+    data, err = load_json_file(bug_list_path)
+    if err:
+        error_out("Cannot load bug fix list for auto-skip: {}".format(err))
+        return []
+    bugs = data.get("bugs", [])
+    status_map = {
+        bug.get("id"): bug.get("status", "pending")
+        for bug in bugs
+        if isinstance(bug, dict) and bug.get("id")
+    }
+
+    to_skip = set()
+    changed = True
+    while changed:
+        changed = False
+        for bug in bugs:
+            if not isinstance(bug, dict):
+                continue
+            bug_id = bug.get("id")
+            if not bug_id or bug_id in to_skip:
+                continue
+            if status_map.get(bug_id, "pending") != "pending":
+                continue
+            dependencies = bug.get("dependencies", [])
+            if not isinstance(dependencies, list):
+                continue
+            if any(
+                status_map.get(dependency_id, "pending")
+                in RESET_BLOCKING_ROOT_STATUSES | {"auto_skipped"}
+                or dependency_id in to_skip
+                for dependency_id in dependencies
+            ):
+                to_skip.add(bug_id)
+                status_map[bug_id] = "auto_skipped"
+                changed = True
+
+    if not to_skip:
+        return []
+
+    for bug in bugs:
+        if isinstance(bug, dict) and bug.get("id") in to_skip:
+            bug["status"] = "auto_skipped"
+    err = write_json_file(bug_list_path, data)
+    if err:
+        error_out("Failed to write auto-skipped bugs: {}".format(err))
+        return []
+
+    for bug_id in to_skip:
+        bs = load_bug_status(state_dir, bug_id)
+        bs["updated_at"] = now_iso()
+        err = save_bug_status(state_dir, bug_id, bs)
+        if err:
+            error_out("Failed to save auto-skipped bug status: {}".format(err))
+            return []
+
+    skipped_info = []
+    for bug in bugs:
+        if not isinstance(bug, dict) or bug.get("id") not in to_skip:
+            continue
+        dependencies = bug.get("dependencies", [])
+        blockers = [
+            dependency_id
+            for dependency_id in dependencies
+            if dependency_id == blocking_bug_id
+            or status_map.get(dependency_id, "pending")
+            in RESET_BLOCKING_ROOT_STATUSES | {"auto_skipped"}
+        ]
+        skipped_info.append({
+            "bug_id": bug["id"],
+            "title": bug.get("title", ""),
+            "blocked_by": blockers,
+        })
+
+    cause = blocking_bug_id or "existing terminal blockers"
+    print(
+        "[auto-skip] {} bug(s) auto-skipped due to {}".format(
+            len(skipped_info), cause
+        ),
+        file=sys.stderr,
+    )
+    return skipped_info
+
+
 # ---------------------------------------------------------------------------
 # Action: get_next
 # ---------------------------------------------------------------------------
 
-def action_get_next(bug_list_data, state_dir, project_root=None):
+def action_get_next(bug_list_data, state_dir, project_root=None, bug_list_path=None):
     """Find the next bug to process.
 
     Priority logic:
-    1. Skip terminal statuses (completed, failed, skipped, needs_info)
-    2. Only consider bugs whose dependencies are all completed
-    3. Prefer in_progress bugs (interrupted session resume) over pending
-    4. Within each status class, use stable topological list order
+    1. Lazily normalize pending descendants of terminal blockers to auto_skipped
+    2. Skip terminal statuses (completed, failed, skipped, needs_info, auto_skipped)
+    3. Only consider bugs whose dependencies are all completed
+    4. Prefer in_progress bugs (interrupted session resume) over pending
+    5. Within each status class, use stable topological list order
     """
+    if bug_list_path:
+        auto_skip_blocked_bugs(bug_list_path, state_dir)
+        refreshed, refresh_error = load_json_file(bug_list_path)
+        if refresh_error:
+            error_out("Cannot reload bug fix list after auto-skip: {}".format(refresh_error))
+            return
+        bug_list_data = refreshed
+
     bugs = bug_list_data.get("bugs", [])
     if not bugs:
         print("PIPELINE_COMPLETE")
@@ -513,6 +614,8 @@ def action_update(args, bug_list_path, state_dir):
     bs = load_bug_status(state_dir, bug_id)
 
     current_list_status = get_bug_status_from_list(bug_list_path, bug_id)
+    bs["max_retries"] = max_retries
+    bs["max_infra_retries"] = max_infra_retries
 
     # Track what status we write to bug-fix-list.json
     new_status = current_list_status
@@ -677,6 +780,12 @@ def action_update(args, bug_list_path, state_dir):
         error_out("Failed to save bug status: {}".format(err))
         return
 
+    auto_skipped_bugs = []
+    if new_status in RESET_BLOCKING_ROOT_STATUSES:
+        auto_skipped_bugs = auto_skip_blocked_bugs(
+            bug_list_path, state_dir, bug_id
+        )
+
     summary = {
         "action": "update",
         "bug_id": bug_id,
@@ -689,6 +798,8 @@ def action_update(args, bug_list_path, state_dir):
         "checkpoint_state": semantic_checkpoint,
         "updated_at": bs["updated_at"],
     }
+    if auto_skipped_bugs:
+        summary["auto_skipped"] = [info["bug_id"] for info in auto_skipped_bugs]
     if session_status in ("commit_missing", "docs_missing", "merge_conflict"):
         summary["degraded_reason"] = session_status
         summary["restart_policy"] = "finalization_retry"
@@ -863,7 +974,20 @@ def action_status(bug_list_data, state_dir, project_root=None):
     project_name = bug_list_data.get("project_name", "Unknown")
     project_root = os.path.abspath(project_root) if project_root else _default_project_root()
 
-    counts = {"completed": 0, "in_progress": 0, "failed": 0, "pending": 0, "needs_info": 0, "skipped": 0}
+    counts = {
+        "completed": 0,
+        "in_progress": 0,
+        "failed": 0,
+        "pending": 0,
+        "needs_info": 0,
+        "skipped": 0,
+        "auto_skipped": 0,
+    }
+    status_map = {
+        bug.get("id"): bug.get("status", "pending")
+        for bug in bugs
+        if isinstance(bug, dict) and bug.get("id")
+    }
     bug_lines = []
 
     for bug in bugs:
@@ -879,11 +1003,8 @@ def action_status(bug_list_data, state_dir, project_root=None):
         bs = load_bug_status(state_dir, bid)
         retry_count = bs.get("retry_count", 0)
         max_retries_val = bs.get("max_retries", 3)
-        # Read phase cursor from checkpoint (authoritative when valid).
+        # Read the authoritative checkpoint cursor without mutating cached runtime state.
         resume_phase = _checkpoint_phase_or_cached(project_root, bid, bs)
-        if resume_phase != bs.get("resume_from_phase"):
-            bs["resume_from_phase"] = resume_phase
-            save_bug_status(state_dir, bid, bs)
 
         if bstatus in counts:
             counts[bstatus] += 1
@@ -901,6 +1022,8 @@ def action_status(bug_list_data, state_dir, project_root=None):
             icon = COLOR_MAGENTA + "[?]" + COLOR_RESET
         elif bstatus == "skipped":
             icon = COLOR_GRAY + "[—]" + COLOR_RESET
+        elif bstatus == "auto_skipped":
+            icon = COLOR_GRAY + "[⊘]" + COLOR_RESET
         else:
             icon = COLOR_GRAY + "[ ]" + COLOR_RESET
 
@@ -921,6 +1044,16 @@ def action_status(bug_list_data, state_dir, project_root=None):
             detail = " (failed after {} retries)".format(retry_count)
         elif bstatus == "needs_info":
             detail = " (needs more info)"
+        elif bstatus == "auto_skipped":
+            blockers = [
+                dependency_id
+                for dependency_id in bug.get("dependencies", [])
+                if status_map.get(dependency_id, "pending")
+                in RESET_BLOCKING_ROOT_STATUSES | {"auto_skipped"}
+            ]
+            detail = " (blocked by {})".format(
+                ", ".join(blockers) if blockers else "dependency chain"
+            )
 
         # Colorize
         if bstatus == "completed":
@@ -954,8 +1087,12 @@ def action_status(bug_list_data, state_dir, project_root=None):
     summary_line = "Total: {} bugs | Completed: {} | In Progress: {}".format(
         total, completed, counts["in_progress"]
     )
-    summary_line2 = "Failed: {} | Pending: {} | Needs Info: {} | Skipped: {}".format(
-        counts["failed"], counts["pending"], counts["needs_info"], counts["skipped"]
+    summary_line2 = "Failed: {} | Pending: {} | Needs Info: {} | Skipped: {} | Auto-skipped: {}".format(
+        counts["failed"],
+        counts["pending"],
+        counts["needs_info"],
+        counts["skipped"],
+        counts["auto_skipped"],
     )
 
     inner = BOX_WIDTH - 2
@@ -1146,6 +1283,8 @@ def action_start(args, bug_list_path, state_dir):
     bs = load_bug_status(state_dir, bug_id)
     old_status = get_bug_status_from_list(bug_list_path, bug_id)
 
+    bs["max_retries"] = args.max_retries
+    bs["max_infra_retries"] = args.max_infra_retries
     bs["updated_at"] = now_iso()
 
     err = save_bug_status(state_dir, bug_id, bs)
@@ -1172,64 +1311,37 @@ def action_start(args, bug_list_path, state_dir):
 
 
 # ---------------------------------------------------------------------------
-# Action: unskip
+# Action: reset_state
 # ---------------------------------------------------------------------------
 
-def action_unskip(args, bug_list_path, state_dir):
-    """Reset skipped bugs back to pending.
-
-    Two modes:
-    - --bug-id B-001: Reset the specified skipped bug to pending.
-    - No --bug-id: Reset ALL skipped bugs to pending.
-    """
-    bug_id = args.bug_id
-
+def action_reset_state(args, bug_list_path, state_dir):
+    """Reset one causal bug closure, or every recoverable closure, to pending."""
     data, err = load_json_file(bug_list_path)
     if err:
         error_out("Cannot load bug fix list: {}".format(err))
         return
     bugs = data.get("bugs", [])
 
-    to_reset = set()
-
-    if bug_id:
-        # Find the target bug
-        target = None
-        for b in bugs:
-            if isinstance(b, dict) and b.get("id") == bug_id:
-                target = b
-                break
-        if not target:
-            error_out("Bug '{}' not found in .prizmkit/plans/bug-fix-list.json".format(bug_id))
-            return
-        if target.get("status") not in ("failed", "skipped", "needs_info"):
-            error_out(
-                "Bug '{}' has status '{}', expected 'failed', 'skipped', or 'needs_info'".format(
-                    bug_id, target.get("status", "unknown")
-                )
-            )
-            return
-        to_reset.add(bug_id)
-    else:
-        # No bug-id: reset ALL skipped/failed/needs_info bugs
-        for b in bugs:
-            if isinstance(b, dict) and b.get("id"):
-                if b.get("status") in ("failed", "skipped", "needs_info"):
-                    to_reset.add(b["id"])
-
-    if not to_reset:
-        error_out("No bugs to unskip")
+    try:
+        recovery_ids = causal_reset_selection(
+            bugs,
+            selected_id=args.bug_id,
+            blocking_root_statuses=RESET_BLOCKING_ROOT_STATUSES,
+            item_label="Bug",
+        )
+    except ValueError as exc:
+        error_out(str(exc))
         return
 
-    # Reset all collected bugs in bug-fix-list.json
+    to_reset = set(recovery_ids)
     reset_details = []
-    for b in bugs:
-        if isinstance(b, dict) and b.get("id") in to_reset:
-            old_status = b.get("status", "unknown")
-            b["status"] = "pending"
+    for bug in bugs:
+        if isinstance(bug, dict) and bug.get("id") in to_reset:
+            old_status = bug.get("status", "unknown")
+            bug["status"] = "pending"
             reset_details.append({
-                "bug_id": b["id"],
-                "title": b.get("title", ""),
+                "bug_id": bug["id"],
+                "title": bug.get("title", ""),
                 "old_status": old_status,
             })
 
@@ -1238,22 +1350,31 @@ def action_unskip(args, bug_list_path, state_dir):
         error_out("Failed to write .prizmkit/plans/bug-fix-list.json: {}".format(err))
         return
 
-    # Reset runtime fields in status.json for each bug
-    for bid in to_reset:
-        bs = load_bug_status(state_dir, bid)
+    for bug_id in recovery_ids:
+        bs = load_bug_status(state_dir, bug_id)
+        checkout_identity = {
+            key: bs[key]
+            for key in ("active_dev_branch", "base_branch")
+            if key in bs
+        }
         bs["retry_count"] = 0
         bs["infra_error_count"] = 0
         bs["last_infra_error_session_id"] = None
         bs["sessions"] = []
         bs["last_session_id"] = None
+        bs["last_failed_session_id"] = None
         bs["resume_from_phase"] = None
         reset_continuation_metadata(bs)
+        bs.update(checkout_identity)
         bs["updated_at"] = now_iso()
-        save_bug_status(state_dir, bid, bs)
+        err = save_bug_status(state_dir, bug_id, bs)
+        if err:
+            error_out("Failed to save bug status: {}".format(err))
+            return
 
     result = {
-        "action": "unskip",
-        "reset_count": len(to_reset),
+        "action": "reset_state",
+        "reset_count": len(recovery_ids),
         "bugs": reset_details,
     }
     print(json.dumps(result, indent=2, ensure_ascii=False))
@@ -1283,7 +1404,12 @@ def main():
         error_out("Cannot load bug fix list: {}".format(err))
 
     if args.action == "get_next":
-        action_get_next(bug_list_data, args.state_dir, args.project_root)
+        action_get_next(
+            bug_list_data,
+            args.state_dir,
+            args.project_root,
+            args.bug_list,
+        )
     elif args.action == "start":
         action_start(args, args.bug_list, args.state_dir)
     elif args.action == "update":
@@ -1296,8 +1422,8 @@ def main():
         action_clean(args, args.bug_list, args.state_dir)
     elif args.action == "pause":
         action_pause(args.state_dir)
-    elif args.action == "unskip":
-        action_unskip(args, args.bug_list, args.state_dir)
+    elif args.action == "reset_state":
+        action_reset_state(args, args.bug_list, args.state_dir)
     elif args.action == "complete":
         # Shortcut: 'complete' is equivalent to 'update --session-status success'
         args.session_status = "success"

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

@@ -14,6 +14,7 @@ if _PIPELINE_ROOT not in sys.path:
 
 from prizmkit_runtime.checkpoint_state import (  # noqa: E402
     MAX_OUTER_REPAIR_ROUNDS,
+    PLAN_RESULTS,
     REVIEW_RESULTS,
     SKILL_WORKFLOW_STAGES,
     STEP_ID_PATTERN,
@@ -110,9 +111,16 @@ def _mandatory_predecessor_verdict_error(steps, index, workflow_type):
     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)
+    skill = steps[index].get("skill")
+    if skill == "prizmkit-implement":
+        planning = [
+            item for item in preceding
+            if item.get("stage_result") in PLAN_RESULTS
+        ]
+        if len(planning) != 1 or planning[0].get("status") != "completed" or planning[0].get("stage_result") != "PLAN_READY":
+            return "Implementation requires a completed PLAN_READY predecessor"
     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"
@@ -153,29 +161,44 @@ def _validate_semantic_update(step, semantic_update):
     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)
-    if terminal_status == "WORKFLOW_BLOCKED" and not semantic_update.get("blocked_reason"):
+    blocked_reason = semantic_update.get("blocked_reason")
+    blocked_policy_result = stage_result in {"TEST_NEEDS_FIXES", "TEST_BLOCKED"}
+    if terminal_status == "WORKFLOW_COMPLETED" and blocked_policy_result:
+        return "WORKFLOW_COMPLETED conflicts with blocking stage result {}".format(stage_result)
+    if blocked_reason is not None:
+        if not isinstance(blocked_reason, str) or not blocked_reason.strip():
+            return "blocked_reason must be a non-empty string"
+        if terminal_status == "WORKFLOW_COMPLETED":
+            return "WORKFLOW_COMPLETED cannot retain blocked_reason"
+        if terminal_status != "WORKFLOW_BLOCKED" and not blocked_policy_result:
+            return "blocked_reason requires terminal_status=WORKFLOW_BLOCKED"
+    if terminal_status == "WORKFLOW_BLOCKED" and not blocked_reason:
         return "WORKFLOW_BLOCKED requires blocked_reason"
     return None
 
 
 def _apply_repair_policy(l4_state, stage_result, repair_scope):
-    if stage_result not in {"REVIEW_NEEDS_FIXES", "TEST_NEEDS_FIXES", "TEST_BLOCKED"}:
-        return False
-    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 in {"TEST_NEEDS_FIXES", "TEST_BLOCKED"}:
+    terminal_blockers = {
+        "PLAN_BLOCKED": "plan_blocked",
+        "IMPLEMENT_REPAIR": "implementation_repair",
+        "IMPLEMENT_BLOCKED": "implementation_blocked",
+        "TEST_BLOCKED": "test_blocked",
+        "RETRO_BLOCKED": "retrospective_blocked",
+        "COMMIT_BLOCKED": "commit_blocked",
+    }
+    if stage_result in terminal_blockers:
         l4_state.update(
             terminal_status="WORKFLOW_BLOCKED",
-            blocked_reason=(
-                "test_needs_fixes"
-                if stage_result == "TEST_NEEDS_FIXES"
-                else "test_blocked"
-            ),
+            blocked_reason=terminal_blockers[stage_result],
             current_stage=None,
             next_stage=None,
         )
         return False
+    if stage_result not in {"REVIEW_NEEDS_FIXES", "TEST_NEEDS_FIXES"}:
+        return False
+    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 current_round >= MAX_OUTER_REPAIR_ROUNDS:
         l4_state.update(
             repair_round=MAX_OUTER_REPAIR_ROUNDS,
@@ -194,12 +217,36 @@ def _apply_repair_policy(l4_state, stage_result, repair_scope):
         )
         return False
     l4_state["repair_round"] = current_round + 1
+    l4_state["repair_scope"] = repair_scope
     l4_state["terminal_status"] = None
     l4_state["blocked_reason"] = None
     l4_state["next_stage"] = "prizmkit-implement"
     return True
 
 
+def _prepare_repair_reentry(data, index):
+    """Rewind downstream gates when a routed repair re-enters implementation."""
+    step = data["steps"][index]
+    if step.get("skill") != "prizmkit-implement":
+        return
+    state_key = semantic_state_key(str(data.get("workflow_type") or ""))
+    l4_state = data.get(state_key)
+    if not isinstance(l4_state, dict):
+        return
+    if (
+        l4_state.get("next_stage") != "prizmkit-implement"
+        or l4_state.get("stage_result")
+        not in {"REVIEW_NEEDS_FIXES", "TEST_NEEDS_FIXES"}
+    ):
+        return
+    for later in data["steps"][index + 1:]:
+        later["status"] = "pending"
+        later.pop("stage_result", None)
+        later.pop("note", None)
+    l4_state["terminal_status"] = None
+    l4_state["blocked_reason"] = None
+
+
 def _sync_cursor(data, l4_state, preserve_next_stage=False):
     active = next(
         (step for step in data["steps"] if step.get("status") not in TERMINAL_STEP_STATUSES),
@@ -280,6 +327,9 @@ def update_checkpoint(
         suffix = " Available: {}".format(", ".join(available)) if available else ""
         return {"ok": False, "error": "{}{}".format(find_error or "Step not found.", suffix)}
 
+    if new_status == "in_progress":
+        _prepare_repair_reentry(data, index)
+
     if new_status in {"in_progress", "completed", "skipped"} and not _predecessors_terminal(data["steps"], index):
         return {
             "ok": False,
@@ -295,6 +345,11 @@ def update_checkpoint(
             return {"ok": False, "error": verdict_error}
 
     semantic_update = _normalize_semantic_update(semantic_update)
+    if semantic_update.get("stage_result") == "COMMITTED":
+        return {
+            "ok": False,
+            "error": "COMMITTED is Runtime-owned and cannot be written by the Prompt checkpoint helper",
+        }
     semantic_error = _validate_semantic_update(step, semantic_update)
     if semantic_error:
         return {"ok": False, "error": semantic_error}
@@ -308,6 +363,10 @@ def update_checkpoint(
         stage_result = stage_result or step.get("stage_result")
         if stage_result != "TEST_PASS":
             return {"ok": False, "error": "Test completion requires TEST_PASS"}
+    if new_status == "completed" and step.get("skill") == "prizmkit-committer":
+        stage_result = stage_result or step.get("stage_result")
+        if stage_result != "COMMITTED":
+            return {"ok": False, "error": "Committer completion requires Runtime-owned COMMITTED"}
     expected_status = expected_status_for_stage_result(stage_result)
     if expected_status is not None and new_status != expected_status:
         return {
@@ -339,7 +398,7 @@ def update_checkpoint(
         if key in semantic_update:
             l4_state[key] = semantic_update[key]
     l4_state["schema_version"] = 1
-    l4_state["orchestrator"] = "prizmkit-l4"
+    l4_state["orchestrator"] = "pipeline-runtime"
     skill = step.get("skill")
     l4_state["stage"] = SKILL_WORKFLOW_STAGES.get(skill, skill)
     l4_state["status"] = new_status
@@ -361,11 +420,13 @@ def update_checkpoint(
         exists=True,
         project_root=_checkpoint_project_root(checkpoint_path),
     )
-    if not final_state.valid:
+    if not final_state.valid or final_state.semantic.error_code:
+        error_code = final_state.error_code or final_state.semantic.error_code
+        error_message = final_state.error_message or final_state.semantic.error_message
         return {
             "ok": False,
             "error": "Update would create invalid checkpoint ({}): {}".format(
-                final_state.error_code, final_state.error_message
+                error_code, error_message
             ),
         }