prizmkit 1.1.180 → 1.1.181

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.181",
3
+ "bundledAt": "2026-09-11T01:19:27.025Z",
4
+ "bundledFrom": "203a6c3"
5
5
  }
@@ -1,5 +1,5 @@
1
1
  {
2
- "version": "1.1.180",
2
+ "version": "1.1.181",
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.",
@@ -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
@@ -380,32 +380,16 @@ def validate_feature_list(data, is_new_plan=True):
380
380
  else:
381
381
  complexity_dist[complexity] += 1
382
382
 
383
- # -- Granularity (optional but validated if present) --
383
+ # -- Optional leftover keys (historical lists only; not taught for new items) --
384
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
- )
385
+ if granularity is not None and granularity not in VALID_GRANULARITIES:
386
+ errors.append(
387
+ "{}: session_granularity '{}' invalid, must be one of: {}".format(
388
+ label, granularity, ", ".join(sorted(VALID_GRANULARITIES))
399
389
  )
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
390
  )
408
391
 
392
+ subs = feat.get("sub_features")
409
393
  # -- Browser interaction check (warning for frontend features) --
410
394
  has_frontend = bool(
411
395
  data.get("global_context", {}).get("frontend_framework")
@@ -614,8 +598,8 @@ def generate_summary_markdown(data):
614
598
  lines.append("")
615
599
 
616
600
  # Table header
617
- lines.append("| ID | Title | Complexity | Priority | Dependencies | Criteria | Granularity |")
618
- lines.append("|----|-------|------------|----------|--------------|----------|-------------|")
601
+ lines.append("| ID | Title | Complexity | Priority | Dependencies | Criteria |")
602
+ lines.append("|----|-------|------------|----------|--------------|----------|")
619
603
 
620
604
  for feat in features:
621
605
  fid = feat.get("id", "?")
@@ -625,10 +609,9 @@ def generate_summary_markdown(data):
625
609
  deps = feat.get("dependencies", [])
626
610
  deps_str = ", ".join(deps) if deps else "-"
627
611
  criteria_count = len(feat.get("acceptance_criteria", []))
628
- granularity = feat.get("session_granularity", "-")
629
612
 
630
- lines.append("| {} | {} | {} | {} | {} | {} | {} |".format(
631
- fid, title, complexity, priority, deps_str, criteria_count, granularity
613
+ lines.append("| {} | {} | {} | {} | {} | {} |".format(
614
+ fid, title, complexity, priority, deps_str, criteria_count
632
615
  ))
633
616
 
634
617
  lines.append("")
@@ -642,21 +625,15 @@ def generate_summary_markdown(data):
642
625
 
643
626
  # Statistics
644
627
  complexity_dist = {"low": 0, "medium": 0, "high": 0, "critical": 0}
645
- total_sub = 0
646
628
  for feat in features:
647
629
  c = feat.get("estimated_complexity")
648
630
  if c in complexity_dist:
649
631
  complexity_dist[c] += 1
650
- subs = feat.get("sub_features")
651
- if isinstance(subs, list):
652
- total_sub += len(subs)
653
632
 
654
633
  _, max_depth = _detect_cycles(features)
655
634
 
656
635
  lines.append("## Statistics")
657
636
  lines.append("- Total features: {}".format(len(features)))
658
- if total_sub > 0:
659
- lines.append("- Total sub-features: {}".format(total_sub))
660
637
  lines.append("- Complexity: {} low, {} medium, {} high, {} critical".format(
661
638
  complexity_dist["low"], complexity_dist["medium"],
662
639
  complexity_dist["high"], complexity_dist["critical"]
@@ -671,14 +648,10 @@ def generate_summary_json(data):
671
648
  features = data.get("features", [])
672
649
 
673
650
  complexity_dist = {"low": 0, "medium": 0, "high": 0, "critical": 0}
674
- total_sub = 0
675
651
  for feat in features:
676
652
  c = feat.get("estimated_complexity")
677
653
  if c in complexity_dist:
678
654
  complexity_dist[c] += 1
679
- subs = feat.get("sub_features")
680
- if isinstance(subs, list):
681
- total_sub += len(subs)
682
655
 
683
656
  has_cycles, max_depth = _detect_cycles(features)
684
657
 
@@ -691,7 +664,6 @@ def generate_summary_json(data):
691
664
  "estimated_complexity": feat.get("estimated_complexity"),
692
665
  "dependencies": feat.get("dependencies", []),
693
666
  "acceptance_criteria_count": len(feat.get("acceptance_criteria", [])),
694
- "session_granularity": feat.get("session_granularity"),
695
667
  "status": feat.get("status"),
696
668
  })
697
669
 
@@ -700,7 +672,6 @@ def generate_summary_json(data):
700
672
  "features": feature_summaries,
701
673
  "stats": {
702
674
  "total_features": len(features),
703
- "total_sub_features": total_sub,
704
675
  "complexity_distribution": complexity_dist,
705
676
  "max_dependency_depth": max_depth,
706
677
  "has_cycles": has_cycles,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "prizmkit",
3
- "version": "1.1.180",
3
+ "version": "1.1.181",
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": {