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
@@ -1,5 +1,5 @@
1
1
  {
2
- "frameworkVersion": "1.1.178",
3
- "bundledAt": "2026-08-15T02:56:19.265Z",
4
- "bundledFrom": "6b87213"
2
+ "frameworkVersion": "1.1.180",
3
+ "bundledAt": "2026-09-08T17:45:34.677Z",
4
+ "bundledFrom": "6b16941"
5
5
  }
@@ -5,6 +5,7 @@ description: "PrizmKit progressive context loading protocol"
5
5
  This project uses PrizmKit's progressive loading protocol:
6
6
  - ON SESSION START: Read exact `.prizmkit/prizm-docs/root.prizm` (L0 project map) when it exists.
7
7
  - ON TASK: Read only relevant direct-child L1 documents (`.prizmkit/prizm-docs/<module>.prizm`) selected through root MODULE_INDEX/MODULE_GROUPS pointers.
8
+ - LAYER_RULES: 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. When a layer-rules sentence conflicts with current L2 `.prizm` 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.
8
9
  - ON FILE EDIT: Read the complete relevant nested L2 document and complete parent/child documents needed to resolve its SUBDIRS or DETAILS pointer before modification. Grep-only fragments are insufficient modification context.
9
10
  - IF L2 IS ABSENT: Inspect only bounded target source and narrowly implicated contracts; proceed without creating a placeholder. Documentation creation belongs to Retrospective or explicit documentation repair and requires complete Value-Gate-qualified content.
10
11
  - NEVER load all L1/L2 documents at session start, create L3, or load unrelated modules.
