prizmkit 1.1.47 → 1.1.49

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.1.47",
-  "bundledAt": "2026-05-21T00:55:32.225Z",
-  "bundledFrom": "59d8ec1"
+  "frameworkVersion": "1.1.49",
+  "bundledAt": "2026-05-21T14:22:00.608Z",
+  "bundledFrom": "a8dea99"
 }

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

@@ -0,0 +1,173 @@
+#!/usr/bin/env python3
+"""Safely update a workflow-checkpoint.json step status.
+
+Instead of having the AI hand-write JSON, this script reads the checkpoint,
+validates the update, and writes it back atomically.
+
+Usage:
+  python3 update-checkpoint.py --checkpoint-path <path> --step <skill-or-id> --status <status>
+  python3 update-checkpoint.py --checkpoint-path <path> --step prizmkit-implement --status completed
+  python3 update-checkpoint.py --checkpoint-path <path> --step S04 --status in_progress
+  python3 update-checkpoint.py --checkpoint-path <path> --step prizmkit-code-review --status failed --note "max rounds exhausted"
+
+Exit codes:
+  0 = success
+  1 = validation error (step not found, invalid status, etc.)
+  2 = file error (not found, corrupted JSON)
+
+Output (stdout): JSON with {ok: true, step_id, skill, old_status, new_status} or {ok: false, error}
+"""
+
+import argparse
+import json
+import os
+import sys
+import tempfile
+
+VALID_STATUSES = {"pending", "in_progress", "completed", "skipped", "failed"}
+
+
+def _load_checkpoint(path):
+    """Load checkpoint JSON. Returns (data, error_string)."""
+    if not os.path.isfile(path):
+        return None, "File not found: {}".format(path)
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+    except json.JSONDecodeError as e:
+        return None, "Corrupted JSON: {}".format(e)
+    except IOError as e:
+        return None, "Cannot read file: {}".format(e)
+
+    if "steps" not in data or not isinstance(data["steps"], list):
+        return None, "Invalid checkpoint: missing 'steps' array"
+    return data, None
+
+
+def _write_checkpoint(path, data):
+    """Write checkpoint JSON atomically using a temp file + rename."""
+    parent = os.path.dirname(os.path.abspath(path))
+    if parent and not os.path.isdir(parent):
+        os.makedirs(parent, exist_ok=True)
+
+    tmp_path = None
+    try:
+        fd, tmp_path = tempfile.mkstemp(
+            dir=parent, suffix=".tmp", prefix=".checkpoint-"
+        )
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, ensure_ascii=False)
+            f.write("\n")
+        os.replace(tmp_path, os.path.abspath(path))
+    except (IOError, OSError) as e:
+        # Clean up temp file on error
+        if tmp_path is not None and os.path.exists(tmp_path):
+            os.unlink(tmp_path)
+        return "Cannot write file: {}".format(e)
+    return None
+
+
+def _find_step(steps, identifier):
+    """Find a step by skill name or step ID.
+
+    Returns (index, step_dict) or (None, None).
+    """
+    for i, step in enumerate(steps):
+        if step.get("skill") == identifier or step.get("id") == identifier:
+            return i, step
+    return None, None
+
+
+def update_checkpoint(checkpoint_path, step_identifier, new_status, note=None):
+    """Update a single step's status in the checkpoint file.
+
+    Returns a result dict: {ok, step_id, skill, old_status, new_status} or {ok, error}.
+    """
+    if new_status not in VALID_STATUSES:
+        return {
+            "ok": False,
+            "error": "Invalid status '{}'. Must be one of: {}".format(
+                new_status, ", ".join(sorted(VALID_STATUSES))
+            ),
+        }
+
+    data, err = _load_checkpoint(checkpoint_path)
+    if err:
+        return {"ok": False, "error": err}
+
+    idx, step = _find_step(data["steps"], step_identifier)
+    if step is None:
+        available = [
+            "{} ({})".format(s.get("id", "?"), s.get("skill", "?"))
+            for s in data["steps"]
+        ]
+        return {
+            "ok": False,
+            "error": "Step '{}' not found. Available: {}".format(
+                step_identifier, ", ".join(available)
+            ),
+        }
+
+    old_status = step.get("status", "unknown")
+    step["status"] = new_status
+
+    if note:
+        step["note"] = note
+
+    err = _write_checkpoint(checkpoint_path, data)
+    if err:
+        return {"ok": False, "error": err}
+
+    return {
+        "ok": True,
+        "step_id": step.get("id"),
+        "skill": step.get("skill"),
+        "old_status": old_status,
+        "new_status": new_status,
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Safely update a workflow-checkpoint.json step status.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "Examples:\n"
+            "  %(prog)s --checkpoint-path .prizmkit/specs/my-feature/workflow-checkpoint.json "
+            "--step prizmkit-implement --status completed\n"
+            "  %(prog)s --checkpoint-path .prizmkit/bugfix/B-001/workflow-checkpoint.json "
+            "--step S04 --status in_progress\n"
+            "  %(prog)s --checkpoint-path .prizmkit/refactor/R-001/workflow-checkpoint.json "
+            "--step prizmkit-code-review --status failed --note 'max rounds exhausted'"
+        ),
+    )
+    parser.add_argument(
+        "--checkpoint-path", required=True, help="Path to workflow-checkpoint.json"
+    )
+    parser.add_argument(
+        "--step",
+        required=True,
+        help="Step identifier (skill name like 'prizmkit-implement' or step ID like 'S04')",
+    )
+    parser.add_argument(
+        "--status",
+        required=True,
+        choices=sorted(VALID_STATUSES),
+        help="New status for the step",
+    )
+    parser.add_argument(
+        "--note",
+        default=None,
+        help="Optional note to attach to the step (e.g., failure reason)",
+    )
+
+    args = parser.parse_args()
+    result = update_checkpoint(
+        args.checkpoint_path, args.step, args.status, args.note
+    )
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if result.get("ok") else (2 if "File not found" in result.get("error", "") or "Corrupted" in result.get("error", "") else 1)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/bundled/dev-pipeline/templates/sections/checkpoint-system.md

