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.
@@ -1,5 +1,5 @@
1
1
  {
2
- "frameworkVersion": "1.1.174",
3
- "bundledAt": "2026-08-08T02:37:10.579Z",
4
- "bundledFrom": "b12b5d8"
2
+ "frameworkVersion": "1.1.175",
3
+ "bundledAt": "2026-08-08T09:53:47.266Z",
4
+ "bundledFrom": "17d8555"
5
5
  }
@@ -1,5 +1,5 @@
1
1
  {
2
- "version": "1.1.174",
2
+ "version": "1.1.175",
3
3
  "skills": {
4
4
  "prizmkit": {
5
5
  "description": "Framework introduction and navigation for the formal single-requirement lifecycle, project initialization, Prizm docs, and independent deployment.",
@@ -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. Read existing `.prizmkit/plans/bug-fix-list.json` first (if missing, ask whether to start new plan)
176
- 2. Continue with next sequential `B-NNN` IDs
177
- 3. Preserve existing entries, append new bugs
178
- 4. Re-run validation on the merged list
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**: Write a draft `.prizmkit/plans/bug-fix-list.draft.json` with all collected bug data. Conform to `.prizmkit/dev-pipeline/templates/bug-fix-list-schema.json`.
325
- 2. **Generate and validate**: Run the generate script to validate and produce the final file:
326
- ```bash
327
- python3 ${SKILL_DIR}/scripts/validate-bug-list.py generate --input .prizmkit/plans/bug-fix-list.draft.json --output .prizmkit/plans/bug-fix-list.json
328
- ```
329
- The script fills in defaults (`$schema`, `created_at`, `created_by`), validates all fields, and writes the final file only if validation passes.
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 artifacts directly because `.prizmkit` files may be gitignored. 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.
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, call the generate script:
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, call the generate script:
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 directly:
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. If a pre-session final list exists, compare by stable bug IDs (`B-*`).
23
- 2. Root project prose is reviewable content, not generator metadata. 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`.
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. Read unchanged entries only when needed to verify dependency references, duplicate handling, or root-cause overlap with reviewed bugs.
26
- 5. If no snapshot exists, review all bug entries produced by the current generation flow.
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. Regenerate the final list through the existing generator:
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 validation/generation until valid. Do not hand-patch `.prizmkit/plans/bug-fix-list.json` as the source of truth.
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 ("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
 
@@ -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. 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
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. Read existing `.prizmkit/plans/feature-list.json` and confirm scope
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 generate script:
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 generate --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
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 generate (max 2 attempts, then escalate to full workflow)
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
- 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.
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 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.
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 directly:
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. 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.
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. Regenerate the final list through the existing generator:
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 validation/generation until valid. Do not hand-patch `.prizmkit/plans/feature-list.json` as the source of truth.
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