@@ -1,5 +1,5 @@
1
1
  {
2
- "version": "1.1.178",
2
+ "version": "1.1.180",
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.",
@@ -47,7 +47,7 @@ If you believe the task is better suited for a different workflow, you MUST:
47
47
  2. `.prizmkit/plans/project-brief.draft.md` — working source during planning and saved draft when the user exits before completion
48
48
  3. The resolved project instruction target for the current AI host (with user consent) — only project conventions, infrastructure configuration (database conventions, deployment config, **cloud services**), frontend design direction, and architecture decisions
49
49
  4. `.prizmkit/rules/<layer>-rules.md` — per-layer development rules generated by Rules Configuration
50
- 5. `.prizmkit/prizm-docs/root.prizm` — `RULES:` pointer line only (not other root.prizm content; created minimally if absent)
50
+ 5. `.prizmkit/prizm-docs/root.prizm` — `LAYER_RULES:` pointer block only (not other root.prizm content; created minimally if absent)
51
51
 
52
52
  **Current-host project instruction target resolution**:
53
53
  - Identify the current AI host from direct runtime/session evidence and the host's own project conventions. Installed project resources, existing project files, and `.prizmkit/manifest.json` are supporting evidence only; they are not a platform identity or path allowlist and must not override stronger current-session evidence.
@@ -166,7 +166,7 @@ After Infrastructure configuration is complete (CP-AP-1.5), check whether the pr
166
166
 
167
167
  Rules are optional. If the user skips, AI uses general best practices freely — no reminders, no blocking.
168
168
 
169
- → Read `${SKILL_DIR}/references/rules-configuration.md` for the full contract: layer detection, explicit Quick/Full/Skip authorization, interactive decisions, invariant-only fixed rules, selected-option derivation with semantic fallback, dual-native profiles, conflict detection, deterministic resource validation, template rendering, and the `root.prizm` `RULES:` pointer update. Run `${SKILL_DIR}/scripts/validate-rules-configuration.py` before questioning and again before final rendering. Before writing rule files or updating the pointer, require both a passing decision-conflict gate and the Pre-Generation Headless Context Completeness Gate for every proposed new or changed rule.
169
+ → Read `${SKILL_DIR}/references/rules-configuration.md` for the full contract: layer detection, explicit Quick/Full/Skip authorization, interactive decisions, invariant-only fixed rules, selected-option derivation with semantic fallback, dual-native profiles, conflict detection, deterministic resource validation, template rendering, and the `root.prizm` `LAYER_RULES:` pointer update. Run `${SKILL_DIR}/scripts/validate-rules-configuration.py` before questioning and again before final rendering. Before writing rule files or updating the pointer, require both a passing decision-conflict gate and the Pre-Generation Headless Context Completeness Gate for every proposed new or changed rule.
170
170
 
171
171
  ### After rules configuration
172
172
 
@@ -298,7 +298,7 @@ Checkpoints catch cascading errors early — skipping one means the next phase b
298
298
  | **CP-AP-0** | Intent Confirmed | User confirmed session goal (produce / explore) | 1 |
299
299
  | **CP-AP-1** | Conventions Checked | Current-host project instruction target resolved; its `### Project Conventions` section is loaded or asked and up to date | 1 |
300
300
  | **CP-AP-1.5** | Infrastructure Checked | Resolved project instruction target `### Infrastructure` section addressed — database, deployment **and cloud services** each configured or explicitly deferred | 1-2 |
301
- | **CP-AP-1.6** | Rules Configured | Rules resources pass deterministic validation; Quick defaults are explicitly authorized; every detected layer has a conflict-free `.prizmkit/rules/<layer>-rules.md` or an explicit skip; dual-native choices use separate profiles; no residual placeholders remain; `root.prizm` `RULES:` pointer is up to date. | 2 |
301
+ | **CP-AP-1.6** | Rules Configured | Rules resources pass deterministic validation; Quick defaults are explicitly authorized; every detected layer has a conflict-free `.prizmkit/rules/<layer>-rules.md` or an explicit skip; dual-native choices use separate profiles; no residual placeholders remain; `root.prizm` `LAYER_RULES:` pointer is up to date. | 2 |
302
302
  | **CP-AP-2** | Vision Summary | Goal/users/differentiators confirmed by user. For brownfield: existing purpose confirmed or refined. | 1-2 |
303
303
  | **CP-AP-3** | Frontend Design Evaluated | For frontend projects: checked for existing UI/UX design system; user was asked if missing. **Auto-pass** for backend-only or non-UI projects. | 2 |
304
304
  | **CP-AP-4** | Project Brief Accumulated | The in-memory brief or `.prizmkit/plans/project-brief.draft.md` contains at least 3 ideas. For brownfield: already-implemented items marked `[x]` count toward this total. The final brief is not written before CP-AP-5.5. | 3 |
@@ -311,10 +311,10 @@ Checkpoints catch cascading errors early — skipping one means the next phase b
311
311
  Run this gate before any final handoff whenever the current `app-planner` session wrote or rewrote final app-level planning content. In full produce mode this runs after CP-AP-5.5 and the passing content's final writes; in Quick Context Mode it runs after the confirmed `.prizmkit/plans/project-brief.md` write; in conventions, infrastructure, architecture-decision, or rules-only final-write flows it runs after those writes and before the completion summary. This gate reviews generated planning artifacts directly, not implementation diffs.
312
312
 
313
313
  1. **Load the local reference**: read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the source of truth for app-planner generated content review.
314
- 2. **Read actual planning artifacts directly**: inspect current-session final outputs such as `.prizmkit/plans/project-brief.md`, changed sections in the resolved project instruction target, `.prizmkit/rules/<layer>-rules.md`, and `.prizmkit/prizm-docs/root.prizm` `RULES:` pointer line. Do not rely on `git status`, `git diff`, or `git diff --cached`, because `.prizmkit` planning artifacts are often gitignored or untracked.
314
+ 2. **Read actual planning artifacts directly**: inspect current-session final outputs such as `.prizmkit/plans/project-brief.md`, changed sections in the resolved project instruction target, `.prizmkit/rules/<layer>-rules.md`, and `.prizmkit/prizm-docs/root.prizm` `LAYER_RULES:` pointer block. Do not rely on `git status`, `git diff`, or `git diff --cached`, because `.prizmkit` planning artifacts are often gitignored or untracked.
315
315
  3. **Scope to new/changed app-planning content**: compare against pre-session snapshots or in-memory drafts when available. Preserve unchanged historical brief items, instruction-file sections, rules files, and Prizm doc content. For explore-only sessions, draft-save exits, or flows with no new final planning content, report: `Local generated-plan review: not applicable — no new final planning content written.`
316
316
  4. **Run the local checklist and fresh-session simulation** from the reference: project brief completeness; consistency of conventions, infrastructure, and architecture decisions; Rules Configuration resource-validation and conflict-gate evidence; selected-decision precedence; explicit not-applicable/deferred sections; dual-native profile separation; rules pointer consistency; normalization of selected decisions; purpose-tagged references; app-planner writable-boundary compliance; and downstream `feature-planner` readiness to produce `.prizmkit/plans/feature-list.json` without guessing or seeing the original conversation.
317
- 5. **Apply accepted fixes through the source/writer path**: project brief fixes go through the draft/checklist source, instruction-file section fixes go through the resolved project instruction target's section source with user confirmation when changing approved wording, rules fixes re-render from rules configuration answers/templates when available, and `root.prizm` fixes are limited to the `RULES:` pointer line.
317
+ 5. **Apply accepted fixes through the source/writer path**: project brief fixes go through the draft/checklist source, instruction-file section fixes go through the resolved project instruction target's section source with user confirmation when changing approved wording, rules fixes re-render from rules configuration answers/templates when available, and `root.prizm` fixes are limited to the `LAYER_RULES:` pointer block.
318
318
  6. **Recheck changed sections directly** after every accepted fix batch.
319
319
  7. **Report CP-AP-6** in the completion summary: include local generated-plan review verdict, reviewed app-planning artifacts/sections, accepted fixes (or "none"), and final writer/validation result.
320
320
 
@@ -325,7 +325,7 @@ After Phase 2, if framework-shaping architecture decisions emerged during planni
325
325
  **How it works**:
326
326
  1. If decisions are captured → run the Pre-Generation Headless Context Completeness Gate on each decision, then append passing decisions to the resolved project instruction target under `### Architecture Decisions`
327
327
  2. Downstream skills (feature-planner, prizmkit-plan, etc.) read the current host's project instruction context, so they automatically receive these decisions
328
- 3. Do NOT write architecture decision content directly to `.prizmkit/prizm-docs/root.prizm` — that file is maintained by `prizmkit-prizm-docs` and `prizmkit-retrospective`. (The `RULES:` pointer line is managed by Rules Configuration, not by this section.) If the project needs `.prizmkit/prizm-docs/`, recommend the user run `prizmkit-prizm-docs` init after planning.
328
+ 3. Do NOT write architecture decision content directly to `.prizmkit/prizm-docs/root.prizm` — that file is maintained by `prizmkit-prizm-docs` and `prizmkit-retrospective`. (The `LAYER_RULES:` pointer block is managed by Rules Configuration, not by this section.) If the project needs `.prizmkit/prizm-docs/`, recommend the user run `prizmkit-prizm-docs` init after planning.
329
329
 
330
330
  ## Project Brief Accumulation
331
331
 
@@ -361,7 +361,7 @@ After CP-AP-6 passes or is reported not applicable, present a summary and end th
361
361
  - Infrastructure config → resolved project instruction target `### Infrastructure` (database conventions + deployment config)
362
362
  - Tech stack assumptions → captured in `.prizmkit/plans/project-brief.md` and reused from `.prizmkit/config.json` when it already exists
363
363
  - Architecture decisions (if any) → resolved project instruction target `### Architecture Decisions`
364
- - Dev rules (if configured) → `.prizmkit/rules/<layer>-rules.md` (with `root.prizm` `RULES:` pointer)
364
+ - Dev rules (if configured) → `.prizmkit/rules/<layer>-rules.md` (with `root.prizm` `LAYER_RULES:` pointer)
365
365
  - Project brief → `.prizmkit/plans/project-brief.md`
366
366
  - Local generated-plan review → verdict, reviewed app-planning artifacts/sections, accepted fixes (or "none"), and final writer/validation result
367
367
 
@@ -4,7 +4,7 @@ Use this local review loop before app-planner presents the final completion summ
4
4
 
5
5
  ## Trigger
6
6
 
7
- Run only when the current `app-planner` session wrote or rewrote final app-level planning content. This includes project brief finalization, project conventions, infrastructure configuration, architecture decisions, rules files, or a `root.prizm` `RULES:` pointer update.
7
+ Run only when the current `app-planner` session wrote or rewrote final app-level planning content. This includes project brief finalization, project conventions, infrastructure configuration, architecture decisions, rules files, or a `root.prizm` `LAYER_RULES:` pointer update.
8
8
 
9
9
  For explore-only sessions, draft-save exits, validate-only checks, or other flows with no new final planning content, report: `Local generated-plan review: not applicable — no new final planning content written.`
10
10
 
@@ -16,7 +16,7 @@ Planning artifacts may be gitignored, untracked, or absent from staged and unsta
16
16
  - Draft brief when present: `.prizmkit/plans/project-brief.draft.md`
17
17
  - The exact project instruction target selected for the current session, limited to sections written or changed by app-planner
18
18
  - Generated rule files: `.prizmkit/rules/<layer>-rules.md`
19
- - Prizm docs root pointer: `.prizmkit/prizm-docs/root.prizm` `RULES:` line only
19
+ - Prizm docs root pointer: `.prizmkit/prizm-docs/root.prizm` `LAYER_RULES:` pointer block only
20
20
  - In-memory answers, draft brief data, rules configuration answers, or section snapshots captured before writes
21
21
 
22
22
  Do not rely on `git status`, `git diff`, or `git diff --cached` to decide whether app-planner output exists or changed. Do not invoke `/prizmkit-code-review` for this planner-output gate; `/prizmkit-code-review` remains the implementation/code-diff review gate after `/prizmkit-implement`.
@@ -26,7 +26,7 @@ Do not rely on `git status`, `git diff`, or `git diff --cached` to decide whethe
26
26
  1. Compare current final artifacts with pre-session snapshots or in-memory drafts when available.
27
27
  2. Review only newly added or changed app-planning sections from the current session.
28
28
  3. Preserve unchanged historical project brief ideas, instruction-file sections, rules files, and Prizm doc content.
29
- 4. For `.prizmkit/prizm-docs/root.prizm`, review only the `RULES:` pointer line managed by rules configuration.
29
+ 4. For `.prizmkit/prizm-docs/root.prizm`, review only the `LAYER_RULES:` pointer block managed by rules configuration.
30
30
  5. If no snapshot exists, review only the artifacts the current app-planner session reports as produced.
31
31
 
32
32
  ## Source-of-Truth Map
@@ -34,7 +34,7 @@ Do not rely on `git status`, `git diff`, or `git diff --cached` to decide whethe
34
34
  - `project-brief.md` fixes go through the draft/checklist project brief source representation described in `project-brief-guide.md`, then rewrite the final brief through the existing project brief writer path.
35
35
  - Project conventions, infrastructure, frontend design direction, and architecture decisions are source sections in the exact project instruction target selected for the current session. If a fix changes user-approved wording or meaning, ask for user confirmation before rewriting.
36
36
  - `.prizmkit/rules/<layer>-rules.md` fixes should re-render from the normalized decision ledger, invariant/derivation sources, and template inputs. Rerun `scripts/validate-rules-configuration.py` and the Rules Configuration conflict gate before rewriting. If no structured source remains, rebuild the decision ledger or ask for clarification; do not hand-patch a contradictory final rule file.
37
- - `root.prizm` fixes are limited to correcting or adding the `RULES:` pointer line; do not rewrite unrelated root content.
37
+ - `root.prizm` fixes are limited to correcting or adding the `LAYER_RULES:` pointer block; do not rewrite unrelated root content or convert `LAYER_RULES:` into MUST/NEVER `RULES:` entries.
38
38
 
39
39
  ## Review Checklist
40
40
 
@@ -47,7 +47,7 @@ For every reviewed app-planning artifact or section, check:
47
47
  - Consistency among conventions, infrastructure, architecture decisions, and project brief content
48
48
  - Infrastructure completeness or explicit deferral for database, deployment, and cloud services topics when those flows ran
49
49
  - Rules Configuration integrity: the deterministic resource validator passed; Quick defaults were explicitly authorized; fixed content contains only invariants; selected decisions own their policy domains; no active rule conflicts with the decision ledger; unmatched/not-applicable choices are explicit; dual-native decisions remain in separate iOS/Android profiles; and rendered files contain no residual placeholders
50
- - Rules pointer consistency: generated `.prizmkit/rules/<layer>-rules.md` files are referenced by the `root.prizm` `RULES:` line when rules were configured
50
+ - Rules pointer consistency: generated `.prizmkit/rules/<layer>-rules.md` files are referenced by the `root.prizm` `LAYER_RULES:` pointer block when rules were configured; `RULES:` remains MUST/NEVER and is not a file pointer
51
51
  - Substantive user meaning and detail preservation at matching detail after conversational normalization in project brief ideas, conventions, infrastructure notes, architecture decisions, and rules
52
52
  - Artifact-wide readability: every generated natural-language value across all AI-visible fields and sections—including briefs/drafts, instruction sections, generated rules, appendices, comments, brainstorm summaries, quoted evidence, and parentheticals—is a standalone domain statement without dialogue-role labels, question IDs, answer tokens, planning-option recommendation markers, raw answer-map content, or planning provenance
53
53
  - Every selected product or technical decision is expressed by complete meaning rather than `A`, `B`, `C`, `方案A`, `方案B`, or another unseen option label; substantive rationale remains durable, while opaque transcript provenance is absent
@@ -86,7 +86,7 @@ Apply this stricter gate prospectively to new or changed content and preserve un
86
86
 
87
87
  1. Present findings with artifact path, section name, severity, evidence, and suggested source change.
88
88
  2. Accept only findings that improve planner correctness, consistency, substantive meaning preservation, or downstream feature-planner readiness.
89
- 3. Apply accepted fixes to the source representation first: brief draft/checklist, instruction-file section source, rules answer/template source, or `root.prizm` `RULES:` pointer source.
89
+ 3. Apply accepted fixes to the source representation first: brief draft/checklist, instruction-file section source, rules answer/template source, or `root.prizm` `LAYER_RULES:` pointer source.
90
90
  4. Regenerate or rewrite final artifacts through the same writer path used by app-planner. Do not hand-patch final artifacts as a shortcut when a draft/source representation exists.
91
91
  5. Re-read the changed final artifacts directly and repeat the Headless Context Completeness Gate only for changed sections.
92
92
  6. Do not report `PASS` until every required fresh-session answer is available and each changed artifact passes its final writer/validation check.
@@ -21,6 +21,25 @@ Every confirmed option is valid input even when this file has no pre-authored bl
21
21
 
22
22
  Before output, compare all active blocks with the decision ledger. A selected decision owns its policy domain; incompatible blocks fail generation instead of being merged.
23
23
 
24
+ ## Design-module gate (source-only)
25
+
26
+ These notes are maintainer records for option-derived design modules. Do not inject them into generated frontend-rules.
27
+
28
+ ### M6 Narrow viewport and pointer type
29
+
30
+ - Failure if missing: a hover-only required action is unreachable on touch or narrow viewports
31
+ - Scope: option-derived — Q11 Mobile-first, Desktop-first, and Mobile only land MUST/NEVER lines; Q11 Desktop only renders an explicit not-applicable statement
32
+ - Product-page story: no
33
+ - Falsifiable: yes when touch or narrow viewports are in scope — a hover-only required action with no tap/click path fails
34
+ - Ownership: do not restate F-069 table-layout overflow; D-RESP-* keep selected breakpoint and touch-target policy
35
+
36
+ ### M8 Third-party chrome copy
37
+
38
+ - Failure if missing: vendor-default chrome (dialog close, placeholders, sr-only names) contradicts the selected localization strategy
39
+ - Scope: option-derived — Q13 catalog strategies route chrome through the catalog; Q13 hardcoded single-language keeps chrome in the selected language
40
+ - Product-page story: no
41
+ - Falsifiable: yes — vendor English Close on a localized or selected-language dialog fails
42
+
24
43
  ## Phase 2 Normalized Semantic Fill Table
25
44
 
26
45
  > These placeholders **don't need rule blocks**. Resolve the selected option or custom reply into the complete semantic value shown by the examples. Never copy raw answer tokens, recommendation markers, question IDs, dialogue labels, or planning chronology into placeholders. The Source column is internal derivation metadata only and never appears in generated rules.
@@ -31,7 +50,7 @@ Before output, compare all active blocks with the decision ledger. A selected de
31
50
  | `{{ generated_at }}` | Phase 4, AI writes current ISO date | `2026-05-18` |
32
51
  | `{{ project_scope }}` | Phase 0 ask user ("Which directories/subprojects does this spec apply to?") | `apps/web, apps/admin` |
33
52
  | `{{ design_source }}` | Q8 answer | `Responsive layout, token, and component constraints extracted into this rules document; transient planning source omitted` |
34
- | `{{ framework }}` | Q1 answer | `React 18+` |
53
+ | `{{ framework }}` | Q1 answer | `React` |
35
54
  | `{{ meta_framework }}` | Q2 answer | `Next.js (App Router)` |
36
55
  | `{{ package_manager }}` | Q3 answer | `pnpm` |
37
56
  | `{{ style_solution }}` | Q4 answer | `Tailwind CSS` |
@@ -57,7 +76,7 @@ Appendix placeholders are auto-generated by AI in Phase 4:
57
76
  | Template Placeholder | Generation Method |
58
77
  |---------------------|-------------------|
59
78
  | `{{ deny_list_summary }}` | Extract all "❌ Forbid" entries from §1.5 / §3 / §7.4 / §9 |
60
- | `{{ recommended_libs }}` | Recommend ecosystem based on `framework` / `style_solution` / `state_lib` combinations |
79
+ | `{{ recommended_libs }}` | Recommend a compatible ecosystem based on `framework` / `style_solution` / `state_lib`. Mark every appendix library **non-binding**. Never write Must-install. Do not list `react-hook-form`, `zod`, or `@tanstack/react-table` unless the decision ledger selected them or they are already present in the project. |
61
80
 
62
81
  ---
63
82
 
@@ -111,12 +130,19 @@ Appendix placeholders are auto-generated by AI in Phase 4:
111
130
  | Q11 = Desktop-first | `D-RESP-DF-01` | `{{ breakpoint_rules }}` |
112
131
  | Q11 = Desktop only | `D-RESP-DESKTOP-ONLY-01` | `{{ breakpoint_rules }}` |
113
132
  | Q11 = Mobile only | `D-RESP-MOBILE-ONLY-01` | `{{ breakpoint_rules }}` |
133
+ | Q11 = Mobile-first | `D-DESIGN-M6-TOUCH-01` | `{{ DESIGN_MODULE_M6 }}` |
134
+ | Q11 = Desktop-first | `D-DESIGN-M6-TOUCH-01` | `{{ DESIGN_MODULE_M6 }}` |
135
+ | Q11 = Mobile only | `D-DESIGN-M6-TOUCH-01` | `{{ DESIGN_MODULE_M6 }}` |
136
+ | Q11 = Desktop only | `D-DESIGN-M6-DESKTOP-ONLY-01` | `{{ DESIGN_MODULE_M6 }}` |
114
137
  | Q12 = Tailwind defaults | `D-BP-TW-01` | `{{ breakpoint_rules }}` |
115
138
  | Q12 = MD breakpoints | `D-BP-MD-01` | `{{ breakpoint_rules }}` |
116
139
  | Q12 = Custom breakpoints | `D-BP-CUSTOM-01` | `{{ breakpoint_rules }}` |
117
140
  | Q13 = Multi-language | `D-I18N-01` | `{{ i18n_rules }}` |
118
141
  | Q13 = Single-language, centralized | `D-I18N-NONE-01` | `{{ i18n_rules }}` |
119
142
  | Q13 = Single-language, hardcoding | `D-I18N-HARDCODE-01` | `{{ i18n_rules }}` |
143
+ | Q13 = Multi-language | `D-DESIGN-M8-CATALOG-01` | `{{ DESIGN_MODULE_M8 }}` |
144
+ | Q13 = Single-language, centralized | `D-DESIGN-M8-CATALOG-01` | `{{ DESIGN_MODULE_M8 }}` |
145
+ | Q13 = Single-language, hardcoding | `D-DESIGN-M8-HARDCODE-01` | `{{ DESIGN_MODULE_M8 }}` |
120
146
  | Q14 = WCAG 2.1 AA | D-A11Y-AA-01 | `{{ a11y_extra_rules }}` |
121
147
  | Q14 = WCAG 2.1 AAA | `D-A11Y-AAA-01` | `{{ a11y_extra_rules }}` |
122
148
  | Q14 = Basic keyboard reachability only | `D-A11Y-BASIC-01` | `{{ a11y_extra_rules }}` |
@@ -145,7 +171,8 @@ Appendix placeholders are auto-generated by AI in Phase 4:
145
171
  ### D-REACT-01
146
172
  **Trigger**: Q1 = React | **Inject into**: `{{ tech_stack_rules }}`
147
173
 
148
- - Framework: React 18+, use function components + Hooks. Forbid Class components.
174
+ - Selected framework: React. Follow the React major and APIs currently declared in the project's `package.json` and existing framework docs. Do not treat a planning-time major as current law.
175
+ - Use function components + Hooks. Forbid Class components.
149
176
  - Hooks rules:
150
177
  - Custom Hook filenames start with `use` (`useUserProfile.ts`).
151
178
  - Strictly forbid calling Hooks inside loops, conditions, or nested functions.
@@ -154,7 +181,7 @@ Appendix placeholders are auto-generated by AI in Phase 4:
154
181
  - Performance:
155
182
  - List rendering must provide a stable `key`. Forbid using `index` as key (unless the list is read-only and never reordered).
156
183
  - Reusable callbacks use `useCallback`. Reusable objects use `useMemo`. But **prefer restructuring the component** over abusing memo.
157
- - Large lists use virtualization (`react-window` / `react-virtuoso`).
184
+ - Large lists use virtualization only when the project's selected or already-present list library supports it; do not add a virtualization package as current law.
158
185
  - Context:
159
186
  - One Context carries only one concern.
160
187
  - Frequently updated state must not go in Context. Use a dedicated store.
@@ -211,12 +238,15 @@ Appendix placeholders are auto-generated by AI in Phase 4:
211
238
  ### D-NEXT-01
212
239
  **Trigger**: Q2 = Next.js | **Inject into**: `{{ tech_stack_rules }}`
213
240
 
214
- - Use App Router (`app/` directory). Forbid adding new Pages Router pages.
241
+ - Use the selected Next.js App Router (`app/` directory). Forbid adding new Pages Router pages.
242
+ - Before using framework APIs (`cookies`, `headers`, `metadata`, routing, caching), read the installed Next.js docs for the version in `package.json`. Do not copy training-time or planning-time API snapshots.
215
243
  - Default to Server Components. Explicitly mark `'use client'` when interactivity is needed, and push it down to leaf nodes.
216
244
  - Server Action function files start with `'use server'`. Forbid exposing sensitive logic in Client Components.
245
+ - Nested `generateMetadata` overrides the parent; do not assume parent metadata still applies to the nested route.
246
+ - Do not capture locale or auth at module top level (module scope runs once per process/bundle, not per request). Read them inside the request/render function.
217
247
  - Data fetching:
218
- - Server Components directly `await fetch`, using Next.js caching strategies (`cache`, `revalidate`).
219
- - Client Components use TanStack Query / SWR.
248
+ - Server Components directly `await fetch`, using the installed Next.js caching strategies.
249
+ - Client Components use the selected server-state library; do not force TanStack Query or SWR from the Next.js choice.
220
250
  - Route file naming follows Next.js conventions: `page.tsx`, `layout.tsx`, `loading.tsx`, `error.tsx`, `not-found.tsx`.
221
251
 
222
252
  ### D-NEXT-02
@@ -258,7 +288,8 @@ Appendix placeholders are auto-generated by AI in Phase 4:
258
288
  - Split into sub-components.
259
289
  - State variant order fixed: `base → hover → focus → active → disabled → dark`.
260
290
  - Forbid writing complex conditional class string concatenation in templates. Must use `clsx` or `tailwind-variants` / `cva`.
261
- - Recommend installing and enabling `prettier-plugin-tailwindcss` for automatic utility class sorting.
291
+ - Recommend installing and enabling `prettier-plugin-tailwindcss` for automatic utility class sorting. This remains non-binding unless already selected or present.
292
+ - 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.
262
293
 
263
294
  ### D-TAILWIND-02
264
295
  **Trigger**: Q4 = Tailwind | **Inject into**: `{{ style_specific_rules }}`
@@ -336,7 +367,8 @@ Appendix placeholders are auto-generated by AI in Phase 4:
336
367
  ### D-TANSTACK-01
337
368
  **Trigger**: Q6 = TanStack Query | **Inject into**: `{{ server_state_rules }}`
338
369
 
339
- - Server state uniformly uses TanStack Query. Forbid the `useEffect + fetch` pattern in components.
370
+ - TanStack Query applies only to non-secret server state. Forbid putting one-shot plaintext credentials into QueryCache, MutationCache, persisted stores, URLs, or initial HTML.
371
+ - For non-secret server state, use TanStack Query. Forbid the `useEffect + fetch` pattern in components for that class of data.
340
372
  - queryKey naming convention: `[domain, resource, params?]`. Must be a stable, serializable array.
341
373
  - Example: `['user', 'profile', { userId }]`, `['order', 'list', { page, status }]`.
342
374
  - Default config (set centrally in `QueryClient`):
@@ -345,7 +377,7 @@ Appendix placeholders are auto-generated by AI in Phase 4:
345
377
  - `retry: 1` (write operations `retry: 0`)
346
378
  - `refetchOnWindowFocus: false` (enable per business need)
347
379
  - Mutations must handle `onSuccess` to invalidate related queries (`queryClient.invalidateQueries`).
348
- - Error handling: use the global `QueryCache` `onError` hook for unified reporting. UI layer renders error state via the `error` field.
380
+ - Error handling: use the global `QueryCache` `onError` hook for unified reporting of non-secret failures. UI layer renders error state via the `error` field.
349
381
 
350
382
  ### D-TANSTACK-02
351
383
  **Trigger**: Q6 = TanStack Query | **Inject into**: `{{ server_state_rules }}`
@@ -376,10 +408,11 @@ Appendix placeholders are auto-generated by AI in Phase 4:
376
408
  ### D-OPENAPI-01
377
409
  **Trigger**: Q7 = OpenAPI auto-gen | **Inject into**: `{{ server_state_rules }}`
378
410
 
379
- - API types auto-generated from backend OpenAPI/Swagger. Recommended tools: `openapi-typescript` or `orval`.
380
- - Generated type files placed in `src/api/generated/`. **Forbid manual modification**. File header adds `// AUTO-GENERATED, DO NOT EDIT`.
381
- - Generation command named `gen:api` in `package.json`. CI validates generated output matches the committed version.
382
- - Business code references generated types using type-only import: `import type { User } from '@/api/generated'`.
411
+ - API types are generated from the backend OpenAPI/Swagger using the project's existing codegen command and generated-types entrypoint recorded in `package.json` or framework docs. Do not pin a codegen tool or a generated-types directory as current law.
412
+ - **Forbid manual modification** of generated contract files. File header adds `// AUTO-GENERATED, DO NOT EDIT` when the existing generator does not already mark them.
413
+ - Generation stays behind the repository's existing script name (commonly recorded in `package.json`). CI validates generated output matches the committed version when that check already exists.
414
+ - Business code references generated types using type-only import from the detected generated entrypoint.
415
+ - Do not disable contract assertions to ship an undeclared request body. Change the OpenAPI spec, then regenerate.
383
416
 
384
417
  ### D-PROTO-01
385
418
  **Trigger**: Q7 = Protobuf | **Inject into**: `{{ server_state_rules }}`
@@ -424,7 +457,7 @@ Appendix placeholders are auto-generated by AI in Phase 4:
424
457
  - Dark mode uses CSS variable switching: `:root` defines light, `:root[data-theme="dark"]` defines dark.
425
458
  - Switch via `<html data-theme="dark">` attribute. To avoid FOUC (Flash of Unstyled Content), an inline script must set it early in `<head>`.
426
459
  - **Every Semantic Token must have both light and dark values**. CI validates for omissions.
427
- - User preference persisted to `localStorage` and supports following the system setting (`prefers-color-scheme`).
460
+ - User preference may be persisted (for example `localStorage`) and supports following the system setting (`prefers-color-scheme`). A dedicated Zustand theme store is not required.
428
461
 
429
462
  ### D-DARK-CLASS-01
430
463
  **Trigger**: Q10 = class-based dark | **Inject into**: `{{ dark_mode_rules }}`
@@ -433,7 +466,7 @@ Appendix placeholders are auto-generated by AI in Phase 4:
433
466
  - Components use `dark:` prefix utilities, which must appear in pairs with base classes.
434
467
  - Example: `bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100`.
435
468
  - Before toggling, an inline script in `<head>` reads localStorage to set the initial class to avoid FOUC.
436
- - Supports following system theme (`prefers-color-scheme`).
469
+ - Supports following system theme (`prefers-color-scheme`). A dedicated Zustand theme store is not required.
437
470
 
438
471
  ### D-DARK-NONE-01
439
472
  **Trigger**: Q10 = No dark mode | **Inject into**: `{{ dark_mode_rules }}`
@@ -515,6 +548,7 @@ Appendix placeholders are auto-generated by AI in Phase 4:
515
548
  - Do not invent numeric coverage thresholds. Add them only when explicitly confirmed outside the tier choice.
516
549
  - Unit tests assert behavior and accessible semantics, isolate unstable dependencies, and use deterministic async assertions.
517
550
  - E2E tests cover product-defined critical flows rather than generic login/checkout/payment examples, with isolated data and deterministic setup/teardown.
551
+ - Selected test tiers must cover long unbounded strings, omitted optional fields, and stable error-identifier fixtures. Coverage percentages are not visual evidence of layout, overflow, or error-branch correctness.
518
552
 
519
553
  ### D-AI-DEP-STRICT-01
520
554
  **Trigger**: Q19 = No, forbid self-initiated | **Inject into**: `{{ ai_dependency_rule }}`
@@ -564,7 +598,7 @@ Appendix placeholders are auto-generated by AI in Phase 4:
564
598
  **Trigger**: Q18 = Not required | **Inject into**: `{{ ai_index_rule }}`
565
599
 
566
600
  - No central component registry is required. Update direct exports and affected consumers through the repository's existing structure.
567
- - Search the relevant component ownership areas before creating a duplicate; do not invent or periodically maintain an unselected index file.
601
+ - 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.
568
602
 
569
603
  ### D-AI-LINES-01
570
604
  **Trigger**: Q22 = N | **Inject into**: `{{ ai_max_lines }}`
@@ -730,6 +764,32 @@ Appendix placeholders are auto-generated by AI in Phase 4:
730
764
  - AI may modify config files, but must explain each change in the PR description.
731
765
  - Each config change must include: which file, what was changed, why the change is needed, and potential impact on other developers.
732
766
 
767
+ ### D-DESIGN-M6-TOUCH-01
768
+ **Trigger**: Q11 = Mobile-first, Desktop-first, or Mobile only | **Inject into**: `{{ DESIGN_MODULE_M6 }}`
769
+
770
+ - MUST expose any hover-revealed required action through a click/tap-reachable control at the selected narrow or touch breakpoints.
771
+ - NEVER hide the only path to a required action behind hover when the selected responsive strategy includes touch or a viewport narrower than the desktop layout.
772
+ - Forbidden counterexample: a row Edit control that appears only on hover and is absent on a touch device.
773
+
774
+ ### D-DESIGN-M6-DESKTOP-ONLY-01
775
+ **Trigger**: Q11 = Desktop only | **Inject into**: `{{ DESIGN_MODULE_M6 }}`
776
+
777
+ - Not applicable: the selected desktop-only strategy has no required touch or narrow-viewport path, so hover-only actions remain reachable under the selected pointer model.
778
+
779
+ ### D-DESIGN-M8-CATALOG-01
780
+ **Trigger**: Q13 = Multi-language or Single-language, centralized | **Inject into**: `{{ DESIGN_MODULE_M8 }}`
781
+
782
+ - MUST route third-party component chrome (dialog close, placeholders, pagination labels, sr-only control names) through the selected localization catalog.
783
+ - NEVER ship vendor-default chrome that contradicts that catalog on a user-visible or assistive-name surface.
784
+ - Forbidden counterexample: a localized dialog body with vendor English Close.
785
+
786
+ ### D-DESIGN-M8-HARDCODE-01
787
+ **Trigger**: Q13 = Single-language, hardcoding | **Inject into**: `{{ DESIGN_MODULE_M8 }}`
788
+
789
+ - MUST keep third-party component chrome in the same selected language as product copy.
790
+ - NEVER leave vendor-default another-language chrome on a user-visible or assistive-name surface.
791
+ - Forbidden counterexample: selected-language product copy beside a vendor English Close control.
792
+
733
793
 
734
794
  ## Template Placeholder Coverage Self-Check Table (Mandatory Check Before Phase 4 Rendering)
735
795
 
@@ -787,7 +847,15 @@ Appendix placeholders are auto-generated by AI in Phase 4:
787
847
  | `{{ FIXED_RULES_AI_BASE }}` | fixed-rules.md I9 | Invariant injection |
788
848
  | `{{ FIXED_RULES_GIT }}` | fixed-rules.md I10 | Invariant injection |
789
849
  | `{{ FIXED_RULES_SECURITY }}` | fixed-rules.md I11 | Invariant injection |
850
+ | `{{ FIXED_RULES_DESIGN_M1 }}` | fixed-rules.md I12 | Invariant injection |
851
+ | `{{ FIXED_RULES_DESIGN_M2 }}` | fixed-rules.md I13 | Invariant injection |
852
+ | `{{ FIXED_RULES_DESIGN_M3 }}` | fixed-rules.md I14 | Invariant injection |
853
+ | `{{ FIXED_RULES_DESIGN_M4 }}` | fixed-rules.md I15 | Invariant injection |
854
+ | `{{ FIXED_RULES_DESIGN_M5 }}` | fixed-rules.md I16 | Invariant injection |
855
+ | `{{ FIXED_RULES_DESIGN_M7 }}` | fixed-rules.md I17 | Invariant injection |
856
+ | `{{ DESIGN_MODULE_M6 }}` | D-DESIGN-M6-TOUCH-01 or D-DESIGN-M6-DESKTOP-ONLY-01 | Derivation |
857
+ | `{{ DESIGN_MODULE_M8 }}` | D-DESIGN-M8-CATALOG-01 or D-DESIGN-M8-HARDCODE-01 | Derivation |
790
858
  | `{{ deny_list_summary }}` | Phase 4 auto-extract all ❌ entries from §1.5/§3/§7.4/§9 | Auto-generated |
791
- | `{{ recommended_libs }}` | Phase 4 recommend based on framework + style_solution + state_lib | Auto-generated |
859
+ | `{{ recommended_libs }}` | Phase 4 recommend based on framework + style_solution + state_lib; non-binding; never Must-install; omit react-hook-form, zod, and @tanstack/react-table unless selected or already present | Auto-generated |
792
860
 
793
861
  **Self-check rule**: Before rendering, scan the output file. If any `{{ ... }}` string still remains, it's an alignment failure — must go back to Phase 2/3 to trace the issue.
@@ -12,6 +12,7 @@ These blocks contain only safety and correctness requirements that remain valid
12
12
  - In typed code, keep public inputs and outputs typed and justify any suppression or unsafe cast at the narrowest boundary.
13
13
  - Validate untrusted runtime data before treating it as a trusted application type.
14
14
  - Do not invent API fields, routes, component props, or library capabilities.
15
+ - Consumer types must not tighten optional or nullable contract fields to required.
15
16
  - Rationale: contract safety applies regardless of framework or type system.
16
17
 
17
18
  Inject into `{{ FIXED_RULES_TYPESCRIPT }}`.
@@ -38,6 +39,7 @@ Inject into `{{ FIXED_RULES_DENY_LIST }}`.
38
39
 
39
40
  - Components expose explicit inputs, outputs, states, and ownership boundaries.
40
41
  - Data-driven UI handles the applicable loading, error, empty, and success states or documents why a state cannot occur.
42
+ - Omitted optional or nullable contract fields are valid empty or missing UI states, not contract violations.
41
43
  - Shared components preserve accessibility semantics and consumer compatibility.
42
44
  - Rationale: clear component contracts are framework-independent.
43
45
 
@@ -57,6 +59,7 @@ Inject into `{{ FIXED_RULES_I18N_BASELINE }}`.
57
59
  - Do not swallow errors silently.
58
60
  - Async user actions expose a deterministic pending and failure outcome and prevent unintended duplicate submission where side effects are not idempotent.
59
61
  - User-facing errors avoid secrets and internal implementation details while logs preserve actionable diagnostic context.
62
+ - User-visible error branching uses a stable machine identifier from the API contract when one exists and must not match localized message substrings.
60
63
  - Rationale: failures must remain observable under every framework choice.
61
64
 
62
65
  Inject into `{{ FIXED_RULES_ERROR_HANDLING }}`.
@@ -103,6 +106,8 @@ Inject into `{{ FIXED_RULES_GIT }}`.
103
106
  ## I11. Frontend Security
104
107
 
105
108
  - Never place secrets or privileged credentials in browser-delivered code.
109
+ - Secrets and reusable plaintext credentials must not live in global client caches, persisted stores, URLs, or initial HTML.
110
+ - Authenticated streams that need custom headers use fetch plus ReadableStream and never EventSource.
106
111
  - Treat browser validation as usability and defense-in-depth, not as the server authorization boundary.
107
112
  - Sanitize untrusted rich content and protect external navigation boundaries against opener and redirect abuse.
108
113
  - Sensitive side effects require the authorization and confirmation behavior defined by the product contract.
@@ -110,6 +115,122 @@ Inject into `{{ FIXED_RULES_GIT }}`.
110
115
 
111
116
  Inject into `{{ FIXED_RULES_SECURITY }}`.
112
117
 
118
+ ## Design-module gate (source-only)
119
+
120
+ These notes are maintainer records for the four-question gate. Do not inject them into generated frontend-rules.
121
+
122
+ ### M1 Asynchronous UI states
123
+
124
+ - Failure if missing: user cannot tell pending vs empty vs failure vs success; a non-idempotent control can be activated again while in flight; a failed write is shown as success
125
+ - Scope: invariant — holds for every frontend option
126
+ - Product-page story: no
127
+ - Falsifiable: yes — a reviewer can mark distinct pending/empty/failure/success presentation and in-flight lock as done or not done
128
+
129
+ ### M2 Overflow recovery after truncation
130
+
131
+ - Failure if missing: truncated unbounded text has no path back to the full string
132
+ - Scope: invariant — holds for every frontend option
133
+ - Product-page story: no
134
+ - Falsifiable: yes — clipped text without title, tooltip, expand, or equivalent recovery fails
135
+ - Ownership: F-069 keeps nowrap, max-width-without-truncate, and stacked min-width table-layout; this module does not restate those rules
136
+
137
+ ### M3 Stacking and floating layers
138
+
139
+ - Failure if missing: a floating layer covers primary or row actions, or a modal lets the page scroll through
140
+ - Scope: invariant — holds for every frontend option
141
+ - Product-page story: no
142
+ - Falsifiable: yes — covered controls or background scroll-through fail
143
+
144
+ ### M4 Dangerous or non-idempotent actions
145
+
146
+ - Failure if missing: a destructive or other non-idempotent action runs without confirmation, stays active in flight, or is presented as success after failure
147
+ - Scope: invariant — holds for every frontend option
148
+ - Product-page story: no
149
+ - Falsifiable: yes — missing confirmation, an enabled in-flight control, or fake success fails
150
+
151
+ ### M5 Focus, keyboard, and accessible names
152
+
153
+ - Failure if missing: overlay focus is not moved or restored; an icon-only control has no accessible name; a required state is conveyed by color alone
154
+ - Scope: invariant — holds for every frontend option; WCAG AA/AAA remain the selected Q14 derivation
155
+ - Product-page story: no
156
+ - Falsifiable: yes — unnamed controls, lost focus, or color-only required state fail
157
+
158
+ ### M7 Leave and conflict recovery
159
+
160
+ - Failure if missing: unsaved close or navigation drops edits with no prompt; a detected write conflict silently overwrites newer server state
161
+ - Scope: invariant — holds for every frontend option when unsaved edits or write conflicts can occur
162
+ - Product-page story: no
163
+ - Falsifiable: yes — silent discard or silent overwrite fails
164
+
165
+ ### M9 Motion
166
+
167
+ - Failure if missing: none that a reviewer can mark done or not done without an aesthetic preference or duplicating M1 or M5
168
+ - Scope: not applicable
169
+ - Product-page story: no
170
+ - Falsifiable: no
171
+ - Outcome: 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
172
+
173
+ ## I12. Asynchronous UI States
174
+
175
+ - MUST render distinct pending, empty, failure, and success presentations for data-driven views that can occupy those states, or document why a state cannot occur.
176
+ - MUST keep a user-visible retry or recovery control when a user-initiated load or mutation fails.
177
+ - MUST ignore or disable repeat activation of a non-idempotent control while its request is in flight.
178
+ - NEVER replace a failed mutation with a success presentation.
179
+ - NEVER leave only a blank or stale previous view with no pending or failure signal while a required load is in flight.
180
+ - Forbidden counterexample: a save control that stays enabled and shows a success toast after the request returns 500.
181
+
182
+ Inject into `{{ FIXED_RULES_DESIGN_M1 }}`.
183
+
184
+ ## I13. Overflow Recovery After Truncation
185
+
186
+ - MUST keep truncated user-visible text recoverable through title, tooltip, expand, or an equivalent full-text control.
187
+ - MUST apply that recovery wherever unbounded strings are clipped in tables, lists, badges, or single-line titles.
188
+ - NEVER clip unbounded text with no remaining path to the full string.
189
+ - Forbidden counterexample: a table cell that ellipsizes a description with no title, tooltip, or expand control.
190
+
191
+ Inject into `{{ FIXED_RULES_DESIGN_M2 }}`.
192
+
193
+ ## I14. Stacking and Floating Layers
194
+
195
+ - MUST keep the current view's primary action and in-row actions reachable while floating layers are open, unless the layer is a modal that intentionally owns the task.
196
+ - MUST prevent background page scroll-through while a modal overlay is open.
197
+ - NEVER allow a persistent floating layer to cover the current view's primary or row-level actions.
198
+ - Forbidden counterexample: a persistent launcher that sits on the last table action column so those controls cannot be activated.
199
+
200
+ Inject into `{{ FIXED_RULES_DESIGN_M3 }}`.
201
+
202
+ ## I15. Dangerous or Non-Idempotent Actions
203
+
204
+ - MUST require an explicit confirmation step before a destructive or other non-idempotent action that cannot be undone from the same view.
205
+ - MUST keep the triggering control inert while that action is in flight.
206
+ - MUST preserve the pre-action data and selection on failure; do not present the action as completed.
207
+ - NEVER treat a failed destructive or non-idempotent action as success.
208
+ - Forbidden counterexample: a Delete control that hides the row immediately, keeps it hidden after a 500, and offers no confirmation.
209
+
210
+ Inject into `{{ FIXED_RULES_DESIGN_M4 }}`.
211
+
212
+ ## I16. Focus, Keyboard, and Accessible Names
213
+
214
+ - MUST move focus into an overlay when it opens and restore focus to the invoking control when it closes.
215
+ - MUST close a dismissible overlay on Escape unless the product contract requires a choice first.
216
+ - MUST give every icon-only or graphic-only control an accessible name.
217
+ - MUST provide a keyboard-operable path to every interactive control that pointer users can activate.
218
+ - NEVER convey a required state (error, selected, destructive) by color alone.
219
+ - NEVER leave keyboard focus trapped in a closed overlay or lost after close.
220
+ - Forbidden counterexample: an icon-only destructive control with no accessible name.
221
+
222
+ Inject into `{{ FIXED_RULES_DESIGN_M5 }}`.
223
+
224
+ ## I17. Leave and Conflict Recovery
225
+
226
+ - MUST warn or offer save/discard before a navigation or close that would drop unsaved user edits.
227
+ - MUST present a user-controlled refresh or retry when a write conflict is detected, without silently overwriting newer server state.
228
+ - NEVER discard unsaved edits on overlay close or route change with no recovery prompt when those edits would be lost.
229
+ - NEVER silently overwrite a detected newer server state with the in-progress client payload.
230
+ - Forbidden counterexample: a dirty dialog that closes on overlay click and drops edits with no prompt.
231
+
232
+ Inject into `{{ FIXED_RULES_DESIGN_M7 }}`.
233
+
113
234
  ## Injection Contract
114
235
 
115
- Copy each `I*` block only into its named placeholder. Do not copy the header, policy metadata, or selected-decision boundary into generated files. If a proposed invariant conflicts with a confirmed decision, fail generation and reclassify the rule instead of emitting both.
236
+ Copy each `I*` block only into its named placeholder. Do not copy the header, policy metadata, selected-decision boundary, or Design-module gate notes into generated files. If a proposed invariant conflicts with a confirmed decision, fail generation and reclassify the rule instead of emitting both.
@@ -63,12 +63,12 @@ Total: 25 questions.
63
63
 
64
64
  ### Q1. Frontend Framework
65
65
  - **Options**:
66
- - A) React 18+ **【Recommended】**
66
+ - A) React **【Recommended】**
67
67
  - B) Vue 3
