prizmkit 1.1.178 → 1.1.180

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 (37) hide show
  1. package/bundled/VERSION.json +3 -3
  2. package/bundled/rules/prizm/prizm-progressive-loading.md +1 -0
  3. package/bundled/skills/_metadata.json +1 -1
  4. package/bundled/skills/app-planner/SKILL.md +7 -7
  5. package/bundled/skills/app-planner/references/generated-plan-review.md +6 -6
  6. package/bundled/skills/app-planner/references/rules/frontend/derivation-rules.md +86 -18
  7. package/bundled/skills/app-planner/references/rules/frontend/fixed-rules.md +122 -1
  8. package/bundled/skills/app-planner/references/rules/frontend/question-bank.md +2 -2
  9. package/bundled/skills/app-planner/references/rules/frontend/question-manifest.json +4 -4
  10. package/bundled/skills/app-planner/references/rules/frontend/template.md +40 -1
  11. package/bundled/skills/app-planner/references/rules-configuration.md +8 -3
  12. package/bundled/skills/bug-planner/SKILL.md +3 -3
  13. package/bundled/skills/bug-planner/references/generated-plan-review.md +3 -0
  14. package/bundled/skills/feature-planner/SKILL.md +4 -4
  15. package/bundled/skills/feature-planner/assets/planning-guide.md +21 -45
  16. package/bundled/skills/feature-planner/references/completeness-review.md +4 -1
  17. package/bundled/skills/feature-planner/references/decomposition-patterns.md +1 -1
  18. package/bundled/skills/feature-planner/references/generated-plan-review.md +4 -0
  19. package/bundled/skills/feature-planner/references/new-project-planning.md +7 -6
  20. package/bundled/skills/feature-planner/scripts/validate-and-generate.py +13 -8
  21. package/bundled/skills/prizmkit-implement/SKILL.md +1 -1
  22. package/bundled/skills/prizmkit-init/SKILL.md +2 -0
  23. package/bundled/skills/prizmkit-plan/SKILL.md +2 -1
  24. package/bundled/skills/prizmkit-plan/references/verification-checklist.md +1 -0
  25. package/bundled/skills/prizmkit-prizm-docs/assets/prizm-docs-format.md +11 -0
  26. package/bundled/skills/prizmkit-prizm-docs/references/op-init.md +1 -0
  27. package/bundled/skills/prizmkit-prizm-docs/references/op-rebuild.md +1 -1
  28. package/bundled/skills/prizmkit-prizm-docs/references/op-update.md +1 -1
  29. package/bundled/skills/prizmkit-retrospective/references/structural-sync-steps.md +1 -1
  30. package/bundled/skills/refactor-planner/SKILL.md +3 -3
  31. package/bundled/skills/refactor-planner/assets/planning-guide.md +20 -21
  32. package/bundled/skills/refactor-planner/references/fast-path.md +4 -5
  33. package/bundled/skills/refactor-planner/references/generated-plan-review.md +3 -0
  34. package/bundled/skills/refactor-planner/references/planning-phases.md +1 -1
  35. package/bundled/skills/refactor-planner/references/refactor-scoping-guide.md +18 -15
  36. package/bundled/templates/project-memory-template.md +1 -0
  37. package/package.json +1 -1
@@ -109,6 +109,44 @@ If a decision is deferred or not applicable, its cell and section state that exp
109
109
 
110
110
  {{ performance_rules }}
111
111
 
112
+ ### 4.5 Design modules
113
+
114
+ #### M1 Asynchronous UI states
115
+
116
+ {{ FIXED_RULES_DESIGN_M1 }}
117
+
118
+ #### M2 Overflow recovery after truncation
119
+
120
+ {{ FIXED_RULES_DESIGN_M2 }}
121
+
122
+ #### M3 Stacking and floating layers
123
+
124
+ {{ FIXED_RULES_DESIGN_M3 }}
125
+
126
+ #### M4 Dangerous or non-idempotent actions
127
+
128
+ {{ FIXED_RULES_DESIGN_M4 }}
129
+
130
+ #### M5 Focus, keyboard, and accessible names
131
+
132
+ {{ FIXED_RULES_DESIGN_M5 }}
133
+
134
+ #### M6 Narrow viewport and pointer type
135
+
136
+ {{ DESIGN_MODULE_M6 }}
137
+
138
+ #### M7 Leave and conflict recovery
139
+
140
+ {{ FIXED_RULES_DESIGN_M7 }}
141
+
142
+ #### M8 Third-party chrome copy
143
+
144
+ {{ DESIGN_MODULE_M8 }}
145
+
146
+ #### M9 Motion
147
+
148
+ Not applicable: no distinct user-visible or operable failure can be stated that a reviewer can mark done or not done without becoming an aesthetic preference or duplicating M1 or M5.
149
+
112
150
  ## 5. Testing
113
151
 
114
152
  {{ test_rules }}
@@ -151,11 +189,12 @@ The deny list is derived only from active invariant and selected rule blocks; it
151
189
 
152
190
  {{ recommended_libs }}
153
191
 
154
- Recommendations must be compatible with the selected stack and dependency-permission rule. They are not authorization to modify dependencies.
192
+ Recommendations are non-binding. They must be compatible with the selected stack and dependency-permission rule. They are not authorization to modify dependencies and must not be written as Must-install unless the decision ledger selected the library or it is already present in the project.
155
193
 
156
194
  ## Source Contract
157
195
 
158
196
  - Owner: app-planner Rules Configuration
159
197
  - Resource family: `references/rules/frontend/`
