prizmkit 1.1.193 → 1.1.195

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (79) hide show
  1. package/bin/create-prizmkit.js +43 -12
  2. package/bundled/VERSION.json +3 -3
  3. package/bundled/dev-pipeline/.env.example +5 -0
  4. package/bundled/dev-pipeline/README.md +2 -1
  5. package/bundled/dev-pipeline/prizmkit_runtime/checkpoint_state.py +111 -30
  6. package/bundled/dev-pipeline/prizmkit_runtime/cli.py +44 -3
  7. package/bundled/dev-pipeline/prizmkit_runtime/commands.py +29 -9
  8. package/bundled/dev-pipeline/prizmkit_runtime/config.py +121 -44
  9. package/bundled/dev-pipeline/prizmkit_runtime/daemon.py +190 -37
  10. package/bundled/dev-pipeline/prizmkit_runtime/interoperability.py +1 -0
  11. package/bundled/dev-pipeline/prizmkit_runtime/iterate.py +2480 -0
  12. package/bundled/dev-pipeline/prizmkit_runtime/paths.py +3 -0
  13. package/bundled/dev-pipeline/prizmkit_runtime/runner_bookkeeping.py +32 -8
  14. package/bundled/dev-pipeline/prizmkit_runtime/runners.py +29 -12
  15. package/bundled/dev-pipeline/prizmkit_runtime/runtime_commit.py +13 -5
  16. package/bundled/dev-pipeline/prizmkit_runtime/status.py +166 -0
  17. package/bundled/dev-pipeline/scripts/feature_list_contract.py +964 -0
  18. package/bundled/dev-pipeline/scripts/generate-bootstrap-prompt.py +18 -40
  19. package/bundled/dev-pipeline/scripts/generate-bugfix-prompt.py +24 -19
  20. package/bundled/dev-pipeline/scripts/prompt_framework.py +24 -8
  21. package/bundled/dev-pipeline/templates/bootstrap-tier3.md +1 -63
  22. package/bundled/dev-pipeline/templates/bug-fix-list-schema.json +8 -6
  23. package/bundled/dev-pipeline/templates/bugfix-bootstrap-prompt.md +0 -10
  24. package/bundled/dev-pipeline/templates/feature-list-schema.json +8 -6
  25. package/bundled/dev-pipeline/templates/iterate/evaluate-prompt.md +97 -0
  26. package/bundled/dev-pipeline/templates/iterate/evaluation-schema.json +538 -0
  27. package/bundled/dev-pipeline/templates/iterate/headless-plan-prompt.md +66 -0
  28. package/bundled/dev-pipeline/templates/sections/phase-specify-plan-full.md +2 -2
  29. package/bundled/dev-pipeline/templates/sections/runtime-commit-handoff.md +13 -4
  30. package/bundled/rules/USAGE.md +15 -48
  31. package/bundled/rules/_rules-metadata.json +7 -14
  32. package/bundled/rules/general/coding-baseline.md +23 -0
  33. package/bundled/rules/prizm/prizm-progressive-loading.md +2 -2
  34. package/bundled/skills/_metadata.json +12 -42
  35. package/bundled/skills/app-planner/SKILL.md +2 -2
  36. package/bundled/skills/app-planner/references/generated-plan-review.md +2 -2
  37. package/bundled/skills/app-planner/references/project-state-detection.md +1 -1
  38. package/bundled/skills/app-planner/references/rules-configuration.md +158 -88
  39. package/bundled/skills/app-planner/scripts/validate-rules-configuration.py +543 -12
  40. package/bundled/skills/bug-planner/references/verification.md +4 -5
  41. package/bundled/skills/bugfix-pipeline-launcher/SKILL.md +20 -14
  42. package/bundled/skills/bugfix-pipeline-launcher/references/configuration.md +49 -9
  43. package/bundled/skills/feature-pipeline-launcher/SKILL.md +20 -14
  44. package/bundled/skills/feature-pipeline-launcher/references/configuration.md +49 -9
  45. package/bundled/skills/feature-planner/SKILL.md +3 -3
  46. package/bundled/skills/feature-planner/references/browser-interaction.md +9 -29
  47. package/bundled/skills/iterate-pipeline-launcher/SKILL.md +273 -0
  48. package/bundled/skills/iterate-pipeline-launcher/references/configuration.md +105 -0
  49. package/bundled/skills/prizmkit-code-review/SKILL.md +10 -8
  50. package/bundled/skills/prizmkit-code-review/references/independent-code-review.md +4 -1
  51. package/bundled/skills/prizmkit-code-review/references/review-report-template.md +2 -1
  52. package/bundled/skills/prizmkit-code-review/scripts/render_review_report.py +12 -8
  53. package/bundled/skills/prizmkit-implement/SKILL.md +2 -2
  54. package/bundled/skills/prizmkit-init/SKILL.md +10 -10
  55. package/bundled/skills/prizmkit-init/references/brownfield-deep-init.md +81 -0
  56. package/bundled/skills/prizmkit-plan/SKILL.md +2 -1
  57. package/bundled/skills/prizmkit-plan/assets/plan-template.md +2 -0
  58. package/bundled/skills/prizmkit-prizm-docs/SKILL.md +8 -4
  59. package/bundled/skills/prizmkit-prizm-docs/assets/prizm-docs-format.md +8 -7
  60. package/bundled/skills/prizmkit-prizm-docs/references/op-init.md +33 -16
  61. package/bundled/skills/prizmkit-prizm-docs/references/op-validate.md +1 -1
  62. package/bundled/skills/prizmkit-retrospective/SKILL.md +29 -12
  63. package/bundled/skills/prizmkit-retrospective/references/retrospective-result-schema.json +126 -2
  64. package/bundled/skills/prizmkit-retrospective/references/rule-evolution-steps.md +86 -0
  65. package/bundled/skills/prizmkit-test/SKILL.md +2 -1
  66. package/bundled/skills/prizmkit-workflow/SKILL.md +8 -0
  67. package/bundled/skills/prizmkit-workflow/references/cold-start-rules.md +84 -0
  68. package/bundled/templates/project-memory-template.md +3 -3
  69. package/package.json +1 -1
  70. package/src/clean.js +2 -3
  71. package/src/config.js +52 -39
  72. package/src/index.js +29 -111
  73. package/src/prompts.js +20 -87
  74. package/src/runtime-passthrough.js +324 -0
  75. package/src/scaffold.js +41 -294
  76. package/src/upgrade.js +7 -39
  77. package/bundled/dev-pipeline/templates/sections/phase-browser-verification-auto.md +0 -127
  78. package/bundled/dev-pipeline/templates/sections/phase-browser-verification-opencli.md +0 -124
  79. package/src/external-skills.js +0 -103
