prizmkit 1.1.154 → 1.1.156

package/bundled/skills/app-planner/references/rules/mobile/template.md

@@ -1,175 +1,163 @@
 # Mobile Rules — {{ project_name }}
 
-> This document was generated by the `mobile-rules` skill on {{ generated_at }}
-> Audience: All mobile developers + all AI coding assistants on this project
->
-> **Usage**:
-> 1. All AI coding assistants must read this file before generating or modifying any mobile code
-> 2. This document takes precedence over "general best practices" in AI training data
-> 3. Code conflicting with this document must not be committed
+> Generated by app-planner Rules Configuration
+> Audience: project contributors and AI coding assistants working on mobile applications
 
----
+This document contains confirmed mobile decisions. In dual-native mode, platform-specific rules belong to their named profile and never become an unqualified cross-platform requirement.
 
-## 0. TL;DR — Key Decisions at a Glance
+## 1. Decision Ledger
 
-| Dimension | Decision |
-|-----------|----------|
+| Domain | Selected Decision |
+|---|---|
 | Platform | {{ platform }} |
-| Min OS Version | {{ min_os_version }} |
-| Architecture Pattern | {{ architecture }} |
-| UI Framework | {{ ui_framework }} |
+| Minimum OS support | {{ min_os_version }} |
+| Architecture | {{ architecture }} |
+| UI framework | {{ ui_framework }} |
 | Navigation | {{ navigation }} |
-| State Management | {{ state_management }} |
+| State management | {{ state_management }} |
 | Networking | {{ networking }} |
-| Local Persistence | {{ persistence }} |
-| Push Notifications | {{ push_notifications }} |
-| Background Tasks | {{ background_tasks }} |
-| Permissions Strategy | {{ permissions_strategy }} |
-| Test Coverage | {{ test_coverage }} |
-| Unit Test Framework | {{ unit_test_framework }} |
-| E2E Test Framework | {{ e2e_framework }} |
+| Persistence | {{ persistence }} |
+| Push notifications | {{ push_notifications }} |
+| Background work | {{ background_tasks }} |
+| Permission timing | {{ permissions_strategy }} |
+| Test depth | {{ test_coverage }} |
+| Unit test framework | {{ unit_test_framework }} |
+| UI/E2E framework | {{ e2e_framework }} |
 | Distribution | {{ distribution }} |
-| Performance Target | {{ performance_target }} |
-| Accessibility Target | {{ a11y_target }} |
+| Performance | {{ performance_target }} |
+| Accessibility | {{ a11y_target }} |
 
----
+For dual-native projects, scalar cells summarize the profiles below; they do not replace profile-specific choices.
 
-## 1. Project Structure
+## 2. Platform Profiles
+
+{{ platform_profiles }}
+
+Single-platform projects render one profile. Dual-native projects render separate `iOS` and `Android` profiles containing UI framework, state management, networking, persistence, unit testing, and UI/E2E testing decisions.
+
+## 3. Project Structure and Architecture
+
+### 3.1 Platform ownership invariants
 
 {{ FIXED_RULES_STRUCTURE }}
 
+### 3.2 Selected platform and OS rules
+
 {{ tech_stack_rules }}
 
----
+### 3.3 Selected architecture
+
+{{ arch_rules }}
 
-## 2. UI Development
+## 4. UI and Navigation
+
+### 4.1 UI invariants and selected framework
 
 {{ FIXED_RULES_UI }}
 
 {{ ui_rules }}
 
----
-
-## 3. Navigation & Deep Linking
+### 4.2 Navigation
 
 {{ FIXED_RULES_NAVIGATION }}
 
 {{ navigation_rules }}
 
----
+A no-deep-link selection suppresses deep-link setup rules and records the accepted limitation explicitly.
+
+## 5. State, Networking, and Persistence
 
-## 4. State Management
+### 5.1 State
 
 {{ FIXED_RULES_STATE }}
 
 {{ state_rules }}
 
----
-
-## 5. Networking
+### 5.2 Networking
 
 {{ FIXED_RULES_NETWORKING }}
 
 {{ networking_rules }}
 
----
-
-## 6. Data Persistence
+### 5.3 Persistence
 
 {{ FIXED_RULES_PERSISTENCE }}
 
 {{ persistence_rules }}
 
----
+In dual-native mode, each derived block is assigned to its platform profile before rendering.
 