@@ -8,23 +8,53 @@ A checkpoint file tracks your progress through this workflow:
 
 1. **Before each skill**: Read `workflow-checkpoint.json`, verify the previous step has `status: "completed"` or `status: "skipped"`. If it is still `"pending"` or `"in_progress"`, you MUST complete it first before moving on.
 
-2. **Starting a skill**: Update the current step to `status: "in_progress"`.
+2. **Starting a skill**: Use the update script to set the current step to `status: "in_progress"`.
 
-3. **After each skill completes**: Update the current step to `status: "completed"`. Then immediately re-read the file to verify the JSON is valid. If the read fails, re-write the file with correct JSON.
+3. **After each skill completes**: Use the update script to set the current step to `status: "completed"`.
 
-4. **On failure**: Set the step to `status: "failed"` and continue to the next step if possible, or halt and write failure-log.md.
+4. **On failure**: Use the update script to set the step to `status: "failed"` and continue to the next step if possible, or halt and write failure-log.md.
 
 5. **On session exit**: The checkpoint file reflects your actual progress. Do NOT manually set future steps to "completed".
 
 ### Checkpoint Update Pattern
 
-After completing each skill:
+**IMPORTANT: NEVER hand-write or edit `workflow-checkpoint.json` directly. Always use the update script.**
 
-1. Read `{{CHECKPOINT_PATH}}`
-2. Update the current step `"status": "completed"`
-3. Update the next step `"status": "in_progress"`
-4. Write the updated JSON back to `{{CHECKPOINT_PATH}}`
-5. Verify: `python3 -c "import json; json.load(open('{{CHECKPOINT_PATH}}'))"` — if this fails, re-write
+After completing each skill, run:
+
+```bash
+python3 $PIPELINE_DIR/scripts/update-checkpoint.py \
+  --checkpoint-path {{CHECKPOINT_PATH}} \
+  --step <SKILL_NAME> \
+  --status completed
+```
+
+For example, after completing `prizmkit-implement`:
+```bash
+python3 $PIPELINE_DIR/scripts/update-checkpoint.py \
+  --checkpoint-path {{CHECKPOINT_PATH}} \
+  --step prizmkit-implement \
+  --status completed
+```
+
+Before starting the next skill:
+```bash
+python3 $PIPELINE_DIR/scripts/update-checkpoint.py \
+  --checkpoint-path {{CHECKPOINT_PATH}} \
+  --step <NEXT_SKILL_NAME> \
+  --status in_progress
+```
+
+On failure:
+```bash
+python3 $PIPELINE_DIR/scripts/update-checkpoint.py \
+  --checkpoint-path {{CHECKPOINT_PATH}} \
+  --step <SKILL_NAME> \
+  --status failed \
+  --note "brief failure reason"
+```
+
+The script outputs JSON: `{"ok": true, ...}` on success, `{"ok": false, "error": "..."}` on failure.
 
 ### Resume Behavior
 

