prizmkit 1.1.175 → 1.1.176

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,5 +1,5 @@
1
1
  {
2
- "frameworkVersion": "1.1.175",
3
- "bundledAt": "2026-08-08T09:53:47.266Z",
4
- "bundledFrom": "17d8555"
2
+ "frameworkVersion": "1.1.176",
3
+ "bundledAt": "2026-08-11T07:08:48.540Z",
4
+ "bundledFrom": "529c4ac"
5
5
  }
@@ -10,9 +10,9 @@ For a formal requirement:
10
10
  1. Complete `/prizmkit-retrospective` after Test and before Committer; it synchronizes durable documentation or records `NO_DOC_CHANGE` but never stages or commits.
11
11
  2. Use `/prizmkit-committer` for one local commit operation and one truthful Conventional Commit message.
12
12
  3. The commit candidate is the complete current Git-visible workspace: staged, unstaged, added, deleted, renamed, copied, and non-ignored untracked content, regardless of when or where each valid change originated.
13
- 4. Final Code Review and Test authority must cover every behavior-affecting candidate. Committer inspects the complete final workspace, blocks stale or unsafe evidence, previews every visible change, and waits for explicit interactive confirmation.
14
- 5. Interactive Committer stages the confirmed complete workspace. Headless preparation writes a schema-v2 pathless request, and Python Runtime re-enumerates and stages the complete validated workspace after `COMMIT_PENDING`.
13
+ 4. Final Code Review and Test authority must cover every behavior-affecting candidate. Committer inspects the complete final workspace, blocks stale or unsafe evidence, reports every visible change and message, and continues without an additional confirmation pause.
14
+ 5. Direct Committer revalidates and stages the complete workspace automatically. Explicit Runtime preparation still writes a schema-v2 pathless request, and Python Runtime re-enumerates and stages the complete validated workspace after `COMMIT_PENDING`.
15
15
  6. Ignored paths remain local, never block, and are never force-added. Path provenance or namespace alone never admits or excludes content.
16
- 7. Merge conflicts, Secrets, sensitive local content, known incorrect or incoherent changes, and unverifiable content still block. Only the exact active interactive workflow state or Runtime request/checkpoint and post-commit receipt writes may remain outside the snapshot because their causal finalization follows the commit.
16
+ 7. Merge conflicts, Secrets, sensitive local content, known incorrect or incoherent changes, and unverifiable content still block. Only the exact active direct-workflow state or Runtime request/checkpoint and post-commit receipt writes may remain outside the snapshot because their causal finalization follows the commit.
17
17
  8. Runtime verifies the base, parent, message, non-empty commit, recovery receipt, and checkpoint finalization before integration.
18
18
  9. Remote publication and deployment remain separate.
