prizmkit 1.1.188 → 1.1.190

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.
@@ -54,14 +54,14 @@ Split into additional top-level features only when:
54
54
 
55
55
  ### Phase 6: Generate + Validate
56
56
 
57
- 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.
58
- 2. Immediately generate the final file without a separate draft-approval pause:
57
+ 1. Write `.prizmkit/plans/feature-list.draft.json` as the private review workspace after the main Skill's consequential decision and pre-generation gates pass.
58
+ 2. Run the main Skill's mandatory Local Generated-Plan Review against that complete draft and apply accepted fixes through the draft. Nothing is written to `feature-list.json` yet.
59
+ 3. After review returns `PASS`, generate the final file once without a separate draft-approval pause:
59
60
  ```bash
60
61
  python3 ${SKILL_DIR}/scripts/validate-and-generate.py generate --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
61
62
  ```
62
- 3. Fix draft errors, then re-run `generate` until validation passes.
63
- 4. Run the main Skill's mandatory Local Generated-Plan Review and apply accepted fixes through the complete draft.
64
- 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.
63
+ 4. If `generate` rejects the draft, fix the draft and retry; a rejection writes no file, so the final list is never partial.
64
+ 5. After the single successful `generate`, delete the draft and report `Draft cleanup: removed`. Retain it only under the main Skill's explicit recovery conditions and report the reason.
65
65
 
66
66
  ## Quality Rules
67
67
 
@@ -80,6 +80,6 @@ Split into additional top-level features only when:
80
80
  - [ ] User confirmed initial feature scope
81
81
  - [ ] IDs are sequential
82
82
  - [ ] `status` initialized to `pending`
83
- - [ ] Validation and Local Generated-Plan Review pass
84
- - [ ] Ordinary internal draft was deleted, or its retained recovery path and reason were reported
83
+ - [ ] Validation and Local Generated-Plan Review passed on the draft, then exactly one `generate` ran
84
+ - [ ] Ordinary internal draft was deleted after that single insert, or its retained recovery path and reason were reported
85
85
  - [ ] Next step recommendation: `feature-pipeline-launcher`
@@ -19,6 +19,7 @@ Usage:
19
19
  python3 validate-and-generate.py context --input .prizmkit/plans/feature-list.json
20
20
  python3 validate-and-generate.py show --input .prizmkit/plans/feature-list.json --id F-001
21
21
  python3 validate-and-generate.py append --input additions.json --output .prizmkit/plans/feature-list.json
22
+ python3 validate-and-generate.py append --input additions.json --output .prizmkit/plans/feature-list.json --dry-run
22
23
  python3 validate-and-generate.py generate --input draft.json --output .prizmkit/plans/feature-list.json
23
24
  python3 validate-and-generate.py summary --input .prizmkit/plans/feature-list.json [--format markdown|json]
24
25
  python3 validate-and-generate.py grade --workspace /.codebuddy/skill-evals/feature-planner-workspace --iteration iteration-1
@@ -837,6 +838,11 @@ def cmd_append(args):
837
838
  _err(" " + error)
838
839
  return 1
839
840
 
841
+ if getattr(args, "dry_run", False):
842
+ _info("Dry run: {} feature(s) would be appended to {}".format(
843
+ len(prepared), args.output))
844
+ return 0
845
+
840
846
  try:
841
847
  _write_json_atomic(args.output, merged)
842
848
  except Exception as exc:
@@ -1113,6 +1119,11 @@ def main():
1113
1119
  action="store_true",
1114
1120
  help="Replace the exact existing suffix with the same IDs after local review",
1115
1121
  )
1122
+ p_append.add_argument(
1123
+ "--dry-run",
1124
+ action="store_true",
1125
+ help="Validate the would-be merged list without writing it",
1126
+ )
1116
1127
 
1117
1128
  # -- generate --