@@ -1,130 +1,200 @@
1
1
  # Rules Configuration — Contract and Procedure
2
2
 
3
- Configure optional per-layer development rules during app planning without mixing unconditional invariants with user-owned technology or workflow decisions.
3
+ Configure optional per-layer development rules (`.prizmkit/rules/<layer>-rules.md`) during app planning without forcing heavy multi-round questionnaires by default or mixing unconditional invariants with user-owned technology or workflow decisions.
4
4
 
5
5
  ## Design Contract
6
6
 
7
- Rules Configuration uses four resource roles per layer:
7
+ Rules Configuration supports two authoring paths—default **AI Auto-Synthesize** and **Advanced Manual Questionnaire (Quick / Full)**—plus **Skip rules configuration**, and emits one unified five-section `.prizmkit/rules/<layer>-rules.md` contract compatible with incremental retrospective evolution and cold-start upgrades.
8
+
9
+ Each layer (`frontend`, `backend`, `database`, `mobile`) maintains five canonical source resources under `${SKILL_DIR}/references/rules/<layer>/`:
8
10
 
9
11
  1. `question-manifest.json` — structural contract: question order, conditions, placeholders, fallback policy, and multi-profile behavior.
10
- 2. `question-bank.md` — user-facing decision wording and recommended options.
12
+ 2. `question-bank.md` — user-facing decision wording and recommended options (used in `Advanced Manual Questionnaire`).
11
13
  3. `fixed-rules.md` — invariant safety and correctness principles only.
