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
@@ -4,109 +4,124 @@ 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. Treat it as internal transport/recovery state, not as a user approval artifact.
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
+ After consequential decisions and the pre-generation semantic gate pass, immediately 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. Do not ask for separate user approval merely to promote the additions draft into the final list. Fix invalid additions and rerun until valid; during local review, correct the exact current suffix with `append --replace-tail`. Keep the draft through that fix loop. After review returns `PASS` and final validation passes, delete the ordinary internal draft before final handoff. For a later adjustment, recreate only the exact current additions from confirmed in-memory entries or explicit-ID `show` results before using `append --replace-tail`. Use `generate` only for an initial plan or an explicit full-list rewrite.
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
+ - [ ] Atomic append ran immediately after semantic gates without a post-draft approval pause
124
+ - [ ] Existing project conventions preserved from project evidence
125
+ - [ ] Complete merged dependency graph validates through `append`
126
+ - [ ] Ordinary internal draft was deleted after review and final validation, or its retained recovery path and reason were reported
112
127
  - [ ] Next step recommendation: `feature-pipeline-launcher`
@@ -53,12 +53,14 @@ Split into `sub_features` when:
53
53
 
54
54
  ### Phase 6: Generate + Validate
55
55
 
56
- 1. Write `.prizmkit/plans/feature-list.draft.json`.
57
- 2. Generate the final file:
56
+ 1. Write `.prizmkit/plans/feature-list.draft.json` as internal writer/review input after the main Skill's consequential decision and pre-generation gates pass.
57
+ 2. Immediately generate the final file without a separate draft-approval pause:
58
58
  ```bash
59
59
  python3 ${SKILL_DIR}/scripts/validate-and-generate.py generate --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
60
60
  ```
61
- 3. Fix draft errors, then re-run generate.
61
+ 3. Fix draft errors, then re-run `generate` until validation passes.
62
+ 4. Run the main Skill's mandatory Local Generated-Plan Review and apply accepted fixes through the complete draft.
63
+ 5. After review returns `PASS` and final validation passes, delete the ordinary internal draft before final handoff. Retain it only under the main Skill's explicit recovery conditions and report the reason.
62
64
 
63
65
  ## Quality Rules
64
66
 
@@ -77,5 +79,6 @@ Split into `sub_features` when:
77
79
  - [ ] User confirmed initial feature scope
78
80
  - [ ] IDs are sequential
79
81
  - [ ] `status` initialized to `pending`
80
- - [ ] Validation passes
82
+ - [ ] Validation and Local Generated-Plan Review pass
83
+ - [ ] Ordinary internal draft was deleted, or its retained recovery path and reason were reported
81
84
  - [ ] 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,
@@ -74,11 +74,11 @@ Typos, pure formatting, small documentation edits, and other explicitly low-risk
74
74
  | `prizmkit-code-review` | Review, repair, verify, and converge on the supplied change. | `PASS` |
75
75
  | `prizmkit-test` | Test the supplied change with a consistent report/result pair. | `TEST_PASS` |
76
76
  | `prizmkit-retrospective` | Synchronize durable documentation or record no change. | `RETRO_COMPLETE` |
77
- | `prizmkit-committer` | Create a confirmed interactive commit or prepare an exact Runtime request. | `COMMITTED` or `COMMIT_REQUEST_READY` |
77
+ | `prizmkit-committer` | Automatically create a validated direct local commit, or explicitly prepare an exact Runtime request. | `COMMITTED` or `COMMIT_REQUEST_READY` |
78
78
 
79
79
  ### `prizmkit-workflow`
80
80
 
81
- Use for a one-entry formal requirement workflow. It coordinates all six lifecycle skills, preserves one `artifact_dir`, routes failures, and stops for commit confirmation. It handles exactly one requirement per invocation.
81
+ Use for a one-entry formal requirement workflow. It coordinates all six lifecycle skills, preserves one `artifact_dir`, routes failures, and continues through the validated local commit without another confirmation pause. It handles exactly one requirement per invocation.
82
82
 
83
83
  ### `prizmkit-init`
84
84
 
@@ -121,7 +121,7 @@ Automatic outer repair is limited to three rounds. The workflow stops with a res
121
121
 