package/bundled/dev-pipeline/templates/sections/phase-browser-verification-auto.md

@@ -150,4 +150,10 @@ Append results to `context-snapshot.md`:
 If verification fails, log the failure details but continue to commit. Failures do NOT block the commit, but you MUST attempt verification and MUST clean up the dev server.
 
 
-**Checkpoint update**: Update `workflow-checkpoint.json` — set step `browser-verification` to `"completed"`.
+**Checkpoint update**: Run the update script to set step `browser-verification` to `"completed"`:
+```bash
+python3 $PIPELINE_DIR/scripts/update-checkpoint.py \
+  --checkpoint-path {{CHECKPOINT_PATH}} \
+  --step browser-verification \
+  --status completed
+```

package/bundled/dev-pipeline/templates/sections/phase-browser-verification-opencli.md

@@ -121,4 +121,10 @@ Append results to `context-snapshot.md`:
 If verification fails, log the failure details but continue to commit. Failures do NOT block the commit, but you MUST attempt verification and MUST clean up the dev server.
 
 
-**Checkpoint update**: Update `workflow-checkpoint.json` — set step `browser-verification` to `"completed"`.
+**Checkpoint update**: Run the update script to set step `browser-verification` to `"completed"`:
+```bash
+python3 $PIPELINE_DIR/scripts/update-checkpoint.py \
+  --checkpoint-path {{CHECKPOINT_PATH}} \
+  --step browser-verification \
+  --status completed
+```

package/bundled/dev-pipeline/templates/sections/phase-browser-verification.md

@@ -143,4 +143,10 @@ Browser cleanup: confirmed
 If verification fails, log the failure details but continue to commit. Failures do NOT block the commit, but you MUST attempt verification and MUST clean up the dev server.
 
 
-**Checkpoint update**: Update `workflow-checkpoint.json` — set step `browser-verification` to `"completed"`.
+**Checkpoint update**: Run the update script to set step `browser-verification` to `"completed"`:
+```bash
+python3 $PIPELINE_DIR/scripts/update-checkpoint.py \
+  --checkpoint-path {{CHECKPOINT_PATH}} \
+  --step browser-verification \
+  --status completed
+```

package/bundled/dev-pipeline/templates/sections/phase-commit-full.md

@@ -55,4 +55,17 @@ Rules for writing completion notes:
 - If this feature has no downstream dependents, still write the summary (it serves as documentation)
 
 
-**Checkpoint update**: After `/prizmkit-retrospective` completes, update `workflow-checkpoint.json` — set step `prizmkit-retrospective` to `"completed"`. After `/prizmkit-committer` completes, set step `prizmkit-committer` to `"completed"`.
+**Checkpoint update**: After `/prizmkit-retrospective` completes, run the update script to set step `prizmkit-retrospective` to `"completed"`:
+```bash
+python3 $PIPELINE_DIR/scripts/update-checkpoint.py \
+  --checkpoint-path {{CHECKPOINT_PATH}} \
+  --step prizmkit-retrospective \
+  --status completed
+```
+After `/prizmkit-committer` completes, set step `prizmkit-committer` to `"completed"`:
+```bash
+python3 $PIPELINE_DIR/scripts/update-checkpoint.py \
+  --checkpoint-path {{CHECKPOINT_PATH}} \
+  --step prizmkit-committer \
+  --status completed
+```

package/bundled/dev-pipeline/templates/sections/phase-commit.md

@@ -48,4 +48,17 @@ Rules for writing completion notes:
 - If this feature has no downstream dependents, still write the summary (it serves as documentation)
 
 
-**Checkpoint update**: After `/prizmkit-retrospective` completes, update `workflow-checkpoint.json` — set step `prizmkit-retrospective` to `"completed"`. After `/prizmkit-committer` completes, set step `prizmkit-committer` to `"completed"`.
+**Checkpoint update**: After `/prizmkit-retrospective` completes, run the update script to set step `prizmkit-retrospective` to `"completed"`:
+```bash
+python3 $PIPELINE_DIR/scripts/update-checkpoint.py \
+  --checkpoint-path {{CHECKPOINT_PATH}} \
+  --step prizmkit-retrospective \
+  --status completed
+```
+After `/prizmkit-committer` completes, set step `prizmkit-committer` to `"completed"`:
+```bash
+python3 $PIPELINE_DIR/scripts/update-checkpoint.py \
+  --checkpoint-path {{CHECKPOINT_PATH}} \
+  --step prizmkit-committer \
+  --status completed
+```

package/bundled/dev-pipeline/templates/sections/phase-context-snapshot-agent-suffix.md

@@ -14,4 +14,10 @@
      - <trap entries extracted from L1/L2 docs>
 
 
-**Checkpoint update**: Update `workflow-checkpoint.json` — set step `context-snapshot` to `"completed"`.
+**Checkpoint update**: Run the update script to set step `context-snapshot` to `"completed"`:
+```bash
+python3 $PIPELINE_DIR/scripts/update-checkpoint.py \
+  --checkpoint-path {{CHECKPOINT_PATH}} \
+  --step context-snapshot \
+  --status completed
+```

package/bundled/dev-pipeline/templates/sections/phase-context-snapshot-lite-suffix.md

@@ -3,4 +3,10 @@
    - **Section 5 — Existing Tests**: full content of related test files as code block
 
 
-**Checkpoint update**: Update `workflow-checkpoint.json` — set step `context-snapshot` to `"completed"`.
+**Checkpoint update**: Run the update script to set step `context-snapshot` to `"completed"`:
+```bash
+python3 $PIPELINE_DIR/scripts/update-checkpoint.py \
+  --checkpoint-path {{CHECKPOINT_PATH}} \
+  --step context-snapshot \
+  --status completed
+```

package/bundled/dev-pipeline/templates/sections/phase-critic-plan-full.md

@@ -44,4 +44,10 @@ After all critics return, read all 3 reports:
 **CP-2.5**: Plan challenges reviewed and resolved.
 
 
-**Checkpoint update**: Update `workflow-checkpoint.json` — set step `critic-plan-review` to `"completed"`.
+**Checkpoint update**: Run the update script to set step `critic-plan-review` to `"completed"`:
+```bash
+python3 $PIPELINE_DIR/scripts/update-checkpoint.py \
+  --checkpoint-path {{CHECKPOINT_PATH}} \
+  --step critic-plan-review \
+  --status completed
+```

package/bundled/dev-pipeline/templates/sections/phase-critic-plan.md

@@ -23,4 +23,10 @@ Wait for Critic to return.
 **CP-2.5**: Plan challenges reviewed and resolved.
 
 
-**Checkpoint update**: Update `workflow-checkpoint.json` — set step `critic-plan-review` to `"completed"`.
+**Checkpoint update**: Run the update script to set step `critic-plan-review` to `"completed"`:
+```bash
+python3 $PIPELINE_DIR/scripts/update-checkpoint.py \
+  --checkpoint-path {{CHECKPOINT_PATH}} \
+  --step critic-plan-review \
+  --status completed
+```

package/bundled/dev-pipeline/templates/sections/phase-implement-agent.md

@@ -28,4 +28,10 @@ grep -q "## Implementation Log" .prizmkit/specs/{{FEATURE_SLUG}}/context-snapsho
 If GATE:MISSING — send message to Dev (re-spawn if needed): "Write the '## Implementation Log' section to context-snapshot.md before I can proceed to review. Include: files changed/created, key decisions, deviations from plan, notable discoveries."
 
 
-**Checkpoint update**: Update `workflow-checkpoint.json` — set step `prizmkit-implement` to `"completed"`.
+**Checkpoint update**: Run the update script to set step `prizmkit-implement` to `"completed"`:
+```bash
+python3 $PIPELINE_DIR/scripts/update-checkpoint.py \
+  --checkpoint-path {{CHECKPOINT_PATH}} \
+  --step prizmkit-implement \
+  --status completed
+```

package/bundled/dev-pipeline/templates/sections/phase-implement-full.md

@@ -41,4 +41,10 @@ Wait for Dev to return. **If Dev times out before all tasks are `[x]`**:
 All tasks `[x]`, tests pass.
 
 
-**Checkpoint update**: Update `workflow-checkpoint.json` — set step `prizmkit-implement` to `"completed"`.
+**Checkpoint update**: Run the update script to set step `prizmkit-implement` to `"completed"`:
+```bash
+python3 $PIPELINE_DIR/scripts/update-checkpoint.py \
+  --checkpoint-path {{CHECKPOINT_PATH}} \
+  --step prizmkit-implement \
+  --status completed
+```

package/bundled/dev-pipeline/templates/sections/phase-implement-lite.md