12
14
  4. `derivation-rules.md` — rules owned by selected technologies, practices, permissions, and explicit defaults.
13
- 5. `template.md` — output layout; it contains no hidden decision that can override a confirmed answer.
15
+ 5. `template.md` — canonical domain layout and design-module structure; it contains no hidden decision that can override a confirmed answer.
14
16
 
15
17
  **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.
16
18
 
17
19
  **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`.
18
20
 
19
- ## Step 1: Detect Layers
21
+ ### Unified Five-Section Output Contract
20
22
 
21
- - Prefer `.prizmkit/config.json` `tech_stack` when present.
22
- - Otherwise infer layers from project files:
23
- - frontend: browser UI framework, bundler, or frontend package indicators;
24
- - backend: service framework, API entrypoint, or server runtime indicators;
25
- - database: schema, migrations, ORM, query, or database dependency indicators;
26
- - mobile: Flutter, React Native, iOS, Android, or native project indicators.
27
- - 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.
28
- - Include `Skip rules configuration` as a non-blocking option.
23
+ Every file written by `app-planner` at `.prizmkit/rules/<layer>-rules.md` (in both `ai-synthesized` and `manual-questionnaire` modes) uses this metadata header and section skeleton:
29
24
 
30
- ## Step 2: Choose Configuration Mode
25
+ ```markdown
26
+ # <Layer> Rules — <Project Name>
31
27
 
32
- Present three modes:
28
+ > Owner: app-planner
29
+ > Mode: ai-synthesized | manual-questionnaire
30
+ > Layer: frontend | backend | database | mobile
31
+ > Stack Snapshot: <concise verified/confirmed stack summary>
33
32
 
34
- - **Quick** — ask only manifest groups marked `quick_mode: true`; use the question bank's recommended option for every remaining applicable question.
35
- - **Full** — ask every applicable manifest group in order.
36
- - **Skip** — create no rule file for that layer and continue without reminders.
33
+ ## 1. Confirmed Stack & Scope Decisions
34
+ <!-- In ai-synthesized mode, label every entry with provenance: verified-from-code | confirmed-by-user | ai-inferred-default -->
37
35
 
38
- 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.
36
+ ## 2. Invariant Baseline
37
+ <!-- Layer invariants from fixed-rules.md without repeating coding-baseline.md or cohesive-modeling.md -->
39
38
 
40
- ## Step 3: Load and Validate Resources
39
+ ## 3. Stack-Specific Rules
40
+ <!-- Active derivation rules, frontend M1-M9 design modules or mobile dual-native iOS/Android profiles, and conflict-gated engineering risks -->
41
41
 
42
- For each selected layer:
42
+ ## 4. AI Change Permissions & Active Deny List
43
+ <!-- Selected/confirmed AI permissions, active deny list consistent with Section 3, and non-binding compatible recommendations -->
43
44
 
