prizmkit 1.1.178 → 1.1.179
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.
- package/bundled/VERSION.json +3 -3
- package/bundled/rules/prizm/prizm-progressive-loading.md +1 -0
- package/bundled/skills/_metadata.json +1 -1
- package/bundled/skills/app-planner/SKILL.md +7 -7
- package/bundled/skills/app-planner/references/generated-plan-review.md +6 -6
- package/bundled/skills/app-planner/references/rules/frontend/derivation-rules.md +86 -18
- package/bundled/skills/app-planner/references/rules/frontend/fixed-rules.md +122 -1
- package/bundled/skills/app-planner/references/rules/frontend/question-bank.md +2 -2
- package/bundled/skills/app-planner/references/rules/frontend/question-manifest.json +4 -4
- package/bundled/skills/app-planner/references/rules/frontend/template.md +40 -1
- package/bundled/skills/app-planner/references/rules-configuration.md +8 -3
- package/bundled/skills/prizmkit-implement/SKILL.md +1 -1
- package/bundled/skills/prizmkit-init/SKILL.md +2 -0
- package/bundled/skills/prizmkit-plan/SKILL.md +2 -1
- package/bundled/skills/prizmkit-plan/references/verification-checklist.md +1 -0
- package/bundled/skills/prizmkit-prizm-docs/assets/prizm-docs-format.md +11 -0
- package/bundled/skills/prizmkit-prizm-docs/references/op-init.md +1 -0
- package/bundled/skills/prizmkit-prizm-docs/references/op-rebuild.md +1 -1
- package/bundled/skills/prizmkit-prizm-docs/references/op-update.md +1 -1
- package/bundled/skills/prizmkit-retrospective/references/structural-sync-steps.md +1 -1
- package/bundled/templates/project-memory-template.md +1 -0
- package/package.json +1 -1
package/bundled/VERSION.json
CHANGED
|
@@ -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.
|
|
@@ -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` — `
|
|
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` `
|
|
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` `
|
|
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` `
|
|
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 `
|
|
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 `
|
|
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` `
|
|
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` `
|
|
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` `
|
|
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 `
|
|
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 `
|
|
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` `
|
|
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` `
|
|
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
|
|
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`
|
|
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
|
-
-
|
|
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
|
|
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
|
|
219
|
-
- Client Components use TanStack Query
|
|
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
|
-
-
|
|
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
|
|
380
|
-
-
|
|
381
|
-
- Generation
|
|
382
|
-
- Business code references generated types using type-only import
|
|
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
|
|
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,
|
|
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
|
|
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**:
|
|
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
|
}
|
|
@@ -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
|
|
131
|
-
-
|
|
132
|
-
-
|
|
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
|
|
@@ -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.
|
|
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
|
|
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 `
|
|
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
|
|
|
@@ -6,6 +6,7 @@ This project uses PrizmKit with the Prizm documentation system for AI-optimized
|
|
|
6
6
|
### Progressive Loading Protocol
|
|
7
7
|
- ON SESSION START: Read exact `.prizmkit/prizm-docs/root.prizm` first when it exists; it alone is L0.
|
|
8
8
|
- ON TASK: Read only relevant direct-child L1 documents (`.prizmkit/prizm-docs/<module>.prizm`) selected through MODULE_INDEX or MODULE_GROUPS pointers.
|
|
9
|
+
- 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.
|
|
9
10
|
- ON FILE EDIT: Read the complete relevant nested L2 and complete parent/child documents needed to resolve its SUBDIRS or DETAILS pointer. Grep-only fragments are insufficient modification context.
|
|
10
11
|
- IF L2 IS ABSENT: Inspect bounded target source and narrowly implicated contracts without creating a placeholder; documentation creation belongs to Retrospective or explicit repair.
|
|
11
12
|
- NEVER load all `.prizm` docs at once, load unrelated modules, or create L3.
|