122
122
  ## Commit and Deployment Boundary
123
123
 
124
- The active coordinator validates all required evidence before invoking `prizmkit-committer` with exact `evidence_paths` and any caller-state `excluded_paths`. Interactive use confirms and creates a local commit. Preparation use returns `COMMIT_REQUEST_READY` without Git mutation; the injected Prompt records its pending state and Python Runtime executes the request.
124
+ The active coordinator validates all required evidence before invoking `prizmkit-committer` with exact `evidence_paths` and, for direct execution, only the exact causal bookkeeping path whose finalization must follow the commit. Direct use automatically validates and creates a local commit without another confirmation. Explicit preparation use returns `COMMIT_REQUEST_READY` without Git mutation; the injected Prompt records its pending state and Python Runtime executes the request.
125
125
 
126
126
  Pushing to a remote is a separate explicit action. Deployment is always a separate invocation of `/prizmkit-deploy`.
127
127
 
@@ -139,7 +139,7 @@ Then:
139
139
  1. Optionally run /prizmkit-init when entering a project for the first time.
140
140
  2. Start a formal requirement with /prizmkit-plan.
141
141
  3. Continue through implement → code-review → test → retrospective → committer.
142
- 4. For interactive use, confirm the local commit when `/prizmkit-committer operation=interactive-commit` presents it; pipeline runtimes use preparation mode and execute Git themselves.
142
+ 4. Direct `/prizmkit-committer` use validates and creates the local commit automatically; pipeline runtimes keep using explicit preparation mode and execute Git themselves.
143
143
  5. Invoke /prizmkit-deploy separately when deployment or operations work is needed.
