prizmkit 1.1.48 → 1.1.49

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.1.48",
-  "bundledAt": "2026-05-21T01:37:14.355Z",
-  "bundledFrom": "a20d996"
+  "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.48",
+  "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
 

package/bundled/skills/bug-planner/scripts/validate-bug-list.py

@@ -1,20 +1,30 @@
 #!/usr/bin/env python3
 """
-Validate .prizmkit/plans/bug-fix-list.json against the PrizmKit bug-fix-list schema.
+Validate and generate .prizmkit/plans/bug-fix-list.json files
+for the dev-pipeline system.
+
+Commands:
+  validate    Validate an existing bug-fix-list.json
+  generate    Validate a draft JSON and generate final bug-fix-list.json with defaults
 
 Usage:
-    python3 validate-bug-list.py [.prizmkit/plans/bug-fix-list.json] [--feature-list .prizmkit/plans/feature-list.json]
+  python3 validate-bug-list.py validate .prizmkit/plans/bug-fix-list.json [--feature-list .prizmkit/plans/feature-list.json]
+  python3 validate-bug-list.py generate --input draft.json --output .prizmkit/plans/bug-fix-list.json
 
 Exit codes:
-    0 = valid
-    1 = validation errors found
-    2 = file not found or JSON parse error
+  0 = valid / generated
+  1 = validation errors found
+  2 = file not found or JSON parse error
+
+Python 3.6+ required. No external dependencies.
 """
 
+import argparse
 import json
 import sys
 import os
 import re
+from datetime import datetime, timezone
 
 VALID_SEVERITIES = {"critical", "high", "medium", "low"}
 VALID_SOURCE_TYPES = {"stack_trace", "user_report", "failed_test", "log_pattern", "monitoring_alert"}
@@ -24,129 +34,289 @@ BUG_ID_PATTERN = re.compile(r"^B-\d{3}$")
 SCHEMA_VERSION = "dev-pipeline-bug-fix-list-v1"
 
 
-def validate(bug_list_path, feature_list_path=None):
-    errors = []
-    warnings = []
+def _err(msg):
+    """Print an error message to stderr."""
+    print("ERROR: {}".format(msg), file=sys.stderr)
+
+
+def _warn(msg):
+    """Print a warning message to stderr."""
+    print("WARN: {}".format(msg), file=sys.stderr)
+
 
-    # Load bug-fix-list.json
+def _info(msg):
+    """Print an informational message to stderr."""
+    print("INFO: {}".format(msg), file=sys.stderr)
+
+
+def _load_json(path):
+    """Load and return parsed JSON from a file. Returns (data, error_string)."""
+    if not os.path.isfile(path):
+        return None, "File not found: {}".format(path)
     try:
-        with open(bug_list_path) as f:
+        with open(path, "r", encoding="utf-8") as f:
             data = json.load(f)
-    except FileNotFoundError:
-        print(f"ERROR: File not found: {bug_list_path}", file=sys.stderr)
-        return 2
+        return data, None
     except json.JSONDecodeError as e:
-        print(f"ERROR: Invalid JSON in {bug_list_path}: {e}", file=sys.stderr)
-        return 2
+        return None, "Invalid JSON in {}: {}".format(path, e)
+    except Exception as e:
+        return None, "Cannot read {}: {}".format(path, e)
 
-    # Load feature-list.json (optional, for cross-reference)
-    feature_ids = set()
-    if feature_list_path:
-        try:
-            with open(feature_list_path) as f:
-                fl_data = json.load(f)
-            feature_ids = {f.get("id") for f in fl_data.get("features", [])}
-        except (FileNotFoundError, json.JSONDecodeError):
-            warnings.append(f"Could not load feature-list.json at {feature_list_path}")
+
+def _write_json(path, data):
+    """Write data as pretty-printed JSON to path. Creates parent dirs if needed."""
+    parent = os.path.dirname(os.path.abspath(path))
+    if parent and not os.path.isdir(parent):
+        os.makedirs(parent, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2, ensure_ascii=False)
+        f.write("\n")
+
+
+def validate(data, feature_ids=None):
+    """Validate a parsed bug-fix-list data structure.
+
+    Returns a dict with keys: valid, errors, warnings, stats.
+    """
+    errors = []
+    warnings = []
 
     # Top-level required fields
     if "$schema" not in data:
         errors.append("Missing required field: $schema")
     elif data["$schema"] != SCHEMA_VERSION:
-        errors.append(f"Invalid $schema: expected '{SCHEMA_VERSION}', got '{data['$schema']}'")
+        errors.append("Invalid $schema: expected '{}', got '{}'".format(SCHEMA_VERSION, data["$schema"]))
 
     if not data.get("project_name"):
         errors.append("Missing or empty required field: project_name")
 
     bugs = data.get("bugs", [])
-    if not bugs:
+    if not bugs or not isinstance(bugs, list):
         errors.append("Missing or empty required field: bugs")
+        return {
+            "valid": False,
+            "errors": errors,
+            "warnings": warnings,
+            "stats": {"total_bugs": 0, "severity_distribution": {}},
+        }
 
     # Per-bug validation
     seen_ids = set()
-    seen_priorities = set()
+    severity_counts = {}
 
     for i, bug in enumerate(bugs):
-        prefix = f"bugs[{i}]"
+        prefix = "bugs[{}]".format(i)
 
         # Required fields
         bug_id = bug.get("id", "")
         if not bug_id:
-            errors.append(f"{prefix}: missing required field 'id'")
+            errors.append("{}: missing required field 'id'".format(prefix))
         elif not BUG_ID_PATTERN.match(bug_id):
-            errors.append(f"{prefix}: id '{bug_id}' does not match pattern B-NNN")
+            errors.append("{}: id '{}' does not match pattern B-NNN".format(prefix, bug_id))
 
         if bug_id in seen_ids:
-            errors.append(f"{prefix}: duplicate bug id '{bug_id}'")
+            errors.append("{}: duplicate bug id '{}'".format(prefix, bug_id))
         seen_ids.add(bug_id)
 
         if not bug.get("title"):
-            errors.append(f"{prefix} ({bug_id}): missing required field 'title'")
+            errors.append("{} ({}): missing required field 'title'".format(prefix, bug_id))
 
         if not bug.get("description"):
-            errors.append(f"{prefix} ({bug_id}): missing required field 'description'")
+            errors.append("{} ({}): missing required field 'description'".format(prefix, bug_id))
 
         severity = bug.get("severity", "")
         if severity not in VALID_SEVERITIES:
-            errors.append(f"{prefix} ({bug_id}): invalid severity '{severity}' — must be one of {VALID_SEVERITIES}")
+            errors.append("{} ({}): invalid severity '{}' — must be one of {}".format(
+                prefix, bug_id, severity, sorted(VALID_SEVERITIES)))
+        else:
+            severity_counts[severity] = severity_counts.get(severity, 0) + 1
 
         # error_source
         error_source = bug.get("error_source", {})
         source_type = error_source.get("type", "") if isinstance(error_source, dict) else ""
         if source_type not in VALID_SOURCE_TYPES:
-            errors.append(f"{prefix} ({bug_id}): invalid error_source.type '{source_type}' — must be one of {VALID_SOURCE_TYPES}")
+            errors.append("{} ({}): invalid error_source.type '{}' — must be one of {}".format(
+                prefix, bug_id, source_type, sorted(VALID_SOURCE_TYPES)))
 
         # verification_type
         vtype = bug.get("verification_type", "")
         if vtype not in VALID_VERIFICATION_TYPES:
-            errors.append(f"{prefix} ({bug_id}): invalid verification_type '{vtype}' — must be one of {VALID_VERIFICATION_TYPES}")
+            errors.append("{} ({}): invalid verification_type '{}' — must be one of {}".format(
+                prefix, bug_id, vtype, sorted(VALID_VERIFICATION_TYPES)))
 
         # acceptance_criteria
         ac = bug.get("acceptance_criteria", [])
         if not ac or not isinstance(ac, list):
