prizmkit 1.1.174 → 1.1.176

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (23) hide show
  1. package/bundled/VERSION.json +3 -3
  2. package/bundled/rules/prizm/prizm-commit-workflow.md +3 -3
  3. package/bundled/skills/_metadata.json +1 -1
  4. package/bundled/skills/bug-planner/SKILL.md +46 -43
  5. package/bundled/skills/bug-planner/references/error-recovery.md +24 -24
  6. package/bundled/skills/bug-planner/references/generated-plan-review.md +24 -11
  7. package/bundled/skills/bug-planner/scripts/validate-bug-list.py +216 -1
  8. package/bundled/skills/feature-planner/SKILL.md +39 -30
  9. package/bundled/skills/feature-planner/references/error-recovery.md +25 -15
  10. package/bundled/skills/feature-planner/references/generated-plan-review.md +24 -11
  11. package/bundled/skills/feature-planner/references/incremental-feature-planning.md +85 -70
  12. package/bundled/skills/feature-planner/references/new-project-planning.md +7 -4
  13. package/bundled/skills/feature-planner/scripts/validate-and-generate.py +213 -0
  14. package/bundled/skills/prizmkit/SKILL.md +5 -5
  15. package/bundled/skills/prizmkit-committer/SKILL.md +21 -24
  16. package/bundled/skills/prizmkit-workflow/SKILL.md +8 -8
  17. package/bundled/skills/prizmkit-workflow/references/workflow-state-protocol.md +5 -5
  18. package/bundled/skills/refactor-planner/SKILL.md +47 -14
  19. package/bundled/skills/refactor-planner/references/error-recovery.md +16 -8
  20. package/bundled/skills/refactor-planner/references/fast-path.md +6 -5
  21. package/bundled/skills/refactor-planner/references/generated-plan-review.md +24 -11
  22. package/bundled/skills/refactor-planner/scripts/validate-and-generate-refactor.py +213 -0
  23. package/package.json +1 -1
@@ -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 ("validate", "generate"):
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
 
@@ -48,7 +48,7 @@ The user chose this skill intentionally. Respect that choice.
48
48
 
49
49
  **Your ONLY writable outputs are:**
50
50
  1. `.prizmkit/plans/feature-list.json` (`.prizmkit/plans/`)
51
- 2. Draft backups in `.prizmkit/plans/` (e.g., `feature-list.draft.json`)
51
+ 2. Planner-owned draft state in `.prizmkit/plans/` (e.g., `feature-list.draft.json`) while it is required for deterministic writing, review repair, or explicit recovery
52
52
 
53
53
  **After planning is complete**, you MUST:
54
54
  1. Present the summary and recommended next step (invoking `feature-pipeline-launcher` )
@@ -57,6 +57,10 @@ The user chose this skill intentionally. Respect that choice.
57
57
  4. **NEVER auto-execute** the pipeline, launcher, composite workflow, or any implementation step
58
58
  5. Return the validated list to the caller; only `feature-pipeline-launcher` prepares the runtime command
59
59
 
60
+ ## Draft Lifecycle (Hard Rule)
61
+
62
+ In an ordinary successful flow, `.prizmkit/plans/feature-list.draft.json` is internal writer/review input, not a user approval artifact or separate deliverable. Keep it through `generate`/`append`, validation, and the complete Local Generated-Plan Review fix loop. After the Local Generated-Plan Review returns `PASS` and final validation passes, delete the ordinary internal draft before final handoff. Report `Draft cleanup: removed`. Present the final written result. Retain the draft only for explicit draft-save, interruption or blocking before terminal gates, or cleanup failure; report its path and reason. Cleanup failure does not invalidate an already reviewed and validated final list, but makes the file stale recovery state. Never delete explicit recovery state merely because an older valid final exists. For later adjustments, recreate only the minimum source draft from confirmed in-memory entries or exact-ID `show`; ordinary appends must preserve the exact current suffix and use `append --replace-tail` without loading unrelated history.
63
+
60
64
  ## Fresh-Session Task Contract (Hard Rule)
61
65
 