-## 7. Platform Features
+## 6. Platform Features
 
 {{ FIXED_RULES_PLATFORM_FEATURES }}
 
 {{ platform_features_rules }}
 
----
+Push and background sections are explicit `not applicable` statements when those capabilities are not selected. Permission behavior follows the selected timing decision.
+
+## 7. Performance and Accessibility
 
-## 8. Performance
+### 7.1 Performance
 
 {{ FIXED_RULES_PERFORMANCE }}
 
 {{ performance_rules }}
 
----
-
-## 9. Accessibility
+### 7.2 Accessibility
 
 {{ FIXED_RULES_A11Y }}
 
 {{ a11y_rules }}
 
----
-
-## 10. Security
+## 8. Security
 
 {{ FIXED_RULES_SECURITY }}
 
----
-
-## 11. Testing
+## 9. Testing
 
 {{ FIXED_RULES_TEST }}
 
 {{ test_rules }}
 
----
+Only selected test tiers are mandatory. Dual-native test frameworks are stated per profile.
 
-## 12. App Distribution
+## 10. Distribution
 
 {{ FIXED_RULES_DISTRIBUTION }}
 
 {{ distribution_rules }}
 
----
+Public-store, enterprise, and undecided distribution rules are mutually exclusive unless the user explicitly selects multiple channels.
 
-## 13. AI Vibecoding Behavior Constraints
+## 11. AI Change Permissions
 
-### 13.1 Baseline Constraints (project-agnostic, always active)
+### 11.1 Invariant change safety
 
 {{ FIXED_RULES_AI_BASE }}
 
-### 13.2 Project-Specific Hard Constraints
-
-- **Adding dependencies**: {{ ai_dependency_rule }}
-- **Modifying shared code**: {{ ai_breaking_change_rule }}
-- **Platform-specific code**: {{ ai_platform_rule }}
-
-### 13.3 Mandatory Pre-Actions (before every code generation)
-
-AI must complete the following in order before generating or modifying any mobile code:
+### 11.2 Selected permissions
 
-1. Read this file (`mobile-rules.md`)
-2. Read existing files in the target feature's directory to confirm whether similar functionality already exists
-3. If modifying shared widgets/components/services, search all callers and assess platform impact
-4. If modifying navigation routes or deep link schemes, assess all entry points
+- Dependency changes: {{ ai_dependency_rule }}
+- Shared-code impact analysis: {{ ai_breaking_change_rule }}
+- Platform-specific flexibility: {{ ai_platform_rule }}
 
----
+These decisions own their domains for each applicable platform profile.
 
-## 14. Architecture
-
-{{ arch_rules }}
-
----
-
-## Appendix A: Deny List (Quick Reference)
-
-> This appendix is auto-generated by AI in Phase 4 by extracting all forbidden entries from each section.
+## Appendix A: Active Deny List
 
 {{ deny_list_summary }}
 
-## Appendix B: Recommended Libraries & Tools
+Include only prohibitions from active invariant and selected blocks.
 
-> This appendix is auto-generated by AI in Phase 4 to recommend the supporting ecosystem based on platform and framework choices.
+## Appendix B: Compatible Recommendations
 
 {{ recommended_libs }}
 
----
+Recommendations must match the active platform profile and dependency-permission decision.
+
+## Source Contract
 
-**Version**: v1.0 — Generated on {{ generated_at }}
-**Next review recommended**: before tech stack changes or platform migration
+- Owner: app-planner Rules Configuration
+- Resource family: `references/rules/mobile/`
+- Regenerate after a decision or source-contract change.
+- Generation metadata value: {{ generated_at }}

package/bundled/skills/app-planner/references/rules-configuration.md

@@ -1,77 +1,145 @@
-# Rules Configuration — Full Procedure
+# Rules Configuration — Contract and Procedure
 