@@ -39,4 +39,10 @@ You know this project's tech stack. Identify ALL test commands that apply (e.g.,
 **CP-2**: All acceptance criteria met, all tests pass.
 
 
-**Checkpoint update**: Update `workflow-checkpoint.json` — set step `prizmkit-implement` to `"completed"`.
+**Checkpoint update**: Run the update script to set step `prizmkit-implement` to `"completed"`:
+```bash
+python3 $PIPELINE_DIR/scripts/update-checkpoint.py \
+  --checkpoint-path {{CHECKPOINT_PATH}} \
+  --step prizmkit-implement \
+  --status completed
+```

package/bundled/dev-pipeline/templates/sections/phase-plan-agent.md

@@ -18,4 +18,10 @@ Before proceeding past CP-1, verify:
 **CP-1**: plan.md exists with Tasks section.
 
 
-**Checkpoint update**: Update `workflow-checkpoint.json` — set step `prizmkit-plan` to `"completed"`.
+**Checkpoint update**: Run the update script to set step `prizmkit-plan` to `"completed"`:
+```bash
+python3 $PIPELINE_DIR/scripts/update-checkpoint.py \
+  --checkpoint-path {{CHECKPOINT_PATH}} \
+  --step prizmkit-plan \
+  --status completed
+```

package/bundled/dev-pipeline/templates/sections/phase-plan-lite.md

@@ -18,4 +18,10 @@ Before proceeding past CP-1:
 **CP-1**: plan.md exists with Tasks section.
 
 
-**Checkpoint update**: Update `workflow-checkpoint.json` — set step `prizmkit-plan` to `"completed"`.
+**Checkpoint update**: Run the update script to set step `prizmkit-plan` to `"completed"`:
+```bash
+python3 $PIPELINE_DIR/scripts/update-checkpoint.py \
+  --checkpoint-path {{CHECKPOINT_PATH}} \
+  --step prizmkit-plan \
+  --status completed
+```

package/bundled/dev-pipeline/templates/sections/phase-review-agent.md

@@ -18,4 +18,10 @@ Read `review-report.md` and check the Verdict:
 **CP-3**: Review complete, report written.
 
 
-**Checkpoint update**: Update `workflow-checkpoint.json` — set step `prizmkit-code-review` to `"completed"`.
+**Checkpoint update**: Run the update script to set step `prizmkit-code-review` to `"completed"`:
+```bash
+python3 $PIPELINE_DIR/scripts/update-checkpoint.py \
+  --checkpoint-path {{CHECKPOINT_PATH}} \
+  --step prizmkit-code-review \
+  --status completed
+```

package/bundled/dev-pipeline/templates/sections/phase-review-full.md