62
66
  Every new or changed feature is an executable contract for a fresh AI session that has never seen the planning conversation. Do not add new JSON fields, context objects, schema versions, or pipeline runtime structures. Use the existing fields correctly:
@@ -149,7 +153,7 @@ Before questions, check optional context files (never block if absent):
149
153
  - `.prizmkit/prizm-docs/root.prizm` (architecture/project context — typically created by app-planner with captured decisions)
150
154
  - `.prizmkit/config.json` (existing stack preferences and detected tech stack)
151
155
  - `.prizmkit/plans/project-brief.md` (project context from app-planner, if available)
152
- - existing `.prizmkit/plans/feature-list.json` (required for incremental mode)
156
+ - existing `.prizmkit/plans/feature-list.json` (required for incremental mode; inspect it only through the bounded commands below)
153
157
  - 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
158
  - 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
159
  ```bash
@@ -231,11 +235,16 @@ F-003 | Tooltip copy update | low | Cosmetic clarity only |
231
235
 
232
236
  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
237
 
234
-
235
238
  ---
236
-
239
+ ## Bounded Existing-List Context (Hard Rule)
240
+ 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.
241
+ 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).
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
+ 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
+ 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 internal transport/recovery state, not a user approval artifact. 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, immediately run `append`: `python3 ${SKILL_DIR}/scripts/validate-and-generate.py append --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json`. Do not ask for separate user approval merely to promote the draft into the final list. The command validates the base, IDs, dependencies, and complete DAG before atomic replacement. Apply review fixes only to the bounded additions and rerun `append --replace-tail` for the exact current suffix, then follow §Draft Lifecycle before presenting the final written result. `generate` remains the initial-plan/full-rewrite path.
237
247
  ## Scenario Routing
238
-
239
248
  Classify user intent first:
240
249
 
241
250
  ### Route A: Initial Feature Set for Existing/App-Planned Project
@@ -251,9 +260,9 @@ Use when user already has a `.prizmkit/plans/feature-list.json` and wants to add
251
260
 
252
261
  Actions:
253
262
  1. Load `${SKILL_DIR}/references/incremental-feature-planning.md`
254
- 2. Read existing `.prizmkit/plans/feature-list.json` first (if missing, ask whether to start new plan)
255
- 3. Append features with next sequential `F-NNN` IDs
256
- 4. Preserve style/language/detail consistency with existing plan
263
+ 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
264
+ 3. Append features with the returned next sequential `F-NNN` IDs through the additions-only `append` command
265
+ 4. Preserve confirmed project conventions and self-contained task quality without forcing unrelated recent history into new features
257
266
 
258
267
  ### Route C: Validate Existing Plan
259
268
  Use when the user asks to check or validate an existing plan without adding or changing features.
@@ -305,8 +314,8 @@ Execute the planning workflow in conversation mode with mandatory checkpoints:
305
314
  7. Build or append `.prizmkit/plans/feature-list.json`
306
315
  8. Apply default testing strategy (see §Testing Defaults below)
307
316
  9. Validate and fix until pass
308
- 10. Run the mandatory Local Generated-Plan Review Gate (see §Local Generated-Plan Review Gate below); apply accepted fixes to the draft/source plan, regenerate, and revalidate until pass
309
- 11. Summarize final feature table with local review result and validation outcome
317
+ 10. Run the mandatory Local Generated-Plan Review Gate (see §Local Generated-Plan Review Gate below); apply accepted fixes to the draft/source plan, regenerate, and revalidate until pass, then complete §Draft Lifecycle cleanup
318
+ 11. Summarize final feature table with local review result, validation outcome, and draft cleanup result
310
319
 
311
320
  ### Checkpoints (Mandatory Gates)
312
321
 
@@ -322,7 +331,7 @@ Checkpoints catch cascading errors early — skipping one means the next phase b
322
331
  | **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 |
323
332
  | **CP-FP-4** | `.prizmkit/plans/feature-list.json` Generated | Schema validates, all required keys present | 7-8 |
324
333
  | **CP-FP-5** | Final Validation Pass | Python script returns `"valid": true` with zero errors | 9 |
325
- | **CP-FP-6** | Local Plan Review Passed | Local generated-plan review loaded `${SKILL_DIR}/references/generated-plan-review.md`, reviewed only newly added/changed feature entries, applied accepted fixes through draft/source data, regenerated, and revalidated | 10 |
334
+ | **CP-FP-6** | Local Plan Review Passed | Local generated-plan review loaded `${SKILL_DIR}/references/generated-plan-review.md`, reviewed only newly added/changed feature entries, applied accepted fixes through draft/source data, regenerated, revalidated, and completed terminal draft cleanup or reported why recovery state was retained | 10-11 |
326
335
 
327
336
  **Resume Detection**: If existing artifacts are found, read `${SKILL_DIR}/references/error-recovery.md` §Resume Support for checkpoint-based resumption.
328
337
 
@@ -347,7 +356,7 @@ For simple incremental planning, skip detailed Phase 2-3 analysis:
347
356
  - **No architectural changes** to existing tech stack
348
357
 
349
358
  ### Fast Path Workflow
350
- 1. Read existing `.prizmkit/plans/feature-list.json` and confirm scope
359
+ 1. Run the bounded `context` command from §Bounded Existing-List Context and confirm scope without reading the complete historical list
351
360
  2. **User confirmation (mandatory)** — Use `AskUserQuestion` to present interactive selectable options:
352
361
 
353
362
  ```
