prizmkit 1.1.125 → 1.1.126

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.1.125",
-  "bundledAt": "2026-07-12T10:06:26.471Z",
-  "bundledFrom": "ae3f6a3"
+  "frameworkVersion": "1.1.126",
+  "bundledAt": "2026-07-12T14:55:57.208Z",
+  "bundledFrom": "577a809"
 }

package/bundled/dev-pipeline/prizmkit_runtime/reset.py

@@ -11,8 +11,23 @@ from dataclasses import dataclass
 from pathlib import Path
 
 from .commands import CommandResult  # type: ignore  # runtime boundary import
-from .gitops import default_branch, list_reset_branches, reset_cleanup_branch
+from .gitops import (
+    BranchContext,
+    WorktreePolicy,
+    default_branch,
+    guarded_worktree_remove,
+    list_reset_branches,
+    reset_cleanup_branch,
+    worktree_runtime_context,
+)
 from .runner_models import RunnerFamily, family_for
+from .task_checkout import (
+    CHECKOUT_MODE_WORKTREE,
+    TaskCheckout,
+    load_task_checkout,
+    mark_task_checkout_reset_locked,
+    task_checkout_guard,
+)
 
 
 @dataclass(frozen=True)
@@ -128,7 +143,12 @@ def run_reset_command(kind: str, legacy_args: tuple[str, ...], paths) -> Command
     failed = 0
     return_branch = default_branch(paths.project_root)
     for item in items:
-        ok = _reset_one(family, item, options, paths.project_root, return_branch, lines)
+        try:
+            with task_checkout_guard(family.state_dir, item.item_id):
+                ok = _reset_one(family, item, options, paths.project_root, return_branch, lines)
+        except RuntimeError as exc:
+            lines.append(f"ERROR: Reset {item.item_id} could not acquire checkout lifecycle: {exc}")
+            ok = False
         if ok:
             success += 1
         else:
