prizmkit 1.1.114 → 1.1.116

package/bundled/dev-pipeline/assets/prizm-dev-team-integration.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-dev-pipeline drives feature sessions through the unified Python outer loop. Each iteration spawns a new AI CLI session with a bootstrap prompt that makes the main session orchestrator responsible for implementation, while Critic and Reviewer agents remain available for challenge/review phases.
+dev-pipeline drives feature sessions through the unified Python outer loop. Each iteration spawns a new AI CLI session with a bootstrap prompt that makes the main session orchestrator responsible for planning, implementation, review coordination, testing, retrospective, and commit.
 
 ## Architecture
 
@@ -10,31 +10,27 @@ dev-pipeline drives feature sessions through the unified Python outer loop. Each
 dev-pipeline (outer loop)
     │
     ├── cli.py feature                    Python runtime CLI — picks next feature, spawns CLI
-    ├── scripts/                  Python state management scripts
-    ├── templates/bootstrap-prompt.md  Session prompt template
+    ├── scripts/                          Python state and prompt management scripts
+    ├── templates/                        Session prompt templates and sections
     │
     └── [per session] AI CLI
             │
-            ├── Phase 0: Init (Orchestrator)
-            ├── Phase 1-2: Context snapshot + Specify + Plan (Orchestrator)
-            ├── Phase 3: Analyze (Reviewer agent) [tier2] / Phase 4: Analyze [tier3]
-            ├── Phase 3.5: Plan Challenge (Critic agent(s), 1 or 3 parallel) [tier2+]
-            ├── Phase 4: Implement (main orchestrator runs /prizmkit-implement directly)
-            ├── Phase 5: Review (Reviewer agent)
-            └── Phase 6: Retrospective & Commit (Orchestrator)
-            │
-            └── Write session-status.json → exit
+            ├── Context snapshot + specify + plan (Orchestrator)
+            ├── Local plan/spec review loop inside prizmkit-plan
+            ├── Implement (main orchestrator runs /prizmkit-implement directly)
+            ├── Code review (/prizmkit-code-review via Reviewer)
+            ├── Scoped test gate and browser attempt
+            └── Retrospective & commit (Orchestrator)
 ```
 
 ## Agent Definitions (Source of Truth)
 
 | Agent | Definition Path | Type |
 |-------|----------------|------|
-| Dev | `.claude/agents/prizm-dev-team-dev.md` (or `.codebuddy/agents/`) | prizm-dev-team-dev; reserved for targeted fix/specialized handoffs, not top-level feature implementation |
-| Reviewer | `.claude/agents/prizm-dev-team-reviewer.md` (or `.codebuddy/agents/`) | prizm-dev-team-reviewer |
-| Critic | `.claude/agents/prizm-dev-team-critic.md` (or `.codebuddy/agents/`) | prizm-dev-team-critic |
+| Dev | `.claude/agents/prizm-dev-team-dev.md` (or platform equivalent) | reserved for targeted specialized handoffs, not top-level feature implementation |
+| Reviewer | `.claude/agents/prizm-dev-team-reviewer.md` (or platform equivalent) | code review quality gate |
 
-Note: The Orchestrator role is handled by the main agent (session orchestrator) directly — no separate agent definition needed.
+The Orchestrator role is handled by the main agent directly — no separate agent definition needed.
 
 ## Pipeline Scripts
 
@@ -42,96 +38,28 @@ Located at `.prizmkit/dev-pipeline/scripts/`:
 
 | Script | Purpose |
 |--------|---------|
-| `init-dev-team.py` | Initialize `.dev-team/` + `.prizmkit/` directories |
-| `init-pipeline.py` | Initialize pipeline state directories and config |
+| `init-pipeline.py` | Initialize feature pipeline state |
 | `init-bugfix-pipeline.py` | Initialize bugfix pipeline state |
-| `generate-bootstrap-prompt.py` | Render tier-specific bootstrap prompt with feature context |
+| `init-refactor-pipeline.py` | Initialize refactor pipeline state |
+| `generate-bootstrap-prompt.py` | Render feature bootstrap prompt with feature context |
 | `generate-bugfix-prompt.py` | Render bugfix bootstrap prompt with bug context |
-| `update-feature-status.py` | Update feature status in feature-list.json after session |
-| `update-bug-status.py` | Update bug status in bug-fix-list.json after session |
-| `check-session-status.py` | Read and validate session-status.json output |
-| `detect-stuck.py` | Detect stuck/hung pipeline sessions via heartbeat |
+| `generate-refactor-prompt.py` | Render refactor bootstrap prompt with refactor context |
+| `update-feature-status.py` | Update feature status after session |
+| `update-bug-status.py` | Update bug status after session |
+| `update-refactor-status.py` | Update refactor status after session |
+| `check-session-status.py` | Read and validate session-status output |
+| `detect-stuck.py` | Detect stuck or stale pipeline sessions |
 | `parse-stream-progress.py` | Parse AI CLI output stream for progress tracking |
 | `utils.py` | Shared utility functions for pipeline scripts |
 
-## Artifact Mapping
-
-### PrizmKit Artifacts (.prizmkit/)
-
-| Phase | File | Content |
-|-------|------|---------|
-| 1 | `specs/spec.md` | Feature specification (WHAT/WHY) |
-| 2 | `plans/plan.md` | Technical plan (architecture, API, tests) |
-| 3 | `tasks/tasks.md` | Executable task list with `[ ]` / `[x]` (legacy — now part of plan.md Tasks section) |
-| 4 | `analysis/analyze-report.md` | Consistency analysis |
-
-### Dev-Team Artifacts (.dev-team/)
-
-| Phase | File | Content |
-|-------|------|---------|
-| 1 | `specs/requirements.md` | Requirements with REQ-NNN IDs |
-| 2 | `contracts/*.contract.json` | Interface contracts |
-| 2 | `contracts/data-models.json` | Data entity definitions |
-| 3 | `tasks/task-manifest.json` | Structured tasks with T-NNN IDs |
-| 3 | `tasks/dependency-graph.json` | Task DAG |
-| 6 | `reports/dev/self-test-*.md` | Dev self-test reports |
-| 7 | `reports/qa/integration-test.md` | QA integration test report |
-| 7 | `reports/review/code-review.md` | Review report |
-
 ## Session Lifecycle
 
-### 1. Session Start
-
-The bootstrap prompt instructs the agent to:
-- Execute phases directly as the session orchestrator
-- Spawn Dev and Reviewer agents as subagents for implementation and review phases
-- The orchestrator handles context building, planning, retrospective, and commit phases directly
-
-### 2. Pipeline Execution
-
-The Orchestrator drives the pipeline phases with checkpoints (CP-0 through CP-3). Each checkpoint validates artifacts.
-
-### 3. Session End
-
-The agent MUST write `session-status.json` before exiting:
-
-```json
-{
-  "session_id": "F-001-20260304100000",
-  "feature_id": "F-001",
-  "status": "success",
-  "completed_phases": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
-  "current_phase": 9,
-  "checkpoint_reached": "CP-7",
-  "tasks_completed": 12,
-  "tasks_total": 12,
-  "errors": [],
-  "can_resume": false,
-  "resume_from_phase": null,
-  "artifacts": {
-    "spec_path": ".prizmkit/specs/spec.md",
-    "plan_path": ".prizmkit/plans/plan.md"
-  },
-  "timestamp": "2026-03-04T11:30:00Z"
-}
-```
+1. Runtime selects the next eligible item from the plan list.
+2. Prompt generator renders a session prompt and checkpoint file.
+3. AI CLI session executes the generated prompt in the active project checkout or runner-owned worktree.
+4. Session writes status and completion artifacts.
+5. Runtime updates plan-list status and propagates completion notes.
 
 ## Failure Recovery
 
-| Session Outcome | Pipeline Action |
-|-----------------|-----------------|
-| `status: "success"` | Mark feature completed, pick next |
-| `status: "partial"`, `can_resume: true` | Resume from `resume_from_phase` |
-| `status: "partial"`, `can_resume: false` | Retry from scratch |
-| `status: "failed"` | Retry (up to MAX_RETRIES) |
-| No status file (crash) | Treat as failed, retry |
-
-## Team Naming Convention
-
-Each feature gets its own team instance: `prizm-dev-team-{FEATURE_ID}`
-
-Examples:
-- `prizm-dev-team-F-001` — User Authentication
-- `prizm-dev-team-F-002` — Dashboard
-
-This ensures clean isolation between features and allows multiple features to have separate artifact histories.
+The generated checkpoint file is the recovery truth. Continuation prompts resume from the first pending or in-progress checkpoint step and prefer synthesized artifacts over full log rereads.

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

@@ -0,0 +1,283 @@
+"""Shared workflow-checkpoint.json reader and validator."""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Mapping
+
+VALID_CHECKPOINT_STATUSES = {"pending", "in_progress", "completed", "skipped", "failed"}
+TERMINAL_STEP_STATUSES = {"completed", "skipped"}
+STEP_ID_PATTERN = re.compile(r"^S[0-9]+$")
+
+
+@dataclass(frozen=True)
+class CheckpointStep:
+    """Validated workflow checkpoint step."""
+
+    id: str
+    skill: str
+    name: str
+    status: str
+    depends_on: str | None = None
+    required_artifacts: tuple[str, ...] = ()
+    index: int = 0
+
+    @property
+    def number(self) -> int:
+        """Return the numeric cursor component from an SNN step ID."""
+        return int(self.id[1:])
+
+    @property
+    def label(self) -> str:
+        """Return a compact human label for cursor summaries."""
+        return f"{self.id} ({self.skill})"
+
+
+@dataclass(frozen=True)
+class CheckpointState:
+    """Result of loading and validating one workflow checkpoint."""
+
+    path: Path | None
+    exists: bool
+    valid: bool
+    error_code: str = ""
+    error_message: str = ""
+    steps: tuple[CheckpointStep, ...] = ()
+    current_step: CheckpointStep | None = None
+    all_completed: bool = False
+    duplicate_skills: Mapping[str, tuple[str, ...]] = field(default_factory=dict)
+    raw_data: Mapping[str, Any] | None = None
+
+    @property
+    def current_step_name(self) -> str:
+        """Return the user-facing phase label, or an empty string when unavailable."""
+        return self.current_step.name if self.valid and self.current_step is not None else ""
+
+    @property
+    def cursor(self) -> int | None:
+        """Return the current numeric cursor for valid checkpoints."""
+        if not self.valid:
+            return None
+        if self.current_step is not None:
+            return self.current_step.number
+        if self.steps:
+            return self.steps[-1].number
+        return None
+
+    @property
+    def cursor_signature(self) -> str:
+        """Return a stable progress fingerprint cursor string."""
+        if not self.valid:
+            return f"invalid:{self.error_code}" if self.exists else ""
+        if self.all_completed:
+            return "complete"
+        if self.current_step is None:
+            return ""
+        return f"{self.current_step.id}:{self.current_step.skill}:{self.current_step.status}"
+
+
+def load_checkpoint_state(path: str | Path | None) -> CheckpointState:
+    """Load and validate one workflow-checkpoint.json file."""
+    checkpoint_path = Path(path) if path is not None else None
+    if checkpoint_path is None or not checkpoint_path.is_file():
+        return _invalid(checkpoint_path, False, "missing", "Checkpoint file not found")
+    try:
+        data = json.loads(checkpoint_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        return _invalid(checkpoint_path, True, "malformed_json", f"Malformed checkpoint JSON: {exc}")
+    except OSError as exc:
+        return _invalid(checkpoint_path, True, "read_error", f"Cannot read checkpoint: {exc}")
+    return validate_checkpoint_data(data, path=checkpoint_path, exists=True)
+
+
+def validate_checkpoint_data(
+    data: Any,
+    *,
+    path: str | Path | None = None,
+    exists: bool = True,
+) -> CheckpointState:
+    """Validate already-loaded checkpoint data."""
+    checkpoint_path = Path(path) if path is not None else None
+    if not isinstance(data, dict):
+        return _invalid(checkpoint_path, exists, "invalid_root", "Checkpoint root must be an object")
+
+    raw_steps = data.get("steps")
+    if raw_steps is None:
+        return _invalid(checkpoint_path, exists, "missing_steps", "Checkpoint is missing a steps array", data)
+    if not isinstance(raw_steps, list):
+        return _invalid(checkpoint_path, exists, "invalid_steps", "Checkpoint steps must be an array", data)
+    if not raw_steps:
+        return _invalid(checkpoint_path, exists, "empty_steps", "Checkpoint steps array must not be empty", data)
+
+    seen_ids: dict[str, int] = {}
+    steps: list[CheckpointStep] = []
+    skill_to_ids: dict[str, list[str]] = {}
+    pending_depends_on: list[tuple[str, str]] = []
+
+    for index, raw_step in enumerate(raw_steps):
+        if not isinstance(raw_step, dict):
+            return _invalid(checkpoint_path, exists, "invalid_step", f"Step at index {index} must be an object", data)
+
+        step_id = raw_step.get("id")
+        if not isinstance(step_id, str) or not STEP_ID_PATTERN.match(step_id):
+            return _invalid(checkpoint_path, exists, "malformed_step_id", f"Step at index {index} has malformed id", data)
+        if step_id in seen_ids:
+            return _invalid(checkpoint_path, exists, "duplicate_step_id", f"Duplicate step id: {step_id}", data)
+        seen_ids[step_id] = index
+
+        skill = raw_step.get("skill")
+        if not isinstance(skill, str) or not skill.strip():
+            return _invalid(checkpoint_path, exists, "invalid_skill", f"Step {step_id} has invalid skill", data)
+        skill = skill.strip()
+
+        name = raw_step.get("name")
+        if not isinstance(name, str) or not name.strip():
+            return _invalid(checkpoint_path, exists, "invalid_step_name", f"Step {step_id} has invalid name", data)
+        name = name.strip()
+
+        status = raw_step.get("status")
+        if status not in VALID_CHECKPOINT_STATUSES:
+            return _invalid(checkpoint_path, exists, "invalid_status", f"Step {step_id} has invalid status", data)
+
+        depends_on = raw_step.get("depends_on")
+        if depends_on is not None:
+            if not isinstance(depends_on, str) or not STEP_ID_PATTERN.match(depends_on):
+                return _invalid(checkpoint_path, exists, "invalid_depends_on", f"Step {step_id} has invalid depends_on", data)
+            if depends_on == step_id:
+                return _invalid(checkpoint_path, exists, "invalid_depends_on", f"Step {step_id} depends on itself", data)
+            pending_depends_on.append((step_id, depends_on))
+
+        artifacts = raw_step.get("required_artifacts", [])
+        if artifacts is None:
+            artifacts = []
+        if not isinstance(artifacts, list) or any(not isinstance(item, str) for item in artifacts):
+            return _invalid(checkpoint_path, exists, "invalid_required_artifacts", f"Step {step_id} has invalid required_artifacts", data)
+
+        step = CheckpointStep(
+            id=step_id,
+            skill=skill,
+            name=name,
+            status=str(status),
+            depends_on=depends_on,
+            required_artifacts=tuple(artifacts),
+            index=index,
+        )
+        steps.append(step)
+        skill_to_ids.setdefault(skill, []).append(step_id)
+
+    for step_id, dependency_id in pending_depends_on:
+        if dependency_id not in seen_ids:
+            return _invalid(
+                checkpoint_path,
+                exists,
+                "invalid_depends_on",
+                f"Step {step_id} depends on missing step {dependency_id}",
+                data,
+            )
+        if seen_ids[dependency_id] >= seen_ids[step_id]:
+            return _invalid(
+                checkpoint_path,
+                exists,
+                "invalid_depends_on",
+                f"Step {step_id} depends on non-prior step {dependency_id}",
+                data,
+            )
+
+    duplicate_skills = {
+        skill: tuple(ids)
+        for skill, ids in skill_to_ids.items()
+        if len(ids) > 1
+    }
+    current_step = next((step for step in steps if step.status not in TERMINAL_STEP_STATUSES), None)
+    return CheckpointState(
+        path=checkpoint_path,
+        exists=exists,
+        valid=True,
+        steps=tuple(steps),
+        current_step=current_step,
+        all_completed=current_step is None,
+        duplicate_skills=duplicate_skills,
+        raw_data=data,
+    )
+
+
+def read_checkpoint_cursor(path: str | Path | None) -> int | None:
+    """Read the numeric cursor from a valid workflow checkpoint."""
+    return load_checkpoint_state(path).cursor
+
+
+def checkpoint_cursor(checkpoint: Mapping[str, Any] | None) -> dict[str, object]:
+    """Summarize checkpoint step groups and the first active cursor."""
+    state = validate_checkpoint_data(checkpoint or {}, exists=checkpoint is not None)
+    if not state.valid:
+        return {
+            "valid": False,
+            "error_code": state.error_code,
+            "error_message": state.error_message,
+            "completed": [],
+            "skipped": [],
+            "in_progress": [],
+            "pending": [],
+            "failed": [],
+            "first_cursor": f"(invalid checkpoint: {state.error_code})",
+            "current_step_name": "",
+        }
+
+    grouped: dict[str, list[str]] = {
+        "completed": [],
+        "skipped": [],
+        "in_progress": [],
+        "pending": [],
+        "failed": [],
+    }
+    first_cursor = "(all checkpoint steps completed or skipped)"
+    for step in state.steps:
+        grouped[step.status].append(step.label)
+        if step is state.current_step:
+            first_cursor = step.label
+
+    return {
+        "valid": True,
+        "error_code": "",
+        "error_message": "",
+        "completed": grouped["completed"],
+        "skipped": grouped["skipped"],
+        "in_progress": grouped["in_progress"],
+        "pending": grouped["pending"],
+        "failed": grouped["failed"],
+        "first_cursor": first_cursor,
+        "current_step_name": state.current_step_name,
+    }
+
+
+def completed_workflow_state(path: str | Path | None) -> CheckpointState:
+    """Return checkpoint state for completed-workflow evidence checks."""
+    return load_checkpoint_state(path)
+
+
+def invalid_existing_checkpoint(path: str | Path | None) -> CheckpointState | None:
+    """Return invalid state only when a checkpoint file exists but is invalid."""
+    state = load_checkpoint_state(path)
+    if state.exists and not state.valid:
+        return state
+    return None
+
+
+def _invalid(
+    path: Path | None,
+    exists: bool,
+    code: str,
+    message: str,
+    raw_data: Mapping[str, Any] | None = None,
+) -> CheckpointState:
+    return CheckpointState(
+        path=path,
+        exists=exists,
+        valid=False,
+        error_code=code,
+        error_message=message,
+        raw_data=raw_data,
+    )

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

@@ -39,7 +39,6 @@ class DaemonStartOptions:
     env_overrides: str = ""
     mode: str = ""
     features_filter: str = ""
-    critic: bool | None = None
     help_requested: bool = False
 
 
@@ -247,7 +246,6 @@ def _parse_start_args(family: RunnerFamily, legacy_args: tuple[str, ...]) -> Dae
     env_overrides = ""
     mode = ""
     features_filter = ""
-    critic: bool | None = None
     help_requested = False
     positional: list[str] = []
     index = 0
@@ -266,16 +264,14 @@ def _parse_start_args(family: RunnerFamily, legacy_args: tuple[str, ...]) -> Dae
         elif arg == "--features" and index + 1 < len(legacy_args):
             index += 1
             features_filter = legacy_args[index]
-        elif arg == "--critic":
-            critic = True
-        elif arg == "--no-critic":
-            critic = False
+        elif arg.startswith("-"):
+            raise ValueError("Unsupported option: {}".format(arg))
         else:
             positional.append(arg)
         index += 1
     if positional:
         list_path = Path(positional[0]).expanduser()
-    return DaemonStartOptions(list_path=list_path, env_overrides=env_overrides, mode=mode, features_filter=features_filter, critic=critic, help_requested=help_requested)
+    return DaemonStartOptions(list_path=list_path, env_overrides=env_overrides, mode=mode, features_filter=features_filter, help_requested=help_requested)
 
 
 def _parse_log_args(legacy_args: tuple[str, ...]) -> DaemonLogOptions:
@@ -312,10 +308,6 @@ def _payload_command(family: RunnerFamily, paths, list_path: Path, options: Daem
         command.extend(["--features", options.features_filter])
     if options.mode:
         command.extend(["--mode", options.mode])
-    if options.critic is True:
-        command.append("--critic")
-    elif options.critic is False:
-        command.append("--no-critic")
     return command
 
 
@@ -328,8 +320,6 @@ def _daemon_env(options: DaemonStartOptions) -> dict[str, str]:
                 env[key] = value
     if options.mode:
         env["PIPELINE_MODE"] = options.mode
-    if options.critic is not None:
-        env["ENABLE_CRITIC"] = "true" if options.critic else "false"
     return env
 
 

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

@@ -31,6 +31,8 @@ HIDDEN_TOOL_WORKTREE_EXCLUDES = (
     ":(top,exclude,glob).prizmkit/prizm-docs/**",
     ":(top,exclude).prizmkit/config.json",
     ":(top,exclude).prizmkit/manifest.json",
+    ":(top,exclude).prizmkit/state",
+    ":(top,exclude,glob).prizmkit/state/**",
     ":(top,exclude).prizmkit/dev-pipeline/scripts",
     ":(top,exclude,glob).prizmkit/dev-pipeline/scripts/**",
     ":(top,exclude).prizmkit/dev-pipeline/prizmkit_runtime",

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

@@ -69,7 +69,6 @@ def _progress_signature(path: Path | None) -> tuple[str, str]:
     child_signature = str(data.get("child_activity_signature") or "")
     signature = json.dumps(
         [
-            data.get("current_phase") or "",
             data.get("current_tool") or "",
             int(data.get("message_count") or 0),
             int(data.get("total_tool_calls") or 0),

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

@@ -42,6 +42,10 @@ def _repo_path(project_root: Path, path: Path) -> str:
         return path.as_posix()
 
 
+def _visible_status_result(project_root: Path) -> GitCommandResult:
+    return run_git_command(project_root, ("status", "--porcelain", "--", ".", *HIDDEN_TOOL_WORKTREE_EXCLUDES))
+
+
 def _changed_paths_in(project_root: Path, paths: Sequence[str]) -> tuple[str, ...]:
     result = run_git_command(project_root, ("status", "--porcelain", "--", *paths))
     if result.return_code != 0:
@@ -73,7 +77,10 @@ def commit_bookkeeping_changes(
 
 def commit_preflight_ready_changes(project_root: Path, item_id: str) -> BookkeepingResult:
     """Preserve visible pre-existing changes before task branch setup."""
-    if not git_status_safe(project_root).strip():
+    visible_status = _visible_status_result(project_root)
+    if visible_status.return_code != 0:
+        return BookkeepingResult(attempted=True, committed=False, result=visible_status)
+    if not visible_status.stdout.strip():
         return BookkeepingResult(attempted=False, committed=False)
     add_result = run_git_command(project_root, ("add", "-A", "--", ".", *HIDDEN_TOOL_WORKTREE_EXCLUDES))
     if add_result.return_code != 0:
@@ -82,7 +89,12 @@ def commit_preflight_ready_changes(project_root: Path, item_id: str) -> Bookkeep
         project_root,
         ("commit", "--no-verify", "-m", f"chore: ready for {item_id}", "--", ".", *HIDDEN_TOOL_WORKTREE_EXCLUDES),
     )
-    return BookkeepingResult(attempted=True, committed=result.return_code == 0, result=result)
+    if result.return_code != 0:
+        return BookkeepingResult(attempted=True, committed=False, result=result)
+    clean_result = _visible_status_result(project_root)
+    if clean_result.return_code != 0 or clean_result.stdout.strip():
+        return BookkeepingResult(attempted=True, committed=False, result=clean_result)
+    return BookkeepingResult(attempted=True, committed=True, result=result)
 
 
 def commit_task_branch_changes(

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

@@ -3,10 +3,10 @@
 from __future__ import annotations
 
 import hashlib
-import json
 import subprocess
 from pathlib import Path
 
+from .checkpoint_state import load_checkpoint_state
 from .gitops import HIDDEN_TOOL_WORKTREE_EXCLUDES, git_status_safe, run_git_command
 from .runner_models import PromptGenerationResult, SessionClassification
 from .sessions import AISessionResult
@@ -47,6 +47,13 @@ def classify_session(
 ) -> SessionClassification:
     """Classify raw AI session signals with durable success precedence."""
     fingerprint = progress_fingerprint(project_root, prompt)
+    invalid_checkpoint = _invalid_existing_workflow_checkpoint(prompt)
+    if invalid_checkpoint is not None:
+        return SessionClassification(
+            "crashed",
+            reason=f"invalid_workflow_checkpoint:{invalid_checkpoint.error_code}",
+            progress_fingerprint=fingerprint,
+        )
     has_commit_since_base = _has_commit_since(project_root, base_head)
 
     if _is_terminal_success(result) and _has_completed_workflow_artifact(prompt):
@@ -108,11 +115,7 @@ def progress_fingerprint(project_root: Path, prompt: PromptGenerationResult | No
     if prompt and prompt.artifact_path and prompt.artifact_path.exists():
         artifact_hash = _hash_tree(prompt.artifact_path)
     if prompt and prompt.checkpoint_path and prompt.checkpoint_path.is_file():
-        try:
-            data = json.loads(prompt.checkpoint_path.read_text(encoding="utf-8"))
-            checkpoint_cursor = _checkpoint_cursor(data)
-        except (OSError, json.JSONDecodeError):
-            checkpoint_cursor = "unreadable"
+        checkpoint_cursor = load_checkpoint_state(prompt.checkpoint_path).cursor_signature
     return {
         "git_diff_fingerprint": hashlib.sha256(status_text.encode()).hexdigest(),
         "checkpoint_cursor": checkpoint_cursor,
@@ -146,12 +149,8 @@ def _has_completed_workflow_artifact(prompt: PromptGenerationResult | None) -> b
     if prompt is None:
         return False
     if prompt.checkpoint_path and prompt.checkpoint_path.is_file():
-        try:
-            data = json.loads(prompt.checkpoint_path.read_text(encoding="utf-8"))
-        except (OSError, json.JSONDecodeError):
-            data = {}
-        if isinstance(data, dict) and _checkpoint_cursor(data) == "complete":
-            return True
+        state = load_checkpoint_state(prompt.checkpoint_path)
+        return state.valid and state.all_completed
     if prompt.artifact_path and has_completed_artifact_path(prompt.artifact_path):
         return True
     return False
@@ -169,15 +168,23 @@ def has_completed_artifact_path(artifact_path: Path | None) -> bool:
         return False
     checkpoint = artifact_path / "workflow-checkpoint.json"
     if checkpoint.is_file():
-        try:
-            data = json.loads(checkpoint.read_text(encoding="utf-8"))
-        except (OSError, json.JSONDecodeError):
-            data = {}
-        if isinstance(data, dict) and _checkpoint_cursor(data) == "complete":
-            return True
+        state = load_checkpoint_state(checkpoint)
+        return state.valid and state.all_completed
     return (artifact_path / "completion-summary.json").is_file()
 
 
+def _invalid_existing_workflow_checkpoint(prompt: PromptGenerationResult | None):
+    if prompt is None:
+        return None
+    checkpoint = prompt.checkpoint_path
+    if checkpoint is None and prompt.artifact_path is not None:
+        checkpoint = prompt.artifact_path / "workflow-checkpoint.json"
+    if checkpoint is None or not checkpoint.is_file():
+        return None
+    state = load_checkpoint_state(checkpoint)
+    return state if not state.valid else None
+
+
 def _next_no_progress_count(previous: object | None, current: object, count: int) -> int:
     if previous and previous == current:
         return max(0, count) + 1
@@ -251,16 +258,3 @@ def _hash_tree(path: Path) -> str:
             except OSError:
                 continue
     return digest.hexdigest()
-
-
-def _checkpoint_cursor(data: dict[str, object]) -> str:
-    steps = data.get("steps")
-    if not isinstance(steps, list):
-        return ""
-    for step in steps:
-        if not isinstance(step, dict):
-            continue
-        status = step.get("status", "pending")
-        if status not in {"completed", "skipped"}:
-            return f"{step.get('id', '?')}:{step.get('skill', 'unknown')}:{status}"
-    return "complete"