@@ -369,12 +378,12 @@ For simple incremental planning, skip detailed Phase 2-3 analysis:
369
378
  3. Generate next sequential feature IDs
370
379
  4. Draft features (title + description + acceptance_criteria + dependencies)
371
380
  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 generate script:
381
+ 6. Write the additions-only draft as internal input and immediately call the append command without a second draft-approval pause:
373
382
  ```bash
374
- python3 ${SKILL_DIR}/scripts/validate-and-generate.py generate --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
383
+ python3 ${SKILL_DIR}/scripts/validate-and-generate.py append --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
375
384
  ```
376
- 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 generate (max 2 attempts, then escalate to full workflow)
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, re-run `append` (max 2 attempts, then escalate to full workflow)
378
387
 
379
388
  ## Browser Interaction Planning
380
389
 
@@ -415,18 +424,22 @@ Key requirements:
415
424
  - `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
425
 
417
426
  **IMPORTANT: Do NOT hand-write the final JSON file.** Instead:
418
- 1. Write a draft JSON to a temporary path (e.g., `.prizmkit/plans/feature-list.draft.json`)
419
- 2. Call the generate script to validate and produce the final file:
420
- ```bash
421
- python3 ${SKILL_DIR}/scripts/validate-and-generate.py generate --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
422
- ```
423
- The script fills in defaults (`$schema`, `created_at`, `created_by`), validates all fields, and writes the final file only if validation passes. If validation fails, fix the draft and retry.
427
+ - Initial plan or explicit full-list rewrite: write the complete draft and use `generate`:
428
+ ```bash
429
+ python3 ${SKILL_DIR}/scripts/validate-and-generate.py generate --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
430
+ ```
431
+ - Ordinary incremental append: follow §Bounded Existing-List Context, write only the additions-only `features` object, and use `append`:
432
+ ```bash
433
+ python3 ${SKILL_DIR}/scripts/validate-and-generate.py append --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
434
+ ```
435
+
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, call `append` immediately after semantic gates; the draft is not a second approval checkpoint. If either command fails, fix its source draft and retry. Do not delete the draft until the Local Generated-Plan Review and final validation pass; then follow §Draft Lifecycle.
424
437
 
425
438
  ## Local Generated-Plan Review Gate
426
439
 
427
440
  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
441
 
429
- Read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the single source of truth. Review the actual draft and final artifacts directly because `.prizmkit` files may be gitignored. Repeat the Headless Context Completeness Gate for every reviewed new or changed 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.
442
+ 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, update ordinary appended entries through `append --replace-tail`, rerun validation, and repeat the local review until it returns `PASS`. Complete §Draft Lifecycle cleanup before reporting the final written result.
430
443
 
431
444
  ## Testing Defaults (Phase 8)
432
445
 
@@ -450,11 +463,7 @@ Recommend invoking `feature-pipeline-launcher` to configure and launch the dev-p
450
463
 
451
464
  If validation fails or a session is interrupted → read `${SKILL_DIR}/references/error-recovery.md` for the full error type table, decision tree, retry logic, and checkpoint-based resume support.
452
465
 
453
- Key behaviors:
454
- - Warnings only → proceed with user approval
455
- - Critical errors → group by type, auto-fix where possible, max 3 total attempts
456
- - Interrupted session → detect checkpoint from existing artifacts, offer resume or restart
457
- - `.prizmkit/plans/feature-list.json` MUST be written to `.prizmkit/plans/` (project root level: `./{root}/.prizmkit/plans/feature-list.json`)
466
+ Key behaviors: continue informational warnings without a draft-promotion pause; clarify consequential warnings; group critical errors and retry safe fixes at most three times; resume interrupted state from actual artifacts; always write the final list at project-root `.prizmkit/plans/feature-list.json`.
458
467
 
459
468
  ## Session Exit Gate
460
469
 
@@ -471,7 +480,7 @@ When the session appears to be ending:
471
480
  1. **Remind**: "You set out to produce `.prizmkit/plans/feature-list.json` but we haven't completed it yet."
472
481
  2. Use `AskUserQuestion` with one question:
473
482
  - **Continue to completion (Recommended)** — resume from current phase
474
- - **Save draft & exit** — write current progress as `.prizmkit/plans/feature-list.draft.json`
483
+ - **Save draft & exit** — write current progress as `.prizmkit/plans/feature-list.draft.json` and retain it as explicit recovery state; terminal cleanup does not apply until planning resumes and completes
475
484
  - **Abandon** — exit without saving
476
485
 
477
486
  ## Handoff Message Template
@@ -480,7 +489,7 @@ After successful validation and the Local Generated-Plan Review Gate, report:
480
489
  1. Output file path
481
490
  2. Total features + newly added features
482
491
  3. Dependency and priority highlights
483
- 4. Local generated-plan review result: verdict, reviewed feature IDs plus reviewed root prose when applicable, accepted fixes (or "none"), and final validation result
492
+ 4. Local generated-plan review result: verdict, reviewed feature IDs plus reviewed root prose when applicable, accepted fixes (or "none"), final validation result, and draft cleanup result (`removed` or retained path/reason)
484
493
  5. Recommended next action: `feature-pipeline-launcher`
485
494
 
486
495
  Then apply the post-planning handoff in §Scope Boundary (ask before proceeding; never auto-execute).
@@ -12,8 +12,8 @@ Script returns JSON with `"valid": false`, `"errors": [...]`, `"warnings": [...]
12
12
  ### Decision Tree