68
68
  - C) Svelte 5
69
69
  - D) Solid
70
70
  - E) Custom (specify version)
71
- - **Note**: Determines which hooks/Composition API-specific rules are injected.
71
+ - **Note**: Names the selected framework. Generated rules follow the major and APIs currently declared in the project's package.json and existing docs; do not freeze a planning-time major as current law.
72
72
  - **Maps to**: `{{ framework }}` (TL;DR) + `{{ tech_stack_rules }}` (derivation injection)
73
73
 
74
74
  ### Q2. Meta-Framework
@@ -36,9 +36,9 @@
36
36
  { "id": "Q8", "group": "G4", "topic": "Primary Design/Mockup Source", "maps_to": ["design_source"], "required": true },
37
37
  { "id": "Q9", "group": "G4", "topic": "Token Naming Layers", "maps_to": ["token_layering", "token_layering_rules"], "required": true },
38
38
  { "id": "Q10", "group": "G4", "topic": "Dark Mode", "maps_to": ["dark_mode", "dark_mode_rules"], "required": true },
39
- { "id": "Q11", "group": "G5", "topic": "Adaptation Strategy", "maps_to": ["responsive_strategy", "breakpoint_rules"], "required": true },
39
+ { "id": "Q11", "group": "G5", "topic": "Adaptation Strategy", "maps_to": ["responsive_strategy", "breakpoint_rules", "DESIGN_MODULE_M6"], "required": true },
40
40
  { "id": "Q12", "group": "G5", "topic": "Breakpoint Scheme", "maps_to": ["breakpoint_scheme", "breakpoint_rules"], "required": true },