198
+ - Generated rules name selected options, then follow the repository's current installed versions, `package.json`, and existing codegen or framework-docs entrypoints. Do not treat a planning-time major, codegen tool, or generated-types directory as current law.
160
199
  - Regenerate after changing a selected decision or source contract; do not patch contradictory generated sections independently.
161
200
  - Generation metadata value: {{ generated_at }}
@@ -127,9 +127,14 @@ Check every fixed and derived rule against the ledger:
127
127
 
128
128
  ## Step 8: Update `root.prizm`
129
129
 
130
- - Ensure `.prizmkit/prizm-docs/root.prizm` has a concise `RULES:` pointer to configured rule files.
131
- - If `root.prizm` exists, update only the `RULES:` line.
132
- - If absent, create only the minimal valid root plus the `RULES:` pointer allowed by the parent Skill.
130
+ - Ensure `.prizmkit/prizm-docs/root.prizm` has an optional `LAYER_RULES:` list of arrow pointers to configured convention-path files only:
131
+ - `frontend -> .prizmkit/rules/frontend-rules.md`
132
+ - `backend -> .prizmkit/rules/backend-rules.md`
133
+ - `database -> .prizmkit/rules/database-rules.md`
134
+ - `mobile -> .prizmkit/rules/mobile-rules.md`
135
+ - Include only layers whose rule files were written. Omit skipped layers. Omit the `LAYER_RULES:` key entirely when no layer file was written.
136
+ - If `root.prizm` exists, add or update only the `LAYER_RULES:` block. Do not place those paths in the `RULES:` MUST/NEVER list and do not rewrite `RULES:` as a file pointer.
137
+ - If absent, create only the minimal valid root plus the `LAYER_RULES:` pointer block allowed by the parent Skill.
133
138
  - Do not write architecture decisions, project brief content, temporal metadata, or changelog content into `root.prizm`.
134
139
 
135
140
  ## Completion Evidence
@@ -57,11 +57,11 @@ In an ordinary successful flow, `.prizmkit/plans/bug-fix-list.draft.json` is int
57
57
 
58
58
  Every new or changed bug is an executable contract for a fresh AI session that has never seen the planning conversation. Do not add new JSON fields, context objects, schema versions, or pipeline runtime structures. Use the existing fields correctly:
59
59
 
60
- 1. **Self-contained contract**: The bug's `description` and `acceptance_criteria`, read together, MUST define the objective, current state and actual behavior, desired state and expected behavior, selected scope and decisions, severity rationale, constraints, non-goals, relevant integrations, edge cases, reproduction conditions, verification decisions, and completion evidence. Because no separate rationale field is added, include the durable severity rationale in `description`. Preserve user requirements at matching detail.
60
+ 1. **Self-contained contract**: The bug's `description` and `acceptance_criteria`, read together, MUST define the objective, current state and actual behavior, desired state and expected behavior, selected scope and decisions, severity rationale, constraints, non-goals, relevant integrations, edge cases, reproduction conditions, verification decisions, and completion evidence. Because no separate rationale field is added, include the durable severity rationale in `description`. AI rewrite is allowed; dropping a confirmed item is not. There is no word-count upper limit and no acceptance-criteria count upper limit.
61
61
  2. **Supplementary evidence only**: `user_context` is supplementary evidence only. Logs, stack traces, screenshots, and source excerpts may support diagnosis, but they MUST NOT expand, replace, or contradict the contract. If `user_context` were removed, a fresh bug-fix session must still know what fails, where and when it fails, what correct behavior means, which scope was selected, and how to verify the fix.
62
62
  3. **Severity and verification are durable decisions**: Write the complete severity rationale, selected scope, environment, reproduction path, verification type, and verification decisions by meaning. Never store only an option label or conversational answer.
63
63
  4. **Clarify by impact, do not guess**: Expected behavior, selected behavioral scope, material applicability, and relative references require clarification when multiple meanings would materially change the contract. Root cause, code location, and fix approach may remain explicitly labeled as evidence-backed hypotheses or unknowns when the confirmed behavior and bounded investigation path are sufficient for execution.
64
- 5. **Bug isolation**: Each bug contract and its supplementary evidence contain only material relevant to that bug. Repeat shared environment or constraints only when explicitly global.
64
+ 5. **Bug isolation**: Keep one bug per task unless bugs share the same root cause or the same failing contract and the user confirms a merge. Do not domain-merge unrelated bugs merely because they sit in the same module. Each bug contract and its supplementary evidence contain only material relevant to that bug. Repeat shared environment or constraints only when explicitly global.
65
65
 
66
66
  ### Artifact-Wide AI Readability
67
67
 
@@ -317,7 +317,7 @@ Return `NEEDS_FIXES` whenever any answer is missing, ambiguous, or available onl
317
317
  **Step 2 — Acceptance criteria specificity check**: For each bug, verify each acceptance criterion passes the "pipeline autonomy test" — could an AI session, without asking a human, determine whether this criterion is met? Flag criteria that are subjective ("works correctly"), lack measurable conditions ("performs better"), omit expected behavior, or leave reproduction and verification decisions only in `user_context`.
318
318
 
319
319
  **Step 3 — Cross-bug analysis**: Check for:
320
- - **Root cause overlap**: Multiple bugs in the same module may share a root cause — flag for user to confirm whether they should be merged or kept separate
320
+ - **Root cause overlap**: Keep one bug per task. Multiple bugs in the same module are not merged by module. Merge only when they share the same root cause or the same failing contract and the user confirms.
321
321
  - **Missing dependencies**: If fixing B-002 requires B-001 to be fixed first, flag the dependency
322
322
  - **Scope gaps**: If bugs describe symptoms but the underlying cause likely affects more areas, suggest additional bugs
323
323
 