13
13
 
14
14
  **if `error_count == 0` (warnings only):**
15
- - Proceed with user approval
16
- - Show warnings and ask: "Continue? (Y/n)"
15
+ - Continue the deterministic writer/review flow when warnings are informational
16
+ - Ask the user only when a warning exposes a consequential product, scope, compatibility, or verification decision; do not add a generic draft-promotion approval
17
17
 
18
18
  **elif `error_count > 0` (critical errors):**
19
19
 
@@ -34,15 +34,14 @@ Group errors by type and apply targeted fixes:
34
34
  ```
35
35
  For auto-fixable errors:
36
36
  1. Show summary: "Found N schema/ID/format issues"
37
- 2. Offer: auto-fix? (Y/n)
38
- 3. Apply fix → regenerate file
39
- 4. Re-run validation
40
- 5. If new errors → loop (max 2 more attempts)
37
+ 2. Apply unambiguous mechanical fixes to the planner-owned draft
38
+ 3. Re-run the matching deterministic writer and validation
39
+ 4. If new errors → loop (max 2 more attempts)
41
40
 
42
- For manual fixes (dependencies, AC content):
43
- 1. Show concise prompt: "Edit line X-Y in feature-list.json"
44
- 2. Wait for user action
45
- 3. Retry validation (max 2 more attempts)
41
+ For semantic fixes (dependencies, acceptance-criteria content):
42
+ 1. Ask only for the consequential missing decision
43
+ 2. Apply the confirmed correction to the planner-owned draft, never directly to the final list
44
+ 3. Re-run the matching writer and validation (max 2 more attempts)
46
45
 
47
46
  if all_retries_exceeded:
48
47
  → Escalate: "After 3 attempts, validation still fails.
@@ -61,13 +60,16 @@ Check for artifact files in `.prizmkit/plans/`:
61
60
  | Artifacts Found | Resume Action |
62
61
  |-----------------|---------------|
63
62
  | None | Start fresh planning (Phase 1) |
64
- | `feature-list.json` exists but not validated | Offer to validate or extend (Phase 9) |
65
- | `feature-list.json` + validation passed | Offer: handoff to `feature-pipeline-launcher` |
66
- | `feature-list.draft.json` only | Resume interactive planning from last checkpoint |
63
+ | `feature-list.json` exists but not validated | Resume writer/validation repair through the source draft |
64
+ | Valid `feature-list.json` only | Offer handoff to `feature-pipeline-launcher` |
65
+ | `feature-list.draft.json` only | Resume interactive planning from the draft's actual completeness |
66
+ | Valid `feature-list.json` plus `feature-list.draft.json` | Treat as interrupted review or cleanup-failure state; inspect the draft and offer to resume review, discard it, or start a new increment rather than assuming either artifact wins |
67
67
 
68
- When existing file detected, suggest:
68
+ When only a valid final list is detected, suggest:
69
69
  > "Existing plan found with N features. Resume incremental planning? (Y/n)"
70
70
 
71
+ When final and draft both exist, identify the two artifacts explicitly and ask whether to resume the unfinished review/recovery state or discard it before starting a new increment.
72
+
71
73
  ### Incremental Mode Abort
72
74
 
73
75
  If in Incremental mode but existing `feature-list.json` not found:
@@ -84,8 +86,16 @@ Before writing, verify the directory exists: `mkdir -p .prizmkit/plans`
84
86
  <project-root>/
85
87
  └── .prizmkit/plans/
86
88
  ├── feature-list.json # Primary output
87
- ├── feature-list.draft.json # Draft backup (Session Exit Gate)
89
+ ├── feature-list.draft.json # Temporary writer/review input or explicit recovery state
88
90
  └── <ISO-timestamp>.backup.json # Optional incremental backups
89
91
  ```
