prizmkit 1.1.174 → 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.
Files changed (23) hide show
  1. package/bundled/VERSION.json +3 -3
  2. package/bundled/rules/prizm/prizm-commit-workflow.md +3 -3
  3. package/bundled/skills/_metadata.json +1 -1
  4. package/bundled/skills/bug-planner/SKILL.md +46 -43
  5. package/bundled/skills/bug-planner/references/error-recovery.md +24 -24
  6. package/bundled/skills/bug-planner/references/generated-plan-review.md +24 -11
  7. package/bundled/skills/bug-planner/scripts/validate-bug-list.py +216 -1
  8. package/bundled/skills/feature-planner/SKILL.md +39 -30
  9. package/bundled/skills/feature-planner/references/error-recovery.md +25 -15
  10. package/bundled/skills/feature-planner/references/generated-plan-review.md +24 -11
  11. package/bundled/skills/feature-planner/references/incremental-feature-planning.md +85 -70
  12. package/bundled/skills/feature-planner/references/new-project-planning.md +7 -4
  13. package/bundled/skills/feature-planner/scripts/validate-and-generate.py +213 -0
  14. package/bundled/skills/prizmkit/SKILL.md +5 -5
  15. package/bundled/skills/prizmkit-committer/SKILL.md +21 -24
  16. package/bundled/skills/prizmkit-workflow/SKILL.md +8 -8
  17. package/bundled/skills/prizmkit-workflow/references/workflow-state-protocol.md +5 -5
  18. package/bundled/skills/refactor-planner/SKILL.md +47 -14
  19. package/bundled/skills/refactor-planner/references/error-recovery.md +16 -8
  20. package/bundled/skills/refactor-planner/references/fast-path.md +6 -5
  21. package/bundled/skills/refactor-planner/references/generated-plan-review.md +24 -11
  22. package/bundled/skills/refactor-planner/scripts/validate-and-generate-refactor.py +213 -0
  23. package/package.json +1 -1