-Procedure for configuring per-layer development rules during app planning.
+Configure optional per-layer development rules during app planning without mixing unconditional invariants with user-owned technology or workflow decisions.
+
+## Design Contract
+
+Rules Configuration uses four resource roles per layer:
+
+1. `question-manifest.json` — structural contract: question order, conditions, placeholders, fallback policy, and multi-profile behavior.
+2. `question-bank.md` — user-facing decision wording and recommended options.
+3. `fixed-rules.md` — invariant safety and correctness principles only.
+4. `derivation-rules.md` — rules owned by selected technologies, practices, permissions, and explicit defaults.
+5. `template.md` — output layout; it contains no hidden decision that can override a confirmed answer.
+
+**Selected-decision precedence:** when a selected or explicitly authorized default conflicts with an unconditional rule, the selected decision wins and the unconditional content is invalid. Fix the source resources and rerun validation; never emit both rules.
+
+**Fixed-rule boundary:** a rule is invariant only when it remains correct for every option the layer exposes. Framework choice, architecture, API style, database model, test depth, dependency permission, deployment topology, localization strategy, navigation capability, and performance target are decision-owned and must not be placed in `fixed-rules.md`.
 
 ## Step 1: Detect Layers
 
 - Prefer `.prizmkit/config.json` `tech_stack` when present.
 - Otherwise infer layers from project files:
-  - frontend: `package.json` plus React/Vue/Svelte/Next/Vite indicators
-  - backend: Express/FastAPI/Django/Go/Java service indicators
-  - database: migrations, ORM config, schema files, or DB dependencies
-  - mobile: Flutter/React Native/iOS/Android indicators
-- Present detected layers with `AskUserQuestion`; include "Skip rules configuration" as a non-blocking option.
+  - frontend: browser UI framework, bundler, or frontend package indicators;
+  - backend: service framework, API entrypoint, or server runtime indicators;
+  - database: schema, migrations, ORM, query, or database dependency indicators;
+  - mobile: Flutter, React Native, iOS, Android, or native project indicators.
+- Present detected layers through the current host's structured-choice capability when available; otherwise ask the same concise question in chat and wait for explicit input.
+- Include `Skip rules configuration` as a non-blocking option.
 
 ## Step 2: Choose Configuration Mode
 
-- Quick mode asks only manifest groups marked `quick_mode: true`.
-- Full mode asks every manifest group in order.
-- Skip mode records no rules file for that layer and continues without reminders.
+Present three modes:
 
-## Step 3: Ask Questions with AskUserQuestion
+- **Quick** — ask only manifest groups marked `quick_mode: true`; use the question bank's recommended option for every remaining applicable question.
+- **Full** — ask every applicable manifest group in order.
+- **Skip** — create no rule file for that layer and continue without reminders.
 
-- Convert each question-bank option group into selectable `AskUserQuestion` options.
-- Do not ask users to type letter shortcuts such as `A` or `1`; those shortcuts are legacy notation in question banks only.
-- Every non-essential question includes a skip/defer option.
+Quick mode is explicit authorization to apply the concrete recommended meanings for unasked applicable questions. Record the resulting decisions, not the phrase `use recommendations`. If a question has no single recommendation for the selected technology or prior answer, Quick mode must ask it rather than guess.
 