90
92
 
93
+ ## Draft Management
94
+
95
+ - An ordinary writer draft must remain available while generation, append, validation, or Local Generated-Plan Review repair is incomplete.
96
+ - After Local Generated-Plan Review returns `PASS` and final validation passes, delete the ordinary internal draft before handoff.
97
+ - Retain a draft only after explicit **Save draft & exit**, interruption or blocking before terminal gates, or cleanup failure. Report its path and reason.
98
+ - Cleanup failure does not invalidate a reviewed and validated final list, but the retained file is stale recovery state and must be surfaced.
99
+ - If both final and draft exist on resume, do not delete or promote the draft blindly. Determine whether review was interrupted or cleanup failed from the artifacts and available session evidence; ask the user when that outcome remains ambiguous.
100
+
91
101
  > **Note**: For cross-session workflow recovery (e.g., interrupted pipeline execution, branch-level state detection), use `recovery-workflow` instead. This error-recovery reference handles only within-session validation retries and checkpoint resumption.
@@ -6,24 +6,27 @@ Use this local review loop after `.prizmkit/plans/feature-list.json` has been ge
6
6
 
7
7
  Run only when the current `feature-planner` session generated, appended, or rewrote final feature planning content. For validate-only, summary-only, or draft-save flows with no new final planning content, report: `Local generated-plan review: not applicable — no new final planning content written.`
8
8
 
9
+ In ordinary incremental flow, the additions draft is internal transport/recovery state. After consequential decisions and the pre-generation gate pass, immediately run `append`; do not ask for separate user approval merely to promote the draft into the final list. Keep the draft through the bounded review/fix loop, then delete the ordinary internal draft before final handoff only after this review returns `PASS` and final validation passes.
10
+
9
11
  ## Direct Artifact Reads