-            errors.append(f"{prefix} ({bug_id}): missing or empty acceptance_criteria array")
+            errors.append("{} ({}): missing or empty acceptance_criteria array".format(prefix, bug_id))
 
         # status
         status = bug.get("status", "")
         if status not in VALID_STATUSES:
-            errors.append(f"{prefix} ({bug_id}): invalid status '{status}' — must be one of {VALID_STATUSES}")
+            errors.append("{} ({}): invalid status '{}' — must be one of {}".format(
+                prefix, bug_id, status, sorted(VALID_STATUSES)))
 
         # Priority validation (optional field)
         priority = bug.get("priority")
         if priority is not None:
             if priority not in ("high", "medium", "low"):
-                errors.append(f"{prefix} ({bug_id}): invalid priority '{priority}' — must be one of 'high', 'medium', 'low'")
+                errors.append("{} ({}): invalid priority '{}' — must be one of 'high', 'medium', 'low'".format(
+                    prefix, bug_id, priority))
+
+    return {
+        "valid": len(errors) == 0,
+        "errors": errors,
+        "warnings": warnings,
+        "stats": {
+            "total_bugs": len(bugs),
+            "severity_distribution": severity_counts,
+        },
+    }
+
+
+def cmd_validate(args):
+    """Handle the 'validate' command."""
+    bug_list = args.input
+    feature_list = args.feature_list
+
+    data, load_err = _load_json(bug_list)
+    if load_err:
+        _err(load_err)
+        return 2
+
+    # Load feature-list.json (optional, for cross-reference)
+    if feature_list:
+        fl_data, fl_err = _load_json(feature_list)
+        if not fl_data:
+            _warn("Could not load feature-list.json at {}: {}".format(feature_list, fl_err))
+
+    result = validate(data)
 
+    # Print results to stdout
+    print(json.dumps(result, indent=2, ensure_ascii=False))
 
-    # Output results
-    if errors:
-        print(f"VALIDATION FAILED — {len(errors)} error(s), {len(warnings)} warning(s)\n")
-        for e in errors:
-            print(f"  ERROR: {e}")
-        for w in warnings:
-            print(f"  WARN:  {w}")
+    if result["valid"]:
+        bug_count = result["stats"]["total_bugs"]
+        sev = result["stats"]["severity_distribution"]
+        sev_str = ", ".join("{}={}".format(k, v) for k, v in sorted(sev.items()))
+        _info("VALIDATION PASSED — {} bugs ({})".format(bug_count, sev_str))
+        return 0
+    else:
+        _err("VALIDATION FAILED — {} error(s), {} warning(s)".format(
+            len(result["errors"]), len(result["warnings"])))
+        for e in result["errors"]:
+            _err("  ERROR: {}".format(e))
+        for w in result["warnings"]:
+            _warn("  WARN: {}".format(w))
         return 1
+
+
+def cmd_generate(args):
+    """Handle the 'generate' command.
+
+    Loads a draft JSON (produced by AI), fills in defaults, validates,
+    and writes the final bug-fix-list.json.
+    """
+    # Load draft (supports stdin via '-')
+    if args.input == "-":
+        try:
+            data = json.load(sys.stdin)
+        except json.JSONDecodeError as exc:
+            _err("Invalid JSON from stdin: {}".format(exc))
+            return 2
     else:
-        bug_count = len(bugs)
-        severity_counts = {}
-        for b in bugs:
-            s = b.get("severity", "unknown")
-            severity_counts[s] = severity_counts.get(s, 0) + 1
-        sev_str = ", ".join(f"{k}={v}" for k, v in sorted(severity_counts.items()))
-        print(f"VALIDATION PASSED — {bug_count} bugs ({sev_str})")
-        if warnings:
-            for w in warnings:
-                print(f"  WARN:  {w}")
+        data, load_err = _load_json(args.input)
+        if load_err:
+            _err(load_err)
+            return 2
+
+    # Fill in defaults
+    now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    data.setdefault("$schema", SCHEMA_VERSION)
+    data.setdefault("created_at", now)
+    data.setdefault("created_by", "bug-planner")
+
+    # Set default status for bugs without one
+    for bug in data.get("bugs", []):
+        bug.setdefault("status", "pending")
+
+    # Validate
+    result = validate(data)
+
+    # Output validation result
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+
+    if result["valid"]:
+        _write_json(args.output, data)
+        _info("Generated bug-fix-list written to {}".format(args.output))
         return 0