44
- 1. Read:
45
- - `${SKILL_DIR}/references/rules/<layer>/question-manifest.json`
46
- - `${SKILL_DIR}/references/rules/<layer>/question-bank.md`
47
- - `${SKILL_DIR}/references/rules/<layer>/fixed-rules.md`
48
- - `${SKILL_DIR}/references/rules/<layer>/derivation-rules.md`
49
- - `${SKILL_DIR}/references/rules/<layer>/template.md`
50
- 2. Run the deterministic resource validator before asking questions:
51
- ```bash
52
- python3 ${SKILL_DIR}/scripts/validate-rules-configuration.py \
53
- --rules-root ${SKILL_DIR}/references/rules
54
- ```
55
- 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.
45
+ ## 5. Project-Evolved Rules
46
+ <!-- Governed incremental rules evolved from verified review/test evidence; seeded empty on fresh generation and preserved verbatim on upgrade -->
47
+ ```
48
+
49
+ Size and hygiene limits (enforced by `--validate-output`):
50
+
51
+ - Target size: under **12 KB (12,288 bytes)** raw UTF-8 (soft warning band at 12 KB; hard failure above **16 KB / 16,384 bytes**).
52
+ - Evolution cap: maximum **20 entries** under `## 5. Project-Evolved Rules`.
53
+ - Zero unresolved `{{ ... }}` placeholders, raw question IDs, option-letter shorthand, transcript-provenance annotations, platform-specific skill paths, retired independent layer-rules skill names, workflow task IDs, or branch names.
54
+
55
+ ## Step 1: Detect Layers and Inspect Existing Layer Files
56
+
57
+ 1. Prefer `.prizmkit/config.json` `tech_stack` and confirmed earlier app-planner decisions when present.
58
+ 2. Otherwise infer active layers from project files and confirmed scope:
59
+ - `frontend`: browser UI framework, bundler, or frontend package indicators;
60
+ - `backend`: service framework, API entrypoint, or server runtime indicators;
61
+ - `database`: schema, migrations, ORM, query, or database dependency indicators;
62
+ - `mobile`: Flutter, React Native, iOS, Android, or native project indicators.
63
+ 3. For each detected/confirmed layer only, check whether `.prizmkit/rules/<layer>-rules.md` already exists via exact path Read (never load all four files by default and do not depend on globbing):
64
+ - If an existing file is stamped `Mode: cold-start-lightweight`, note it as a **Cold-Start Upgrade Candidate** and count its existing entries under `## 5. Project-Evolved Rules`.
65
+ - If an existing file is stamped `Mode: ai-synthesized` or `Mode: manual-questionnaire` (or a pre-mode rules file), note its current mode and `## 5. Project-Evolved Rules` count so the user can keep, re-synthesize/upgrade, or manually reconfigure without losing evolved rules.
66
+
67
+ ## Step 2: Single High-Level Confirmation
68
+
69
+ Present the detected/confirmed layers, a concise stack summary per layer, and any detected `Mode: cold-start-lightweight` upgrade candidates **once** through the current host's structured-choice capability when available (otherwise ask the same concise question in chat and wait for explicit input). Offer exactly three paths:
70
+
71
+ 1. **`AI Auto-Synthesize (Recommended)`** — synthesize unified `.prizmkit/rules/<layer>-rules.md` files automatically from project facts and canonical layer rule assets without multi-round questionnaires (and upgrade any detected `cold-start-lightweight` file while preserving all existing `## 5. Project-Evolved Rules` entries).
72
+ 2. **`Advanced Manual Questionnaire (Quick / Full)`** — run the interactive per-layer `question-manifest.json` questionnaire (`Quick` or `Full` mode).
73
+ 3. **`Skip rules configuration`** — create or modify no rule files and continue without reminders.
74
+
75
+ Do not force multi-round questionnaires when the user chooses `AI Auto-Synthesize (Recommended)` or `Skip rules configuration`.
76
+
77
+ ## Step 3: Validate Canonical Source Resources
78
+
79
+ Before synthesizing (Step 4A) or asking manual questions (Step 4B), load the relevant layer resources under `${SKILL_DIR}/references/rules/<layer>/` and run the deterministic static validator:
80
+
81
+ ```bash
82
+ python3 ${SKILL_DIR}/scripts/validate-rules-configuration.py \
83
+ --rules-root ${SKILL_DIR}/references/rules
84
+ ```
85
+
86
+ 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.
56
87
 
57
- ## Step 4: Ask and Normalize Decisions
88
+ ## Step 4A: AI Auto-Synthesize (Default Path)
58
89
 