144
144
  ```
145
145
 
@@ -151,7 +151,7 @@ The toolkit does not promise universal automatic handoff, universal deployment a
151
151
 
152
152
  If the user says only "ship it", ask whether they mean:
153
153
 
154
- 1. Use `/prizmkit-committer operation=interactive-commit` for a user-confirmed local commit, or preparation mode when a Python pipeline runtime owns Git execution.
154
+ 1. Use `/prizmkit-committer operation=interactive-commit` for an automatically validated local commit, or preparation mode when a Python pipeline runtime owns Git execution.
155
155
  2. Deploy or operate the project with `/prizmkit-deploy`.
156
156
 
157
157
  Do not route an ambiguous "ship it" directly to either action.
@@ -1,14 +1,14 @@
1
1
  ---
2
2
  name: "prizmkit-committer"
3
- description: "Perform one commit stage for a caller-supplied final change. Either review, preview, confirm, and commit the complete Git-visible workspace interactively, or validate it and prepare a pathless Runtime commit request without Git mutation. Returns only commit-stage results. (project)"
3
+ description: "Perform one commit stage for a caller-supplied final change. By default, validate and automatically commit the complete Git-visible workspace locally without a confirmation pause. An explicit prepare-runtime-commit operation still writes the pathless Runtime request without Git mutation. Returns only commit-stage results. (project)"
4
4
  ---
5
5
 
6
6
  # PrizmKit Committer
7
7
 
8
- `/prizmkit-committer` handles one caller-supplied final workspace through one explicit operation:
8
+ `/prizmkit-committer` handles one caller-supplied final workspace through one commit operation:
9
9
 
10
- - `operation=interactive-commit`: inspect the complete Git-visible workspace, preview it, confirm it, stage it, commit it, and verify it locally.
11
- - `operation=prepare-runtime-commit`: validate the complete Git-visible workspace and write a pathless Runtime request without staging or committing.
10
+ - direct/default invocation or `operation=interactive-commit`: inspect the complete Git-visible workspace, report the validated candidate, then stage, commit, and verify it locally without asking for another confirmation;
11
+ - explicit `operation=prepare-runtime-commit`: validate the complete Git-visible workspace and write a pathless Runtime request without staging or committing.
12
12
 
13
13
  Remote publication is outside this Skill.
14
14
 
@@ -17,18 +17,18 @@ Remote publication is outside this Skill.
17
17
  | Parameter | Required | Description |
18
18
  |---|---|---|
19
19
  | `artifact_dir` | Yes | Exact caller-supplied artifact root for this commit stage. |
20
- | `operation` | Yes | `interactive-commit` or `prepare-runtime-commit`. |
20
+ | `operation` | No | Defaults to direct local commit. `interactive-commit` is the compatible explicit name for that behavior; `prepare-runtime-commit` must be supplied explicitly for request-only preparation. |
21
21
  | `evidence_paths` | Yes | Exact caller-supplied artifacts that establish final Review/Test/Retrospective readiness. |
22
- | `causal_bookkeeping_path` | Interactive conditional | The one exact caller-owned coordinator state whose truthful finalization must follow this commit. It cannot exclude ordinary content. |
22
+ | `causal_bookkeeping_path` | Direct-commit conditional | The one exact caller-owned coordinator state whose truthful finalization must follow this commit. It cannot exclude ordinary content. |
23
23
  | `request_path` | Preparation only | Must equal `{artifact_dir}/runtime-commit-request.json`. |
24
24
 
25
- There is no caller-supplied commit-path manifest, support-path admission record, or ownership classification. Do not discover another artifact root or infer the operation from provider, platform, prompt style, tracking policy, checkout cleanliness, or human availability.
25
+ There is no caller-supplied commit-path manifest, support-path admission record, or ownership classification. Do not discover another artifact root or choose preparation mode from provider, platform, prompt style, tracking policy, checkout cleanliness, or human availability. Reject any non-empty `operation` value other than `interactive-commit` or `prepare-runtime-commit`. Only explicit `operation=prepare-runtime-commit` selects request-only preparation; an omitted operation or `operation=interactive-commit` uses direct local commit.
26
26
 
27
27
  ## Stage Boundary
28
28
 
29
- This Skill owns only final-workspace inspection and its selected commit operation. It does not invoke another Skill or repair incorrect content.
29
+ This Skill owns only final-workspace inspection and its selected commit operation. It does not invoke another Skill or repair incorrect content. Each invocation creates at most one local commit and never amends, resets, merges, pushes, opens a pull request, deploys, or publishes.
30
30
 
31
- In preparation mode it must not stage, unstage, commit, amend, reset, merge, or push. It may write only the exact Runtime request after validation succeeds.
31
+ In preparation mode it must not stage, unstage, or commit. It may write only the exact Runtime request after validation succeeds.
32
32
 
33
33
  ## Complete Git-Visible Workspace
34
34
 
@@ -40,11 +40,11 @@ The candidate commit is the complete current Git-visible workspace:
40
40
 
41
41
  Ignored files remain naturally absent, stay local, do not block, and are never force-added. Git visibility is independent of path provenance: product, test, documentation, `.prizmkit`, generated, instruction, lock, host-support, or previously existing content receives no namespace-based admission or exclusion. A non-clean starting checkout is acceptable when the combined final workspace is correct and fully validated.
42
42
 
43
- The only non-final Git-visible content that may remain outside a commit snapshot is exact active coordinator/Runtime bookkeeping whose final mutation cannot truthfully precede the commit: one validated caller-supplied interactive coordinator-state path, or the automated request/checkpoint and post-commit receipt. This is a causal operation boundary, not a directory allowlist, denylist, or general exclusion mechanism.
43
+ The only non-final Git-visible content that may remain outside a commit snapshot is exact active coordinator/Runtime bookkeeping whose final mutation cannot truthfully precede the commit: one validated caller-supplied direct-commit coordinator-state path, or the automated request/checkpoint and post-commit receipt. This is a causal operation boundary, not a directory allowlist, denylist, or general exclusion mechanism.
44
44
 
45
45
  ## Step 1: Validate Evidence and the Complete Final Workspace
46
46
 
47
- 1. Resolve `artifact_dir`, every `evidence_paths` entry, the optional interactive `causal_bookkeeping_path`, and preparation `request_path` exactly as supplied. Reject any causal path not proven to be the active caller-owned coordinator state finalized after this operation.
47
+ 1. Resolve `artifact_dir`, every `evidence_paths` entry, the optional direct-commit `causal_bookkeeping_path`, and preparation `request_path` exactly as supplied. Reject any causal path not proven to be the active caller-owned coordinator state finalized after this operation.
48
48
  2. Reject missing, unreadable, stale, contradictory, blocked, or explicitly non-passing readiness evidence.
49
49
  3. Inventory staged, unstaged, untracked, deleted, renamed, and copied Git-visible files with bounded Git status and diff commands. Do not discover ignored files. Identify only the exact active causal bookkeeping path for the selected operation; every other visible path remains a candidate.
50
50
  4. Inspect every candidate path and its relevant diff/content. Correct pre-existing or requirement-adjacent changes may be included even when they were not created in the current implementation session.
@@ -65,19 +65,16 @@ Generate one concise single-line Conventional Commit message describing the comb
65
65
 
66
66
  A heterogeneous but coherent workspace may use the narrowest truthful shared scope and description. If no truthful single commit description exists, block as incoherent content rather than silently omit files.
67
67
 
68
- ## Step 3A: Interactive Commit
68
+ ## Step 3A: Direct Local Commit
69
69
 
70
- For `operation=interactive-commit`:
70
+ For a default/direct invocation or `operation=interactive-commit`:
71
71
 
72
- 1. Present the complete Git-visible candidate set, the exact validated interactive causal bookkeeping path retained locally when visible, change summary, diff statistics, sensitive-content result, proposed message, and a clear statement that confirmation covers every candidate while ignored files stay local.
73
- 2. Ask the current user to confirm that complete local commit.
74
- 3. If the workspace changes after preview, repeat whole-workspace validation and preview before using the confirmation.
75
- 4. Only after confirmation, stage the complete workspace with ordinary `git add -A -- .` semantics, then reset only the validated `causal_bookkeeping_path` in the index to `HEAD` when it is Git-visible. Never force-add ignored content or accept any other exclusion.
76
- 5. Verify that the staged paths equal the in-memory confirmed candidate set, no non-ignored unstaged/untracked candidate remains outside the exact causal state, no incidental path appeared, and the staged snapshot still passes global sensitive-content checks.
77
- 6. Create the local commit and verify its hash, single parent, message, committed path set, and remaining Git-visible workspace against the confirmed snapshot.
78
- 7. Return `COMMITTED`, commit hash/message, committed paths, and any remaining ignored or causal bookkeeping content that is intentionally local.
79
-
80
- If confirmation is declined, return `COMMIT_DECLINED` without Git mutation.
72
+ 1. Report the complete Git-visible candidate set, the exact validated causal bookkeeping path retained locally when visible, change summary, diff statistics, sensitive-content result, proposed message, and that every candidate will be committed while ignored files stay local. This is an informational report, not a confirmation gate.
73
+ 2. Immediately before Git mutation, repeat the bounded whole-workspace status, evidence-freshness, merge-state, and sensitive-content checks. If the workspace changed, rebuild the candidate and message and validate again; block when coherence or safety cannot be re-established. Never ask the user merely to continue the validated commit.
74
+ 3. Stage the complete workspace with ordinary `git add -A -- .` semantics, then reset only the validated `causal_bookkeeping_path` in the index to `HEAD` when it is Git-visible. Never force-add ignored content or accept any other exclusion.
75
+ 4. Verify that the staged paths equal the latest validated candidate set, no non-ignored unstaged/untracked candidate remains outside the exact causal state, no incidental path appeared, and the staged snapshot still passes global sensitive-content checks.
76
+ 5. Create the local commit and verify its hash, single parent, message, committed path set, and remaining Git-visible workspace against the validated snapshot.
77
+ 6. Return `COMMITTED`, commit hash/message, committed paths, and any remaining ignored or causal bookkeeping content that is intentionally local.
81
78
 
82
79
  ## Step 3B: Runtime Commit Request
83
80
 
@@ -110,10 +107,10 @@ Schema version 1 path-manifest requests are not silently reinterpreted as worksp
110
107
 
111
108
  ## Output
112
109
 
113
- Interactive operation returns exactly one of:
110
+ Direct/default and `interactive-commit` operations return exactly one of:
114
111
 
115
112
  ```text
116
- COMMITTED | COMMIT_DECLINED | COMMIT_BLOCKED
113
+ COMMITTED | COMMIT_BLOCKED
117
114
  ```
118
115
 
119
116
  Preparation operation returns exactly one of: