prizmkit 1.1.180 → 1.1.182

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.180",
3
- "bundledAt": "2026-09-08T17:45:34.677Z",
4
- "bundledFrom": "6b16941"
2
+ "frameworkVersion": "1.1.182",
3
+ "bundledAt": "2026-09-17T02:06:17.607Z",
4
+ "bundledFrom": "b336a5e"
5
5
  }
@@ -26,8 +26,6 @@ PrizmKit uses three JSON plan-list schemas under `dev-pipeline/templates/`:
26
26
  ## Feature-Specific Fields
27
27
 
28
28
  - `estimated_complexity`: maps feature work to `lite`, `standard`, or `full` prompt modes.
29
- - `session_granularity`: feature, sub-feature, or auto execution strategy.
30
- - `sub_features`: optional sub-feature decomposition.
31
29
  - `completion_notes`: downstream dependency context after completion.
32
30
  - `testing`: optional testing expectations for the scoped test gate.
33
31
 
@@ -19,9 +19,7 @@
19
19
  "TypeScript compiles without errors",
20
20
  "ESLint and Prettier configs applied"
21
21
  ],
22
- "status": "pending",
23
- "session_granularity": "feature",
24
- "sub_features": []
22
+ "status": "pending"
25
23
  },
26
24
  {
27
25
  "id": "F-002",
@@ -39,9 +37,7 @@
39
37
  "Protected API routes reject unauthenticated requests",
40
38
  "Session persists across page refreshes"
41
39
  ],
42
- "status": "pending",
43
- "session_granularity": "feature",
44
- "sub_features": []
40
+ "status": "pending"
45
41
  },
46
42
  {
47
43
  "id": "F-003",
@@ -59,9 +55,7 @@
59
55
  "Delete task with confirmation",
60
56
  "Task validation enforced on both client and server"
61
57
  ],
62
- "status": "pending",
63
- "session_granularity": "feature",
64
- "sub_features": []
58
+ "status": "pending"
65
59
  },
66
60
  {
67
61
  "id": "F-004",
@@ -79,20 +73,7 @@
79
73
  "Project-level task filtering",
80
74
  "Team member list with role display"
81
75
  ],
82
- "status": "pending",
83
- "session_granularity": "auto",
84
- "sub_features": [
85
- {
86
- "id": "F-004-A",
87
- "title": "Project CRUD & Organization",
88
- "description": "Create, read, update, delete projects. Associate tasks with projects."
89
- },
90
- {
91
- "id": "F-004-B",
92
- "title": "Team & Permissions",
93
- "description": "Team creation, member invitation, role-based access control."
94
- }
95
- ]
76
+ "status": "pending"
96
77
  },
97
78
  {
98
79
  "id": "F-005",
@@ -110,9 +91,7 @@
110
91
  "Graceful fallback when WebSocket disconnects",
111
92
  "No duplicate notifications"
112
93
  ],
113
- "status": "pending",
114
- "session_granularity": "feature",
115
- "sub_features": []
94
+ "status": "pending"
116
95
  },
117
96
  {
118
97
  "id": "F-006",
@@ -131,9 +110,7 @@
131
110
  "Project progress bars",
132
111
  "Date range filtering for all charts"
133
112
  ],
134
- "status": "pending",
135
- "session_granularity": "feature",
136
- "sub_features": []
113
+ "status": "pending"
137
114
  }
138
115
  ],
139
116
  "global_context": {
@@ -42,16 +42,20 @@ REQUIRED_FEATURE_FIELDS = [
42
42
  "acceptance_criteria",
43
43
  "status",
44
44
  ]
45
- ALLOWED_FEATURE_FIELDS = set(REQUIRED_FEATURE_FIELDS) | {
45
+ CURRENT_FEATURE_FIELDS = set(REQUIRED_FEATURE_FIELDS) | {
46
46
  "estimated_complexity",
47
- "session_granularity",
48
- "sub_features",
49
47
  "model",
50
48
  "completion_notes",
51
49
  "user_context",
52
50
  "browser_interaction",
53
51
  "testing",
54
52
  }
53
+ # Historical lists may still carry these keys. They are ignored residue, not
54
+ # current planning fields, and must not fail unknown-field validation.
55
+ LEFTOVER_IGNORED_FEATURE_FIELDS = {
56
+ "session_granularity",
57
+ "sub_features",
58
+ }
55
59
 
56
60
 
57
61
  def parse_args():
@@ -149,7 +153,11 @@ def validate_features(features):
149
153
  "Feature at index {} missing required field: {}".format(i, field)
150
154
  )
151
155
 
152
- unknown = set(feature) - ALLOWED_FEATURE_FIELDS
156
+ unknown = (
157
+ set(feature)
158
+ - CURRENT_FEATURE_FIELDS
159
+ - LEFTOVER_IGNORED_FEATURE_FIELDS
160
+ )
153
161
  if unknown:
154
162
  errors.append(
155
163
  "Feature at index {} has unknown fields: {}".format(
@@ -45,7 +45,7 @@
45
45
  "id": {
46
46
  "type": "string",
47
47
  "pattern": "^F-\\d{3}(-[A-Z])?$",
48
- "description": "Feature ID, format F-001, F-002... Optional sub-feature suffix: F-001-A"
48
+ "description": "Feature ID, format F-001, F-002..."
49
49
  },
50
50
  "title": {
51
51
  "type": "string",
@@ -106,41 +106,8 @@
106
106
  ],
107
107
  "description": "Feature status. Pipeline manages status transitions automatically."
108
108
  },
109
- "session_granularity": {
110
- "type": "string",
111
- "enum": [
112
- "feature",
113
- "sub_feature",
114
- "auto"
115
- ],
116
- "default": "feature",
117
- "description": "Session execution strategy: feature=one-session-per-feature, sub_feature=one-session-per-sub-feature, auto=pipeline-decides"
118
- },
119
- "sub_features": {
120
- "type": "array",
121
- "items": {
122
- "type": "object",
123
- "required": [
124
- "id",
125
- "title",
126
- "description"
127
- ],
128
- "properties": {
129
- "id": {
130
- "type": "string",
131
- "pattern": "^F-\\d{3}-[A-Z]$"
132
- },
133
- "title": {
134
- "type": "string",
135
- "minLength": 1
136
- },
137
- "description": {
138
- "type": "string",
139
- "minLength": 1
140
- }
141
- }
142
- }
143
- },
109
+ "session_granularity": {},
110
+ "sub_features": {},
144
111
  "model": {
145
112
  "type": "string",
146
113
  "description": "AI model ID for this feature. Overrides $MODEL env var."
@@ -777,6 +777,40 @@ def test_init_scripts_reject_unknown_item_fields(tmp_path):
777
777
  assert any("unknown fields: unexpected_field" in error for error in payload["errors"])
778
778
 
779
779
 
780
+ def test_init_pipeline_accepts_historical_leftover_nested_fields(tmp_path):
781
+ paths = _make_paths(tmp_path / "init-feature-leftover-nested")
782
+ items = _family_items("feature", [("F-001", [], "pending")])
783
+ items[0]["session_granularity"] = "auto"
784
+ items[0]["sub_features"] = [
785
+ {
786
+ "id": "F-001-A",
787
+ "title": "Nested leftover",
788
+ "description": "Unused nested work that Runtime never scheduled.",
789
+ }
790
+ ]
791
+ plan_path = _write_family_plan(paths, "feature", items)
792
+ result = subprocess.run(
793
+ [
794
+ PYTHON_310_PLUS,
795
+ str(PIPELINE_ROOT / "scripts" / "init-pipeline.py"),
796
+ "--feature-list",
797
+ str(plan_path),
798
+ "--state-dir",
799
+ str(paths.project_root / ".prizmkit" / "state" / "init-feature-leftover-nested"),
800
+ ],
801
+ cwd=REPO_ROOT,
802
+ stdout=subprocess.PIPE,
803
+ stderr=subprocess.PIPE,
804
+ text=True,
805
+ check=False,
806
+ )
807
+
808
+ assert result.returncode == 0, (result.stdout, result.stderr)
809
+ payload = json.loads(result.stdout)
810
+ assert payload["valid"] is True
811
+ assert "errors" not in payload or payload["errors"] == []
812
+
813
+
780
814
  @pytest.mark.parametrize("location", ("root", "global_context"))
781
815
  def test_init_scripts_reject_unknown_list_fields(tmp_path, location):
782
816
  script_config = {
@@ -861,6 +895,38 @@ def test_planner_validators_reject_unknown_item_fields():
861
895
  assert any("unknown fields: unexpected_field" in error for error in result["errors"])
862
896
 
863
897
 
898
+ def test_feature_planner_validator_accepts_historical_leftover_nested_fields():
899
+ from importlib.util import module_from_spec, spec_from_file_location
900
+
901
+ script_path = REPO_ROOT / (
902
+ "core/skills/orchestration-skill/pipelines/feature-planner/scripts/validate-and-generate.py"
903
+ )
904
+ spec = spec_from_file_location("feature_planner_leftover_nested", script_path)
905
+ module = module_from_spec(spec)
906
+ spec.loader.exec_module(module)
907
+ items = _family_items("feature", [("F-001", [], "pending")])
908
+ items[0]["description"] = (
909
+ "Historical list item that already stored unused nested leftover "
910
+ "fields from an older planner and must still validate successfully."
911
+ )
912
+ items[0]["session_granularity"] = "auto"
913
+ items[0]["sub_features"] = [
914
+ {
915
+ "id": "F-001-A",
916
+ "title": "Nested leftover",
917
+ "description": "Unused nested work that Runtime never scheduled.",
918
+ }
919
+ ]
920
+ result = module.validate_feature_list({
921
+ "$schema": "dev-pipeline-feature-list-v1",
922
+ "project_name": "Fake",
923
+ "features": items,
924
+ })
925
+
926
+ assert result["valid"] is True, result["errors"]
927
+ assert "total_sub_features" not in result["stats"]
928
+
929
+
864
930
  @pytest.mark.parametrize("location", ("root", "global_context"))
865
931
  def test_planner_validators_reject_unknown_list_fields(location):
866
932
  from importlib.util import module_from_spec, spec_from_file_location
@@ -1,5 +1,5 @@
1
1
  {
2
- "version": "1.1.180",
2
+ "version": "1.1.182",
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.",
@@ -66,7 +66,7 @@ These notes are maintainer records for option-derived design modules. Do not inj
66
66
  | `{{ test_coverage }}` | Q15 answer | `Shared components + critical path E2E` |
67
67
  | `{{ unit_test_framework }}` | Q16 answer | `Vitest` |
68
68
  | `{{ e2e_framework }}` | Q17 answer | `Playwright` |
69
- | `{{ ai_max_lines }}` | Q22 answer (number) | `300` |
69
+ | `{{ ai_max_lines }}` | Q22 answer | `No numeric file-size limit. Prefer extraction when a change would make an already-long file longer.` |
70
70
  | `{{ lcp_target }}` | Q23 answer | `<2.5s` |
71
71
  | `{{ font_strategy }}` | Q4b answer | Direct fill |
72
72
  | `{{ bundle_size }}` | Q24 answer | `<300KB (<100KB gzipped)` |
@@ -156,7 +156,8 @@ Appendix placeholders are auto-generated by AI in Phase 4:
156
156
  | Q20 = No | `D-AI-BREAK-LOOSE-01` | `{{ ai_breaking_change_rule }}` |
157
157
  | Q21 = Forbid; config files must be manually edited | `D-AI-CONFIG-FRONTEND-STRICT-01` | `{{ ai_config_rule }}` |
158
158
  | Q21 = Allowed, must explain each change | `D-AI-CONFIG-FRONTEND-LOOSE-01` | `{{ ai_config_rule }}` |
159
- | Q22 = Any value N | `D-AI-LINES-01` (replace `{{ ai_max_lines }}`) | `{{ ai_max_lines }}` |
159
+ | Q22 = 200 / 300 / 500 | `D-AI-LINES-01` | `{{ ai_max_lines }}` |
160
+ | Q22 = No numeric limit | `D-AI-LINES-NONE-01` | `{{ ai_max_lines }}` |
160
161
  | Q23 = LCP <2.5s | `D-PERF-25-01` | `{{ performance_rules }}` |
161
162
  | Q23 = LCP <1.5s | `D-PERF-15-01` | `{{ performance_rules }}` |
162
163
  | Q23 = Not required yet | `D-PERF-NONE-01` | `{{ performance_rules }}` |
@@ -189,8 +190,10 @@ Appendix placeholders are auto-generated by AI in Phase 4:
189
190
  ### D-REACT-02
190
191
  **Trigger**: Q1 = React | **Inject into**: `{{ style_specific_rules }}` (only when Q4 is not CSS-in-JS)
191
192
 
192
- - React components use `clsx` / `classnames` to concatenate className. Forbid string concatenation.
193
- - Conditional styles must be expressed in `clsx`. Avoid ternary operator stacking.
193
+ - Compose `className` values without inventing a helper package.
194
+ - If `clsx` or `classnames` is already in `package.json`, use that installed helper for conditional classes and do not reintroduce ad-hoc string concatenation for the same cases.
195
+ - If neither helper is installed, follow the project's existing composition pattern (for example array `.filter(Boolean).join(' ')` or equivalent). Do not add `clsx` or `classnames` unless Q19 authorizes a new dependency.
196
+ - Never emit Must-install for `clsx` or `classnames` when they are absent and Q19 forbids self-initiated dependencies.
194
197
 
195
198
  ### D-VUE-01
196
199
  **Trigger**: Q1 = Vue 3 | **Inject into**: `{{ tech_stack_rules }}`
@@ -287,7 +290,9 @@ Appendix placeholders are auto-generated by AI in Phase 4:
287
290
  - Extract as `@apply` component class (only for generic semantic components), or
288
291
  - Split into sub-components.
289
292
  - State variant order fixed: `base → hover → focus → active → disabled → dark`.
290
- - Forbid writing complex conditional class string concatenation in templates. Must use `clsx` or `tailwind-variants` / `cva`.
293
+ - Forbid writing complex conditional class string concatenation in templates.
294
+ - If `clsx`, `tailwind-variants`, or `cva` is already in `package.json`, use that installed helper for complex conditional classes.
295
+ - If none of those helpers are installed, extract a sub-component or `@apply` class instead of adding a package, unless Q19 authorizes the dependency.
291
296
  - Recommend installing and enabling `prettier-plugin-tailwindcss` for automatic utility class sorting. This remains non-binding unless already selected or present.
292
297
  - Dense tables and lists: do not rely on `nowrap` or `max-width` without truncation or wrapping. Cover primitive defaults such as `whitespace-nowrap` on table cells. Do not stack `min-width` / `min-w-*` tracks that overflow the content pane. `nowrap` is only for short status, numeric, or action cells.
293
298
 
@@ -601,8 +606,20 @@ Appendix placeholders are auto-generated by AI in Phase 4:
601
606
  - Search the relevant component ownership areas before creating a duplicate; do not invent or periodically maintain an unselected index file. Never invent `src/components/index.ts` when no component registry was detected or selected.
602
607
 
603
608
  ### D-AI-LINES-01
604
- **Trigger**: Q22 = N | **Inject into**: `{{ ai_max_lines }}`
605
- **Generation rule**: Directly replace the placeholder with the user's chosen value (200 / 300 / 500 / no limit).
609
+ **Trigger**: Q22 = 200 / 300 / 500 | **Inject into**: `{{ ai_max_lines }}`
610
+ **Generation rule**: Replace the placeholder with the selected number plus an explicit no-checker statement.
611
+
612
+ - Record the selected file-size preference of N lines.
613
+ - There is no automated line-count checker, split hint, lint, or CI gate for this number.
614
+ - Prefer extraction when a change would make an already-long file longer, instead of appending unrelated responsibility.
615
+ - Legitimate long files such as generated parsers or schema/type collections may stay long.
616
+
617
+ ### D-AI-LINES-NONE-01
618
+ **Trigger**: Q22 = No numeric limit | **Inject into**: `{{ ai_max_lines }}`
619
+
620
+ - No numeric file-size limit.
621
+ - Prefer extraction when a change would make an already-long file longer, instead of appending unrelated responsibility.
622
+ - Legitimate long files such as generated parsers or schema/type collections may stay long.
606
623
 
607
624
  ### D-PERF-25-01
608
625
  **Trigger**: Q23 = LCP < 2.5s | **Inject into**: `{{ performance_rules }}`
@@ -818,7 +835,7 @@ Appendix placeholders are auto-generated by AI in Phase 4:
818
835
  | `{{ test_coverage }}` | Q15 answer | Direct fill |
819
836
  | `{{ unit_test_framework }}` | Q16 answer | Direct fill |
820
837
  | `{{ e2e_framework }}` | Q17 answer | Direct fill |
821
- | `{{ ai_max_lines }}` | Q22 answer | Direct fill (D-AI-LINES-01) |
838
+ | `{{ ai_max_lines }}` | Q22 answer | Direct fill (D-AI-LINES-01 / D-AI-LINES-NONE-01) |
822
839
  | `{{ lcp_target }}` | Q23 answer | Direct fill |
823
840
  | `{{ bundle_size }}` | Q24 answer | Direct fill |
824
841
  | `{{ token_layering_rules }}` | D-TOKEN-{1L/2L/3L}-01 | Derivation |
@@ -299,12 +299,12 @@ Total: 25 questions.
299
299
  ### Q22. AI Single File Generation Limit
300
300
  - **Options**:
301
301
  - A) 200 lines
302
- - B) 300 lines **【Recommended】**
302
+ - B) 300 lines
303
303
  - C) 500 lines
304
- - D) No limit
305
- - **Strict option**: A
306
- - **Note**: Exceeding the limit auto-triggers a split hint to prevent god components.
307
- - **Maps to**: `{{ ai_max_lines }}` (appears in TL;DR + §3.3 + §7.3 + §8.2 — AI replaces the value in all locations)
304
+ - D) No numeric limit **【Recommended】**
305
+ - **Strict option**: D
306
+ - **Note**: There is no automated line-count checker or split hint. Numeric options record a selected preference only. The recommended default is no numeric cap; prefer extraction when a change would make an already-long file longer.
307
+ - **Maps to**: `{{ ai_max_lines }}` (Decision Ledger in §1 and File-size guidance in §6.2)
308
308
 
309
309
  ---
310
310
 
@@ -106,6 +106,7 @@ Check every fixed and derived rule against the ledger:
106
106
  - A selected `none` or `not required` decision suppresses incompatible requirement blocks.
107
107
  - Cross-layer references must agree on shared decisions; report disagreement instead of choosing silently.
108
108
  - If two active rules require incompatible behavior, fail generation, identify both source blocks, repair the source/decision state, and rerun the gate.
109
+ - A Must-level derivation that names a package is incompatible with dependency permission forbid unless that package is already present or the decision ledger selected it. Fail generation rather than emit both.
109
110
 
110
111
  ## Step 7: Render and Validate
111
112
 
@@ -68,11 +68,11 @@ Every new or changed feature is an executable contract for a fresh AI session th
68
68
  1. **Self-contained contract**: The feature's `description` and `acceptance_criteria`, read together, MUST define the objective, current state, desired state, selected decisions, constraints, non-goals, relevant integrations, edge cases, and completion evidence. AI rewrite is allowed; dropping a confirmed item is not. There is no word-count upper limit and no acceptance-criteria count upper limit.
69
69
  2. **Supplementary evidence only**: `user_context` is supplementary evidence only. It may preserve scoped source excerpts and purpose-tagged references, but it MUST NOT expand, replace, or contradict the contract in `description` and `acceptance_criteria`. If `user_context` were removed, a fresh execution session must still know exactly what to implement and how to prove completion.
70
70
  3. **Clarify by impact, do not guess**: Ask when conflicting requirements or multiple plausible antecedents would materially change product behavior, scope, compatibility, safety, cost, or completion evidence. Resolve evidence-backed facts from project context and retain safe low-risk reversible choices as explicit assumptions rather than silently inventing user intent.
71
- 4. **Feature isolation**: In multi-feature planning, each written task contract and its supplementary evidence contain only material relevant to that feature. Repeat shared context only when it explicitly applies to every affected feature. Isolation does not mean split by module or directory. **Domain grouping**: Group by contract-bounded capability — shared domain objects, state machine, invariants, public API, and error semantics. That grouping is not the same module, directory, or written task contract in `description` and `acceptance_criteria`; independently shippable is not a split reason. MUST NOT populate `sub_features`. Runtime does not inject or schedule nested sub-features. Ask the user only when two groupings would materially change task boundaries.
71
+ 4. **Feature isolation**: In multi-feature planning, each written task contract and its supplementary evidence contain only material relevant to that feature. Repeat shared context only when it explicitly applies to every affected feature. Isolation does not mean split by module or directory. **Domain grouping**: Group by contract-bounded capability — shared domain objects, state machine, invariants, public API, and error semantics. That grouping is not the same module, directory, or written task contract in `description` and `acceptance_criteria`; independently shippable is not a split reason. Before the first user-facing feature table, merge same-domain over-split. Coverage is not one ID per complaint. Ask the user only when two groupings would materially change task boundaries.
72
72
 
73
73
  ### Artifact-Wide AI Readability
74
74
 
75
- - Every generated natural-language value must be a standalone domain statement. This applies to all AI-visible fields and sections, including `project_description`, `global_context`, titles, descriptions, acceptance criteria, rationales, `sub_features`, `completion_notes`, `testing`, `user_context`, evidence and environment text, browser verification goals, comments, appendices, and parentheticals.
75
+ - Every generated natural-language value must be a standalone domain statement. This applies to all AI-visible fields and sections, including `project_description`, `global_context`, titles, descriptions, acceptance criteria, rationales, `completion_notes`, `testing`, `user_context`, evidence and environment text, browser verification goals, comments, appendices, and parentheticals.
76
76
  - Machine metadata such as schema markers, stable IDs, statuses, enums, and timestamps is exempt. Natural-language metadata is not exempt.
77
77
  - Never emit dialogue-role or chronology labels such as `user said`, `user answered`, `original request`, `this round`, `previous discussion`, `as discussed earlier`, `用户本轮回答`, or `如前面讨论`. Never emit planning question IDs, answer tokens, planning-option recommendation markers, checkpoint provenance, or raw internal answer-map entries as domain content.
78
78
  - `user_context` may hold independently intelligible evidence, not transcript fragments. Rewrite every confirmed turn into direct product behavior, constraints, rationale, or verification evidence before generation.
@@ -118,7 +118,7 @@ Trigger conditions are covered by the frontmatter `description`. Do NOT use this
118
118
  ## Resource Loading Rules (Mandatory)
119
119
 
120
120
  1. **Planning reference** — load before writing feature descriptions:
121
- - Read `${SKILL_DIR}/assets/planning-guide.md` for description writing standards, acceptance criteria patterns, complexity estimation, dependency rules, and contract-bounded grouping
121
+ - Read `${SKILL_DIR}/assets/planning-guide.md` for description writing standards, acceptance criteria patterns, complexity estimation, dependency rules, and contract-bounded grouping. Apply that grouping before the first user-facing feature table.
122
122
 
123
123
  2. **Incremental planning reference** — load for incremental mode:
124
124
  - Read `${SKILL_DIR}/references/incremental-feature-planning.md`
@@ -305,7 +305,7 @@ Execute the planning workflow in conversation mode with mandatory checkpoints:
305
305
 
306
306
  If the user provides materials, require or infer only when unambiguous a task-specific purpose for each material; otherwise ask what the execution AI should inspect. Read/fetch them before Phase 2. For web links, retrieve and analyze the relevant content; for images, analyze the relevant visual evidence. Material ingestion follows the same durability rule as final output: copy or normalize task-relevant requirements and exact evidence, omit transient non-code paths, and retain only purpose-tagged stable execution-time sources. Do not copy complete large materials merely to preserve them.
307
307
  2. Confirm constraints and existing architecture
308
- 3. Propose feature set with dependencies
308
+ 3. Propose feature set with dependencies. **Contract-bounded over-split (Hard Rule)** — Before the first user-facing feature table, merge items that share one contract-bounded capability. Walkthrough notes, complaints, empty states, and button copy default into few capabilities; one complaint per row is forbidden. Long description, many acceptance criteria, and changing frontend and backend together are not split reasons. Split into additional top-level features only when implementation plus verification clearly cannot finish in one existing headless session, typically after two or more heavy capability seams. Ask the user only when two groupings would materially change task boundaries. Present the contract-grained table and note which complaints landed in which item. Users confirm coverage and contract cuts, not a UI-part menu.
309
309
  4. Refine descriptions and acceptance criteria
310
310
  4.1 **Per-feature clarification** — for each feature, ask when multiple interpretations of behavior, acceptance criteria, scope, non-goals, material integrations, or completion evidence would materially change the contract. Resolve evidence-backed details from project context, label low-risk reversible assumptions, and reject conversational shorthand that requires an unseen question, recommendation, or option list. Do not force user confirmation for unconstrained implementation details that a fresh session can safely decide and verify.
311
311
  4.2 **Browser interaction** (mandatory for fullstack/frontend projects) — see §Browser Interaction Planning below. Qualifying features get `browser_interaction` by default. Only confirm with the user as a batch summary; do NOT ask per-feature.
@@ -324,7 +324,7 @@ Checkpoints catch cascading errors early — skipping one means the next phase b
324
324
  | Checkpoint | Artifact/State | Criteria | Phase |
325
325
  |-----------|----------------|----------|-------|
326
326
  | **CP-FP-1** | Scope Confirmed | User confirmed what features to plan and context understood | 1 |
327
- | **CP-FP-2** | Feature Proposals | Feature set with titles+deps identified (pre-validation) | 3-5 |
327
+ | **CP-FP-2** | Feature Proposals | Feature set with titles+deps identified after same-domain over-split (pre-validation); first table is contract-grained | 3-5 |
328
328
  | **CP-FP-3** | DAG Validity | No cycles, dependencies resolved (validation dry-run) | 5 |
329
329
  | **CP-FP-3.1** | Browser Interaction Applied | Qualifying features have `browser_interaction` field; user confirmed or opted out | 4 |
330
330
  | **CP-FP-3.2** | Testing Defaults Applied | All features have appropriate testing expectations | 7 |
@@ -216,14 +216,34 @@ These rules ensure the feature dependency graph is valid and buildable.
216
216
 
217
217
  A **contract-bounded capability** is one business capability whose later session would still need the earlier session's shared domain objects, state machine, invariants, public API, and error semantics. That grouping is not the same module, directory, or written task contract (`description` plus `acceptance_criteria`); independently shippable is not a split reason. Directories and package names are clues only.
218
218
 
219
- Runtime runs one fresh session per top-level feature. MUST NOT populate `sub_features`. MUST NOT set `session_granularity` to `auto` or `sub_feature`. Runtime does not inject or schedule nested sub-features; intent stored there never reaches execution.
219
+ Runtime runs one fresh session per top-level feature.
220
220
 
221
221
  Default: one top-level feature per contract-bounded capability, even when large. Split into additional top-level features only when implementation plus verification clearly cannot finish in one existing headless session, typically after two or more heavy capability seams. Each resulting item still needs a complete `description` plus `acceptance_criteria`.
222
222
 
223
+ ### Before the first user-facing table
224
+
225
+ Run this over-split before presenting titles and dependencies (Phase 3 / CP-FP-2), not only during Phase 6 completeness review:
226
+
227
+ - Shared domain objects, state machine, invariants, public API, and error semantics → one top-level feature
228
+ - Walkthrough notes, complaints, empty states, and button copy: merge into few capabilities first; one complaint per row is forbidden
229
+ - Long `description`, many acceptance criteria, and changing frontend and backend together are not split reasons
230
+ - Ask only when two groupings would materially change task boundaries. Default to the contract-grained table and note which complaints landed in which item.
231
+
232
+ Phase 6 same-domain over-split remains `NEEDS_FIXES` and may still merge. A previously shown row count is not a freeze.
233
+
234
+ ### Misread contrast
235
+
236
+ | Easy misread | Actual requirement |
237
+ |---|---|
238
+ | Do not drop confirmed requirements | Write the behavior into the same contract. Coverage is not one ID per complaint |
239
+ | One session per feature, so smaller tickets run better | Forbidden as a split reason; prefer one long contract with many acceptance criteria |
240
+ | User confirms which features to plan | Confirming coverage and contract cuts is not the same as confirming how many table rows |
241
+
223
242
  ### Examples
224
243
 
225
244
  - Merge: payment capture, refund, and payment callbacks share money/idempotency contracts → one feature. The contract may be long and may have many acceptance criteria.
226
245
  - Split across domains: payment vs inventory stock reservation (different core contracts) → two features.
227
- - Overflow split: one payment domain that cannot finish in one existing headless session → two top-level features at capability seams (for example user capture vs payouts), never nested `sub_features`.
228
-
229
- Schema may still allow `session_granularity` and `sub_features` on historical lists. Do not use them for new or changed features.
246
+ - Overflow split: one payment domain that cannot finish in one existing headless session → two top-level features at capability seams (for example user capture vs payouts).
247
+ - Walkthrough / complaint list:
248
+ - Bad: a long interaction-complaint list becomes one feature per UI region (search box, unsaved-change dialog, drag-and-drop, preview pane, URL/tab state each get their own ID).
249
+ - Good: shared resource identity and the same mutation/error contract stay one top-level feature. Empty states and button copy land in that same contract. A genuinely separate contract (for example navigation identity that is not the same resource/mutation contract) may be a second top-level feature.
@@ -63,8 +63,8 @@ Look at the feature set as a whole:
63
63
  - **Design necessity**: Does every prescribed component, interface, or dependency map to confirmed intent, an existing contract, or an evidenced risk?
64
64
  - **Evidence status**: Are recommendations and inferred implementation details clearly separated from confirmed product decisions?
65
65
  - **Source conflict**: Does an excerpt describe an earlier alternative that conflicts with the selected final decision?
66
- - **same-domain over-split**: Do two new or changed items share one contract-bounded capability without an existing-headless-session overflow exception? If yes, merge them. Independently shippable is not a split reason.
67
- - **unused nested work**: Does a new or changed item store required work in `sub_features` or only in `user_context`? If yes, `NEEDS_FIXES` — move it into `description` and `acceptance_criteria`.
66
+ - **same-domain over-split**: Do two new or changed items share one contract-bounded capability without an existing-headless-session overflow exception? If yes, merge them. Independently shippable is not a split reason. This gate may still merge after a table was shown; a previously shown row count is not a freeze.
67
+ - **unused nested work**: Does a new or changed item store required work only in `user_context`? If yes, `NEEDS_FIXES` — move it into `description` and `acceptance_criteria`.
68
68
  - **size caps**: Do not treat long descriptions or many acceptance criteria as defects. There is no word-count upper limit and no acceptance-criteria count upper limit.
69
69
 
70
70
  ## Step 4: Present Review and Repair
@@ -71,5 +71,5 @@ F-010: Admin Dashboard (deps: F-006, F-007)
71
71
 
72
72
  - Every app starts with an infrastructure/setup feature (F-001) that has zero dependencies.
73
73
  - Authentication almost always comes second unless the app is fully public.
74
- - Group related functionality into a single contract-bounded capability rather than splitting too finely. Independently shippable is not a split reason. MUST NOT populate `sub_features`.
74
+ - Group related functionality into a single contract-bounded capability rather than splitting too finely. Independently shippable is not a split reason.
75
75
  - If a pattern does not match the app being planned, combine elements from multiple patterns or define a custom decomposition from scratch.
@@ -46,7 +46,7 @@ For every reviewed feature entry, check:
46
46
  - Purpose-tagged stable code, configuration, machine-consumed interface, and URL references; transient non-code planning/evidence paths are replaced by inline task-relevant decisions and excerpts, and large materials are bounded rather than injected in full
47
47
  - Priority/complexity calibration: every reviewed feature has short priority and complexity rationales, medium/low assignments are allowed when criteria fit, and high/high is not used merely because work is framework-related, multi-file, or user-requested
48
48
  - Domain cohesion: same contract-bounded capability stays one top-level item; independently shippable is not a split reason; same-domain over-split is `NEEDS_FIXES` unless implementation plus verification cannot finish in one existing headless session
49
- - Unused nested work: new or changed items MUST NOT populate `sub_features` or use `session_granularity` `auto`/`sub_feature`; Runtime does not inject or schedule nested sub-features
49
+ - Unused nested work: new or changed items MUST NOT store required work only in `user_context`; move it into `description` and `acceptance_criteria`
50
50
  - Injected-field fidelity: confirmed WHAT, constraints, non-goals, boundaries, and completion evidence are in `description` and `acceptance_criteria`; AI rewrite is allowed; dropping a confirmed item is not
51
51
  - Size: there is no word-count upper limit and no acceptance-criteria count upper limit; long contracts are not defects
52
52
  - Browser interaction fields for qualifying frontend/fullstack features when applicable
@@ -56,6 +56,8 @@ Use current project evidence as the primary source. The recent five-task window
56
56
 
57
57
  Draft new items only; do not rewrite old validated features unless the user explicitly requested an old ID operation.
58
58
 
59
+ Group the increment by contract-bounded capability before presenting or writing the additions table. A long idea or complaint list is not one new ID per idea. Merge first; split into additional top-level additions only when one existing headless session cannot finish and the cut is at a heavy capability seam.
60
+
59
61
  For each new feature:
60
62
  - assign the next sequential ID returned by `context`;
61
63
  - omit `status` or set it to `pending`;
@@ -117,6 +119,7 @@ Use concise prompts during interaction:
117
119
  - [ ] Bounded `context` command used; complete historical list not loaded
118
120
  - [ ] At most five recent `{id, description}` pairs inspected
119
121
  - [ ] No historical content added by default
122
+ - [ ] Increment grouped by contract before presenting or writing the additions table
120
123
  - [ ] Any incorporated history is minimum, contract-affecting, and task-scoped
121
124
  - [ ] Old dependency IDs represent real execution prerequisites
122
125
  - [ ] Additions-only draft contains no root metadata or historical features
@@ -44,9 +44,9 @@ Check:
44
44
  - order is executable
45
45
  - priorities align with delivery value and risk
46
46
 
47
- ### Phase 5: Granularity
47
+ ### Phase 5: Contract-Bounded Grouping
48
48
 
49
- Group by contract-bounded capability. Independently shippable is not a split reason. MUST NOT populate `sub_features`.
49
+ Group by contract-bounded capability. Independently shippable is not a split reason. Run this grouping before the first user-facing feature table, including the initial MVP proposal.
50
50
 
51
51
  Split into additional top-level features only when:
52
52
  - implementation plus verification cannot finish in one existing headless session
@@ -49,7 +49,6 @@ SCHEMA_VERSION = "dev-pipeline-feature-list-v1"
49
49
  VALID_STATUSES = {"pending", "in_progress", "completed", "failed", "skipped", "split", "auto_skipped"}
50
50
  VALID_COMPLEXITIES = {"low", "medium", "high", "critical"}
51
51
  VALID_PRIORITIES = {"critical", "high", "medium", "low"}
52
- VALID_GRANULARITIES = {"feature", "sub_feature", "auto"}
53
52
  ALLOWED_LIST_FIELDS = {
54
53
  "$schema", "project_name", "project_description", "created_at",
55
54
  "created_by", "features", "global_context",
@@ -59,14 +58,15 @@ ALLOWED_GLOBAL_CONTEXT_FIELDS = {
59
58
  "frontend_styling", "backend_framework", "database", "orm",
60
59
  "design_system", "testing_strategy", "bundler", "project_type",
61
60
  }
62
- ALLOWED_FEATURE_FIELDS = {
61
+ CURRENT_FEATURE_FIELDS = {
63
62
  "id", "title", "description", "priority", "estimated_complexity",
64
- "dependencies", "acceptance_criteria", "status", "session_granularity",
65
- "sub_features", "model", "completion_notes", "user_context",
66
- "browser_interaction", "testing",
63
+ "dependencies", "acceptance_criteria", "status", "model", "completion_notes",
64
+ "user_context", "browser_interaction", "testing",
67
65
  }
66
+ # Historical lists may still carry these keys. They are ignored residue, not
67
+ # current planning fields, and must not fail unknown-field validation.
68
+ LEFTOVER_IGNORED_FEATURE_FIELDS = {"session_granularity", "sub_features"}
68
69
  FEATURE_ID_RE = re.compile(r"^F-\d{3}(-[A-Z])?$")
69
- SUB_FEATURE_ID_RE = re.compile(r"^F-\d{3}-[A-Z]$")
70
70
 
71
71
  # Keywords in acceptance criteria that indicate UI/browser interaction behavior.
72
72
  UI_KEYWORDS_RE = re.compile(
@@ -249,7 +249,6 @@ def validate_feature_list(data, is_new_plan=True):
249
249
  "warnings": warnings,
250
250
  "stats": {
251
251
  "total_features": 0,
252
- "total_sub_features": 0,
253
252
  "complexity_distribution": {},
254
253
  "max_dependency_depth": 0,
255
254
  "has_cycles": False,
@@ -267,7 +266,6 @@ def validate_feature_list(data, is_new_plan=True):
267
266
  seen_ids = set()
268
267
  priorities = []
269
268
  complexity_dist = {"low": 0, "medium": 0, "high": 0, "critical": 0}
270
- total_sub_features = 0
271
269
 
272
270
  for idx, feat in enumerate(features):
273
271
  label = "features[{}]".format(idx)
@@ -283,7 +281,11 @@ def validate_feature_list(data, is_new_plan=True):
283
281
  label, ", ".join(sorted(missing))
284
282
  ))
285
283
 
286
- unknown = set(feat.keys()) - ALLOWED_FEATURE_FIELDS
284
+ unknown = (
285
+ set(feat.keys())
286
+ - CURRENT_FEATURE_FIELDS
287
+ - LEFTOVER_IGNORED_FEATURE_FIELDS
288
+ )
287
289
  if unknown:
288
290
  errors.append("{} has unknown fields: {}".format(
289
291
  label, ", ".join(sorted(unknown))
@@ -380,32 +382,6 @@ def validate_feature_list(data, is_new_plan=True):
380
382
  else:
381
383
  complexity_dist[complexity] += 1
382
384
 
383
- # -- Granularity (optional but validated if present) --
384
- granularity = feat.get("session_granularity")
385
- if granularity is not None:
386
- if granularity not in VALID_GRANULARITIES:
387
- errors.append(
388
- "{}: session_granularity '{}' invalid, must be one of: {}".format(
389
- label, granularity, ", ".join(sorted(VALID_GRANULARITIES))
390
- )
391
- )
392
- elif granularity in ("auto", "sub_feature"):
393
- warnings.append(
394
- "{}: session_granularity '{}' is unused by Runtime; "
395
- "do not use auto/sub_feature for new items. "
396
- "Nested sub-features are not injected or scheduled.".format(
397
- label, granularity
398
- )
399
- )
400
-
401
- subs = feat.get("sub_features")
402
- if isinstance(subs, list) and len(subs) > 0:
403
- warnings.append(
404
- "{}: nested sub-features are unused; Runtime does not inject "
405
- "or schedule them. Move required intent into description and "
406
- "acceptance_criteria.".format(label)
407
- )
408
-
409
385
  # -- Browser interaction check (warning for frontend features) --
410
386
  has_frontend = bool(
411
387
  data.get("global_context", {}).get("frontend_framework")
@@ -422,40 +398,6 @@ def validate_feature_list(data, is_new_plan=True):
422
398
  "field. Consider adding browser verification.".format(label)
423
399
  )
424
400
 
425
- if isinstance(subs, list):
426
- for sidx, sub in enumerate(subs):
427
- sub_label = "{}->sub_features[{}]".format(label, sidx)
428
- if not isinstance(sub, dict):
429
- errors.append("{} is not an object".format(sub_label))
430
- continue
431
-
432
- sub_missing = {"id", "title", "description"} - set(sub.keys())
433
- if sub_missing:
434
- errors.append("{} missing required keys: {}".format(
435
- sub_label, ", ".join(sorted(sub_missing))
436
- ))
437
-
438
- sub_id = sub.get("id", "")
439
- if not SUB_FEATURE_ID_RE.match(str(sub_id)):
440
- errors.append(
441
- "{}: id '{}' must be F-NNN-X format".format(sub_label, sub_id)
442
- )
443
-
444
- # Sub-feature ID should share parent prefix
445
- parent_prefix = str(fid).rstrip("ABCDEFGHIJKLMNOPQRSTUVWXYZ").rstrip("-")
446
- sub_prefix = str(sub_id)[:5] # e.g. "F-001"
447
- if parent_prefix and sub_prefix != parent_prefix:
448
- warnings.append(
449
- "{}: sub-feature '{}' does not share parent prefix '{}'".format(
450
- sub_label, sub_id, parent_prefix
451
- )
452
- )
453
-
454
- if sub_id in seen_ids:
455
- errors.append("{}: duplicate id '{}'".format(sub_label, sub_id))
456
- seen_ids.add(sub_id)
457
- total_sub_features += 1
458
-
459
401
  # ------------------------------------------------------------------
460
402
  # 3. Dependency validation
461
403
  # ------------------------------------------------------------------
@@ -486,7 +428,6 @@ def validate_feature_list(data, is_new_plan=True):
486
428
  "warnings": warnings,
487
429
  "stats": {
488
430
  "total_features": len(features),
489
- "total_sub_features": total_sub_features,
490
431
  "complexity_distribution": complexity_dist,
491
432
  "max_dependency_depth": max_depth,
492
433
  "has_cycles": has_cycles,
@@ -614,8 +555,8 @@ def generate_summary_markdown(data):
614
555
  lines.append("")
615
556
 
616
557
  # Table header
617
- lines.append("| ID | Title | Complexity | Priority | Dependencies | Criteria | Granularity |")
618
- lines.append("|----|-------|------------|----------|--------------|----------|-------------|")
558
+ lines.append("| ID | Title | Complexity | Priority | Dependencies | Criteria |")
559
+ lines.append("|----|-------|------------|----------|--------------|----------|")
619
560
 
620
561
  for feat in features:
621
562
  fid = feat.get("id", "?")
@@ -625,10 +566,9 @@ def generate_summary_markdown(data):
625
566
  deps = feat.get("dependencies", [])
626
567
  deps_str = ", ".join(deps) if deps else "-"
627
568
  criteria_count = len(feat.get("acceptance_criteria", []))
628
- granularity = feat.get("session_granularity", "-")
629
569
 
630
- lines.append("| {} | {} | {} | {} | {} | {} | {} |".format(
631
- fid, title, complexity, priority, deps_str, criteria_count, granularity
570
+ lines.append("| {} | {} | {} | {} | {} | {} |".format(
571
+ fid, title, complexity, priority, deps_str, criteria_count
632
572
  ))
633
573
 
634
574
  lines.append("")
@@ -642,21 +582,15 @@ def generate_summary_markdown(data):
642
582
 
643
583
  # Statistics
644
584
  complexity_dist = {"low": 0, "medium": 0, "high": 0, "critical": 0}
645
- total_sub = 0
646
585
  for feat in features:
647
586
  c = feat.get("estimated_complexity")
648
587
  if c in complexity_dist:
649
588
  complexity_dist[c] += 1
650
- subs = feat.get("sub_features")
651
- if isinstance(subs, list):
652
- total_sub += len(subs)
653
589
 
654
590
  _, max_depth = _detect_cycles(features)
655
591
 
656
592
  lines.append("## Statistics")
657
593
  lines.append("- Total features: {}".format(len(features)))
658
- if total_sub > 0:
659
- lines.append("- Total sub-features: {}".format(total_sub))
660
594
  lines.append("- Complexity: {} low, {} medium, {} high, {} critical".format(
661
595
  complexity_dist["low"], complexity_dist["medium"],
662
596
  complexity_dist["high"], complexity_dist["critical"]
@@ -671,14 +605,10 @@ def generate_summary_json(data):
671
605
  features = data.get("features", [])
672
606
 
673
607
  complexity_dist = {"low": 0, "medium": 0, "high": 0, "critical": 0}
674
- total_sub = 0
675
608
  for feat in features:
676
609
  c = feat.get("estimated_complexity")
677
610
  if c in complexity_dist:
678
611
  complexity_dist[c] += 1
679
- subs = feat.get("sub_features")
680
- if isinstance(subs, list):
681
- total_sub += len(subs)
682
612
 
683
613
  has_cycles, max_depth = _detect_cycles(features)
684
614
 
@@ -691,7 +621,6 @@ def generate_summary_json(data):
691
621
  "estimated_complexity": feat.get("estimated_complexity"),
692
622
  "dependencies": feat.get("dependencies", []),
693
623
  "acceptance_criteria_count": len(feat.get("acceptance_criteria", [])),
694
- "session_granularity": feat.get("session_granularity"),
695
624
  "status": feat.get("status"),
696
625
  })
697
626
 
@@ -700,7 +629,6 @@ def generate_summary_json(data):
700
629
  "features": feature_summaries,
701
630
  "stats": {
702
631
  "total_features": len(features),
703
- "total_sub_features": total_sub,
704
632
  "complexity_distribution": complexity_dist,
705
633
  "max_dependency_depth": max_depth,
706
634
  "has_cycles": has_cycles,
@@ -728,7 +656,6 @@ def cmd_validate(args):
728
656
  "warnings": [],
729
657
  "stats": {
730
658
  "total_features": 0,
731
- "total_sub_features": 0,
732
659
  "complexity_distribution": {},
733
660
  "max_dependency_depth": 0,
734
661
  "has_cycles": False,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "prizmkit",
3
- "version": "1.1.180",
3
+ "version": "1.1.182",
4
4
  "description": "Create a new PrizmKit-powered project with clean initialization — no framework dev files, just what you need.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -15,7 +15,7 @@ import { execSync } from 'node:child_process';
15
15
  import path from 'path';
16
16
  import os from 'node:os';
17
17
  import fs from 'fs-extra';
18
- import { resolvePayloadPlatforms } from './platforms.js';
18
+ import { payloadSkillRoots } from './platforms.js';
19
19
 
20
20
  /**
21
21
  * @param {Object} skill - Skill definition from external_skills.known
@@ -99,11 +99,5 @@ export async function cleanExternalSkillArtifacts(projectRoot, platform, aiCli =
99
99
  }
100
100
 
101
101
  function getTargetDirs(platform, projectRoot, aiCli = '') {
102
- return resolvePayloadPlatforms(platform, aiCli).map(p => {
103
- if (p === 'codebuddy') return path.join(projectRoot, '.codebuddy', 'skills');
104
- if (p === 'codex') return path.join(projectRoot, '.agents', 'skills');
105
- if (p === 'pi') return path.join(projectRoot, '.pi', 'skills');
106
- if (p === 'cursor') return path.join(projectRoot, '.cursor', 'skills');
107
- return path.join(projectRoot, '.claude', 'skills');
108
- });
102
+ return payloadSkillRoots(platform, projectRoot, aiCli);
109
103
  }
@@ -1,10 +1,36 @@
1
1
  /**
2
2
  * Generate only explicit private host-memory ignores.
3
3
  *
4
- * `.prizmkit/**` tracking policy is project-controlled: this module never adds,
5
- * removes, or interprets framework-directory ignore entries.
4
+ * `.prizmkit/**` tracking policy is project-controlled: this module never adds
5
+ * framework-directory ignore entries. Install/upgrade may remove only the exact
6
+ * retired installer-written `.prizmkit/*` and `.prizmkit/**` lines plus the exact
7
+ * old `# PrizmKit` header; they do not interpret other `.prizmkit/` ignores.
6
8
  */
7
9
 
10
+ export const RETIRED_FRAMEWORK_GITIGNORE_LINES = new Set([
11
+ '.prizmkit/*',
12
+ '.prizmkit/**',
13
+ '# PrizmKit',
14
+ ]);
15
+
16
+ /**
17
+ * Remove exact retired installer-written framework-directory ignore lines.
18
+ * @param {string} content
19
+ * @returns {string}
20
+ */
21
+ export function stripRetiredFrameworkGitignore(content) {
22
+ const next = String(content).split(/\r?\n/).filter(line => (
23
+ !RETIRED_FRAMEWORK_GITIGNORE_LINES.has(line.trim())
24
+ ));
25
+ return next.join('\n').replace(/\n{3,}/g, '\n\n').replace(/^\n+/, '');
26
+ }
27
+
28
+ export function hasRetiredFrameworkGitignore(content) {
29
+ return String(content).split(/\r?\n/).some(line => (
30
+ RETIRED_FRAMEWORK_GITIGNORE_LINES.has(line.trim())
31
+ ));
32
+ }
33
+
8
34
  /**
9
35
  * @param {Object} options - { privateMemoryFiles?: string[] }
10
36
  * @returns {string}
package/src/platforms.js CHANGED
@@ -1,3 +1,4 @@
1
+ import path from 'path';
1
2
  import { isBuiltInAiCli } from './ai-cli-launch.js';
2
3
 
3
4
  export const PLATFORM_IDS = ['codebuddy', 'claude', 'codex', 'pi', 'cursor'];
@@ -93,3 +94,15 @@ export function defaultCliForPlatform(platform) {
93
94
  if (platform === 'cursor') return 'agent';
94
95
  return '';
95
96
  }
97
+
98
+ export function nativeSkillRoot(platform, projectRoot) {
99
+ if (platform === 'codebuddy') return path.join(projectRoot, '.codebuddy', 'skills');
100
+ if (platform === 'codex') return path.join(projectRoot, '.agents', 'skills');
101
+ if (platform === 'pi') return path.join(projectRoot, '.pi', 'skills');
102
+ if (platform === 'cursor') return path.join(projectRoot, '.cursor', 'skills');
103
+ return path.join(projectRoot, '.claude', 'skills');
104
+ }
105
+
106
+ export function payloadSkillRoots(platform, projectRoot, aiCli = '') {
107
+ return resolvePayloadPlatforms(platform, aiCli).map(p => nativeSkillRoot(p, projectRoot));
108
+ }
package/src/scaffold.js CHANGED
@@ -24,9 +24,9 @@ import {
24
24
  loadRulesMetadata,
25
25
  getSkillCandidatePaths,
26
26
  } from './metadata.js';
27
- import { generateGitignore } from './gitignore-template.js';
28
- import { buildManifest, writeManifest } from './manifest.js';
29
- import { defaultCliForPlatform, expandPlatforms, isKnownPlatform, platformLabel, privateProjectMemoryFile, privateProjectMemoryFiles, projectMemoryFile, resolvePayloadPlatforms } from './platforms.js';
27
+ import { generateGitignore, hasRetiredFrameworkGitignore, stripRetiredFrameworkGitignore } from './gitignore-template.js';
28
+ import { buildManifest, readManifestForLifecycle, writeManifest } from './manifest.js';
29
+ import { defaultCliForPlatform, expandPlatforms, isKnownPlatform, nativeSkillRoot, payloadSkillRoots, platformLabel, privateProjectMemoryFile, privateProjectMemoryFiles, projectMemoryFile, resolvePayloadPlatforms } from './platforms.js';
30
30
  import { normalizeRuntime, runtimeLabel } from './runtimes.js';
31
31
  import { applyAiCliLaunchToConfig, resolveAiCliLaunchSelection } from './ai-cli-launch.js';
32
32
 
@@ -1378,31 +1378,45 @@ export async function installGitignore(projectRoot, options = {}, dryRun) {
1378
1378
  pipeline: options.pipeline,
1379
1379
  privateMemoryFiles: options.privateMemoryFiles || [],
1380
1380
  });
1381
+ const existed = await fs.pathExists(targetPath);
1382
+ const existing = existed ? await fs.readFile(targetPath, 'utf-8') : '';
1383
+ const retiredRemoved = existed && hasRetiredFrameworkGitignore(existing);
1384
+ const stripped = retiredRemoved ? stripRetiredFrameworkGitignore(existing) : existing;
1381
1385
 
1382
- if (!templateContent) {
1383
- if (dryRun) console.log(chalk.gray(' [dry-run] .gitignore (no managed private-memory entries)'));
1386
+ if (dryRun) {
1387
+ if (retiredRemoved) console.log(chalk.gray(' [dry-run] .gitignore (remove retired .prizmkit/* ignore)'));
1388
+ if (!templateContent) {
1389
+ if (!retiredRemoved) console.log(chalk.gray(' [dry-run] .gitignore (no managed private-memory entries)'));
1390
+ return;
1391
+ }
1392
+ console.log(chalk.gray(' [dry-run] .gitignore (private host memory only)'));
1384
1393
  return;
1385
1394
  }
1386
1395
 
1387
- if (dryRun) {
1388
- console.log(chalk.gray(` [dry-run] .gitignore (private host memory only)`));
1396
+ let current = existed ? stripped : '';
1397
+ if (retiredRemoved) {
1398
+ await fs.writeFile(targetPath, current ? `${current.replace(/\s+$/, '')}\n` : '');
1399
+ current = await fs.readFile(targetPath, 'utf-8');
1400
+ console.log(chalk.green(' ✓ .gitignore (removed retired .prizmkit/* ignore)'));
1401
+ }
1402
+
1403
+ if (!templateContent) {
1404
+ if (!existed) console.log(chalk.gray(' • .gitignore (no managed private-memory entries)'));
1389
1405
  return;
1390
1406
  }
1391
1407
 
1392
1408
  if (await fs.pathExists(targetPath)) {
1393
- // 合并模式:追加缺失条目
1394
- const existing = await fs.readFile(targetPath, 'utf-8');
1395
- const existingLines = new Set(existing.split('\n').map(l => l.trim()));
1409
+ const existingLines = new Set(current.split('\n').map(l => l.trim()));
1396
1410
  const templateLines = templateContent.split('\n').map(l => l.trim()).filter(Boolean);
1397
1411
  const missing = templateLines.filter(line => !existingLines.has(line) && !line.startsWith('#'));
1398
1412
 
1399
1413
  if (missing.length > 0) {
1400
- const separator = existing.endsWith('\n') ? '' : '\n';
1414
+ const separator = current.endsWith('\n') ? '' : '\n';
1401
1415
  const managedHeader = '# PrizmKit private host memory';
1402
1416
  const header = existingLines.has(managedHeader) ? '' : `${managedHeader}\n`;
1403
1417
  await fs.appendFile(targetPath, separator + '\n' + header + missing.join('\n') + '\n');
1404
1418
  console.log(chalk.green(` ✓ .gitignore (added ${missing.length} entries)`));
1405
- } else {
1419
+ } else if (!retiredRemoved) {
1406
1420
  console.log(chalk.green(' ✓ .gitignore (up-to-date)'));
1407
1421
  }
1408
1422
  } else {
@@ -1415,13 +1429,79 @@ export async function installGitignore(projectRoot, options = {}, dryRun) {
1415
1429
  // Playwright CLI 安装
1416
1430
  // ============================================================
1417
1431
 
1432
+ const PLAYWRIGHT_SKILL_NAME = 'playwright-cli';
1433
+
1434
+ function extrasContextObject(value) {
1435
+ return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
1436
+ }
1437
+
1438
+ function resolveOpenCliAutoDownload(autoDownloadOrContext, fallback = true) {
1439
+ if (extrasContextObject(autoDownloadOrContext)) {
1440
+ if (Object.prototype.hasOwnProperty.call(autoDownloadOrContext, 'openCliAutoDownload')) {
1441
+ return Boolean(autoDownloadOrContext.openCliAutoDownload);
1442
+ }
1443
+ return fallback;
1444
+ }
1445
+ if (typeof autoDownloadOrContext === 'boolean') return autoDownloadOrContext;
1446
+ return fallback;
1447
+ }
1448
+
1449
+ function completePlaywrightSkillDir(dir) {
1450
+ return dir && fs.pathExistsSync(path.join(dir, 'SKILL.md')) ? dir : null;
1451
+ }
1452
+
1453
+ function discoverPlaywrightSkillSource(projectRoot) {
1454
+ const home = process.env.HOME || process.env.USERPROFILE || '.';
1455
+ return completePlaywrightSkillDir(path.join(projectRoot, '.claude', 'skills', PLAYWRIGHT_SKILL_NAME))
1456
+ || completePlaywrightSkillDir(path.join(home, '.claude', 'skills', PLAYWRIGHT_SKILL_NAME));
1457
+ }
1458
+
1459
+ async function distributePlaywrightSkill(projectRoot, extrasContext, dryRun) {
1460
+ const platform = extrasContext?.platform;
1461
+ if (!platform) {
1462
+ console.log(chalk.yellow(' ⚠ playwright-cli skills were not copied: install platform is missing'));
1463
+ return;
1464
+ }
1465
+ const aiCli = extrasContext?.aiCli || '';
1466
+ const payloadPlatforms = resolvePayloadPlatforms(platform, aiCli);
1467
+ const destinations = payloadSkillRoots(platform, projectRoot, aiCli).map(root => path.join(root, PLAYWRIGHT_SKILL_NAME));
1468
+ if (dryRun) {
1469
+ for (const dest of destinations) {
1470
+ console.log(chalk.gray(` [dry-run] ${path.relative(projectRoot, dest)}`));
1471
+ }
1472
+ return;
1473
+ }
1474
+ const source = discoverPlaywrightSkillSource(projectRoot);
1475
+ if (!source) {
1476
+ console.log(chalk.yellow(' ⚠ playwright-cli skill tree was not found after install --skills'));
1477
+ return;
1478
+ }
1479
+ const sourceReal = await fs.realpath(source).catch(() => path.resolve(source));
1480
+ for (const dest of destinations) {
1481
+ const destReal = await fs.realpath(dest).catch(() => path.resolve(dest));
1482
+ if (destReal === sourceReal) continue;
1483
+ await fs.remove(dest).catch(() => {});
1484
+ await fs.copy(source, dest);
1485
+ console.log(chalk.green(` ✓ ${path.relative(projectRoot, dest)}`));
1486
+ }
1487
+ if (!payloadPlatforms.includes('claude')) {
1488
+ const leftover = path.join(nativeSkillRoot('claude', projectRoot), PLAYWRIGHT_SKILL_NAME);
1489
+ if (await fs.pathExists(leftover)) {
1490
+ await fs.remove(leftover);
1491
+ console.log(chalk.gray(` • removed leftover ${path.relative(projectRoot, leftover)}`));
1492
+ }
1493
+ }
1494
+ }
1495
+
1418
1496
  /**
1419
1497
  * 安装 playwright-cli(全局 npm 包 + AI agent skills)
1420
1498
  * 用于浏览器交互验证(browser_interaction 功能)
1421
1499
  */
1422
- export async function installPlaywrightCli(projectRoot, dryRun) {
1500
+ export async function installPlaywrightCli(projectRoot, dryRun, extrasContext = {}) {
1501
+ const context = extrasContextObject(extrasContext) ? extrasContext : {};
1423
1502
  if (dryRun) {
1424
1503
  console.log(chalk.gray(' [dry-run] @playwright/cli (global install + workspace init)'));
1504
+ await distributePlaywrightSkill(projectRoot, context, true);
1425
1505
  return;
1426
1506
  }
1427
1507
 
@@ -1451,6 +1531,7 @@ export async function installPlaywrightCli(projectRoot, dryRun) {
1451
1531
  if (fs.pathExistsSync(dotPlaywright)) {
1452
1532
  fs.removeSync(dotPlaywright);
1453
1533
  }
1534
+ await distributePlaywrightSkill(projectRoot, context, false);
1454
1535
  } catch (e) {
1455
1536
  console.log(chalk.yellow(` ⚠ Skills install skipped: ${e.message}`));
1456
1537
  console.log(chalk.yellow(' ⚠ Run manually: playwright-cli install --skills'));
@@ -1500,6 +1581,7 @@ function isOpenCliAvailable() {
1500
1581
  * 用于浏览器交互验证,复用 Chrome 已登录会话(OAuth/SSO/第三方集成)
1501
1582
  */
1502
1583
  export async function installOpenCli(projectRoot, dryRun, autoDownload = true) {
1584
+ const shouldAutoDownload = resolveOpenCliAutoDownload(autoDownload);
1503
1585
  if (dryRun) {
1504
1586
  console.log(chalk.gray(' [dry-run] @jackwener/opencli (global install)'));
1505
1587
  return;
@@ -1531,7 +1613,7 @@ export async function installOpenCli(projectRoot, dryRun, autoDownload = true) {
1531
1613
  );
1532
1614
  if (fs.pathExistsSync(extensionManifest)) {
1533
1615
  console.log(chalk.green(' ✓ OpenCLI extension files (already downloaded)'));
1534
- } else if (autoDownload) {
1616
+ } else if (shouldAutoDownload) {
1535
1617
  await downloadOpenCliExtension();
1536
1618
  } else {
1537
1619
  printOpenCliManualSteps();
@@ -1717,6 +1799,20 @@ export async function scaffold(config) {
1717
1799
  console.log('');
1718
1800
  }
1719
1801
 
1802
+ let existingManifest = null;
1803
+ try {
1804
+ existingManifest = await readManifestForLifecycle(projectRoot);
1805
+ } catch {
1806
+ existingManifest = null;
1807
+ }
1808
+ const { reconcileDroppedPayloadPlatformRules } = await import('./upgrade.js');
1809
+ await reconcileDroppedPayloadPlatformRules(projectRoot, {
1810
+ manifest: existingManifest,
1811
+ nextPlatforms: payloadPlatforms,
1812
+ rulesMeta: await loadRulesMetadata(),
1813
+ dryRun,
1814
+ });
1815
+
1720
1816
  // 6. Pipeline
1721
1817
  let installedPipelineFiles = [];
1722
1818
  if (pipeline) {
@@ -1784,7 +1880,7 @@ export async function scaffold(config) {
1784
1880
  if (playwrightCli) {
1785
1881
  activeExtras.push('playwright-cli');
1786
1882
  console.log(chalk.blue(` ${EXTRAS_REGISTRY['playwright-cli'].label}:`));
1787
- await installPlaywrightCli(projectRoot, dryRun);
1883
+ await installPlaywrightCli(projectRoot, dryRun, { platform, aiCli: resolvedAiCli });
1788
1884
  console.log('');
1789
1885
  }
1790
1886
  if (openCli) {
package/src/upgrade.js CHANGED
@@ -33,7 +33,7 @@ import {
33
33
  removeRetiredAgentTeamArtifacts,
34
34
  EXTRAS_REGISTRY,
35
35
  } from './scaffold.js';
36
- import { platformLabel, privateProjectMemoryFiles, resolvePayloadPlatforms } from './platforms.js';
36
+ import { expandPlatforms, PLATFORM_IDS, platformLabel, privateProjectMemoryFiles, resolvePayloadPlatforms, uniquePlatforms } from './platforms.js';
37
37
  import { normalizeRuntime, runtimeLabel } from './runtimes.js';
38
38
 
39
39
  const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -119,31 +119,123 @@ export async function removeAgentFiles(platform, projectRoot, agentFileNames, dr
119
119
  }
120
120
  }
121
121
 
122
+ export const CURSOR_FRAMEWORK_RULE_SOURCE = 'prizmkit-framework.md';
123
+
124
+ function ruleInstallBasename(platform, fileName) {
125
+ const baseName = path.basename(fileName);
126
+ return platform === 'codebuddy' || platform === 'cursor'
127
+ ? baseName.replace(/\.md$/, '.mdc')
128
+ : baseName;
129
+ }
130
+
131
+ function platformRuleSearchRoots(platform, projectRoot) {
132
+ if (platform === 'claude') return [path.join(projectRoot, '.claude', 'rules')];
133
+ if (platform === 'codex') {
134
+ return [
135
+ path.join(projectRoot, '.agents', 'rules'),
136
+ path.join(projectRoot, '.codex', 'rules'),
137
+ ];
138
+ }
139
+ if (platform === 'pi') return [path.join(projectRoot, '.pi', 'rules')];
140
+ if (platform === 'cursor') return [path.join(projectRoot, '.cursor', 'rules')];
141
+ return [path.join(projectRoot, '.codebuddy', 'rules')];
142
+ }
143
+
144
+ export function managedRuleFileNames(rulesMeta, manifest) {
145
+ const names = new Set();
146
+ for (const key of Object.keys(rulesMeta?.rules || {})) {
147
+ names.add(`${path.basename(key)}.md`);
148
+ }
149
+ for (const recorded of manifest?.files?.rules || []) {
150
+ const baseName = path.basename(recorded);
151
+ names.add(baseName.endsWith('.mdc') ? baseName.replace(/\.mdc$/, '.md') : baseName);
152
+ }
153
+ names.add(CURSOR_FRAMEWORK_RULE_SOURCE);
154
+ return [...names];
155
+ }
156
+
157
+ export function previousPayloadPlatformsFromManifest(manifest) {
158
+ if (!manifest) return [];
159
+ const listed = [];
160
+ if (Array.isArray(manifest.files?.payloadPlatforms)) {
161
+ listed.push(...manifest.files.payloadPlatforms);
162
+ }
163
+ if (manifest.platform) {
164
+ const group = manifest.platform === 'both' ? 'all' : manifest.platform;
165
+ listed.push(...expandPlatforms(group));
166
+ }
167
+ return uniquePlatforms(listed);
168
+ }
169
+
170
+ export async function detectManagedRulePlatforms(projectRoot, ruleFileNames) {
171
+ const found = [];
172
+ for (const platform of PLATFORM_IDS) {
173
+ let hit = false;
174
+ for (const dir of platformRuleSearchRoots(platform, projectRoot)) {
175
+ for (const fileName of ruleFileNames) {
176
+ if (await fs.pathExists(path.join(dir, ruleInstallBasename(platform, fileName)))) {
177
+ hit = true;
178
+ break;
179
+ }
180
+ }
181
+ if (hit) break;
182
+ }
183
+ if (hit) found.push(platform);
184
+ }
185
+ return found;
186
+ }
187
+
188
+ export async function collectPreviousPayloadPlatforms(projectRoot, manifest, ruleFileNames) {
189
+ return uniquePlatforms([
190
+ ...previousPayloadPlatformsFromManifest(manifest),
191
+ ...(await detectManagedRulePlatforms(projectRoot, ruleFileNames)),
192
+ ]);
193
+ }
194
+
195
+ export async function removeDroppedPayloadPlatformRules({
196
+ projectRoot,
197
+ previousPlatforms,
198
+ nextPlatforms,
199
+ ruleFileNames,
200
+ dryRun,
201
+ }) {
202
+ const next = new Set(nextPlatforms);
203
+ const dropped = uniquePlatforms(previousPlatforms).filter(platform => !next.has(platform));
204
+ if (!dropped.length) return dropped;
205
+ console.log(chalk.blue('\n Dropped-platform rules:'));
206
+ for (const platform of dropped) {
207
+ console.log(chalk.blue(` Removing leftover PrizmKit rules (${platformLabel(platform)}):`));
208
+ await removeRuleFiles(platform, projectRoot, ruleFileNames, dryRun);
209
+ }
210
+ return dropped;
211
+ }
212
+
213
+ export async function reconcileDroppedPayloadPlatformRules(projectRoot, {
214
+ manifest,
215
+ nextPlatforms,
216
+ rulesMeta,
217
+ dryRun,
218
+ }) {
219
+ const ruleFileNames = managedRuleFileNames(rulesMeta, manifest);
220
+ const previousPlatforms = await collectPreviousPayloadPlatforms(projectRoot, manifest, ruleFileNames);
221
+ return removeDroppedPayloadPlatformRules({
222
+ projectRoot,
223
+ previousPlatforms,
224
+ nextPlatforms,
225
+ ruleFileNames,
226
+ dryRun,
227
+ });
228
+ }
229
+
122
230
  /**
123
231
  * Remove rule files for a specific platform.
124
232
  */
125
233
  export async function removeRuleFiles(platform, projectRoot, ruleFileNames, dryRun) {
126
234
  for (const fileName of ruleFileNames) {
127
- const baseName = path.basename(fileName);
128
- const dir = platform === 'claude'
129
- ? path.join(projectRoot, '.claude', 'rules')
130
- : platform === 'codex'
131
- ? path.join(projectRoot, '.agents', 'rules')
132
- : platform === 'pi'
133
- ? path.join(projectRoot, '.pi', 'rules')
134
- : platform === 'cursor'
135
- ? path.join(projectRoot, '.cursor', 'rules')
136
- : path.join(projectRoot, '.codebuddy', 'rules');
137
- // Cursor and CodeBuddy use .mdc; Claude/Codex/Pi use Markdown.
138
- const targetName = platform === 'codebuddy' || platform === 'cursor'
139
- ? baseName.replace(/\.md$/, '.mdc')
140
- : baseName;
235
+ const targetName = ruleInstallBasename(platform, fileName);
141
236
  const filePaths = platform === 'codex'
142
- ? [
143
- path.join(dir, targetName),
144
- path.join(projectRoot, '.codex', 'rules', targetName),
145
- ]
146
- : [path.join(dir, targetName)];
237
+ ? platformRuleSearchRoots(platform, projectRoot).map(dir => path.join(dir, targetName))
238
+ : [path.join(platformRuleSearchRoots(platform, projectRoot)[0], targetName)];
147
239
  for (const filePath of filePaths) {
148
240
  if (await fs.pathExists(filePath)) {
149
241
  if (dryRun) {
@@ -412,7 +504,7 @@ export async function runUpgrade(directory, options = {}) {
412
504
  const entry = EXTRAS_REGISTRY[extraName];
413
505
  if (!entry) continue;
414
506
  console.log(chalk.blue(` ${entry.label}:`));
415
- await entry.install(projectRoot, dryRun);
507
+ await entry.install(projectRoot, dryRun, { platform, aiCli });
416
508
  console.log('');
417
509
  }
418
510
  }
@@ -438,6 +530,13 @@ export async function runUpgrade(directory, options = {}) {
438
530
  await installProjectMemory(p, projectRoot, dryRun);
439
531
  }
440
532
 
533
+ await reconcileDroppedPayloadPlatformRules(projectRoot, {
534
+ manifest: oldManifest,
535
+ nextPlatforms: payloadPlatforms,
536
+ rulesMeta,
537
+ dryRun,
538
+ });
539
+
441
540
  // 8. Write new manifest
442
541
  if (!dryRun) {
443
542
  await writeManifest(projectRoot, newManifest);