10
12
 
11
- Planning artifacts may be gitignored, untracked, or absent from staged and unstaged diffs. Read the actual files directly:
13
+ Planning artifacts may be gitignored, untracked, or absent from staged and unstaged diffs. Read the actual files through bounded, source-first access:
12
14
 
13
- - Final list: `.prizmkit/plans/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
15
+ - 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
16
+ - Draft/source list when present: `.prizmkit/plans/feature-list.draft.json` — ordinary incremental flow contains only additions and may be read completely
17
+ - Pre-session final list snapshot if captured in memory before edits — retain only bounded root context, prior task count/next ID, and the five recent `{id, description}` pairs, not full history
16
18
  - In-memory draft object if the session has not written a draft file yet
19
+ - Newly appended or explicitly modified final entries — load each known ID with `python3 ${SKILL_DIR}/scripts/validate-and-generate.py show --input .prizmkit/plans/feature-list.json --id F-NNN`
17
20
 
18
21
  Do not rely on `git status`, `git diff`, or `git diff --cached` to decide whether planner output exists or changed. Do not invoke `/prizmkit-code-review` for this planner-output gate; `/prizmkit-code-review` remains the implementation/code-diff review gate after `/prizmkit-implement`.
19
22
 
20
23
  ## Review Scope
21
24
 
22
- 1. If a pre-session final list exists, compare by stable feature IDs (`F-*`).
23
- 2. Root project prose is reviewable content, not generator metadata. 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`.
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. Read unchanged entries only when needed to verify dependency references from reviewed features.
26
- 5. If no snapshot exists, review all feature entries produced by the current generation flow.
25
+ 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.
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
+ 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
+ 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.
29
+ 5. If no snapshot exists during initial generation, review all entries in that session's complete draft. Absence of a snapshot never authorizes loading unrelated history during append flow.
27
30
 
28
31
  ## Review Checklist
29
32
 
@@ -75,15 +78,24 @@ Do not add new JSON fields, context objects, schema versions, or pipeline runtim
75
78
  1. Present findings with IDs, severity, evidence, and suggested draft/source changes.
76
79
  2. Accept only findings that improve planner correctness, completeness, or downstream execution readiness.
77
80
  3. Apply accepted fixes to `.prizmkit/plans/feature-list.draft.json` or the in-memory draft object first.
78
- 4. Regenerate the final list through the existing generator:
81
+ 4. For an ordinary incremental additions-only draft, rerun the existing script's append command:
82
+
83
+ ```bash
84
+ python3 ${SKILL_DIR}/scripts/validate-and-generate.py append --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json --replace-tail
85
+ ```
86
+
87
+ `--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.
88
+
89
+ For an initial plan or explicit full-list rewrite, regenerate through the existing script's complete-draft command:
79
90
 
80
91
  ```bash
81
92
  python3 ${SKILL_DIR}/scripts/validate-and-generate.py generate --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
82
93
  ```
83
94
 
84
- 5. Re-run validation/generation until valid. Do not hand-patch `.prizmkit/plans/feature-list.json` as the source of truth.
95
+ 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.
85
96
  6. Repeat the local review and Headless Context Completeness Gate only for entries changed by accepted fixes.
86
97
  7. Do not report `PASS` until every required fresh-session answer is available and final validation passes after regeneration.
98
+ 8. After `PASS`, delete `.prizmkit/plans/feature-list.draft.json` before final handoff when it is an ordinary internal draft. Retain it only for explicit draft-save, interruption or blocking before the terminal gates, or cleanup failure; report the retained path and reason. Cleanup failure leaves the reviewed final list valid but must be reported as stale recovery state.
87
99
 
88
100
  ## Report Format
89
101
 
@@ -93,4 +105,5 @@ Report in the final handoff summary:
93
105
  - Reviewed feature IDs and reviewed root prose (`project_description` / `global_context`) when applicable
94
106
  - Accepted fixes, or `none`
95
107
  - Final validation result
108
+ - Draft cleanup result: `removed`, or retained path and recovery reason
96
109
  - Note when review was not applicable because no new final planning content was written