@@ -45,6 +45,9 @@ For every reviewed bug entry, check:
45
45
  - Task-scoped `user_context` isolation: no unrelated sibling bug descriptions, logs, stack traces, reproduction steps, expected/actual behavior notes, or supplementary materials; shared context appears on multiple bugs only when explicitly global
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
  - Severity/priority calibration: every reviewed bug has a short severity rationale and priority rationale, the preserved severity-to-priority mapping is followed, and high priority is not used without core outage, data loss/integrity, security/auth, timeout/crash, or no-workaround indicators
48
+ - Incident scope: keep one bug per task unless the same root cause or same failing contract is confirmed; do not domain-merge by module
49
+ - Injected-field fidelity: confirmed actual/expected behavior and completion evidence are in `description` and `acceptance_criteria`; AI rewrite is allowed; dropping a confirmed item is not
50
+ - Size: there is no word-count upper limit and no acceptance-criteria count upper limit
48
51
  - Browser interaction and verification fields for UI-reproducible bugs when applicable
49
52
 
50
53
  ## Headless Context Completeness Gate
@@ -65,10 +65,10 @@ In an ordinary successful flow, `.prizmkit/plans/feature-list.draft.json` is int
65
65
 
66
66
  Every new or changed feature is an executable contract for a fresh AI session that has never seen the planning conversation. Do not add new JSON fields, context objects, schema versions, or pipeline runtime structures. Use the existing fields correctly:
67
67
 
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. Preserve detailed user requirements at matching detail; normalization must not simplify substantive rules.
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 contract and its supplementary evidence contain only material relevant to that feature. Repeat shared context only when it explicitly applies to every affected feature. Ask the user to map material whose applicability is unclear.
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.
72
72
 
73
73
  ### Artifact-Wide AI Readability
74
74
 
@@ -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 session granularity
121
+ - Read `${SKILL_DIR}/assets/planning-guide.md` for description writing standards, acceptance criteria patterns, complexity estimation, dependency rules, and contract-bounded grouping
122
122
 
123
123
  2. **Incremental planning reference** — load for incremental mode:
124
124
  - Read `${SKILL_DIR}/references/incremental-feature-planning.md`
@@ -420,7 +420,7 @@ Key requirements:
420
420
  - new items default `status: "pending"`
421
421
  - English feature titles for stable slug generation
422
422
  - `browser_interaction` auto-generated for qualifying frontend features (with `tool` selection: `auto`/`playwright-cli`/`opencli`)
423
- - descriptions: minimum 15 words (error), recommended minimum 30/50/80/100+ for low/medium/high/critical (warning). No upper limit — preserve substantive requirements at matching detail so `description` plus `acceptance_criteria` remains complete without `user_context`
423
+ - descriptions: minimum 15 words (error), recommended minimum 30/50/80/100+ for low/medium/high/critical (warning). There is no word-count upper limit and no acceptance-criteria count upper limit. Keep `description` plus `acceptance_criteria` complete without `user_context`.
424
424
  - `estimated_complexity` records implementation scope and verification risk for planning summaries, ordering, and downstream context. It does not select a fixed agent count or named review topology; every normal feature session receives the runtime's full guidance.
425
425
 
426
426
  **IMPORTANT: Do NOT hand-write the final JSON file.** Instead:
@@ -1,6 +1,6 @@
1
1
  # Feature Planning Reference Guide
2
2
 
3
- This guide provides structured templates and patterns for writing high-quality feature descriptions, acceptance criteria, complexity estimates, dependency graphs, and session granularity decisions. Use during feature-planner sessions.
3
+ This guide provides structured templates and patterns for writing high-quality feature descriptions, acceptance criteria, complexity estimates, dependency graphs, and contract-bounded grouping decisions. Use during feature-planner sessions.
4
4
 
5
5
  For app-level design references (vision templates, tech stack matrix), see `app-planner/references/app-design-guide.md`. For feature decomposition patterns (CRUD, SaaS, Social, E-commerce), see `${SKILL_DIR}/references/decomposition-patterns.md`.
6
6
 
@@ -21,7 +21,7 @@ Feature descriptions are the **primary input** for autonomous pipeline sessions.
21
21
 
22
22
  Below 15 words is a validation error. Below the recommended minimum triggers a warning.
23
23
 
24
- There is no schema-level upper limit, but length is not a quality target. Add detail only when it establishes confirmed intent, current/desired behavior, constraints, integrations, relevant edge cases, or completion evidence. Do not add speculative infrastructure, API shape, data fields, or future capability merely to reach a recommended word count.
24
+ There is no schema-level upper limit, but length is not a quality target. There is no word-count upper limit and no acceptance-criteria count upper limit. Do not pad with unconfirmed HOW. Add confirmed intent only; AI rewrite is allowed; dropping a confirmed item is not. Do not add speculative infrastructure, API shape, data fields, or future capability merely to reach a recommended word count.
25
25
 
26
26
  ### What to Include
27
27
 
@@ -125,7 +125,7 @@ Then [expected outcome]
125
125
  2. **No implementation details.** Criteria describe what, not how. Say "user is redirected" not "React Router navigates to /dashboard."
126
126
  3. **Include relevant edge cases.** Cover invalid input, unauthorized access, empty states, and error conditions only when they can affect the confirmed outcome.
127
127
  4. **Be measurable.** Where performance matters, include specific thresholds (e.g., "within 2 seconds").
128
- 5. **Keep the count manageable.** A feature with more than 8 acceptance criteria may need to be split into sub-features.
128
+ 5. **Keep every confirmed criterion.** There is no acceptance-criteria count upper limit. Do not merge or drop confirmed completion evidence to stay under a count.
129
129
 