59
- - Ask one manifest group at a time, with at most three questions per interaction.
60
- - Use the current host's structured-choice capability when available. A named platform tool is an implementation example, not part of this protocol.
90
+ For each confirmed layer, synthesize the unified five-section rule file by fusing four inputs:
91
+
92
+ 1. **Project Facts**:
93
+ - **Brownfield**: package/build manifests (`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `pom.xml`, `pubspec.yaml`, etc.), linter/formatter/compiler configs (`tsconfig.json`, `eslint*`, `biome.json`, `ruff.toml`, `.golangci.yml`, etc.), representative entry/module source files, `.prizmkit/prizm-docs/root.prizm`, and relevant pointed module/detail `.prizm` documents (architecture contracts, dependencies, traps, and decisions) when present.
94
+ - **Greenfield**: confirmed product vision, tech stack, infrastructure decisions, project conventions, frontend design direction, and architecture decisions captured earlier in `app-planner`.
95
+ 2. **Canonical Layer Assets** (`${SKILL_DIR}/references/rules/<layer>/{fixed-rules.md, derivation-rules.md, template.md}`):
96
+ - Pull invariant rules from `fixed-rules.md` (excluding source-only policy headers and gate notes).
97
+ - Select matching stack derivations from `derivation-rules.md` (applying `SEMANTIC_FALLBACK_POLICY` whenever a detected/confirmed stack has no pre-authored block—never importing an unselected recommended option's rules).
98
+ - For **frontend**: preserve invariant data-shape constraints, render the M1–M9 UI/UX design modules (keeping M1–M5 and M7 invariants, selecting M6 and M8 from responsive/localization/chrome facts, keeping M9 explicit not-applicable statement, keeping gate notes source-only, and keeping WCAG targets with the accessibility decision), name selected options then follow installed `package.json` versions and existing codegen/framework-docs entrypoints, mark compatible recommendations as non-binding (never Must-install unless selected or already present), and honor dependency-forbid constraints.
99
+ - For **mobile**: preserve dual-native `iOS` and `Android` profile separation when dual-native is detected or confirmed.
100
+ 3. **Built-in Global Rules Deduplication**:
101
+ - Check built-in framework rules (`coding-baseline.md` and `cohesive-modeling.md`) and active project linters/formatters/compilers.
102
+ - Do **not** repeat generic rules already enforced by `coding-baseline.md`, `cohesive-modeling.md`, or automated tooling; keep layer rules focused on concrete stack-specific, project-specific, and layer-invariant constraints.
103
+ 4. **Conflict-Gated AI Stack-Specific Engineering Risk Rules**:
104
+ - Add concise, falsifiable `MUST:` / `NEVER:` rules for high-impact engineering risks specific to the project's stack (such as concurrency, data integrity, schema/migration safety, SSR/hydration boundaries, auth/session boundaries, or wire-compatibility redlines).
105
+ - Filter every candidate through the Step 6 Conflict Gate so no synthesized rule contradicts confirmed decisions, active code contracts, or dependency permissions.
106
+
107
+ ### Single Consolidated Conflict Confirmation and Provenance
108
+
109
+ - Ask **only a single consolidated confirmation** (via the current host's structured-choice capability) if genuine mutually exclusive high-impact architecture conflicts exist across inputs (for example, conflicting datastore/ORM choices across backend and database layers, contradictory auth/deployment boundaries, or a stack requirement that conflicts with an explicit dependency-forbid rule).
110
+ - When no high-impact conflict exists, synthesize directly with zero extra question rounds.
111
+ - Label **every entry** in `## 1. Confirmed Stack & Scope Decisions` with one explicit evidence provenance token:
112
+ - `verified-from-code` — directly observed in repository manifests, configs, source code, or `.prizm` detail docs;
113
+ - `confirmed-by-user` — explicitly confirmed by the user in this `app-planner` session;
114
+ - `ai-inferred-default` — safe, reversible default synthesized when neither code nor user specified the choice.
115
+
116
+ ## Step 4B: Advanced Manual Questionnaire (Quick / Full Fallback)
117
+
118
+ Run this path only when the user selects `Advanced Manual Questionnaire (Quick / Full)` in Step 2. It preserves the full existing questionnaire contract without regression.
119
+
120
+ ### Choose Manual Depth
121
+
122
+ Present two depth options (plus `Skip` for individual layers):
123
+
124
+ - **Quick** — ask only manifest groups marked `quick_mode: true`; use `question-bank.md`'s recommended option for every remaining applicable question.
125
+ - **Full** — ask every applicable manifest group in order.
126
+
127
+ 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.
128
+
129
+ ### Ask, Normalize, and Derive
130
+
131
+ For each selected layer, read `question-manifest.json`, `question-bank.md`, `fixed-rules.md`, `derivation-rules.md`, and `template.md`:
132
+
133
+ - Ask one manifest group at a time, with at most three questions per interaction, using the current host's structured-choice capability when available.
61
134
  - Every non-essential question includes a skip/defer option.
62
135
  - Do not require letter shortcuts. Question-bank labels such as `A` and `B` are internal matching aids only.
63
- - Resolve every answer to a complete semantic decision immediately.
64
- - Track each question as one of:
65
- - `answered`;
66
- - `quick_default_authorized`;
67
- - `auto_derived`;
68
- - `conditionally_not_applicable`;
69
- - `explicitly_deferred`.
136
+ - Resolve every answer to a complete semantic decision immediately and track each question as `answered`, `quick_default_authorized`, `auto_derived`, `conditionally_not_applicable`, or `explicitly_deferred`.
70
137
  - 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.
138
+ - Conditional handling:
139
+ - `required_if` false means the question is not applicable;
140
+ - `auto_derived_when` true means the complete semantic answer is derived from an earlier decision;
141
+ - `options_vary_by` changes the option set but never authorizes guessing;
142
+ - For Mobile `Q1 == E`, follow `multi_profile_contract`: collect the listed dimensions separately for iOS and Android and render both profiles so a scalar answer never overwrites the other platform's decision.
143
+ - Derivation and fallback:
144
+ - Match normalized decisions to named derivation blocks in `derivation-rules.md`.
145
+ - If no pre-authored block exists, apply `SEMANTIC_FALLBACK_POLICY`: state the selected technology or practice, require consistency with official/current project conventions, preserve detected brownfield behavior unless migration was explicitly chosen, do not import a recommended option's rules, and do not leave the policy blank.
146
+ - For `No`, `None`, `Not required`, deferred, or conditionally skipped choices, render an explicit not-applicable or deferred statement.
147
+ - Resolve all `template.md` placeholders (`from_questions`, `from_fixed_rules`, `auto_generated`, `metadata`) with zero residual `{{ ... }}`, then emit the final file using the Unified Five-Section Output Contract stamped `> Mode: manual-questionnaire` (placing Decision Ledger and scope in Section 1, invariants in Section 2, stack/domain/design-module/testing/profile derivations in Section 3, AI permissions, active deny list, and non-binding compatible recommendations in Section 4, and `## 5. Project-Evolved Rules` in Section 5).
71
148
 
72
- ### Conditional Questions
149
+ ## Step 5: Cold-Start Upgrade Handoff
73
150
 
74
- - `required_if` false means the question is not applicable.
75
- - `auto_derived_when` true means the complete semantic answer is derived from an earlier decision.
76
- - `options_vary_by` changes the option set but never authorizes guessing.
77
- - 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.
151
+ When a target layer already has `.prizmkit/rules/<layer>-rules.md` stamped `Mode: cold-start-lightweight` (created by lightweight workflow cold-start preflight) and the user proceeds with synthesis or manual configuration:
78
152
 
79
- ## Step 5: Derive Rule Blocks
153
+ 1. **Read full existing file before replacement** and preserve its exact pre-write bytes in memory.
154
+ 2. **Extract `## 5. Project-Evolved Rules` deterministically**: copy every existing bullet/numbered rule entry under `## 5. Project-Evolved Rules` verbatim in its original order (ignoring only the empty cold-start HTML placeholder comment when real entries exist).
155
+ 3. **Carry verified repo constraints forward**: treat non-conflicting verified facts from the cold-start file as supporting brownfield evidence while upgrading Sections 1–4 into full `Mode: ai-synthesized` (or `Mode: manual-questionnaire`) rules.
156
+ 4. **Preserve every evolved entry intact**: write the extracted entries verbatim into `## 5. Project-Evolved Rules` of the upgraded file (never truncate, rewrite, or drop valid entries). On fresh generation with no prior evolved entries, seed `## 5. Project-Evolved Rules` empty with its HTML comment placeholder.
157
+ 5. **Verify preservation after write**: re-read the written file and confirm every extracted `## 5. Project-Evolved Rules` entry is still present verbatim. If any entry was lost or output validation fails, repair and re-verify (or restore exact pre-write bytes on unrecoverable failure).
80
158
 
81
- Apply derivation rules after all applicable decisions are normalized:
82
-
83
- 1. Match a normalized decision to a named derivation block.
84
- 2. If a pre-authored block exists, use it only for the matching option and compatible prior decisions.
85
- 3. If no pre-authored block exists, apply `SEMANTIC_FALLBACK_POLICY`:
86
- - state the selected technology or practice;
87
- - require consistency with its official/current project conventions;
88
- - preserve detected brownfield behavior unless the user explicitly chose migration;
89
- - do not import a recommended option's rules;
90
- - do not leave the placeholder blank.
91
- 4. For `No`, `None`, `Not required`, deferred, or conditionally skipped choices, render an explicit not-applicable or deferred statement. Never leave unexplained empty sections.
159
+ Apply the same `## 5. Project-Evolved Rules` preservation rule whenever regenerating or upgrading an existing `ai-synthesized` or `manual-questionnaire` file.
92
160
 
93
161
  ## Step 6: Conflict Gate
94
162
 
95
- Before rendering, build a decision ledger with one owner per policy domain, such as:
163
+ Before writing any `.prizmkit/rules/<layer>-rules.md` file, build a decision ledger with one owner per policy domain:
96
164
 
97
- - frontend localization, dependency permission, caller analysis, config permission, testing depth;
98
- - backend architecture, API style, authentication, data technology, cache/queue/deployment, observability, testing, AI permissions;
99
- - database model, identifier strategy, normalization, cache, audit, backup/HA, DDL permission;
100
- - mobile platform profile, navigation, platform features, testing, distribution, performance, AI permissions.
165
+ - `frontend`: localization, dependency permission, caller analysis, config permission, testing depth, design modules;
166
+ - `backend`: architecture, API style, authentication, data technology, cache/queue/deployment, observability, testing, AI permissions;
167
+ - `database`: model, identifier strategy, normalization, cache, audit, backup/HA, DDL permission;
168
+ - `mobile`: platform profile, navigation, platform features, testing, distribution, performance, AI permissions.
101
169
 
102
- Check every fixed and derived rule against the ledger:
170
+ Check every invariant, derived, and AI-synthesized rule against the ledger:
103
171
 
104
172
  - Fixed content may constrain only invariant safety/correctness.
105
- - Derived content may constrain only the option that owns the domain.
173
+ - Derived and synthesized content may constrain only the option or verified stack that owns the domain.
106
174
  - A selected `none` or `not required` decision suppresses incompatible requirement blocks.
107
175
  - Cross-layer references must agree on shared decisions; report disagreement instead of choosing silently.
108
- - If two active rules require incompatible behavior, fail generation, identify both source blocks, repair the source/decision state, and rerun the gate.
176
+ - If two active rules require incompatible behavior, **fail generation**, identify both source blocks, repair the source/decision state, and rerun the gate.
109
177
  - A Must-level derivation that names a package is incompatible with dependency permission forbid unless that package is already present or the decision ledger selected it. Fail generation rather than emit both.
178
+ - Compatible recommendations remain non-binding and must not contradict the decision ledger or dependency permissions.
110
179
 
111
- ## Step 7: Render and Validate
180
+ ## Step 7: Emit, Validate Output, and Run Fresh-Session Gate
112
181
 
113
- 1. Fill every template placeholder from the manifest categories:
114
- - `from_questions` — normalized decisions and compatible derivation blocks;
115
- - `from_fixed_rules` — invariant-only blocks;
116
- - `auto_generated` — bounded summaries, deny lists, recommendations, and platform profiles;
117
- - `metadata` — project identity and scope.
118
- 2. Recommendations are non-binding and must not contradict the decision ledger.
119
- 3. Scan the rendered document:
182
+ 1. Verify the candidate document contains:
183
+ - required headers (`Owner: app-planner`, `Mode: ai-synthesized | manual-questionnaire`, `Layer`, `Stack Snapshot`) and all five unified `## 1.`–`## 5.` sections;
120
184
  - no residual `{{ ... }}`;
121
- - no raw answer tokens or dialogue provenance;
122
- - no blank policy section without an explicit not-applicable statement;
185
+ - no raw question IDs, option-letter shorthand, or dialogue/transcript provenance;
186
+ - no blank policy section without an explicit not-applicable or deferred statement;
123
187
  - no duplicate policy domain with conflicting requirements;
124
- - no platform-specific source-of-truth path;
125
- - no reference to a retired independent layer-rules skill.
126
- 4. Run the app-planner Pre-Generation Headless Context Completeness Gate on every generated rule.
127
- 5. Write `.prizmkit/rules/<layer>-rules.md` only after all checks pass.
188
+ - no platform-specific source-of-truth path or reference to a retired independent layer-rules skill;
189
+ - no workflow task IDs, checkpoint IDs, internal artifact paths, or branch names.
190
+ 2. Run the app-planner Pre-Generation Headless Context Completeness Gate on every generated rule.
191
+ 3. Write `.prizmkit/rules/<layer>-rules.md` and run the deterministic output validator immediately:
192
+ ```bash
193
+ python3 ${SKILL_DIR}/scripts/validate-rules-configuration.py \
194
+ --validate-output .prizmkit/rules/<layer>-rules.md
195
+ ```
196
+ (Or run `--validate-output .prizmkit/rules` once all configured layers are written.)
197
+ 4. Require `valid: true` (exit code 0). If validation returns `valid: false` (exit code 1), fix the underlying synthesis/ledger source, re-render while preserving `## 5. Project-Evolved Rules`, and rerun `--validate-output` until it passes. If the 12 KB soft warning triggers, tighten redundant prose when safe while keeping all verified constraints and evolved rules intact.
128
198
 
129
199
  ## Step 8: Update `root.prizm`
130
200
 
@@ -142,10 +212,10 @@ Check every fixed and derived rule against the ledger:
142
212
 
143
213
  Report:
144
214
 
145
- - configured and skipped layers;
146
- - mode used per layer;
147
- - explicitly selected, quick-authorized, deferred, and not-applicable decisions;
148
- - deterministic resource validation result;
215
+ - configured, upgraded (from `cold-start-lightweight`), and skipped layers;
216
+ - mode used per layer (`ai-synthesized` or `manual-questionnaire` with Quick/Full depth);
217
+ - provenance summary (`verified-from-code`, `confirmed-by-user`, `ai-inferred-default`) or manual decision status summary;
218
+ - preserved `## 5. Project-Evolved Rules` entry count on upgrades;
219
+ - deterministic static resource validation (`--rules-root`) and generated output validation (`--validate-output`) results including byte size and warnings;
149
220
  - conflict-gate result;
150
- - rendered files and residual-placeholder check;
151
- - `root.prizm` pointer result.
221
+ - `root.prizm` `LAYER_RULES:` pointer result.