+    else:
+        _err("Validation failed with {} error(s)".format(len(result["errors"])))
+        for e in result["errors"]:
+            _err("  ERROR: {}".format(e))
+        return 1
 
 
-if __name__ == "__main__":
-    bug_list = sys.argv[1] if len(sys.argv) > 1 else ".prizmkit/plans/bug-fix-list.json"
-    feature_list = None
+def main():
+    # Backward compatibility: if first arg is a file path (not a subcommand),
+    # treat it as 'validate' command
+    if len(sys.argv) > 1 and not sys.argv[1].startswith("-") and sys.argv[1] not in ("validate", "generate"):
+        sys.argv.insert(1, "validate")
+
+    parser = argparse.ArgumentParser(
+        description="Validate and generate .prizmkit/plans/bug-fix-list.json files.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "Examples:\n"
+            "  %(prog)s validate .prizmkit/plans/bug-fix-list.json\n"
+            "  %(prog)s validate .prizmkit/plans/bug-fix-list.json --feature-list .prizmkit/plans/feature-list.json\n"
+            "  %(prog)s generate --input draft.json --output .prizmkit/plans/bug-fix-list.json\n"
+        ),
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Command to execute")
+
+    # -- validate --
+    p_validate = subparsers.add_parser(
+        "validate",
+        help="Validate an existing bug-fix-list.json",
+    )
+    p_validate.add_argument(
+        "input", help="Path to bug-fix-list.json"
+    )
+    p_validate.add_argument(
+        "--feature-list", default=None, help="Path to feature-list.json for cross-reference"
+    )
 
-    if "--feature-list" in sys.argv:
-        idx = sys.argv.index("--feature-list")
-        if idx + 1 < len(sys.argv):
-            feature_list = sys.argv[idx + 1]
+    # -- generate --
+    p_generate = subparsers.add_parser(
+        "generate",
+        help="Validate a draft and generate final bug-fix-list.json with defaults",
+    )
+    p_generate.add_argument(
+        "--input", required=True, help="Path to draft JSON (or '-' for stdin)"
+    )
+    p_generate.add_argument(
+        "--output", required=True, help="Path to write final bug-fix-list.json"
+    )
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help(sys.stderr)
+        return 2
 