130
130
  ---
131
131
 
@@ -151,20 +151,22 @@ Use at least two relevant indicators in each `estimated_complexity` rationale:
151
151
  - acceptance-criteria count and edge-case breadth
152
152
  - existing test coverage and verification difficulty
153
153
 
154
- ### Complexity Red Flags
154
+ ### Complexity Labeling Notes
155
155
 
156
- Consider splitting a feature if it exhibits any of the following:
156
+ Acceptance-criteria count, file count, and module count may raise the complexity **label**. They are not split reasons. Independently shippable is not a split reason.
157
+
158
+ Split a feature into additional **top-level** items only when implementation plus verification clearly cannot finish in one existing headless session, typically after crossing two or more heavy capability seams of one contract-bounded capability. Directory names are clues, not the grouping authority.
159
+
160
+ Do not split merely because of:
157
161
 
158
162
  - More than 8 acceptance criteria.
159
163
  - Touches more than 3 distinct modules or layers.
160
- - Requires both frontend and backend architectural decisions.
161
- - Involves third-party service integration AND non-trivial business logic.
162
- - Contains both real-time and batch processing requirements.
163
- - Needs new infrastructure (e.g., message queue, search index) AND application logic.
164
+ - Frontend and backend work in the same contract-bounded capability.
165
+ - Complexity `high`.
164
166
 
165
167
  ### Estimation Consistency Rules
166
168
 
167
- - If a feature is marked as `low` complexity, it should not have more than 5 acceptance criteria and should have no public API/schema changes.
169
+ - If a feature is marked as `low` complexity, its **label** usually matches a small surface; many confirmed acceptance criteria raise the label rather than forcing a split or dropped criteria.
168
170
  - If a feature is marked as `medium` complexity, explain why the scope is bounded even if it touches multiple files.
169
171
  - If a feature is marked as `high` complexity, it must have a clear concrete justification (e.g., "payment processing with webhook idempotency across API, persistence, and worker modules").
170
172
  - Use `critical` complexity only for features requiring architectural changes that touch 10+ files, involve cross-module API surface changes, or need stronger review and test gates for safety.
@@ -210,44 +212,18 @@ These rules ensure the feature dependency graph is valid and buildable.
210
212
 
211
213
  ---
212
214
 
213
- ## Session Granularity Decision Rules
214
-
215
- Session granularity determines whether a feature is implemented in a single coding session or split across multiple sub-feature sessions.
216
-
217
- ### Decision Table
218
-
219
- | Condition | Granularity | Notes |
220
- |-----------|-------------|-------|
221
- | Acceptance criteria <= 5 | `feature` | Single session can handle it |
222
- | Acceptance criteria 6-8 | `feature` or `auto` | Use judgment based on complexity |
223
- | Acceptance criteria > 8 | `auto` | Define sub_features |
224
- | Touches <= 2 modules | `feature` | Focused enough for one session |
225
- | Touches 3+ modules | `auto` | Split by module boundary |
226
- | Complexity "low" | `feature` | Always single session |
227
- | Complexity "high" + many criteria | `auto` | Always consider splitting |
228
-
229
- ### Sub-Feature Naming Convention
230
-
231
- When using `auto` granularity with sub-features, name each sub-feature with the parent feature ID as a prefix:
232
-
233
- ```
234
- F-003-A: Backend API for [entity] CRUD
235
- F-003-B: Frontend UI for [entity] management
236
- F-003-C: Integration tests for [entity] workflows
237
- ```
238
-
239
- ### Sub-Feature Design Principles
215
+ ## Contract-Bounded Grouping Rules
240
216
 
241
- 1. **Independently testable.** Each sub-feature should produce a verifiable result on its own. A backend API sub-feature can be tested via API calls without the frontend.
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.
242
218
 
243
- 2. **Single concern.** Each sub-feature focuses on one layer or aspect: backend API, frontend UI, data migration, integration, etc.
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.
244
220
 
245
- 3. **Clear boundaries.** The interface between sub-features should be well-defined (e.g., API contracts between backend and frontend sub-features).
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`.
246
222
 
247
- 4. **Ordered when necessary.** Sub-features within a feature may have internal ordering (e.g., backend before frontend), but this should be captured in the sub-feature dependencies.
223
+ ### Examples
248
224
 
249
- ### When NOT to Split
225
+ - 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
+ - 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`.
250
228
 
251
- - If the feature is inherently atomic (e.g., "add a favicon" or "configure environment variables").
252
- - If splitting would create sub-features that are too small to justify a separate session (fewer than 2 acceptance criteria each).
253
- - If the feature involves tightly coupled frontend and backend logic where splitting would require extensive mocking.
229
+ Schema may still allow `session_granularity` and `sub_features` on historical lists. Do not use them for new or changed features.
@@ -29,7 +29,7 @@ If any consequential answer is unavailable, ambiguous, or present only in `user_
29
29
 
30
30
  ## Step 2: Contract and Material Checks
31
31
 
32
- - Preserve substantive user requirements, rationale, and constraints at matching detail; normalization must not collapse a detailed specification into a short summary.
32
+ - Preserve substantive user requirements, rationale, and constraints at matching detail; AI rewrite is allowed; dropping a confirmed item is not.
33
33
  - Expand option shorthand into complete selected meaning, for example: `Selected decision: use cursor pagination with a 50-item default`.
34
34
  - Do not emit transcript annotations such as `(original response: "...")`; parenthetical content must also be independently intelligible and materially useful.
35
35
  - Resolve `方案B`, `按推荐走`, `same as above`, or `go with your recommendation` only when there is one provable antecedent. Otherwise ask the user for clarification.
@@ -63,6 +63,9 @@ 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`.
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.
66
69
 