@@ -20,4 +20,10 @@ Run the full test suite: `({{TEST_CMD}}) 2>&1 | tee /tmp/review-test-out.txt | t
 **CP-3**: Review complete, tests pass, report written.
 
 
-**Checkpoint update**: Update `workflow-checkpoint.json` — set step `prizmkit-code-review` to `"completed"`.
+**Checkpoint update**: Run the update script to set step `prizmkit-code-review` to `"completed"`:
+```bash
+python3 $PIPELINE_DIR/scripts/update-checkpoint.py \
+  --checkpoint-path {{CHECKPOINT_PATH}} \
+  --step prizmkit-code-review \
+  --status completed
+```

package/bundled/dev-pipeline/templates/sections/phase-specify-plan-full.md

@@ -64,4 +64,10 @@ Before proceeding past CP-1, verify:
 **CP-1**: Both spec.md and plan.md exist.
 
 
-**Checkpoint update**: Update `workflow-checkpoint.json` — set step `context-snapshot-and-plan` to `"completed"`.
+**Checkpoint update**: Run the update script to set step `context-snapshot-and-plan` to `"completed"`:
+```bash
+python3 $PIPELINE_DIR/scripts/update-checkpoint.py \
+  --checkpoint-path {{CHECKPOINT_PATH}} \
+  --step context-snapshot-and-plan \
+  --status completed
+```

package/bundled/dev-pipeline/templates/sections/phase0-init.md

@@ -4,4 +4,10 @@
 - **CP-0**: Verify `.prizmkit/prizm-docs/root.prizm`, `.prizmkit/config.json` exist
 
 
-**Checkpoint update**: Update `workflow-checkpoint.json` — set step `prizmkit-init` to `"completed"`.
+**Checkpoint update**: Run the update script to set step `prizmkit-init` to `"completed"`:
+```bash
+python3 $PIPELINE_DIR/scripts/update-checkpoint.py \
+  --checkpoint-path {{CHECKPOINT_PATH}} \
+  --step prizmkit-init \
+  --status completed
+```

package/bundled/dev-pipeline/templates/sections/phase0-test-baseline.md

@@ -12,4 +12,10 @@ Save the list of **pre-existing failing tests** (if any) as `BASELINE_FAILURES`.
 > **Test Output Rule**: Always capture test output to a temp file (`tee /tmp/test-out.txt`). Then grep the file instead of re-running the suite.
 
 
-**Checkpoint update**: Update `workflow-checkpoint.json` — set step `test-baseline` to `"completed"`.
+**Checkpoint update**: Run the update script to set step `test-baseline` to `"completed"`:
+```bash
+python3 $PIPELINE_DIR/scripts/update-checkpoint.py \
+  --checkpoint-path {{CHECKPOINT_PATH}} \
+  --step test-baseline \
+  --status completed
+```

package/bundled/skills/_metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.1.47",
+  "version": "1.1.49",
   "skills": {
     "prizm-kit": {
       "description": "Full-lifecycle dev toolkit. Covers spec-driven development, Prizm context docs, code quality, debugging, deployment, and knowledge management.",

package/bundled/skills/bug-planner/SKILL.md

@@ -223,9 +223,13 @@ Only proceed to Phase 5 after user confirms.
 
 ### Phase 5: Generate & Validate
 
-1. **Generate `.prizmkit/plans/bug-fix-list.json`**: Conform to `.prizmkit/dev-pipeline/templates/bug-fix-list-schema.json`
-2. **Validate against schema**: Run `python3 ${SKILL_DIR}/scripts/validate-bug-list.py .prizmkit/plans/bug-fix-list.json --feature-list .prizmkit/plans/feature-list.json`. If the script is unavailable, use the checklist in `${SKILL_DIR}/references/schema-validation.md`.
-3. **Write file** to `.prizmkit/plans/` (or user-specified path)
+1. **Write draft JSON**: Write a draft `.prizmkit/plans/bug-fix-list.draft.json` with all collected bug data. Conform to `.prizmkit/dev-pipeline/templates/bug-fix-list-schema.json`.
+2. **Generate and validate**: Run the generate script to validate and produce the final file:
+   ```bash
+   python3 ${SKILL_DIR}/scripts/validate-bug-list.py generate --input .prizmkit/plans/bug-fix-list.draft.json --output .prizmkit/plans/bug-fix-list.json
+   ```
+   The script fills in defaults (`$schema`, `created_at`, `created_by`), validates all fields, and writes the final file only if validation passes.
+3. **If validation fails**: Fix the draft and retry (max 3 attempts). If the script is unavailable, use the checklist in `${SKILL_DIR}/references/schema-validation.md`.
 4. **Output**: File path, summary, and next steps
 
 **Gate → CP-BP-5**: `bug-fix-list.json` passes validation script with zero errors.
@@ -269,8 +273,12 @@ Batch-parse error logs to generate bug entries without interactive prompts:
    - error_source: populated from log content
    - verification_type: default to `automated`
    - acceptance_criteria: auto-generate "Error no longer occurs in [scenario]"
-4. Output draft `.prizmkit/plans/bug-fix-list.json` for user review
+4. Write draft to `.prizmkit/plans/bug-fix-list.draft.json` for user review
 5. Ask: "Review and confirm? You can edit individual entries."
+6. After user confirms, call the generate script:
+   ```bash
+   python3 ${SKILL_DIR}/scripts/validate-bug-list.py generate --input .prizmkit/plans/bug-fix-list.draft.json --output .prizmkit/plans/bug-fix-list.json
+   ```
 
 ## Operation: From Tests
 
@@ -280,7 +288,11 @@ Batch-parse failed test output:
 2. Parse each failed test case as a separate bug entry
 3. Auto-populate `failed_test_path`, `error_message`
 4. Set verification_type to `automated` (test already exists)
-5. Output draft `.prizmkit/plans/bug-fix-list.json`
+5. Write draft to `.prizmkit/plans/bug-fix-list.draft.json`
+6. After user confirms, call the generate script:
+   ```bash
+   python3 ${SKILL_DIR}/scripts/validate-bug-list.py generate --input .prizmkit/plans/bug-fix-list.draft.json --output .prizmkit/plans/bug-fix-list.json
+   ```
 
 ## Operation: Validate