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.
@@ -4,109 +4,122 @@ Use this reference when the user adds features to an existing app/plan.
4
4
 
5
5
  ## Pre-Checks
6
6
 
7
- 1. Read existing `feature-list.json`.
8
- 2. Determine current max ID and continue from next `F-NNN`.
9
- 3. **Detect existing writing style** (see §Style Detection below).
10
- 4. Preserve compatibility with existing dependency structure.
11
- 5. **Project conventions** — handled by the main SKILL.md flow (rule #6) before incremental planning begins. No additional action needed here; conventions are loaded automatically.
7
+ 1. Do not read the complete existing `feature-list.json`. Run:
8
+ ```bash
9
+ python3 ${SKILL_DIR}/scripts/validate-and-generate.py context --input .prizmkit/plans/feature-list.json
10
+ ```
11
+ 2. Consume only `project_name`, `project_description`, `global_context`, `task_count`, `next_id`, and the five most recent `{id, description}` pairs.
12
+ 3. Use the returned `next_id` for the first addition and continue sequentially.
13
+ 4. Preserve confirmed project conventions and dependency correctness without treating recent chronology as relevance.
14
+ 5. Project conventions remain handled by the main `SKILL.md` flow before incremental planning begins.
12
15
 
13
- If `feature-list.json` is missing, ask whether to initialize a new plan.
16
+ If `feature-list.json` is missing, ask whether to initialize a new plan. If the context command reports invalid input or exhausted ID capacity, stop and resolve that explicit blocker instead of reading or rewriting the entire list in AI context.
14
17
 
15
- ## Style Detection (Automatic)
18
+ ## Recent-History Relevance Gate
16
19
 
17
- Before drafting new features, analyze existing plan to preserve consistency:
20
+ The five recent pairs are a bounded continuity and conflict check, not a default source of new feature content.
18
21
 
19
- 1. **Language Detection**
20
- - Scan `title` and `description` fields
21
- - If >70% English titles → default to English
22
- - If >70% Chinese titles → suggest Chinese (or allow bilingual)
22
+ - Add no historical content by default.
23
+ - Inspect recent descriptions only for material continuation, duplication, conflict, a shared public behavior contract, or a real execution prerequisite.
24
+ - Chronology, broad module overlap, shared technology, reusable implementation ideas, and similar wording alone do not establish relevance.
25
+ - When omission would make the new feature's scope, behavior, compatibility, acceptance criteria, or dependency ordering incorrect, incorporate only the minimum exact contract-affecting information into that feature.
26
+ - Do not persist vague text such as `related to F-123` and do not copy an entire historical description merely because it overlaps.
27
+ - Add an old ID to `dependencies` only when it is a real execution prerequisite.
23
28
 
24
- 2. **Description Density**
25
- - Calculate avg word count per description
26
- - If avg <30 words → draft concise descriptions
27
- - If avg 30-80 words → draft standard detail
28
- - If avg >80 words → draft detailed descriptions
29
+ When the user explicitly identifies an old feature ID for modification or detailed review, or a validation error names it, load only that complete top-level feature:
29
30
 
30
- 3. **Acceptance Criteria Patterns**
31
- - Count avg AC per feature
32
- - Identify dominant format (Given/When/Then Gherkin, BDD, or loose)
33
- - Draft new AC in same format
34
-
35
- 4. **Complexity Distribution**
36
- - Count low/medium/high distribution in existing features
37
- - Alert if new features deviate significantly (>20 percentile points)
38
- - Suggest rebalancing if needed
39
-
40
- ### Style Consistency Prompt
41
-
42
- If new features deviate significantly from detected style:
43
-
44
- ```
45
- "Your new features use avg X words/description, but existing features use Y.
46
- Current ratio: low:M%, medium:N%, high:O%.
47
- Adjust new features to match? (Y/n)"
31
+ ```bash
32
+ python3 ${SKILL_DIR}/scripts/validate-and-generate.py show --input .prizmkit/plans/feature-list.json --id F-NNN
48
33
  ```
49
34
 
50
- Accept user choice, then adjust draft accordingly before JSON generation.
35
+ Do not perform default full-history keyword search.
51
36
 
52
37
  ## Incremental Planning Flow
53
38
 
54
39
  ### Step 1: Clarify Increment Scope
40
+
55
41
  Capture:
56
- - business objective of the new increment
57
- - affected existing modules/features
58
- - timeline or priority constraints
42
+ - business objective of the new increment;
43
+ - affected existing capabilities and current project modules established from project evidence;
44
+ - timeline or priority constraints.
59
45
 
60
46
  ### Step 2: Impact Mapping
47
+
61
48
  For each candidate feature, identify:
62
- - upstream dependencies
63
- - downstream impacts
64
- - risk hotspots (auth, data migration, API compatibility)
49
+ - real upstream prerequisites;
50
+ - downstream impacts;
51
+ - risk hotspots such as auth, data migration, and API compatibility.
65
52
 
66
- ### Step 3: Append Features
67
- Append new items only (do not rewrite old validated features unless user asks).
53
+ Use current project evidence as the primary source. The recent five-task window supplies only the narrow relevance evidence permitted by the gate above.
54
+
55
+ ### Step 3: Draft Additions
56
+
57
+ Draft new items only; do not rewrite old validated features unless the user explicitly requested an old ID operation.
68
58
 
69
59
  For each new feature:
70
- - assign next ID
71
- - set `status: "pending"`
72
- - link dependencies to existing IDs where needed
73
- - keep title in English
74
- - **write rich descriptions** (see `planning-guide.md` §4):
75
- - minimum 15 words (validation error below this)
76
- - recommended minimum: 30+ (low), 50+ (medium), 80+ (high), 100+ (critical) — no upper limit, more detail is always better
77
- - include: what to build, key behaviors, integration points, data model, error/edge cases
60
+ - assign the next sequential ID returned by `context`;
61
+ - omit `status` or set it to `pending`;
62
+ - link dependencies to old IDs only for real execution prerequisites;
63
+ - keep the title in English for stable slug generation;
64
+ - write a self-contained description with objective, current and desired behavior, selected decisions, constraints, non-goals, relevant integrations, edge cases, and completion evidence;
65
+ - add concrete measurable acceptance criteria.
66
+
67
+ The additions-only `.prizmkit/plans/feature-list.draft.json` has exactly one root field:
68
+
69
+ ```json
70
+ {
71
+ "features": [
72
+ {
73
+ "id": "F-NNN",
74
+ "title": "English stable title",
75
+ "description": "Self-contained feature contract",
76
+ "priority": "medium",
77
+ "dependencies": [],
78
+ "acceptance_criteria": ["Concrete measurable result"]
79
+ }
80
+ ]
81
+ }
82
+ ```
83
+
84
+ Each item uses the unchanged final feature-item schema. Required draft fields are `id`, `title`, `description`, `priority`, `dependencies`, and `acceptance_criteria`; `status` may be omitted and defaults to `pending`; all existing optional feature fields remain allowed. Root project metadata and historical features must not be copied into this draft.
78
85
 
79
86
  ### Step 4: Rebalance Priority
80
- Allow priority updates for both old and new features if user requests reprioritization.
81
- Keep dependency correctness as first constraint.
82
87
 
83
- ### Step 5: Validate
84
- Write a draft and generate the final list:
88
+ Default to append only. Reprioritizing historical tasks is an explicit old-task modification, not part of ordinary append flow; require the user to identify the affected IDs and load only those tasks with `show`.
89
+
90
+ ### Step 5: Append and Validate
91
+
92
+ Merge the additions-only draft with untouched history outside AI context:
93
+
85
94
  ```bash
86
- python3 ${SKILL_DIR}/scripts/validate-and-generate.py generate --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
95
+ python3 ${SKILL_DIR}/scripts/validate-and-generate.py append --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
87
96
  ```
88
97
 
89
- Fix and re-run until pass.
98
+ The append command validates the existing base, exact sequential new IDs, all old/new dependencies, and the complete DAG before atomically replacing the final list. Fix the additions draft and rerun until valid. Use `generate` only for an initial plan or an explicit full-list rewrite.
90
99
 
91
100
  ## Merge/Rewrite Rules
92
101
 
93
- - Default: append only
94
- - Rewrite existing features only when user explicitly asks
95
- - Never break valid IDs/references
96
- - Never set new features to `in_progress` or `completed`
102
+ - Default: append only through the additions-only draft.
103
+ - Preserve every historical task and root value unchanged.
104
+ - Rewrite existing features only when the user explicitly identifies them.
105
+ - Never break valid IDs/references.
106
+ - Never set new features to `in_progress` or `completed`.
97
107
 
98
108
  ## Practical Prompts
99
109
 
100
110
  Use concise prompts during interaction:
101
- - "What is the goal of this increment? Which user problem is the priority?"
102
- - "Which existing Feature IDs do these new features depend on?"
103
- - "Do you want to reprioritize at the same time, or just append to the current sequence?"
111
+ - “What is the goal of this increment? Which user problem is the priority?”
112
+ - “Does any of the five recent descriptions represent a real continuation, conflict, shared contract, or prerequisite? If not, no historical content will be carried forward.”
113
+ - “Do you want only an append, or are you explicitly modifying identified historical Feature IDs?”
104
114
 
105
115
  ## Final Delivery Checklist
106
116
 
107
- - [ ] Existing file read before edits
108
- - [ ] New IDs continue sequence
109
- - [ ] Existing style preserved
110
- - [ ] Dependency graph still DAG
111
- - [ ] Validation passes
117
+ - [ ] Bounded `context` command used; complete historical list not loaded
118
+ - [ ] At most five recent `{id, description}` pairs inspected
119
+ - [ ] No historical content added by default
120
+ - [ ] Any incorporated history is minimum, contract-affecting, and task-scoped
121
+ - [ ] Old dependency IDs represent real execution prerequisites
122
+ - [ ] Additions-only draft contains no root metadata or historical features
123
+ - [ ] Existing project conventions preserved from project evidence
124
+ - [ ] Complete merged dependency graph validates through `append`
112
125
  - [ ] Next step recommendation: `feature-pipeline-launcher`
@@ -6,6 +6,9 @@ for the dev-pipeline system.
6
6
  Commands:
7
7
  validate Validate an existing .prizmkit/plans/feature-list.json
8
8
  template Generate a blank template .prizmkit/plans/feature-list.json
9
+ context Print bounded project context plus the five most recent features
10
+ show Print one explicitly requested top-level feature
11
+ append Merge an additions-only draft into an existing validated list
9
12
  generate Validate a draft JSON and generate final feature-list.json with defaults
10
13
  summary Print a summary table of features from a .prizmkit/plans/feature-list.json
11
14
  grade Generate grading results from eval runs (for npm run skill:review)
@@ -13,6 +16,9 @@ Commands:
13
16
  Usage:
14
17
  python3 validate-and-generate.py validate --input .prizmkit/plans/feature-list.json [--output validated.json]
15
18
  python3 validate-and-generate.py template --output .prizmkit/plans/feature-list.json
19
+ python3 validate-and-generate.py context --input .prizmkit/plans/feature-list.json
20
+ python3 validate-and-generate.py show --input .prizmkit/plans/feature-list.json --id F-001
21
+ python3 validate-and-generate.py append --input additions.json --output .prizmkit/plans/feature-list.json
16
22
  python3 validate-and-generate.py generate --input draft.json --output .prizmkit/plans/feature-list.json
17
23
  python3 validate-and-generate.py summary --input .prizmkit/plans/feature-list.json [--format markdown|json]
18
24
  python3 validate-and-generate.py grade --workspace /.codebuddy/skill-evals/feature-planner-workspace --iteration iteration-1
@@ -26,10 +32,12 @@ Python 3.6+ required. No external dependencies.
26
32
 
27
33
  import argparse
28
34
  import collections
35
+ import copy
29
36
  import json
30
37
  import os
31
38
  import re
32
39
  import sys
40
+ import tempfile
33
41
  from datetime import datetime, timezone
34
42
 
35
43
  # ---------------------------------------------------------------------------
@@ -115,6 +123,25 @@ def _write_json(path, data):
115
123
  fh.write("\n")
116
124
 
117
125
 
126
+ def _write_json_atomic(path, data):
127
+ """Atomically replace *path* with pretty-printed JSON data."""
128
+ parent = os.path.dirname(os.path.abspath(path))
129
+ if parent and not os.path.isdir(parent):
130
+ os.makedirs(parent, exist_ok=True)
131
+ fd, temp_path = tempfile.mkstemp(prefix=".feature-list-", suffix=".tmp", dir=parent)
132
+ try:
133
+ with os.fdopen(fd, "w", encoding="utf-8") as fh:
134
+ json.dump(data, fh, indent=2, ensure_ascii=False)
135
+ fh.write("\n")
136
+ os.replace(temp_path, path)
137
+ except Exception:
138
+ try:
139
+ os.unlink(temp_path)
140
+ except OSError:
141
+ pass
142
+ raise
143
+
144
+
118
145
  # ---------------------------------------------------------------------------
119
146
  # Cycle detection (Kahn's algorithm)
120
147
  # ---------------------------------------------------------------------------
@@ -745,6 +772,148 @@ def cmd_template(args):
745
772
  return 0
746
773
 
747
774
 
775
+ def _load_valid_existing(path):
776
+ """Load and validate one existing feature list."""
777
+ data, load_err = _load_json(path)
778
+ if load_err:
779
+ _err(load_err)
780
+ return None, None, 2
781
+ if not isinstance(data, dict):
782
+ _err("Feature list root must be an object")
783
+ return None, None, 1
784
+
785
+ result = validate_feature_list(data, is_new_plan=False)
786
+ if not result["valid"]:
787
+ _err("Existing feature list is invalid")
788
+ for error in result["errors"]:
789
+ _err(" " + error)
790
+ return None, result, 1
791
+ return data, result, 0
792
+
793
+
794
+ def _next_top_level_id(features):
795
+ """Return the next F-NNN ID, or None when numeric capacity is exhausted."""
796
+ numbers = []
797
+ for feature in features:
798
+ match = FEATURE_ID_RE.match(str(feature.get("id", "")))
799
+ if match:
800
+ numbers.append(int(str(feature["id"])[2:5]))
801
+ next_number = max(numbers, default=0) + 1
802
+ if next_number > 999:
803
+ return None
804
+ return "F-{:03d}".format(next_number)
805
+
806
+
807
+ def cmd_context(args):
808
+ """Print bounded existing-list context for incremental planning."""
809
+ data, _, exit_code = _load_valid_existing(args.input)
810
+ if exit_code:
811
+ return exit_code
812
+
813
+ features = data["features"]
814
+ next_id = _next_top_level_id(features)
815
+ if next_id is None:
816
+ _err("Feature ID capacity exhausted at F-999")
817
+ return 1
818
+
819
+ context = {
820
+ "project_name": data.get("project_name"),
821
+ "project_description": data.get("project_description"),
822
+ "global_context": data.get("global_context") or {},
823
+ "task_count": len(features),
824
+ "next_id": next_id,
825
+ "recent_tasks": [
826
+ {"id": feature.get("id"), "description": feature.get("description")}
827
+ for feature in features[-5:]
828
+ ],
829
+ }
830
+ print(json.dumps(context, indent=2, ensure_ascii=False))
831
+ return 0
832
+
833
+
834
+ def cmd_show(args):
835
+ """Print one explicitly requested top-level feature."""
836
+ data, _, exit_code = _load_valid_existing(args.input)
837
+ if exit_code:
838
+ return exit_code
839
+ if not FEATURE_ID_RE.match(str(args.id)):
840
+ _err("Feature ID '{}' must match F-NNN or F-NNN-X".format(args.id))
841
+ return 1
842
+
843
+ for feature in data["features"]:
844
+ if feature.get("id") == args.id:
845
+ print(json.dumps(feature, indent=2, ensure_ascii=False))
846
+ return 0
847
+ _err("Feature '{}' not found".format(args.id))
848
+ return 1
849
+
850
+
851
+ def cmd_append(args):
852
+ """Append a collection-only draft to an existing validated feature list."""
853
+ base, _, exit_code = _load_valid_existing(args.output)
854
+ if exit_code:
855
+ return exit_code
856
+
857
+ draft, load_err = _load_json(args.input)
858
+ if load_err:
859
+ _err(load_err)
860
+ return 2
861
+ if not isinstance(draft, dict) or set(draft.keys()) != {"features"}:
862
+ _err("Additions draft must be an object containing only 'features'")
863
+ return 1
864
+ additions = draft.get("features")
865
+ if not isinstance(additions, list) or not additions:
866
+ _err("Additions draft 'features' must be a non-empty array")
867
+ return 1
868
+ if not all(isinstance(feature, dict) for feature in additions):
869
+ _err("Every feature addition must be an object")
870
+ return 1
871
+
872
+ merge_base = copy.deepcopy(base)
873
+ if args.replace_tail:
874
+ addition_ids = [feature.get("id") for feature in additions]
875
+ tail_ids = [feature.get("id") for feature in base["features"][-len(additions):]]
876
+ if len(base["features"]) < len(additions) or tail_ids != addition_ids:
877
+ _err("--replace-tail requires additions IDs to match the existing final-list suffix exactly")
878
+ return 1
879
+ merge_base["features"] = merge_base["features"][:-len(additions)]
880
+
881
+ next_id = _next_top_level_id(merge_base["features"])
882
+ if next_id is None:
883
+ _err("Feature ID capacity exhausted at F-999")
884
+ return 1
885
+ start_number = int(next_id[2:])
886
+ prepared = copy.deepcopy(additions)
887
+ for offset, feature in enumerate(prepared):
888
+ expected_id = "F-{:03d}".format(start_number + offset)
889
+ if start_number + offset > 999:
890
+ _err("Feature ID capacity exhausted at F-999")
891
+ return 1
892
+ if feature.get("id") != expected_id:
893
+ _err("Feature addition {} must use next sequential ID '{}'".format(offset, expected_id))
894
+ return 1
895
+ feature.setdefault("status", "pending")
896
+
897
+ merged = copy.deepcopy(merge_base)
898
+ merged["features"].extend(prepared)
899
+ result = validate_feature_list(merged, is_new_plan=False)
900
+ result["appended_ids"] = [feature["id"] for feature in prepared]
901
+ print(json.dumps(result, indent=2, ensure_ascii=False))
902
+ if not result["valid"]:
903
+ _err("Merged feature list validation failed")
904
+ for error in result["errors"]:
905
+ _err(" " + error)
906
+ return 1
907
+
908
+ try:
909
+ _write_json_atomic(args.output, merged)
910
+ except Exception as exc:
911
+ _err("Failed to write merged feature list: {}".format(exc))
912
+ return 2
913
+ _info("Appended {} feature(s) to {}".format(len(prepared), args.output))
914
+ return 0
915
+
916
+
748
917
  def cmd_generate(args):
749
918
  """Handle the 'generate' command.
750
919
 
@@ -943,6 +1112,9 @@ def main():
943
1112
  " %(prog)s validate --input .prizmkit/plans/feature-list.json\n"
944
1113
  " %(prog)s validate --input .prizmkit/plans/feature-list.json --output validated.json\n"
945
1114
  " %(prog)s template --output .prizmkit/plans/feature-list.json\n"
1115
+ " %(prog)s context --input .prizmkit/plans/feature-list.json\n"
1116
+ " %(prog)s show --input .prizmkit/plans/feature-list.json --id F-001\n"
1117
+ " %(prog)s append --input additions.json --output .prizmkit/plans/feature-list.json\n"
946
1118
  " %(prog)s generate --input draft.json --output .prizmkit/plans/feature-list.json\n"
947
1119
  " %(prog)s summary --input .prizmkit/plans/feature-list.json\n"
948
1120
  " %(prog)s summary --input .prizmkit/plans/feature-list.json --format json\n"
@@ -972,6 +1144,44 @@ def main():
972
1144
  "--output", required=True, help="Path to write template file"
973
1145
  )
974
1146
 
1147
+ # -- context --
1148
+ p_context = subparsers.add_parser(
1149
+ "context",
1150
+ help="Print root context and the five most recent feature id/description pairs",
1151
+ )
1152
+ p_context.add_argument(
1153
+ "--input", required=True, help="Path to existing .prizmkit/plans/feature-list.json"
1154
+ )
1155
+
1156
+ # -- show --
1157
+ p_show = subparsers.add_parser(
1158
+ "show",
1159
+ help="Print one explicitly requested top-level feature",
1160
+ )
1161
+ p_show.add_argument(
1162
+ "--input", required=True, help="Path to existing .prizmkit/plans/feature-list.json"
1163
+ )
1164
+ p_show.add_argument(
1165
+ "--id", required=True, help="Exact top-level feature ID"
1166
+ )
1167
+
1168
+ # -- append --
1169
+ p_append = subparsers.add_parser(
1170
+ "append",
1171
+ help="Append a features-only draft to an existing validated feature list",
1172
+ )
1173
+ p_append.add_argument(
1174
+ "--input", required=True, help="Path to additions-only draft JSON"
1175
+ )
1176
+ p_append.add_argument(
1177
+ "--output", required=True, help="Path to existing final feature-list.json"
1178
+ )
1179
+ p_append.add_argument(
1180
+ "--replace-tail",
1181
+ action="store_true",
1182
+ help="Replace the exact existing suffix with the same IDs after local review",
1183
+ )
1184
+
975
1185
  # -- generate --
976
1186
  p_generate = subparsers.add_parser(
977
1187
  "generate",
@@ -1024,6 +1234,9 @@ def main():
1024
1234
  dispatch = {
1025
1235
  "validate": cmd_validate,
1026
1236
  "template": cmd_template,
1237
+ "context": cmd_context,
1238
+ "show": cmd_show,
1239
+ "append": cmd_append,
1027
1240
  "generate": cmd_generate,
1028
1241
  "summary": cmd_summary,
1029
1242
  "grade": cmd_grade,
@@ -142,7 +142,7 @@ Before questions, check optional context files (never block if absent):
142
142
  - `.prizmkit/prizm-docs/root.prizm` (architecture/project context)
143
143
  - `.prizmkit/config.json` (existing stack preferences and detected tech stack)
144
144
  - Existing test suite (critical for behavior preservation assessment)
145
- - Existing `.prizmkit/plans/refactor-list.json` (if appending additional items)
145
+ - Existing `.prizmkit/plans/refactor-list.json` (if appending additional items; inspect it only through the bounded commands below)
146
146
  - If `.prizmkit/prizm-docs/root.prizm` is absent and the project has existing source code, scan the directory structure:
147
147
  ```bash
148
148
  find . -maxdepth 2 -type d -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/__pycache__/*' -not -path '*/vendor/*' | sed -e 's;[^/]*/;|____;g;s;____|; |;g'
@@ -153,6 +153,28 @@ Before questions, check optional context files (never block if absent):
153
153
  - If no test suite detected, WARN: "No test suite found. Behavior preservation will rely on manual verification. Consider writing tests before refactoring."
154
154
  - Record test suite status in planning context for downstream use
155
155
 
156
+ ## Bounded Existing-List Context (Hard Rule)
157
+
158
+ For any flow that appends to an existing `.prizmkit/plans/refactor-list.json`, NEVER read the complete historical list into AI context and NEVER perform default full-history keyword search.
159
+
160
+ 1. Load only bounded project and recent-task context:
161
+ ```bash
162
+ python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py context --input .prizmkit/plans/refactor-list.json
163
+ ```
164
+ Consume only `project_name`, `project_description`, `global_context`, `task_count`, `next_id`, and exactly the five most recently appended top-level refactors as `{id, description}` pairs (or all available refactors when fewer than five exist).
165
+ 2. Inspect those five pairs only for material continuation, duplication, conflict, a shared public behavior contract, or an execution prerequisite. Add no historical content by default. Chronology, broad module overlap, shared technology, reusable implementation ideas, or similar wording alone do not establish relevance.
166
+ 3. When a material relationship exists, incorporate only the minimum exact information whose omission would make the new refactor's scope, behavior preservation, compatibility, acceptance criteria, or dependency ordering incorrect. Do not write vague text such as `related to R-123`, do not copy an entire historical description merely because it overlaps, and add an old ID to `dependencies` only when it is a real execution prerequisite.
167
+ 4. Load a complete historical refactor only when the user explicitly identifies its ID for modification or detailed review, or a validation error identifies it:
168
+ ```bash
169
+ python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py show --input .prizmkit/plans/refactor-list.json --id R-NNN
170
+ ```
171
+ 5. For append-only planning, write `.prizmkit/plans/refactor-list.draft.json` as an additions-only object with exactly one root field, `refactors`. The array must be non-empty; each item uses the unchanged final refactor-item schema, with required `id`, `title`, `description`, `scope`, `type`, `priority`, `complexity`, `behavior_preservation`, `dependencies`, and `acceptance_criteria`; `status` may be omitted and defaults to `pending`; all existing optional refactor fields remain allowed. Do not copy root metadata or historical refactors into this draft.
172
+ 6. Merge and validate outside AI context:
173
+ ```bash
174
+ python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py append --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
175
+ ```
176
+ The command validates the existing base, sequential new IDs, dependencies, and the complete DAG before atomically replacing the final list. Existing `generate` behavior remains the full-draft path for a new list and explicit full-list rewrites.
177
+
156
178
  ## Operation Modes
157
179
 
158
180
  ### Mode A: Interactive (default)
@@ -293,12 +315,17 @@ See `${SKILL_DIR}/references/planning-phases.md` for the full 5-step review chec
293
315
  **Goal**: Produce `.prizmkit/plans/refactor-list.json` and validate it.
294
316
 
295
317
  **IMPORTANT: Do NOT hand-write the final JSON file.** Instead:
296
- 1. Write a draft JSON to `.prizmkit/plans/refactor-list.draft.json` with all collected refactor data.
297
- 2. Call the generate script to validate and produce the final file:
298
- ```bash
299
- python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py generate --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
300
- ```
301
- The script fills in defaults (`$schema`, `created_at`, `created_by`), validates all fields, and writes the final file only if validation passes.
318
+ 1. For a new list, write the complete `.prizmkit/plans/refactor-list.draft.json`. For an existing list, follow §Bounded Existing-List Context and write only the additions-only `refactors` object.
319
+ 2. Use the matching deterministic writer:
320
+ - New list or explicit full-list rewrite:
321
+ ```bash
322
+ python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py generate --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
323
+ ```
324
+ - Ordinary existing-list append:
325
+ ```bash
326
+ python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py append --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
327
+ ```
328
+ `generate` fills root defaults for a complete draft. `append` preserves root metadata and historical refactors, defaults missing new statuses, and writes only after the merged full list validates.
302
329
  3. If validation fails -> fix the draft and retry (max 3 attempts)
303
330
  4. If validation passes -> run the mandatory Local Generated-Plan Review Gate (see §Local Generated-Plan Review Gate below); apply accepted fixes to the draft/source plan, regenerate, and revalidate until pass
304
331
  5. If review and validation pass -> present final summary
@@ -324,7 +351,7 @@ See `${SKILL_DIR}/references/planning-phases.md` for the full 5-step review chec
324
351
 
325
352
  Run this gate after `.prizmkit/plans/refactor-list.json` passes generation and validation, and before the final handoff. It applies whenever this session added or changed final refactor entries. For validate-only, summary-only, or draft-save flows with no final content change, report that the gate is not applicable.
326
353
 
327
- 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 refactor. 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.
354
+ Read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the single source of truth. Review the actual additions-only draft and use bounded `context` plus explicit-ID `show` for new or changed final entries because `.prizmkit` files may be gitignored; do not load unchanged historical entries. Repeat the Headless Context Completeness Gate for every reviewed new or changed refactor. Keep the review planning-only, apply accepted findings to the draft/source representation, regenerate the final JSON, rerun validation, and repeat local review until it returns `PASS` before reporting the result.
328
355
 
329
356
  ## Output Rules
330
357
 
@@ -10,7 +10,7 @@ For simple refactoring with minimal scope.
10
10
  - Existing test coverage for target area
11
11
 
12
12
  ## Fast Path Workflow
13
- 1. Confirm refactoring scope with user
13
+ 1. If `.prizmkit/plans/refactor-list.json` exists, run the parent Skill's bounded `context` command and consume only root context plus the five recent `{id, description}` pairs; never read the complete historical list or perform default keyword search. Then confirm refactoring scope with the user.
14
14
  2. **User confirmation (mandatory)** — Use `AskUserQuestion` to present interactive selectable options:
15
15
 
16
16
  ```
@@ -31,12 +31,12 @@ For simple refactoring with minimal scope.
31
31
  **NEVER proceed without explicit user selection via `AskUserQuestion`. Do NOT render options as plain text — the user must be able to click/select.**
32
32
  3. Draft items (title + type + scope + description + acceptance_criteria + behavior_preservation + dependencies)
33
33
  4. Run the mandatory Phase 6 Headless Context Completeness Gate on every drafted item; repair the draft until each returns `PASS` without conversation history or `user_context`.
34
- 5. Write draft to `.prizmkit/plans/refactor-list.draft.json`, then call the generate script:
34
+ 5. Write `.prizmkit/plans/refactor-list.draft.json`. For a new list, use the complete final-list draft and `generate`; for an existing list, write only the additions-only `refactors` object and call:
35
35
  ```bash
36
- python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py generate --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
36
+ python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py append --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
37
37
  ```
38
38
  6. If valid -> run the mandatory Local Generated-Plan Review Gate from the main `refactor-planner` skill before summarizing or recommending `refactor-pipeline-launcher`.
39
- 7. If invalid -> apply fixes to the draft, re-run generate (max 2 attempts, then escalate to full workflow)
39
+ 7. If invalid -> apply fixes to the draft and re-run the same writer (`generate` for a new list, `append` for an existing list; max 2 attempts, then escalate to full workflow)
40
40
 
41
41
  ## When NOT to Use Fast Path
42
42
  - More than 2 refactor items
@@ -8,22 +8,23 @@ Run only when the current `refactor-planner` session generated, appended, or rew
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/refactor-list.json`
14
- - Draft/source list when present: `.prizmkit/plans/refactor-list.draft.json`
15
- - Pre-session final list snapshot if captured in memory before edits
13
+ - Final list: `.prizmkit/plans/refactor-list.json` — run the `context` command for root prose and recent IDs; do not load the complete historical list into AI context
14
+ - Draft/source list when present: `.prizmkit/plans/refactor-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-refactor.py show --input .prizmkit/plans/refactor-list.json --id R-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 refactor IDs (`R-*`).
23
- 2. Root project prose is reviewable content, not generator metadata. Review new or changed `project_description` and `global_context` even when no refactor item changed. Ignore root generator metadata and formatting-only differences such as `$schema`, `created_at`, and `created_by`.
24
- 3. Treat refactors as changed only when item fields changed; review newly added refactor IDs and changed refactor IDs.
25
- 4. Preserve unchanged historical refactors. Read unchanged entries only when needed to verify dependency references or behavior-preservation interactions with reviewed refactors.
26
- 5. If no snapshot exists, review all refactor entries produced by the current generation flow.
23
+ 1. For ordinary append flow, use the additions-only draft and the append result's stable refactor IDs (`R-*`) as the change set; do not compare complete pre/post historical arrays in AI context.
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 refactor item changed. Ignore root generator metadata and formatting-only differences such as `$schema`, `created_at`, and `created_by`.
25
+ 3. Treat refactors as changed only when item fields changed; load and review newly added refactor IDs and explicitly changed refactor IDs through `show`.
26
+ 4. Preserve unchanged historical refactors. Do not load unchanged entries merely to establish review completeness. Use the full-list validator for dependency/DAG truth; use `show` for an old dependency or behavior-preservation interaction only when a specific reviewed refactor requires semantic inspection.
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 behavior-preserving execution readiness.
76
77
  3. Apply accepted fixes to `.prizmkit/plans/refactor-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-and-generate-refactor.py append --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-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-and-generate-refactor.py generate --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
81
90
  ```
82
91
 
83
- 5. Re-run validation/generation until valid. Do not hand-patch `.prizmkit/plans/refactor-list.json` as the source of truth.
92
+ 5. Re-run append/generation until valid. Do not hand-patch `.prizmkit/plans/refactor-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