67
70
  ## Step 4: Present Review and Repair
68
71
 
@@ -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 single features rather than splitting too finely. A feature should represent a coherent unit of user-facing value.
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`.
75
75
  - If a pattern does not match the app being planned, combine elements from multiple patterns or define a custom decomposition from scratch.
@@ -45,6 +45,10 @@ For every reviewed feature entry, check:
45
45
  - Task-scoped `user_context` isolation: no unrelated sibling feature descriptions, file references, or supplementary materials; shared context appears on multiple items only when explicitly global
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
+ - 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
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
+ - Size: there is no word-count upper limit and no acceptance-criteria count upper limit; long contracts are not defects
48
52
  - Browser interaction fields for qualifying frontend/fullstack features when applicable
49
53
 
50
54
  ## Headless Context Completeness Gate
@@ -23,7 +23,7 @@ Read `.prizmkit/config.json`, `.prizmkit/plans/project-brief.md`, `.prizmkit/pri
23
23
  Rules:
24
24
  - Include foundational setup feature first only when the existing project still needs setup work.
25
25
  - Aim 5-12 features for an initial executable plan unless the user explicitly scopes smaller.
26
- - Keep each feature implementable in one pipeline unit unless clearly too large.
26
+ - Keep each feature implementable in one pipeline unit unless implementation plus verification cannot finish in one existing headless session.
27
27
 
28
28
  For each feature define:
29
29
  - `id`
@@ -46,10 +46,11 @@ Check:
46
46
 
47
47
  ### Phase 5: Granularity
48
48
 
49
- Split into `sub_features` when:
50
- - scope crosses too many modules
51
- - acceptance criteria are excessive
52
- - complexity is high and uncertainty is high
49
+ Group by contract-bounded capability. Independently shippable is not a split reason. MUST NOT populate `sub_features`.
50
+
51
+ Split into additional top-level features only when:
52
+ - implementation plus verification cannot finish in one existing headless session
53
+ - the split is at a capability seam, and each item has a complete `description` plus `acceptance_criteria`
53
54
 
54
55
  ### Phase 6: Generate + Validate
55
56
 
@@ -71,7 +72,7 @@ Split into `sub_features` when:
71
72
  - Medium complexity: ≥50 words — add integration points, data model overview, error handling approach
72
73
  - High complexity: ≥80 words — add architecture decisions, performance considerations, security implications, migration strategy if applicable
73
74
  - Description must cover what, integration points, key behaviors, data model when applicable, and error/edge cases.
74
- - Write at least 1 testable acceptance criterion to satisfy schema validation. Fewer than 3 criteria is a planner quality warning; medium/high features should usually target 5+.
75
+ - Write at least 1 testable acceptance criterion to satisfy schema validation. There is no acceptance-criteria count upper limit; keep every confirmed criterion.
75
76
  - Keep dependency graph simple and explicit.
76
77
 
77
78
  ## Final Delivery Checklist
@@ -389,15 +389,22 @@ def validate_feature_list(data, is_new_plan=True):
389
389
  label, granularity, ", ".join(sorted(VALID_GRANULARITIES))
390
390
  )
391
391
  )
392
- if granularity == "auto":
393
- subs = feat.get("sub_features")
394
- if not isinstance(subs, list) or len(subs) == 0:
395
- warnings.append(
396
- "{}: granularity is 'auto' but no sub_features defined".format(label)
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
397
398
  )
399
+ )
398
400
 
399
- # -- Sub-features --
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
+ )
401
408
 
402
409
  # -- Browser interaction check (warning for frontend features) --
403
410
  has_frontend = bool(
@@ -519,8 +526,6 @@ def generate_template():
519
526
  "Linting and formatting configured",
520
527
  ],
521
528
  "status": "pending",
522
- "session_granularity": "feature",
523
- "sub_features": [],
524
529
  }
525
530
  ],