@@ -1,5 +1,5 @@
1
1
  {
2
- "version": "1.1.175",
2
+ "version": "1.1.176",
3
3
  "skills": {
4
4
  "prizmkit": {
5
5
  "description": "Framework introduction and navigation for the formal single-requirement lifecycle, project initialization, Prizm docs, and independent deployment.",
@@ -40,7 +40,7 @@ This skill is PLANNING ONLY. It may create, append, validate, and review bug pla
40
40
 
41
41
  Your ONLY writable outputs are:
42
42
  1. `.prizmkit/plans/bug-fix-list.json`
43
- 2. Draft backups in `.prizmkit/plans/` (e.g., `bug-fix-list.draft.json`)
43
+ 2. Planner-owned draft state in `.prizmkit/plans/` (e.g., `bug-fix-list.draft.json`) while it is required for deterministic writing, review repair, or explicit recovery
44
44
 
45
45
  After planning is complete, you MUST:
46
46
  1. Present the summary and recommended next step (invoking `bugfix-pipeline-launcher`)
@@ -49,6 +49,10 @@ After planning is complete, you MUST:
49
49
  4. NEVER auto-execute the pipeline, launcher, composite workflow, or any fix step
50
50
  5. Return the validated bug list to the caller; only `bugfix-pipeline-launcher` prepares the runtime command
51
51
 
52
+ ## Draft Lifecycle (Hard Rule)
53
+
54
+ In an ordinary successful flow, `.prizmkit/plans/bug-fix-list.draft.json` is internal writer/review input, not a user approval artifact or separate deliverable. Keep it through `generate`/`append`, validation, and the complete Local Generated-Plan Review fix loop. After the Local Generated-Plan Review returns `PASS` and final validation passes, delete the ordinary internal draft before final handoff. Report `Draft cleanup: removed`. Present the final written result only after cleanup succeeds or a retained recovery reason is surfaced. Retain the draft only for explicit draft-save, interruption or blocking before terminal gates, or cleanup failure; report its path and reason. Cleanup failure does not invalidate an already reviewed and validated final list, but makes the file stale recovery state. Never delete explicit recovery state merely because an older valid final exists. For later adjustments, recreate only the minimum source draft from confirmed in-memory entries or exact-ID `show`; ordinary appends must preserve the exact current suffix and use `append --replace-tail` without loading unrelated history.
55
+
52
56
  ## Fresh-Session Task Contract (Hard Rule)
53
57
 
54
58
  Every new or changed bug is an executable contract for a fresh AI session that has never seen the planning conversation. Do not add new JSON fields, context objects, schema versions, or pipeline runtime structures. Use the existing fields correctly:
@@ -161,8 +165,8 @@ For any content-generating flow that appends to an existing `.prizmkit/plans/bug
161
165
  2. Inspect those pairs only for material continuation, duplication, conflict, a shared public behavior contract, or an execution prerequisite. Add no historical content by default. Chronology, broad module overlap, shared technology, reusable implementation ideas, or similar wording alone do not establish relevance.
162
166
  3. Incorporate only the minimum exact information whose omission would make scope, behavior, compatibility, acceptance criteria, or dependency ordering incorrect. Reject vague `related to B-123` text and whole-description copying; add an old ID to `dependencies` only when it is a real execution prerequisite.
163
167
  4. Only for an explicitly identified old ID or a validation error, run `python3 ${SKILL_DIR}/scripts/validate-bug-list.py show --input .prizmkit/plans/bug-fix-list.json --id B-NNN`.
164
- 5. For append-only planning, write `.prizmkit/plans/bug-fix-list.draft.json` with exactly one root field, `bugs`, containing non-empty unchanged-schema items. Required draft fields are `id`, `title`, `description`, `severity`, `error_source`, `verification_type`, and `acceptance_criteria`; `status` may be omitted and defaults to `pending`; existing optional fields remain allowed. Copy no root metadata or historical bugs.
165
- 6. Run `python3 ${SKILL_DIR}/scripts/validate-bug-list.py append --input .prizmkit/plans/bug-fix-list.draft.json --output .prizmkit/plans/bug-fix-list.json`; it validates the base, sequential IDs, dependencies, and complete DAG before atomic replacement. `generate` remains the new-list and explicit full-rewrite path.
168
+ 5. For append-only planning, write `.prizmkit/plans/bug-fix-list.draft.json` with exactly one root field, `bugs`, containing non-empty unchanged-schema items. This bounded draft is internal transport/recovery state, not a user approval artifact. Required draft fields are `id`, `title`, `description`, `severity`, `error_source`, `verification_type`, and `acceptance_criteria`; `status` may be omitted and defaults to `pending`; existing optional fields remain allowed. Copy no root metadata or historical bugs.
169
+ 6. After consequential decisions and the pre-generation gate pass, immediately run `append`: `python3 ${SKILL_DIR}/scripts/validate-bug-list.py append --input .prizmkit/plans/bug-fix-list.draft.json --output .prizmkit/plans/bug-fix-list.json`. Do not ask for separate user approval merely to promote the draft into the final list. The command validates the base, IDs, dependencies, and complete DAG before atomic replacement. Apply review fixes only to the bounded additions and rerun `append --replace-tail` for the exact current suffix, then follow §Draft Lifecycle before presenting the final written result. `generate` remains the new-list/full-rewrite path.
166
170
  ## Scenario Routing
167
171
 
168
172
  Classify user intent first:
@@ -319,18 +323,18 @@ Return `NEEDS_FIXES` whenever any answer is missing, ambiguous, or available onl
319
323
 
320
324
  **Step 4 — Present review table**: Display the completeness assessment using the template in `${SKILL_DIR}/assets/bug-confirmation-template.md` (§Completeness Review Template).
321
325
 
322
- For any items that need attention, ask targeted questions to fill gaps. Iterate until the user confirms all bugs are adequately described. Present the prompt:
326
+ For any items that need attention, ask targeted questions to fill consequential gaps. Iterate until every flagged semantic gap is resolved. Present the prompt:
323
327
 
324
328
  > "Above is the completeness review. Every `NEEDS_FIXES` item must be clarified before generation. Which flagged item should we address first?"
325
329
 
326
- For every `NEEDS_FIXES` result, update the draft/source bug contract, rerun the artifact-alone questions, and continue until all new or changed bugs return `PASS`. Only proceed to Phase 5 after user confirms.
330
+ For every `NEEDS_FIXES` result, ask only for the consequential missing decision, update the draft/source bug contract, and rerun the artifact-alone questions until all new or changed bugs return `PASS`. Then proceed directly to Phase 5; do not add a separate approval merely to write the already-confirmed content.
327
331
 
328
332
  **Gate → CP-BP-4**: All new or changed bugs pass the Headless Context Completeness Gate without relying on conversation history or `user_context`.
329
333
 
330
334
  ### Phase 5: Generate & Validate
331
335
 
332
- 1. **Write draft JSON**: For a new list, write the complete `.prizmkit/plans/bug-fix-list.draft.json` conforming to the final schema. For an existing list, follow §Bounded Existing-List Context and write only the additions-only `bugs` object.
333
- 2. **Generate or append and validate**:
336
+ 1. **Write draft JSON**: For a new list, write the complete `.prizmkit/plans/bug-fix-list.draft.json` conforming to the final schema. For an existing list, follow §Bounded Existing-List Context and write only the additions-only `bugs` object as internal transport/recovery state.
337
+ 2. **Generate or append immediately and validate** — once required semantic gates pass, invoke the matching writer without a second draft-approval pause:
334
338
  - New list or explicit full-list rewrite:
335
339
  ```bash
336
340
  python3 ${SKILL_DIR}/scripts/validate-bug-list.py generate --input .prizmkit/plans/bug-fix-list.draft.json --output .prizmkit/plans/bug-fix-list.json
@@ -342,28 +346,21 @@ For every `NEEDS_FIXES` result, update the draft/source bug contract, rerun the
342
346
  `generate` fills root defaults for a complete draft. `append` preserves root metadata and historical bugs, defaults missing new statuses, and writes only after the merged full list validates.
343
347
  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`.
344
348
  4. **Run the mandatory Local Generated-Plan Review Gate** (see §Local Generated-Plan Review Gate below): load `${SKILL_DIR}/references/generated-plan-review.md` and review only newly added/changed bug entries after validation passes and before success output.
345
- 5. **Output**: File path, summary, local generated-plan review result, validation outcome, and next steps
349
+ 5. **Complete cleanup and output**: After local review returns `PASS` and final validation passes, follow §Draft Lifecycle, then report the file path, summary, local review, validation, cleanup result, and next steps.
346
350
 
347
351
  **Gate → CP-BP-5**: `bug-fix-list.json` passes validation script with zero errors.
348
352
 
349
- **Gate → CP-BP-6**: Local generated-plan review loaded `${SKILL_DIR}/references/generated-plan-review.md`, reviewed only newly added/changed bug entries, applied accepted fixes through draft/source data, regenerated, and revalidated.
353
+ **Gate → CP-BP-6**: Local generated-plan review loaded `${SKILL_DIR}/references/generated-plan-review.md`, reviewed only newly added/changed bug entries, applied accepted fixes through draft/source data, regenerated, revalidated, and completed terminal draft cleanup or reported why recovery state was retained.
350
354
 
351
355
  ## Local Generated-Plan Review Gate
352
356
 
353
357
  Run this gate after `.prizmkit/plans/bug-fix-list.json` passes generation and validation, and before the final handoff. It applies whenever this session added or changed final bug entries. For validate-only, summary-only, or draft-save flows with no final content change, report that the gate is not applicable.
354
358
 
355
- Read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the single source of truth. Review the actual additions-only draft and use bounded `context` plus explicit-ID `show` for new or changed final entries because `.prizmkit` files may be gitignored; do not load unchanged historical entries. Repeat the Headless Context Completeness Gate for every reviewed new or changed bug. Keep the review planning-only, apply accepted findings to the draft/source representation, regenerate the final JSON, rerun validation, and repeat local review until it returns `PASS` before reporting the result.
359
+ Read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the single source of truth. Review the actual additions-only draft and use bounded `context` plus explicit-ID `show` for new or changed final entries because `.prizmkit` files may be gitignored; do not load unchanged historical entries. Repeat the Headless Context Completeness Gate for every reviewed new or changed bug. Keep the review planning-only, apply accepted findings to the draft/source representation, update ordinary appended entries through `append --replace-tail`, rerun validation, and repeat local review until it returns `PASS`. Complete §Draft Lifecycle cleanup before reporting the final written result.
356
360
 
357
361
  #### Success Output
358
362
 
359
- ```
360
- .prizmkit/plans/bug-fix-list.json generated with 3 bugs (1 critical, 1 medium, 1 low)
361
- Local generated-plan review: PASS, reviewed B-001..B-003, accepted fixes: none, final validation: PASS
362
-
363
- Next steps:
364
- - Review: cat .prizmkit/plans/bug-fix-list.json
365
- - Start fixing: say "start fixing" to launch the bugfix pipeline via bugfix-pipeline-launcher
366
- ```
363
+ Report the final path and bug counts, Local Generated-Plan Review verdict and reviewed IDs, accepted fixes, final validation result, draft cleanup result, and `bugfix-pipeline-launcher` handoff.
367
364
 
368
365
  ### Checkpoints (Mandatory Gates)
369
366
 
@@ -376,7 +373,7 @@ Checkpoints catch cascading errors early — skipping one means the next phase b
376
373
  | **CP-BP-3** | Priorities Set | Severity/priority assigned, duplicates resolved | 3 |
377
374
  | **CP-BP-4** | Completeness Passed | All bugs pass headless execution readiness check | 4 |
378
375
  | **CP-BP-5** | File Generated | `bug-fix-list.json` passes validation script | 5 |
379
- | **CP-BP-6** | Local Plan Review Passed | Local generated-plan review loaded `${SKILL_DIR}/references/generated-plan-review.md`, reviewed only newly added/changed bug entries, applied accepted fixes through draft/source data, regenerated, and revalidated | 5 |
376
+ | **CP-BP-6** | Local Plan Review Passed | Local generated-plan review loaded `${SKILL_DIR}/references/generated-plan-review.md`, reviewed only newly added/changed bug entries, applied accepted fixes through draft/source data, regenerated, revalidated, and completed terminal draft cleanup or reported why recovery state was retained | 5 |
380
377
 
381
378
  **Resume Detection**: If existing `.prizmkit/plans/bug-fix-list.json` or draft found, read `${SKILL_DIR}/references/error-recovery.md` §Resume Support for checkpoint-based resumption.
382
379
 
@@ -386,7 +383,7 @@ Checkpoints catch cascading errors early — skipping one means the next phase b
386
383
 
387
384
  Triggers: "parse this error log", "here's a stack trace", "parse these errors".
388
385
 
389
- Batch-parse error logs with minimal interaction: parse automatically, then require final user confirmation before generating the final list:
386
+ Batch-parse error logs with minimal interaction: parse automatically, resolve consequential gaps through targeted questions, then write the final list immediately:
390
387
 
391
388
  1. Accept log file path or piped content
392
389
  2. Parse all unique errors (deduplicate by error message pattern)
@@ -397,11 +394,10 @@ Batch-parse error logs with minimal interaction: parse automatically, then requi
397
394
  - error_source: populated from log content
398
395
  - verification_type: default to `automated`
399
396
  - acceptance_criteria: auto-generate "Error no longer occurs in [scenario]"
400
- 4. Write draft to `.prizmkit/plans/bug-fix-list.draft.json` for user review
397
+ 4. Write `.prizmkit/plans/bug-fix-list.draft.json` as internal transport/recovery state.
401
398
  5. Run the Phase 4 Headless Context Completeness Gate on every parsed bug. Ask targeted clarification for missing expected behavior, selected scope, severity rationale, or verification decisions; update the draft until all entries pass.
402
- 6. Ask: "Review and confirm? You can edit individual entries."
403
- 7. After user confirms, use the Phase 5 writer: `generate` for a new complete list, or the bounded additions-only `append` command when a final list already exists.
404
- 8. If validation passes, run the mandatory Local Generated-Plan Review Gate before summarizing or recommending `bugfix-pipeline-launcher`.
399
+ 6. Immediately use the Phase 5 writer: `generate` for a new complete list, or the bounded additions-only `append` command when a final list already exists. Do not add another broad approval after the consequential gaps are resolved.
400
+ 7. If validation passes, run the mandatory Local Generated-Plan Review Gate, complete §Draft Lifecycle cleanup, and present the final written result. For later adjustments, recreate the minimum source draft from confirmed in-memory entries or exact-ID `show`, then rerun `generate` for a new-list rewrite or `append --replace-tail` for an ordinary append before recommending `bugfix-pipeline-launcher`.
405
401
 
406
402
  ## Operation: From Tests
407
403
 
@@ -413,11 +409,10 @@ Batch-parse failed test output:
413
409
  2. Parse each failed test case as a separate bug entry
414
410
  3. Auto-populate `failed_test_path`, `error_message`
415
411
  4. Set verification_type to `automated` (test already exists)
416
- 5. Write draft to `.prizmkit/plans/bug-fix-list.draft.json`
417
- 6. Run the Phase 4 Headless Context Completeness Gate on every parsed failed-test bug; ensure the failing test evidence agrees with the final expected behavior and selected fix scope.
418
- 7. Present parsed failed-test bug entries for confirmation; allow edits, merges, or removals
419
- 8. After user confirms, use the Phase 5 writer: `generate` for a new complete list, or the bounded additions-only `append` command when a final list already exists.
420
- 9. If validation passes, run the mandatory Local Generated-Plan Review Gate before summarizing or recommending `bugfix-pipeline-launcher`.
412
+ 5. Write `.prizmkit/plans/bug-fix-list.draft.json` as internal transport/recovery state.
413
+ 6. Run the Phase 4 Headless Context Completeness Gate on every parsed failed-test bug; ask only for consequential missing expected behavior or scope, and allow needed edits, merges, or removals until all entries pass.
414
+ 7. Immediately use the Phase 5 writer: `generate` for a new complete list, or the bounded additions-only `append` command when a final list already exists. Do not add another broad approval after the consequential gaps are resolved.
415
+ 8. If validation passes, run the mandatory Local Generated-Plan Review Gate, complete §Draft Lifecycle cleanup, and present the final written result. For later adjustments, recreate the minimum source draft from confirmed in-memory entries or exact-ID `show`, then rerun `generate` for a new-list rewrite or `append --replace-tail` for an ordinary append before recommending `bugfix-pipeline-launcher`.
421
416
 
422
417
  ## Operation: Validate
423
418
 
@@ -470,8 +465,9 @@ Recommend invoking `bugfix-pipeline-launcher` to configure and launch the pipeli
470
465
  After `.prizmkit/plans/bug-fix-list.json` is generated, validated, and reviewed, present:
471
466
  1. Summary of generated bugs (count, severity breakdown)
472
467
  2. Local generated-plan review result: verdict, reviewed bug IDs plus reviewed root prose when applicable, accepted fixes (or "none"), and final validation result
473
- 3. Recommend: "Say 'start fixing' to launch the bugfix pipeline via `bugfix-pipeline-launcher`"
474
- 4. Alternative: fix a single bug interactively via `bug-fix-workflow`
468
+ 3. Draft cleanup result: `removed`, or retained path and recovery reason
469
+ 4. Recommend: "Say 'start fixing' to launch the bugfix pipeline via `bugfix-pipeline-launcher`"
470
+ 5. Alternative: fix a single bug interactively via `bug-fix-workflow`
475
471
 
476
472
  ## Error Handling
477
473
 
@@ -7,22 +7,22 @@ Reference document for bug-planner error handling and session recovery. Load thi
7
7
  ### Warnings Only
8
8
 
9
9
  If `validate-bug-list.py` returns warnings but no errors:
10
- 1. Present warnings to user
11
- 2. Ask: "Proceed with these warnings, or fix them first?"
12
- 3. If user approves → write file and continue
13
- 4. If user wants fixes → address each warning, re-validate
10
+ 1. Present the warnings
11
+ 2. Continue the deterministic writer/review flow when they are informational
12
+ 3. Ask the user only when a warning exposes a consequential behavior, scope, severity, or verification decision
13
+ 4. Apply any confirmed correction to the planner-owned draft and re-run the matching writer; do not add a generic draft-promotion approval
14
14
 
15
15
  ### Errors Found
16
16
 
17
17
  If validation returns errors:
18
18
  1. Group errors by type (missing fields, invalid values, duplicate IDs, broken references)
19
- 2. Auto-fix where possible:
19
+ 2. Apply unambiguous mechanical fixes to the planner-owned draft where possible:
20
20
  - Missing `status` → set to `pending`
21
21
  - Duplicate IDs → re-number with next sequential B-NNN
22
- - Invalid `priority` → re-derive from severity using the mapping table
23
- 3. Present fixes to user for confirmation
24
- 4. Re-validate after fixes
25
- 5. Maximum 3 total validation attempts — if still failing after 3 rounds, present the raw errors and ask user for guidance
22
+ - Invalid `priority` → re-derive from the already confirmed severity using the mapping table
23
+ 3. Ask only when a correction changes confirmed behavior, scope, severity, verification, or dependency semantics
24
+ 4. Re-run the matching writer and validation after fixes
25
+ 5. Maximum 3 total validation attempts — if still failing after 3 rounds, retain the draft, present the raw errors, and ask user for guidance
26
26
 
27
27
  ### JSON Parse Failure
28
28
 
@@ -39,22 +39,21 @@ When bug-planner detects existing artifacts, determine the last completed checkp
39
39
 
40
40
  | Existing Artifact | Last Checkpoint | Resume From |
41
41
  |---|---|---|
42
- | `.prizmkit/plans/bug-fix-list.json` (valid) | CP-BP-5 | Offer: "Valid bug list exists. Append new bugs (Route B) or regenerate?" |
43
- | `.prizmkit/plans/bug-fix-list.json` (invalid) | CP-BP-4 | Re-run Phase 5 validation and fix |
44
- | `.prizmkit/plans/bug-fix-list.draft.json` | CP-BP-2 or CP-BP-3 | Load draft, determine phase from content completeness, resume |
42
+ | `.prizmkit/plans/bug-fix-list.json` (valid), no draft | CP-BP-6 | Offer: "Valid bug list exists. Append new bugs (Route B) or regenerate?" |
43
+ | `.prizmkit/plans/bug-fix-list.json` (invalid) | CP-BP-4 | Resume Phase 5 repair through the source draft |
44
+ | `.prizmkit/plans/bug-fix-list.draft.json` only | CP-BP-2 through CP-BP-5 | Load draft, determine phase from actual completeness, resume |
45
+ | Valid final plus `.prizmkit/plans/bug-fix-list.draft.json` | CP-BP-5 or cleanup failure | Treat as interrupted review or cleanup-failure state; inspect and offer resume review, discard, or a new append rather than assuming either artifact wins |
45
46
  | `.prizmkit/config.json` with tech_stack | CP-BP-1 (partial) | Skip project context questions, start at Phase 2 |
46
47
  | No artifacts | — | Start from Phase 1 |
47
48
 
48
49
  ### Resume Detection Flow
49
50
 
50
- 1. Check for `.prizmkit/plans/bug-fix-list.json`
51
- - If exists and valid → offer Route B (append) or full regeneration
52
- - If exists but invalid → offer to fix and re-validate (resume from CP-BP-4)
53
- 2. Check for `.prizmkit/plans/bug-fix-list.draft.json`
54
- - If exists → load draft, count bugs with/without confirmation, resume from appropriate phase
55
- 3. Check for `.prizmkit/config.json`
56
- - If exists with tech_stack → skip Phase 1 context gathering
57
- 4. If no artifacts → start fresh (Route A)
51
+ 1. Check for both `.prizmkit/plans/bug-fix-list.json` and `.prizmkit/plans/bug-fix-list.draft.json` before choosing a route.
52
+ 2. If both exist, validate the final and inspect the draft's actual completeness. Resume unfinished review/recovery or discard the draft only after its state is understood; ask the user if session evidence cannot distinguish interruption from cleanup failure.
53
+ 3. If only the final exists, offer Route B for a valid list or resume writer/validation repair for an invalid list.
54
+ 4. If only the draft exists, load it, determine which semantic and validation gates remain, and resume there.
55
+ 5. Check `.prizmkit/config.json`; if it contains `tech_stack`, skip Phase 1 context gathering.
56
+ 6. If no artifacts exist, start fresh (Route A).
58
57
 
59
58
  ### Session Interruption Recovery
60
59
 
@@ -67,7 +66,8 @@ If a bug-planner session is interrupted mid-planning:
67
66
 
68
67
  ## Draft Management
69
68
 
70
- - Save drafts to `.prizmkit/plans/bug-fix-list.draft.json` after each completed phase (CP-BP-1 through CP-BP-4)
71
- - Drafts use the same schema as the final file but may have incomplete fields
72
- - Delete draft after successful generation of the final `bug-fix-list.json`
73
- - Keep at most 1 draft — overwrite on each phase completion
69
+ - Use one planner-owned `.prizmkit/plans/bug-fix-list.draft.json`. In an ordinary writer flow it must be either a complete new-list source or a complete additions-only object; an explicitly saved pre-generation recovery draft may be incomplete and must not enter `generate` or `append` until the semantic gates and required shape pass.
70
+ - Keep the ordinary draft through generation/append, validation, and the complete Local Generated-Plan Review fix loop. Generation success alone is not a cleanup boundary because review repairs still use the draft as source.
71
+ - After Local Generated-Plan Review returns `PASS` and final validation passes, delete the ordinary internal draft before handoff.
72
+ - Retain a draft only for explicit draft-save, interruption or blocking before terminal gates, or cleanup failure. Report its path and reason. Cleanup failure leaves a reviewed final list valid but must be reported as stale recovery state.
73
+ - Keep at most one active draft. Do not archive or duplicate an ambiguous draft until the user chooses to discard or preserve it.
@@ -6,6 +6,8 @@ Use this local review loop after `.prizmkit/plans/bug-fix-list.json` has been ge
6
6
 
7
7
  Run only when the current `bug-planner` session generated, appended, or rewrote final bug planning content. For validate-only, summary-only, or draft-save flows with no new final planning content, report: `Local generated-plan review: not applicable — no new final planning content written.`
8
8
 
9
+ In ordinary incremental flow, the additions draft is internal transport/recovery state. After consequential decisions and the pre-generation gate pass, immediately run `append`; do not ask for separate user approval merely to promote the draft into the final list. Keep the draft through the bounded review/fix loop, then delete the ordinary internal draft before final handoff only after this review returns `PASS` and final validation passes.
10
+
9
11
  ## Direct Artifact Reads
10
12
 
11
13
  Planning artifacts may be gitignored, untracked, or absent from staged and unstaged diffs. Read the actual files through bounded, source-first access:
@@ -89,9 +91,10 @@ For a new list or explicit full-list rewrite, regenerate through the existing sc
89
91
  python3 ${SKILL_DIR}/scripts/validate-bug-list.py generate --input .prizmkit/plans/bug-fix-list.draft.json --output .prizmkit/plans/bug-fix-list.json
90
92
  ```
91
93
 
92
- 5. Re-run append/generation until valid. Do not hand-patch `.prizmkit/plans/bug-fix-list.json` as the source of truth.
94
+ 5. Re-run append/generation until valid. Do not hand-patch `.prizmkit/plans/bug-fix-list.json` as the source of truth and do not add a user approval round for the mechanical rewrite.
93
95
  6. Repeat the local review and Headless Context Completeness Gate only for entries changed by accepted fixes.
94
96
  7. Do not report `PASS` until every required fresh-session answer is available and final validation passes after regeneration.
97
+ 8. After `PASS`, delete `.prizmkit/plans/bug-fix-list.draft.json` before final handoff when it is an ordinary internal draft. Retain it only for explicit draft-save, interruption or blocking before the terminal gates, or cleanup failure; report the retained path and reason. Cleanup failure leaves the reviewed final list valid but must be reported as stale recovery state.
95
98
 
96
99
  ## Report Format
97
100
 
@@ -101,4 +104,5 @@ Report in the final handoff summary:
101
104
  - Reviewed bug IDs and reviewed root prose (`project_description` / `global_context`) when applicable
102
105
  - Accepted fixes, or `none`
103
106
  - Final validation result
107
+ - Draft cleanup result: `removed`, or retained path and recovery reason
104
108
  - Note when review was not applicable because no new final planning content was written
@@ -48,7 +48,7 @@ The user chose this skill intentionally. Respect that choice.
48
48
 
49
49
  **Your ONLY writable outputs are:**
50
50
  1. `.prizmkit/plans/feature-list.json` (`.prizmkit/plans/`)
51
- 2. Draft backups in `.prizmkit/plans/` (e.g., `feature-list.draft.json`)
51
+ 2. Planner-owned draft state in `.prizmkit/plans/` (e.g., `feature-list.draft.json`) while it is required for deterministic writing, review repair, or explicit recovery
52
52
 
53
53
  **After planning is complete**, you MUST:
54
54
  1. Present the summary and recommended next step (invoking `feature-pipeline-launcher` )
@@ -57,6 +57,10 @@ The user chose this skill intentionally. Respect that choice.
57
57
  4. **NEVER auto-execute** the pipeline, launcher, composite workflow, or any implementation step
58
58
  5. Return the validated list to the caller; only `feature-pipeline-launcher` prepares the runtime command
59
59
 
60
+ ## Draft Lifecycle (Hard Rule)
61
+
62
+ In an ordinary successful flow, `.prizmkit/plans/feature-list.draft.json` is internal writer/review input, not a user approval artifact or separate deliverable. Keep it through `generate`/`append`, validation, and the complete Local Generated-Plan Review fix loop. After the Local Generated-Plan Review returns `PASS` and final validation passes, delete the ordinary internal draft before final handoff. Report `Draft cleanup: removed`. Present the final written result. Retain the draft only for explicit draft-save, interruption or blocking before terminal gates, or cleanup failure; report its path and reason. Cleanup failure does not invalidate an already reviewed and validated final list, but makes the file stale recovery state. Never delete explicit recovery state merely because an older valid final exists. For later adjustments, recreate only the minimum source draft from confirmed in-memory entries or exact-ID `show`; ordinary appends must preserve the exact current suffix and use `append --replace-tail` without loading unrelated history.
63
+
60
64
  ## Fresh-Session Task Contract (Hard Rule)
61
65
 
62
66
  Every new or changed feature is an executable contract for a fresh AI session that has never seen the planning conversation. Do not add new JSON fields, context objects, schema versions, or pipeline runtime structures. Use the existing fields correctly:
@@ -238,8 +242,8 @@ For ordinary incremental planning, NEVER read the complete existing `.prizmkit/p
238
242
  2. Inspect those pairs only for material continuation, duplication, conflict, a shared public behavior contract, or an execution prerequisite. Add no historical content by default. Chronology, broad module overlap, shared technology, reusable implementation ideas, or similar wording alone do not establish relevance.
239
243
  3. Incorporate only the minimum exact information whose omission would make scope, behavior, compatibility, acceptance criteria, or dependency ordering incorrect. Reject vague `related to F-123` text and whole-description copying; add an old ID to `dependencies` only when it is a real execution prerequisite.
240
244
  4. Only for an explicitly identified old ID or a validation error, run `python3 ${SKILL_DIR}/scripts/validate-and-generate.py show --input .prizmkit/plans/feature-list.json --id F-NNN`.
241
- 5. For append-only planning, write `.prizmkit/plans/feature-list.draft.json` with exactly one root field, `features`, containing non-empty unchanged-schema items. Required draft fields are `id`, `title`, `description`, `priority`, `dependencies`, and `acceptance_criteria`; `status` may be omitted and defaults to `pending`; existing optional fields remain allowed. Copy no root metadata or historical features.
242
- 6. Run `python3 ${SKILL_DIR}/scripts/validate-and-generate.py append --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json`; it validates the base, sequential IDs, dependencies, and complete DAG before atomic replacement. `generate` remains the initial-plan and explicit full-rewrite path.
245
+ 5. For append-only planning, write `.prizmkit/plans/feature-list.draft.json` with exactly one root field, `features`, containing non-empty unchanged-schema items. This bounded draft is internal transport/recovery state, not a user approval artifact. Required draft fields are `id`, `title`, `description`, `priority`, `dependencies`, and `acceptance_criteria`; `status` may be omitted and defaults to `pending`; existing optional fields remain allowed. Copy no root metadata or historical features.
246
+ 6. After consequential decisions and the pre-generation gate pass, immediately run `append`: `python3 ${SKILL_DIR}/scripts/validate-and-generate.py append --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json`. Do not ask for separate user approval merely to promote the draft into the final list. The command validates the base, IDs, dependencies, and complete DAG before atomic replacement. Apply review fixes only to the bounded additions and rerun `append --replace-tail` for the exact current suffix, then follow §Draft Lifecycle before presenting the final written result. `generate` remains the initial-plan/full-rewrite path.
243
247
  ## Scenario Routing
244
248
  Classify user intent first:
245
249
 
@@ -310,8 +314,8 @@ Execute the planning workflow in conversation mode with mandatory checkpoints:
310
314
  7. Build or append `.prizmkit/plans/feature-list.json`
311
315
  8. Apply default testing strategy (see §Testing Defaults below)
312
316
  9. Validate and fix until pass
313
- 10. Run the mandatory Local Generated-Plan Review Gate (see §Local Generated-Plan Review Gate below); apply accepted fixes to the draft/source plan, regenerate, and revalidate until pass
314
- 11. Summarize final feature table with local review result and validation outcome
317
+ 10. Run the mandatory Local Generated-Plan Review Gate (see §Local Generated-Plan Review Gate below); apply accepted fixes to the draft/source plan, regenerate, and revalidate until pass, then complete §Draft Lifecycle cleanup
318
+ 11. Summarize final feature table with local review result, validation outcome, and draft cleanup result
315
319
 
316
320
  ### Checkpoints (Mandatory Gates)
317
321
 
@@ -327,7 +331,7 @@ Checkpoints catch cascading errors early — skipping one means the next phase b
327
331
  | **CP-FP-3.3** | Completeness Review Passed | Every new or changed feature passes fresh-session simulation from `description` and `acceptance_criteria` without conversation history or `user_context` | 6 |
328
332
  | **CP-FP-4** | `.prizmkit/plans/feature-list.json` Generated | Schema validates, all required keys present | 7-8 |
329
333
  | **CP-FP-5** | Final Validation Pass | Python script returns `"valid": true` with zero errors | 9 |
330
- | **CP-FP-6** | Local Plan Review Passed | Local generated-plan review loaded `${SKILL_DIR}/references/generated-plan-review.md`, reviewed only newly added/changed feature entries, applied accepted fixes through draft/source data, regenerated, and revalidated | 10 |
334
+ | **CP-FP-6** | Local Plan Review Passed | Local generated-plan review loaded `${SKILL_DIR}/references/generated-plan-review.md`, reviewed only newly added/changed feature entries, applied accepted fixes through draft/source data, regenerated, revalidated, and completed terminal draft cleanup or reported why recovery state was retained | 10-11 |
331
335
 
332
336
  **Resume Detection**: If existing artifacts are found, read `${SKILL_DIR}/references/error-recovery.md` §Resume Support for checkpoint-based resumption.
333
337
 
@@ -374,11 +378,11 @@ For simple incremental planning, skip detailed Phase 2-3 analysis:
374
378
  3. Generate next sequential feature IDs
375
379
  4. Draft features (title + description + acceptance_criteria + dependencies)
376
380
  5. Run the mandatory pre-generation Headless Context Completeness Gate from Phase 6 on every drafted feature; repair the draft until each returns `PASS`.
377
- 6. Write an additions-only draft to `.prizmkit/plans/feature-list.draft.json`, then call the append command:
381
+ 6. Write the additions-only draft as internal input and immediately call the append command without a second draft-approval pause:
378
382
  ```bash
379
383
  python3 ${SKILL_DIR}/scripts/validate-and-generate.py append --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
380
384
  ```
381
- 7. If valid → run the mandatory Local Generated-Plan Review Gate, then summarize and recommend next step
385
+ 7. If valid → run the mandatory Local Generated-Plan Review Gate, complete §Draft Lifecycle cleanup, then present the final written result and recommend the next step
382
386
  8. If invalid → apply fixes to the additions-only draft, re-run `append` (max 2 attempts, then escalate to full workflow)
383
387
 
384
388
  ## Browser Interaction Planning
@@ -429,13 +433,13 @@ Key requirements:
429
433
  python3 ${SKILL_DIR}/scripts/validate-and-generate.py append --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
430
434
  ```
431
435
 
432
- `generate` fills root defaults for complete drafts. `append` preserves root metadata and historical features, defaults missing new statuses, validates the merged full list, and writes only after validation passes. If either command fails, fix its source draft and retry.
436
+ `generate` fills root defaults for complete drafts. `append` preserves root metadata and historical features, defaults missing new statuses, validates the merged full list, and writes only after validation passes. In ordinary incremental flow, call `append` immediately after semantic gates; the draft is not a second approval checkpoint. If either command fails, fix its source draft and retry. Do not delete the draft until the Local Generated-Plan Review and final validation pass; then follow §Draft Lifecycle.
433
437
 
434
438
  ## Local Generated-Plan Review Gate
435
439
 
436
440
  Run this gate after `.prizmkit/plans/feature-list.json` passes generation and validation, and before the final handoff. It applies whenever this session added or changed final feature entries. For validate-only, summary-only, or draft-save flows with no final content change, report that the gate is not applicable.
437
441
 
438
- Read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the single source of truth. Review the actual additions-only draft and use bounded `context` plus explicit-ID `show` for new or changed final entries because `.prizmkit` files may be gitignored; do not load unchanged historical entries. Repeat the Headless Context Completeness Gate for every reviewed new or changed feature. Keep the review planning-only, apply accepted findings to the draft/source representation, regenerate the final JSON, rerun validation, and repeat the local review until it returns `PASS` before reporting the result.
442
+ Read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the single source of truth. Review the actual additions-only draft and use bounded `context` plus explicit-ID `show` for new or changed final entries because `.prizmkit` files may be gitignored; do not load unchanged historical entries. Repeat the Headless Context Completeness Gate for every reviewed new or changed feature. Keep the review planning-only, apply accepted findings to the draft/source representation, update ordinary appended entries through `append --replace-tail`, rerun validation, and repeat the local review until it returns `PASS`. Complete §Draft Lifecycle cleanup before reporting the final written result.
439
443
 
440
444
  ## Testing Defaults (Phase 8)
441
445
 
@@ -459,11 +463,7 @@ Recommend invoking `feature-pipeline-launcher` to configure and launch the dev-p
459
463
 
460
464
  If validation fails or a session is interrupted → read `${SKILL_DIR}/references/error-recovery.md` for the full error type table, decision tree, retry logic, and checkpoint-based resume support.
461
465
 
462
- Key behaviors:
463
- - Warnings only → proceed with user approval
464
- - Critical errors → group by type, auto-fix where possible, max 3 total attempts
465
- - Interrupted session → detect checkpoint from existing artifacts, offer resume or restart
466
- - `.prizmkit/plans/feature-list.json` MUST be written to `.prizmkit/plans/` (project root level: `./{root}/.prizmkit/plans/feature-list.json`)
466
+ Key behaviors: continue informational warnings without a draft-promotion pause; clarify consequential warnings; group critical errors and retry safe fixes at most three times; resume interrupted state from actual artifacts; always write the final list at project-root `.prizmkit/plans/feature-list.json`.
467
467
 
468
468
  ## Session Exit Gate
469
469
 
@@ -480,7 +480,7 @@ When the session appears to be ending:
480
480
  1. **Remind**: "You set out to produce `.prizmkit/plans/feature-list.json` but we haven't completed it yet."
481
481
  2. Use `AskUserQuestion` with one question:
482
482
  - **Continue to completion (Recommended)** — resume from current phase
483
- - **Save draft & exit** — write current progress as `.prizmkit/plans/feature-list.draft.json`
483
+ - **Save draft & exit** — write current progress as `.prizmkit/plans/feature-list.draft.json` and retain it as explicit recovery state; terminal cleanup does not apply until planning resumes and completes
484
484
  - **Abandon** — exit without saving
485
485
 
486
486
  ## Handoff Message Template
@@ -489,7 +489,7 @@ After successful validation and the Local Generated-Plan Review Gate, report:
489
489
  1. Output file path
490
490
  2. Total features + newly added features
491
491
  3. Dependency and priority highlights
492
- 4. Local generated-plan review result: verdict, reviewed feature IDs plus reviewed root prose when applicable, accepted fixes (or "none"), and final validation result
492
+ 4. Local generated-plan review result: verdict, reviewed feature IDs plus reviewed root prose when applicable, accepted fixes (or "none"), final validation result, and draft cleanup result (`removed` or retained path/reason)
493
493
  5. Recommended next action: `feature-pipeline-launcher`
494
494
 
495
495
  Then apply the post-planning handoff in §Scope Boundary (ask before proceeding; never auto-execute).
@@ -12,8 +12,8 @@ Script returns JSON with `"valid": false`, `"errors": [...]`, `"warnings": [...]
12
12
  ### Decision Tree
13
13
 
14
14
  **if `error_count == 0` (warnings only):**
15
- - Proceed with user approval
16
- - Show warnings and ask: "Continue? (Y/n)"
15
+ - Continue the deterministic writer/review flow when warnings are informational
16
+ - Ask the user only when a warning exposes a consequential product, scope, compatibility, or verification decision; do not add a generic draft-promotion approval
17
17
 
18
18
  **elif `error_count > 0` (critical errors):**
19
19
 
@@ -34,15 +34,14 @@ Group errors by type and apply targeted fixes:
34
34
  ```
35
35
  For auto-fixable errors:
36
36
  1. Show summary: "Found N schema/ID/format issues"
37
- 2. Offer: auto-fix? (Y/n)
38
- 3. Apply fix → regenerate file
39
- 4. Re-run validation
40
- 5. If new errors → loop (max 2 more attempts)
37
+ 2. Apply unambiguous mechanical fixes to the planner-owned draft
38
+ 3. Re-run the matching deterministic writer and validation
39
+ 4. If new errors → loop (max 2 more attempts)
41
40
 
42
- For manual fixes (dependencies, AC content):
43
- 1. Show concise prompt: "Edit line X-Y in feature-list.json"
44
- 2. Wait for user action
45
- 3. Retry validation (max 2 more attempts)
41
+ For semantic fixes (dependencies, acceptance-criteria content):
42
+ 1. Ask only for the consequential missing decision
43
+ 2. Apply the confirmed correction to the planner-owned draft, never directly to the final list
44
+ 3. Re-run the matching writer and validation (max 2 more attempts)
46
45
 
47
46
  if all_retries_exceeded:
48
47
  → Escalate: "After 3 attempts, validation still fails.
@@ -61,13 +60,16 @@ Check for artifact files in `.prizmkit/plans/`:
61
60
  | Artifacts Found | Resume Action |
62
61
  |-----------------|---------------|
63
62
  | None | Start fresh planning (Phase 1) |
64
- | `feature-list.json` exists but not validated | Offer to validate or extend (Phase 9) |
65
- | `feature-list.json` + validation passed | Offer: handoff to `feature-pipeline-launcher` |
66
- | `feature-list.draft.json` only | Resume interactive planning from last checkpoint |
63
+ | `feature-list.json` exists but not validated | Resume writer/validation repair through the source draft |
64
+ | Valid `feature-list.json` only | Offer handoff to `feature-pipeline-launcher` |
65
+ | `feature-list.draft.json` only | Resume interactive planning from the draft's actual completeness |
66
+ | Valid `feature-list.json` plus `feature-list.draft.json` | Treat as interrupted review or cleanup-failure state; inspect the draft and offer to resume review, discard it, or start a new increment rather than assuming either artifact wins |
67
67
 
68
- When existing file detected, suggest:
68
+ When only a valid final list is detected, suggest:
69
69
  > "Existing plan found with N features. Resume incremental planning? (Y/n)"
70
70
 
71
+ When final and draft both exist, identify the two artifacts explicitly and ask whether to resume the unfinished review/recovery state or discard it before starting a new increment.
72
+
71
73
  ### Incremental Mode Abort
72
74
 
73
75
  If in Incremental mode but existing `feature-list.json` not found:
@@ -84,8 +86,16 @@ Before writing, verify the directory exists: `mkdir -p .prizmkit/plans`
84
86
  <project-root>/
85
87
  └── .prizmkit/plans/
86
88
  ├── feature-list.json # Primary output
87
- ├── feature-list.draft.json # Draft backup (Session Exit Gate)
89
+ ├── feature-list.draft.json # Temporary writer/review input or explicit recovery state
88
90
  └── <ISO-timestamp>.backup.json # Optional incremental backups
89
91
  ```
90
92
 
93
+ ## Draft Management
94
+
95
+ - An ordinary writer draft must remain available while generation, append, validation, or Local Generated-Plan Review repair is incomplete.
96
+ - After Local Generated-Plan Review returns `PASS` and final validation passes, delete the ordinary internal draft before handoff.
97
+ - Retain a draft only after explicit **Save draft & exit**, interruption or blocking before terminal gates, or cleanup failure. Report its path and reason.
98
+ - Cleanup failure does not invalidate a reviewed and validated final list, but the retained file is stale recovery state and must be surfaced.
99
+ - If both final and draft exist on resume, do not delete or promote the draft blindly. Determine whether review was interrupted or cleanup failed from the artifacts and available session evidence; ask the user when that outcome remains ambiguous.
100
+
91
101
  > **Note**: For cross-session workflow recovery (e.g., interrupted pipeline execution, branch-level state detection), use `recovery-workflow` instead. This error-recovery reference handles only within-session validation retries and checkpoint resumption.
@@ -6,6 +6,8 @@ Use this local review loop after `.prizmkit/plans/feature-list.json` has been ge
6
6
 
7
7
  Run only when the current `feature-planner` session generated, appended, or rewrote final feature planning content. For validate-only, summary-only, or draft-save flows with no new final planning content, report: `Local generated-plan review: not applicable — no new final planning content written.`
8
8
 
9
+ In ordinary incremental flow, the additions draft is internal transport/recovery state. After consequential decisions and the pre-generation gate pass, immediately run `append`; do not ask for separate user approval merely to promote the draft into the final list. Keep the draft through the bounded review/fix loop, then delete the ordinary internal draft before final handoff only after this review returns `PASS` and final validation passes.
10
+
9
11
  ## Direct Artifact Reads
10
12
 
11
13
  Planning artifacts may be gitignored, untracked, or absent from staged and unstaged diffs. Read the actual files through bounded, source-first access:
@@ -90,9 +92,10 @@ For an initial plan or explicit full-list rewrite, regenerate through the existi
90
92
  python3 ${SKILL_DIR}/scripts/validate-and-generate.py generate --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
91
93
  ```
92
94
 
93
- 5. Re-run append/generation until valid. Do not hand-patch `.prizmkit/plans/feature-list.json` as the source of truth.
95
+ 5. Re-run append/generation until valid. Do not hand-patch `.prizmkit/plans/feature-list.json` as the source of truth and do not add a user approval round for the mechanical rewrite.
94
96
  6. Repeat the local review and Headless Context Completeness Gate only for entries changed by accepted fixes.
95
97
  7. Do not report `PASS` until every required fresh-session answer is available and final validation passes after regeneration.
98
+ 8. After `PASS`, delete `.prizmkit/plans/feature-list.draft.json` before final handoff when it is an ordinary internal draft. Retain it only for explicit draft-save, interruption or blocking before the terminal gates, or cleanup failure; report the retained path and reason. Cleanup failure leaves the reviewed final list valid but must be reported as stale recovery state.
96
99
 
97
100
  ## Report Format
98
101
 
@@ -102,4 +105,5 @@ Report in the final handoff summary:
102
105
  - Reviewed feature IDs and reviewed root prose (`project_description` / `global_context`) when applicable
103
106
  - Accepted fixes, or `none`
104
107
  - Final validation result
108
+ - Draft cleanup result: `removed`, or retained path and recovery reason
105
109
  - Note when review was not applicable because no new final planning content was written
@@ -81,7 +81,7 @@ The additions-only `.prizmkit/plans/feature-list.draft.json` has exactly one roo
81
81
  }
82
82
  ```
83
83
 
84
- Each item uses the unchanged final feature-item schema. Required draft fields are `id`, `title`, `description`, `priority`, `dependencies`, and `acceptance_criteria`; `status` may be omitted and defaults to `pending`; all existing optional feature fields remain allowed. Root project metadata and historical features must not be copied into this draft.
84
+ Each item uses the unchanged final feature-item schema. Required draft fields are `id`, `title`, `description`, `priority`, `dependencies`, and `acceptance_criteria`; `status` may be omitted and defaults to `pending`; all existing optional feature fields remain allowed. Root project metadata and historical features must not be copied into this draft. Treat it as internal transport/recovery state, not as a user approval artifact.
85
85
 
86
86
  ### Step 4: Rebalance Priority
87
87
 
@@ -89,13 +89,13 @@ Default to append only. Reprioritizing historical tasks is an explicit old-task
89
89
 
90
90
  ### Step 5: Append and Validate
91
91
 
92
- Merge the additions-only draft with untouched history outside AI context:
92
+ After consequential decisions and the pre-generation semantic gate pass, immediately merge the additions-only draft with untouched history outside AI context:
93
93
 
94
94
  ```bash
95
95
  python3 ${SKILL_DIR}/scripts/validate-and-generate.py append --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
96
96
  ```
97
97
 
98
- The append command validates the existing base, exact sequential new IDs, all old/new dependencies, and the complete DAG before atomically replacing the final list. Fix the additions draft and rerun until valid. Use `generate` only for an initial plan or an explicit full-list rewrite.
98
+ The append command validates the existing base, exact sequential new IDs, all old/new dependencies, and the complete DAG before atomically replacing the final list. Do not ask for separate user approval merely to promote the additions draft into the final list. Fix invalid additions and rerun until valid; during local review, correct the exact current suffix with `append --replace-tail`. Keep the draft through that fix loop. After review returns `PASS` and final validation passes, delete the ordinary internal draft before final handoff. For a later adjustment, recreate only the exact current additions from confirmed in-memory entries or explicit-ID `show` results before using `append --replace-tail`. Use `generate` only for an initial plan or an explicit full-list rewrite.
99
99
 
100
100
  ## Merge/Rewrite Rules
101
101
 
@@ -120,6 +120,8 @@ Use concise prompts during interaction:
120
120
  - [ ] Any incorporated history is minimum, contract-affecting, and task-scoped
121
121
  - [ ] Old dependency IDs represent real execution prerequisites
122
122
  - [ ] Additions-only draft contains no root metadata or historical features
123
+ - [ ] Atomic append ran immediately after semantic gates without a post-draft approval pause
123
124
  - [ ] Existing project conventions preserved from project evidence
124
125
  - [ ] Complete merged dependency graph validates through `append`
126
+ - [ ] Ordinary internal draft was deleted after review and final validation, or its retained recovery path and reason were reported
125
127
  - [ ] Next step recommendation: `feature-pipeline-launcher`
@@ -53,12 +53,14 @@ Split into `sub_features` when:
53
53
 
54
54
  ### Phase 6: Generate + Validate
55
55
 
56
- 1. Write `.prizmkit/plans/feature-list.draft.json`.
57
- 2. Generate the final file:
56
+ 1. Write `.prizmkit/plans/feature-list.draft.json` as internal writer/review input after the main Skill's consequential decision and pre-generation gates pass.
57
+ 2. Immediately generate the final file without a separate draft-approval pause:
58
58
  ```bash
59
59
  python3 ${SKILL_DIR}/scripts/validate-and-generate.py generate --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
60
60
  ```
61
- 3. Fix draft errors, then re-run generate.
61
+ 3. Fix draft errors, then re-run `generate` until validation passes.
62
+ 4. Run the main Skill's mandatory Local Generated-Plan Review and apply accepted fixes through the complete draft.
63
+ 5. After review returns `PASS` and final validation passes, delete the ordinary internal draft before final handoff. Retain it only under the main Skill's explicit recovery conditions and report the reason.
62
64
 
63
65
  ## Quality Rules
64
66
 
@@ -77,5 +79,6 @@ Split into `sub_features` when:
77
79
  - [ ] User confirmed initial feature scope
78
80
  - [ ] IDs are sequential
79
81
  - [ ] `status` initialized to `pending`
80
- - [ ] Validation passes
82
+ - [ ] Validation and Local Generated-Plan Review pass
83
+ - [ ] Ordinary internal draft was deleted, or its retained recovery path and reason were reported
81
84
  - [ ] Next step recommendation: `feature-pipeline-launcher`
@@ -74,11 +74,11 @@ Typos, pure formatting, small documentation edits, and other explicitly low-risk
74
74
  | `prizmkit-code-review` | Review, repair, verify, and converge on the supplied change. | `PASS` |
75
75
  | `prizmkit-test` | Test the supplied change with a consistent report/result pair. | `TEST_PASS` |
76
76
  | `prizmkit-retrospective` | Synchronize durable documentation or record no change. | `RETRO_COMPLETE` |
77
- | `prizmkit-committer` | Create a confirmed interactive commit or prepare an exact Runtime request. | `COMMITTED` or `COMMIT_REQUEST_READY` |
77
+ | `prizmkit-committer` | Automatically create a validated direct local commit, or explicitly prepare an exact Runtime request. | `COMMITTED` or `COMMIT_REQUEST_READY` |
78
78
 
79
79
  ### `prizmkit-workflow`
80
80
 
81
- Use for a one-entry formal requirement workflow. It coordinates all six lifecycle skills, preserves one `artifact_dir`, routes failures, and stops for commit confirmation. It handles exactly one requirement per invocation.
81
+ Use for a one-entry formal requirement workflow. It coordinates all six lifecycle skills, preserves one `artifact_dir`, routes failures, and continues through the validated local commit without another confirmation pause. It handles exactly one requirement per invocation.
82
82
 
83
83
  ### `prizmkit-init`
84
84
 
@@ -121,7 +121,7 @@ Automatic outer repair is limited to three rounds. The workflow stops with a res
121
121
 
122
122
  ## Commit and Deployment Boundary
123
123
 
124
- The active coordinator validates all required evidence before invoking `prizmkit-committer` with exact `evidence_paths` and any caller-state `excluded_paths`. Interactive use confirms and creates a local commit. Preparation use returns `COMMIT_REQUEST_READY` without Git mutation; the injected Prompt records its pending state and Python Runtime executes the request.
124
+ The active coordinator validates all required evidence before invoking `prizmkit-committer` with exact `evidence_paths` and, for direct execution, only the exact causal bookkeeping path whose finalization must follow the commit. Direct use automatically validates and creates a local commit without another confirmation. Explicit preparation use returns `COMMIT_REQUEST_READY` without Git mutation; the injected Prompt records its pending state and Python Runtime executes the request.
125
125
 
126
126
  Pushing to a remote is a separate explicit action. Deployment is always a separate invocation of `/prizmkit-deploy`.
127
127
 
@@ -139,7 +139,7 @@ Then:
139
139
  1. Optionally run /prizmkit-init when entering a project for the first time.
140
140
  2. Start a formal requirement with /prizmkit-plan.
141
141
  3. Continue through implement → code-review → test → retrospective → committer.
142
- 4. For interactive use, confirm the local commit when `/prizmkit-committer operation=interactive-commit` presents it; pipeline runtimes use preparation mode and execute Git themselves.
142
+ 4. Direct `/prizmkit-committer` use validates and creates the local commit automatically; pipeline runtimes keep using explicit preparation mode and execute Git themselves.
143
143
  5. Invoke /prizmkit-deploy separately when deployment or operations work is needed.
144
144
  ```
145
145
 
@@ -151,7 +151,7 @@ The toolkit does not promise universal automatic handoff, universal deployment a
151
151
 
152
152
  If the user says only "ship it", ask whether they mean:
153
153
 
154
- 1. Use `/prizmkit-committer operation=interactive-commit` for a user-confirmed local commit, or preparation mode when a Python pipeline runtime owns Git execution.
154
+ 1. Use `/prizmkit-committer operation=interactive-commit` for an automatically validated local commit, or preparation mode when a Python pipeline runtime owns Git execution.
155
155
  2. Deploy or operate the project with `/prizmkit-deploy`.
156
156
 
157
157
  Do not route an ambiguous "ship it" directly to either action.
@@ -1,14 +1,14 @@
1
1
  ---
2
2
  name: "prizmkit-committer"
3
- description: "Perform one commit stage for a caller-supplied final change. Either review, preview, confirm, and commit the complete Git-visible workspace interactively, or validate it and prepare a pathless Runtime commit request without Git mutation. Returns only commit-stage results. (project)"
3
+ description: "Perform one commit stage for a caller-supplied final change. By default, validate and automatically commit the complete Git-visible workspace locally without a confirmation pause. An explicit prepare-runtime-commit operation still writes the pathless Runtime request without Git mutation. Returns only commit-stage results. (project)"
4
4
  ---
5
5
 
6
6
  # PrizmKit Committer
7
7
 
8
- `/prizmkit-committer` handles one caller-supplied final workspace through one explicit operation:
8
+ `/prizmkit-committer` handles one caller-supplied final workspace through one commit operation:
9
9
 
10
- - `operation=interactive-commit`: inspect the complete Git-visible workspace, preview it, confirm it, stage it, commit it, and verify it locally.
11
- - `operation=prepare-runtime-commit`: validate the complete Git-visible workspace and write a pathless Runtime request without staging or committing.
10
+ - direct/default invocation or `operation=interactive-commit`: inspect the complete Git-visible workspace, report the validated candidate, then stage, commit, and verify it locally without asking for another confirmation;
11
+ - explicit `operation=prepare-runtime-commit`: validate the complete Git-visible workspace and write a pathless Runtime request without staging or committing.
12
12
 
13
13
  Remote publication is outside this Skill.
14
14
 
@@ -17,18 +17,18 @@ Remote publication is outside this Skill.
17
17
  | Parameter | Required | Description |
18
18
  |---|---|---|
19
19
  | `artifact_dir` | Yes | Exact caller-supplied artifact root for this commit stage. |
20
- | `operation` | Yes | `interactive-commit` or `prepare-runtime-commit`. |
20
+ | `operation` | No | Defaults to direct local commit. `interactive-commit` is the compatible explicit name for that behavior; `prepare-runtime-commit` must be supplied explicitly for request-only preparation. |
21
21
  | `evidence_paths` | Yes | Exact caller-supplied artifacts that establish final Review/Test/Retrospective readiness. |
22
- | `causal_bookkeeping_path` | Interactive conditional | The one exact caller-owned coordinator state whose truthful finalization must follow this commit. It cannot exclude ordinary content. |
22
+ | `causal_bookkeeping_path` | Direct-commit conditional | The one exact caller-owned coordinator state whose truthful finalization must follow this commit. It cannot exclude ordinary content. |
23
23
  | `request_path` | Preparation only | Must equal `{artifact_dir}/runtime-commit-request.json`. |
24
24
 
25
- There is no caller-supplied commit-path manifest, support-path admission record, or ownership classification. Do not discover another artifact root or infer the operation from provider, platform, prompt style, tracking policy, checkout cleanliness, or human availability.
25
+ There is no caller-supplied commit-path manifest, support-path admission record, or ownership classification. Do not discover another artifact root or choose preparation mode from provider, platform, prompt style, tracking policy, checkout cleanliness, or human availability. Reject any non-empty `operation` value other than `interactive-commit` or `prepare-runtime-commit`. Only explicit `operation=prepare-runtime-commit` selects request-only preparation; an omitted operation or `operation=interactive-commit` uses direct local commit.
26
26
 
27
27
  ## Stage Boundary
28
28
 
29
- This Skill owns only final-workspace inspection and its selected commit operation. It does not invoke another Skill or repair incorrect content.
29
+ This Skill owns only final-workspace inspection and its selected commit operation. It does not invoke another Skill or repair incorrect content. Each invocation creates at most one local commit and never amends, resets, merges, pushes, opens a pull request, deploys, or publishes.
30
30
 
31
- In preparation mode it must not stage, unstage, commit, amend, reset, merge, or push. It may write only the exact Runtime request after validation succeeds.
31
+ In preparation mode it must not stage, unstage, or commit. It may write only the exact Runtime request after validation succeeds.
32
32
 
33
33
  ## Complete Git-Visible Workspace
34
34
 
@@ -40,11 +40,11 @@ The candidate commit is the complete current Git-visible workspace:
40
40
 
41
41
  Ignored files remain naturally absent, stay local, do not block, and are never force-added. Git visibility is independent of path provenance: product, test, documentation, `.prizmkit`, generated, instruction, lock, host-support, or previously existing content receives no namespace-based admission or exclusion. A non-clean starting checkout is acceptable when the combined final workspace is correct and fully validated.
42
42
 
43
- The only non-final Git-visible content that may remain outside a commit snapshot is exact active coordinator/Runtime bookkeeping whose final mutation cannot truthfully precede the commit: one validated caller-supplied interactive coordinator-state path, or the automated request/checkpoint and post-commit receipt. This is a causal operation boundary, not a directory allowlist, denylist, or general exclusion mechanism.
43
+ The only non-final Git-visible content that may remain outside a commit snapshot is exact active coordinator/Runtime bookkeeping whose final mutation cannot truthfully precede the commit: one validated caller-supplied direct-commit coordinator-state path, or the automated request/checkpoint and post-commit receipt. This is a causal operation boundary, not a directory allowlist, denylist, or general exclusion mechanism.
44
44
 
45
45
  ## Step 1: Validate Evidence and the Complete Final Workspace
46
46
 
47
- 1. Resolve `artifact_dir`, every `evidence_paths` entry, the optional interactive `causal_bookkeeping_path`, and preparation `request_path` exactly as supplied. Reject any causal path not proven to be the active caller-owned coordinator state finalized after this operation.
47
+ 1. Resolve `artifact_dir`, every `evidence_paths` entry, the optional direct-commit `causal_bookkeeping_path`, and preparation `request_path` exactly as supplied. Reject any causal path not proven to be the active caller-owned coordinator state finalized after this operation.
48
48
  2. Reject missing, unreadable, stale, contradictory, blocked, or explicitly non-passing readiness evidence.
49
49
  3. Inventory staged, unstaged, untracked, deleted, renamed, and copied Git-visible files with bounded Git status and diff commands. Do not discover ignored files. Identify only the exact active causal bookkeeping path for the selected operation; every other visible path remains a candidate.
50
50
  4. Inspect every candidate path and its relevant diff/content. Correct pre-existing or requirement-adjacent changes may be included even when they were not created in the current implementation session.
@@ -65,19 +65,16 @@ Generate one concise single-line Conventional Commit message describing the comb
65
65
 
66
66
  A heterogeneous but coherent workspace may use the narrowest truthful shared scope and description. If no truthful single commit description exists, block as incoherent content rather than silently omit files.
67
67
 
68
- ## Step 3A: Interactive Commit
68
+ ## Step 3A: Direct Local Commit
69
69
 
70
- For `operation=interactive-commit`:
70
+ For a default/direct invocation or `operation=interactive-commit`:
71
71
 
72
- 1. Present the complete Git-visible candidate set, the exact validated interactive causal bookkeeping path retained locally when visible, change summary, diff statistics, sensitive-content result, proposed message, and a clear statement that confirmation covers every candidate while ignored files stay local.
73
- 2. Ask the current user to confirm that complete local commit.
74
- 3. If the workspace changes after preview, repeat whole-workspace validation and preview before using the confirmation.
75
- 4. Only after confirmation, stage the complete workspace with ordinary `git add -A -- .` semantics, then reset only the validated `causal_bookkeeping_path` in the index to `HEAD` when it is Git-visible. Never force-add ignored content or accept any other exclusion.
76
- 5. Verify that the staged paths equal the in-memory confirmed candidate set, no non-ignored unstaged/untracked candidate remains outside the exact causal state, no incidental path appeared, and the staged snapshot still passes global sensitive-content checks.
77
- 6. Create the local commit and verify its hash, single parent, message, committed path set, and remaining Git-visible workspace against the confirmed snapshot.
78
- 7. Return `COMMITTED`, commit hash/message, committed paths, and any remaining ignored or causal bookkeeping content that is intentionally local.
79
-
80
- If confirmation is declined, return `COMMIT_DECLINED` without Git mutation.
72
+ 1. Report the complete Git-visible candidate set, the exact validated causal bookkeeping path retained locally when visible, change summary, diff statistics, sensitive-content result, proposed message, and that every candidate will be committed while ignored files stay local. This is an informational report, not a confirmation gate.
73
+ 2. Immediately before Git mutation, repeat the bounded whole-workspace status, evidence-freshness, merge-state, and sensitive-content checks. If the workspace changed, rebuild the candidate and message and validate again; block when coherence or safety cannot be re-established. Never ask the user merely to continue the validated commit.
74
+ 3. Stage the complete workspace with ordinary `git add -A -- .` semantics, then reset only the validated `causal_bookkeeping_path` in the index to `HEAD` when it is Git-visible. Never force-add ignored content or accept any other exclusion.
75
+ 4. Verify that the staged paths equal the latest validated candidate set, no non-ignored unstaged/untracked candidate remains outside the exact causal state, no incidental path appeared, and the staged snapshot still passes global sensitive-content checks.
76
+ 5. Create the local commit and verify its hash, single parent, message, committed path set, and remaining Git-visible workspace against the validated snapshot.
77
+ 6. Return `COMMITTED`, commit hash/message, committed paths, and any remaining ignored or causal bookkeeping content that is intentionally local.
81
78
 
82
79
  ## Step 3B: Runtime Commit Request
83
80
 
@@ -110,10 +107,10 @@ Schema version 1 path-manifest requests are not silently reinterpreted as worksp
110
107
 
111
108
  ## Output
112
109
 
113
- Interactive operation returns exactly one of:
110
+ Direct/default and `interactive-commit` operations return exactly one of:
114
111
 
115
112
  ```text
116
- COMMITTED | COMMIT_DECLINED | COMMIT_BLOCKED
113
+ COMMITTED | COMMIT_BLOCKED
117
114
  ```
118
115
 
119
116
  Preparation operation returns exactly one of:
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: "prizmkit-workflow"
3
- description: "Coordinate one explicitly requested formal software requirement through the complete PrizmKit lifecycle from plan to confirmed commit. Use when the user invokes prizmkit-workflow or explicitly asks for the full six-stage lifecycle, a plan-to-commit workflow, or one formal requirement completed end to end. Do not trigger on generic build, implement, feature, bug, or refactor requests; those belong to the applicable individual skill or an external integration. (project)"
3
+ description: "Coordinate one explicitly requested formal software requirement through the complete PrizmKit lifecycle from plan to verified local commit. Use when the user invokes prizmkit-workflow or explicitly asks for the full six-stage lifecycle, a plan-to-commit workflow, or one formal requirement completed end to end. Do not trigger on generic build, implement, feature, bug, or refactor requests; those belong to the applicable individual skill or an external integration. (project)"
4
4
  ---
5
5
 
6
6
  # PrizmKit Workflow
@@ -98,7 +98,7 @@ Expected transitions:
98
98
  | `prizmkit-code-review` | `PASS` plus valid `review-report.md` | `prizmkit-test` |
99
99
  | `prizmkit-test` | `TEST_PASS` plus a consistent report/result pair with `production_changed=false` | `prizmkit-retrospective` |
100
100
  | `prizmkit-retrospective` | `RETRO_COMPLETE` plus an artifact whose `outcome` and `result` agree | `prizmkit-committer` |
101
- | `prizmkit-committer` | `COMMITTED` after explicit interactive confirmation | end |
101
+ | `prizmkit-committer` | `COMMITTED` after automatic direct-commit validation and verification | end |
102
102
 
103
103
  Before accepting a Test transition, require `production_changed` to be a boolean and agree between `test-report.md` and `test-result.json`. A passing result with `production_changed=true` follows the bounded production-repair route below and is not final Test authority for Retrospective.
104
104
 
@@ -115,7 +115,7 @@ The composite must not:
115
115
  - claim tests passed without a consistent `test-report.md` and terminal `test-result.json`;
116
116
  - reinterpret testing-domain results as runtime/session outcomes;
117
117
  - perform retrospective documentation changes itself;
118
- - stage or commit before `prizmkit-committer` completes the interactive preview and confirmation boundary;
118
+ - stage or commit before `prizmkit-committer` completes final-workspace validation and enters its direct-commit boundary;
119
119
  - invoke `prizmkit-deploy` as a hidden seventh stage.
120
120
 
121
121
  ## Failure and Repair Routing
@@ -207,15 +207,15 @@ When the limit is reached:
207
207
 
208
208
  The internal `prizmkit-code-review` limit of ten completed review rounds remains separate and does not increment `repair_round`.
209
209
 
210
- ## Interactive Commit Boundary
210
+ ## Automatic Local Commit Boundary
211
211
 
212
- The composite reaches `/prizmkit-committer operation=interactive-commit` but must not silently create a Git commit.
212
+ The composite reaches `/prizmkit-committer operation=interactive-commit`, which automatically creates the validated local commit without another user-confirmation pause.
213
213
 
214
214
  The composite must validate all prior stage artifacts, derive exact non-`.prizmkit/` source-change paths for retrospective input, and validate its result. Code Review and Test must have treated the complete behavior-affecting Git-visible workspace as their final scope, including correct changes that predated this implementation session or live in framework, generated, instruction, lock, or host-support namespaces. If production behavior changes after those final gates, re-enter Review/Test rather than carrying stale authority into Committer.
215
215
 
216
- Invoke Committer with the same `artifact_dir`, exact `evidence_paths`, `operation=interactive-commit`, and `causal_bookkeeping_path` equal to this workflow's exact state path. Do not assemble or pass `intended_paths`, support-path admission records, namespace classifications, or ordinary content exclusions. Committer inventories and validates the complete current Git-visible workspace, presents all of it with one truthful message, waits for confirmation, and stages and creates the complete commit only after approval. A non-clean starting checkout is not a blocker when the combined final content is correct and validated.
216
+ Invoke Committer with the same `artifact_dir`, exact `evidence_paths`, `operation=interactive-commit`, and `causal_bookkeeping_path` equal to this workflow's exact state path. Do not assemble or pass `intended_paths`, support-path admission records, namespace classifications, or ordinary content exclusions. Committer inventories and validates the complete current Git-visible workspace, reports the candidate and message, revalidates immediately before mutation, and then stages, creates, and verifies the local commit without asking the user to continue. A non-clean starting checkout is not a blocker when the combined final content is correct and validated.
217
217
 
218
- Ignored paths remain naturally absent, stay local, and never block or require force-add. Global Secret, sensitive-content, merge-state, evidence-freshness, and content-correctness checks apply to every Git-visible candidate without provenance exceptions. The exact `.prizmkit/state/workflows/<requirement-identity>.json` remains local during the interactive commit because this coordinator must finalize it after Committer returns. Exact active Runtime request/checkpoint and post-commit receipt writes follow the same causal rule in automation; no broader or caller-selected exclusion is allowed.
218
+ Ignored paths remain naturally absent, stay local, and never block or require force-add. Global Secret, sensitive-content, merge-state, evidence-freshness, and content-correctness checks apply to every Git-visible candidate without provenance exceptions. The exact `.prizmkit/state/workflows/<requirement-identity>.json` remains local during the direct commit because this coordinator must finalize it after Committer returns. Exact active Runtime request/checkpoint and post-commit receipt writes follow the same causal rule in automation; no broader or caller-selected exclusion is allowed.
219
219
 
220
220
  External headless orchestration supplies explicit readiness evidence to `operation=prepare-runtime-commit`, maps `COMMIT_REQUEST_READY` to its own pending state, and lets Python Runtime validate and execute the schema-v2 pathless request. Runtime commits the complete validated Git-visible workspace with only exact causal bookkeeping omitted, then verifies Git and finalizes `COMMITTED`. Remote publication remains separate.
221
221
 
@@ -268,7 +268,7 @@ push: not performed automatically
268
268
  next_action: invoke /prizmkit-deploy separately if deployment is needed
269
269
  ```
270
270
 
271
- If the user declines interactive commit confirmation, preserve the committer stage as pending or in progress without a workflow `stage_result`, report the atomic operation result `COMMIT_DECLINED`, and provide the exact `/prizmkit-committer operation=interactive-commit` resume entry. `COMMIT_PENDING` is reserved for a validated Runtime commit request and must not represent an interactive decline.
271
+ There is no confirmation-decline state for direct local commit. If Committer returns `COMMIT_BLOCKED`, preserve the committer stage as incomplete with the exact safety, evidence, coherence, or Git blocker and the `/prizmkit-committer operation=interactive-commit` resume entry. `COMMIT_PENDING` remains reserved for a validated Runtime commit request.
272
272
 
273
273
  If blocked, report:
274
274
 
@@ -104,7 +104,7 @@ retrospective outcome=RETRO_COMPLETE, result=DOCS_UPDATED → status=completed
104
104
  retrospective outcome=RETRO_COMPLETE, result=NO_DOC_CHANGE → status=completed, stage_result=RETRO_COMPLETE
105
105
  retrospective outcome=RETRO_BLOCKED → status=failed, stage_result=RETRO_BLOCKED
106
106
  runtime commit preparation → status=in_progress, stage_result=COMMIT_PENDING
107
- local commit confirmed → status=completed, stage_result=COMMITTED
107
+ local commit verified → status=completed, stage_result=COMMITTED
108
108
  commit blocked → status=failed, stage_result=COMMIT_BLOCKED
109
109
  ```
110
110
 
@@ -155,18 +155,18 @@ Any outer repair or continuation policy is independently owned by the caller and
155
155
 
156
156
  ## Commit Execution Ownership
157
157
 
158
- Interactive execution:
158
+ Direct local commit execution:
159
159
 
160
160
  ```text
161
161
  coordinator validates final Review, Test, and Retrospective authority for the complete behavior-affecting Git-visible workspace
162
162
  → committer inventories and inspects the complete current Git-visible workspace without caller-supplied paths
163
163
  → committer applies global correctness, freshness, merge-state, and Secret checks
164
- → committer previews every visible change and one truthful message
165
- → waits for explicit current-user confirmation
164
+ → committer reports every visible change and one truthful message without pausing for confirmation
165
+ → committer revalidates immediately before mutation
166
166
  → stages the complete workspace, creates, and verifies the local commit
167
167
  ```
168
168
 
169
- Git visibility, validated final content, and confirmation determine commit scope; path provenance does not. Correct changes may predate the active requirement or live under `.prizmkit/**`, generated, instruction, lock, or host-support namespaces. Ignored files remain absent, stay local, never block, and are never force-added. If behavior-affecting content appears after final Review/Test, the evidence is stale and the workflow re-enters those gates. Sensitive, conflicted, incorrect, incoherent, unreadable, or unverifiable content blocks on its actual state rather than an unknown-path category. The exact active workflow-state path derived from the artifact basename remains outside the interactive snapshot only because the coordinator finalizes it after Committer returns; it is not a general framework exclusion.
169
+ Git visibility and validated final content determine commit scope; path provenance does not. Correct changes may predate the active requirement or live under `.prizmkit/**`, generated, instruction, lock, or host-support namespaces. Ignored files remain absent, stay local, never block, and are never force-added. If behavior-affecting content appears after final Review/Test, the evidence is stale and the workflow re-enters those gates. Sensitive, conflicted, incorrect, incoherent, unreadable, or unverifiable content blocks on its actual state rather than an unknown-path category. The exact active workflow-state path derived from the artifact basename remains outside the direct-commit snapshot only because the coordinator finalizes it after Committer returns; it is not a general framework exclusion.
170
170
 
171
171
  Pipeline execution:
172
172
 
@@ -44,7 +44,7 @@ The user chose this skill intentionally. Respect that choice.
44
44
 
45
45
  **Your ONLY writable outputs are:**
46
46
  1. `.prizmkit/plans/refactor-list.json` (`.prizmkit/plans/`)
47
- 2. Draft backups in `.prizmkit/plans/` (e.g., `refactor-list.draft.json`)
47
+ 2. Planner-owned draft state in `.prizmkit/plans/` (e.g., `refactor-list.draft.json`) while it is required for deterministic writing, review repair, or explicit recovery
48
48
 
49
49
  **After planning is complete**, you MUST:
50
50
  1. Present the summary and recommended next step
@@ -54,6 +54,10 @@ The user chose this skill intentionally. Respect that choice.
54
54
  5. **NEVER auto-execute** the pipeline, launcher, composite workflow, or any implementation step
55
55
  6. Return the validated refactor list to the caller; only `refactor-pipeline-launcher` prepares the runtime command
56
56
 
57
+ ## Draft Lifecycle (Hard Rule)
58
+
59
+ In an ordinary successful flow, `.prizmkit/plans/refactor-list.draft.json` is internal writer/review input, not a user approval artifact or separate deliverable. Keep it through `generate`/`append`, validation, and the complete Local Generated-Plan Review fix loop. After the Local Generated-Plan Review returns `PASS` and final validation passes, delete the ordinary internal draft before final handoff. Report `Draft cleanup: removed`. Present the final written result only after cleanup succeeds or a retained recovery reason is surfaced. Retain the draft only for explicit draft-save, interruption or blocking before terminal gates, or cleanup failure; report its path and reason. Cleanup failure does not invalidate an already reviewed and validated final list, but makes the file stale recovery state. Never delete explicit recovery state merely because an older valid final exists. For later adjustments, recreate only the minimum source draft from confirmed in-memory entries or exact-ID `show`; ordinary appends must preserve the exact current suffix and use `append --replace-tail` without loading unrelated history.
60
+
57
61
  ## Fresh-Session Task Contract (Hard Rule)
58
62
 
59
63
  Every new or changed refactor item is an executable contract for a fresh AI session that has never seen the planning conversation. Do not add new JSON fields, context objects, schema versions, or pipeline runtime structures. Use the existing fields correctly:
@@ -168,12 +172,12 @@ For any flow that appends to an existing `.prizmkit/plans/refactor-list.json`, N
168
172
  ```bash
169
173
  python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py show --input .prizmkit/plans/refactor-list.json --id R-NNN
170
174
  ```
171
- 5. For append-only planning, write `.prizmkit/plans/refactor-list.draft.json` as an additions-only object with exactly one root field, `refactors`. The array must be non-empty; each item uses the unchanged final refactor-item schema, with required `id`, `title`, `description`, `scope`, `type`, `priority`, `complexity`, `behavior_preservation`, `dependencies`, and `acceptance_criteria`; `status` may be omitted and defaults to `pending`; all existing optional refactor fields remain allowed. Do not copy root metadata or historical refactors into this draft.
172
- 6. Merge and validate outside AI context:
175
+ 5. For append-only planning, write `.prizmkit/plans/refactor-list.draft.json` as an additions-only object with exactly one root field, `refactors`. The array must be non-empty; each item uses the unchanged final refactor-item schema, with required `id`, `title`, `description`, `scope`, `type`, `priority`, `complexity`, `behavior_preservation`, `dependencies`, and `acceptance_criteria`; `status` may be omitted and defaults to `pending`; all existing optional refactor fields remain allowed. Do not copy root metadata or historical refactors into this bounded internal transport/recovery state.
176
+ 6. After consequential decisions and the pre-generation gate pass, immediately run `append` outside AI context:
173
177
  ```bash
174
178
  python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py append --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
175
179
  ```
176
- The command validates the existing base, sequential new IDs, dependencies, and the complete DAG before atomically replacing the final list. Existing `generate` behavior remains the full-draft path for a new list and explicit full-list rewrites.
180
+ Do not ask for separate user approval merely to promote the draft into the final list. The command validates the base, IDs, dependencies, and complete DAG before atomic replacement. Apply review fixes only to the bounded additions and rerun `append --replace-tail` for the exact current suffix, then follow §Draft Lifecycle before presenting the final written result. Existing `generate` remains the new-list/full-rewrite path.
177
181
 
178
182
  ## Operation Modes
179
183
 
@@ -315,8 +319,8 @@ See `${SKILL_DIR}/references/planning-phases.md` for the full 5-step review chec
315
319
  **Goal**: Produce `.prizmkit/plans/refactor-list.json` and validate it.
316
320
 
317
321
  **IMPORTANT: Do NOT hand-write the final JSON file.** Instead:
318
- 1. For a new list, write the complete `.prizmkit/plans/refactor-list.draft.json`. For an existing list, follow §Bounded Existing-List Context and write only the additions-only `refactors` object.
319
- 2. Use the matching deterministic writer:
322
+ 1. For a new list, write the complete `.prizmkit/plans/refactor-list.draft.json`. For an existing list, follow §Bounded Existing-List Context and write only the additions-only `refactors` object as internal transport/recovery state.
323
+ 2. Once required semantic gates pass, immediately use the matching deterministic writer without a second draft-approval pause:
320
324
  - New list or explicit full-list rewrite:
321
325
  ```bash
322
326
  python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py generate --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
@@ -327,12 +331,13 @@ See `${SKILL_DIR}/references/planning-phases.md` for the full 5-step review chec
327
331
  ```
328
332
  `generate` fills root defaults for a complete draft. `append` preserves root metadata and historical refactors, defaults missing new statuses, and writes only after the merged full list validates.
329
333
  3. If validation fails -> fix the draft and retry (max 3 attempts)
330
- 4. If validation passes -> run the mandatory Local Generated-Plan Review Gate (see §Local Generated-Plan Review Gate below); apply accepted fixes to the draft/source plan, regenerate, and revalidate until pass
331
- 5. If review and validation pass -> present final summary
334
+ 4. If validation passes -> run the mandatory Local Generated-Plan Review Gate (see §Local Generated-Plan Review Gate below); apply accepted fixes to the draft/source plan, use `append --replace-tail` for ordinary appended entries, and revalidate until pass
335
+ 5. If review and validation pass -> delete the ordinary internal draft under §Draft Lifecycle; retain and report it only for an explicit recovery condition or cleanup failure
336
+ 6. Present the final written result, summary, and draft cleanup result. For later user adjustments, recreate the minimum source draft from confirmed in-memory entries or exact-ID `show`, then rerun `generate` for a new-list rewrite or `append --replace-tail` for ordinary appended entries
332
337
 
333
338
  **CHECKPOINT CP-RP-6**: `.prizmkit/plans/refactor-list.json` generated and validated.
334
339
 
335
- **CHECKPOINT CP-RP-7**: Local generated-plan review loaded `${SKILL_DIR}/references/generated-plan-review.md`, reviewed only newly added/changed refactor entries, applied accepted fixes through draft/source data, regenerated, and revalidated.
340
+ **CHECKPOINT CP-RP-7**: Local generated-plan review loaded `${SKILL_DIR}/references/generated-plan-review.md`, reviewed only newly added/changed refactor entries, applied accepted fixes through draft/source data, regenerated, revalidated, and completed terminal draft cleanup or reported why recovery state was retained.
336
341
 
337
342
  ## Checkpoints (Mandatory Gates)
338
343
 
@@ -345,13 +350,13 @@ See `${SKILL_DIR}/references/planning-phases.md` for the full 5-step review chec
345
350
  | **CP-RP-4** | Items Confirmed | User confirmed/modified/skipped each item | 5 |
346
351
  | **CP-RP-5** | Completeness OK | DAG valid, preservation strategies declared, no gaps | 6 |
347
352
  | **CP-RP-6** | Output Valid | `.prizmkit/plans/refactor-list.json` passes validation script | 7 |
348
- | **CP-RP-7** | Local Plan Review Passed | Local generated-plan review loaded `${SKILL_DIR}/references/generated-plan-review.md`, reviewed only newly added/changed refactor entries, applied accepted fixes through draft/source data, regenerated, and revalidated | 7 |
353
+ | **CP-RP-7** | Local Plan Review Passed | Local generated-plan review loaded `${SKILL_DIR}/references/generated-plan-review.md`, reviewed only newly added/changed refactor entries, applied accepted fixes through draft/source data, regenerated, revalidated, and completed terminal draft cleanup or reported why recovery state was retained | 7 |
349
354
 
350
355
  ## Local Generated-Plan Review Gate
351
356
 
352
357
  Run this gate after `.prizmkit/plans/refactor-list.json` passes generation and validation, and before the final handoff. It applies whenever this session added or changed final refactor entries. For validate-only, summary-only, or draft-save flows with no final content change, report that the gate is not applicable.
353
358
 
354
- Read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the single source of truth. Review the actual additions-only draft and use bounded `context` plus explicit-ID `show` for new or changed final entries because `.prizmkit` files may be gitignored; do not load unchanged historical entries. Repeat the Headless Context Completeness Gate for every reviewed new or changed refactor. Keep the review planning-only, apply accepted findings to the draft/source representation, regenerate the final JSON, rerun validation, and repeat local review until it returns `PASS` before reporting the result.
359
+ Read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the single source of truth. Review the actual additions-only draft and use bounded `context` plus explicit-ID `show` for new or changed final entries because `.prizmkit` files may be gitignored; do not load unchanged historical entries. Repeat the Headless Context Completeness Gate for every reviewed new or changed refactor. Keep the review planning-only, apply accepted findings to the draft/source representation, update ordinary appended entries through `append --replace-tail`, rerun validation, and repeat local review until it returns `PASS`. Complete §Draft Lifecycle cleanup before reporting the final written result.
355
360
 
356
361
  ## Output Rules
357
362
 
@@ -460,4 +465,5 @@ After successful validation and the Local Generated-Plan Review Gate, report:
460
465
  3. Dependency ordering highlights (which items must run first)
461
466
  4. Behavior preservation strategy distribution (N items with test-gate, M with snapshot, etc.)
462
467
  5. Local generated-plan review result: verdict, reviewed refactor IDs plus reviewed root prose when applicable, accepted fixes (or "none"), and final validation result
463
- 6. Recommended next action: `refactor-pipeline-launcher`
468
+ 6. Draft cleanup result: `removed`, or retained path and recovery reason
469
+ 7. Recommended next action: `refactor-pipeline-launcher`
@@ -4,8 +4,8 @@ Load this reference when validation fails, the planning session is interrupted,
4
4
 
5
5
  ## Validation Recovery
6
6
 
7
- - Warnings only: present the warnings and ask whether to continue.
8
- - Validation errors: group related errors, correct the planning draft, and regenerate. Limit automatic correction to three attempts before asking the user how to proceed.
7
+ - Warnings only: present them and continue when informational. Ask the user only when a warning exposes a consequential architecture, scope, behavior-preservation, or verification decision; do not add a generic draft-promotion approval.
8
+ - Validation errors: group related errors, apply unambiguous mechanical corrections to the planning draft, and rerun the matching writer. Ask before semantic corrections, and limit automatic correction to three attempts before retaining the draft and asking the user how to proceed.
9
9
  - Keep `.prizmkit/plans/refactor-list.json` at the project-root `.prizmkit/plans/` path.
10
10
  - Do not alter source code or run project tests while recovering a planning artifact.
11
11
 
@@ -14,11 +14,12 @@ Load this reference when validation fails, the planning session is interrupted,
14
14
  | Artifact Found | Resume Point |
15
15
  |---|---|
16
16
  | No planning artifact | Phase 1: Project Context |
17
- | Draft in `.prizmkit/plans/` | Phase matching the draft's completeness |
18
- | Incomplete final refactor list | Phase 6: Completeness Review |
19
- | Valid final refactor list | Mode D: Summary |
17
+ | Draft only in `.prizmkit/plans/` | Phase matching the draft's actual completeness |
18
+ | Incomplete final refactor list | Resume writer/validation repair through the source draft |
19
+ | Valid final refactor list only | Mode D: Summary or a new bounded append |
20
+ | Valid final plus draft | Treat as interrupted review or cleanup-failure state; inspect and offer resume review, discard, or a new append rather than assuming either artifact wins |
20
21
 
21
- Read the artifact directly because `.prizmkit` content may be gitignored. Preserve existing valid entries and resume only the unfinished planning work.
22
+ Read the artifacts directly because `.prizmkit` content may be gitignored. Preserve existing valid entries and resume only unfinished planning work. When final and draft both exist and available evidence cannot distinguish interrupted review from cleanup failure, ask the user before deleting or promoting the draft.
22
23
 
23
24
  ## Session Exit Gate
24
25
 
@@ -31,7 +32,14 @@ Activate the exit gate when all of these are true:
31
32
  Use `AskUserQuestion` with these options:
32
33
 
33
34
  - **Continue to completion (Recommended)** — resume from the detected planning phase.
34
- - **Save draft and exit** — save current planning content as `.prizmkit/plans/refactor-list.draft.json`.
35
+ - **Save draft and exit** — save current planning content as `.prizmkit/plans/refactor-list.draft.json` and retain it as explicit recovery state.
35
36
  - **Abandon** — exit without saving new planning content.
36
37
 
37
- When saving a draft, state clearly that it is not validated and can be resumed by running `refactor-planner` again.
38
+ When saving a draft, state clearly that it is not validated and can be resumed by running `refactor-planner` again. Terminal cleanup does not apply until resumed planning completes.
39
+
40
+ ## Draft Management
41
+
42
+ - Keep an ordinary writer draft through generation/append, validation, and the complete Local Generated-Plan Review fix loop.
43
+ - After Local Generated-Plan Review returns `PASS` and final validation passes, delete the ordinary internal draft before handoff.
44
+ - Retain a draft only for explicit **Save draft and exit**, interruption or blocking before terminal gates, or cleanup failure. Report its path and reason.
45
+ - Cleanup failure does not invalidate a reviewed and validated final list, but the retained file is stale recovery state and must be surfaced.
@@ -31,12 +31,13 @@ For simple refactoring with minimal scope.
31
31
  **NEVER proceed without explicit user selection via `AskUserQuestion`. Do NOT render options as plain text — the user must be able to click/select.**
32
32
  3. Draft items (title + type + scope + description + acceptance_criteria + behavior_preservation + dependencies)
33
33
  4. Run the mandatory Phase 6 Headless Context Completeness Gate on every drafted item; repair the draft until each returns `PASS` without conversation history or `user_context`.
34
- 5. Write `.prizmkit/plans/refactor-list.draft.json`. For a new list, use the complete final-list draft and `generate`; for an existing list, write only the additions-only `refactors` object and call:
34
+ 5. Write `.prizmkit/plans/refactor-list.draft.json` as internal transport/recovery state. For a new list, use the complete final-list draft and `generate`; for an existing list, write only the additions-only `refactors` object and immediately call `append` without a second draft-approval pause:
35
35
  ```bash
36
36
  python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py append --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
37
37
  ```
38
- 6. If valid -> run the mandatory Local Generated-Plan Review Gate from the main `refactor-planner` skill before summarizing or recommending `refactor-pipeline-launcher`.
39
- 7. If invalid -> apply fixes to the draft and re-run the same writer (`generate` for a new list, `append` for an existing list; max 2 attempts, then escalate to full workflow)
38
+ 6. If valid -> run the mandatory Local Generated-Plan Review Gate from the main `refactor-planner` skill. After review returns `PASS` and final validation passes, delete the ordinary internal draft under the main Skill's Draft Lifecycle, then present the final written result before recommending `refactor-pipeline-launcher`.
39
+ 7. For a later adjustment after cleanup, recreate only the minimum source draft from confirmed in-memory entries or exact-ID `show`, then rerun `generate` for a new-list rewrite or `append --replace-tail` for an ordinary append.
40
+ 8. If invalid -> apply fixes to the draft and re-run the same writer (`generate` for a new list, `append` for an existing list; max 2 attempts, then escalate to full workflow)
40
41
 
41
42
  ## When NOT to Use Fast Path
42
43
  - More than 2 refactor items
@@ -6,6 +6,8 @@ Use this local review loop after `.prizmkit/plans/refactor-list.json` has been g
6
6
 
7
7
  Run only when the current `refactor-planner` session generated, appended, or rewrote final refactor planning content. For validate-only, summary-only, or draft-save flows with no new final planning content, report: `Local generated-plan review: not applicable — no new final planning content written.`
8
8
 
9
+ In ordinary incremental flow, the additions draft is internal transport/recovery state. After consequential decisions and the pre-generation gate pass, immediately run `append`; do not ask for separate user approval merely to promote the draft into the final list. Keep the draft through the bounded review/fix loop, then delete the ordinary internal draft before final handoff only after this review returns `PASS` and final validation passes.
10
+
9
11
  ## Direct Artifact Reads
10
12
 
11
13
  Planning artifacts may be gitignored, untracked, or absent from staged and unstaged diffs. Read the actual files through bounded, source-first access:
@@ -89,9 +91,10 @@ For a new list or explicit full-list rewrite, regenerate through the existing sc
89
91
  python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py generate --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
90
92
  ```
91
93
 
92
- 5. Re-run append/generation until valid. Do not hand-patch `.prizmkit/plans/refactor-list.json` as the source of truth.
94
+ 5. Re-run append/generation until valid. Do not hand-patch `.prizmkit/plans/refactor-list.json` as the source of truth and do not add a user approval round for the mechanical rewrite.
93
95
  6. Repeat the local review and Headless Context Completeness Gate only for entries changed by accepted fixes.
94
96
  7. Do not report `PASS` until every required fresh-session answer is available and final validation passes after regeneration.
97
+ 8. After `PASS`, delete `.prizmkit/plans/refactor-list.draft.json` before final handoff when it is an ordinary internal draft. Retain it only for explicit draft-save, interruption or blocking before the terminal gates, or cleanup failure; report the retained path and reason. Cleanup failure leaves the reviewed final list valid but must be reported as stale recovery state.
95
98
 
96
99
  ## Report Format
97
100
 
@@ -101,4 +104,5 @@ Report in the final handoff summary:
101
104
  - Reviewed refactor IDs and reviewed root prose (`project_description` / `global_context`) when applicable
102
105
  - Accepted fixes, or `none`
103
106
  - Final validation result
107
+ - Draft cleanup result: `removed`, or retained path and recovery reason
104
108
  - Note when review was not applicable because no new final planning content was written
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "prizmkit",
3
- "version": "1.1.175",
3
+ "version": "1.1.176",
4
4
  "description": "Create a new PrizmKit-powered project with clean initialization — no framework dev files, just what you need.",
5
5
  "type": "module",
6
6
  "bin": {