1118
1129
  p_generate = subparsers.add_parser(
@@ -56,7 +56,7 @@ The user chose this skill intentionally. Respect that choice.
56
56
 
57
57
  ## Draft Lifecycle (Hard Rule)
58
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.
59
+ In an ordinary successful flow, `.prizmkit/plans/refactor-list.draft.json` is a private reasoning workspace: never presented as a deliverable, never given its own approval round, never retained after the batch lands. Build the batch there, validate it there, and run the entire Local Generated-Plan Review against it; the final list is written exactly once, after that review returns `PASS`, by a single `append` (existing list) or `generate` (new list). Then delete the draft immediately and report `Draft cleanup: removed`. A batch lost before it lands is regenerated from the confirmed decisions rather than recovered. Conditions that must keep a draft — explicit draft-save, interruption, a writer-rejected insert, cleanup failure — are defined in `${SKILL_DIR}/references/error-recovery.md`, and any retained path is named in the terminal report. For later adjustments, recreate only the minimum source draft from confirmed in-memory entries or exact-ID `show`; modifying entries this session did not create is the one case that still uses `append --replace-tail` for the exact current suffix.
60
60
 
61
61
  ## Fresh-Session Task Contract (Hard Rule)
62
62
 
@@ -172,12 +172,12 @@ For any flow that appends to an existing `.prizmkit/plans/refactor-list.json`, N
172
172
  ```bash
173
173
  python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py show --input .prizmkit/plans/refactor-list.json --id R-NNN
174
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:
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 private reasoning workspace, which is the review target rather than a deliverable.
176
+ 6. After consequential decisions and the pre-generation gate pass, write the batch to the additions-only draft with the `context` IDs and check merge feasibility without writing:
177
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
178
+ python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py append --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json --dry-run
179
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.
180
+ Do not ask for separate user approval merely to promote the draft into the final list. The dry run applies the same base, exact-ID, dependency, and complete-DAG checks the real insert will, so a `PASS` review is a promise the insert keeps. Run the real `append` once, after §Local Generated-Plan Review Gate returns `PASS`, then follow §Draft Lifecycle. Existing `generate` remains the new-list/full-rewrite path.
181
181
 
182
182
  ## Operation Modes
183
183
 
@@ -319,25 +319,22 @@ See `${SKILL_DIR}/references/planning-phases.md` for the full 5-step review chec
319
319
  **Goal**: Produce `.prizmkit/plans/refactor-list.json` and validate it.
320
320
 
321
321
  **IMPORTANT: Do NOT hand-write the final JSON file.** Instead:
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
- ```
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. The draft is the review target, so nothing is written to the final list yet.
323
+ 2. Once required semantic gates pass, check merge feasibility without a second draft-approval pause:
324
+ - New list or explicit full-list rewrite: the draft is complete and nothing exists to overwrite, so its post-review `generate` is the validator.
328
325
  - Ordinary existing-list append:
329
326
  ```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
327
+ python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py append --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json --dry-run
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
+ The dry run applies the same base, exact-ID, dependency, and complete-DAG checks the real insert will, including `append`'s preservation of root metadata and historical refactors.
333
330
  3. If validation fails -> fix the draft and retry (max 3 attempts)
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
331
+ 4. If the draft and dry run pass -> run the mandatory Local Generated-Plan Review Gate (see §Local Generated-Plan Review Gate below) on the draft; apply accepted fixes to the draft and revalidate until `PASS`
332
+ 5. After `PASS` -> insert exactly once (`append`, or `generate` for a new list), confirm its `appended_ids`, and delete the draft under §Draft Lifecycle
336
333
  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
337
334
 
338
- **CHECKPOINT CP-RP-6**: `.prizmkit/plans/refactor-list.json` generated and validated.
335
+ **CHECKPOINT CP-RP-6**: The draft batch validates and its merge dry run returns zero errors; the final list is still untouched.
339
336
 
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.
337
+ **CHECKPOINT CP-RP-7**: Local generated-plan review loaded `${SKILL_DIR}/references/generated-plan-review.md`, reviewed only the draft batch, applied accepted fixes through the draft, revalidated, returned `PASS`, then ran exactly one insert whose `appended_ids` match the batch and removed the draft.
341
338
 
342
339
  ## Checkpoints (Mandatory Gates)
343
340
 
@@ -349,14 +346,14 @@ See `${SKILL_DIR}/references/planning-phases.md` for the full 5-step review chec
349
346
  | **CP-RP-3** | Items Decomposed | All items have deps, complexity, preservation strategy | 4 |
350
347
  | **CP-RP-4** | Items Confirmed | User confirmed/modified/skipped each item | 5 |
351
348
  | **CP-RP-5** | Completeness OK | DAG valid, preservation strategies declared, no gaps | 6 |
352
- | **CP-RP-6** | Output Valid | `.prizmkit/plans/refactor-list.json` passes validation script | 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
+ | **CP-RP-6** | Draft Batch Ready | Additions-only or complete draft holds the whole batch with `context` IDs; merge dry run clean; final list still untouched | 7 |
350
+ | **CP-RP-7** | Reviewed, Then Inserted Once | Local generated-plan review loaded `${SKILL_DIR}/references/generated-plan-review.md`, reviewed only the draft batch, applied accepted fixes through the draft, revalidated, returned `PASS`, then ran exactly one insert whose `appended_ids` match the batch, and removed the draft | 7 |
354
351
 
355
352
  ## Local Generated-Plan Review Gate
356
353
 
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.
354
+ Run this gate after the batch is written to the draft and passes draft validation, and before anything is written to `.prizmkit/plans/refactor-list.json`. The review target is the batch that is about to be inserted, not a file that already contains it. It applies whenever this session produced or changed a batch. For validate-only, summary-only, or draft-save flows with no batch, report that the gate is not applicable.
358
355
 
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.
356
+ Read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the single source of truth. Review the draft directly, reading `.prizmkit` artifacts from disk rather than from `git status` or `git diff`, because those files may be gitignored. Use bounded `context` and explicit-ID `show` only for already-committed entries whose contract or dependency semantics a reviewed item relies on; 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, re-run draft validation and the merge dry run, and repeat local review until it returns `PASS`. Only then insert once and complete §Draft Lifecycle cleanup before reporting the final written result. If the insert is rejected after `PASS`, nothing landed; fix the draft, re-run validation and the dry run, and re-review only the entries you changed.
360
357
 
361
358
  ## Output Rules
362
359
 
@@ -459,11 +456,12 @@ When validation fails, existing planning artifacts are detected, the session is
459
456
 
460
457
  ## Handoff Message Template
461
458
 
462
- After successful validation and the Local Generated-Plan Review Gate, report:
459
+ After the batch is inserted, report:
463
460
  1. Output file path
464
461
  2. Total refactor items
465
462
  3. Dependency ordering highlights (which items must run first)
466
463
  4. Behavior preservation strategy distribution (N items with test-gate, M with snapshot, etc.)
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
468
- 6. Draft cleanup result: `removed`, or retained path and recovery reason
469
- 7. Recommended next action: `refactor-pipeline-launcher`
464
+ 5. Local generated-plan review result: verdict, reviewed batch IDs plus reviewed root prose when applicable, and accepted fixes (or "none")
465
+ 6. Insert result: the single writer run and the `appended_ids` it reported
466
+ 7. Draft cleanup result: `removed`
467
+ 8. Recommended next action: `refactor-pipeline-launcher`
@@ -31,13 +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` 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:
34
+ 5. Write `.prizmkit/plans/refactor-list.draft.json` as the private review workspace. For a new list, write the complete final-list draft; for an existing list, write only the additions-only `refactors` object and check merge feasibility without writing, with no second draft-approval pause:
35
35
  ```bash
36
- python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py append --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 --dry-run
37
37
  ```
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`.
38
+ 6. If valid -> run the mandatory Local Generated-Plan Review Gate from the main `refactor-planner` skill against the draft. After review returns `PASS`, insert once (`append`, or `generate` for a new list), delete the draft under the main Skill's Draft Lifecycle, then present the final written result before recommending `refactor-pipeline-launcher`.
39
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
+ 8. If invalid -> apply fixes to the draft and re-run the dry run; a new list is validated by its post-`PASS` `generate`, which writes nothing when it rejects (max 2 attempts, then escalate to full workflow)
41
41
 
42
42
  ## When NOT to Use Fast Path
43
43
  - More than 2 refactor items
@@ -1,28 +1,28 @@
1
1
  # Generated Plan Review — Refactor Planner
2
2
 
3
- Use this local review loop after `.prizmkit/plans/refactor-list.json` has been generated and validated. This is a planner-output review, not an implementation/code-diff review.
3
+ Use this local review loop on the batch that is about to be inserted into `.prizmkit/plans/refactor-list.json`. This is a planner-output review, not an implementation/code-diff review, and it runs before the insert so the verdict decides whether the batch lands.
4
4
 
5
5
  ## Trigger
6
6
 
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.`
7
+ Run only when the current `refactor-planner` session produced a draft batch of new or changed refactors. For validate-only, summary-only, or draft-save flows with no new batch, report: `Local generated-plan review: not applicable — no new 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.
9
+ The draft is the whole review surface. Nothing is written to the final list while this loop runs: the single insert happens only after a `PASS`, so the verdict decides whether the batch lands and no final list ever holds reviewed-looking entries that were never reviewed.
10
10
 
11
11
  ## Direct Artifact Reads
12
12
 
13
13
  Planning artifacts may be gitignored, untracked, or absent from staged and unstaged diffs. Read the actual files through bounded, source-first access:
14
14
 
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
15
+ - Review target: `.prizmkit/plans/refactor-list.draft.json` — the additions-only or complete batch, read in full; this is the only planning content under review
16
+ - 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, and do not expect this session's batch to appear in it yet
17
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
18
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`
19
+ - Already-committed entries a reviewed item relies on — load each referenced ID with `python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py show --input .prizmkit/plans/refactor-list.json --id R-NNN`
20
20
 
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`.
21
+ Do not rely on `git status`, `git diff`, or `git diff --cached` to decide whether planner output exists or changed. If the final list already contains this session's batch, the insert ran before the verdict — report that instead of reviewing an already-landed batch. Do not invoke `/prizmkit-code-review` for this planner-output gate; `/prizmkit-code-review` remains the implementation/code-diff review gate after `/prizmkit-implement`.
22
22
 
23
23
  ## Review Scope
24
24
 
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.
25
+ 1. Treat the draft batch as the change set. Its `R-*` IDs are the sequential `context` IDs the writer demands at insert time, so the IDs reviewed are the IDs that land; do not compare complete pre/post historical arrays in AI context.
26
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
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
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.
@@ -48,6 +48,7 @@ For every reviewed refactor entry, check:
48
48
  - Priority/complexity calibration: every reviewed refactor has short priority and complexity rationales, medium/low assignments are allowed when criteria fit, and high/high is not used merely because the work is cleanup, framework-related, multi-file, or user-requested
49
49
  - Domain cohesion: same contract-bounded capability stays one top-level item; independently shippable is not a split reason; same-domain over-split is `NEEDS_FIXES` unless one existing headless session cannot finish
50
50
  - Injected-field fidelity: confirmed structure, scope, preservation, and completion evidence are in `description` and `acceptance_criteria`; AI rewrite is allowed; dropping a confirmed item is not
51
+ - Insert feasibility: every `dependencies` entry on a committed ID exists in the final list, the batch uses the consecutive IDs `context` reported, and the merge dry run returns `"valid": true`. Draft-only validation cannot see the merged graph, so a `PASS` without this check is a verdict the writer may reject.
51
52
  - Size: there is no word-count upper limit and no acceptance-criteria count upper limit
52
53
 
53
54
  ## Headless Context Completeness Gate
@@ -80,32 +81,27 @@ Do not add new JSON fields, context objects, schema versions, or pipeline runtim
80
81
  1. Present findings with IDs, severity, evidence, and suggested draft/source changes.
81
82
  2. Accept only findings that improve planner correctness, completeness, or downstream behavior-preserving execution readiness.
82
83
  3. Apply accepted fixes to `.prizmkit/plans/refactor-list.draft.json` or the in-memory draft object first.
83
- 4. For an ordinary incremental additions-only draft, rerun the existing script's append command:
84
+ 4. Re-check the fixed draft without writing:
84
85
 
85
86
  ```bash
86
- 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
87
+ python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py append --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json --dry-run
87
88
  ```
88
89
 
89
- `--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.
90
+ The dry run enforces the same base, exact-ID, dependency, and complete-DAG checks as the real insert, so keep it green instead of discovering a merge conflict after `PASS`. A new list or explicit full-list rewrite has no merged graph to check and nothing to overwrite, so its single post-`PASS` `generate` is the validator; if it rejects the draft, fix and retry, because no file was written.
90
91
 
91
- For a new list or explicit full-list rewrite, regenerate through the existing script's complete-draft command:
92
-
93
- ```bash
94
- python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py generate --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
95
- ```
96
-
97
- 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.
92
+ 5. Never hand-patch `.prizmkit/plans/refactor-list.json` as the source of truth and do not add a user approval round for the mechanical rewrite.
98
93
  6. Repeat the local review and Headless Context Completeness Gate only for entries changed by accepted fixes.
99
- 7. Do not report `PASS` until every required fresh-session answer is available and final validation passes after regeneration.
100
- 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.
94
+ 7. Do not report `PASS` until every required fresh-session answer is available and the draft validation plus merge dry run pass.
95
+ 8. After `PASS`, insert the batch exactly once (`append`, or `generate` for a new list), confirm the writer's `appended_ids`, then delete `.prizmkit/plans/refactor-list.draft.json`. Retain a draft only under the conditions in `${SKILL_DIR}/references/error-recovery.md`; report the retained path and reason.
101
96
 
102
97
  ## Report Format
103
98
 
104
99
  Report in the final handoff summary:
105
100
 
106
101
  - `Local generated-plan review: PASS` or `NEEDS_FIXES`
107
- - Reviewed refactor IDs and reviewed root prose (`project_description` / `global_context`) when applicable
102
+ - Reviewed batch IDs and reviewed root prose (`project_description` / `global_context`) when applicable
103
+ - Merge dry-run result
108
104
  - Accepted fixes, or `none`
109
- - Final validation result
105
+ - Insert result: the single writer run and the `appended_ids` it reported
110
106
  - Draft cleanup result: `removed`, or retained path and recovery reason
111
- - Note when review was not applicable because no new final planning content was written
107
+ - Note when review was not applicable because no new planning content was written
@@ -18,6 +18,7 @@ Usage:
18
18
  python3 validate-and-generate-refactor.py context --input .prizmkit/plans/refactor-list.json
19
19
  python3 validate-and-generate-refactor.py show --input .prizmkit/plans/refactor-list.json --id R-001
20
20
  python3 validate-and-generate-refactor.py append --input additions.json --output .prizmkit/plans/refactor-list.json
21
+ python3 validate-and-generate-refactor.py append --input additions.json --output .prizmkit/plans/refactor-list.json --dry-run
21
22
  python3 validate-and-generate-refactor.py generate --input draft.json --output .prizmkit/plans/refactor-list.json
22
23
  python3 validate-and-generate-refactor.py summary --input .prizmkit/plans/refactor-list.json [--format markdown|json]
23
24
 
@@ -888,6 +889,11 @@ def cmd_append(args):
888
889
  _err(" " + error)
889
890
  return 1
890
891
 
892
+ if getattr(args, "dry_run", False):
893
+ _info("Dry run: {} refactor(s) would be appended to {}".format(
894
+ len(prepared), args.output))
895
+ return 0
896
+
891
897
  try:
892
898
  _write_json_atomic(args.output, merged)
893
899
  except Exception as exc:
@@ -1053,6 +1059,11 @@ def main():
1053
1059
  action="store_true",
1054
1060
  help="Replace the exact existing suffix with the same IDs after local review",
1055
1061
  )
1062
+ p_append.add_argument(
1063
+ "--dry-run",
1064
+ action="store_true",
1065
+ help="Validate the would-be merged list without writing it",
1066
+ )
1056
1067
 
1057
1068
  # -- generate --
1058
1069
  p_generate = subparsers.add_parser(
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "prizmkit",
3
- "version": "1.1.188",
3
+ "version": "1.1.190",
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": {