526
531
  "global_context": {
@@ -38,7 +38,7 @@ Before editing:
38
38
  2. Read `.prizmkit/prizm-docs/root.prizm` when present.
39
39
  3. Follow its pointers to only the relevant direct-child module index and nested detail documentation. Before modifying source, read the complete relevant detail plus the complete parent/child documents needed to resolve its pointers; grep-only fragments are insufficient modification context.
40
40
  4. If relevant detail documentation is missing, inspect only bounded target source files and narrowly implicated callers/contracts as fallback, record that detailed context was unavailable, and proceed without creating a placeholder. Context loading never creates or modifies documentation.
41
- 5. Read referenced layer rules when present. If a rule conflicts with the plan, stop and ask the user unless the plan clearly supersedes the rule.
41
+ 5. If the current task lands on frontend, backend, database, or mobile, Read `.prizmkit/rules/<layer>-rules.md` when that exact convention path exists. Skip a missing file without blocking. Never load all four files by default. If a task spans two layers, read both existing files. Map browser UI work to frontend, service or API work to backend, schema migration or ORM work to database, and iOS, Android, React Native, or Flutter work to mobile. Discover by exact path Read; do not depend on git tracking or glob. Use layer-rules only to fill HOW the plan does not specify. When a layer-rules sentence conflicts with current nested `.prizm` detail facts, committed OpenAPI or other contract sources, or project instruction conventions, those current sources win without a clarification pause. L0 `RULES:` MUST/NEVER remain authoritative for that key.
42
42
 
43
43
  ## Optional Inline Delegation
44
44
 
@@ -181,6 +181,7 @@ After Infrastructure Quick Scan completes, check if `detected_layers` is non-emp
181
181
  Invoke prizmkit-prizm-docs (Init operation), passing the two-tier module structure from Phase 4:
182
182
  - Create only documentation directories needed by complete documents; do not create placeholder sub-module files.
183
183
  - Generate exact `root.prizm` (L0) with `PRIZM_VERSION: 4`, project meta, and MODULE_INDEX listing only top-level modules. If module count > 15 or measured capacity requires it, use MODULE_GROUPS.
184
+ - When generating `root.prizm`, preserve an existing `LAYER_RULES:` block analogously to `PROJECT_BRIEF:`; do not convert it into MUST/NEVER `RULES:` entries and do not invent it by globbing `.prizmkit/rules/`.
184
185
  - For each module entry in MODULE_INDEX/MODULE_GROUPS, include only high-value intent tags and a pointer to one direct-child L1 at `.prizmkit/prizm-docs/<M>.prizm`.
185
186
  - Generate one direct-child L1 structural index for each top-level module. Record source submodules structurally, but emit a SUBDIRS pointer only when its complete nested L2 exists.
186
187
  - Skip all L2 during Init. Before later source modification, read a complete existing relevant L2 and complete resolving pointer documents; if absent, inspect bounded relevant source as fallback without creating a placeholder. `/prizmkit-retrospective` may later create a complete Value-Gate-qualified L2.
@@ -235,6 +236,7 @@ Otherwise, generate a project brief to capture the user's overall product vision
235
236
  - If exact match `PROJECT_BRIEF: .prizmkit/plans/project-brief.md` exists: skip (already correct)
236
237
  - If `PROJECT_BRIEF:` exists with a different path: warn user and ask to confirm update or keep old path
237
238
  - If not present: add `PROJECT_BRIEF: .prizmkit/plans/project-brief.md` at the end of `root.prizm`, after all standard sections
239
+ - If `root.prizm` already contains a `LAYER_RULES:` block, preserve it analogously to `PROJECT_BRIEF:` and do not convert it into MUST/NEVER `RULES:` entries. Do not invent `LAYER_RULES:` by globbing `.prizmkit/rules/`.
238
240
  - This ensures every AI session that loads L0 knows to read the project brief
239
241
 
240
242
  **Phase 8: Report**
@@ -46,7 +46,8 @@ Before proposing or finalizing a plan:
46
46
  1. Check whether project context such as `.prizmkit/prizm-docs/root.prizm`, `.prizmkit/config.json`, or a project brief exists.
47
47
  2. If initialization context is missing, do not block planning; load the README, manifests, project instruction files, source structure, and relevant source files as fallback.
48
48
  3. If Prizm docs exist, read `root.prizm`, follow only its relevant module/detail pointers, and use source fallback when detailed documentation is absent.
49
- 4. Read `${SKILL_DIR}/references/artifact-identity.md`, validate or generate `artifact_dir` exactly once, and keep it stable throughout this planning invocation.
49
+ 4. If the current requirement lands on frontend, backend, database, or mobile, Read `.prizmkit/rules/<layer>-rules.md` when that exact convention path exists. Skip a missing file without blocking. Never load all four files by default. If a requirement spans two layers, read both existing files. Map browser UI work to frontend, service or API work to backend, schema migration or ORM work to database, and iOS, Android, React Native, or Flutter work to mobile. Discover by exact path Read; do not depend on git tracking or glob. When a layer-rules sentence conflicts with current nested `.prizm` detail facts, committed OpenAPI or other contract sources, or project instruction conventions, those current sources win without a clarification pause. L0 `RULES:` MUST/NEVER remain authoritative for that key.
50
+ 5. Read `${SKILL_DIR}/references/artifact-identity.md`, validate or generate `artifact_dir` exactly once, and keep it stable throughout this planning invocation.
50
51
 
51
52
  ## Phase 1: Specify (`spec.md`)
52
53
 
@@ -51,6 +51,7 @@ Run this checklist after generating the Tasks section in plan.md. Fix any issues
51
51
  ## Rules Alignment
52
52
 
53
53
  - [ ] No spec or plan element conflicts with `.prizmkit/prizm-docs/root.prizm` RULES MUST/NEVER directives
54
+ - [ ] `RULES:` is MUST/NEVER, not a file pointer; layer-rules are loaded by convention path separately
54
55
  - [ ] Tech stack choices in plan.md match `.prizmkit/prizm-docs/root.prizm` TECH_STACK (if defined)
55
56
 
56
57
  ## Database Design (skip if no Data Model section)
@@ -174,6 +174,13 @@ TEMPLATE:
174
174
  - NEVER: <project-wide prohibition>
175
175
  - PREFER: <project-wide preference>
176
176
 
177
+ LAYER_RULES:
178
+ - frontend -> .prizmkit/rules/frontend-rules.md
179
+ - backend -> .prizmkit/rules/backend-rules.md
180
+ - database -> .prizmkit/rules/database-rules.md
181
+ - mobile -> .prizmkit/rules/mobile-rules.md
182
+ (Optional. Include only configured layers. Omit the key when no layer file was written. Never place these paths in RULES.)
183
+
177
184
  PATTERNS:
178
185
  - <pattern-name>: <one-line description of code pattern used across project>
179
186
 
@@ -192,6 +199,10 @@ CONSTRAINTS:
192
199
  - MODULE_INDEX must have arrow pointer (->) for every entry
193
200
  - MODULE_INDEX and MODULE_GROUPS entries point to direct-child L1 documents only
194
201
  - RULES limited to 5-10 most critical conventions
202
+ - RULES is MUST/NEVER (and optional PREFER), never a file-pointer list
203
+ - LAYER_RULES is optional; entries use arrow pointers only to `.prizmkit/rules/frontend-rules.md`, `.prizmkit/rules/backend-rules.md`, `.prizmkit/rules/database-rules.md`, and `.prizmkit/rules/mobile-rules.md`
204
+ - Omit skipped layers from LAYER_RULES; omit the key entirely when no layer file was written
205
+ - Init, Update, Rebuild, and Retrospective preserve an existing LAYER_RULES block analogously to PROJECT_BRIEF and do not convert it into MUST/NEVER RULES entries
195
206
  - No prose paragraphs
196
207
  - root.prizm RULES are AUTHORITATIVE: they override any conflicting L1/L2 RULES
197
208
 
@@ -16,6 +16,7 @@ STEPS:
16
16
  4. Create `.prizmkit/prizm-docs/` and only the mirrored directories needed by documents that will exist. Do not create placeholder detail files.
17
17
  5. Generate `root.prizm` (L0) with concise PROJECT, LANG, FRAMEWORK, BUILD, TEST, ENTRY, navigation pointers, and only Value-Gate-qualified global RULES/PATTERNS/CROSS_CUTTING facts. Set `PRIZM_VERSION: 4`. Keep L0 a summary/pointer map; never copy child interfaces, data flow, traps, decisions, or full rules. No CHANGELOG sections/files, UPDATED/date metadata, feature/bug/refactor/task/session/run/pipeline/workflow IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths.
18
18
  - If `.prizmkit/plans/project-brief.md` exists, add `PROJECT_BRIEF: .prizmkit/plans/project-brief.md`; otherwise skip it.
19
+ - If the previous `root.prizm` already contains a `LAYER_RULES:` block, preserve that block analogously to `PROJECT_BRIEF:`. Do not convert it into MUST/NEVER `RULES:` entries. Do not invent `LAYER_RULES:` by globbing `.prizmkit/rules/`.
19
20
  - Use MODULE_GROUPS whenever MODULE_INDEX cannot fit the required map within 4096B. More than 15 modules is a mandatory grouping trigger. Use 3-8 stable functional domains; never raise the L0 limit for project size.
20
21
  - Generate only high-value intent-matching keyword tags; do not copy exported names or imports mechanically when they add no navigation value.
21
22
  6. Generate one direct-child L1 structural index for each discovered top-level source module at `.prizmkit/prizm-docs/<module>.prizm`. Include concise MODULE, FILES navigation summary, RESPONSIBILITY, SUBDIRS, KEY_FILES, DEPENDENCIES, and at most three critical RULES. A SUBDIRS arrow is emitted only when its mirrored L2 exists, so every arrow resolves. Do not include INTERFACES, DATA_FLOW, TRAPS, DECISIONS, full rules, or a low-value file inventory.
@@ -14,7 +14,7 @@ STEPS:
14
14
  - each semantic L2 has the complete CONCERN terminal shape, explicit non-empty/non-overlapping FILES ownership, and one resolving L1 DETAILS pointer
15
15
  - unstable concern boundaries, empty normalized slugs, sibling or mirrored-path collisions, and overlapping ownership block arbitrary creation; report the required manual identity/ownership decision instead of task names or numeric suffixes
16
16
  5. Rewrite the existing L1 as a concise structural summary and pointer index only. Preserve SUBDIRS pointers for real source-submodule L2 and DETAILS pointers for semantic L2. Never copy child interfaces, data flow, traps, decisions, or full rules into L1. Remove an obsolete detail only after all still-valid protected knowledge has been preserved in its current owner and its source/concern identity no longer exists.
17
- 6. Update only the equivalent root MODULE_INDEX or MODULE_GROUPS entry in place. Preserve concise pointer-only parent behavior, existing project-wide knowledge, and `PROJECT_BRIEF:`. Use MODULE_GROUPS whenever MODULE_INDEX cannot fit within the unchanged 4096B L0 limit; more than 15 modules is a mandatory grouping trigger, not permission for a larger root.
17
+ 6. Update only the equivalent root MODULE_INDEX or MODULE_GROUPS entry in place. Preserve concise pointer-only parent behavior, existing project-wide knowledge, `PROJECT_BRIEF:`, and an existing `LAYER_RULES:` block. Do not convert `LAYER_RULES:` into MUST/NEVER `RULES:` entries. Use MODULE_GROUPS whenever MODULE_INDEX cannot fit within the unchanged 4096B L0 limit; more than 15 modules is a mandatory grouping trigger, not permission for a larger root.
18
18
  7. Measure exact raw UTF-8 bytes using hard limits L0/L1 4096B and L2 5120B. Report warning-range results without failing. For any rewritten target at 90% or above, trim low-value material, deduplicate, move child-owned behavior, or safely semantic-split toward 3277-3686B for L0/L1 or 4096-4607B for L2. Never delete protected knowledge for size; unresolved hard-limit or unsafe-split pressure blocks Rebuild.
19
19
  8. Build and validate the complete affected candidate set before replacement, then write bottom-up. Compare candidate/current bytes and do not rewrite byte-identical targets.
20
20
  9. Re-read actual bytes and validate Value/Cleanup compliance, complete semantic fields, FILES ownership, pointer resolution in both directions, hierarchy, parent-summary boundaries, capacity, and format. Warning-only results pass; hard-limit or format errors fail.
@@ -18,7 +18,7 @@ STEPS:
18
18
  - add only a genuinely new durable fact with no semantic equivalent
19
19
  Append-only repair is prohibited.
20
20
  6. Reconcile bottom-up. L2 owns Value-Gate-qualified INTERFACES/DATA_FLOW/DEPENDENCIES/RULES/TRAPS/DECISIONS. L1 owns concise FILES/KEY_FILES/SUBDIRS/DETAILS/DEPENDENCIES summaries. L0 changes only for project-map structure. When L2 has complete behavior, L0/L1 retain only a concise summary and resolving pointer, never copied interfaces, data flow, traps, decisions, or full RULES.
21
- 7. Preserve `PROJECT_BRIEF:` in `root.prizm`; it is managed by `/prizmkit-init`. Do not write prohibited history, date, workflow, branch, absolute-path, or runtime-artifact metadata.
21
+ 7. Preserve `PROJECT_BRIEF:` in `root.prizm`; it is managed by `/prizmkit-init`. Preserve an existing `LAYER_RULES:` block analogously; it is managed by app-planner Rules Configuration. Do not convert `LAYER_RULES:` into MUST/NEVER `RULES:` entries. Do not write prohibited history, date, workflow, branch, absolute-path, or runtime-artifact metadata.
22
22
  8. Skip comments/whitespace/formatting-only changes, `.prizm`-only changes, and test-only changes that reveal no durable behavior boundary or fact passing the Value Gate.
23
23
  9. If a new top-level directory qualifies as a module, create its direct-child L1 and add a concise pointer to MODULE_INDEX or MODULE_GROUPS. Use MODULE_GROUPS whenever MODULE_INDEX cannot fit within 4096B; never raise the limit for project size.
24
24
  10. Create L2 only for durable behavioral knowledge:
@@ -115,7 +115,7 @@ Prepare all candidates before the first replacement and write only after each ca
115
115
  3. Update the direct module index only as concise summaries and resolving pointers, using `SUBDIRS` or `DETAILS` as applicable.
116
116
  4. Update the root project map last and only when module structure or its concise resolving pointer changed.
117
117
 
118
- Complete `INTERFACES`, `DATA_FLOW`, `TRAPS`, `DECISIONS`, and full RULES owned by a child must not be copied into the module index or root project map. Parent docs retain the shortest useful summary and pointer. Preserve any root `PROJECT_BRIEF:` line because it is managed separately.
118
+ Complete `INTERFACES`, `DATA_FLOW`, `TRAPS`, `DECISIONS`, and full RULES owned by a child must not be copied into the module index or root project map. Parent docs retain the shortest useful summary and pointer. Preserve any root `PROJECT_BRIEF:` line because it is managed separately. Preserve any root `LAYER_RULES:` block analogously; do not convert it into MUST/NEVER `RULES:` entries.
119
119
 
120
120
  Before each replacement, compare candidate bytes with current bytes. A byte-identical candidate is not written, reordered, or reported as an update.
121
121
 
@@ -62,11 +62,11 @@ In an ordinary successful flow, `.prizmkit/plans/refactor-list.draft.json` is in
62
62
 
63
63
  Every new or changed refactor item is an executable contract for a fresh AI session that has never seen the planning conversation. Do not add new JSON fields, context objects, schema versions, or pipeline runtime structures. Use the existing fields correctly:
64
64
 
65
- 1. **Self-contained contract**: The item's `description` and `acceptance_criteria`, read together, MUST define the objective, current state, desired target architecture, selected decisions, scope boundaries, constraints, non-goals, relevant integrations and consumers, edge cases, behavior-preservation decisions, and completion evidence. Preserve substantive user requirements at matching detail.
65
+ 1. **Self-contained contract**: The item's `description` and `acceptance_criteria`, read together, MUST define the objective, current state, desired target architecture, selected decisions, scope boundaries, constraints, non-goals, relevant integrations and consumers, edge cases, behavior-preservation decisions, 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.
66
66
  2. **Supplementary evidence only**: `user_context` is supplementary evidence only. It may contain scoped exact excerpts and purpose-tagged references, but it MUST NOT expand, replace, or contradict the contract. If `user_context` were removed, a fresh refactor session must still know the current structure, target architecture, allowed scope, forbidden changes, preservation strategy, and verification evidence.
67
67
  3. **Purposeful scope**: Every path in `scope.files` and every related path reference must be a purpose-tagged target path in the task contract or supplementary evidence, stating what to inspect or change. The scope array may remain schema-compatible path strings, while `description` explains each path or coherent path group's role.
68
68
  4. **Clarify by impact, do not guess**: Ask when multiple meanings of target architecture, scope boundaries, preservation behavior, material applicability, or relative references would materially change the refactor contract. Keep AI-proposed architecture labeled as a recommendation until confirmed; retain low-risk reversible implementation details as explicit assumptions when safe.
69
- 5. **Item isolation**: Each refactor contract and its supplementary evidence contain only relevant goals, paths, constraints, desired end state, and preservation evidence.
69
+ 5. **Item isolation**: Each written task contract and its supplementary evidence contain only relevant goals, paths, constraints, desired end state, and preservation evidence. 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; independently shippable is not a split reason.
70
70
 
71
71
  ### Artifact-Wide AI Readability
72
72
 
@@ -389,7 +389,7 @@ Set behavior-preservation and testing expectations for each refactor item.
389
389
 
390
390
  ## Fast Path
391
391
 
392
- For simple refactoring with minimal scope (1-2 items, low/medium complexity, no cross-module impact, existing test coverage). Read `${SKILL_DIR}/references/fast-path.md` for eligibility criteria, full workflow (including AskUserQuestion format), conditions NOT to use, and an example session.
392
+ For simple refactoring with minimal scope (1-2 items, low/medium complexity, one contract-bounded capability, existing test coverage). Read `${SKILL_DIR}/references/fast-path.md` for eligibility criteria, full workflow (including AskUserQuestion format), conditions NOT to use, and an example session.
393
393
 
394
394
  ## Browser Verification
395
395