prizmkit 1.1.3 → 1.1.5

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.1.3",
-  "bundledAt": "2026-04-04T02:47:27.664Z",
-  "bundledFrom": "f15da00"
+  "frameworkVersion": "1.1.5",
+  "bundledAt": "2026-04-04T15:56:26.382Z",
+  "bundledFrom": "902d4ef"
 }

package/bundled/dev-pipeline/run-bugfix.sh

@@ -224,6 +224,41 @@ spawn_and_wait_session() {
 
     log_info "Session result: $session_status"
 
+    # Validate checkpoint completeness after successful session
+    if [[ "$session_status" == "success" ]]; then
+        local _ckpt_root
+        _ckpt_root="$(cd "$SCRIPT_DIR/.." && pwd)"
+        local checkpoint_file="$_ckpt_root/.prizmkit/bugfix/${bug_id}/workflow-checkpoint.json"
+        if [[ -f "$checkpoint_file" ]]; then
+            local checkpoint_result
+            checkpoint_result=$(python3 -c "
+import json, sys
+try:
+    with open(sys.argv[1]) as f:
+        data = json.load(f)
+except json.JSONDecodeError as e:
+    print('CORRUPTED: {}'.format(e))
+    sys.exit(2)
+incomplete = [s for s in data['steps'] if s['status'] not in ('completed', 'skipped')]
+if incomplete:
+    for s in incomplete:
+        print('INCOMPLETE: {} {} = {}'.format(s['id'], s['skill'], s['status']))
+    sys.exit(1)
+print('ALL_COMPLETE')
+sys.exit(0)
+" "$checkpoint_file" 2>&1)
+            local check_exit=$?
+            if [[ $check_exit -eq 2 ]]; then
+                log_warn "CHECKPOINT_CORRUPTED: workflow-checkpoint.json is not valid JSON"
+            elif [[ $check_exit -eq 1 ]]; then
+                log_warn "CHECKPOINT_INCOMPLETE: Not all workflow steps completed:"
+                echo "$checkpoint_result" | while read -r line; do log_warn "  $line"; done
+            else
+                log_info "CHECKPOINT: All workflow steps completed"
+            fi
+        fi
+    fi
+
     # Subagent detection
     prizm_detect_subagents "$session_log"
 

package/bundled/dev-pipeline/run-feature.sh

@@ -287,6 +287,39 @@ sys.exit(1)
         if [[ ! -f "$plan_file" ]]; then
             log_warn "ARTIFACT_MISSING: plan.md not found at $plan_file"
         fi
+
+        # Validate checkpoint completeness
+        local checkpoint_file="$project_root_for_artifacts/.prizmkit/specs/${feature_slug}/workflow-checkpoint.json"
+        if [[ -f "$checkpoint_file" ]]; then
+            local checkpoint_result
+            checkpoint_result=$(python3 -c "
+import json, sys
+try:
+    with open(sys.argv[1]) as f:
+        data = json.load(f)
+except json.JSONDecodeError as e:
+    print('CORRUPTED: {}'.format(e))
+    sys.exit(2)
+incomplete = [s for s in data['steps'] if s['status'] not in ('completed', 'skipped')]
+if incomplete:
+    for s in incomplete:
+        print('INCOMPLETE: {} {} = {}'.format(s['id'], s['skill'], s['status']))
+    sys.exit(1)
+print('ALL_COMPLETE')
+sys.exit(0)
+" "$checkpoint_file" 2>&1)
+            local check_exit=$?
+            if [[ $check_exit -eq 2 ]]; then
+                log_warn "CHECKPOINT_CORRUPTED: workflow-checkpoint.json is not valid JSON"
+            elif [[ $check_exit -eq 1 ]]; then
+                log_warn "CHECKPOINT_INCOMPLETE: Not all workflow steps completed:"
+                echo "$checkpoint_result" | while read -r line; do log_warn "  $line"; done
+            else
+                log_info "CHECKPOINT: All workflow steps completed"
+            fi
+        else
+            log_info "CHECKPOINT: No workflow-checkpoint.json found (checkpoint system not active)"
+        fi
     fi
 
     # Check if session produced a failure-log for future retries

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

@@ -530,6 +530,171 @@ def determine_pipeline_mode(complexity):
     return mapping.get(complexity, "lite")
 
 
+# ============================================================
+# Checkpoint generation
+# ============================================================
+
+# Mapping: section name -> (skill_key, display_name, required_artifacts)
+# skill_key is a unique identifier in the checkpoint, not necessarily the
+# prizmkit skill name.  This ensures each section has a distinct key so
+# merge_checkpoint_state() never collides.
+SECTION_TO_SKILL = {
+    "phase0-init": ("prizmkit-init", "Project Bootstrap",
+                    [".prizm-docs/root.prizm", ".prizmkit/config.json"]),
+    "phase0-test-baseline": ("test-baseline", "Test Baseline", []),
+    "phase-context-snapshot": ("context-snapshot", "Build Context Snapshot",
+                               [".prizmkit/specs/{slug}/context-snapshot.md"]),
+    "phase-specify-plan": ("context-snapshot-and-plan", "Specify & Plan",
+                           [".prizmkit/specs/{slug}/context-snapshot.md",
+                            ".prizmkit/specs/{slug}/plan.md"]),
+    "phase-plan": ("prizmkit-plan", "Plan & Tasks",
+                   [".prizmkit/specs/{slug}/plan.md"]),
+    "phase-analyze": ("prizmkit-analyze", "Analyze", []),
+    "phase-critic-plan": ("critic-plan-review", "Critic: Plan Review", []),
+    "phase-implement": ("prizmkit-implement", "Implement + Test", []),
+    "phase-critic-code": ("critic-code-review", "Critic: Code Review", []),
+    "phase-review": ("prizmkit-code-review", "Code Review", []),
+    "phase-browser": ("browser-verification", "Browser Verification", []),
+    "phase-deploy": ("deploy-verification", "Deploy Verification", []),
+    "phase-commit": None,  # special: split into retrospective + committer
+}
+
+# phase-commit is split into two steps
+_COMMIT_STEPS = [
+    ("prizmkit-retrospective", "Retrospective", []),
+    ("prizmkit-committer", "Commit", []),
+]
+
+
+def _resolve_artifacts(artifact_templates, slug):
+    """Replace {slug} placeholder with the actual feature slug."""
+    return [a.replace("{slug}", slug) for a in artifact_templates]
+
+
+def generate_checkpoint_definition(sections, pipeline_mode, workflow_type,
+                                   item_id, item_slug, session_id,
+                                   init_done=False):
+    """Derive checkpoint step definitions from the assembled sections list.
+
+    Args:
+        sections: list of (name, content) tuples from assemble_sections()
+        pipeline_mode: "lite" | "standard" | "full"
+        workflow_type: "feature-pipeline"
+        item_id: feature ID (e.g. "F-001")
+        item_slug: feature slug (e.g. "001-user-auth")
+        session_id: current session ID
+        init_done: whether project is already initialized (Phase 0 skip)
+
+    Returns:
+        dict suitable for writing as workflow-checkpoint.json
+    """
+    steps = []
+    step_counter = 1
+    prev_step_id = None
+
+    for section_name, _content in sections:
+        if section_name not in SECTION_TO_SKILL:
+            continue
+
+        mapping = SECTION_TO_SKILL[section_name]
+
+        if mapping is None:
+            # phase-commit -> split into retrospective + committer
+            for skill, name, artifacts in _COMMIT_STEPS:
+                step_id = "S{:02d}".format(step_counter)
+                steps.append({
+                    "id": step_id,
+                    "skill": skill,
+                    "name": name,
+                    "status": "pending",
+                    "required_artifacts": _resolve_artifacts(artifacts, item_slug),
+                    "depends_on": prev_step_id,
+                })
+                prev_step_id = step_id
+                step_counter += 1
+            continue
+
+        skill, name, artifacts = mapping
+        step_id = "S{:02d}".format(step_counter)
+
+        status = "pending"
+        if init_done and section_name in ("phase0-init", "phase0-test-baseline"):
+            status = "skipped"
+
+        steps.append({
+            "id": step_id,
+            "skill": skill,
+            "name": name,
+            "status": status,
+            "required_artifacts": _resolve_artifacts(artifacts, item_slug),
+            "depends_on": prev_step_id,
+        })
+
+        prev_step_id = step_id
+        step_counter += 1
+
+    return {
+        "version": 1,
+        "workflow_type": workflow_type,
+        "pipeline_mode": pipeline_mode,
+        "item_id": item_id,
+        "item_slug": item_slug,
+        "session_id": session_id,
+        "steps": steps,
+    }
+
+
+def merge_checkpoint_state(existing, fresh, project_root):
+    """Merge existing checkpoint state into a freshly generated definition.
+
+    Matching is by skill_key (not step ID), since tier changes across retries
+    may shift step IDs.
+
+    Merge rules:
+    1. Only keep completed steps whose required_artifacts all exist on disk
+    2. Keep skipped steps unconditionally
+    3. Once a step is NOT completed/skipped, break the dependency chain:
+       all subsequent steps reset to pending
+    """
+    existing_status = {}
+    existing_artifacts = {}
+    for step in existing.get("steps", []):
+        existing_status[step["skill"]] = step["status"]
+        existing_artifacts[step["skill"]] = step.get("required_artifacts", [])
+
+    # Determine which completed steps have valid artifacts
+    valid_completed = set()
+    for skill_key, status in existing_status.items():
+        if status == "completed":
+            artifacts = existing_artifacts.get(skill_key, [])
+            if all(os.path.exists(os.path.join(project_root, a))
+                   for a in artifacts):
+                valid_completed.add(skill_key)
+            else:
+                LOGGER.warning(
+                    "Step '%s' was completed but artifacts missing — "
+                    "resetting to pending", skill_key
+                )
+        elif status == "skipped":
+            valid_completed.add(skill_key)
+
+    # Apply to fresh steps; break chain on first non-valid step
+    chain_broken = False
+    for step in fresh["steps"]:
+        if chain_broken:
+            step["status"] = "pending"
+            continue
+
+        prev = existing_status.get(step["skill"])
+        if step["skill"] in valid_completed:
+            step["status"] = prev  # completed or skipped
+        else:
+            chain_broken = True
+            step["status"] = "pending"
+
+    return fresh
+
+
 # ============================================================
 # Section Assembly (new modular approach)
 # ============================================================
@@ -721,6 +886,12 @@ def assemble_sections(pipeline_mode, sections_dir, init_done, is_resume,
                           load_section(sections_dir,
                                        "subagent-timeout-recovery.md")))
 
+    # --- Checkpoint System ---
+    checkpoint_section_path = os.path.join(sections_dir, "checkpoint-system.md")
+    if os.path.isfile(checkpoint_section_path):
+        sections.append(("checkpoint-system",
+                          load_section(sections_dir, "checkpoint-system.md")))
+
     # --- Execution header ---
     sections.append(("execution-header", "---\n\n## Execution\n"))
 
@@ -1143,6 +1314,9 @@ def build_replacements(args, feature, features, global_context, script_dir):
         "{{SESSION_STATUS_PATH}}": session_status_abs,
         "{{PROJECT_ROOT}}": project_root,
         "{{FEATURE_SLUG}}": feature_slug,
+        "{{CHECKPOINT_PATH}}": os.path.join(
+            ".prizmkit", "specs", feature_slug, "workflow-checkpoint.json",
+        ),
         "{{PIPELINE_MODE}}": pipeline_mode,
         "{{COMPLEXITY}}": complexity,
         "{{CRITIC_ENABLED}}": "true" if critic_enabled else "false",
@@ -1314,6 +1488,52 @@ def main():
     if err:
         emit_failure(err)
 
+    # ── Generate checkpoint file ──────────────────────────────────────
+    project_root = resolve_project_root(
+        os.path.dirname(os.path.abspath(__file__))
+    )
+    feature_slug = replacements.get("{{FEATURE_SLUG}}", "")
+    checkpoint_path = ""
+
+    if use_sections and feature_slug:
+        checkpoint = generate_checkpoint_definition(
+            sections=sections,
+            pipeline_mode=pipeline_mode,
+            workflow_type="feature-pipeline",
+            item_id=args.feature_id,
+            item_slug=feature_slug,
+            session_id=args.session_id,
+            init_done=init_done,
+        )
+
+        checkpoint_dir = os.path.join(
+            project_root, ".prizmkit", "specs", feature_slug,
+        )
+        os.makedirs(checkpoint_dir, exist_ok=True)
+        checkpoint_path = os.path.join(
+            checkpoint_dir, "workflow-checkpoint.json",
+        )
+
+        # On resume, merge existing completed state (with artifact validation)
+        if is_resume and os.path.exists(checkpoint_path):
+            try:
+                with open(checkpoint_path, "r", encoding="utf-8") as f:
+                    existing = json.load(f)
+                checkpoint = merge_checkpoint_state(
+                    existing, checkpoint, project_root,
+                )
+                LOGGER.info("Merged existing checkpoint state from %s",
+                            checkpoint_path)
+            except (json.JSONDecodeError, KeyError) as exc:
+                LOGGER.warning(
+                    "Existing checkpoint corrupted (%s) — generating fresh",
+                    exc,
+                )
+
+        with open(checkpoint_path, "w", encoding="utf-8") as f:
+            json.dump(checkpoint, f, indent=2, ensure_ascii=False)
+        LOGGER.info("Wrote checkpoint to %s", checkpoint_path)
+
     # ── Success JSON ───────────────────────────────────────────────────
     feature_model = feature.get("model", "")
     mode_agent_counts = {"lite": 1, "standard": 3, "full": 3}
@@ -1331,6 +1551,7 @@ def main():
         "render_mode": "sections" if use_sections else "legacy",
         "validation_warnings": len(warnings),
         "validation_errors": len(errors),
+        "checkpoint_path": checkpoint_path,
     }
     print(json.dumps(output, indent=2, ensure_ascii=False))
     sys.exit(0)

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

@@ -324,6 +324,95 @@ def emit_failure(message):
     sys.exit(1)
 
 
+# ============================================================
+# Checkpoint generation for bugfix pipeline
+# ============================================================
+
+BUGFIX_STEPS = [
+    ("prizmkit-init", "Initialize", []),
+    ("bug-diagnosis", "Bug Diagnosis & Fix Plan",
+     [".prizmkit/bugfix/{slug}/fix-plan.md"]),
+    ("bug-reproduce", "Write Reproduction Test", []),
+    ("bug-fix", "Implement Fix", []),
+    ("prizmkit-code-review", "Code Review", []),
+    ("prizmkit-committer", "Commit", []),
+    ("bug-report", "Generate Fix Report & Update TRAPS",
+     [".prizmkit/bugfix/{slug}/fix-report.md"]),
+]
+
+
+def generate_bugfix_checkpoint(bug_id, session_id):
+    """Generate a checkpoint definition for bugfix pipeline.
+
+    Returns a dict suitable for writing as workflow-checkpoint.json.
+    """
+    steps = []
+    prev_id = None
+    for i, (skill, name, artifacts) in enumerate(BUGFIX_STEPS, 1):
+        step_id = "S{:02d}".format(i)
+        steps.append({
+            "id": step_id,
+            "skill": skill,
+            "name": name,
+            "status": "pending",
+            "required_artifacts": [a.replace("{slug}", bug_id) for a in artifacts],
+            "depends_on": prev_id,
+        })
+        prev_id = step_id
+
+    return {
+        "version": 1,
+        "workflow_type": "bugfix-pipeline",
+        "pipeline_mode": "single",
+        "item_id": bug_id,
+        "item_slug": bug_id,
+        "session_id": session_id,
+        "steps": steps,
+    }
+
+
+def merge_bugfix_checkpoint_state(existing, fresh, project_root):
+    """Merge existing bugfix checkpoint state into fresh definition.
+
+    Same logic as feature pipeline: validate artifacts, break chain on
+    first invalid step.
+    """
+    existing_status = {}
+    existing_artifacts = {}
+    for step in existing.get("steps", []):
+        existing_status[step["skill"]] = step["status"]
+        existing_artifacts[step["skill"]] = step.get("required_artifacts", [])
+
+    valid_completed = set()
+    for skill_key, status in existing_status.items():
+        if status == "completed":
+            artifacts = existing_artifacts.get(skill_key, [])
+            if all(os.path.exists(os.path.join(project_root, a))
+                   for a in artifacts):
+                valid_completed.add(skill_key)
+            else:
+                LOGGER.warning(
+                    "Step '%s' was completed but artifacts missing — "
+                    "resetting to pending", skill_key
+                )
+        elif status == "skipped":
+            valid_completed.add(skill_key)
+
+    chain_broken = False
+    for step in fresh["steps"]:
+        if chain_broken:
+            step["status"] = "pending"
+            continue
+        prev = existing_status.get(step["skill"])
+        if step["skill"] in valid_completed:
+            step["status"] = prev
+        else:
+            chain_broken = True
+            step["status"] = "pending"
+
+    return fresh
+
+
 def main():
     args = parse_args()
 
@@ -366,6 +455,12 @@ def main():
     # Build replacements
     replacements = build_replacements(args, bug, global_context, script_dir)
 
+    # Add checkpoint path to replacements
+    checkpoint_rel = os.path.join(
+        ".prizmkit", "bugfix", args.bug_id, "workflow-checkpoint.json",
+    )
+    replacements["{{CHECKPOINT_PATH}}"] = checkpoint_rel
+
     # Render the template
     rendered = render_template(template_content, replacements, bug)
 
@@ -374,10 +469,39 @@ def main():
     if err:
         emit_failure(err)
 
+    # Generate checkpoint file
+    project_root = resolve_project_root(script_dir)
+    checkpoint_path = os.path.join(project_root, checkpoint_rel)
+    checkpoint_dir = os.path.dirname(checkpoint_path)
+    os.makedirs(checkpoint_dir, exist_ok=True)
+
+    checkpoint = generate_bugfix_checkpoint(args.bug_id, args.session_id)
+
+    is_resume = args.resume_phase != "null"
+    if is_resume and os.path.exists(checkpoint_path):
+        try:
+            with open(checkpoint_path, "r", encoding="utf-8") as f:
+                existing = json.load(f)
+            checkpoint = merge_bugfix_checkpoint_state(
+                existing, checkpoint, project_root,
+            )
+            LOGGER.info("Merged existing bugfix checkpoint from %s",
+                        checkpoint_path)
+        except (json.JSONDecodeError, KeyError) as exc:
+            LOGGER.warning(
+                "Existing bugfix checkpoint corrupted (%s) — generating fresh",
+                exc,
+            )
+
+    with open(checkpoint_path, "w", encoding="utf-8") as f:
+        json.dump(checkpoint, f, indent=2, ensure_ascii=False)
+    LOGGER.info("Wrote bugfix checkpoint to %s", checkpoint_path)
+
     # Success
     output = {
         "success": True,
         "output_path": os.path.abspath(args.output),
+        "checkpoint_path": checkpoint_path,
     }
     print(json.dumps(output, indent=2, ensure_ascii=False))
     sys.exit(0)

package/bundled/dev-pipeline/templates/agent-prompts/dev-implement.md

@@ -3,7 +3,8 @@
 ⚠️ DO NOT re-read source files already listed in Section 4 File Manifest unless you need implementation detail beyond the interface summary.
 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` for full context.
 2. Run `/prizmkit-implement` to execute the tasks in plan.md. Run tests with: `{{TEST_CMD}}`. Known baseline failures (pre-existing, not your fault): `{{BASELINE_FAILURES}}`.
-3. After implement completes, verify the '## Implementation Log' section was written to context-snapshot.md.
+3. If plan.md has more than 5 tasks: run `/compact` after completing every 3 tasks to manage context budget. If `/compact` is unavailable, continue without it.
+4. After implement completes, verify the '## Implementation Log' section was written to context-snapshot.md.
 
 ## Acceptance Criteria Verification
 

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

@@ -152,6 +152,8 @@ $TEST_CMD 2>&1 | tee /tmp/test-baseline.txt | tail -20
 - Runs tests using `TEST_CMD` after each task
 - Writes '## Implementation Log' to `context-snapshot.md`
 
+**3b-compact.** Context management — if plan.md has more than 5 tasks, run `/compact` after completing every 3 tasks during implementation. This prevents context window exhaustion in long sessions. If `/compact` is not available (non-Claude CLI), skip this step.
+
 **3c.** After implement completes, verify:
 1. All tasks in plan.md are `[x]`
 2. Run the full test suite to ensure nothing is broken
@@ -285,6 +287,8 @@ git status --short
 ```
 Working tree MUST be clean after this step. If any feature-related files remain, stage them into the SAME commit via `git add <file> && git commit --amend --no-edit`, do NOT create a separate commit.
 
+**Exception**: `session-summary.md` in the artifact directory is a local cross-session artifact generated by `/prizmkit-committer` — it is NOT committed to git. Ignore it in the clean-tree check.
+
 ## Critical Paths
 
 | Resource | Path |

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

@@ -215,8 +215,9 @@ Prompt:
 > ⚠️ DO NOT re-read source files already listed in Section 4 File Manifest unless you need implementation detail beyond the interface summary.
 > 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` for full context.
 > 2. Run `/prizmkit-implement` to execute the tasks in plan.md. Run tests with: `{{TEST_CMD}}`. Known baseline failures (pre-existing, not your fault): `{{BASELINE_FAILURES}}`.
-> 3. After implement completes, verify the '## Implementation Log' section was written to context-snapshot.md.
-> 4. Do NOT execute any git commands (no git add/commit/reset/push).
+> 3. If plan.md has more than 5 tasks: run `/compact` after completing every 3 tasks to manage context budget. If `/compact` is unavailable, continue without it.
+> 4. After implement completes, verify the '## Implementation Log' section was written to context-snapshot.md.
+> 5. Do NOT execute any git commands (no git add/commit/reset/push).
 > Do NOT exit until all tasks are [x] and the '## Implementation Log' section is written in context-snapshot.md."
 
 Wait for Dev to return. All tasks must be `[x]`, tests pass.
@@ -383,6 +384,8 @@ git status --short
 ```
 Working tree MUST be clean after this step. If any feature-related files remain, stage them into the SAME commit via `git add <file> && git commit --amend --no-edit`, do NOT create a separate commit.
 
+**Exception**: `session-summary.md` in the artifact directory is a local cross-session artifact generated by `/prizmkit-committer` — it is NOT committed to git. Ignore it in the clean-tree check.
+
 ## Critical Paths
 
 | Resource | Path |

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

@@ -280,8 +280,9 @@ Prompt:
 > ⚠️ DO NOT re-read source files already listed in Section 4 File Manifest unless you need implementation detail beyond the interface summary.
 > 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` for full context.
 > 2. Run `/prizmkit-implement` to execute the tasks in plan.md. Run tests with: `{{TEST_CMD}}`. Known baseline failures (pre-existing, not your fault): `{{BASELINE_FAILURES}}`.
-> 3. After implement completes, verify the '## Implementation Log' section was written to context-snapshot.md.
-> 4. Do NOT execute any git commands (no git add/commit/reset/push).
+> 3. If plan.md has more than 5 tasks: run `/compact` after completing every 3 tasks to manage context budget. If `/compact` is unavailable, continue without it.
+> 4. After implement completes, verify the '## Implementation Log' section was written to context-snapshot.md.
+> 5. Do NOT execute any git commands (no git add/commit/reset/push).
 > Do NOT exit until all tasks are [x] and the '## Implementation Log' section is written in context-snapshot.md."
 
 **Gate Check — Implementation Log**:
@@ -476,6 +477,8 @@ git status --short
 ```
 Working tree MUST be clean after this step. If any feature-related files remain, stage them into the SAME commit via `git add <file> && git commit --amend --no-edit`, do NOT create a separate commit.
 
+**Exception**: `session-summary.md` in the artifact directory is a local cross-session artifact generated by `/prizmkit-committer` — it is NOT committed to git. Ignore it in the clean-tree check.
+
 ## Critical Paths
 
 | Resource | Path |

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

@@ -67,6 +67,19 @@ You are the **bug fix session orchestrator**. Fix Bug {{BUG_ID}}: "{{BUG_TITLE}}
 
 **IMPORTANT**: Only 2 artifact files per bug, NEVER more. This is a fixed convention.
 
+## Workflow Checkpoint System
+
+A checkpoint file tracks your progress through this workflow:
+
+**Path**: `{{CHECKPOINT_PATH}}`
+
+**Rules**:
+1. **Before each step**: Read `workflow-checkpoint.json`, verify the previous step has `status: "completed"` or `status: "skipped"`. If not, complete it first.
+2. **Starting a step**: Update the current step to `status: "in_progress"`.
+3. **After each step completes**: Update the step to `status: "completed"`. Verify JSON is valid after writing.
+4. **On failure**: Set the step to `status: "failed"` and halt.
+5. **On resume**: Steps already `"completed"` are skipped. Start from the first `"pending"` or `"in_progress"` step.
+
 ## Execution Instructions
 
 **YOU are the orchestrator. Execute each phase by spawning the appropriate team agent with run_in_background=false.**
@@ -109,6 +122,7 @@ Reference `{{TEAM_CONFIG_PATH}}` for agent definitions:
   "
 - **Wait for Dev to return**
 - **CP-BF-1**: `.prizmkit/bugfix/{{BUG_ID}}/fix-plan.md` exists
+- **Checkpoint update**: set step `bug-diagnosis` to `"completed"` in `{{CHECKPOINT_PATH}}`
 
 **DECISION GATE — Fast Path Check**:
 - If severity is LOW or MEDIUM, AND root cause is obvious (high confidence), AND fix is < 10 lines:
@@ -141,6 +155,7 @@ Reference `{{TEAM_CONFIG_PATH}}` for agent definitions:
   - Write session-status.json with status="partial", errors=["reproduction_failed"]
   - Set bug status to `needs_info` and STOP
 - **CP-BF-2**: Reproduction test exists and FAILS
+- **Checkpoint update**: set step `bug-reproduce` to `"completed"` in `{{CHECKPOINT_PATH}}`
 
 ---
 
@@ -158,11 +173,13 @@ Reference `{{TEAM_CONFIG_PATH}}` for agent definitions:
      - Do NOT refactor — fix the bug only
   4. Run the reproduction test → MUST PASS
   5. Run the module's test suite → MUST PASS (no regression)
-  6. If fix fails after 3 rounds, report detailed analysis
+  6. If the fix involves multiple files or steps: run `/compact` after completing the core fix and before running the full test suite, to free context budget. If `/compact` is unavailable, continue without it.
+  7. If fix fails after 3 rounds, report detailed analysis
   "
 - **Wait for Dev to return**
 - If fix fails after 3 rounds: escalate to user, write status="failed"
 - **CP-BF-3**: Reproduction test passes, module tests pass
+- **Checkpoint update**: set step `bug-fix` to `"completed"` in `{{CHECKPOINT_PATH}}`
 
 ---
 
@@ -185,6 +202,7 @@ Reference `{{TEAM_CONFIG_PATH}}` for agent definitions:
 - **Wait for Reviewer to return**
 - If NEEDS_FIXES: return to Phase 3 for refinement following Fix Instructions (max 2 review rounds)
 - **CP-BF-4**: Code review passes, all tests green
+- **Checkpoint update**: set step `prizmkit-code-review` to `"completed"` in `{{CHECKPOINT_PATH}}`
 
 {{IF_VERIFICATION_MANUAL_OR_HYBRID}}
 **MANUAL VERIFICATION GATE**:
@@ -222,6 +240,7 @@ Reference `{{TEAM_CONFIG_PATH}}` for agent definitions:
   - Acceptance Criteria Verification (checklist with pass/fail for each criterion)
 
 - **CP-BF-5**: Commit recorded, fix-report.md written, TRAPS updated (if applicable)
+- **Checkpoint update**: set steps `prizmkit-committer` and `bug-report` to `"completed"` in `{{CHECKPOINT_PATH}}`
 
 ### Step 3: Report Session Status