prizmkit 1.1.174 → 1.1.175
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 +26 -19
- package/bundled/skills/bug-planner/references/generated-plan-review.md +20 -11
- package/bundled/skills/bug-planner/scripts/validate-bug-list.py +216 -1
- package/bundled/skills/feature-planner/SKILL.md +27 -18
- package/bundled/skills/feature-planner/references/generated-plan-review.md +20 -11
- package/bundled/skills/feature-planner/references/incremental-feature-planning.md +83 -70
- package/bundled/skills/feature-planner/scripts/validate-and-generate.py +213 -0
- package/bundled/skills/refactor-planner/SKILL.md +35 -8
- package/bundled/skills/refactor-planner/references/fast-path.md +4 -4
- package/bundled/skills/refactor-planner/references/generated-plan-review.md +20 -11
- package/bundled/skills/refactor-planner/scripts/validate-and-generate-refactor.py +213 -0
- package/package.json +1 -1
package/bundled/VERSION.json
CHANGED
|
@@ -155,6 +155,14 @@ This skill handles multiple operations. Determine the user's intent and dispatch
|
|
|
155
155
|
| Validate existing bug list | **Operation: Validate** |
|
|
156
156
|
| Summarize bug list | **Operation: Summary** |
|
|
157
157
|
|
|
158
|
+
## Bounded Existing-List Context (Hard Rule)
|
|
159
|
+
For any content-generating flow that appends to an existing `.prizmkit/plans/bug-fix-list.json`, NEVER read the complete historical list into AI context and NEVER perform default full-history keyword search.
|
|
160
|
+
1. Run `python3 ${SKILL_DIR}/scripts/validate-bug-list.py context --input .prizmkit/plans/bug-fix-list.json`; consume only `project_name`, `project_description`, `global_context`, `task_count`, `next_id`, and the five most recently appended top-level bugs as `{id, description}` pairs (or all available bugs when fewer than five exist).
|
|
161
|
+
2. Inspect those pairs only for material continuation, duplication, conflict, a shared public behavior contract, or an execution prerequisite. Add no historical content by default. Chronology, broad module overlap, shared technology, reusable implementation ideas, or similar wording alone do not establish relevance.
|
|
162
|
+
3. Incorporate only the minimum exact information whose omission would make scope, behavior, compatibility, acceptance criteria, or dependency ordering incorrect. Reject vague `related to B-123` text and whole-description copying; add an old ID to `dependencies` only when it is a real execution prerequisite.
|
|
163
|
+
4. Only for an explicitly identified old ID or a validation error, run `python3 ${SKILL_DIR}/scripts/validate-bug-list.py show --input .prizmkit/plans/bug-fix-list.json --id B-NNN`.
|
|
164
|
+
5. For append-only planning, write `.prizmkit/plans/bug-fix-list.draft.json` with exactly one root field, `bugs`, containing non-empty unchanged-schema items. Required draft fields are `id`, `title`, `description`, `severity`, `error_source`, `verification_type`, and `acceptance_criteria`; `status` may be omitted and defaults to `pending`; existing optional fields remain allowed. Copy no root metadata or historical bugs.
|
|
165
|
+
6. Run `python3 ${SKILL_DIR}/scripts/validate-bug-list.py append --input .prizmkit/plans/bug-fix-list.draft.json --output .prizmkit/plans/bug-fix-list.json`; it validates the base, sequential IDs, dependencies, and complete DAG before atomic replacement. `generate` remains the new-list and explicit full-rewrite path.
|
|
158
166
|
## Scenario Routing
|
|
159
167
|
|
|
160
168
|
Classify user intent first:
|
|
@@ -172,10 +180,10 @@ Actions:
|
|
|
172
180
|
Use when `.prizmkit/plans/bug-fix-list.json` already exists and user wants to add more bugs.
|
|
173
181
|
|
|
174
182
|
Actions:
|
|
175
|
-
1.
|
|
176
|
-
2. Continue with next sequential `B-NNN`
|
|
177
|
-
3.
|
|
178
|
-
4.
|
|
183
|
+
1. Run the bounded `context` command from §Bounded Existing-List Context (if the file is missing, ask whether to start a new plan); do not read the complete list
|
|
184
|
+
2. Continue with the returned next sequential `B-NNN` ID
|
|
185
|
+
3. Write only new bugs to the additions-only draft and merge through `append`
|
|
186
|
+
4. Preserve existing entries and validate the complete merged list outside AI context
|
|
179
187
|
|
|
180
188
|
---
|
|
181
189
|
|
|
@@ -321,12 +329,17 @@ For every `NEEDS_FIXES` result, update the draft/source bug contract, rerun the
|
|
|
321
329
|
|
|
322
330
|
### Phase 5: Generate & Validate
|
|
323
331
|
|
|
324
|
-
1. **Write draft JSON**:
|
|
325
|
-
2. **Generate and validate**:
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
332
|
+
1. **Write draft JSON**: For a new list, write the complete `.prizmkit/plans/bug-fix-list.draft.json` conforming to the final schema. For an existing list, follow §Bounded Existing-List Context and write only the additions-only `bugs` object.
|
|
333
|
+
2. **Generate or append and validate**:
|
|
334
|
+
- New list or explicit full-list rewrite:
|
|
335
|
+
```bash
|
|
336
|
+
python3 ${SKILL_DIR}/scripts/validate-bug-list.py generate --input .prizmkit/plans/bug-fix-list.draft.json --output .prizmkit/plans/bug-fix-list.json
|
|
337
|
+
```
|
|
338
|
+
- Ordinary existing-list append:
|
|
339
|
+
```bash
|
|
340
|
+
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
|
+
```
|
|
342
|
+
`generate` fills root defaults for a complete draft. `append` preserves root metadata and historical bugs, defaults missing new statuses, and writes only after the merged full list validates.
|
|
330
343
|
3. **If validation fails**: Fix the draft and retry (max 3 attempts). If the script is unavailable, use the checklist in `${SKILL_DIR}/references/schema-validation.md`.
|
|
331
344
|
4. **Run the mandatory Local Generated-Plan Review Gate** (see §Local Generated-Plan Review Gate below): load `${SKILL_DIR}/references/generated-plan-review.md` and review only newly added/changed bug entries after validation passes and before success output.
|
|
332
345
|
5. **Output**: File path, summary, local generated-plan review result, validation outcome, and next steps
|
|
@@ -339,7 +352,7 @@ For every `NEEDS_FIXES` result, update the draft/source bug contract, rerun the
|
|
|
339
352
|
|
|
340
353
|
Run this gate after `.prizmkit/plans/bug-fix-list.json` passes generation and validation, and before the final handoff. It applies whenever this session added or changed final bug entries. For validate-only, summary-only, or draft-save flows with no final content change, report that the gate is not applicable.
|
|
341
354
|
|
|
342
|
-
Read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the single source of truth. Review the actual draft and final
|
|
355
|
+
Read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the single source of truth. Review the actual additions-only draft and use bounded `context` plus explicit-ID `show` for new or changed final entries because `.prizmkit` files may be gitignored; do not load unchanged historical entries. Repeat the Headless Context Completeness Gate for every reviewed new or changed bug. Keep the review planning-only, apply accepted findings to the draft/source representation, regenerate the final JSON, rerun validation, and repeat local review until it returns `PASS` before reporting the result.
|
|
343
356
|
|
|
344
357
|
#### Success Output
|
|
345
358
|
|
|
@@ -387,10 +400,7 @@ Batch-parse error logs with minimal interaction: parse automatically, then requi
|
|
|
387
400
|
4. Write draft to `.prizmkit/plans/bug-fix-list.draft.json` for user review
|
|
388
401
|
5. Run the Phase 4 Headless Context Completeness Gate on every parsed bug. Ask targeted clarification for missing expected behavior, selected scope, severity rationale, or verification decisions; update the draft until all entries pass.
|
|
389
402
|
6. Ask: "Review and confirm? You can edit individual entries."
|
|
390
|
-
7. After user confirms,
|
|
391
|
-
```bash
|
|
392
|
-
python3 ${SKILL_DIR}/scripts/validate-bug-list.py generate --input .prizmkit/plans/bug-fix-list.draft.json --output .prizmkit/plans/bug-fix-list.json
|
|
393
|
-
```
|
|
403
|
+
7. After user confirms, use the Phase 5 writer: `generate` for a new complete list, or the bounded additions-only `append` command when a final list already exists.
|
|
394
404
|
8. If validation passes, run the mandatory Local Generated-Plan Review Gate before summarizing or recommending `bugfix-pipeline-launcher`.
|
|
395
405
|
|
|
396
406
|
## Operation: From Tests
|
|
@@ -406,10 +416,7 @@ Batch-parse failed test output:
|
|
|
406
416
|
5. Write draft to `.prizmkit/plans/bug-fix-list.draft.json`
|
|
407
417
|
6. Run the Phase 4 Headless Context Completeness Gate on every parsed failed-test bug; ensure the failing test evidence agrees with the final expected behavior and selected fix scope.
|
|
408
418
|
7. Present parsed failed-test bug entries for confirmation; allow edits, merges, or removals
|
|
409
|
-
8. After user confirms,
|
|
410
|
-
```bash
|
|
411
|
-
python3 ${SKILL_DIR}/scripts/validate-bug-list.py generate --input .prizmkit/plans/bug-fix-list.draft.json --output .prizmkit/plans/bug-fix-list.json
|
|
412
|
-
```
|
|
419
|
+
8. After user confirms, use the Phase 5 writer: `generate` for a new complete list, or the bounded additions-only `append` command when a final list already exists.
|
|
413
420
|
9. If validation passes, run the mandatory Local Generated-Plan Review Gate before summarizing or recommending `bugfix-pipeline-launcher`.
|
|
414
421
|
|
|
415
422
|
## Operation: Validate
|
|
@@ -8,22 +8,23 @@ Run only when the current `bug-planner` session generated, appended, or rewrote
|
|
|
8
8
|
|
|
9
9
|
## Direct Artifact Reads
|
|
10
10
|
|
|
11
|
-
Planning artifacts may be gitignored, untracked, or absent from staged and unstaged diffs. Read the actual files
|
|
11
|
+
Planning artifacts may be gitignored, untracked, or absent from staged and unstaged diffs. Read the actual files through bounded, source-first access:
|
|
12
12
|
|
|
13
|
-
- Final list: `.prizmkit/plans/bug-fix-list.json`
|
|
14
|
-
- Draft/source list when present: `.prizmkit/plans/bug-fix-list.draft.json`
|
|
15
|
-
- Pre-session final list snapshot if captured in memory before edits
|
|
13
|
+
- 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
|
|
14
|
+
- Draft/source list when present: `.prizmkit/plans/bug-fix-list.draft.json` — ordinary incremental flow contains only additions and may be read completely
|
|
15
|
+
- Pre-session final list snapshot if captured in memory before edits — retain only bounded root context, prior task count/next ID, and the five recent `{id, description}` pairs, not full history
|
|
16
16
|
- In-memory draft object if the session has not written a draft file yet
|
|
17
|
+
- Newly appended or explicitly modified final entries — load each known ID with `python3 ${SKILL_DIR}/scripts/validate-bug-list.py show --input .prizmkit/plans/bug-fix-list.json --id B-NNN`
|
|
17
18
|
|
|
18
19
|
Do not rely on `git status`, `git diff`, or `git diff --cached` to decide whether planner output exists or changed. Do not invoke `/prizmkit-code-review` for this planner-output gate; `/prizmkit-code-review` remains the implementation/code-diff review gate after `/prizmkit-implement`.
|
|
19
20
|
|
|
20
21
|
## Review Scope
|
|
21
22
|
|
|
22
|
-
1.
|
|
23
|
-
2. Root project prose is reviewable content, not generator metadata.
|
|
24
|
-
3. Treat bugs as changed only when item fields changed; review newly added bug IDs and changed bug IDs
|
|
25
|
-
4. Preserve unchanged historical bugs.
|
|
26
|
-
5. If no snapshot exists, review all
|
|
23
|
+
1. For ordinary append flow, use the additions-only draft and the append result's stable bug IDs (`B-*`) as the change set; do not compare complete pre/post historical arrays in AI context.
|
|
24
|
+
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`.
|
|
25
|
+
3. Treat bugs as changed only when item fields changed; load and review newly added bug IDs and explicitly changed bug IDs through `show`.
|
|
26
|
+
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.
|
|
27
|
+
5. If no snapshot exists during initial generation, review all entries in that session's complete draft. Absence of a snapshot never authorizes loading unrelated history during append flow.
|
|
27
28
|
|
|
28
29
|
## Review Checklist
|
|
29
30
|
|
|
@@ -74,13 +75,21 @@ Do not add new JSON fields, context objects, schema versions, or pipeline runtim
|
|
|
74
75
|
1. Present findings with IDs, severity, evidence, and suggested draft/source changes.
|
|
75
76
|
2. Accept only findings that improve planner correctness, completeness, or downstream bug-fix execution readiness.
|
|
76
77
|
3. Apply accepted fixes to `.prizmkit/plans/bug-fix-list.draft.json` or the in-memory draft object first.
|
|
77
|
-
4.
|
|
78
|
+
4. For an ordinary incremental additions-only draft, rerun the existing script's append command:
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
python3 ${SKILL_DIR}/scripts/validate-bug-list.py append --input .prizmkit/plans/bug-fix-list.draft.json --output .prizmkit/plans/bug-fix-list.json --replace-tail
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
`--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.
|
|
85
|
+
|
|
86
|
+
For a new list or explicit full-list rewrite, regenerate through the existing script's complete-draft command:
|
|
78
87
|
|
|
79
88
|
```bash
|
|
80
89
|
python3 ${SKILL_DIR}/scripts/validate-bug-list.py generate --input .prizmkit/plans/bug-fix-list.draft.json --output .prizmkit/plans/bug-fix-list.json
|
|
81
90
|
```
|
|
82
91
|
|
|
83
|
-
5. Re-run
|
|
92
|
+
5. Re-run append/generation until valid. Do not hand-patch `.prizmkit/plans/bug-fix-list.json` as the source of truth.
|
|
84
93
|
6. Repeat the local review and Headless Context Completeness Gate only for entries changed by accepted fixes.
|
|
85
94
|
7. Do not report `PASS` until every required fresh-session answer is available and final validation passes after regeneration.
|
|
86
95
|
|
|
@@ -5,10 +5,16 @@ for the dev-pipeline system.
|
|
|
5
5
|
|
|
6
6
|
Commands:
|
|
7
7
|
validate Validate an existing bug-fix-list.json
|
|
8
|
+
context Print bounded project context plus the five most recent bugs
|
|
9
|
+
show Print one explicitly requested bug
|
|
10
|
+
append Merge an additions-only draft into an existing validated list
|
|
8
11
|
generate Validate a draft JSON and generate final bug-fix-list.json with defaults
|
|
9
12
|
|
|
10
13
|
Usage:
|
|
11
14
|
python3 validate-bug-list.py validate .prizmkit/plans/bug-fix-list.json [--feature-list .prizmkit/plans/feature-list.json]
|
|
15
|
+
python3 validate-bug-list.py context --input .prizmkit/plans/bug-fix-list.json
|
|
16
|
+
python3 validate-bug-list.py show --input .prizmkit/plans/bug-fix-list.json --id B-001
|
|
17
|
+
python3 validate-bug-list.py append --input additions.json --output .prizmkit/plans/bug-fix-list.json
|
|
12
18
|
python3 validate-bug-list.py generate --input draft.json --output .prizmkit/plans/bug-fix-list.json
|
|
13
19
|
|
|
14
20
|
Exit codes:
|
|
@@ -20,10 +26,12 @@ Python 3.6+ required. No external dependencies.
|
|
|
20
26
|
"""
|
|
21
27
|
|
|
22
28
|
import argparse
|
|
29
|
+
import copy
|
|
23
30
|
import json
|
|
24
31
|
import sys
|
|
25
32
|
import os
|
|
26
33
|
import re
|
|
34
|
+
import tempfile
|
|
27
35
|
from datetime import datetime, timezone
|
|
28
36
|
|
|
29
37
|
VALID_SEVERITIES = {"critical", "high", "medium", "low"}
|
|
@@ -120,6 +128,25 @@ def _write_json(path, data):
|
|
|
120
128
|
f.write("\n")
|
|
121
129
|
|
|
122
130
|
|
|
131
|
+
def _write_json_atomic(path, data):
|
|
132
|
+
"""Atomically replace *path* with pretty-printed JSON data."""
|
|
133
|
+
parent = os.path.dirname(os.path.abspath(path))
|
|
134
|
+
if parent and not os.path.isdir(parent):
|
|
135
|
+
os.makedirs(parent, exist_ok=True)
|
|
136
|
+
fd, temp_path = tempfile.mkstemp(prefix=".bug-fix-list-", suffix=".tmp", dir=parent)
|
|
137
|
+
try:
|
|
138
|
+
with os.fdopen(fd, "w", encoding="utf-8") as f:
|
|
139
|
+
json.dump(data, f, indent=2, ensure_ascii=False)
|
|
140
|
+
f.write("\n")
|
|
141
|
+
os.replace(temp_path, path)
|
|
142
|
+
except Exception:
|
|
143
|
+
try:
|
|
144
|
+
os.unlink(temp_path)
|
|
145
|
+
except OSError:
|
|
146
|
+
pass
|
|
147
|
+
raise
|
|
148
|
+
|
|
149
|
+
|
|
123
150
|
def validate(data, feature_ids=None):
|
|
124
151
|
"""Validate a parsed bug-fix-list data structure.
|
|
125
152
|
|
|
@@ -317,6 +344,148 @@ def cmd_validate(args):
|
|
|
317
344
|
return 1
|
|
318
345
|
|
|
319
346
|
|
|
347
|
+
def _load_valid_existing(path):
|
|
348
|
+
"""Load and validate one existing bug list."""
|
|
349
|
+
data, load_err = _load_json(path)
|
|
350
|
+
if load_err:
|
|
351
|
+
_err(load_err)
|
|
352
|
+
return None, None, 2
|
|
353
|
+
if not isinstance(data, dict):
|
|
354
|
+
_err("Bug list root must be an object")
|
|
355
|
+
return None, None, 1
|
|
356
|
+
|
|
357
|
+
result = validate(data)
|
|
358
|
+
if not result["valid"]:
|
|
359
|
+
_err("Existing bug list is invalid")
|
|
360
|
+
for error in result["errors"]:
|
|
361
|
+
_err(" " + error)
|
|
362
|
+
return None, result, 1
|
|
363
|
+
return data, result, 0
|
|
364
|
+
|
|
365
|
+
|
|
366
|
+
def _next_top_level_id(bugs):
|
|
367
|
+
"""Return the next B-NNN ID, or None when numeric capacity is exhausted."""
|
|
368
|
+
numbers = []
|
|
369
|
+
for bug in bugs:
|
|
370
|
+
match = BUG_ID_PATTERN.match(str(bug.get("id", "")))
|
|
371
|
+
if match:
|
|
372
|
+
numbers.append(int(str(bug["id"])[2:]))
|
|
373
|
+
next_number = max(numbers, default=0) + 1
|
|
374
|
+
if next_number > 999:
|
|
375
|
+
return None
|
|
376
|
+
return "B-{:03d}".format(next_number)
|
|
377
|
+
|
|
378
|
+
|
|
379
|
+
def cmd_context(args):
|
|
380
|
+
"""Print bounded existing-list context for incremental planning."""
|
|
381
|
+
data, _, exit_code = _load_valid_existing(args.input)
|
|
382
|
+
if exit_code:
|
|
383
|
+
return exit_code
|
|
384
|
+
|
|
385
|
+
bugs = data["bugs"]
|
|
386
|
+
next_id = _next_top_level_id(bugs)
|
|
387
|
+
if next_id is None:
|
|
388
|
+
_err("Bug ID capacity exhausted at B-999")
|
|
389
|
+
return 1
|
|
390
|
+
|
|
391
|
+
context = {
|
|
392
|
+
"project_name": data.get("project_name"),
|
|
393
|
+
"project_description": data.get("project_description"),
|
|
394
|
+
"global_context": data.get("global_context") or {},
|
|
395
|
+
"task_count": len(bugs),
|
|
396
|
+
"next_id": next_id,
|
|
397
|
+
"recent_tasks": [
|
|
398
|
+
{"id": bug.get("id"), "description": bug.get("description")}
|
|
399
|
+
for bug in bugs[-5:]
|
|
400
|
+
],
|
|
401
|
+
}
|
|
402
|
+
print(json.dumps(context, indent=2, ensure_ascii=False))
|
|
403
|
+
return 0
|
|
404
|
+
|
|
405
|
+
|
|
406
|
+
def cmd_show(args):
|
|
407
|
+
"""Print one explicitly requested top-level bug."""
|
|
408
|
+
data, _, exit_code = _load_valid_existing(args.input)
|
|
409
|
+
if exit_code:
|
|
410
|
+
return exit_code
|
|
411
|
+
if not BUG_ID_PATTERN.match(str(args.id)):
|
|
412
|
+
_err("Bug ID '{}' must match B-NNN".format(args.id))
|
|
413
|
+
return 1
|
|
414
|
+
|
|
415
|
+
for bug in data["bugs"]:
|
|
416
|
+
if bug.get("id") == args.id:
|
|
417
|
+
print(json.dumps(bug, indent=2, ensure_ascii=False))
|
|
418
|
+
return 0
|
|
419
|
+
_err("Bug '{}' not found".format(args.id))
|
|
420
|
+
return 1
|
|
421
|
+
|
|
422
|
+
|
|
423
|
+
def cmd_append(args):
|
|
424
|
+
"""Append a collection-only draft to an existing validated bug list."""
|
|
425
|
+
base, _, exit_code = _load_valid_existing(args.output)
|
|
426
|
+
if exit_code:
|
|
427
|
+
return exit_code
|
|
428
|
+
|
|
429
|
+
draft, load_err = _load_json(args.input)
|
|
430
|
+
if load_err:
|
|
431
|
+
_err(load_err)
|
|
432
|
+
return 2
|
|
433
|
+
if not isinstance(draft, dict) or set(draft.keys()) != {"bugs"}:
|
|
434
|
+
_err("Additions draft must be an object containing only 'bugs'")
|
|
435
|
+
return 1
|
|
436
|
+
additions = draft.get("bugs")
|
|
437
|
+
if not isinstance(additions, list) or not additions:
|
|
438
|
+
_err("Additions draft 'bugs' must be a non-empty array")
|
|
439
|
+
return 1
|
|
440
|
+
if not all(isinstance(bug, dict) for bug in additions):
|
|
441
|
+
_err("Every bug addition must be an object")
|
|
442
|
+
return 1
|
|
443
|
+
|
|
444
|
+
merge_base = copy.deepcopy(base)
|
|
445
|
+
if args.replace_tail:
|
|
446
|
+
addition_ids = [bug.get("id") for bug in additions]
|
|
447
|
+
tail_ids = [bug.get("id") for bug in base["bugs"][-len(additions):]]
|
|
448
|
+
if len(base["bugs"]) < len(additions) or tail_ids != addition_ids:
|
|
449
|
+
_err("--replace-tail requires additions IDs to match the existing final-list suffix exactly")
|
|
450
|
+
return 1
|
|
451
|
+
merge_base["bugs"] = merge_base["bugs"][:-len(additions)]
|
|
452
|
+
|
|
453
|
+
next_id = _next_top_level_id(merge_base["bugs"])
|
|
454
|
+
if next_id is None:
|
|
455
|
+
_err("Bug ID capacity exhausted at B-999")
|
|
456
|
+
return 1
|
|
457
|
+
start_number = int(next_id[2:])
|
|
458
|
+
prepared = copy.deepcopy(additions)
|
|
459
|
+
for offset, bug in enumerate(prepared):
|
|
460
|
+
expected_id = "B-{:03d}".format(start_number + offset)
|
|
461
|
+
if start_number + offset > 999:
|
|
462
|
+
_err("Bug ID capacity exhausted at B-999")
|
|
463
|
+
return 1
|
|
464
|
+
if bug.get("id") != expected_id:
|
|
465
|
+
_err("Bug addition {} must use next sequential ID '{}'".format(offset, expected_id))
|
|
466
|
+
return 1
|
|
467
|
+
bug.setdefault("status", "pending")
|
|
468
|
+
|
|
469
|
+
merged = copy.deepcopy(merge_base)
|
|
470
|
+
merged["bugs"].extend(prepared)
|
|
471
|
+
result = validate(merged)
|
|
472
|
+
result["appended_ids"] = [bug["id"] for bug in prepared]
|
|
473
|
+
print(json.dumps(result, indent=2, ensure_ascii=False))
|
|
474
|
+
if not result["valid"]:
|
|
475
|
+
_err("Merged bug list validation failed")
|
|
476
|
+
for error in result["errors"]:
|
|
477
|
+
_err(" " + error)
|
|
478
|
+
return 1
|
|
479
|
+
|
|
480
|
+
try:
|
|
481
|
+
_write_json_atomic(args.output, merged)
|
|
482
|
+
except Exception as exc:
|
|
483
|
+
_err("Failed to write merged bug list: {}".format(exc))
|
|
484
|
+
return 2
|
|
485
|
+
_info("Appended {} bug(s) to {}".format(len(prepared), args.output))
|
|
486
|
+
return 0
|
|
487
|
+
|
|
488
|
+
|
|
320
489
|
def cmd_generate(args):
|
|
321
490
|
"""Handle the 'generate' command.
|
|
322
491
|
|
|
@@ -366,7 +535,9 @@ def cmd_generate(args):
|
|
|
366
535
|
def main():
|
|
367
536
|
# Backward compatibility: if first arg is a file path (not a subcommand),
|
|
368
537
|
# treat it as 'validate' command
|
|
369
|
-
if len(sys.argv) > 1 and not sys.argv[1].startswith("-") and sys.argv[1] not in (
|
|
538
|
+
if len(sys.argv) > 1 and not sys.argv[1].startswith("-") and sys.argv[1] not in (
|
|
539
|
+
"validate", "context", "show", "append", "generate"
|
|
540
|
+
):
|
|
370
541
|
sys.argv.insert(1, "validate")
|
|
371
542
|
|
|
372
543
|
parser = argparse.ArgumentParser(
|
|
@@ -376,6 +547,9 @@ def main():
|
|
|
376
547
|
"Examples:\n"
|
|
377
548
|
" %(prog)s validate .prizmkit/plans/bug-fix-list.json\n"
|
|
378
549
|
" %(prog)s validate .prizmkit/plans/bug-fix-list.json --feature-list .prizmkit/plans/feature-list.json\n"
|
|
550
|
+
" %(prog)s context --input .prizmkit/plans/bug-fix-list.json\n"
|
|
551
|
+
" %(prog)s show --input .prizmkit/plans/bug-fix-list.json --id B-001\n"
|
|
552
|
+
" %(prog)s append --input additions.json --output .prizmkit/plans/bug-fix-list.json\n"
|
|
379
553
|
" %(prog)s generate --input draft.json --output .prizmkit/plans/bug-fix-list.json\n"
|
|
380
554
|
),
|
|
381
555
|
)
|
|
@@ -394,6 +568,44 @@ def main():
|
|
|
394
568
|
"--feature-list", default=None, help="Path to feature-list.json for cross-reference"
|
|
395
569
|
)
|
|
396
570
|
|
|
571
|
+
# -- context --
|
|
572
|
+
p_context = subparsers.add_parser(
|
|
573
|
+
"context",
|
|
574
|
+
help="Print root context and the five most recent bug id/description pairs",
|
|
575
|
+
)
|
|
576
|
+
p_context.add_argument(
|
|
577
|
+
"--input", required=True, help="Path to existing .prizmkit/plans/bug-fix-list.json"
|
|
578
|
+
)
|
|
579
|
+
|
|
580
|
+
# -- show --
|
|
581
|
+
p_show = subparsers.add_parser(
|
|
582
|
+
"show",
|
|
583
|
+
help="Print one explicitly requested top-level bug",
|
|
584
|
+
)
|
|
585
|
+
p_show.add_argument(
|
|
586
|
+
"--input", required=True, help="Path to existing .prizmkit/plans/bug-fix-list.json"
|
|
587
|
+
)
|
|
588
|
+
p_show.add_argument(
|
|
589
|
+
"--id", required=True, help="Exact top-level bug ID"
|
|
590
|
+
)
|
|
591
|
+
|
|
592
|
+
# -- append --
|
|
593
|
+
p_append = subparsers.add_parser(
|
|
594
|
+
"append",
|
|
595
|
+
help="Append a bugs-only draft to an existing validated bug list",
|
|
596
|
+
)
|
|
597
|
+
p_append.add_argument(
|
|
598
|
+
"--input", required=True, help="Path to additions-only draft JSON"
|
|
599
|
+
)
|
|
600
|
+
p_append.add_argument(
|
|
601
|
+
"--output", required=True, help="Path to existing final bug-fix-list.json"
|
|
602
|
+
)
|
|
603
|
+
p_append.add_argument(
|
|
604
|
+
"--replace-tail",
|
|
605
|
+
action="store_true",
|
|
606
|
+
help="Replace the exact existing suffix with the same IDs after local review",
|
|
607
|
+
)
|
|
608
|
+
|
|
397
609
|
# -- generate --
|
|
398
610
|
p_generate = subparsers.add_parser(
|
|
399
611
|
"generate",
|
|
@@ -414,6 +626,9 @@ def main():
|
|
|
414
626
|
|
|
415
627
|
dispatch = {
|
|
416
628
|
"validate": cmd_validate,
|
|
629
|
+
"context": cmd_context,
|
|
630
|
+
"show": cmd_show,
|
|
631
|
+
"append": cmd_append,
|
|
417
632
|
"generate": cmd_generate,
|
|
418
633
|
}
|
|
419
634
|
|
|
@@ -149,7 +149,7 @@ Before questions, check optional context files (never block if absent):
|
|
|
149
149
|
- `.prizmkit/prizm-docs/root.prizm` (architecture/project context — typically created by app-planner with captured decisions)
|
|
150
150
|
- `.prizmkit/config.json` (existing stack preferences and detected tech stack)
|
|
151
151
|
- `.prizmkit/plans/project-brief.md` (project context from app-planner, if available)
|
|
152
|
-
- existing `.prizmkit/plans/feature-list.json` (required for incremental mode)
|
|
152
|
+
- existing `.prizmkit/plans/feature-list.json` (required for incremental mode; inspect it only through the bounded commands below)
|
|
153
153
|
- Platform instruction file: use the `platform` field in `.prizmkit/manifest.json` as source of truth when present (`codex` → `AGENTS.md`, `cursor` → existing user-owned `AGENTS.md` when present, `claude` → `CLAUDE.md`, `codebuddy` → `CODEBUDDY.md`, `all` → read every matching file). Legacy manifests may contain `both`; treat it as read-only compatibility and read `CLAUDE.md` plus `CODEBUDDY.md` only when encountered.
|
|
154
154
|
- If `.prizmkit/prizm-docs/root.prizm` is absent and the project has existing source code, scan the directory structure to understand the codebase layout:
|
|
155
155
|
```bash
|
|
@@ -231,11 +231,16 @@ F-003 | Tooltip copy update | low | Cosmetic clarity only |
|
|
|
231
231
|
|
|
232
232
|
Anti-pattern rule: do not assign every generated item `Priority: high` and `Complexity: high` unless each item independently satisfies the documented high criteria and its rationale names those criteria. In feature JSON this means `estimated_complexity: high`; in user-facing review summaries label the column `Complexity`.
|
|
233
233
|
|
|
234
|
-
|
|
235
234
|
---
|
|
236
|
-
|
|
235
|
+
## Bounded Existing-List Context (Hard Rule)
|
|
236
|
+
For ordinary incremental planning, NEVER read the complete existing `.prizmkit/plans/feature-list.json` into AI context and NEVER perform default full-history keyword search.
|
|
237
|
+
1. Run `python3 ${SKILL_DIR}/scripts/validate-and-generate.py context --input .prizmkit/plans/feature-list.json`; consume only `project_name`, `project_description`, `global_context`, `task_count`, `next_id`, and the five most recently appended top-level tasks as `{id, description}` pairs (or all available tasks when fewer than five exist).
|
|
238
|
+
2. Inspect those pairs only for material continuation, duplication, conflict, a shared public behavior contract, or an execution prerequisite. Add no historical content by default. Chronology, broad module overlap, shared technology, reusable implementation ideas, or similar wording alone do not establish relevance.
|
|
239
|
+
3. Incorporate only the minimum exact information whose omission would make scope, behavior, compatibility, acceptance criteria, or dependency ordering incorrect. Reject vague `related to F-123` text and whole-description copying; add an old ID to `dependencies` only when it is a real execution prerequisite.
|
|
240
|
+
4. Only for an explicitly identified old ID or a validation error, run `python3 ${SKILL_DIR}/scripts/validate-and-generate.py show --input .prizmkit/plans/feature-list.json --id F-NNN`.
|
|
241
|
+
5. For append-only planning, write `.prizmkit/plans/feature-list.draft.json` with exactly one root field, `features`, containing non-empty unchanged-schema items. Required draft fields are `id`, `title`, `description`, `priority`, `dependencies`, and `acceptance_criteria`; `status` may be omitted and defaults to `pending`; existing optional fields remain allowed. Copy no root metadata or historical features.
|
|
242
|
+
6. Run `python3 ${SKILL_DIR}/scripts/validate-and-generate.py append --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json`; it validates the base, sequential IDs, dependencies, and complete DAG before atomic replacement. `generate` remains the initial-plan and explicit full-rewrite path.
|
|
237
243
|
## Scenario Routing
|
|
238
|
-
|
|
239
244
|
Classify user intent first:
|
|
240
245
|
|
|
241
246
|
### Route A: Initial Feature Set for Existing/App-Planned Project
|
|
@@ -251,9 +256,9 @@ Use when user already has a `.prizmkit/plans/feature-list.json` and wants to add
|
|
|
251
256
|
|
|
252
257
|
Actions:
|
|
253
258
|
1. Load `${SKILL_DIR}/references/incremental-feature-planning.md`
|
|
254
|
-
2.
|
|
255
|
-
3. Append features with next sequential `F-NNN` IDs
|
|
256
|
-
4. Preserve
|
|
259
|
+
2. Run the bounded `context` command from §Bounded Existing-List Context (if the file is missing, ask whether to start a new plan); do not read the complete list
|
|
260
|
+
3. Append features with the returned next sequential `F-NNN` IDs through the additions-only `append` command
|
|
261
|
+
4. Preserve confirmed project conventions and self-contained task quality without forcing unrelated recent history into new features
|
|
257
262
|
|
|
258
263
|
### Route C: Validate Existing Plan
|
|
259
264
|
Use when the user asks to check or validate an existing plan without adding or changing features.
|
|
@@ -347,7 +352,7 @@ For simple incremental planning, skip detailed Phase 2-3 analysis:
|
|
|
347
352
|
- **No architectural changes** to existing tech stack
|
|
348
353
|
|
|
349
354
|
### Fast Path Workflow
|
|
350
|
-
1.
|
|
355
|
+
1. Run the bounded `context` command from §Bounded Existing-List Context and confirm scope without reading the complete historical list
|
|
351
356
|
2. **User confirmation (mandatory)** — Use `AskUserQuestion` to present interactive selectable options:
|
|
352
357
|
|
|
353
358
|
```
|
|
@@ -369,12 +374,12 @@ For simple incremental planning, skip detailed Phase 2-3 analysis:
|
|
|
369
374
|
3. Generate next sequential feature IDs
|
|
370
375
|
4. Draft features (title + description + acceptance_criteria + dependencies)
|
|
371
376
|
5. Run the mandatory pre-generation Headless Context Completeness Gate from Phase 6 on every drafted feature; repair the draft until each returns `PASS`.
|
|
372
|
-
6. Write draft to `.prizmkit/plans/feature-list.draft.json`, then call the
|
|
377
|
+
6. Write an additions-only draft to `.prizmkit/plans/feature-list.draft.json`, then call the append command:
|
|
373
378
|
```bash
|
|
374
|
-
python3 ${SKILL_DIR}/scripts/validate-and-generate.py
|
|
379
|
+
python3 ${SKILL_DIR}/scripts/validate-and-generate.py append --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
|
|
375
380
|
```
|
|
376
381
|
7. If valid → run the mandatory Local Generated-Plan Review Gate, then summarize and recommend next step
|
|
377
|
-
8. If invalid → apply fixes to the draft, re-run
|
|
382
|
+
8. If invalid → apply fixes to the additions-only draft, re-run `append` (max 2 attempts, then escalate to full workflow)
|
|
378
383
|
|
|
379
384
|
## Browser Interaction Planning
|
|
380
385
|
|
|
@@ -415,18 +420,22 @@ Key requirements:
|
|
|
415
420
|
- `estimated_complexity` records implementation scope and verification risk for planning summaries, ordering, and downstream context. It does not select a fixed agent count or named review topology; every normal feature session receives the runtime's full guidance.
|
|
416
421
|
|
|
417
422
|
**IMPORTANT: Do NOT hand-write the final JSON file.** Instead:
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
423
|
+
- Initial plan or explicit full-list rewrite: write the complete draft and use `generate`:
|
|
424
|
+
```bash
|
|
425
|
+
python3 ${SKILL_DIR}/scripts/validate-and-generate.py generate --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
|
|
426
|
+
```
|
|
427
|
+
- Ordinary incremental append: follow §Bounded Existing-List Context, write only the additions-only `features` object, and use `append`:
|
|
428
|
+
```bash
|
|
429
|
+
python3 ${SKILL_DIR}/scripts/validate-and-generate.py append --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
|
|
430
|
+
```
|
|
431
|
+
|
|
432
|
+
`generate` fills root defaults for complete drafts. `append` preserves root metadata and historical features, defaults missing new statuses, validates the merged full list, and writes only after validation passes. If either command fails, fix its source draft and retry.
|
|
424
433
|
|
|
425
434
|
## Local Generated-Plan Review Gate
|
|
426
435
|
|
|
427
436
|
Run this gate after `.prizmkit/plans/feature-list.json` passes generation and validation, and before the final handoff. It applies whenever this session added or changed final feature entries. For validate-only, summary-only, or draft-save flows with no final content change, report that the gate is not applicable.
|
|
428
437
|
|
|
429
|
-
Read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the single source of truth. Review the actual draft and final
|
|
438
|
+
Read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the single source of truth. Review the actual additions-only draft and use bounded `context` plus explicit-ID `show` for new or changed final entries because `.prizmkit` files may be gitignored; do not load unchanged historical entries. Repeat the Headless Context Completeness Gate for every reviewed new or changed feature. Keep the review planning-only, apply accepted findings to the draft/source representation, regenerate the final JSON, rerun validation, and repeat the local review until it returns `PASS` before reporting the result.
|
|
430
439
|
|
|
431
440
|
## Testing Defaults (Phase 8)
|
|
432
441
|
|
|
@@ -8,22 +8,23 @@ Run only when the current `feature-planner` session generated, appended, or rewr
|
|
|
8
8
|
|
|
9
9
|
## Direct Artifact Reads
|
|
10
10
|
|
|
11
|
-
Planning artifacts may be gitignored, untracked, or absent from staged and unstaged diffs. Read the actual files
|
|
11
|
+
Planning artifacts may be gitignored, untracked, or absent from staged and unstaged diffs. Read the actual files through bounded, source-first access:
|
|
12
12
|
|
|
13
|
-
- Final list: `.prizmkit/plans/feature-list.json`
|
|
14
|
-
- Draft/source list when present: `.prizmkit/plans/feature-list.draft.json`
|
|
15
|
-
- Pre-session final list snapshot if captured in memory before edits
|
|
13
|
+
- 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
|
|
14
|
+
- Draft/source list when present: `.prizmkit/plans/feature-list.draft.json` — ordinary incremental flow contains only additions and may be read completely
|
|
15
|
+
- Pre-session final list snapshot if captured in memory before edits — retain only bounded root context, prior task count/next ID, and the five recent `{id, description}` pairs, not full history
|
|
16
16
|
- In-memory draft object if the session has not written a draft file yet
|
|
17
|
+
- Newly appended or explicitly modified final entries — load each known ID with `python3 ${SKILL_DIR}/scripts/validate-and-generate.py show --input .prizmkit/plans/feature-list.json --id F-NNN`
|
|
17
18
|
|
|
18
19
|
Do not rely on `git status`, `git diff`, or `git diff --cached` to decide whether planner output exists or changed. Do not invoke `/prizmkit-code-review` for this planner-output gate; `/prizmkit-code-review` remains the implementation/code-diff review gate after `/prizmkit-implement`.
|
|
19
20
|
|
|
20
21
|
## Review Scope
|
|
21
22
|
|
|
22
|
-
1.
|
|
23
|
-
2. Root project prose is reviewable content, not generator metadata.
|
|
24
|
-
3. Treat features as changed only when item fields changed; review newly added feature IDs and changed feature IDs
|
|
25
|
-
4. Preserve unchanged historical features.
|
|
26
|
-
5. If no snapshot exists, review all
|
|
23
|
+
1. For ordinary append flow, use the additions-only draft and the append result's stable feature IDs (`F-*`) as the change set; do not compare complete pre/post historical arrays in AI context.
|
|
24
|
+
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`.
|
|
25
|
+
3. Treat features as changed only when item fields changed; load and review newly added feature IDs and explicitly changed feature IDs through `show`.
|
|
26
|
+
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.
|
|
27
|
+
5. If no snapshot exists during initial generation, review all entries in that session's complete draft. Absence of a snapshot never authorizes loading unrelated history during append flow.
|
|
27
28
|
|
|
28
29
|
## Review Checklist
|
|
29
30
|
|
|
@@ -75,13 +76,21 @@ Do not add new JSON fields, context objects, schema versions, or pipeline runtim
|
|
|
75
76
|
1. Present findings with IDs, severity, evidence, and suggested draft/source changes.
|
|
76
77
|
2. Accept only findings that improve planner correctness, completeness, or downstream execution readiness.
|
|
77
78
|
3. Apply accepted fixes to `.prizmkit/plans/feature-list.draft.json` or the in-memory draft object first.
|
|
78
|
-
4.
|
|
79
|
+
4. For an ordinary incremental additions-only draft, rerun the existing script's append command:
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
python3 ${SKILL_DIR}/scripts/validate-and-generate.py append --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json --replace-tail
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
`--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.
|
|
86
|
+
|
|
87
|
+
For an initial plan or explicit full-list rewrite, regenerate through the existing script's complete-draft command:
|
|
79
88
|
|
|
80
89
|
```bash
|
|
81
90
|
python3 ${SKILL_DIR}/scripts/validate-and-generate.py generate --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
|
|
82
91
|
```
|
|
83
92
|
|
|
84
|
-
5. Re-run
|
|
93
|
+
5. Re-run append/generation until valid. Do not hand-patch `.prizmkit/plans/feature-list.json` as the source of truth.
|
|
85
94
|
6. Repeat the local review and Headless Context Completeness Gate only for entries changed by accepted fixes.
|
|
86
95
|
7. Do not report `PASS` until every required fresh-session answer is available and final validation passes after regeneration.
|
|
87
96
|
|