41
- { "id": "Q13", "group": "G6", "topic": "Internationalization", "maps_to": ["i18n", "i18n_rules"], "required": true },
41
+ { "id": "Q13", "group": "G6", "topic": "Internationalization", "maps_to": ["i18n", "i18n_rules", "DESIGN_MODULE_M8"], "required": true },
42
42
  { "id": "Q14", "group": "G6", "topic": "Accessibility Target", "maps_to": ["a11y_level", "a11y_extra_rules"], "required": true },
43
43
  { "id": "Q15", "group": "G7", "topic": "Test Coverage Requirements", "maps_to": ["test_coverage", "test_rules"], "required": true },
44
44
  { "id": "Q16", "group": "G7", "topic": "Unit Test Framework", "maps_to": ["unit_test_framework", "test_rules"], "required": true, "required_if": "Q15 in [A, B]" },
@@ -52,8 +52,8 @@
52
52
  { "id": "Q24", "group": "G9", "topic": "Single Chunk Size Limit", "maps_to": ["bundle_size", "performance_rules"], "required": true }
53
53
  ],
54
54
  "template_placeholders": {
55
- "from_questions": ["framework", "meta_framework", "package_manager", "style_solution", "style_specific_rules", "font_strategy", "performance_rules", "state_lib", "state_rules", "server_state_lib", "server_state_rules", "api_type_source", "design_source", "token_layering", "token_layering_rules", "dark_mode", "dark_mode_rules", "responsive_strategy", "breakpoint_rules", "breakpoint_scheme", "i18n", "i18n_rules", "a11y_level", "a11y_extra_rules", "test_coverage", "test_rules", "unit_test_framework", "e2e_framework", "ai_index_rule", "ai_dependency_rule", "ai_breaking_change_rule", "ai_config_rule", "ai_max_lines", "lcp_target", "bundle_size", "tech_stack_rules"],
56
- "from_fixed_rules": ["FIXED_RULES_A11Y", "FIXED_RULES_AI_BASE", "FIXED_RULES_COMPONENT_CONTRACT", "FIXED_RULES_DENY_LIST", "FIXED_RULES_ERROR_HANDLING", "FIXED_RULES_GIT", "FIXED_RULES_I18N_BASELINE", "FIXED_RULES_NAMING", "FIXED_RULES_PERFORMANCE", "FIXED_RULES_SECURITY", "FIXED_RULES_TYPESCRIPT"],
55
+ "from_questions": ["framework", "meta_framework", "package_manager", "style_solution", "style_specific_rules", "font_strategy", "performance_rules", "state_lib", "state_rules", "server_state_lib", "server_state_rules", "api_type_source", "design_source", "token_layering", "token_layering_rules", "dark_mode", "dark_mode_rules", "responsive_strategy", "breakpoint_rules", "breakpoint_scheme", "i18n", "i18n_rules", "a11y_level", "a11y_extra_rules", "test_coverage", "test_rules", "unit_test_framework", "e2e_framework", "ai_index_rule", "ai_dependency_rule", "ai_breaking_change_rule", "ai_config_rule", "ai_max_lines", "lcp_target", "bundle_size", "tech_stack_rules", "DESIGN_MODULE_M6", "DESIGN_MODULE_M8"],
56
+ "from_fixed_rules": ["FIXED_RULES_A11Y", "FIXED_RULES_AI_BASE", "FIXED_RULES_COMPONENT_CONTRACT", "FIXED_RULES_DENY_LIST", "FIXED_RULES_DESIGN_M1", "FIXED_RULES_DESIGN_M2", "FIXED_RULES_DESIGN_M3", "FIXED_RULES_DESIGN_M4", "FIXED_RULES_DESIGN_M5", "FIXED_RULES_DESIGN_M7", "FIXED_RULES_ERROR_HANDLING", "FIXED_RULES_GIT", "FIXED_RULES_I18N_BASELINE", "FIXED_RULES_NAMING", "FIXED_RULES_PERFORMANCE", "FIXED_RULES_SECURITY", "FIXED_RULES_TYPESCRIPT"],
57
57
  "auto_generated": ["deny_list_summary", "recommended_libs"],
58
58
  "metadata": ["project_name", "generated_at", "project_scope"]
59
59
  }