-    sys.exit(validate(bug_list, feature_list))
+    dispatch = {
+        "validate": cmd_validate,
+        "generate": cmd_generate,
+    }
+
+    handler = dispatch.get(args.command)
+    if handler is None:
+        _err("Unknown command: {}".format(args.command))
+        return 2
+
+    return handler(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -263,9 +263,12 @@ For simple incremental planning, skip detailed Phase 2-3 analysis:
    **NEVER proceed without explicit user selection via `AskUserQuestion`. Do NOT render options as plain text — the user must be able to click/select.**
 3. Generate next sequential feature IDs
 4. Draft features (title + description + acceptance_criteria + dependencies)
-5. Run validation script immediately
+5. Write draft to `.prizmkit/plans/feature-list.draft.json`, then call the generate script:
+   ```bash
+   python3 ${SKILL_DIR}/scripts/validate-and-generate.py generate --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json --mode incremental
+   ```
 6. If valid → summarize and recommend next step
-7. If invalid → apply fixes, re-validate (max 2 attempts, then escalate to full workflow)
+7. If invalid → apply fixes to the draft, re-run generate (max 2 attempts, then escalate to full workflow)
 
 ## Browser Interaction Planning
 
@@ -309,10 +312,13 @@ Key requirements:
   - `high` → **standard** (orchestrator + dev + reviewer, 3 agents)
   - `critical` → **full** (full team + critic agents, 5 agents). Use for: architectural changes touching 10+ files, cross-module refactoring with API surface changes, features requiring multi-critic voting
 
-Run the validation script after generation:
+**IMPORTANT: Do NOT hand-write the final JSON file.** Instead:
+1. Write a draft JSON to a temporary path (e.g., `.prizmkit/plans/feature-list.draft.json`)
+2. Call the generate script to validate and produce the final file:
 ```bash
-python3 ${SKILL_DIR}/scripts/validate-and-generate.py validate --input <output-path> --mode <new|incremental>
+python3 ${SKILL_DIR}/scripts/validate-and-generate.py generate --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json --mode <new|incremental>
 ```
+The script fills in defaults (`$schema`, `created_at`, `created_by`), validates all fields, and writes the final file only if validation passes. If validation fails, fix the draft and retry.
 
 ## Testing Defaults (Phase 8)
 

package/bundled/skills/feature-planner/scripts/validate-and-generate.py

@@ -6,12 +6,14 @@ for the dev-pipeline system.
 Commands:
   validate    Validate an existing .prizmkit/plans/feature-list.json
   template    Generate a blank template .prizmkit/plans/feature-list.json
+  generate    Validate a draft JSON and generate final feature-list.json with defaults
   summary     Print a summary table of features from a .prizmkit/plans/feature-list.json
   grade       Generate grading results from eval runs (for npm run skill:review)
 
 Usage:
   python3 validate-and-generate.py validate --input .prizmkit/plans/feature-list.json [--output validated.json] [--mode new|incremental]
   python3 validate-and-generate.py template --output .prizmkit/plans/feature-list.json
+  python3 validate-and-generate.py generate --input draft.json --output .prizmkit/plans/feature-list.json [--mode new|incremental]
   python3 validate-and-generate.py summary --input .prizmkit/plans/feature-list.json [--format markdown|json]
   python3 validate-and-generate.py grade --workspace /.codebuddy/skill-evals/feature-planner-workspace --iteration iteration-1
 
@@ -716,6 +718,66 @@ def cmd_template(args):
     return 0
 
 
+def cmd_generate(args):
+    """Handle the 'generate' command.
+
+    Loads a draft JSON (produced by AI), fills in defaults, validates,
+    and writes the final feature-list.json.
+    """
+    if not args.input:
+        _err("--input is required for the generate command")
+        return 2
+    if not args.output:
+        _err("--output is required for the generate command")
+        return 2
+
+    # Load draft (supports stdin via '-')
+    if args.input == "-":
+        try:
+            data = json.load(sys.stdin)
+        except json.JSONDecodeError as exc:
+            _err("Invalid JSON from stdin: {}".format(exc))
+            return 2
+    else:
+        data, load_err = _load_json(args.input)
+        if load_err:
+            _err(load_err)
+            return 2
+
+    # Fill in defaults
+    now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    data.setdefault("$schema", SCHEMA_VERSION)
+    data.setdefault("created_at", now)
+    data.setdefault("created_by", "feature-planner")
+
+    # Ensure project_name from app_name if needed
+    if "project_name" not in data and "app_name" in data:
+        data["project_name"] = data["app_name"]
+
+    # Set default status for features without one
+    for feature in data.get("features", []):
+        feature.setdefault("status", "pending")
+
+    # Validate
+    mode = getattr(args, "mode", "new") or "new"
+    result = validate_feature_list(data, planning_mode=mode)
+
+    # Output validation result
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+
+    if result["valid"]:
+        _write_json(args.output, data)
+        _info("Generated feature-list written to {}".format(args.output))
+        return 0
+    else:
+        _err("Validation failed with {} error(s)".format(len(result["errors"])))
+        for e in result["errors"]:
+            _err("  " + e)
+        for w in result.get("warnings", []):
+            _warn("  " + w)
+        return 1
+
+
 def cmd_summary(args):
     """Handle the 'summary' command."""
     if not args.input:
@@ -857,6 +919,7 @@ def main():
             "  %(prog)s validate --input .prizmkit/plans/feature-list.json --mode incremental\n"
             "  %(prog)s validate --input .prizmkit/plans/feature-list.json --output validated.json\n"
             "  %(prog)s template --output .prizmkit/plans/feature-list.json\n"
+            "  %(prog)s generate --input draft.json --output .prizmkit/plans/feature-list.json\n"
             "  %(prog)s summary --input .prizmkit/plans/feature-list.json\n"
             "  %(prog)s summary --input .prizmkit/plans/feature-list.json --format json\n"
         ),