@@ -1,5 +1,5 @@
1
1
  {
2
- "frameworkVersion": "1.1.174",
3
- "bundledAt": "2026-08-08T02:37:10.579Z",
4
- "bundledFrom": "b12b5d8"
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.174",
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:
@@ -155,6 +159,14 @@ This skill handles multiple operations. Determine the user's intent and dispatch
155
159
  | Validate existing bug list | **Operation: Validate** |
156
160
  | Summarize bug list | **Operation: Summary** |
157
161
 
162
+ ## Bounded Existing-List Context (Hard Rule)
163
+ For any content-generating flow that appends to an existing `.prizmkit/plans/bug-fix-list.json`, NEVER read the complete historical list into AI context and NEVER perform default full-history keyword search.
164
+ 1. Run `python3 ${SKILL_DIR}/scripts/validate-bug-list.py context --input .prizmkit/plans/bug-fix-list.json`; consume only `project_name`, `project_description`, `global_context`, `task_count`, `next_id`, and the five most recently appended top-level bugs as `{id, description}` pairs (or all available bugs when fewer than five exist).
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.
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.
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`.
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.
158
170
  ## Scenario Routing
159
171
 
160
172
  Classify user intent first:
@@ -172,10 +184,10 @@ Actions:
172
184
  Use when `.prizmkit/plans/bug-fix-list.json` already exists and user wants to add more bugs.
173
185
 
174
186
  Actions:
175
- 1. Read existing `.prizmkit/plans/bug-fix-list.json` first (if missing, ask whether to start new plan)
176
- 2. Continue with next sequential `B-NNN` IDs
177
- 3. Preserve existing entries, append new bugs
178
- 4. Re-run validation on the merged list
187
+ 1. Run the bounded `context` command from §Bounded Existing-List Context (if the file is missing, ask whether to start a new plan); do not read the complete list
188
+ 2. Continue with the returned next sequential `B-NNN` ID
189
+ 3. Write only new bugs to the additions-only draft and merge through `append`
190
+ 4. Preserve existing entries and validate the complete merged list outside AI context
179
191
 
180
192
  ---
181
193
 
@@ -311,46 +323,44 @@ Return `NEEDS_FIXES` whenever any answer is missing, ambiguous, or available onl
311
323
 
312
324
  **Step 4 — Present review table**: Display the completeness assessment using the template in `${SKILL_DIR}/assets/bug-confirmation-template.md` (§Completeness Review Template).
313
325
 
314
- 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:
315
327
 
316
328
  > "Above is the completeness review. Every `NEEDS_FIXES` item must be clarified before generation. Which flagged item should we address first?"
317
329
 
318
- 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.
319
331
 
320
332
  **Gate → CP-BP-4**: All new or changed bugs pass the Headless Context Completeness Gate without relying on conversation history or `user_context`.
321
333
 
322
334
  ### Phase 5: Generate & Validate
323
335
 
324
- 1. **Write draft JSON**: Write a draft `.prizmkit/plans/bug-fix-list.draft.json` with all collected bug data. Conform to `.prizmkit/dev-pipeline/templates/bug-fix-list-schema.json`.
325
- 2. **Generate and validate**: Run the generate script to validate and produce the final file:
326
- ```bash
327
- python3 ${SKILL_DIR}/scripts/validate-bug-list.py generate --input .prizmkit/plans/bug-fix-list.draft.json --output .prizmkit/plans/bug-fix-list.json
328
- ```
329
- The script fills in defaults (`$schema`, `created_at`, `created_by`), validates all fields, and writes the final file only if validation passes.
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:
338
+ - New list or explicit full-list rewrite:
339
+ ```bash
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
341
+ ```
342
+ - Ordinary existing-list append:
343
+ ```bash
344
+ python3 ${SKILL_DIR}/scripts/validate-bug-list.py append --input .prizmkit/plans/bug-fix-list.draft.json --output .prizmkit/plans/bug-fix-list.json
345
+ ```
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.
330
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`.
331
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.
332
- 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.
333
350
 
334
351
  **Gate → CP-BP-5**: `bug-fix-list.json` passes validation script with zero errors.
335
352
 
336
- **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.
337
354
 
338
355
  ## Local Generated-Plan Review Gate
339
356
 
340
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.
341
358
 
342
- Read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the single source of truth. Review the actual draft and final artifacts directly because `.prizmkit` files may be gitignored. 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.
343
360
 
344
361
  #### Success Output
345
362
 
346
- ```
347
- .prizmkit/plans/bug-fix-list.json generated with 3 bugs (1 critical, 1 medium, 1 low)
348
- Local generated-plan review: PASS, reviewed B-001..B-003, accepted fixes: none, final validation: PASS
349
-
350
- Next steps:
351
- - Review: cat .prizmkit/plans/bug-fix-list.json
352
- - Start fixing: say "start fixing" to launch the bugfix pipeline via bugfix-pipeline-launcher
353
- ```
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.
354
364
 
355
365
  ### Checkpoints (Mandatory Gates)
356
366
 
@@ -363,7 +373,7 @@ Checkpoints catch cascading errors early — skipping one means the next phase b
363
373
  | **CP-BP-3** | Priorities Set | Severity/priority assigned, duplicates resolved | 3 |
364
374
  | **CP-BP-4** | Completeness Passed | All bugs pass headless execution readiness check | 4 |
365
375
  | **CP-BP-5** | File Generated | `bug-fix-list.json` passes validation script | 5 |
366
- | **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 |
367
377
 
368
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.
369
379
 
@@ -373,7 +383,7 @@ Checkpoints catch cascading errors early — skipping one means the next phase b
373
383
 
374
384
  Triggers: "parse this error log", "here's a stack trace", "parse these errors".
375
385
 
376
- 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:
377
387
 
378
388
  1. Accept log file path or piped content
379
389
  2. Parse all unique errors (deduplicate by error message pattern)
@@ -384,14 +394,10 @@ Batch-parse error logs with minimal interaction: parse automatically, then requi
384
394
  - error_source: populated from log content
385
395
  - verification_type: default to `automated`
386
396
  - acceptance_criteria: auto-generate "Error no longer occurs in [scenario]"
387
- 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.
388
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.
389
- 6. Ask: "Review and confirm? You can edit individual entries."
390
- 7. After user confirms, call the generate script:
391
- ```bash
392
- python3 ${SKILL_DIR}/scripts/validate-bug-list.py generate --input .prizmkit/plans/bug-fix-list.draft.json --output .prizmkit/plans/bug-fix-list.json
393
- ```
394
- 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`.
395
401
 
396
402
  ## Operation: From Tests
397
403
 
@@ -403,14 +409,10 @@ Batch-parse failed test output:
403
409
  2. Parse each failed test case as a separate bug entry
404
410
  3. Auto-populate `failed_test_path`, `error_message`
405
411
  4. Set verification_type to `automated` (test already exists)
406
- 5. Write draft to `.prizmkit/plans/bug-fix-list.draft.json`
407
- 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.
408
- 7. Present parsed failed-test bug entries for confirmation; allow edits, merges, or removals
409
- 8. After user confirms, call the generate script:
410
- ```bash
411
- python3 ${SKILL_DIR}/scripts/validate-bug-list.py generate --input .prizmkit/plans/bug-fix-list.draft.json --output .prizmkit/plans/bug-fix-list.json
412
- ```
413
- 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`.
414
416
 
415
417
  ## Operation: Validate
416
418
 
@@ -463,8 +465,9 @@ Recommend invoking `bugfix-pipeline-launcher` to configure and launch the pipeli
463
465
  After `.prizmkit/plans/bug-fix-list.json` is generated, validated, and reviewed, present:
464
466
  1. Summary of generated bugs (count, severity breakdown)
465
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
466
- 3. Recommend: "Say 'start fixing' to launch the bugfix pipeline via `bugfix-pipeline-launcher`"
467
- 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`
468
471
 
469
472
  ## Error Handling
470
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,24 +6,27 @@ 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
- Planning artifacts may be gitignored, untracked, or absent from staged and unstaged diffs. Read the actual files directly:
13
+ Planning artifacts may be gitignored, untracked, or absent from staged and unstaged diffs. Read the actual files through bounded, source-first access:
12
14
 
13
- - Final list: `.prizmkit/plans/bug-fix-list.json`
14
- - Draft/source list when present: `.prizmkit/plans/bug-fix-list.draft.json`
15
- - Pre-session final list snapshot if captured in memory before edits
15
+ - Final list: `.prizmkit/plans/bug-fix-list.json` — run the `context` command for root prose and recent IDs; do not load the complete historical list into AI context
16
+ - Draft/source list when present: `.prizmkit/plans/bug-fix-list.draft.json` — ordinary incremental flow contains only additions and may be read completely
17
+ - Pre-session final list snapshot if captured in memory before edits — retain only bounded root context, prior task count/next ID, and the five recent `{id, description}` pairs, not full history
16
18
  - In-memory draft object if the session has not written a draft file yet
19
+ - Newly appended or explicitly modified final entries — load each known ID with `python3 ${SKILL_DIR}/scripts/validate-bug-list.py show --input .prizmkit/plans/bug-fix-list.json --id B-NNN`
17
20
 
18
21
  Do not rely on `git status`, `git diff`, or `git diff --cached` to decide whether planner output exists or changed. Do not invoke `/prizmkit-code-review` for this planner-output gate; `/prizmkit-code-review` remains the implementation/code-diff review gate after `/prizmkit-implement`.
19
22
 
20
23
  ## Review Scope
21
24
 
22
- 1. If a pre-session final list exists, compare by stable bug IDs (`B-*`).
23
- 2. Root project prose is reviewable content, not generator metadata. Review new or changed `project_description` and `global_context` even when no bug item changed. Ignore root generator metadata and formatting-only differences such as `$schema`, `created_at`, and `created_by`.
24
- 3. Treat bugs as changed only when item fields changed; review newly added bug IDs and changed bug IDs.
25
- 4. Preserve unchanged historical bugs. Read unchanged entries only when needed to verify dependency references, duplicate handling, or root-cause overlap with reviewed bugs.
26
- 5. If no snapshot exists, review all bug entries produced by the current generation flow.
25
+ 1. For ordinary append flow, use the additions-only draft and the append result's stable bug IDs (`B-*`) as the change set; do not compare complete pre/post historical arrays in AI context.
26
+ 2. Root project prose is reviewable content, not generator metadata. Read it through `context`; review new or changed `project_description` and `global_context` even when no bug item changed. Ignore root generator metadata and formatting-only differences such as `$schema`, `created_at`, and `created_by`.
27
+ 3. Treat bugs as changed only when item fields changed; load and review newly added bug IDs and explicitly changed bug IDs through `show`.
28
+ 4. Preserve unchanged historical bugs. Do not load unchanged entries merely to establish review completeness. Use the full-list validator for dependency/DAG truth; use `show` for an old dependency or overlap only when a specific reviewed bug requires semantic inspection.
29
+ 5. If no snapshot exists during initial generation, review all entries in that session's complete draft. Absence of a snapshot never authorizes loading unrelated history during append flow.
27
30
 
28
31
  ## Review Checklist
29
32
 
@@ -74,15 +77,24 @@ Do not add new JSON fields, context objects, schema versions, or pipeline runtim
74
77
  1. Present findings with IDs, severity, evidence, and suggested draft/source changes.
75
78
  2. Accept only findings that improve planner correctness, completeness, or downstream bug-fix execution readiness.
76
79
  3. Apply accepted fixes to `.prizmkit/plans/bug-fix-list.draft.json` or the in-memory draft object first.
77
- 4. Regenerate the final list through the existing generator:
80
+ 4. For an ordinary incremental additions-only draft, rerun the existing script's append command:
81
+
82
+ ```bash
83
+ python3 ${SKILL_DIR}/scripts/validate-bug-list.py append --input .prizmkit/plans/bug-fix-list.draft.json --output .prizmkit/plans/bug-fix-list.json --replace-tail
84
+ ```
85
+
86
+ `--replace-tail` is allowed only for the exact final-list suffix whose IDs match this session's additions, so accepted local-review fixes replace the current session's entries without duplicating or loading history. If the suffix does not match exactly, stop rather than rewriting another task.
87
+
88
+ For a new list or explicit full-list rewrite, regenerate through the existing script's complete-draft command:
78
89
 
79
90
  ```bash
80
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
81
92
  ```
82
93
 
83
- 5. Re-run validation/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.
84
95
  6. Repeat the local review and Headless Context Completeness Gate only for entries changed by accepted fixes.
85
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.
86
98
 
87
99
  ## Report Format
88
100
 
@@ -92,4 +104,5 @@ Report in the final handoff summary:
92
104
  - Reviewed bug IDs and reviewed root prose (`project_description` / `global_context`) when applicable
93
105
  - Accepted fixes, or `none`
94
106
  - Final validation result
107
+ - Draft cleanup result: `removed`, or retained path and recovery reason
95
108
  - Note when review was not applicable because no new final planning content was written