@@ -254,7 +274,25 @@ def _reset_one(family: RunnerFamily, item: ResetItem, options: ResetOptions, pro
     else:
         lines.append(f"Current status: {item.status} (no runtime state file)")
 
-    for branch in list_reset_branches(project_root, BRANCH_PREFIX_BY_KIND[family.kind], item.item_id):
+    checkout = load_task_checkout(family.state_dir, family.task_type, item.item_id)
+    branches = list(list_reset_branches(project_root, BRANCH_PREFIX_BY_KIND[family.kind], item.item_id))
+    if checkout is not None and (checkout.is_active or checkout.is_completed):
+        if checkout.active_dev_branch not in branches:
+            branches.insert(0, checkout.active_dev_branch)
+        if checkout.checkout_mode == CHECKOUT_MODE_WORKTREE:
+            runtime = worktree_runtime_context(
+                BranchContext(checkout.base_branch, checkout.active_dev_branch, project_root),
+                WorktreePolicy(True, True, True, Path(checkout.worktree_path).parent),
+            )
+            if runtime.worktree_path != Path(checkout.worktree_path).resolve():
+                lines.append(f"ERROR: Reset {item.item_id} worktree identity resolves to an unexpected path")
+                return False
+            removal = guarded_worktree_remove(runtime, delete_branch=False)
+            if not removal.ok:
+                lines.append(f"ERROR: Reset {item.item_id} could not remove linked worktree: {removal.reason}")
+                return False
+
+    for branch in branches:
         cleanup = reset_cleanup_branch(project_root, branch, return_branch=return_branch, delete=options.clean)
         lines.append(f"Discarded uncommitted changes on dev branch: {cleanup.branch}")
         if cleanup.deleted:
@@ -262,11 +300,19 @@ def _reset_one(family: RunnerFamily, item: ResetItem, options: ResetOptions, pro
         elif not options.clean:
             lines.append(f"Dev branch preserved for debugging: {cleanup.branch}")
         lines.extend(f"WARN: {warning}" for warning in cleanup.warnings)
+        if cleanup.warnings:
+            lines.append(f"ERROR: Reset {item.item_id} branch cleanup failed")
+            return False
 
     action = "clean" if options.clean else "reset"
     lines.append(f"{'Cleaning' if options.clean else 'Resetting'} {item.item_id} status...")
     result = _run_updater(family, action, options, item, project_root)
     if result.returncode == 0 and _json_without_error(result.stdout):
+        try:
+            mark_task_checkout_reset_locked(family.state_dir, family.task_type, item.item_id)
+        except RuntimeError as exc:
+            lines.append(f"ERROR: Reset {item.item_id} checkout identity failed: {exc}")
+            return False
         lines.append(f"{item.item_id} {action} complete: status -> pending, retry count -> 0")
         return True
     error = _error_text(result.stdout) or result.stderr.strip() or "unknown"

package/bundled/dev-pipeline/prizmkit_runtime/runners.py

@@ -40,6 +40,15 @@ from .runner_prompts import PromptGenerationResult, generate_prompt
 from .runner_recovery import run_recovery, run_recovery_detect
 from .runner_status import get_next, run_status_action, start_item, status_text, update_item
 from .sessions import AISessionConfig, AISessionLauncher, detect_stream_json_support
+from .task_checkout import (
+    CHECKOUT_MODE_BRANCH,
+    CHECKOUT_MODE_WORKTREE,
+    TaskCheckout,
+    complete_task_checkout_locked,
+    load_task_checkout,
+    reserve_task_checkout_locked,
+    task_checkout_guard,
+)
 
 
 def run_pipeline_command(kind: str, action: str, legacy_args: tuple[str, ...], paths) -> CommandResult:
@@ -247,8 +256,22 @@ def _is_current_task_branch(branch: str, family: RunnerFamily, item_id: str) ->
     return branch == f"{family.branch_prefix}/{item_id}" or branch.startswith(f"{family.branch_prefix}/{item_id}-")
 
 
-def _with_recovery_metadata(family: RunnerFamily, item_id: str, metadata: dict[str, object]) -> dict[str, object]:
+def _with_recovery_metadata(
+    family: RunnerFamily,
+    item_id: str,
+    metadata: dict[str, object],
+    checkout: TaskCheckout | None = None,
+) -> dict[str, object]:
     enriched = dict(metadata)
+    checkout = checkout or load_task_checkout(family.state_dir, family.task_type, item_id)
+    if checkout is not None:
+        if checkout.is_active:
+            enriched["active_dev_branch"] = checkout.active_dev_branch
+            enriched["base_branch"] = checkout.base_branch
+            return enriched
+        for key in ("active_dev_branch", "base_branch"):
+            enriched.pop(key, None)
+        return enriched
     if enriched.get("active_dev_branch") and enriched.get("base_branch"):
         return enriched
     recovered = _latest_session_status(family.state_dir, item_id)
@@ -431,6 +454,21 @@ def _process_item(
     paths,
     *,
     initial_metadata: dict[str, object],
+) -> str:
+    try:
+        with task_checkout_guard(family.state_dir, item_id):
+            return _process_item_locked(family, invocation, item_id, paths, initial_metadata=initial_metadata)
+    except KeyboardInterrupt:
+        raise
+
+
+def _process_item_locked(
+    family: RunnerFamily,
+    invocation: RunnerInvocation,
+    item_id: str,
+    paths,
+    *,
+    initial_metadata: dict[str, object],
 ) -> str:
     env = RunnerEnvironment.from_env()
     config = load_runtime_config(paths)
@@ -438,12 +476,20 @@ def _process_item(
         raise RuntimeError("No supported AI CLI command was found")
 
     active_branch = current_branch(paths.project_root)
-    metadata = _with_recovery_metadata(family, item_id, initial_metadata)
+    checkout = load_task_checkout(family.state_dir, family.task_type, item_id)
+    if checkout is not None and checkout.is_completed:
+        raise RuntimeError(f"Task {item_id} is completed; run explicit reset or clean before rerunning")
+    metadata = _with_recovery_metadata(family, item_id, initial_metadata, checkout)
     base_branch = _resolve_base_branch(paths.project_root, metadata, active_branch, family, item_id)
     branch_name = _resolve_working_branch(family, item_id, metadata, env, active_branch)
     branch_context = BranchContext(base_branch, branch_name, paths.project_root)
     worktree_runtime = None
-    use_worktree = _use_worktree_for_family(env, family)
+    if checkout is not None and checkout.is_active:
+        use_worktree = checkout.uses_worktree
+        worktree_path = Path(checkout.worktree_path) if checkout.worktree_path else None
+    else:
+        use_worktree = _use_worktree_for_family(env, family)
+        worktree_path = None
     execution_root = paths.project_root
 
     try:
@@ -468,9 +514,23 @@ def _process_item(
                     use_worktree=True,
                     cleanup_on_success=True,
                     preserve_on_failure=True,
-                    worktree_root=paths.state_dir / "worktrees",
+                    worktree_root=(worktree_path.parent if worktree_path is not None else paths.state_dir / "worktrees"),
                 ),
             )
+            if worktree_path is not None and worktree_runtime.worktree_path != worktree_path.resolve():
+                raise RuntimeError(f"Task {item_id} worktree identity resolves to an unexpected path")
+        checkout_candidate = TaskCheckout.active(
+            family.task_type,
+            item_id,
+            branch_name,
+            base_branch,
+            checkout_mode=CHECKOUT_MODE_WORKTREE if use_worktree else CHECKOUT_MODE_BRANCH,
+            worktree_path=str(worktree_runtime.worktree_path) if worktree_runtime is not None else "",
+        )
+        checkout = reserve_task_checkout_locked(family.state_dir, checkout_candidate)
+        _emit_info(f"Checkout: reserved task identity at {family.state_dir / item_id / 'checkout.json'}")
+
+        if use_worktree:
             setup = ensure_linked_worktree(worktree_runtime)
             if not setup.ok:
                 return "infra_error"
@@ -670,9 +730,7 @@ def _process_item(
             if final_session_status != "success":
                 commit_final_bookkeeping(status_root, status_family, item_id, new_status)
                 _save_failure_wip(execution_root, family, item_id, new_status, worktree_runtime)
-                if use_worktree and worktree_runtime is not None:
-                    guarded_worktree_remove(worktree_runtime, delete_branch=False)
-                else:
+                if not use_worktree:
                     branch_ensure_return(paths.project_root, base_branch, branch_name)
                 return new_status
 
@@ -697,7 +755,6 @@ def _process_item(
         _emit_warning(f"Interrupted while processing {item_id}; preserving work and returning to {base_branch}")
         if use_worktree and worktree_runtime is not None:
             worktree_save_wip(worktree_runtime)
-            guarded_worktree_remove(worktree_runtime, delete_branch=False)
         else:
             branch_ensure_return(paths.project_root, base_branch, branch_name)
         raise
@@ -789,6 +846,10 @@ def _complete_success_merge(
         merge = merge_linked_worktree(worktree_runtime, auto_push=env.auto_push)
         _emit_git_plan_output(merge)
         if merge.ok:
+            checkout = load_task_checkout(family.state_dir, family.task_type, item_id)
+            if checkout is None:
+                raise RuntimeError(f"Task {item_id} checkout identity disappeared before completion")
+            complete_task_checkout_locked(family.state_dir, checkout)
             guarded_worktree_remove(worktree_runtime, delete_branch=True)
             _emit_success(f"Merged {branch_name} into {base_branch}")
             return new_status
@@ -797,6 +858,10 @@ def _complete_success_merge(
         merge = run_git_plan(paths.project_root, branch_merge_plan(branch_context, auto_push=env.auto_push))
         _emit_git_plan_output(merge)
         if merge.ok:
+            checkout = load_task_checkout(family.state_dir, family.task_type, item_id)
+            if checkout is None:
+                raise RuntimeError(f"Task {item_id} checkout identity disappeared before completion")
+            complete_task_checkout_locked(family.state_dir, checkout)
             _emit_success(f"Merged {branch_name} into {base_branch}")
             return new_status
 
@@ -829,9 +894,7 @@ def _complete_success_merge(
     merged_status = _status_from_update(update)
     commit_final_bookkeeping(status_root, status_family, item_id, merged_status)
     _save_failure_wip(execution_root, family, item_id, merged_status, worktree_runtime)
-    if worktree_runtime is not None:
-        guarded_worktree_remove(worktree_runtime, delete_branch=False)
-    else:
+    if worktree_runtime is None:
         branch_ensure_return(paths.project_root, base_branch, branch_name)
     return merged_status
 
@@ -876,9 +939,7 @@ def _record_setup_failure(
     if update.ok:
         commit_final_bookkeeping(status_root, status_family, item_id, new_status)
         _save_failure_wip(status_root, family, item_id, new_status, worktree_runtime)
-    if worktree_runtime is not None:
-        guarded_worktree_remove(worktree_runtime, delete_branch=False)
-    elif current_branch(project_root) == branch_name:
+    if worktree_runtime is None and current_branch(project_root) == branch_name:
         branch_ensure_return(project_root, base_branch, branch_name)
     return new_status
 

package/bundled/dev-pipeline/prizmkit_runtime/runtime_helper.py

@@ -233,6 +233,39 @@ def _text_contains(args: argparse.Namespace) -> HelperResult:
     return HelperResult(args.found_marker if found else args.missing_marker, found, {"path": str(target), "pattern": args.pattern})
 
 
+def _text_final_verdict(args: argparse.Namespace) -> HelperResult:
+    target = _path(args.path)
+    if not target.is_file():
+        return HelperResult("REVIEW_INCOMPLETE", False, {"path": str(target), "reason": "file_missing"}, 1)
+    try:
+        lines = target.read_text(encoding="utf-8", errors="ignore").splitlines()
+    except OSError as exc:
+        return HelperResult("REVIEW_INCOMPLETE", False, {"path": str(target), "reason": type(exc).__name__}, 1)
+
+    final_indexes = [index for index, line in enumerate(lines) if line.strip() == "## Final Result"]
+    if not final_indexes:
+        return HelperResult("REVIEW_INCOMPLETE", False, {"path": str(target), "reason": "final_result_missing"}, 1)
+
+    verdict = ""
+    for line in lines[final_indexes[-1] + 1:]:
+        stripped = line.strip()
+        if stripped.startswith("## "):
+            break
+        if stripped.startswith("- Verdict:"):
+            verdict = stripped[len("- Verdict:"):].strip()
+            break
+
+    markers = {
+        "PASS": "REVIEW_PASS",
+        "NEEDS_FIXES": "REVIEW_NEEDS_FIXES",
+        "BLOCKED": "REVIEW_BLOCKED",
+    }
+    marker = markers.get(verdict)
+    if not marker:
+        return HelperResult("REVIEW_INVALID", False, {"path": str(target), "verdict": verdict or None}, 1)
+    return HelperResult(marker, True, {"path": str(target), "verdict": verdict})
+
+
 def _platform_detect(args: argparse.Namespace) -> HelperResult:
     paths = resolve_runtime_paths(project_root=args.project_root, pipeline_root=args.pipeline_root)
     resolution = resolve_platform(paths.project_root)
@@ -411,6 +444,10 @@ def build_parser() -> argparse.ArgumentParser:
     contains.add_argument("--missing-marker", default="GATE:MISSING")
     _add_json(contains)
     contains.set_defaults(func=_text_contains)
+    final_verdict = text_sub.add_parser("final-verdict", help="Read the verdict from the last review Final Result section")
+    final_verdict.add_argument("path")
+    _add_json(final_verdict)
+    final_verdict.set_defaults(func=_text_final_verdict)
 
     platform = subparsers.add_parser("platform", help="AI platform and skill detection")
     platform_sub = platform.add_subparsers(dest="action", required=True)

package/bundled/dev-pipeline/prizmkit_runtime/task_checkout.py

@@ -0,0 +1,267 @@
+"""Durable task checkout identity for pipeline branch and worktree reuse."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import tempfile
+import time
+from contextlib import contextmanager
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Iterator
+
+
+CHECKOUT_STATE_ACTIVE = "active"
+CHECKOUT_STATE_COMPLETED = "completed"
+CHECKOUT_STATE_RESET = "reset"
+CHECKOUT_MODE_BRANCH = "branch"
+CHECKOUT_MODE_WORKTREE = "worktree"
+
+
+class TaskCheckoutError(RuntimeError):
+    """Raised when durable checkout identity cannot be coordinated safely."""
+
+
+@dataclass(frozen=True)
+class TaskCheckout:
+    """Checkout identity that remains authoritative until explicit reset or clean."""
+
+    task_type: str
+    task_id: str
+    state: str
+    active_dev_branch: str = ""
+    base_branch: str = ""
+    checkout_mode: str = CHECKOUT_MODE_BRANCH
+    worktree_path: str = ""
+
+    @classmethod
+    def active(
+        cls,
+        task_type: str,
+        task_id: str,
+        active_dev_branch: str,
+        base_branch: str,
+        *,
+        checkout_mode: str = CHECKOUT_MODE_BRANCH,
+        worktree_path: str = "",
+    ) -> "TaskCheckout":
+        branch = active_dev_branch.strip()
+        base = base_branch.strip()
+        mode = checkout_mode.strip()
+        path = worktree_path.strip()
+        if not branch or not base:
+            raise TaskCheckoutError("Active task checkout requires development and base branches")
+        if mode not in {CHECKOUT_MODE_BRANCH, CHECKOUT_MODE_WORKTREE}:
+            raise TaskCheckoutError(f"Unsupported task checkout mode: {mode or '(empty)'}")
+        if mode == CHECKOUT_MODE_WORKTREE and not path:
+            raise TaskCheckoutError("Worktree task checkout requires a canonical worktree path")
+        if mode == CHECKOUT_MODE_BRANCH:
+            path = ""
+        return cls(task_type, task_id, CHECKOUT_STATE_ACTIVE, branch, base, mode, path)
+
+    @classmethod
+    def reset(cls, task_type: str, task_id: str) -> "TaskCheckout":
+        return cls(task_type=task_type, task_id=task_id, state=CHECKOUT_STATE_RESET)
+
+    def completed(self) -> "TaskCheckout":
+        if not self.is_active:
+            raise TaskCheckoutError("Only an active task checkout can be completed")
+        return TaskCheckout(
+            task_type=self.task_type,
+            task_id=self.task_id,
+            state=CHECKOUT_STATE_COMPLETED,
+            active_dev_branch=self.active_dev_branch,
+            base_branch=self.base_branch,
+            checkout_mode=self.checkout_mode,
+            worktree_path=self.worktree_path,
+        )
+
+    @property
+    def is_active(self) -> bool:
+        return self.state == CHECKOUT_STATE_ACTIVE
+
+    @property
+    def is_completed(self) -> bool:
+        return self.state == CHECKOUT_STATE_COMPLETED
+
+    @property
+    def is_reset(self) -> bool:
+        return self.state == CHECKOUT_STATE_RESET
+
+    @property
+    def uses_worktree(self) -> bool:
+        return self.checkout_mode == CHECKOUT_MODE_WORKTREE
+
+
+def task_checkout_path(state_dir: Path | str, task_id: str) -> Path:
+    """Return the canonical checkout identity path for one task."""
+    return Path(state_dir) / task_id / "checkout.json"
+
+
+def task_checkout_lock_path(state_dir: Path | str, task_id: str) -> Path:
+    """Return the exclusive lifecycle lock directory for one task."""
+    return Path(state_dir) / task_id / ".checkout.lock"
+
+
+def load_task_checkout(state_dir: Path | str, task_type: str, task_id: str) -> TaskCheckout | None:
+    """Load and validate checkout identity, returning None only when absent."""
+    path = task_checkout_path(state_dir, task_id)
+    if not path.is_file():
+        return None
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise TaskCheckoutError(f"Cannot read task checkout identity {path}: {exc}") from exc
+    if not isinstance(data, dict):
+        raise TaskCheckoutError(f"Invalid task checkout identity {path}: expected a JSON object")
+
+    checkout = TaskCheckout(
+        task_type=str(data.get("task_type") or ""),
+        task_id=str(data.get("task_id") or ""),
+        state=str(data.get("state") or ""),
+        active_dev_branch=str(data.get("active_dev_branch") or ""),
+        base_branch=str(data.get("base_branch") or ""),
+        checkout_mode=str(data.get("checkout_mode") or CHECKOUT_MODE_BRANCH),
+        worktree_path=str(data.get("worktree_path") or ""),
+    )
+    if checkout.task_type != task_type or checkout.task_id != task_id:
+        raise TaskCheckoutError(f"Task checkout identity mismatch in {path}")
+    if checkout.state not in {CHECKOUT_STATE_ACTIVE, CHECKOUT_STATE_COMPLETED, CHECKOUT_STATE_RESET}:
+        raise TaskCheckoutError(f"Invalid task checkout state in {path}: {checkout.state or '(empty)'}")
+    if checkout.checkout_mode not in {CHECKOUT_MODE_BRANCH, CHECKOUT_MODE_WORKTREE}:
+        raise TaskCheckoutError(f"Invalid task checkout mode in {path}: {checkout.checkout_mode or '(empty)'}")
+    if checkout.is_active or checkout.is_completed:
+        if not checkout.active_dev_branch.strip() or not checkout.base_branch.strip():
+            raise TaskCheckoutError(f"Incomplete task checkout identity in {path}")
+        if checkout.uses_worktree and not checkout.worktree_path.strip():
+            raise TaskCheckoutError(f"Missing worktree path in task checkout identity {path}")
+    return checkout
+
+
+def _process_is_running(pid: int) -> bool:
+    if pid <= 0:
+        return False
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    except OSError:
+        return False
+    return True
+
+
+def _lock_owner_pid(lock_path: Path) -> int:
+    for _attempt in range(5):
+        try:
+            data = json.loads((lock_path / "owner.json").read_text(encoding="utf-8"))
+            return int(data.get("pid") or 0) if isinstance(data, dict) else 0
+        except FileNotFoundError:
+            time.sleep(0.01)
+        except (OSError, ValueError, json.JSONDecodeError):
+            return 0
+    return 0
+
+
+def _remove_stale_lock(lock_path: Path) -> None:
+    stale_path = lock_path.with_name(f"{lock_path.name}.stale-{os.getpid()}-{os.urandom(6).hex()}")
+    try:
+        os.rename(lock_path, stale_path)
+    except FileNotFoundError:
+        return
+    except OSError as exc:
+        raise TaskCheckoutError(f"Cannot claim stale task checkout lock {lock_path}: {exc}") from exc
+    shutil.rmtree(stale_path, ignore_errors=True)
+
+
+@contextmanager
+def task_checkout_guard(state_dir: Path | str, task_id: str) -> Iterator[None]:
+    """Exclusively guard one task lifecycle, reclaiming locks from dead processes."""
+    lock_path = task_checkout_lock_path(state_dir, task_id)
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    acquired = False
+    for _attempt in range(3):
+        try:
+            lock_path.mkdir()
+            (lock_path / "owner.json").write_text(json.dumps({"pid": os.getpid()}) + "\n", encoding="utf-8")
+            acquired = True
+            break
+        except FileExistsError:
+            owner_pid = _lock_owner_pid(lock_path)
+            if _process_is_running(owner_pid):
+                raise TaskCheckoutError(f"Task {task_id} is already running or being reset (PID {owner_pid})")
+            _remove_stale_lock(lock_path)
+        except OSError as exc:
+            raise TaskCheckoutError(f"Cannot acquire task checkout lock {lock_path}: {exc}") from exc
+    if not acquired:
+        raise TaskCheckoutError(f"Cannot acquire task checkout lock {lock_path}")
+    try:
+        yield
+    finally:
+        shutil.rmtree(lock_path, ignore_errors=True)
+
+
+def persist_task_checkout(state_dir: Path | str, checkout: TaskCheckout) -> Path:
+    """Atomically persist checkout identity while the caller holds its task guard."""
+    path = task_checkout_path(state_dir, checkout.task_id)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor = -1
+    temporary = ""
+    try:
+        descriptor, temporary = tempfile.mkstemp(prefix=".checkout-", suffix=".json", dir=path.parent)
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            descriptor = -1
+            json.dump(asdict(checkout), handle, indent=2, ensure_ascii=False)
+            handle.write("\n")
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, path)
+    except OSError as exc:
+        if descriptor >= 0:
+            os.close(descriptor)
+        if temporary:
+            try:
+                os.unlink(temporary)
+            except OSError:
+                pass
+        raise TaskCheckoutError(f"Cannot persist task checkout identity {path}: {exc}") from exc
+    return path
+
+
+def reserve_task_checkout_locked(state_dir: Path | str, candidate: TaskCheckout) -> TaskCheckout:
+    """Reserve once under a task guard; matching reservations are idempotent."""
+    if not candidate.is_active:
+        raise TaskCheckoutError("Only an active checkout can be reserved")
+    existing = load_task_checkout(state_dir, candidate.task_type, candidate.task_id)
+    if existing is not None and existing.is_completed:
+        raise TaskCheckoutError(f"Task {candidate.task_id} is completed; run explicit reset or clean before rerunning")
+    if existing is not None and existing.is_active:
+        if existing != candidate:
+            raise TaskCheckoutError(
+                f"Task {candidate.task_id} already owns checkout {existing.active_dev_branch}; refusing {candidate.active_dev_branch}"
+            )
+        return existing
+    persist_task_checkout(state_dir, candidate)
+    return candidate
+
+
+def reserve_task_checkout(state_dir: Path | str, candidate: TaskCheckout) -> TaskCheckout:
+    """Reserve a checkout with first-writer-wins synchronization."""
+    with task_checkout_guard(state_dir, candidate.task_id):
+        return reserve_task_checkout_locked(state_dir, candidate)
+
+
+def complete_task_checkout_locked(state_dir: Path | str, checkout: TaskCheckout) -> Path:
+    """Mark an active checkout terminal after its successful merge."""
+    current = load_task_checkout(state_dir, checkout.task_type, checkout.task_id)
+    if current != checkout or not checkout.is_active:
+        raise TaskCheckoutError(f"Task {checkout.task_id} checkout changed before completion")
+    return persist_task_checkout(state_dir, checkout.completed())
+
+
+def mark_task_checkout_reset_locked(state_dir: Path | str, task_type: str, task_id: str) -> Path:
+    """Publish an explicit reset boundary while the caller holds the task guard."""
+    return persist_task_checkout(state_dir, TaskCheckout.reset(task_type, task_id))

package/bundled/dev-pipeline/scripts/generate-recovery-prompt.py

@@ -97,8 +97,9 @@ Implement the minimal fix (red → green):
         """\
 Verify fix quality:
 1. Run `/prizmkit-code-review` with the current bugfix artifact directory.
-2. The skill launches one fresh read-only Reviewer per completed round; the Main Agent filters and directly fixes accepted findings.
-3. Continue until no accepted finding remains or the ten-round safety fuse returns `NEEDS_FIXES`; stop and retry later if review returns `BLOCKED`.""",
+2. The Main Agent self-reviews for up to ten rounds; semantic risk limits independent Reviewers to low=0, medium=1, high=2.
+3. Reviewer 2 requires an accepted high finding from Reviewer 1 plus repair, tests, and Main-Agent reconvergence; Reviewer 3 is forbidden.
+4. Continue only after the report's last Final Result is valid; preserve append-only progress for recovery.""",
     ),
     6: (
         "User Verification",

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

@@ -30,7 +30,7 @@ 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 skill uses one fresh read-only Reviewer per completed round, lets the Main Agent filter and directly fix accepted findings, and stops after at most ten completed rounds.
+4. **Review**: Run `/prizmkit-code-review` with `artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/`. The Main Agent self-reviews for up to ten rounds; semantic risk then limits independent Reviewers to `low=0`, `medium=1`, `high=2`, with Reviewer 2 only after an accepted high finding is repaired and reconverged. Reviewer 3 is forbidden. Require the last `## Final Result` verdict before continuing.
 
 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.
 

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

@@ -240,27 +240,15 @@ For each Verification Gate from the Task Contract, write one evidence line to Im
 
 Review the completed implementation before the scoped feature test gate runs. Use `artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` so the code-review skill can read spec, plan, context snapshot, implementation log, and current diff artifacts. Do not require or read a prior `/prizmkit-test` report here; test generation and test-fix looping happen in the next phase.
 
-Run `/prizmkit-code-review` with `artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/`. The skill chooses a platform-supported fresh read-only Reviewer, prefers direct access to the active checkout, and supplies changed content that a platform-forced worktree cannot see. Do not prescribe Agent launch parameters from this bootstrap prompt.
+Run `/prizmkit-code-review` with `artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/`. The skill first runs a Main-Agent self-review loop for up to ten completed rounds, then semantic risk permits independent Reviewers at limits `low=0`, `medium=1`, `high=2`. High risk starts Reviewer 2 only after an accepted high finding was repaired, tested, and reconverged; Reviewer 3 is forbidden. The skill owns launch parameters, current-checkout preference, forced-worktree changed-content fallback, and append-only report progress.
 
-The skill runs an internal review-fix loop (fresh Reviewer → Main-Agent filter → Main-Agent fix, up to ten completed rounds) and writes `review-report.md` to the artifact directory.
-
-**Gate Check — Review Report**:
-After `/prizmkit-code-review` returns, verify the review report:
+**Gate Check — Final Review Result**:
 ```bash
-{{RUNTIME_HELPER_CMD}} text contains .prizmkit/specs/{{FEATURE_SLUG}}/review-report.md --pattern "## Verdict"
+{{RUNTIME_HELPER_CMD}} text final-verdict .prizmkit/specs/{{FEATURE_SLUG}}/review-report.md
 ```
-If GATE:MISSING:
-- Do not re-run `/prizmkit-code-review` in an unbounded report-repair loop.
-- Perform one bounded status check; retry at most once: inspect the skill output, `review-report.md` path, and any Reviewer agent spawn messages.
-- If the missing report is caused by Reviewer agent spawn or review skill error, retry `/prizmkit-code-review` at most once only if it appears transient.
-- If the report is still missing after that single check/retry, write `failure-log.md` with the spawn/skill error and last observable state, then stop with a clear recovery failure. Do not synthesize a passing report through Main-Agent self-review.
-
-Read `review-report.md` and check the Verdict:
-- `PASS` → proceed to next phase
-- `NEEDS_FIXES` → log the unresolved accepted findings and proceed according to the task failure policy (do not retry externally)
-- `BLOCKED` → log the infrastructure reason and stop so the review can be retried
-
-**CP-3**: Review complete, report written.
+Handle `REVIEW_PASS`, `REVIEW_NEEDS_FIXES`, and `REVIEW_BLOCKED` according to task policy. `REVIEW_INCOMPLETE` or `REVIEW_INVALID` means review did not complete: inspect progress once, write `failure-log.md`, and stop. Do not accept old or incidental verdict text or synthesize a passing result through Main-Agent self-review.
+
+**CP-3**: Review has a valid Final Result and the report preserves this execution's progress.
 
 ### Scoped Feature Test Gate — PrizmKit Test