@@ -891,6 +954,24 @@ def main():
         "--output", required=True, help="Path to write template file"
     )
 
+    # -- generate --
+    p_generate = subparsers.add_parser(
+        "generate",
+        help="Validate a draft and generate final feature-list.json with defaults filled in",
+    )
+    p_generate.add_argument(
+        "--input", required=True, help="Path to draft JSON (or '-' for stdin)"
+    )
+    p_generate.add_argument(
+        "--output", required=True, help="Path to write final feature-list.json"
+    )
+    p_generate.add_argument(
+        "--mode",
+        choices=["new", "incremental"],
+        default="new",
+        help="Validation mode (default: new)",
+    )
+
     # -- summary --
     p_summary = subparsers.add_parser(
         "summary",
@@ -931,6 +1012,7 @@ def main():
     dispatch = {
         "validate": cmd_validate,
         "template": cmd_template,
+        "generate": cmd_generate,
         "summary": cmd_summary,
         "grade": cmd_grade,
     }

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

@@ -293,12 +293,14 @@ If issues found, discuss with user and resolve before proceeding.
 
 **Goal**: Produce `.prizmkit/plans/refactor-list.json` and validate it.
 
-1. Generate `.prizmkit/plans/refactor-list.json` at `.prizmkit/plans/`
-2. Run validation:
+**IMPORTANT: Do NOT hand-write the final JSON file.** Instead:
+1. Write a draft JSON to `.prizmkit/plans/refactor-list.draft.json` with all collected refactor data.
+2. Call the generate script to validate and produce the final file:
    ```bash
-   python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py validate --input .prizmkit/plans/refactor-list.json
+   python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py generate --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
    ```
-3. If validation fails -> fix issues and re-validate (max 3 attempts)
+   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)
 4. If validation passes -> present final summary
 
 **CHECKPOINT CP-RP-6**: `.prizmkit/plans/refactor-list.json` generated and validated.
@@ -380,9 +382,12 @@ For simple refactoring with minimal scope:
    
    **NEVER proceed without explicit user selection via `AskUserQuestion`. Do NOT render options as plain text — the user must be able to click/select.**
 3. Draft items (title + type + scope + description + acceptance_criteria + behavior_preservation + dependencies)
-4. Run validation script immediately
+4. Write draft to `.prizmkit/plans/refactor-list.draft.json`, then call the generate script:
+   ```bash
+   python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py generate --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
+   ```
 5. If valid -> summarize and recommend next step
-6. If invalid -> apply fixes, re-validate (max 2 attempts, then escalate to full workflow)
+6. If invalid -> apply fixes to the draft, re-run generate (max 2 attempts, then escalate to full workflow)
 
 ### When NOT to Use Fast Path
 - More than 2 refactor items

package/bundled/skills/refactor-planner/scripts/validate-and-generate-refactor.py

@@ -6,11 +6,13 @@ for the dev-pipeline system.
 Commands:
   validate    Validate an existing .prizmkit/plans/refactor-list.json
   template    Generate a blank template .prizmkit/plans/refactor-list.json
+  generate    Validate a draft JSON and generate final refactor-list.json with defaults
   summary     Print a summary table of refactors from a .prizmkit/plans/refactor-list.json
 
 Usage:
   python3 validate-and-generate-refactor.py validate --input .prizmkit/plans/refactor-list.json [--output validated.json]
   python3 validate-and-generate-refactor.py template --output .prizmkit/plans/refactor-list.json
