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,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:
@@ -142,7 +146,7 @@ Before questions, check optional context files (never block if absent):
142
146
  - `.prizmkit/prizm-docs/root.prizm` (architecture/project context)
143
147
  - `.prizmkit/config.json` (existing stack preferences and detected tech stack)
144
148
  - Existing test suite (critical for behavior preservation assessment)
145
- - Existing `.prizmkit/plans/refactor-list.json` (if appending additional items)
149
+ - Existing `.prizmkit/plans/refactor-list.json` (if appending additional items; inspect it only through the bounded commands below)
146
150
  - If `.prizmkit/prizm-docs/root.prizm` is absent and the project has existing source code, scan the directory structure:
147
151
  ```bash
148
152
  find . -maxdepth 2 -type d -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/__pycache__/*' -not -path '*/vendor/*' | sed -e 's;[^/]*/;|____;g;s;____|; |;g'
@@ -153,6 +157,28 @@ Before questions, check optional context files (never block if absent):
153
157
  - If no test suite detected, WARN: "No test suite found. Behavior preservation will rely on manual verification. Consider writing tests before refactoring."
154
158
  - Record test suite status in planning context for downstream use
155
159
 
160
+ ## Bounded Existing-List Context (Hard Rule)
161
+
162
+ For any flow that appends to an existing `.prizmkit/plans/refactor-list.json`, NEVER read the complete historical list into AI context and NEVER perform default full-history keyword search.
163
+
164
+ 1. Load only bounded project and recent-task context:
165
+ ```bash
166
+ python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py context --input .prizmkit/plans/refactor-list.json
167
+ ```
168
+ Consume only `project_name`, `project_description`, `global_context`, `task_count`, `next_id`, and exactly the five most recently appended top-level refactors as `{id, description}` pairs (or all available refactors when fewer than five exist).
169
+ 2. Inspect those five 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.
170
+ 3. When a material relationship exists, incorporate only the minimum exact information whose omission would make the new refactor's scope, behavior preservation, compatibility, acceptance criteria, or dependency ordering incorrect. Do not write vague text such as `related to R-123`, do not copy an entire historical description merely because it overlaps, and add an old ID to `dependencies` only when it is a real execution prerequisite.
171
+ 4. Load a complete historical refactor only when the user explicitly identifies its ID for modification or detailed review, or a validation error identifies it:
172
+ ```bash
173
+ python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py show --input .prizmkit/plans/refactor-list.json --id R-NNN
174
+ ```
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:
177
+ ```bash
178
+ python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py append --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
179
+ ```
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.
181
+
156
182
  ## Operation Modes
157
183
 
158
184
  ### Mode A: Interactive (default)
@@ -293,19 +319,25 @@ See `${SKILL_DIR}/references/planning-phases.md` for the full 5-step review chec
293
319
  **Goal**: Produce `.prizmkit/plans/refactor-list.json` and validate it.
294
320
 
295
321
  **IMPORTANT: Do NOT hand-write the final JSON file.** Instead:
296
- 1. Write a draft JSON to `.prizmkit/plans/refactor-list.draft.json` with all collected refactor data.
297
- 2. Call the generate script to validate and produce the final file:
298
- ```bash
299
- python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py generate --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
300
- ```
301
- The script fills in defaults (`$schema`, `created_at`, `created_by`), validates all fields, and writes the final file only if validation passes.
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:
324
+ - New list or explicit full-list rewrite:
325
+ ```bash
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
+ ```
328
+ - Ordinary existing-list append:
329
+ ```bash
330
+ python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py append --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
331
+ ```
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.
302
333
  3. If validation fails -> fix the draft and retry (max 3 attempts)
303
- 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
304
- 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
305
337
 
306
338
  **CHECKPOINT CP-RP-6**: `.prizmkit/plans/refactor-list.json` generated and validated.
307
339
 
308
- **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.
309
341
 
310
342
  ## Checkpoints (Mandatory Gates)
311
343
 
@@ -318,13 +350,13 @@ See `${SKILL_DIR}/references/planning-phases.md` for the full 5-step review chec
318
350
  | **CP-RP-4** | Items Confirmed | User confirmed/modified/skipped each item | 5 |
319
351
  | **CP-RP-5** | Completeness OK | DAG valid, preservation strategies declared, no gaps | 6 |
320
352
  | **CP-RP-6** | Output Valid | `.prizmkit/plans/refactor-list.json` passes validation script | 7 |
321
- | **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 |
322
354
 
323
355
  ## Local Generated-Plan Review Gate
324
356
 
325
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.
326
358
 
327
- 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 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.
328
360
 
329
361
  ## Output Rules
330
362
 
@@ -433,4 +465,5 @@ After successful validation and the Local Generated-Plan Review Gate, report:
433
465
  3. Dependency ordering highlights (which items must run first)
434
466
  4. Behavior preservation strategy distribution (N items with test-gate, M with snapshot, etc.)
435
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
436
- 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.
@@ -10,7 +10,7 @@ For simple refactoring with minimal scope.
10
10
  - Existing test coverage for target area
11
11
 
12
12
  ## Fast Path Workflow
13
- 1. Confirm refactoring scope with user
13
+ 1. If `.prizmkit/plans/refactor-list.json` exists, run the parent Skill's bounded `context` command and consume only root context plus the five recent `{id, description}` pairs; never read the complete historical list or perform default keyword search. Then confirm refactoring scope with the user.
14
14
  2. **User confirmation (mandatory)** — Use `AskUserQuestion` to present interactive selectable options:
15
15
 
16
16
  ```
@@ -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 draft to `.prizmkit/plans/refactor-list.draft.json`, then call the generate script:
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
- python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py generate --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
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, re-run generate (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,24 +6,27 @@ 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
- 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/refactor-list.json`
14
- - Draft/source list when present: `.prizmkit/plans/refactor-list.draft.json`
15
- - Pre-session final list snapshot if captured in memory before edits
15
+ - Final list: `.prizmkit/plans/refactor-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/refactor-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-and-generate-refactor.py show --input .prizmkit/plans/refactor-list.json --id R-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 refactor IDs (`R-*`).
23
- 2. Root project prose is reviewable content, not generator metadata. Review new or changed `project_description` and `global_context` even when no refactor item changed. Ignore root generator metadata and formatting-only differences such as `$schema`, `created_at`, and `created_by`.
24
- 3. Treat refactors as changed only when item fields changed; review newly added refactor IDs and changed refactor IDs.
25
- 4. Preserve unchanged historical refactors. Read unchanged entries only when needed to verify dependency references or behavior-preservation interactions with reviewed refactors.
26
- 5. If no snapshot exists, review all refactor entries produced by the current generation flow.
25
+ 1. For ordinary append flow, use the additions-only draft and the append result's stable refactor IDs (`R-*`) 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 refactor item changed. Ignore root generator metadata and formatting-only differences such as `$schema`, `created_at`, and `created_by`.
27
+ 3. Treat refactors as changed only when item fields changed; load and review newly added refactor IDs and explicitly changed refactor IDs through `show`.
28
+ 4. Preserve unchanged historical refactors. 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 behavior-preservation interaction only when a specific reviewed refactor 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 behavior-preserving execution readiness.
76
79
  3. Apply accepted fixes to `.prizmkit/plans/refactor-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-and-generate-refactor.py append --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-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-and-generate-refactor.py generate --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
81
92
  ```
82
93
 
83
- 5. Re-run validation/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.
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/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.
86
98
 
87
99
  ## Report Format
88
100
 
@@ -92,4 +104,5 @@ Report in the final handoff summary:
92
104
  - Reviewed refactor 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