-## Step 4: Configure Each Selected Layer — Full Q&A Workflow
-
-For each selected layer, run the 4-phase rule generation pattern:
-
-### Phase A — Load Layer Resources
-
-- Read `${SKILL_DIR}/references/rules/<layer>/fixed-rules.md` — industry-consensus rules injected without asking
-- Read `${SKILL_DIR}/references/rules/<layer>/question-bank.md` — interactive questions organized in groups (G1->G10): authoritative source for question text, options, "Recommended" markers, and Notes
-- Read `${SKILL_DIR}/references/rules/<layer>/question-manifest.json` — machine-readable structure for this layer. This is the asking checklist. It lists, per question: `group`, `required`, `maps_to`, `required_if`, `auto_derived_when`, and `options_vary_by`. Its `groups[]` carries each group's `quick_mode` flag, and `template_placeholders` is the expected-set for the Phase D self-check. Use the manifest to track coverage; use question-bank.md for the actual wording you present to the user. If a question id in one file is absent from the other, trust question-bank.md for content and note the drift.
-
-### Phase B — Interactive Q&A
-
-- Ask questions one group at a time (max 3 questions per message), as defined in question-bank.md.
-- Each question shows a "Recommended" option to reduce decision cost.
-- Quick mode: ask only the groups whose `quick_mode` is `true` in `question-manifest.json`. All other groups adopt recommended defaults silently.
-- Full mode: ask all groups in manifest order (`groups[]`).
-- Conditional questions:
-  - `required_if: "<expr>"` — ask this question only when the expression over prior answers holds. If false, the question is legitimately skipped.
-  - `auto_derived_when: "<expr>"` — when true, fill the mapped placeholder(s) from the prior answer without asking. Count as satisfied, not skipped.
-  - `options_vary_by: "<Qid>"` — the question is still asked; only its option list depends on that prior answer.
-- Legacy shortcut labels in question banks such as `recommended`, `default`, or `skip` are converted into selectable options in `AskUserQuestion`.
-- Do not ask the user to type these commands manually; selectable options prevent merged or missed decisions.
-- Resolve each response to a complete semantic choice and record only that normalized internal value after each group. Track which manifest questions are answered, auto-derived, or conditionally skipped so Phase D can verify coverage; raw turns and answer tokens are never writer input.
-
-### Phase C — Auto-derivation
-
-- Read `${SKILL_DIR}/references/rules/<layer>/derivation-rules.md`.
-- Match user answers against the trigger map using keyword matching.
-- Derive platform-specific rules without asking the user.
-
-### Phase D — Render and Write
-
-- Read `${SKILL_DIR}/references/rules/<layer>/template.md`.
-- Fill all template placeholders with accumulated content from Phases A+B+C.
-- Never copy raw answer text into a rendered rule. Convert option labels, custom replies, recommended/default shortcuts, and internal Q&A state into normalized semantic values that name the selected technology, behavior, constraint, or deferral.
-- Internal question IDs, answer tokens, `answers[Qx]`, dialogue-role labels, recommendation markers, and planning chronology must not appear in generated rules, TL;DR tables, headers, appendices, comments, or metadata prose.
-- Apply the same source durability rule during rendering: inline relevant meaning from non-code planning/evidence files and omit their transient paths; retain only purpose-tagged stable execution-time references.
-- Post-render self-check driven by `question-manifest.json` -> `template_placeholders`:
-  1. Coverage pass — for every placeholder in `from_questions`, confirm it traces to an answered question OR an `auto_derived_when` path OR a conditionally-skipped question (`required_if` false). If a `from_questions` placeholder has no source, go back and ask it before writing.
-  2. Residual pass — scan the rendered document for any residual `{{ ` or ` }}`; count must be 0. Placeholders in `from_fixed_rules`, `auto_generated`, and `metadata` are filled from fixed rules, Phase D generation, and project metadata.
-  3. AI-readability pass — scan all AI-visible fields and sections. Every generated natural-language value must stand alone without the planning conversation; reject raw turns, Q&A provenance, unresolved relative wording, or transient source dependencies before writing.
-- Generate Appendix A (Deny List) and Appendix B (Recommended Tools) per template instructions.
-- Create `.prizmkit/rules/` directory if it doesn't exist.
-- Write `.prizmkit/rules/<layer>-rules.md`.
-
-## Step 5: Update root.prizm RULES Pointer
-
-- Ensure `.prizmkit/prizm-docs/root.prizm` has a concise `RULES:` pointer to configured rules.
-- If root.prizm exists, update only the `RULES:` line.
-- If root.prizm is absent, create a minimal valid root.prizm with required fields and a `RULES:` pointer.
-- Do not write architecture decisions, project brief content, or changelog metadata into root.prizm.
+## Step 3: Load and Validate Resources
+
+For each selected layer:
+
+1. Read:
+   - `${SKILL_DIR}/references/rules/<layer>/question-manifest.json`
+   - `${SKILL_DIR}/references/rules/<layer>/question-bank.md`
+   - `${SKILL_DIR}/references/rules/<layer>/fixed-rules.md`
+   - `${SKILL_DIR}/references/rules/<layer>/derivation-rules.md`
+   - `${SKILL_DIR}/references/rules/<layer>/template.md`
+2. Run the deterministic resource validator before asking questions:
+   ```bash
+   python3 ${SKILL_DIR}/scripts/validate-rules-configuration.py \
+     --rules-root ${SKILL_DIR}/references/rules
+   ```
+3. If the manifest, question bank, fixed injection map, derivation fallback contract, or template placeholders drift, fail generation. Do not trust one source and continue because an incomplete rule document is worse than no rule document.
+
+## Step 4: Ask and Normalize Decisions
+
+- Ask one manifest group at a time, with at most three questions per interaction.
+- Use the current host's structured-choice capability when available. A named platform tool is an implementation example, not part of this protocol.
+- Every non-essential question includes a skip/defer option.
+- Do not require letter shortcuts. Question-bank labels such as `A` and `B` are internal matching aids only.
+- Resolve every answer to a complete semantic decision immediately.
+- Track each question as one of:
+  - `answered`;
+  - `quick_default_authorized`;
+  - `auto_derived`;
+  - `conditionally_not_applicable`;
+  - `explicitly_deferred`.
+- Never copy raw answer text, turns, question IDs, option labels, recommendation markers, or answer-map syntax into secondary outputs. Pass only normalized semantic values to rendering and review.
+
+### Conditional Questions
+
+- `required_if` false means the question is not applicable.
+- `auto_derived_when` true means the complete semantic answer is derived from an earlier decision.
+- `options_vary_by` changes the option set but never authorizes guessing.
+- For Mobile `Q1 == E`, follow `multi_profile_contract`: collect the listed dimensions separately for iOS and Android and render both profiles. A scalar answer must never overwrite the other platform's decision.
+
+## Step 5: Derive Rule Blocks
+
+Apply derivation rules after all applicable decisions are normalized:
+
+1. Match a normalized decision to a named derivation block.
+2. If a pre-authored block exists, use it only for the matching option and compatible prior decisions.
+3. If no pre-authored block exists, apply `SEMANTIC_FALLBACK_POLICY`:
+   - state the selected technology or practice;
+   - require consistency with its official/current project conventions;
+   - preserve detected brownfield behavior unless the user explicitly chose migration;
+   - do not import a recommended option's rules;
+   - do not leave the placeholder blank.
+4. For `No`, `None`, `Not required`, deferred, or conditionally skipped choices, render an explicit not-applicable or deferred statement. Never leave unexplained empty sections.
+
+## Step 6: Conflict Gate
+
+Before rendering, build a decision ledger with one owner per policy domain, such as:
+
+- frontend localization, dependency permission, caller analysis, config permission, testing depth;
+- backend architecture, API style, authentication, data technology, cache/queue/deployment, observability, testing, AI permissions;
+- database model, identifier strategy, normalization, cache, audit, backup/HA, DDL permission;
+- mobile platform profile, navigation, platform features, testing, distribution, performance, AI permissions.
+
+Check every fixed and derived rule against the ledger:
+
+- Fixed content may constrain only invariant safety/correctness.
+- Derived content may constrain only the option that owns the domain.
+- A selected `none` or `not required` decision suppresses incompatible requirement blocks.
+- Cross-layer references must agree on shared decisions; report disagreement instead of choosing silently.
+- If two active rules require incompatible behavior, fail generation, identify both source blocks, repair the source/decision state, and rerun the gate.
+
+## Step 7: Render and Validate
+
+1. Fill every template placeholder from the manifest categories:
+   - `from_questions` — normalized decisions and compatible derivation blocks;
+   - `from_fixed_rules` — invariant-only blocks;
+   - `auto_generated` — bounded summaries, deny lists, recommendations, and platform profiles;
+   - `metadata` — project identity and scope.
+2. Recommendations are non-binding and must not contradict the decision ledger.
+3. Scan the rendered document:
+   - no residual `{{ ... }}`;
+   - no raw answer tokens or dialogue provenance;
+   - no blank policy section without an explicit not-applicable statement;
+   - no duplicate policy domain with conflicting requirements;
+   - no platform-specific source-of-truth path;
+   - no reference to a retired independent layer-rules skill.
+4. Run the app-planner Pre-Generation Headless Context Completeness Gate on every generated rule.
+5. Write `.prizmkit/rules/<layer>-rules.md` only after all checks pass.
+
+## Step 8: Update `root.prizm`
+
+- Ensure `.prizmkit/prizm-docs/root.prizm` has a concise `RULES:` pointer to configured rule files.
+- If `root.prizm` exists, update only the `RULES:` line.
+- If absent, create only the minimal valid root plus the `RULES:` pointer allowed by the parent Skill.
+- Do not write architecture decisions, project brief content, temporal metadata, or changelog content into `root.prizm`.
+
+## Completion Evidence
+
+Report:
+
+- configured and skipped layers;
+- mode used per layer;
+- explicitly selected, quick-authorized, deferred, and not-applicable decisions;
+- deterministic resource validation result;
+- conflict-gate result;
+- rendered files and residual-placeholder check;
+- `root.prizm` pointer result.