+  python3 validate-and-generate-refactor.py generate --input draft.json --output .prizmkit/plans/refactor-list.json
   python3 validate-and-generate-refactor.py summary --input .prizmkit/plans/refactor-list.json [--format markdown|json]
 
 Python 3.6+ required. No external dependencies.
@@ -22,6 +24,7 @@ import json
 import os
 import re
 import sys
+from datetime import datetime, timezone
 
 # ---------------------------------------------------------------------------
 # Constants
@@ -687,6 +690,61 @@ def cmd_template(args):
     return 0
 
 
+def cmd_generate(args):
+    """Handle the 'generate' command.
+
+    Loads a draft JSON (produced by AI), fills in defaults, validates,
+    and writes the final refactor-list.json.
+    """
+    if not args.input:
+        _err("--input is required for the generate command")
+        return 2
+    if not args.output:
+        _err("--output is required for the generate command")
+        return 2
+
+    # Load draft (supports stdin via '-')
+    if args.input == "-":
+        try:
+            data = json.load(sys.stdin)
+        except json.JSONDecodeError as exc:
+            _err("Invalid JSON from stdin: {}".format(exc))
+            return 2
+    else:
+        data, load_err = _load_json(args.input)
+        if load_err:
+            _err(load_err)
+            return 2
+
+    # Fill in defaults
+    now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    data.setdefault("$schema", SCHEMA_VERSION)
+    data.setdefault("created_at", now)
+    data.setdefault("created_by", "refactor-planner")
+
+    # Set default status for refactors without one
+    for refactor in data.get("refactors", []):
+        refactor.setdefault("status", "pending")
+
+    # Validate
+    result = validate_refactor_list(data)
+
+    # Output validation result
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+
+    if result["valid"]:
+        _write_json(args.output, data)
+        _info("Generated refactor-list written to {}".format(args.output))
+        return 0
+    else:
+        _err("Validation failed with {} error(s)".format(len(result["errors"])))
+        for e in result["errors"]:
+            _err("  " + e)
+        for w in result.get("warnings", []):
+            _warn("  " + w)
+        return 1
+
+
 def cmd_summary(args):
     """Handle the 'summary' command."""
     if not args.input:
@@ -719,6 +777,7 @@ def main():
             "  %(prog)s validate --input .prizmkit/plans/refactor-list.json\n"
             "  %(prog)s validate --input .prizmkit/plans/refactor-list.json --output validated.json\n"
             "  %(prog)s template --output .prizmkit/plans/refactor-list.json\n"
+            "  %(prog)s generate --input draft.json --output .prizmkit/plans/refactor-list.json\n"
             "  %(prog)s summary --input .prizmkit/plans/refactor-list.json\n"
             "  %(prog)s summary --input .prizmkit/plans/refactor-list.json --format json\n"
         ),
@@ -747,6 +806,18 @@ def main():
         "--output", required=True, help="Path to write template file"
     )
 
+    # -- generate --
+    p_generate = subparsers.add_parser(
+        "generate",
+        help="Validate a draft and generate final refactor-list.json with defaults",
+    )
+    p_generate.add_argument(
+        "--input", required=True, help="Path to draft JSON (or '-' for stdin)"
+    )
+    p_generate.add_argument(
+        "--output", required=True, help="Path to write final refactor-list.json"
+    )
+
     # -- summary --
     p_summary = subparsers.add_parser(
         "summary",
@@ -771,6 +842,7 @@ def main():
     dispatch = {
         "validate": cmd_validate,
         "template": cmd_template,
+        "generate": cmd_generate,
         "summary": cmd_summary,
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prizmkit",
-  "version": "1.1.48",
+  "version": "1.1.49",
   "description": "Create a new PrizmKit-powered project with clean initialization — no framework dev files, just what you need.",
   "type": "module",
   "bin": {