prizmkit 1.1.189 → 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.
- package/bundled/VERSION.json +3 -3
- package/bundled/skills/_metadata.json +1 -1
- package/bundled/skills/bug-planner/SKILL.md +29 -31
- package/bundled/skills/bug-planner/references/generated-plan-review.md +19 -23
- package/bundled/skills/bug-planner/scripts/validate-bug-list.py +11 -0
- package/bundled/skills/feature-planner/SKILL.md +20 -20
- package/bundled/skills/feature-planner/references/generated-plan-review.md +19 -23
- package/bundled/skills/feature-planner/references/incremental-feature-planning.md +7 -7
- package/bundled/skills/feature-planner/references/new-project-planning.md +7 -7
- package/bundled/skills/feature-planner/scripts/validate-and-generate.py +11 -0
- package/bundled/skills/refactor-planner/SKILL.md +23 -25
- package/bundled/skills/refactor-planner/references/fast-path.md +4 -4
- package/bundled/skills/refactor-planner/references/generated-plan-review.md +19 -23
- package/bundled/skills/refactor-planner/scripts/validate-and-generate-refactor.py +11 -0
- package/package.json +1 -1
package/bundled/VERSION.json
CHANGED
|
@@ -51,7 +51,7 @@ After planning is complete, you MUST:
|
|
|
51
51
|
|
|
52
52
|
## Draft Lifecycle (Hard Rule)
|
|
53
53
|
|
|
54
|
-
In an ordinary successful flow, `.prizmkit/plans/bug-fix-list.draft.json` is
|
|
54
|
+
In an ordinary successful flow, `.prizmkit/plans/bug-fix-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.
|
|
55
55
|
|
|
56
56
|
## Fresh-Session Task Contract (Hard Rule)
|
|
57
57
|
|
|
@@ -165,8 +165,8 @@ For any content-generating flow that appends to an existing `.prizmkit/plans/bug
|
|
|
165
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
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
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
|
|
169
|
-
6. After consequential decisions and the pre-generation gate pass,
|
|
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 a private reasoning workspace and the review target, not a user approval artifact or a deliverable. 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, write the batch to the additions-only draft with the `context` IDs and check merge feasibility without writing: `python3 ${SKILL_DIR}/scripts/validate-bug-list.py append --input .prizmkit/plans/bug-fix-list.draft.json --output .prizmkit/plans/bug-fix-list.json --dry-run`. 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. `generate` remains the new-list/full-rewrite path.
|
|
170
170
|
## Scenario Routing
|
|
171
171
|
|
|
172
172
|
Classify user intent first:
|
|
@@ -333,34 +333,31 @@ For every `NEEDS_FIXES` result, ask only for the consequential missing decision,
|
|
|
333
333
|
|
|
334
334
|
### Phase 5: Generate & Validate
|
|
335
335
|
|
|
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
|
|
337
|
-
2. **
|
|
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
|
-
```
|
|
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. The draft is the review target, so nothing is written to the final list yet.
|
|
337
|
+
2. **Check merge feasibility without writing** — once required semantic gates pass, run the matching check without a second draft-approval pause:
|
|
338
|
+
- New list or explicit full-list rewrite: the draft is complete and nothing exists to overwrite, so its post-review `generate` is the validator.
|
|
342
339
|
- Ordinary existing-list append:
|
|
343
340
|
```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
|
|
341
|
+
python3 ${SKILL_DIR}/scripts/validate-bug-list.py append --input .prizmkit/plans/bug-fix-list.draft.json --output .prizmkit/plans/bug-fix-list.json --dry-run
|
|
345
342
|
```
|
|
346
|
-
|
|
343
|
+
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 bugs.
|
|
347
344
|
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`.
|
|
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
|
|
349
|
-
5. **
|
|
345
|
+
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 the draft batch before the insert.
|
|
346
|
+
5. **Insert once and output**: After local review returns `PASS`, run a single `append`/`generate`, confirm its `appended_ids`, follow §Draft Lifecycle, then report the file path, summary, local review, inserted IDs, validation, cleanup result, and next steps.
|
|
350
347
|
|
|
351
|
-
**Gate → CP-BP-5**:
|
|
348
|
+
**Gate → CP-BP-5**: The draft batch validates and its merge dry run returns zero errors; the final list is still untouched.
|
|
352
349
|
|
|
353
|
-
**Gate → CP-BP-6**: Local generated-plan review loaded `${SKILL_DIR}/references/generated-plan-review.md`, reviewed only
|
|
350
|
+
**Gate → CP-BP-6**: 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.
|
|
354
351
|
|
|
355
352
|
## Local Generated-Plan Review Gate
|
|
356
353
|
|
|
357
|
-
Run this gate after `.prizmkit/plans/bug-fix-list.json
|
|
354
|
+
Run this gate after the batch is written to the draft and passes draft validation, and before anything is written to `.prizmkit/plans/bug-fix-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
|
|
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 bug. 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
|
#### Success Output
|
|
362
359
|
|
|
363
|
-
Report the final path and bug counts, Local Generated-Plan Review verdict and reviewed IDs, accepted fixes,
|
|
360
|
+
Report the final path and bug counts, Local Generated-Plan Review verdict and reviewed batch IDs, accepted fixes, the single insert's `appended_ids` and validation result, draft cleanup result, and `bugfix-pipeline-launcher` handoff.
|
|
364
361
|
|
|
365
362
|
### Checkpoints (Mandatory Gates)
|
|
366
363
|
|
|
@@ -372,8 +369,8 @@ Checkpoints catch cascading errors early — skipping one means the next phase b
|
|
|
372
369
|
| **CP-BP-2** | Bugs Collected | All bugs extracted and confirmed by user | 2 |
|
|
373
370
|
| **CP-BP-3** | Priorities Set | Severity/priority assigned, duplicates resolved | 3 |
|
|
374
371
|
| **CP-BP-4** | Completeness Passed | All bugs pass headless execution readiness check | 4 |
|
|
375
|
-
| **CP-BP-5** |
|
|
376
|
-
| **CP-BP-6** |
|
|
372
|
+
| **CP-BP-5** | Draft Batch Ready | Additions-only or complete draft holds the whole batch with `context` IDs; merge dry run clean; final list still untouched | 5 |
|
|
373
|
+
| **CP-BP-6** | 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 | 5 |
|
|
377
374
|
|
|
378
375
|
**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.
|
|
379
376
|
|
|
@@ -394,10 +391,10 @@ Batch-parse error logs with minimal interaction: parse automatically, resolve co
|
|
|
394
391
|
- error_source: populated from log content
|
|
395
392
|
- verification_type: default to `automated`
|
|
396
393
|
- acceptance_criteria: auto-generate "Error no longer occurs in [scenario]"
|
|
397
|
-
4. Write `.prizmkit/plans/bug-fix-list.draft.json` as
|
|
394
|
+
4. Write `.prizmkit/plans/bug-fix-list.draft.json` as the private review workspace.
|
|
398
395
|
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.
|
|
399
|
-
6.
|
|
400
|
-
7.
|
|
396
|
+
6. Check merge feasibility without writing: the complete draft for a new list, or `append --dry-run` when a final list already exists. Do not add another broad approval after the consequential gaps are resolved.
|
|
397
|
+
7. Run the mandatory Local Generated-Plan Review Gate on the draft; on `PASS`, insert once with the matching Phase 5 writer, 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`.
|
|
401
398
|
|
|
402
399
|
## Operation: From Tests
|
|
403
400
|
|
|
@@ -409,10 +406,10 @@ Batch-parse failed test output:
|
|
|
409
406
|
2. Parse each failed test case as a separate bug entry
|
|
410
407
|
3. Auto-populate `failed_test_path`, `error_message`
|
|
411
408
|
4. Set verification_type to `automated` (test already exists)
|
|
412
|
-
5. Write `.prizmkit/plans/bug-fix-list.draft.json` as
|
|
409
|
+
5. Write `.prizmkit/plans/bug-fix-list.draft.json` as the private review workspace.
|
|
413
410
|
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.
|
|
415
|
-
8.
|
|
411
|
+
7. Check merge feasibility without writing: the complete draft for a new list, or `append --dry-run` when a final list already exists. Do not add another broad approval after the consequential gaps are resolved.
|
|
412
|
+
8. Run the mandatory Local Generated-Plan Review Gate on the draft; on `PASS`, insert once with the matching Phase 5 writer, 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`.
|
|
416
413
|
|
|
417
414
|
## Operation: Validate
|
|
418
415
|
|
|
@@ -462,12 +459,13 @@ Key points:
|
|
|
462
459
|
|
|
463
460
|
Recommend invoking `bugfix-pipeline-launcher` to configure and launch the pipeline. Do NOT recommend running shell scripts directly — that is the launcher's responsibility.
|
|
464
461
|
|
|
465
|
-
After `.prizmkit/plans/bug-fix-list.json` is
|
|
462
|
+
After `.prizmkit/plans/bug-fix-list.json` is inserted, present:
|
|
466
463
|
1. Summary of generated bugs (count, severity breakdown)
|
|
467
|
-
2. Local generated-plan review result: verdict, reviewed
|
|
468
|
-
3.
|
|
469
|
-
4.
|
|
470
|
-
5.
|
|
464
|
+
2. Local generated-plan review result: verdict, reviewed batch IDs plus reviewed root prose when applicable, and accepted fixes (or "none")
|
|
465
|
+
3. Insert result: the single writer run and the `appended_ids` it reported
|
|
466
|
+
4. Draft cleanup result: `removed`, or retained path and recovery reason
|
|
467
|
+
5. Recommend: "Say 'start fixing' to launch the bugfix pipeline via `bugfix-pipeline-launcher`"
|
|
468
|
+
6. Alternative: fix a single bug interactively via `bug-fix-workflow`
|
|
471
469
|
|
|
472
470
|
## Error Handling
|
|
473
471
|
|
|
@@ -1,28 +1,28 @@
|
|
|
1
1
|
# Generated Plan Review — Bug Planner
|
|
2
2
|
|
|
3
|
-
Use this local review loop
|
|
3
|
+
Use this local review loop on the batch that is about to be inserted into `.prizmkit/plans/bug-fix-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 `bug-planner` session
|
|
7
|
+
Run only when the current `bug-planner` session produced a draft batch of new or changed bugs. 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
|
-
|
|
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
|
-
-
|
|
16
|
-
-
|
|
15
|
+
- Review target: `.prizmkit/plans/bug-fix-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/bug-fix-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
|
-
-
|
|
19
|
+
- Already-committed entries a reviewed item relies on — load each referenced ID with `python3 ${SKILL_DIR}/scripts/validate-bug-list.py show --input .prizmkit/plans/bug-fix-list.json --id B-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.
|
|
25
|
+
1. Treat the draft batch as the change set. Its `B-*` 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 bug item changed. Ignore root generator metadata and formatting-only differences such as `$schema`, `created_at`, and `created_by`.
|
|
27
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
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.
|
|
@@ -48,6 +48,7 @@ For every reviewed bug entry, check:
|
|
|
48
48
|
- Incident scope: keep one bug per task unless the same root cause or same failing contract is confirmed; do not domain-merge by module
|
|
49
49
|
- Injected-field fidelity: confirmed actual/expected behavior and completion evidence are in `description` and `acceptance_criteria`; AI rewrite is allowed; dropping a confirmed item is not
|
|
50
50
|
- Size: there is no word-count upper limit and no acceptance-criteria count upper limit
|
|
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
|
- Browser interaction and verification fields for UI-reproducible bugs when applicable
|
|
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 bug-fix execution readiness.
|
|
82
83
|
3. Apply accepted fixes to `.prizmkit/plans/bug-fix-list.draft.json` or the in-memory draft object first.
|
|
83
|
-
4.
|
|
84
|
+
4. Re-check the fixed draft without writing:
|
|
84
85
|
|
|
85
86
|
```bash
|
|
86
|
-
python3 ${SKILL_DIR}/scripts/validate-bug-list.py append --input .prizmkit/plans/bug-fix-list.draft.json --output .prizmkit/plans/bug-fix-list.json --
|
|
87
|
+
python3 ${SKILL_DIR}/scripts/validate-bug-list.py append --input .prizmkit/plans/bug-fix-list.draft.json --output .prizmkit/plans/bug-fix-list.json --dry-run
|
|
87
88
|
```
|
|
88
89
|
|
|
89
|
-
|
|
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
|
-
|
|
92
|
-
|
|
93
|
-
```bash
|
|
94
|
-
python3 ${SKILL_DIR}/scripts/validate-bug-list.py generate --input .prizmkit/plans/bug-fix-list.draft.json --output .prizmkit/plans/bug-fix-list.json
|
|
95
|
-
```
|
|
96
|
-
|
|
97
|
-
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.
|
|
92
|
+
5. Never 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.
|
|
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
|
|
100
|
-
8. After `PASS`, delete `.prizmkit/plans/bug-fix-list.draft.json
|
|
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/bug-fix-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
|
|
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
|
-
-
|
|
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
|
|
107
|
+
- Note when review was not applicable because no new planning content was written
|
|
@@ -15,6 +15,7 @@ Usage:
|
|
|
15
15
|
python3 validate-bug-list.py context --input .prizmkit/plans/bug-fix-list.json
|
|
16
16
|
python3 validate-bug-list.py show --input .prizmkit/plans/bug-fix-list.json --id B-001
|
|
17
17
|
python3 validate-bug-list.py append --input additions.json --output .prizmkit/plans/bug-fix-list.json
|
|
18
|
+
python3 validate-bug-list.py append --input additions.json --output .prizmkit/plans/bug-fix-list.json --dry-run
|
|
18
19
|
python3 validate-bug-list.py generate --input draft.json --output .prizmkit/plans/bug-fix-list.json
|
|
19
20
|
|
|
20
21
|
Exit codes:
|
|
@@ -477,6 +478,11 @@ def cmd_append(args):
|
|
|
477
478
|
_err(" " + error)
|
|
478
479
|
return 1
|
|
479
480
|
|
|
481
|
+
if getattr(args, "dry_run", False):
|
|
482
|
+
_info("Dry run: {} bug(s) would be appended to {}".format(
|
|
483
|
+
len(prepared), args.output))
|
|
484
|
+
return 0
|
|
485
|
+
|
|
480
486
|
try:
|
|
481
487
|
_write_json_atomic(args.output, merged)
|
|
482
488
|
except Exception as exc:
|
|
@@ -605,6 +611,11 @@ def main():
|
|
|
605
611
|
action="store_true",
|
|
606
612
|
help="Replace the exact existing suffix with the same IDs after local review",
|
|
607
613
|
)
|
|
614
|
+
p_append.add_argument(
|
|
615
|
+
"--dry-run",
|
|
616
|
+
action="store_true",
|
|
617
|
+
help="Validate the would-be merged list without writing it",
|
|
618
|
+
)
|
|
608
619
|
|
|
609
620
|
# -- generate --
|
|
610
621
|
p_generate = subparsers.add_parser(
|
|
@@ -59,7 +59,7 @@ The user chose this skill intentionally. Respect that choice.
|
|
|
59
59
|
|
|
60
60
|
## Draft Lifecycle (Hard Rule)
|
|
61
61
|
|
|
62
|
-
In an ordinary successful flow, `.prizmkit/plans/feature-list.draft.json` is
|
|
62
|
+
In an ordinary successful flow, `.prizmkit/plans/feature-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`; name any retained path 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.
|
|
63
63
|
|
|
64
64
|
## Fresh-Session Task Contract (Hard Rule)
|
|
65
65
|
|
|
@@ -242,8 +242,8 @@ For ordinary incremental planning, NEVER read the complete existing `.prizmkit/p
|
|
|
242
242
|
2. Inspect those pairs only for material continuation, duplication, conflict, a shared public behavior contract, or an execution prerequisite. Add no historical content by default. Chronology, broad module overlap, shared technology, reusable implementation ideas, or similar wording alone do not establish relevance.
|
|
243
243
|
3. Incorporate only the minimum exact information whose omission would make scope, behavior, compatibility, acceptance criteria, or dependency ordering incorrect. Reject vague `related to F-123` text and whole-description copying; add an old ID to `dependencies` only when it is a real execution prerequisite.
|
|
244
244
|
4. Only for an explicitly identified old ID or a validation error, run `python3 ${SKILL_DIR}/scripts/validate-and-generate.py show --input .prizmkit/plans/feature-list.json --id F-NNN`.
|
|
245
|
-
5. For append-only planning, write `.prizmkit/plans/feature-list.draft.json` with exactly one root field, `features`, containing non-empty unchanged-schema items. This bounded draft is
|
|
246
|
-
6. After consequential decisions and the pre-generation gate pass,
|
|
245
|
+
5. For append-only planning, write `.prizmkit/plans/feature-list.draft.json` with exactly one root field, `features`, containing non-empty unchanged-schema items. This bounded draft is a private reasoning workspace and the review target, not a user approval artifact or a deliverable. Required draft fields are `id`, `title`, `description`, `priority`, `dependencies`, and `acceptance_criteria`; `status` may be omitted and defaults to `pending`; existing optional fields remain allowed. Copy no root metadata or historical features.
|
|
246
|
+
6. After consequential decisions and the pre-generation gate pass, write the batch to the additions-only draft with the `context` IDs and check merge feasibility without writing: `python3 ${SKILL_DIR}/scripts/validate-and-generate.py append --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json --dry-run`. Do not ask for separate user approval merely to promote the draft into the final list. The dry run applies the same base, ID, dependency, and 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. `generate` remains the initial-plan/full-rewrite path.
|
|
247
247
|
## Scenario Routing
|
|
248
248
|
Classify user intent first:
|
|
249
249
|
|
|
@@ -311,11 +311,10 @@ Execute the planning workflow in conversation mode with mandatory checkpoints:
|
|
|
311
311
|
4.2 **Browser interaction** (mandatory for fullstack/frontend projects) — see §Browser Interaction Planning below. Qualifying features get `browser_interaction` by default. Only confirm with the user as a batch summary; do NOT ask per-feature.
|
|
312
312
|
5. Verify DAG/order/priorities and show the mandatory priority/complexity calibration table with short rationales for every item
|
|
313
313
|
6. Run the pre-generation Headless Context Completeness Gate (see §Pre-Generation Completeness Review below)
|
|
314
|
-
7. Build
|
|
314
|
+
7. Build the batch in `.prizmkit/plans/feature-list.draft.json` with the `context` IDs; write no final list yet
|
|
315
315
|
8. Apply default testing strategy (see §Testing Defaults below)
|
|
316
|
-
9. Validate and fix until pass
|
|
317
|
-
|
|
318
|
-
11. Summarize final feature table with local review result, validation outcome, and draft cleanup result
|
|
316
|
+
9. Validate the draft batch and fix until pass, then run the mandatory Local Generated-Plan Review Gate (see §Local Generated-Plan Review Gate below) against it; apply accepted fixes to the draft, revalidate, and repeat until `PASS`
|
|
317
|
+
11. Insert the batch once (`append`, or `generate` for a new list), complete §Draft Lifecycle cleanup, and summarize the final feature table with the inserted IDs, local review verdict, writer result, and cleanup result
|
|
319
318
|
|
|
320
319
|
### Checkpoints (Mandatory Gates)
|
|
321
320
|
|
|
@@ -329,9 +328,9 @@ Checkpoints catch cascading errors early — skipping one means the next phase b
|
|
|
329
328
|
| **CP-FP-3.1** | Browser Interaction Applied | Qualifying features have `browser_interaction` field; user confirmed or opted out | 4 |
|
|
330
329
|
| **CP-FP-3.2** | Testing Defaults Applied | All features have appropriate testing expectations | 7 |
|
|
331
330
|
| **CP-FP-3.3** | Completeness Review Passed | Every new or changed feature passes fresh-session simulation from `description` and `acceptance_criteria` without conversation history or `user_context` | 6 |
|
|
332
|
-
| **CP-FP-4** |
|
|
333
|
-
| **CP-FP-5** |
|
|
334
|
-
| **CP-FP-6** |
|
|
331
|
+
| **CP-FP-4** | Draft Batch Ready | Additions-only or complete draft holds the whole batch with `context` IDs; final list still untouched | 7-8 |
|
|
332
|
+
| **CP-FP-5** | Draft Validation Pass | Draft validation plus the merge dry run return `"valid": true` with zero errors | 9 |
|
|
333
|
+
| **CP-FP-6** | 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 `append`/`generate` whose `appended_ids` match the batch, and removed the draft | 10-11 |
|
|
335
334
|
|
|
336
335
|
**Resume Detection**: If existing artifacts are found, read `${SKILL_DIR}/references/error-recovery.md` §Resume Support for checkpoint-based resumption.
|
|
337
336
|
|
|
@@ -378,12 +377,12 @@ For simple incremental planning, skip detailed Phase 2-3 analysis:
|
|
|
378
377
|
3. Generate next sequential feature IDs
|
|
379
378
|
4. Draft features (title + description + acceptance_criteria + dependencies)
|
|
380
379
|
5. Run the mandatory pre-generation Headless Context Completeness Gate from Phase 6 on every drafted feature; repair the draft until each returns `PASS`.
|
|
381
|
-
6. Write the additions-only draft as internal input
|
|
380
|
+
6. Write the additions-only draft as internal input — no second draft-approval pause — and check merge feasibility without writing:
|
|
382
381
|
```bash
|
|
383
|
-
python3 ${SKILL_DIR}/scripts/validate-and-generate.py append --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
|
|
382
|
+
python3 ${SKILL_DIR}/scripts/validate-and-generate.py append --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json --dry-run
|
|
384
383
|
```
|
|
385
|
-
7. If valid → run the mandatory Local Generated-Plan Review Gate, complete §Draft Lifecycle cleanup, then present the final written result and recommend the next step
|
|
386
|
-
8. If invalid → apply fixes to the additions-only draft
|
|
384
|
+
7. If valid → run the mandatory Local Generated-Plan Review Gate on the draft, insert once with `append`, complete §Draft Lifecycle cleanup, then present the final written result and recommend the next step
|
|
385
|
+
8. If invalid → apply fixes to the additions-only draft and re-run the dry run (max 2 attempts, then escalate to full workflow)
|
|
387
386
|
|
|
388
387
|
## Browser Interaction Planning
|
|
389
388
|
|
|
@@ -433,13 +432,13 @@ Key requirements:
|
|
|
433
432
|
python3 ${SKILL_DIR}/scripts/validate-and-generate.py append --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
|
|
434
433
|
```
|
|
435
434
|
|
|
436
|
-
`generate` fills root defaults for complete drafts. `append` preserves root metadata and historical features, defaults missing new statuses, validates the merged full list, and writes only after validation passes. In ordinary incremental flow,
|
|
435
|
+
`generate` fills root defaults for complete drafts. `append` preserves root metadata and historical features, defaults missing new statuses, validates the merged full list, and writes only after validation passes. In ordinary incremental flow the draft is not a second approval checkpoint, but it is the review target, so the real `append` runs once, after the Local Generated-Plan Review returns `PASS`; use `append --dry-run` for every earlier merged check because it validates without writing. If the writer rejects the batch, fix its source draft and retry — a rejection never leaves a partial final list. Then follow §Draft Lifecycle.
|
|
437
436
|
|
|
438
437
|
## Local Generated-Plan Review Gate
|
|
439
438
|
|
|
440
|
-
Run this gate after `.prizmkit/plans/feature-list.json
|
|
439
|
+
Run this gate after the batch is written to the draft and passes draft validation, and before anything is written to `.prizmkit/plans/feature-list.json`: the review target is the batch about to be inserted, not a file that already contains it. For validate-only, summary-only, or draft-save flows with no batch, report that the gate is not applicable.
|
|
441
440
|
|
|
442
|
-
Read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the single source of truth. Review the
|
|
441
|
+
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 feature. Keep the review planning-only: apply accepted findings to the draft, re-run draft validation and the merge dry run, and repeat until it returns `PASS`. Only then insert once, complete §Draft Lifecycle cleanup, and present 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 the changed entries.
|
|
443
442
|
|
|
444
443
|
## Testing Defaults (Phase 8)
|
|
445
444
|
|
|
@@ -485,11 +484,12 @@ When the session appears to be ending:
|
|
|
485
484
|
|
|
486
485
|
## Handoff Message Template
|
|
487
486
|
|
|
488
|
-
After
|
|
487
|
+
After the batch is inserted, report:
|
|
489
488
|
1. Output file path
|
|
490
489
|
2. Total features + newly added features
|
|
491
490
|
3. Dependency and priority highlights
|
|
492
|
-
4. Local generated-plan review result: verdict, reviewed
|
|
493
|
-
5.
|
|
491
|
+
4. Local generated-plan review result: verdict, reviewed batch IDs plus reviewed root prose when applicable, and accepted fixes (or "none")
|
|
492
|
+
5. Insert result: the writer's `appended_ids` from the single post-review run, plus its validation output and the draft cleanup result (`removed`, or retained path and reason)
|
|
493
|
+
6. Recommended next action: `feature-pipeline-launcher`
|
|
494
494
|
|
|
495
495
|
Then apply the post-planning handoff in §Scope Boundary (ask before proceeding; never auto-execute).
|
|
@@ -1,28 +1,28 @@
|
|
|
1
1
|
# Generated Plan Review — Feature Planner
|
|
2
2
|
|
|
3
|
-
Use this local review loop
|
|
3
|
+
Use this local review loop on the batch that is about to be inserted into `.prizmkit/plans/feature-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 `feature-planner` session
|
|
7
|
+
Run only when the current `feature-planner` session produced a draft batch of new or changed features. 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
|
-
|
|
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
|
-
-
|
|
16
|
-
-
|
|
15
|
+
- Review target: `.prizmkit/plans/feature-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/feature-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
|
-
-
|
|
19
|
+
- Already-committed entries a reviewed item relies on — load each referenced ID with `python3 ${SKILL_DIR}/scripts/validate-and-generate.py show --input .prizmkit/plans/feature-list.json --id F-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.
|
|
25
|
+
1. Treat the draft batch as the change set. Its `F-*` 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 feature item changed. Ignore root generator metadata and formatting-only differences such as `$schema`, `created_at`, and `created_by`.
|
|
27
27
|
3. Treat features as changed only when item fields changed; load and review newly added feature IDs and explicitly changed feature IDs through `show`.
|
|
28
28
|
4. Preserve unchanged historical features. 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 only when a specific reviewed feature requires semantic inspection of that prerequisite.
|
|
@@ -49,6 +49,7 @@ For every reviewed feature entry, check:
|
|
|
49
49
|
- Unused nested work: new or changed items MUST NOT store required work only in `user_context`; move it into `description` and `acceptance_criteria`
|
|
50
50
|
- Injected-field fidelity: confirmed WHAT, constraints, non-goals, boundaries, and completion evidence are in `description` and `acceptance_criteria`; AI rewrite is allowed; dropping a confirmed item is not
|
|
51
51
|
- Size: there is no word-count upper limit and no acceptance-criteria count upper limit; long contracts are not defects
|
|
52
|
+
- 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.
|
|
52
53
|
- Browser interaction fields for qualifying frontend/fullstack features when applicable
|
|
53
54
|
|
|
54
55
|
## Headless Context Completeness Gate
|
|
@@ -82,32 +83,27 @@ Do not add new JSON fields, context objects, schema versions, or pipeline runtim
|
|
|
82
83
|
1. Present findings with IDs, severity, evidence, and suggested draft/source changes.
|
|
83
84
|
2. Accept only findings that improve planner correctness, completeness, or downstream execution readiness.
|
|
84
85
|
3. Apply accepted fixes to `.prizmkit/plans/feature-list.draft.json` or the in-memory draft object first.
|
|
85
|
-
4.
|
|
86
|
+
4. Re-check the fixed draft without writing:
|
|
86
87
|
|
|
87
88
|
```bash
|
|
88
|
-
python3 ${SKILL_DIR}/scripts/validate-and-generate.py append --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json --
|
|
89
|
+
python3 ${SKILL_DIR}/scripts/validate-and-generate.py append --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json --dry-run
|
|
89
90
|
```
|
|
90
91
|
|
|
91
|
-
|
|
92
|
+
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`. An initial plan 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.
|
|
92
93
|
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
```bash
|
|
96
|
-
python3 ${SKILL_DIR}/scripts/validate-and-generate.py generate --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
|
|
97
|
-
```
|
|
98
|
-
|
|
99
|
-
5. Re-run append/generation until valid. Do not hand-patch `.prizmkit/plans/feature-list.json` as the source of truth and do not add a user approval round for the mechanical rewrite.
|
|
94
|
+
5. Never hand-patch `.prizmkit/plans/feature-list.json` as the source of truth and do not add a user approval round for the mechanical rewrite.
|
|
100
95
|
6. Repeat the local review and Headless Context Completeness Gate only for entries changed by accepted fixes.
|
|
101
|
-
7. Do not report `PASS` until every required fresh-session answer is available and
|
|
102
|
-
8. After `PASS`,
|
|
96
|
+
7. Do not report `PASS` until every required fresh-session answer is available and the draft validation plus merge dry run pass.
|
|
97
|
+
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/feature-list.draft.json`. Retain a draft only under the conditions in `${SKILL_DIR}/references/error-recovery.md`; report the retained path and reason.
|
|
103
98
|
|
|
104
99
|
## Report Format
|
|
105
100
|
|
|
106
101
|
Report in the final handoff summary:
|
|
107
102
|
|
|
108
103
|
- `Local generated-plan review: PASS` or `NEEDS_FIXES`
|
|
109
|
-
- Reviewed
|
|
104
|
+
- Reviewed batch IDs and reviewed root prose (`project_description` / `global_context`) when applicable
|
|
105
|
+
- Merge dry-run result
|
|
110
106
|
- Accepted fixes, or `none`
|
|
111
|
-
-
|
|
107
|
+
- Insert result: the single writer run and the `appended_ids` it reported
|
|
112
108
|
- Draft cleanup result: `removed`, or retained path and recovery reason
|
|
113
|
-
- Note when review was not applicable because no new
|
|
109
|
+
- Note when review was not applicable because no new planning content was written
|
|
@@ -83,21 +83,21 @@ The additions-only `.prizmkit/plans/feature-list.draft.json` has exactly one roo
|
|
|
83
83
|
}
|
|
84
84
|
```
|
|
85
85
|
|
|
86
|
-
Each item uses the unchanged final feature-item schema. Required draft fields are `id`, `title`, `description`, `priority`, `dependencies`, and `acceptance_criteria`; `status` may be omitted and defaults to `pending`; all existing optional feature fields remain allowed. Root project metadata and historical features must not be copied into this draft. Treat it as
|
|
86
|
+
Each item uses the unchanged final feature-item schema. Required draft fields are `id`, `title`, `description`, `priority`, `dependencies`, and `acceptance_criteria`; `status` may be omitted and defaults to `pending`; all existing optional feature fields remain allowed. Root project metadata and historical features must not be copied into this draft. Treat it as a private reasoning workspace and the review target, not as a user approval artifact or a deliverable.
|
|
87
87
|
|
|
88
88
|
### Step 4: Rebalance Priority
|
|
89
89
|
|
|
90
90
|
Default to append only. Reprioritizing historical tasks is an explicit old-task modification, not part of ordinary append flow; require the user to identify the affected IDs and load only those tasks with `show`.
|
|
91
91
|
|
|
92
|
-
### Step 5:
|
|
92
|
+
### Step 5: Check Feasibility, Review, Then Insert Once
|
|
93
93
|
|
|
94
|
-
After consequential decisions and the pre-generation semantic gate pass,
|
|
94
|
+
After consequential decisions and the pre-generation semantic gate pass, check the additions against untouched history outside AI context without writing:
|
|
95
95
|
|
|
96
96
|
```bash
|
|
97
|
-
python3 ${SKILL_DIR}/scripts/validate-and-generate.py append --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
|
|
97
|
+
python3 ${SKILL_DIR}/scripts/validate-and-generate.py append --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json --dry-run
|
|
98
98
|
```
|
|
99
99
|
|
|
100
|
-
The
|
|
100
|
+
The dry run checks the existing base, exact sequential new IDs, all old/new dependencies, and the complete DAG exactly as the real insert will. Do not ask for separate user approval merely to promote the additions draft into the final list, and do not insert yet: run the Local Generated-Plan Review against the draft, apply accepted fixes there, and re-run this dry run until it stays green and the review returns `PASS`. Then insert once with the real `append` and delete the draft. For a later adjustment, recreate only the exact current additions from confirmed in-memory entries or explicit-ID `show` results before using `append --replace-tail`. Use `generate` only for an initial plan or an explicit full-list rewrite.
|
|
101
101
|
|
|
102
102
|
## Merge/Rewrite Rules
|
|
103
103
|
|
|
@@ -125,6 +125,6 @@ Use concise prompts during interaction:
|
|
|
125
125
|
- [ ] Additions-only draft contains no root metadata or historical features
|
|
126
126
|
- [ ] Atomic append ran immediately after semantic gates without a post-draft approval pause
|
|
127
127
|
- [ ] Existing project conventions preserved from project evidence
|
|
128
|
-
- [ ] Complete merged dependency graph validates through `append`
|
|
129
|
-
- [ ]
|
|
128
|
+
- [ ] Complete merged dependency graph validates through the `append` dry run
|
|
129
|
+
- [ ] Batch was reviewed in the draft, inserted exactly once after `PASS`, and the draft was deleted or its retained recovery path and reason were reported
|
|
130
130
|
- [ ] Next step recommendation: `feature-pipeline-launcher`
|
|
@@ -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
|
|
58
|
-
2.
|
|
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
|
-
|
|
63
|
-
|
|
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
|
|
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
|
|
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
|
|
176
|
-
6. After consequential decisions and the pre-generation gate pass,
|
|
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
|
|
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
|
|
323
|
-
2. Once required semantic gates pass,
|
|
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
|
-
|
|
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
|
|
335
|
-
5.
|
|
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**:
|
|
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
|
|
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** |
|
|
353
|
-
| **CP-RP-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
|
|
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
|
|
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
|
|
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
|
|
468
|
-
6.
|
|
469
|
-
7.
|
|
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
|
|
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`
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
-
|
|
16
|
-
-
|
|
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
|
-
-
|
|
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.
|
|
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.
|
|
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 --
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
100
|
-
8. After `PASS`,
|
|
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
|
|
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
|
-
-
|
|
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
|
|
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(
|