@wildo-ai/framework-knowledge 1.1.8 → 1.1.10

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 (480) hide show
  1. package/dist/claude-marketplace/.claude-plugin/marketplace.json +1 -1
  2. package/dist/claude-marketplace/plugins/wildo/.claude-plugin/plugin.json +1 -1
  3. package/dist/claude-marketplace/plugins/wildo/references/acceptance.md +11 -0
  4. package/dist/claude-marketplace/plugins/wildo/references/composites-and-the-loop.md +9 -2
  5. package/dist/claude-marketplace/plugins/wildo/references/creation-state.md +21 -0
  6. package/dist/claude-marketplace/plugins/wildo/references/derived-artifacts.md +121 -0
  7. package/dist/claude-marketplace/plugins/wildo/references/expert-personas-and-deliberations.md +26 -7
  8. package/dist/claude-marketplace/plugins/wildo/references/runs-judges-and-questions.md +31 -5
  9. package/dist/claude-marketplace/plugins/wildo/skills/accept/SKILL.md +4 -2
  10. package/dist/claude-marketplace/plugins/wildo/skills/answer/SKILL.md +29 -2
  11. package/dist/claude-marketplace/plugins/wildo/skills/build/SKILL.md +69 -24
  12. package/dist/claude-marketplace/plugins/wildo/skills/doctor/SKILL.md +10 -0
  13. package/dist/claude-marketplace/plugins/wildo/skills/run/SKILL.md +21 -5
  14. package/dist/claude-marketplace/plugins/wildo/skills/start/SKILL.md +31 -5
  15. package/dist/claude-marketplace/plugins/wildo/skills/status/SKILL.md +2 -0
  16. package/dist/claude-marketplace/plugins/wildo/skills/why/SKILL.md +20 -4
  17. package/dist/esm/framework-knowledge.definitions.d.ts +1 -1
  18. package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -1
  19. package/dist/esm/framework-knowledge.definitions.js +95 -5
  20. package/dist/esm/framework-knowledge.definitions.js.map +1 -1
  21. package/dist/esm/framework-knowledge.loader.d.ts.map +1 -1
  22. package/dist/esm/index.d.ts.map +1 -1
  23. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts +2 -2
  24. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts.map +1 -1
  25. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js +2 -2
  26. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js.map +1 -1
  27. package/dist/esm/playbooks/bottom_up.build/playbook.definition.d.ts +11 -11
  28. package/dist/esm/playbooks/bottom_up.build/playbook.definition.d.ts.map +1 -1
  29. package/dist/esm/playbooks/bottom_up.build/playbook.definition.js +29 -22
  30. package/dist/esm/playbooks/bottom_up.build/playbook.definition.js.map +1 -1
  31. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts +41 -3
  32. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts.map +1 -1
  33. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js +175 -14
  34. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js.map +1 -1
  35. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts +1 -1
  36. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts.map +1 -1
  37. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js +3 -3
  38. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js.map +1 -1
  39. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.d.ts +1 -1
  40. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js +1 -1
  41. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js.map +1 -1
  42. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.d.ts +8 -4
  43. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.d.ts.map +1 -1
  44. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.js +13 -6
  45. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.js.map +1 -1
  46. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts +4 -2
  47. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts.map +1 -1
  48. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js +90 -13
  49. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js.map +1 -1
  50. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.d.ts +4 -3
  51. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.d.ts.map +1 -1
  52. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.js +4 -3
  53. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.js.map +1 -1
  54. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts +8 -0
  55. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts.map +1 -1
  56. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js +12 -4
  57. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js.map +1 -1
  58. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts +12 -3
  59. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts.map +1 -1
  60. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js +8 -4
  61. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js.map +1 -1
  62. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.d.ts +4 -1
  63. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.d.ts.map +1 -1
  64. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.js +2 -1
  65. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.js.map +1 -1
  66. package/dist/esm/playbooks/cross_cutting.application-creation/playbook.definition.d.ts.map +1 -1
  67. package/dist/esm/playbooks/cross_cutting.compliance/playbook.definition.d.ts.map +1 -1
  68. package/dist/esm/playbooks/cross_cutting.feature-development/playbook.definition.d.ts.map +1 -1
  69. package/dist/esm/playbooks/cross_cutting.refinement/playbook.definition.d.ts.map +1 -1
  70. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts.map +1 -1
  71. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts +1 -1
  72. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts.map +1 -1
  73. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js +13 -1
  74. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js.map +1 -1
  75. package/dist/esm/playbooks/refinement.feature-contribution/playbook.definition.d.ts.map +1 -1
  76. package/dist/esm/playbooks/refinement.governance-document-candidate/playbook.definition.d.ts.map +1 -1
  77. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts +25 -27
  78. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts.map +1 -1
  79. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js +91 -43
  80. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js.map +1 -1
  81. package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.d.ts +41 -0
  82. package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.d.ts.map +1 -0
  83. package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.js +43 -0
  84. package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.js.map +1 -0
  85. package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.d.ts +200 -0
  86. package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.d.ts.map +1 -0
  87. package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.js +203 -0
  88. package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.js.map +1 -0
  89. package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.d.ts +81 -0
  90. package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.d.ts.map +1 -0
  91. package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.js +93 -0
  92. package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.js.map +1 -0
  93. package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts +3 -1
  94. package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts.map +1 -1
  95. package/dist/esm/playbooks/top_down.business-model/playbook.definition.js +27 -18
  96. package/dist/esm/playbooks/top_down.business-model/playbook.definition.js.map +1 -1
  97. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts.map +1 -1
  98. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts +11 -1
  99. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts.map +1 -1
  100. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.js +11 -11
  101. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.js.map +1 -1
  102. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts +2 -0
  103. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts.map +1 -1
  104. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js +3 -1
  105. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js.map +1 -1
  106. package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.d.ts.map +1 -1
  107. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts +2 -0
  108. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts.map +1 -1
  109. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js +3 -1
  110. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js.map +1 -1
  111. package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.d.ts.map +1 -1
  112. package/dist/esm/playbooks/top_down.definition/playbook.definition.d.ts +5 -2
  113. package/dist/esm/playbooks/top_down.definition/playbook.definition.d.ts.map +1 -1
  114. package/dist/esm/playbooks/top_down.definition/playbook.definition.js +16 -4
  115. package/dist/esm/playbooks/top_down.definition/playbook.definition.js.map +1 -1
  116. package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.d.ts +27 -6
  117. package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.d.ts.map +1 -1
  118. package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.js +32 -12
  119. package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.js.map +1 -1
  120. package/dist/esm/playbooks/top_down.feature-drafts/playbook.definition.d.ts.map +1 -1
  121. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.d.ts.map +1 -1
  122. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.d.ts.map +1 -1
  123. package/dist/esm/playbooks/top_down.market-research/playbook.definition.d.ts.map +1 -1
  124. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts +2 -1
  125. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts.map +1 -1
  126. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js +13 -5
  127. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js.map +1 -1
  128. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts +7 -3
  129. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts.map +1 -1
  130. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js +71 -2
  131. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js.map +1 -1
  132. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts +2 -1
  133. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts.map +1 -1
  134. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js +23 -8
  135. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js.map +1 -1
  136. package/dist/esm/playbooks/top_down.risk-register/playbook.definition.d.ts +7 -1
  137. package/dist/esm/playbooks/top_down.risk-register/playbook.definition.d.ts.map +1 -1
  138. package/dist/esm/playbooks/top_down.risk-register/playbook.definition.js +4 -2
  139. package/dist/esm/playbooks/top_down.risk-register/playbook.definition.js.map +1 -1
  140. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts +9 -3
  141. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts.map +1 -1
  142. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js +3 -3
  143. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js.map +1 -1
  144. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts.map +1 -1
  145. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts +35 -2
  146. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts.map +1 -1
  147. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js +41 -17
  148. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js.map +1 -1
  149. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/authority-basis.json +1 -1
  150. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +1 -1
  151. package/dist/knowledge/manifest.json +8 -8
  152. package/dist/knowledge/playbooks/bottom_up.assemble-verify/method.md +22 -7
  153. package/dist/knowledge/playbooks/bottom_up.assemble-verify/playbook.json +3 -3
  154. package/dist/knowledge/playbooks/bottom_up.build/method.md +17 -15
  155. package/dist/knowledge/playbooks/bottom_up.build/playbook.json +4 -3
  156. package/dist/knowledge/playbooks/bottom_up.build-decompose/evaluation-protocol.json +1 -1
  157. package/dist/knowledge/playbooks/bottom_up.build-decompose/evaluation-treatment.json +1 -1
  158. package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +261 -34
  159. package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +42 -4
  160. package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +188 -59
  161. package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +2 -2
  162. package/dist/knowledge/playbooks/bottom_up.build-scale/method.md +169 -276
  163. package/dist/knowledge/playbooks/bottom_up.build-scale/playbook.json +2 -2
  164. package/dist/knowledge/playbooks/bottom_up.capability-composition/method.md +8 -1
  165. package/dist/knowledge/playbooks/bottom_up.capability-composition/playbook.json +1 -1
  166. package/dist/knowledge/playbooks/bottom_up.conception/method.md +3 -2
  167. package/dist/knowledge/playbooks/bottom_up.conception/playbook.json +11 -3
  168. package/dist/knowledge/playbooks/bottom_up.domain-plan/evaluation-protocol.json +1 -1
  169. package/dist/knowledge/playbooks/bottom_up.domain-plan/evaluation-treatment.json +1 -1
  170. package/dist/knowledge/playbooks/bottom_up.domain-plan/method.md +129 -17
  171. package/dist/knowledge/playbooks/bottom_up.domain-plan/playbook.json +7 -4
  172. package/dist/knowledge/playbooks/bottom_up.experience-plan/method.md +28 -6
  173. package/dist/knowledge/playbooks/bottom_up.experience-plan/playbook.json +5 -4
  174. package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +13 -5
  175. package/dist/knowledge/playbooks/bottom_up.placement-plan/method.md +50 -0
  176. package/dist/knowledge/playbooks/bottom_up.placement-plan/playbook.json +16 -4
  177. package/dist/knowledge/playbooks/bottom_up.website-plan/method.md +19 -0
  178. package/dist/knowledge/playbooks/bottom_up.website-plan/playbook.json +5 -2
  179. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +7 -3
  180. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +1 -1
  181. package/dist/knowledge/playbooks/refinement.document-facts/method.md +8 -0
  182. package/dist/knowledge/playbooks/refinement.document-facts/playbook.json +3 -2
  183. package/dist/knowledge/playbooks/refinement.feature-contribution/method.md +5 -2
  184. package/dist/knowledge/playbooks/refinement.feature-contribution/playbook.json +1 -1
  185. package/dist/knowledge/playbooks/top_down.brand-identity/evaluation-protocol.json +1 -1
  186. package/dist/knowledge/playbooks/top_down.brand-identity/evaluation-treatment.json +1 -1
  187. package/dist/knowledge/playbooks/top_down.brand-identity/method.md +75 -37
  188. package/dist/knowledge/playbooks/top_down.brand-identity/playbook.json +35 -38
  189. package/dist/knowledge/playbooks/top_down.brand-name-research/method.md +145 -0
  190. package/dist/knowledge/playbooks/top_down.brand-name-research/playbook.json +57 -0
  191. package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/evaluation-protocol.json +1 -0
  192. package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/evaluation-treatment.json +1 -0
  193. package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/method.md +99 -0
  194. package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/playbook.json +65 -0
  195. package/dist/knowledge/playbooks/top_down.brand-naming/method.md +56 -0
  196. package/dist/knowledge/playbooks/top_down.brand-naming/playbook.json +76 -0
  197. package/dist/knowledge/playbooks/top_down.business-model/evaluation-protocol.json +1 -1
  198. package/dist/knowledge/playbooks/top_down.business-model/evaluation-treatment.json +1 -1
  199. package/dist/knowledge/playbooks/top_down.business-model/method.md +60 -6
  200. package/dist/knowledge/playbooks/top_down.business-model/playbook.json +15 -10
  201. package/dist/knowledge/playbooks/top_down.capability-map/method.md +10 -9
  202. package/dist/knowledge/playbooks/top_down.capability-map/playbook.json +1 -1
  203. package/dist/knowledge/playbooks/top_down.compliance-analysis/playbook.json +30 -10
  204. package/dist/knowledge/playbooks/top_down.compliance-conception/playbook.json +3 -1
  205. package/dist/knowledge/playbooks/top_down.compliance-posture/playbook.json +4 -1
  206. package/dist/knowledge/playbooks/top_down.definition/method.md +8 -3
  207. package/dist/knowledge/playbooks/top_down.definition/playbook.json +6 -4
  208. package/dist/knowledge/playbooks/top_down.expert-personas/playbook.json +16 -2
  209. package/dist/knowledge/playbooks/top_down.feature-drafts/method.md +5 -2
  210. package/dist/knowledge/playbooks/top_down.feature-drafts/playbook.json +1 -1
  211. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/evaluation-protocol.json +1 -1
  212. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/evaluation-treatment.json +1 -1
  213. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/method.md +26 -0
  214. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/playbook.json +4 -2
  215. package/dist/knowledge/playbooks/top_down.phase-gate/evaluation-protocol.json +1 -1
  216. package/dist/knowledge/playbooks/top_down.phase-gate/evaluation-treatment.json +1 -1
  217. package/dist/knowledge/playbooks/top_down.phase-gate/playbook.json +11 -1
  218. package/dist/knowledge/playbooks/top_down.requirements-definition/evaluation-protocol.json +1 -1
  219. package/dist/knowledge/playbooks/top_down.requirements-definition/evaluation-treatment.json +1 -1
  220. package/dist/knowledge/playbooks/top_down.requirements-definition/method.md +84 -9
  221. package/dist/knowledge/playbooks/top_down.requirements-definition/playbook.json +6 -3
  222. package/dist/knowledge/playbooks/top_down.risk-register/method.md +21 -0
  223. package/dist/knowledge/playbooks/top_down.risk-register/playbook.json +8 -2
  224. package/dist/knowledge/playbooks/top_down.scope-roadmap/playbook.json +4 -2
  225. package/dist/knowledge/playbooks/top_down.vision-elicitation/method.md +29 -0
  226. package/dist/knowledge/playbooks/top_down.vision-elicitation/playbook.json +58 -17
  227. package/dist/knowledge/references/brand.name-choice.config.md +144 -0
  228. package/dist/knowledge/references/brand.name-screening.config.md +308 -0
  229. package/dist/knowledge/references/build-plan.task-graph.config.md +119 -11
  230. package/dist/knowledge/references/business-model.pricing-plan.config.md +16 -0
  231. package/dist/knowledge/references/business-model.snapshot.config.md +64 -0
  232. package/dist/knowledge/references/business-model.snapshot.validation.md +68 -4
  233. package/dist/knowledge/references/capability-composition.config.md +67 -4
  234. package/dist/knowledge/references/companion.market.prompt-renderer.md +11 -6
  235. package/dist/knowledge/references/example.authorization.application-roles.office-and-field.md +44 -0
  236. package/dist/knowledge/references/example.backend.custom-operation.audit-event.md +81 -0
  237. package/dist/knowledge/references/example.backend.custom-operation.child-line-total.md +258 -0
  238. package/dist/knowledge/references/example.backend.custom-operation.computed-total.md +153 -0
  239. package/dist/knowledge/references/example.backend.custom-operation.create-related-resource.md +107 -0
  240. package/dist/knowledge/references/example.data-seeding.minimal.md +39 -10
  241. package/dist/knowledge/references/example.data-seeding.row-reference.md +80 -0
  242. package/dist/knowledge/references/example.email.template.minimal.md +1 -1
  243. package/dist/knowledge/references/example.resource.config-wiring.retention-policy-operations.md +74 -0
  244. package/dist/knowledge/references/example.resource.personal-data.free-text-field.md +19 -0
  245. package/dist/knowledge/references/example.resource.personal-data.person-without-account.md +27 -0
  246. package/dist/knowledge/references/example.resource.status-lifecycle.quote.md +152 -0
  247. package/dist/knowledge/references/example.resource.ui-behavior.filter-presets.md +15 -0
  248. package/dist/knowledge/references/example.resource.ui-behavior.operation-icon.md +8 -0
  249. package/dist/knowledge/references/example.views.app-level.home-definition.md +13 -0
  250. package/dist/knowledge/references/example.views.chart-definition.shared.md +83 -0
  251. package/dist/knowledge/references/experience-plan.config.md +60 -7
  252. package/dist/knowledge/references/market.context-block.builder.md +1 -1
  253. package/dist/knowledge/references/market.snapshot.validation.md +1 -1
  254. package/dist/knowledge/references/placement-plan.config.md +43 -0
  255. package/dist/knowledge/references/requirements.functional-requirement.config.md +8 -2
  256. package/dist/knowledge/references/requirements.non-functional-requirement.config.md +2 -0
  257. package/dist/knowledge/references/requirements.references.conventions.md +1 -1
  258. package/dist/knowledge/references/requirements.snapshot.config.md +57 -1
  259. package/dist/knowledge/references/requirements.snapshot.validation.md +35 -1
  260. package/dist/knowledge/references/saas.backend.audit-logs.log-event.md +63 -0
  261. package/dist/knowledge/references/saas.backend.document-sequence.issue-in-operation.md +60 -0
  262. package/dist/knowledge/references/saas.backend.document-sequence.raise-floor.md +156 -0
  263. package/dist/knowledge/references/saas.backend.email.send.md +77 -0
  264. package/dist/knowledge/references/saas.backend.notifications.operation-email-template-ref.md +60 -0
  265. package/dist/knowledge/references/saas.data-seeding.bootstrap-wiring.md +7 -1
  266. package/dist/knowledge/references/saas.data-seeding.computed-entry.md +43 -0
  267. package/dist/knowledge/references/saas.data-seeding.definition-input.md +14 -2
  268. package/dist/knowledge/references/saas.data-seeding.row-reference.md +93 -0
  269. package/dist/knowledge/references/saas.frontend.collection-filter-presets.md +124 -0
  270. package/dist/knowledge/references/saas.frontend.launcher.item-refs.md +316 -0
  271. package/dist/knowledge/references/saas.frontend.launcher.merge-rules.md +106 -0
  272. package/dist/knowledge/references/saas.frontend.launcher.runtime-availability.md +60 -0
  273. package/dist/knowledge/references/saas.frontend.resource-label-params.md +52 -0
  274. package/dist/knowledge/references/saas.frontend.resource-operation-frontend-config.md +47 -18
  275. package/dist/knowledge/references/saas.frontend.resource-ui-behavior-config.md +4 -1
  276. package/dist/knowledge/references/saas.frontend.settings-hub.engine-destination-roles.md +25 -0
  277. package/dist/knowledge/references/saas.frontend.settings-hub.placement.md +2 -2
  278. package/dist/knowledge/references/saas.models.audit.trail-config.md +45 -0
  279. package/dist/knowledge/references/saas.models.notifications.user-notification-definition.md +5 -3
  280. package/dist/knowledge/references/saas.models.queue.scheduled-recovery.md +81 -2
  281. package/dist/knowledge/references/saas.models.resource-config.builder-parameters.md +26 -0
  282. package/dist/knowledge/references/saas.models.roles.definition.md +61 -0
  283. package/dist/knowledge/references/saas.models.roles.organization-defaults.md +97 -0
  284. package/dist/knowledge/references/saas.public-runtime.contract.md +26 -0
  285. package/dist/knowledge/references/saas.specifications.companion-exports.contract.md +10 -0
  286. package/dist/knowledge/references/saas.website.astro.bridge.md +10 -0
  287. package/dist/knowledge/references/saas.website.astro.label-loader.md +12 -0
  288. package/dist/knowledge/references/saas.website.astro.llms-txt-server.md +14 -1
  289. package/dist/knowledge/references/saas.website.astro.site-context.md +13 -0
  290. package/dist/knowledge/references/saas.website.blog.bridge.md +4 -0
  291. package/dist/knowledge/references/saas.website.config.site-context-loader.md +3 -0
  292. package/dist/knowledge/references/saas.website.factories.define-section.md +4 -0
  293. package/dist/knowledge/references/saas.website.legal.public-document-links.md +76 -0
  294. package/dist/knowledge/references/saas.website.page-manifest.schema.md +12 -3
  295. package/dist/knowledge/references/saas.website.page-sections.component.md +72 -0
  296. package/dist/knowledge/references/saas.website.root-config.seo.md +2 -1
  297. package/dist/knowledge/references/saas.website.runtime.context.md +7 -0
  298. package/dist/knowledge/references/saas.website.sections.definition-schema.md +11 -0
  299. package/dist/knowledge/references/saas.website.seo.llms-txt-config.md +2 -0
  300. package/dist/knowledge/references/website-plan.config.md +26 -0
  301. package/dist/knowledge/references/zod.decorators.chainable-runtime.md +13 -0
  302. package/dist/knowledge/references/zod.decorators.decorator-vocabulary.md +7 -0
  303. package/dist/knowledge/references/zod.decorators.document-sequence.md +65 -0
  304. package/dist/knowledge/references/zod.decorators.schema-metadata.md +1 -0
  305. package/dist/knowledge/references/zod.decorators.shared-structural-methods.md +21 -0
  306. package/dist/knowledge/references/zod.factories.bigdecimal.md +1 -0
  307. package/dist/knowledge/references/zod.factories.code.md +1 -0
  308. package/dist/knowledge/references/zod.factories.duration.md +1 -0
  309. package/dist/knowledge/references/zod.factories.money.md +1 -0
  310. package/dist/knowledge/registries/assurance-authority-bases.json +1 -1
  311. package/dist/knowledge/registries/framework-topics.json +374 -1
  312. package/dist/knowledge/registries/playbooks.json +76 -28
  313. package/dist/knowledge/registries/source-tags.json +1513 -898
  314. package/dist/knowledge/rules/live-context-door.md +5 -2
  315. package/dist/knowledge/skills/INDEX.md +5 -2
  316. package/dist/knowledge/skills/application-consumer-documentation-authoring/SKILL.md +16 -3
  317. package/dist/knowledge/skills/application-database-migrations/SKILL.md +14 -3
  318. package/dist/knowledge/skills/application-roles-authoring/SKILL.md +158 -0
  319. package/dist/knowledge/skills/application-roles-authoring/references/framework-application-roles-api.md +169 -0
  320. package/dist/knowledge/skills/application-roles-authoring/references/office-and-field-worked-example.md +63 -0
  321. package/dist/knowledge/skills/authorization-unit-narrowing/SKILL.md +6 -1
  322. package/dist/knowledge/skills/backend-custom-operation/SKILL.md +256 -9
  323. package/dist/knowledge/skills/backend-custom-operation/references/after-the-operation.md +42 -0
  324. package/dist/knowledge/skills/backend-custom-operation/references/framework-audit-log-event-api.md +220 -0
  325. package/dist/knowledge/skills/brand-logo-authoring/SKILL.md +5 -0
  326. package/dist/knowledge/skills/brand-name-screening/SKILL.md +178 -0
  327. package/dist/knowledge/skills/brand-name-screening/references/framework-brand-name-screening-api.md +466 -0
  328. package/dist/knowledge/skills/brand-name-screening/references/screening-procedure.md +87 -0
  329. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +7 -3
  330. package/dist/knowledge/skills/config-app-shell/SKILL.md +58 -5
  331. package/dist/knowledge/skills/config-app-shell/references/framework-launcher-items-api.md +461 -0
  332. package/dist/knowledge/skills/config-app-shell/references/framework-launcher-visibility-api.md +80 -0
  333. package/dist/knowledge/skills/config-design-system/SKILL.md +28 -6
  334. package/dist/knowledge/skills/config-navigation/SKILL.md +14 -3
  335. package/dist/knowledge/skills/config-saas/SKILL.md +56 -15
  336. package/dist/knowledge/skills/config-saas/references/compliance-declarations.md +65 -2
  337. package/dist/knowledge/skills/config-saas/references/framework-audit-trail-config-api.md +62 -2
  338. package/dist/knowledge/skills/config-saas/references/framework-background-work-api.md +81 -2
  339. package/dist/knowledge/skills/config-saas-backend/SKILL.md +6 -1
  340. package/dist/knowledge/skills/configure-billing/SKILL.md +18 -4
  341. package/dist/knowledge/skills/email-add-template/SKILL.md +28 -6
  342. package/dist/knowledge/skills/email-add-template/references/email-artifact-paths.md +1 -1
  343. package/dist/knowledge/skills/email-add-template/references/framework-email-send-api.md +128 -0
  344. package/dist/knowledge/skills/email-add-template/references/framework-operation-email-template-ref-api.md +99 -0
  345. package/dist/knowledge/skills/engine-component-registration/SKILL.md +6 -1
  346. package/dist/knowledge/skills/engine-product-definitions/SKILL.md +21 -8
  347. package/dist/knowledge/skills/flows-actors-chat-assistant/SKILL.md +10 -2
  348. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/SKILL.md +18 -4
  349. package/dist/knowledge/skills/frontend-component-catalog/SKILL.md +11 -3
  350. package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-catalog.md +2 -1
  351. package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-usage.md +8 -0
  352. package/dist/knowledge/skills/i18n-rerun-pipeline/SKILL.md +19 -5
  353. package/dist/knowledge/skills/i18n-translation-rerun/SKILL.md +10 -2
  354. package/dist/knowledge/skills/inbound-channels/SKILL.md +2 -2
  355. package/dist/knowledge/skills/infra-environment-config/SKILL.md +6 -1
  356. package/dist/knowledge/skills/local-environment-bootstrap/SKILL.md +17 -2
  357. package/dist/knowledge/skills/local-environment-bootstrap/references/derived-artifact-currency.md +122 -0
  358. package/dist/knowledge/skills/local-environment-bootstrap/references/framework-upgrade-and-dependency-alignment.md +11 -0
  359. package/dist/knowledge/skills/local-environment-bootstrap/references/wildo-cli-bootstrap-commands.md +9 -2
  360. package/dist/knowledge/skills/market-add-feature-benefit/SKILL.md +10 -2
  361. package/dist/knowledge/skills/market-alternatives/SKILL.md +10 -2
  362. package/dist/knowledge/skills/market-authoring-overview/SKILL.md +10 -2
  363. package/dist/knowledge/skills/market-category/SKILL.md +21 -7
  364. package/dist/knowledge/skills/market-channels/SKILL.md +6 -1
  365. package/dist/knowledge/skills/market-companion-prompt-enrichment/SKILL.md +22 -4
  366. package/dist/knowledge/skills/market-companion-prompt-enrichment/references/framework-companion-behavior-api.md +12 -2
  367. package/dist/knowledge/skills/market-generation-cli/SKILL.md +21 -11
  368. package/dist/knowledge/skills/market-generation-cli/references/framework-market-generation-cli.md +11 -6
  369. package/dist/knowledge/skills/market-icp/SKILL.md +10 -2
  370. package/dist/knowledge/skills/market-jobs-pains-gains/SKILL.md +6 -1
  371. package/dist/knowledge/skills/market-message-templates-authoring/SKILL.md +6 -1
  372. package/dist/knowledge/skills/market-message-templates-authoring/references/framework-message-template-api.md +1 -1
  373. package/dist/knowledge/skills/market-persona/SKILL.md +14 -3
  374. package/dist/knowledge/skills/market-positioning-authoring/SKILL.md +6 -1
  375. package/dist/knowledge/skills/market-proof-and-objection/SKILL.md +10 -2
  376. package/dist/knowledge/skills/market-scoring-interpretation/SKILL.md +6 -1
  377. package/dist/knowledge/skills/market-snapshot-validation/SKILL.md +15 -4
  378. package/dist/knowledge/skills/market-snapshot-validation/references/framework-snapshot-validation-api.md +1 -1
  379. package/dist/knowledge/skills/market-tone-of-voice/SKILL.md +6 -1
  380. package/dist/knowledge/skills/model-cost-attribution/references/framework-work-unit-api.md +26 -0
  381. package/dist/knowledge/skills/module-companion-exports/SKILL.md +7 -1
  382. package/dist/knowledge/skills/module-companion-exports/references/companion-exports-by-package.md +10 -0
  383. package/dist/knowledge/skills/module-relationships/SKILL.md +37 -8
  384. package/dist/knowledge/skills/pdf-template-authoring/SKILL.md +4 -2
  385. package/dist/knowledge/skills/provider-address-lookup/SKILL.md +14 -3
  386. package/dist/knowledge/skills/provider-frontend-file-picker/SKILL.md +6 -1
  387. package/dist/knowledge/skills/provider-operation-calls/SKILL.md +14 -3
  388. package/dist/knowledge/skills/rate-limit-authoring/SKILL.md +10 -2
  389. package/dist/knowledge/skills/resource-add-field/SKILL.md +10 -2
  390. package/dist/knowledge/skills/resource-add-field/references/framework-field-cross-layer-api.md +46 -17
  391. package/dist/knowledge/skills/resource-add-resource/SKILL.md +14 -2
  392. package/dist/knowledge/skills/resource-add-resource/references/framework-new-resource-core-config-api.md +26 -0
  393. package/dist/knowledge/skills/resource-config-wiring/SKILL.md +29 -3
  394. package/dist/knowledge/skills/resource-config-wiring/references/framework-collection-operation-declarations.md +19 -4
  395. package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-audit-api.md +5 -2
  396. package/dist/knowledge/skills/resource-config-wiring/references/framework-personal-data-declaration-api.md +103 -0
  397. package/dist/knowledge/skills/resource-config-wiring/references/framework-retention-policy-operations.md +135 -0
  398. package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-resource-config-api.md +26 -0
  399. package/dist/knowledge/skills/resource-config-wiring/references/framework-user-notifications-api.md +26 -7
  400. package/dist/knowledge/skills/resource-custom-view/SKILL.md +10 -2
  401. package/dist/knowledge/skills/resource-custom-view/references/custom-view-contracts.md +46 -17
  402. package/dist/knowledge/skills/resource-external-data/references/erasure-suppression.md +2 -2
  403. package/dist/knowledge/skills/resource-retention-binding/SKILL.md +5 -1
  404. package/dist/knowledge/skills/resource-schema-authoring/SKILL.md +15 -1
  405. package/dist/knowledge/skills/resource-schema-authoring/references/computed-totals.md +569 -0
  406. package/dist/knowledge/skills/resource-schema-authoring/references/document-numbers.md +358 -0
  407. package/dist/knowledge/skills/resource-schema-authoring/references/framework-decorator-vocabulary-api.md +8 -0
  408. package/dist/knowledge/skills/resource-schema-authoring/references/framework-shared-decorator-methods-api.md +21 -0
  409. package/dist/knowledge/skills/resource-schema-authoring/references/framework-special-factories-api.md +7 -2
  410. package/dist/knowledge/skills/resource-schema-authoring/references/framework-zod-lifecycle-and-chainable-api.md +13 -0
  411. package/dist/knowledge/skills/resource-status-lifecycle/SKILL.md +153 -0
  412. package/dist/knowledge/skills/resource-status-lifecycle/references/commercial-documents.md +46 -0
  413. package/dist/knowledge/skills/resource-status-lifecycle/references/quote-lifecycle-worked-example.md +198 -0
  414. package/dist/knowledge/skills/resource-ui-behavior/SKILL.md +30 -4
  415. package/dist/knowledge/skills/resource-ui-behavior/references/framework-collection-filter-presets-api.md +157 -0
  416. package/dist/knowledge/skills/resource-ui-behavior/references/framework-frontend-resource-ui-contracts-api.md +101 -19
  417. package/dist/knowledge/skills/seeding-authoring/SKILL.md +202 -39
  418. package/dist/knowledge/skills/seeding-authoring/references/cross-seed-row-references.md +67 -0
  419. package/dist/knowledge/skills/seeding-authoring/references/framework-data-seeding-api.md +154 -4
  420. package/dist/knowledge/skills/seeding-authoring/references/seed-row-overlay.md +22 -0
  421. package/dist/knowledge/skills/seeding-operations/references/framework-data-seeding-operations-api.md +7 -1
  422. package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-destinations-catalog.md +43 -0
  423. package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-placement-api.md +2 -2
  424. package/dist/knowledge/skills/spec-companion-exports/SKILL.md +6 -1
  425. package/dist/knowledge/skills/spec-companion-exports/references/framework-companion-exports-contract-api.md +10 -0
  426. package/dist/knowledge/skills/spec-component-update/SKILL.md +10 -2
  427. package/dist/knowledge/skills/spec-composite-view-update/SKILL.md +2 -2
  428. package/dist/knowledge/skills/spec-family-update/SKILL.md +71 -66
  429. package/dist/knowledge/skills/spec-family-update/references/family-spec-routing.md +1 -1
  430. package/dist/knowledge/skills/spec-resource-update/SKILL.md +30 -10
  431. package/dist/knowledge/skills/spec-resource-update/references/resource-spec-field-routing.md +28 -0
  432. package/dist/knowledge/skills/spec-update-after-change/SKILL.md +22 -5
  433. package/dist/knowledge/skills/views-add-composite-view/SKILL.md +6 -1
  434. package/dist/knowledge/skills/views-add-custom-view/SKILL.md +10 -2
  435. package/dist/knowledge/skills/views-app-level/SKILL.md +13 -3
  436. package/dist/knowledge/skills/views-app-level/references/application-home.md +56 -0
  437. package/dist/knowledge/skills/views-chart-authoring/SKILL.md +221 -37
  438. package/dist/knowledge/skills/views-composite-authoring/SKILL.md +22 -5
  439. package/dist/knowledge/skills/views-execution-authoring/SKILL.md +1 -1
  440. package/dist/knowledge/skills/website-anonymous-session/SKILL.md +32 -2
  441. package/dist/knowledge/skills/website-blog-authoring/SKILL.md +16 -3
  442. package/dist/knowledge/skills/website-blog-authoring/references/blog-adapter-api.md +4 -0
  443. package/dist/knowledge/skills/website-bundle-discipline/SKILL.md +7 -1
  444. package/dist/knowledge/skills/website-consent-gate-overrides/SKILL.md +13 -1
  445. package/dist/knowledge/skills/website-factory-advanced/SKILL.md +14 -2
  446. package/dist/knowledge/skills/website-inbound-contact-forms/SKILL.md +13 -1
  447. package/dist/knowledge/skills/website-layout-overrides/SKILL.md +6 -1
  448. package/dist/knowledge/skills/website-marketing-metadata-extension/SKILL.md +19 -1
  449. package/dist/knowledge/skills/website-navigation-authoring/SKILL.md +55 -18
  450. package/dist/knowledge/skills/website-navigation-authoring/references/framework-public-document-links-api.md +98 -0
  451. package/dist/knowledge/skills/website-navigation-authoring/references/worked-examples-header-footer.md +8 -11
  452. package/dist/knowledge/skills/website-page-authoring/SKILL.md +100 -8
  453. package/dist/knowledge/skills/website-page-authoring/references/framework-site-context-loader-api.md +3 -0
  454. package/dist/knowledge/skills/website-primitive-overrides/SKILL.md +6 -1
  455. package/dist/knowledge/skills/website-section-contact/SKILL.md +15 -0
  456. package/dist/knowledge/skills/website-section-contact/references/define-website-section-api.md +15 -0
  457. package/dist/knowledge/skills/website-section-cta/SKILL.md +15 -0
  458. package/dist/knowledge/skills/website-section-cta/references/define-website-section-api.md +15 -0
  459. package/dist/knowledge/skills/website-section-faq/SKILL.md +21 -1
  460. package/dist/knowledge/skills/website-section-faq/references/define-website-section-api.md +15 -0
  461. package/dist/knowledge/skills/website-section-feature-benefit-summary/SKILL.md +21 -1
  462. package/dist/knowledge/skills/website-section-feature-benefit-summary/references/define-website-section-api.md +15 -0
  463. package/dist/knowledge/skills/website-section-feature-detail/SKILL.md +25 -2
  464. package/dist/knowledge/skills/website-section-feature-detail/references/define-website-section-api.md +15 -0
  465. package/dist/knowledge/skills/website-section-footer-cta/SKILL.md +15 -0
  466. package/dist/knowledge/skills/website-section-footer-cta/references/define-website-section-api.md +15 -0
  467. package/dist/knowledge/skills/website-section-hero/SKILL.md +33 -10
  468. package/dist/knowledge/skills/website-section-hero/references/define-website-section-api.md +15 -0
  469. package/dist/knowledge/skills/website-section-pricing/SKILL.md +21 -1
  470. package/dist/knowledge/skills/website-section-pricing/references/define-website-section-api.md +15 -0
  471. package/dist/knowledge/skills/website-section-social-proof/SKILL.md +27 -2
  472. package/dist/knowledge/skills/website-section-social-proof/references/define-website-section-api.md +15 -0
  473. package/dist/knowledge/skills/website-seo-aeo-geo/SKILL.md +16 -4
  474. package/dist/knowledge/skills/website-seo-aeo-geo/references/aeo-api.md +11 -0
  475. package/dist/knowledge/skills/website-seo-aeo-geo/references/geo-api.md +16 -1
  476. package/dist/knowledge/skills/website-seo-aeo-geo/references/seo-api.md +2 -1
  477. package/dist/knowledge/topic-index.json +1590 -292
  478. package/dist/tsconfig.build.tsbuildinfo +1 -1
  479. package/dist/tsconfig.tsbuildinfo +1 -1
  480. package/package.json +4 -4
@@ -51,8 +51,9 @@ what resources live in each, and how do those resources relate?"* You produce
51
51
  **inside** each module draft because an inventory is inherently *per module*.
52
52
  2. The **relationship drafts** — carried INSIDE the same domain-plan value — the **inter-resource relationship
53
53
  intents**: for each durable association between two inventoried resources, the
54
- two ends, the **cardinality intent** (one-to-one / one-to-many / many-to-many),
55
- and the **ownership direction** (which resource holds the reference). These are
54
+ two ends, the **cardinality intent** (one-to-one / one-to-many / many-to-one /
55
+ many-to-many, read from source to target), and the **ownership direction**
56
+ (which resource holds the reference). These are
56
57
  typed conceptual drafts — a relationship is not a module, so it earns its own
57
58
  family, and the build loop consumes it when it wires FK fields.
58
59
 
@@ -83,7 +84,8 @@ anything:
83
84
 
84
85
 
85
86
  You **read** `requirements` + `market-snapshot` + `feature-drafts` + `roadmap` +
86
- `vision-brief`; you **write** the `domain-plan` families.
87
+ `vision-brief`, and what the creator stated in the other interviews; you **write**
88
+ the `domain-plan` families.
87
89
 
88
90
  ## Step 1 — Derive the modules (the decomposition)
89
91
 
@@ -105,14 +107,57 @@ capability. Derive modules by **clustering** the definition set, not by guessing
105
107
  `businessDomain` (the larger bounded-context label) and `integrationSurfaces`
106
108
  (named surfaces the module participates in).
107
109
  3. **Keep modules justified.** Every module must earn its existence from
108
- requirements or features in the definition set. Do **not** invent a module the
110
+ requirements or features in the definition set, or from a fact the creator
111
+ stated that the requirements neither carry nor exclude (Step 2). Do **not** invent a module the
109
112
  definition set does not call for — a speculative module is a coherence CONCERN
110
- (see the quality gate). Conversely, if a requirement or feature has no home
111
- module, you are missing a module (a coverage GAP).
113
+ (see the quality gate). Conversely, a requirement or feature with no home is a
114
+ coverage GAP — and its home is EITHER a module OR an entry of
115
+ `engineRealizedRequirements` when the engine already provides it (Step 1b). Read
116
+ Step 1b before concluding that a requirement needs a module.
112
117
 
113
118
  The `resource-add-module` skill carries the module-scaffolding vocabulary (what a
114
119
  module is across the project layout); read it to keep module boundaries idiomatic.
115
120
 
121
+ ## Step 1b — Leave the engine's concerns to the engine
122
+
123
+ ### What the engine already provides — never a module, never a resource
124
+
125
+ Some requirements are met by what every Wildo application already has, configured rather than built.
126
+ A module or resource for one of them is read by nothing in the engine: it looks like the feature and
127
+ does none of it. When a requirement falls in one of these areas, record it in the domain plan's
128
+ `engineRealizedRequirements` (the requirement's ref, the concern below, and what the build still has to
129
+ configure) instead of giving it a module home.
130
+
131
+ | The requirement sounds like… | Concern (`realization`) | Where it is configured |
132
+ |---|---|---|
133
+ | "office and field users see different things", "only administrators may…", "a read-only reviewer" | `APPLICATION_ROLES` | the role table, the organization types that offer a role, each operation's `roles` — skill `application-roles-authoring` |
134
+ | "invite colleagues", "manage the team", "departments", "regions" | `ORGANIZATION_MEMBERSHIP` | the engine's members, invitations and organization units — skills `authorization-unit-narrowing`, `service-provider-relationships` |
135
+ | "see who changed what", "a history of changes" | `AUDIT_TRAIL` | operation audit on each resource — skill `resource-config-wiring` |
136
+ | "GDPR", "a customer can ask for their data / its deletion", "keep records for N years" | `PERSONAL_DATA` | personal-data declarations on fields, erasure, export and retention — skills `resource-config-wiring`, `resource-retention-binding` |
137
+ | "the privacy notice lists the purposes", "state the legal basis", "do not claim compliance with X", country disclaimers | `GOVERNED_DOCUMENT` | a governed document composed from the product — skill `compliance-document-authoring` |
138
+ | "customers subscribe to a plan" (the operator charging ITS customers) | `BILLING` | the billing catalogue — skill `configure-billing` |
139
+ | "guide new users", "celebrate the first…" | `GUIDANCE` | onboarding guidance and milestones — skills `guidance-onboarding-authoring`, `milestones-and-celebrations` |
140
+ | "notify the office when…", "email the customer when…" | `NOTIFICATIONS` | notifications declared on the operation that causes them — skills `resource-config-wiring`, `email-add-template` |
141
+ | "available in French and German" | `LOCALIZATION` | the application's languages and generated labels — skill `i18n-label-generation` |
142
+
143
+ Two further rules, because both produced resources nothing reads:
144
+
145
+ - **State derived from other records is never stored.** "The next action for each customer", "what is
146
+ overdue", "the stage a job is in" are computed from the records that carry the work and shown in a
147
+ view. A resource holding them by hand drifts from the records the moment either changes.
148
+ - **A disclaimer is never a resource.** A criterion of the form "does not claim X until Y" or "the product
149
+ states its limits" is a statement the operator makes (`GOVERNED_DOCUMENT`), not data a user types in.
150
+
151
+ An invoice the APPLICATION issues to its own customers (a trade business invoicing a homeowner) IS
152
+ product domain and belongs in a module; `BILLING` is only the operator charging the application's
153
+ subscribers.
154
+
155
+
156
+ `engineRealizedRequirements` is required: write `[]` when no requirement falls in these areas,
157
+ so the plan says it looked. One entry per requirement and concern; a requirement can have a
158
+ module home for its product part AND an engine entry for its access or privacy part (an invoice
159
+ resource in a module, and `APPLICATION_ROLES` for "only the office may issue invoices").
160
+
116
161
  ## Step 2 — Inventory the resources per module
117
162
 
118
163
  For each module, list the **resources** (persisted entity types) it owns. The
@@ -131,10 +176,28 @@ Rules for a plausible inventory:
131
176
  page: a requirement that says "users can label tasks" implies a `task` resource
132
177
  and (probably) a `label` resource. The `resource-add-resource` skill carries the
133
178
  vocabulary for what a resource is; read it to keep the inventory idiomatic.
179
+ - **What the creator stated reaches the inventory too.** Their answers to the
180
+ other interviews arrive in the declared `creator_stated_facts` context section of your brief, and the
181
+ requirements may have carried only part of them. Each stage of the stated
182
+ workflow has a resource it happens on (a site visit, a quote, a job). A stated
183
+ data class has a home: name the resource that holds a job-site address or a
184
+ VAT number in its module's `purpose`, which is the only place this plan can
185
+ say it (fields are the build's job, and the build reads the plan). A named
186
+ e-invoicing or other regime has a module or resource that serves it, or
187
+ belongs to the engine under Step 1b. Each stated user group is served by a
188
+ module, and its access belongs to the engine. What the creator put out of
189
+ scope, and a fact the requirements list in `excludedStatedFacts`, gets no
190
+ module. A stated fact that neither the requirements carry nor exclude, and
191
+ this plan does not carry, is a coverage GAP. Name it in the module's
192
+ `purpose` or raise it as a clarification; never drop it.
134
193
  - **Each resource is inventoried in exactly one module** as its `mainResource`. A
135
194
  resource that is genuinely shared across modules is a signal you either have the
136
195
  module boundary wrong or you need a relationship (Step 3), not the same main
137
196
  resource duplicated in two modules.
197
+ - **Never inventory what Step 1b leaves to the engine.** No resource holding roles,
198
+ permissions or role assignments; no resource holding processing purposes, compliance
199
+ declarations or country rules for users to type in; no resource holding a next action,
200
+ a stage or a status copied from other records.
138
201
  - **Do not author fields or schemas here.** The inventory names the resource and
139
202
  says which module owns it. What fields the resource carries, its enums, its
140
203
  decorators — all of that is the **build loop's** job. If you catch yourself
@@ -149,14 +212,29 @@ the relationship drafts (inside the domain-plan value) stating:
149
212
  - **The two ends** — the two resources that relate (both must be inventoried in
150
213
  some module's inventory from Step 2; a relationship to an un-inventoried resource
151
214
  is a coverage GAP).
152
- - **The cardinality intent** — one-to-one, one-to-many, or many-to-many. This is an
153
- *intent*, in prose; you are not resolving it into a foreign-key placement here.
215
+ - **The cardinality intent** — one-to-one, one-to-many, many-to-one, or
216
+ many-to-many, **always read from the source to the target**: *how many sources*
217
+ to *how many targets*. "Each `task` belongs to one `project`, a project has many
218
+ tasks", authored with `task` as the source and `project` as the target, is
219
+ **many-to-one**. The same association authored with `project` as the source is
220
+ **one-to-many**. This is an *intent*; you are not resolving it into a foreign-key
221
+ placement here.
154
222
  - **The ownership direction** — which resource conceptually **holds** the reference
155
223
  (e.g. "a `task` belongs to a `project`" → the `task` end holds the reference).
156
224
  This is the *intent* the build loop needs; it does **not** decide the physical FK
157
225
  holder (that resolution — FK holder from cardinality, discriminator relationships,
158
226
  conditional relationships — is the `module-relationships` skill's job at build
159
227
  time, **not** here).
228
+ - **The two must agree.** In a one-to-many or many-to-one association the **many**
229
+ side holds the reference, so many-to-one goes with *source holds the reference*
230
+ and one-to-many with *target holds the reference*. Deterministic validation
231
+ refuses the other two combinations. Only one-to-one and many-to-many leave the
232
+ holder to you. The simplest habit: make the resource that carries the reference
233
+ the **source**, and the edge is many-to-one.
234
+ - **Make the rationale say the same thing as the labels.** The relationship
235
+ judge reads the rationale against the cardinality, so "each customer has one
236
+ country context, many customers share one" belongs on a many-to-one edge from
237
+ customer to country context.
160
238
 
161
239
  The `module-relationships` skill carries the technical HOW of realising a
162
240
  relationship (FK fields, cardinality-to-FK-holder resolution, conditional /
@@ -164,6 +242,33 @@ discriminator relationships). Read it to keep your relationship *intents* aligne
164
242
  with what the build loop can actually wire — but do **not** perform that wiring in
165
243
  this planning pass.
166
244
 
245
+ ## Step 4 — Declare the lifecycles
246
+
247
+ For every resource the requirements describe moving through states — a quote that is sent and
248
+ accepted, an invoice that is issued and paid, a case that is opened and closed — declare its
249
+ lifecycle in `lifecycles`:
250
+
251
+ - **`states`** — every state, upper snake case (`DRAFT`, `SENT`, `ACCEPTED`), and the
252
+ **`initialState`** a new record starts in.
253
+ - **`transitions`** — one per verb the business uses, as a lower-case slug (`send`, `accept`,
254
+ `decline`, `issue`, `mark-paid`): the states it may start `from`, the state it moves `to`, and who
255
+ performs it in the requirements' words. One verb is one transition: list every starting state in
256
+ its `from`.
257
+ - **`stampsField`** on a transition whose moment the business needs (when the quote was sent, when the
258
+ invoice was paid): a camelCase timestamp field (`sentAt`, `paidAt`). `null` when nobody needs it.
259
+ - **`createsResourceRef`** on a transition that creates another resource (accepting a quote
260
+ creates a job). The created resource must be inventoried.
261
+ - **`lockedStates`** — the states in which the record can no longer be EDITED but still moves on: an
262
+ issued invoice (later marked paid), a sent quote (later accepted or declined). Empty when none.
263
+ - **`finalStates`** — the TERMINAL states: nothing moves the record out of them, and it is not edited
264
+ there either (a paid invoice, a closed case). Empty when nothing is ever final. No transition starts
265
+ from a final state: a state you can leave is locked, not final.
266
+
267
+ Write `[]` when no resource moves through states. Read the requirements' verbs, not their nouns:
268
+ "an accepted quote can be used to create a job" is a lifecycle (`accept`) and a conversion
269
+ (`createsResourceRef: job`), not a foreign key. A value derived from other records — a next action,
270
+ an overdue flag — is not a state of any resource (Step 1b).
271
+
167
272
  ## Refine, don't re-author
168
273
 
169
274
  - **Keep what still holds.** On a re-run, do not rename or re-decompose modules
@@ -184,9 +289,13 @@ atomic manifest must all be valid. That is a non-bypassable eligibility floor,
184
289
  not a semantic quality opinion.
185
290
 
186
291
  The companion then executes the playbook's structured semantic Treatment over
187
- the exact staged output-set artifact. Its six criteria remain distinct:
188
- requirement coverage, feature coverage, module justification, inventory
189
- plausibility, relationship integrity, and planning-depth boundary discipline.
292
+ the exact staged output-set artifact. Its eight criteria remain distinct:
293
+ requirement coverage (a module home OR an engine realization), feature coverage,
294
+ module justification, inventory plausibility, relationship integrity,
295
+ planning-depth boundary discipline, engine-concern discipline (no module or
296
+ resource for what the engine provides, a disclaimer, or derived state), and
297
+ lifecycle coverage (a requirement that moves a record through states has its
298
+ lifecycle).
190
299
  Each criterion produces PASS / CONCERN / GAP / INDETERMINATE evidence, and the
191
300
  worst-verdict aggregation policy determines the Decision Rule consequence.
192
301
 
@@ -196,9 +305,11 @@ decision is a separate later boundary. CONCERN or GAP requests revision,
196
305
  INDETERMINATE requests evidence, and evaluator or hard-floor failure blocks
197
306
  closed. The evaluation path never mutates accepted specification heads.
198
307
 
199
- ## Scaffold-depth boundary (deferred to a later depth phase)
308
+ ## Scaffold-depth boundary
200
309
 
201
- Keep this playbook at scaffold depth. Explicitly **out of scope here**:
310
+ Keep this playbook at scaffold depth. Lifecycles (Step 4) are IN scope: they are what the
311
+ resources DO, decided where the resources are, and nothing later decides them. Explicitly
312
+ **out of scope here**:
202
313
 
203
314
  - **Schema / field authoring.** The inventory names resources and their owning
204
315
  module; it does **not** author fields, enums, decorators, or Zod schemas. That is
@@ -220,8 +331,9 @@ Keep this playbook at scaffold depth. Explicitly **out of scope here**:
220
331
  registering the module across runtimes, generating resource files — all of that is
221
332
  the bottom-up build loop, downstream of this plan.
222
333
 
223
- If you find yourself perfecting any of the above, stop and leave the slice at
224
- scaffold depth — depth is a dedicated later pass done once, holistically.
334
+ If you find yourself perfecting any of the above, stop: fields, physical foreign keys and
335
+ generated code are the build's. What the build cannot invent — which states a resource has and
336
+ which moves the business allows — is yours, in Step 4.
225
337
 
226
338
  ## What you emit
227
339
 
@@ -232,8 +344,8 @@ Two artifacts for this journey:
232
344
  module carrying its purpose, business capability, primary actors, and its
233
345
  `mainResources` / `supportingResources` inventory.
234
346
  - The **relationship drafts** inside the landed `specifications/src/domain-plan/` value
235
- — the inter-resource relationship intents (two ends + cardinality intent +
236
- ownership direction) between inventoried resources.
347
+ — the inter-resource relationship intents (two ends + cardinality intent read
348
+ source → target + ownership direction) between inventoried resources.
237
349
 
238
350
  After deterministic validation and semantic PASS, the runtime creates a distinct
239
351
  result-bound Authority Request for the exact staged output-set digest. The local
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "ref": "bottom_up.domain-plan",
3
- "version": "0.2.1",
3
+ "version": "0.3.0",
4
4
  "phase": "bottom_up",
5
5
  "intent": "Turn the approved definition set into one atomic, planning-depth domain output set: module decomposition with per-module resource inventory plus typed inter-resource relationship intents. The output remains staged until deterministic validation, semantic evaluation and distinct result authority complete.",
6
6
  "preconditions": [
@@ -47,7 +47,7 @@
47
47
  ],
48
48
  "stepOutputs": [],
49
49
  "method": {
50
- "guidance": "# Domain Plan — Definition Set → Modules + Resources + Relationships (v1 scaffold)\n\n### Target Application Framing\n\nThis knowledge is for configuring behavior in the target application.\nWildo is the framework surface being used, not the product being built.\n\nRead and apply these patterns from the application-developer point of view:\n\n- how the application should configure the relevant app-level file\n- how the application should use framework-provided factories, enums, and helpers\n- how the application should avoid mixing frontend, backend, and infrastructure concerns\n\n\n> **This is a v1 scaffold methodology.** It is a working first cut meant to be\n> iterated. The decomposition heuristic, the resource-inventory convention, and\n> the relationship-intent shape below are deliberately explicit so they can be\n> tuned against real runs — treat them as a starting rubric, not a frozen\n> contract. The *analytical depth* of domain modelling (a full ERD, a\n> cardinality-to-FK solver and full domain-graph validation) is intentionally\n> shallow here and is deepened in a later phase; do\n> not perfect it in this playbook.\n\n## Where you are in the journey\n\nThis is the **first bottom-up playbook** — the pivot from **product definition**\n(top-down: vision, market, requirements, roadmap, business model) to **project\ndefinition** (bottom-up: the app's modules, resources, and how they relate). It\nruns **only after** the exact\n`top_down-to-bottom_up.bootstrap-non-regulated@0.1.0` route has produced a\ndurable `top_down → bottom_up` transition-commit fact. That fact proves the\nroute-bound readiness, semantic decision, Authority Request/Decision and phase\neffect chain; it is not an arbitrary approval flag. The separate\n`phase_is bottom_up` predicate checks the current phase projection. You are not\nre-opening product questions here — you are turning the currently accepted\nproduct definition into the *shape of the software that delivers it*.\n\n## What this playbook does\n\nYou are the **domain architect**. This playbook reads the approved definition set\nand drafts the **domain plan**: the answer to *\"what modules does this app have,\nwhat resources live in each, and how do those resources relate?\"* You produce\n**two artifacts**:\n\n1. The **domain-plan** family — the **module decomposition** with a **per-module\n resource inventory**, authored as a collection of **ModuleBusinessSemantics\n drafts** (one per proposed module). Each module draft states its purpose, its\n business capability, its primary actors, and its resource inventory\n (`mainResources` — the semantic center of the module; `supportingResources` —\n resources that support without being the center). The resource inventory lives\n **inside** each module draft because an inventory is inherently *per module*.\n2. The **relationship drafts** — carried INSIDE the same domain-plan value — the **inter-resource relationship\n intents**: for each durable association between two inventoried resources, the\n two ends, the **cardinality intent** (one-to-one / one-to-many / many-to-many),\n and the **ownership direction** (which resource holds the reference). These are\n typed conceptual drafts — a relationship is not a module, so it earns its own\n family, and the build loop consumes it when it wires FK fields.\n\nThis is a **planning pass**. You name modules, the resources inside them, and how\nthey relate. You do **not** author schemas, resolve a cardinality intent into a\nconcrete foreign-key field, or generate any code — that is the **bottom-up build\nloop's** job, downstream of this plan.\n\n## Read state first — the definition set you read, the two artifacts you write\n\nThis playbook is **idempotent** and, on a re-run, a *refinement*. Before drafting\nanything:\n\n1. Read the current journey state and scope from what this run is given — the loaded\n specifications and the workspace sections of your brief — and do not re-derive it. Confirm the top-down set is present\n and approved, and check whether a `domain-plan` already\n exist from an earlier run (refine them, do not re-author — see below).\n2. Read the approved definition set. **Load-bearing** (these drive the\n decomposition): the **requirements** (`requirements` family — the functional and\n non-functional requirements the domain must satisfy), the capability-mapped\n **MarketSnapshot** (`market-snapshot` — the benefits wired to their delivering\n features, so you know what capability each feature carries), and the\n **feature-drafts** (the prose capability contracts — what each delivering\n feature actually is). **Contextual** (they shape emphasis, not the core\n decomposition): the **roadmap** (`roadmap` — the release phasing, so you can see\n which modules are MVP-critical vs later) and the **VisionSnapshot**\n (`vision-brief` — the product framing and differentiation).\n\n\nYou **read** `requirements` + `market-snapshot` + `feature-drafts` + `roadmap` +\n`vision-brief`; you **write** the `domain-plan` families.\n\n## Step 1 — Derive the modules (the decomposition)\n\nA **module** is a bounded slice of the app that delivers a coherent business\ncapability. Derive modules by **clustering** the definition set, not by guessing:\n\n1. **Cluster requirements and features by capability.** Group the functional\n requirements and the feature-drafts that serve one coherent capability (e.g.\n \"everything about authoring and tracking tasks\", \"everything about billing and\n plans\"). Each tight cluster is a candidate module. A feature-draft and the\n requirements it realises usually land in the same module.\n2. **Name each module and state its semantics.** For each candidate module author a\n `ModuleBusinessSemantics` draft: a `relatedModuleId` (the id the module registry\n will use — it must be **distinct across all module drafts**; two modules sharing\n an id silently collide, since the registry addresses modules by id), a `purpose`\n (why the module exists, in plain language), a\n `businessCapability` (the capability it delivers), the `primaryActors` (the\n human/business actors that interact with it), and — optionally — a\n `businessDomain` (the larger bounded-context label) and `integrationSurfaces`\n (named surfaces the module participates in).\n3. **Keep modules justified.** Every module must earn its existence from\n requirements or features in the definition set. Do **not** invent a module the\n definition set does not call for — a speculative module is a coherence CONCERN\n (see the quality gate). Conversely, if a requirement or feature has no home\n module, you are missing a module (a coverage GAP).\n\nThe `resource-add-module` skill carries the module-scaffolding vocabulary (what a\nmodule is across the project layout); read it to keep module boundaries idiomatic.\n\n## Step 2 — Inventory the resources per module\n\nFor each module, list the **resources** (persisted entity types) it owns. The\ninventory is **two lists on the module draft**:\n\n- **`mainResources`** — the resources that form the semantic **center** of the\n module (the entities the module is *about*: a `tasks` module's `task`).\n- **`supportingResources`** — resources that **support** the module's capability\n without being its center (lookup tables, join/junction entities, per-entity\n settings). A resource that is the center of the module belongs in `mainResources`,\n not here.\n\nRules for a plausible inventory:\n\n- **Derive resources from the requirements + feature-drafts**, not from a blank\n page: a requirement that says \"users can label tasks\" implies a `task` resource\n and (probably) a `label` resource. The `resource-add-resource` skill carries the\n vocabulary for what a resource is; read it to keep the inventory idiomatic.\n- **Each resource is inventoried in exactly one module** as its `mainResource`. A\n resource that is genuinely shared across modules is a signal you either have the\n module boundary wrong or you need a relationship (Step 3), not the same main\n resource duplicated in two modules.\n- **Do not author fields or schemas here.** The inventory names the resource and\n says which module owns it. What fields the resource carries, its enums, its\n decorators — all of that is the **build loop's** job. If you catch yourself\n writing a field list, stop: that is out of this playbook's depth.\n\n## Step 3 — Draft the inter-resource relationships\n\nOnce the resources are inventoried, capture how they **relate**. For each durable\nassociation between two inventoried resources, author a **relationship draft** in\nthe relationship drafts (inside the domain-plan value) stating:\n\n- **The two ends** — the two resources that relate (both must be inventoried in\n some module's inventory from Step 2; a relationship to an un-inventoried resource\n is a coverage GAP).\n- **The cardinality intent** — one-to-one, one-to-many, or many-to-many. This is an\n *intent*, in prose; you are not resolving it into a foreign-key placement here.\n- **The ownership direction** — which resource conceptually **holds** the reference\n (e.g. \"a `task` belongs to a `project`\" → the `task` end holds the reference).\n This is the *intent* the build loop needs; it does **not** decide the physical FK\n holder (that resolution — FK holder from cardinality, discriminator relationships,\n conditional relationships — is the `module-relationships` skill's job at build\n time, **not** here).\n\nThe `module-relationships` skill carries the technical HOW of realising a\nrelationship (FK fields, cardinality-to-FK-holder resolution, conditional /\ndiscriminator relationships). Read it to keep your relationship *intents* aligned\nwith what the build loop can actually wire — but do **not** perform that wiring in\nthis planning pass.\n\n## Refine, don't re-author\n\n- **Keep what still holds.** On a re-run, do not rename or re-decompose modules\n that are already correct. Only add a module, move a resource to a different\n module, or add/correct a relationship where the plan genuinely changed.\n- **Reuse existing module ids.** A module that already exists keeps its\n `relatedModuleId` — never mint a second id for the same module. Likewise, keep a\n resource's name stable across runs.\n- **Never orphan a relationship.** A relationship draft must name two resources\n that are actually inventoried in Step 2. If you move or rename a resource, follow\n it into every relationship draft that references it.\n\n## Executable semantic evaluation — `domain-plan-output-set-result`\n\nThe staged output set first passes deterministic structural validation: exact\nmodule/resource identities, typed relationship ends, unique ownership, and the\natomic manifest must all be valid. That is a non-bypassable eligibility floor,\nnot a semantic quality opinion.\n\nThe companion then executes the playbook's structured semantic Treatment over\nthe exact staged output-set artifact. Its six criteria remain distinct:\nrequirement coverage, feature coverage, module justification, inventory\nplausibility, relationship integrity, and planning-depth boundary discipline.\nEach criterion produces PASS / CONCERN / GAP / INDETERMINATE evidence, and the\nworst-verdict aggregation policy determines the Decision Rule consequence.\n\nA semantic PASS does **not** accept or publish the candidate. It transitions the\nresult Decision Point to `AUTHORITY_REQUIRED`; an explicit operator authority\ndecision is a separate later boundary. CONCERN or GAP requests revision,\nINDETERMINATE requests evidence, and evaluator or hard-floor failure blocks\nclosed. The evaluation path never mutates accepted specification heads.\n\n## Scaffold-depth boundary (deferred to a later depth phase)\n\nKeep this playbook at scaffold depth. Explicitly **out of scope here**:\n\n- **Schema / field authoring.** The inventory names resources and their owning\n module; it does **not** author fields, enums, decorators, or Zod schemas. That is\n the build loop. If you catch yourself writing a field list, stop.\n- **Cardinality-to-FK resolution.** A relationship draft states a cardinality\n *intent* and an ownership *intent* in prose. Resolving that into a physical\n foreign-key holder, a discriminator relationship, or a conditional relationship is\n the `module-relationships` skill's job **at build time**, not here.\n- **A full ERD / domain-graph solver.** Phases-of-a-graph, transitive dependency\n ordering, normalization analysis, and diagram generation are a later-phase\n concern. You draft modules, an inventory, and relationship intents — not a solved\n entity-relationship diagram.\n- **A full domain-graph solver.** The framework now ships a typed conceptual\n relationship-draft contract and deterministic structural validation for the\n atomic output set. It deliberately does not solve physical FK placement,\n normalization, graph execution order, discriminator relationships, or\n conditional relationships; those remain build-depth concerns.\n- **Code generation / module registration.** Scaffolding the module folders,\n registering the module across runtimes, generating resource files — all of that is\n the bottom-up build loop, downstream of this plan.\n\nIf you find yourself perfecting any of the above, stop and leave the slice at\nscaffold depth — depth is a dedicated later pass done once, holistically.\n\n## What you emit\n\nTwo artifacts for this journey:\n\n- The **domain-plan** under `specifications/src/domain-plan/` — a\n collection of `ModuleBusinessSemantics` drafts: the module decomposition, each\n module carrying its purpose, business capability, primary actors, and its\n `mainResources` / `supportingResources` inventory.\n- The **relationship drafts** inside the landed `specifications/src/domain-plan/` value\n — the inter-resource relationship intents (two ends + cardinality intent +\n ownership direction) between inventoried resources.\n\nAfter deterministic validation and semantic PASS, the runtime creates a distinct\nresult-bound Authority Request for the exact staged output-set digest. The local\noperator's explicit interface response settles that request; transition authority\ncannot substitute for it. Only then may the atomic specification-family mutation\naccept both files together for consumption by the bottom-up build loop.\n\n## References\n\nThese are skill FOLDERS installed in the application, named so each piece of work has an\nauthoring contract a later coding agent can open. This step has no tools and does not open them;\nwhat reaches you is this method, your declared inputs, and the brief's own sections.\n\n- `resource-add-module` — the module-scaffolding vocabulary\n (what a module is across the project layout); keeps module boundaries idiomatic.\n- `resource-add-resource` — the resource vocabulary (what a\n resource is); keeps the per-module inventory idiomatic.\n- `module-relationships` — the technical HOW of realising a\n relationship (FK fields, cardinality-to-FK-holder resolution, conditional /\n discriminator relationships) — consulted so relationship *intents* align with what\n the build loop can wire, NOT performed in this planning pass.\n",
50
+ "guidance": "# Domain Plan — Definition Set → Modules + Resources + Relationships (v1 scaffold)\n\n### Target Application Framing\n\nThis knowledge is for configuring behavior in the target application.\nWildo is the framework surface being used, not the product being built.\n\nRead and apply these patterns from the application-developer point of view:\n\n- how the application should configure the relevant app-level file\n- how the application should use framework-provided factories, enums, and helpers\n- how the application should avoid mixing frontend, backend, and infrastructure concerns\n\n\n> **This is a v1 scaffold methodology.** It is a working first cut meant to be\n> iterated. The decomposition heuristic, the resource-inventory convention, and\n> the relationship-intent shape below are deliberately explicit so they can be\n> tuned against real runs — treat them as a starting rubric, not a frozen\n> contract. The *analytical depth* of domain modelling (a full ERD, a\n> cardinality-to-FK solver and full domain-graph validation) is intentionally\n> shallow here and is deepened in a later phase; do\n> not perfect it in this playbook.\n\n## Where you are in the journey\n\nThis is the **first bottom-up playbook** — the pivot from **product definition**\n(top-down: vision, market, requirements, roadmap, business model) to **project\ndefinition** (bottom-up: the app's modules, resources, and how they relate). It\nruns **only after** the exact\n`top_down-to-bottom_up.bootstrap-non-regulated@0.1.0` route has produced a\ndurable `top_down → bottom_up` transition-commit fact. That fact proves the\nroute-bound readiness, semantic decision, Authority Request/Decision and phase\neffect chain; it is not an arbitrary approval flag. The separate\n`phase_is bottom_up` predicate checks the current phase projection. You are not\nre-opening product questions here — you are turning the currently accepted\nproduct definition into the *shape of the software that delivers it*.\n\n## What this playbook does\n\nYou are the **domain architect**. This playbook reads the approved definition set\nand drafts the **domain plan**: the answer to *\"what modules does this app have,\nwhat resources live in each, and how do those resources relate?\"* You produce\n**two artifacts**:\n\n1. The **domain-plan** family — the **module decomposition** with a **per-module\n resource inventory**, authored as a collection of **ModuleBusinessSemantics\n drafts** (one per proposed module). Each module draft states its purpose, its\n business capability, its primary actors, and its resource inventory\n (`mainResources` — the semantic center of the module; `supportingResources` —\n resources that support without being the center). The resource inventory lives\n **inside** each module draft because an inventory is inherently *per module*.\n2. The **relationship drafts** — carried INSIDE the same domain-plan value — the **inter-resource relationship\n intents**: for each durable association between two inventoried resources, the\n two ends, the **cardinality intent** (one-to-one / one-to-many / many-to-one /\n many-to-many, read from source to target), and the **ownership direction**\n (which resource holds the reference). These are\n typed conceptual drafts — a relationship is not a module, so it earns its own\n family, and the build loop consumes it when it wires FK fields.\n\nThis is a **planning pass**. You name modules, the resources inside them, and how\nthey relate. You do **not** author schemas, resolve a cardinality intent into a\nconcrete foreign-key field, or generate any code — that is the **bottom-up build\nloop's** job, downstream of this plan.\n\n## Read state first — the definition set you read, the two artifacts you write\n\nThis playbook is **idempotent** and, on a re-run, a *refinement*. Before drafting\nanything:\n\n1. Read the current journey state and scope from what this run is given — the loaded\n specifications and the workspace sections of your brief — and do not re-derive it. Confirm the top-down set is present\n and approved, and check whether a `domain-plan` already\n exist from an earlier run (refine them, do not re-author — see below).\n2. Read the approved definition set. **Load-bearing** (these drive the\n decomposition): the **requirements** (`requirements` family — the functional and\n non-functional requirements the domain must satisfy), the capability-mapped\n **MarketSnapshot** (`market-snapshot` — the benefits wired to their delivering\n features, so you know what capability each feature carries), and the\n **feature-drafts** (the prose capability contracts — what each delivering\n feature actually is). **Contextual** (they shape emphasis, not the core\n decomposition): the **roadmap** (`roadmap` — the release phasing, so you can see\n which modules are MVP-critical vs later) and the **VisionSnapshot**\n (`vision-brief` — the product framing and differentiation).\n\n\nYou **read** `requirements` + `market-snapshot` + `feature-drafts` + `roadmap` +\n`vision-brief`, and what the creator stated in the other interviews; you **write**\nthe `domain-plan` families.\n\n## Step 1 — Derive the modules (the decomposition)\n\nA **module** is a bounded slice of the app that delivers a coherent business\ncapability. Derive modules by **clustering** the definition set, not by guessing:\n\n1. **Cluster requirements and features by capability.** Group the functional\n requirements and the feature-drafts that serve one coherent capability (e.g.\n \"everything about authoring and tracking tasks\", \"everything about billing and\n plans\"). Each tight cluster is a candidate module. A feature-draft and the\n requirements it realises usually land in the same module.\n2. **Name each module and state its semantics.** For each candidate module author a\n `ModuleBusinessSemantics` draft: a `relatedModuleId` (the id the module registry\n will use — it must be **distinct across all module drafts**; two modules sharing\n an id silently collide, since the registry addresses modules by id), a `purpose`\n (why the module exists, in plain language), a\n `businessCapability` (the capability it delivers), the `primaryActors` (the\n human/business actors that interact with it), and — optionally — a\n `businessDomain` (the larger bounded-context label) and `integrationSurfaces`\n (named surfaces the module participates in).\n3. **Keep modules justified.** Every module must earn its existence from\n requirements or features in the definition set, or from a fact the creator\n stated that the requirements neither carry nor exclude (Step 2). Do **not** invent a module the\n definition set does not call for — a speculative module is a coherence CONCERN\n (see the quality gate). Conversely, a requirement or feature with no home is a\n coverage GAP — and its home is EITHER a module OR an entry of\n `engineRealizedRequirements` when the engine already provides it (Step 1b). Read\n Step 1b before concluding that a requirement needs a module.\n\nThe `resource-add-module` skill carries the module-scaffolding vocabulary (what a\nmodule is across the project layout); read it to keep module boundaries idiomatic.\n\n## Step 1b — Leave the engine's concerns to the engine\n\n### What the engine already provides — never a module, never a resource\n\nSome requirements are met by what every Wildo application already has, configured rather than built.\nA module or resource for one of them is read by nothing in the engine: it looks like the feature and\ndoes none of it. When a requirement falls in one of these areas, record it in the domain plan's\n`engineRealizedRequirements` (the requirement's ref, the concern below, and what the build still has to\nconfigure) instead of giving it a module home.\n\n| The requirement sounds like… | Concern (`realization`) | Where it is configured |\n|---|---|---|\n| \"office and field users see different things\", \"only administrators may…\", \"a read-only reviewer\" | `APPLICATION_ROLES` | the role table, the organization types that offer a role, each operation's `roles` — skill `application-roles-authoring` |\n| \"invite colleagues\", \"manage the team\", \"departments\", \"regions\" | `ORGANIZATION_MEMBERSHIP` | the engine's members, invitations and organization units — skills `authorization-unit-narrowing`, `service-provider-relationships` |\n| \"see who changed what\", \"a history of changes\" | `AUDIT_TRAIL` | operation audit on each resource — skill `resource-config-wiring` |\n| \"GDPR\", \"a customer can ask for their data / its deletion\", \"keep records for N years\" | `PERSONAL_DATA` | personal-data declarations on fields, erasure, export and retention — skills `resource-config-wiring`, `resource-retention-binding` |\n| \"the privacy notice lists the purposes\", \"state the legal basis\", \"do not claim compliance with X\", country disclaimers | `GOVERNED_DOCUMENT` | a governed document composed from the product — skill `compliance-document-authoring` |\n| \"customers subscribe to a plan\" (the operator charging ITS customers) | `BILLING` | the billing catalogue — skill `configure-billing` |\n| \"guide new users\", \"celebrate the first…\" | `GUIDANCE` | onboarding guidance and milestones — skills `guidance-onboarding-authoring`, `milestones-and-celebrations` |\n| \"notify the office when…\", \"email the customer when…\" | `NOTIFICATIONS` | notifications declared on the operation that causes them — skills `resource-config-wiring`, `email-add-template` |\n| \"available in French and German\" | `LOCALIZATION` | the application's languages and generated labels — skill `i18n-label-generation` |\n\nTwo further rules, because both produced resources nothing reads:\n\n- **State derived from other records is never stored.** \"The next action for each customer\", \"what is\n overdue\", \"the stage a job is in\" are computed from the records that carry the work and shown in a\n view. A resource holding them by hand drifts from the records the moment either changes.\n- **A disclaimer is never a resource.** A criterion of the form \"does not claim X until Y\" or \"the product\n states its limits\" is a statement the operator makes (`GOVERNED_DOCUMENT`), not data a user types in.\n\nAn invoice the APPLICATION issues to its own customers (a trade business invoicing a homeowner) IS\nproduct domain and belongs in a module; `BILLING` is only the operator charging the application's\nsubscribers.\n\n\n`engineRealizedRequirements` is required: write `[]` when no requirement falls in these areas,\nso the plan says it looked. One entry per requirement and concern; a requirement can have a\nmodule home for its product part AND an engine entry for its access or privacy part (an invoice\nresource in a module, and `APPLICATION_ROLES` for \"only the office may issue invoices\").\n\n## Step 2 — Inventory the resources per module\n\nFor each module, list the **resources** (persisted entity types) it owns. The\ninventory is **two lists on the module draft**:\n\n- **`mainResources`** — the resources that form the semantic **center** of the\n module (the entities the module is *about*: a `tasks` module's `task`).\n- **`supportingResources`** — resources that **support** the module's capability\n without being its center (lookup tables, join/junction entities, per-entity\n settings). A resource that is the center of the module belongs in `mainResources`,\n not here.\n\nRules for a plausible inventory:\n\n- **Derive resources from the requirements + feature-drafts**, not from a blank\n page: a requirement that says \"users can label tasks\" implies a `task` resource\n and (probably) a `label` resource. The `resource-add-resource` skill carries the\n vocabulary for what a resource is; read it to keep the inventory idiomatic.\n- **What the creator stated reaches the inventory too.** Their answers to the\n other interviews arrive in the declared `creator_stated_facts` context section of your brief, and the\n requirements may have carried only part of them. Each stage of the stated\n workflow has a resource it happens on (a site visit, a quote, a job). A stated\n data class has a home: name the resource that holds a job-site address or a\n VAT number in its module's `purpose`, which is the only place this plan can\n say it (fields are the build's job, and the build reads the plan). A named\n e-invoicing or other regime has a module or resource that serves it, or\n belongs to the engine under Step 1b. Each stated user group is served by a\n module, and its access belongs to the engine. What the creator put out of\n scope, and a fact the requirements list in `excludedStatedFacts`, gets no\n module. A stated fact that neither the requirements carry nor exclude, and\n this plan does not carry, is a coverage GAP. Name it in the module's\n `purpose` or raise it as a clarification; never drop it.\n- **Each resource is inventoried in exactly one module** as its `mainResource`. A\n resource that is genuinely shared across modules is a signal you either have the\n module boundary wrong or you need a relationship (Step 3), not the same main\n resource duplicated in two modules.\n- **Never inventory what Step 1b leaves to the engine.** No resource holding roles,\n permissions or role assignments; no resource holding processing purposes, compliance\n declarations or country rules for users to type in; no resource holding a next action,\n a stage or a status copied from other records.\n- **Do not author fields or schemas here.** The inventory names the resource and\n says which module owns it. What fields the resource carries, its enums, its\n decorators — all of that is the **build loop's** job. If you catch yourself\n writing a field list, stop: that is out of this playbook's depth.\n\n## Step 3 — Draft the inter-resource relationships\n\nOnce the resources are inventoried, capture how they **relate**. For each durable\nassociation between two inventoried resources, author a **relationship draft** in\nthe relationship drafts (inside the domain-plan value) stating:\n\n- **The two ends** — the two resources that relate (both must be inventoried in\n some module's inventory from Step 2; a relationship to an un-inventoried resource\n is a coverage GAP).\n- **The cardinality intent** — one-to-one, one-to-many, many-to-one, or\n many-to-many, **always read from the source to the target**: *how many sources*\n to *how many targets*. \"Each `task` belongs to one `project`, a project has many\n tasks\", authored with `task` as the source and `project` as the target, is\n **many-to-one**. The same association authored with `project` as the source is\n **one-to-many**. This is an *intent*; you are not resolving it into a foreign-key\n placement here.\n- **The ownership direction** — which resource conceptually **holds** the reference\n (e.g. \"a `task` belongs to a `project`\" → the `task` end holds the reference).\n This is the *intent* the build loop needs; it does **not** decide the physical FK\n holder (that resolution — FK holder from cardinality, discriminator relationships,\n conditional relationships — is the `module-relationships` skill's job at build\n time, **not** here).\n- **The two must agree.** In a one-to-many or many-to-one association the **many**\n side holds the reference, so many-to-one goes with *source holds the reference*\n and one-to-many with *target holds the reference*. Deterministic validation\n refuses the other two combinations. Only one-to-one and many-to-many leave the\n holder to you. The simplest habit: make the resource that carries the reference\n the **source**, and the edge is many-to-one.\n- **Make the rationale say the same thing as the labels.** The relationship\n judge reads the rationale against the cardinality, so \"each customer has one\n country context, many customers share one\" belongs on a many-to-one edge from\n customer to country context.\n\nThe `module-relationships` skill carries the technical HOW of realising a\nrelationship (FK fields, cardinality-to-FK-holder resolution, conditional /\ndiscriminator relationships). Read it to keep your relationship *intents* aligned\nwith what the build loop can actually wire — but do **not** perform that wiring in\nthis planning pass.\n\n## Step 4 — Declare the lifecycles\n\nFor every resource the requirements describe moving through states — a quote that is sent and\naccepted, an invoice that is issued and paid, a case that is opened and closed — declare its\nlifecycle in `lifecycles`:\n\n- **`states`** — every state, upper snake case (`DRAFT`, `SENT`, `ACCEPTED`), and the\n **`initialState`** a new record starts in.\n- **`transitions`** — one per verb the business uses, as a lower-case slug (`send`, `accept`,\n `decline`, `issue`, `mark-paid`): the states it may start `from`, the state it moves `to`, and who\n performs it in the requirements' words. One verb is one transition: list every starting state in\n its `from`.\n- **`stampsField`** on a transition whose moment the business needs (when the quote was sent, when the\n invoice was paid): a camelCase timestamp field (`sentAt`, `paidAt`). `null` when nobody needs it.\n- **`createsResourceRef`** on a transition that creates another resource (accepting a quote\n creates a job). The created resource must be inventoried.\n- **`lockedStates`** — the states in which the record can no longer be EDITED but still moves on: an\n issued invoice (later marked paid), a sent quote (later accepted or declined). Empty when none.\n- **`finalStates`** — the TERMINAL states: nothing moves the record out of them, and it is not edited\n there either (a paid invoice, a closed case). Empty when nothing is ever final. No transition starts\n from a final state: a state you can leave is locked, not final.\n\nWrite `[]` when no resource moves through states. Read the requirements' verbs, not their nouns:\n\"an accepted quote can be used to create a job\" is a lifecycle (`accept`) and a conversion\n(`createsResourceRef: job`), not a foreign key. A value derived from other records — a next action,\nan overdue flag — is not a state of any resource (Step 1b).\n\n## Refine, don't re-author\n\n- **Keep what still holds.** On a re-run, do not rename or re-decompose modules\n that are already correct. Only add a module, move a resource to a different\n module, or add/correct a relationship where the plan genuinely changed.\n- **Reuse existing module ids.** A module that already exists keeps its\n `relatedModuleId` — never mint a second id for the same module. Likewise, keep a\n resource's name stable across runs.\n- **Never orphan a relationship.** A relationship draft must name two resources\n that are actually inventoried in Step 2. If you move or rename a resource, follow\n it into every relationship draft that references it.\n\n## Executable semantic evaluation — `domain-plan-output-set-result`\n\nThe staged output set first passes deterministic structural validation: exact\nmodule/resource identities, typed relationship ends, unique ownership, and the\natomic manifest must all be valid. That is a non-bypassable eligibility floor,\nnot a semantic quality opinion.\n\nThe companion then executes the playbook's structured semantic Treatment over\nthe exact staged output-set artifact. Its eight criteria remain distinct:\nrequirement coverage (a module home OR an engine realization), feature coverage,\nmodule justification, inventory plausibility, relationship integrity,\nplanning-depth boundary discipline, engine-concern discipline (no module or\nresource for what the engine provides, a disclaimer, or derived state), and\nlifecycle coverage (a requirement that moves a record through states has its\nlifecycle).\nEach criterion produces PASS / CONCERN / GAP / INDETERMINATE evidence, and the\nworst-verdict aggregation policy determines the Decision Rule consequence.\n\nA semantic PASS does **not** accept or publish the candidate. It transitions the\nresult Decision Point to `AUTHORITY_REQUIRED`; an explicit operator authority\ndecision is a separate later boundary. CONCERN or GAP requests revision,\nINDETERMINATE requests evidence, and evaluator or hard-floor failure blocks\nclosed. The evaluation path never mutates accepted specification heads.\n\n## Scaffold-depth boundary\n\nKeep this playbook at scaffold depth. Lifecycles (Step 4) are IN scope: they are what the\nresources DO, decided where the resources are, and nothing later decides them. Explicitly\n**out of scope here**:\n\n- **Schema / field authoring.** The inventory names resources and their owning\n module; it does **not** author fields, enums, decorators, or Zod schemas. That is\n the build loop. If you catch yourself writing a field list, stop.\n- **Cardinality-to-FK resolution.** A relationship draft states a cardinality\n *intent* and an ownership *intent* in prose. Resolving that into a physical\n foreign-key holder, a discriminator relationship, or a conditional relationship is\n the `module-relationships` skill's job **at build time**, not here.\n- **A full ERD / domain-graph solver.** Phases-of-a-graph, transitive dependency\n ordering, normalization analysis, and diagram generation are a later-phase\n concern. You draft modules, an inventory, and relationship intents — not a solved\n entity-relationship diagram.\n- **A full domain-graph solver.** The framework now ships a typed conceptual\n relationship-draft contract and deterministic structural validation for the\n atomic output set. It deliberately does not solve physical FK placement,\n normalization, graph execution order, discriminator relationships, or\n conditional relationships; those remain build-depth concerns.\n- **Code generation / module registration.** Scaffolding the module folders,\n registering the module across runtimes, generating resource files — all of that is\n the bottom-up build loop, downstream of this plan.\n\nIf you find yourself perfecting any of the above, stop: fields, physical foreign keys and\ngenerated code are the build's. What the build cannot invent — which states a resource has and\nwhich moves the business allows — is yours, in Step 4.\n\n## What you emit\n\nTwo artifacts for this journey:\n\n- The **domain-plan** under `specifications/src/domain-plan/` — a\n collection of `ModuleBusinessSemantics` drafts: the module decomposition, each\n module carrying its purpose, business capability, primary actors, and its\n `mainResources` / `supportingResources` inventory.\n- The **relationship drafts** inside the landed `specifications/src/domain-plan/` value\n — the inter-resource relationship intents (two ends + cardinality intent read\n source → target + ownership direction) between inventoried resources.\n\nAfter deterministic validation and semantic PASS, the runtime creates a distinct\nresult-bound Authority Request for the exact staged output-set digest. The local\noperator's explicit interface response settles that request; transition authority\ncannot substitute for it. Only then may the atomic specification-family mutation\naccept both files together for consumption by the bottom-up build loop.\n\n## References\n\nThese are skill FOLDERS installed in the application, named so each piece of work has an\nauthoring contract a later coding agent can open. This step has no tools and does not open them;\nwhat reaches you is this method, your declared inputs, and the brief's own sections.\n\n- `resource-add-module` — the module-scaffolding vocabulary\n (what a module is across the project layout); keeps module boundaries idiomatic.\n- `resource-add-resource` — the resource vocabulary (what a\n resource is); keeps the per-module inventory idiomatic.\n- `module-relationships` — the technical HOW of realising a\n relationship (FK fields, cardinality-to-FK-holder resolution, conditional /\n discriminator relationships) — consulted so relationship *intents* align with what\n the build loop can wire, NOT performed in this planning pass.\n",
51
51
  "skillRefs": [
52
52
  "resource-add-module",
53
53
  "resource-add-resource",
@@ -63,11 +63,14 @@
63
63
  "options": [
64
64
  "organizations",
65
65
  "users"
66
- ]
66
+ ],
67
+ "depth": "essential"
67
68
  }
68
69
  ]
69
70
  },
70
- "contextSources": [],
71
+ "contextSources": [
72
+ "creator_stated_facts"
73
+ ],
71
74
  "draftableDocumentDefinitionRefs": [],
72
75
  "suspendsForClarification": true,
73
76
  "briefAdequacyGate": false,
@@ -83,6 +83,22 @@ belong to their module and must not. The plan refuses both mistakes, in both dir
83
83
  **Plan an application view.** An application with none opens on whatever the shell defaults to,
84
84
  which is nobody's decision.
85
85
 
86
+ **Decide the home** (`home`): what a person sees first when they open the application. Two earlier
87
+ runs decided none, and both opened on the framework's welcome page. It is one of two things, the two
88
+ the engine can show at the root:
89
+
90
+ - `VIEW` — a planned `APPLICATION_VIEW`, shown in place (name its slug). Only an application view: the
91
+ root looks the view up among the application-level views, so a view owned by one resource (a
92
+ `RESOURCE_COMPOSITE_VIEW`) is not found there. When the home is one resource's view, plan an
93
+ application view that is the home, or make the home that resource's operation;
94
+ - `RESOURCE_OPERATION` — a resource's operation the root opens (module, resource, and the operation:
95
+ `list`, `read`, or a custom verb), reached through that operation's default variant.
96
+
97
+ Choose it for the group that opens the application most, from what the creator stated about the
98
+ user groups and their devices (the declared `creator_stated_facts` context section of your brief): a field worker on a phone
99
+ lands on today's jobs, an office manager at a desk on the pipeline. Say why in its `rationale`. The
100
+ home is authored in `GLOBAL_VIEWS`, so compose that surface when you decide one.
101
+
86
102
  ## Step 3 — Name the preset components each surface reuses
87
103
 
88
104
  This is the field this plan exists for. The framework ships a component catalogue, and a coding
@@ -128,9 +144,12 @@ Five rules decide whether planned guidance will ever be seen — plan against th
128
144
  earned BEFORE the flow's moment, never the one that same moment earns.
129
145
  - **Keep refs stable.** A guidance ref keys every person's saved progress; renaming it forgets it.
130
146
  - **A document names its host.** An `ONBOARDING_DOCUMENT` is seen only where a view embeds it, so it
131
- names that view in `hostViewRef` — a view you plan above, or one the application already has, and
132
- in either case a view of the document's OWN module: a document is declared by the module whose view
133
- shows it, and its build task writes only there. A flow names none: its trigger shows it.
147
+ names that view in `hostViewRef` — a view you plan above (this plan lists every view the application
148
+ keeps, so a view it already has is restated here), written as that view's `slug`, and a view of the
149
+ document's OWN module: a document is declared by the module whose view shows it, and its build task
150
+ writes only there. A host you did not plan is reported back to you; if it is still unplanned on the
151
+ last attempt, the document is dropped when the plan lands, never the plan. A flow names none: its
152
+ trigger shows it.
134
153
 
135
154
  Both carry `servesRefs`, like every surface.
136
155
 
@@ -143,9 +162,10 @@ identifiers and guidance refs, with one more reason: people's progress is stored
143
162
  ## What you emit
144
163
 
145
164
  - The **experience plan** at `specifications/src/experience-plan/index.ts` — the configuration
146
- surfaces this application composes, the views it carries — each with its kind, its home, what a
147
- person does on it, the presets it reuses and what it serves — and its journey: the milestones it
148
- recognises and the guidance toward them.
165
+ surfaces this application composes, the views it carries — each with its kind, the module (and
166
+ resource) it belongs to, what a person does on it, the presets it reuses and what it serves — its
167
+ journey (the milestones it recognises and the guidance toward them), and the application's `home`:
168
+ what a person sees first.
149
169
 
150
170
  ## Verification
151
171
 
@@ -156,6 +176,8 @@ identifiers and guidance refs, with one more reason: people's progress is stored
156
176
  - Every `triggerResourceRef` names a resource the domain plan declares, and no two guidance flows are
157
177
  planned on the same moment.
158
178
  - Every `gatedByMilestoneRefs` entry names a planned milestone or one the application already declares.
179
+ - A home is decided; a `VIEW` home names a planned `APPLICATION_VIEW`, a `RESOURCE_OPERATION` home names a
180
+ module and resource the domain plan declares, and `GLOBAL_VIEWS` is composed.
159
181
 
160
182
  ## References — named by REF, because this step cannot open a file
161
183
 
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "ref": "bottom_up.experience-plan",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "phase": "bottom_up",
5
5
  "intent": "User-experience composition — decide WHAT THIS APPLICATION'S EXPERIENCE IS beyond the screens the framework generates for each resource: which composite, custom, execution and chart views it carries and on which resource, which application-level views and dashboards it opens on, which custom components several views reuse, how its navigation, app shell, design system and global views are composed, and the JOURNEY a new person takes — the milestones it recognises and the onboarding documents and guidance flows that get a person there. Reads the domain plan (the modules, resources and relationships that exist), the requirements and feature drafts (what somebody asked for), the placement plan (where decided subjects already sit) and the brand (the visual tone the design system applies). Every view names the PRESET COMPONENTS it reuses, from the framework's own catalogue, because a coding agent with no catalogue in front of it builds custom surfaces out of raw elements and bypasses the theme, the surface policy and the accessibility behaviour every preset carries. Produces the plan; the decomposer turns it into build tasks, each bound to the skill the view's kind, the configuration's surface, the milestone or the guidance kind names.",
6
6
  "preconditions": [
@@ -36,12 +36,12 @@
36
36
  {
37
37
  "family": "experience-plan",
38
38
  "schemaRef": "saas-specifications:ExperiencePlan",
39
- "description": "The application's experience: the views it carries beyond the generated screens — each with its kind (which names the skill that authors it), the module and resource it belongs to, what a person does on it, the preset components it reuses and what it is accountable to — the application-wide configuration surfaces it composes, each naming what that file gains and why, and its journey: the milestones it recognises (identifier, module, the resource that earns each, the moment) and the guidance toward them (onboarding documents and guidance flows, the milestones each waits for)."
39
+ "description": "The application's experience: the views it carries beyond the generated screens — each with its kind (which names the skill that authors it), the module and resource it belongs to, what a person does on it, the preset components it reuses and what it is accountable to — the application-wide configuration surfaces it composes, each naming what that file gains and why, and its journey: the milestones it recognises (identifier, module, the resource that earns each, the moment) and the guidance toward them (onboarding documents and guidance flows, the milestones each waits for); and its home: what a person sees first, an application view or a resource's operation, with why."
40
40
  }
41
41
  ],
42
42
  "stepOutputs": [],
43
43
  "method": {
44
- "guidance": "# Experience Plan — What This Application's Experience Is\n\n### Target Application Framing\n\nThis knowledge is for configuring behavior in the target application.\nWildo is the framework surface being used, not the product being built.\n\nRead and apply these patterns from the application-developer point of view:\n\n- how the application should configure the relevant app-level file\n- how the application should use framework-provided factories, enums, and helpers\n- how the application should avoid mixing frontend, backend, and infrastructure concerns\n\n\n## Where you are in the journey\n\nThe domain plan is approved: the modules, resources and relationships exist as decisions, and the\nframework generates a list and a read screen for every resource without being asked. You decide\n**what this application carries beyond that** — the surfaces a person actually works on — **how\nits shell, navigation and palette are composed**, and **the journey a new person takes**: the\nmoments the application recognises, and the guidance that gets them there.\n\nYou do not write any of it. `bottom_up.build-decompose` turns each entry here into a build task\nbound to the skill that authors it.\n\n## This is not the placement plan\n\nPlacement decides WHERE a decided subject sits — which settings category, which sidebar section.\nThis decides WHICH SURFACES EXIST. Run in that order: a placement of a view nobody proposed places\nnothing, and the placement plan is an input here so a proposed surface does not duplicate something\nthe shell already reaches.\n\n## Step 1 — Compose the configuration surfaces\n\n**At least one, and in practice always the shell.** An application whose navigation and app shell\nare left at the scaffold's defaults has no route to its own modules: the generated screens exist and\nnothing reaches them. That is the one thing this plan refuses.\n\n| surface | what you decide | skill |\n|---|---|---|\n| `APP_SHELL` | which sidebar sections exist, what the top bar carries, the quick switcher's scope | `config-app-shell` |\n| `NAVIGATION` | the SHAPE the application navigates in — one thing at a time, list-and-detail, or a canvas with a floating detail — and then the zones and per-operation transitions that say it | `config-navigation` |\n| `DESIGN_SYSTEM` | the palette and typography, from the BRAND's visual tone — never invented here. When the brief says the brand does not apply (an internal tool), keep the scaffold's neutral theme and do not propose this surface | `config-design-system` |\n| `GLOBAL_VIEWS` | which app-level views are registered as launcher entries | `views-app-level` |\n\nEach names the things the file gains (`declarationRefs`) — a sidebar section ref, a zone, a token.\nNever the file: `wildo init` writes all four, so a decision that names nothing was true before any\ntask ran.\n\n**`NAVIGATION` is a product decision before it is a configuration.** The scaffold's default — one\nzone, a detail that replaces the list — is a real shape and it is right for some products and wrong\nfor others, and nothing about the domain plan reveals which. The question is *while a person is\nreading one record, what else must stay on screen*, and its answer comes from the ICPs and the\njobs-to-be-done that are already decided (on an application with no market, from\nthe operating team and the work the vision and the requirements describe): users who triage a queue need the list to stay, users who\nopen one record and finish it do not, and a product whose main surface is a board or a map needs the\ndetail to float over it rather than take a share of it.\n\nDecide it HERE, with the market and definition artifacts in front of you, and put the reasoning in\nthe surface's `rationale` — a later task reading only the layout cannot recover why that shape was\nchosen, and the shape decides whether a detail needs its own page chrome, whether a list wants\nselection affordances, and whether operations must be addressable. `config-navigation`\nopens with that question, translates the product shapes into what to declare, and names the trade\nthat is hardest to reverse: content in an overlay has no URL, so nobody can link to it.\n\n## Step 2 — Decide the surfaces\n\nA surface exists because a person has to do something the generated list and read cannot do. Six\nkinds, each naming the skill that authors it:\n\n| kind | what it is | belongs to |\n|---|---|---|\n| `RESOURCE_COMPOSITE_VIEW` | a workspace composing several resources around one | a resource |\n| `RESOURCE_CUSTOM_VIEW` | a bespoke screen for one operation — a wizard, a rich read | a resource |\n| `RESOURCE_EXECUTION_VIEW` | drives a long-running execution and shows its progress | a resource |\n| `RESOURCE_CHART_VIEW` | a chart over one resource's rows | a resource |\n| `APPLICATION_VIEW` | an application-level view or dashboard — the home a person opens on | a module |\n| `CUSTOM_COMPONENT` | a component several surfaces reuse | a module |\n\nThe first four are declared in ONE resource's ui-behavior, so each names its resource; the last two\nbelong to their module and must not. The plan refuses both mistakes, in both directions.\n\n**Plan an application view.** An application with none opens on whatever the shell defaults to,\nwhich is nobody's decision.\n\n## Step 3 — Name the preset components each surface reuses\n\nThis is the field this plan exists for. The framework ships a component catalogue, and a coding\nagent that has not been told which components to reuse builds the surface out of raw elements —\nbypassing the theme, the surface policy and the accessibility behaviour every preset carries. Read\nthe catalogue (`frontend-component-catalog`) and name the components each surface is composed from.\n\nA `CUSTOM_COMPONENT` reuses nothing by definition: it IS the reusable thing.\n\n## Step 4 — Make every surface accountable\n\nEach carries `servesRefs`: the requirement, feature draft, roadmap phase or success criterion that\nasked for it. A surface accountable to nothing is one nobody asked for, and the plan reports it.\n\n## Step 5 — Plan the journey\n\nA new person arrives at an application they have never used. Decide what recognises their progress\nand what tells them what to do first. **Plan at least one of the two** — a plan with neither is\nreported, because a new person then meets a product that neither welcomes nor guides them. An\ninternal tool may rightly have neither; say so by leaving both empty on purpose.\n\n**Milestones** — the moments worth recognising: a person's first record of the thing the product is\nfor, a count that shows it is working for them, a moment a whole organization reaches together. Each\nnames its identifier as a slug (`first-deal-won`, declared `FIRST_DEAL_WON` in code), its module,\nthe resource whose operation earns it, and the moment in the person's own terms. How loudly each one\ncelebrates is decided when it is built, not here.\n\n**Guidance** — two shapes, and choosing between them is the decision:\n\n| kind | what it is | use it when |\n|---|---|---|\n| `ONBOARDING_DOCUMENT` | embedded on a screen — a welcome announcement, a getting-started stepper | the guidance belongs to a place, and should be there whenever that place is |\n| `GUIDANCE_FLOW` | triggered by an event — a banner after the first X, a tour, a one-question survey | the guidance belongs to a moment, and should appear once, right after something happened |\n\nFive rules decide whether planned guidance will ever be seen — plan against them:\n\n- **Only one triggered overlay shows at a time.** The others wait behind it until it is finished,\n skipped or dismissed, and a waiting one is dropped if the page reloads first — so a second flow\n planned on the same moment is often never seen. Give each flow its own moment.\n- **A flow shows once per person.** Guidance that should appear every time — an empty-list message —\n is not a flow; it belongs to the resource's own screen.\n- **A gate is a milestone the person already holds.** `gatedByMilestoneRefs` must name milestones\n earned BEFORE the flow's moment, never the one that same moment earns.\n- **Keep refs stable.** A guidance ref keys every person's saved progress; renaming it forgets it.\n- **A document names its host.** An `ONBOARDING_DOCUMENT` is seen only where a view embeds it, so it\n names that view in `hostViewRef` — a view you plan above, or one the application already has, and\n in either case a view of the document's OWN module: a document is declared by the module whose view\n shows it, and its build task writes only there. A flow names none: its trigger shows it.\n\nBoth carry `servesRefs`, like every surface.\n\n## Refine, don't re-author\n\nYour own prior plan is an input. Keep every view ref that still has a reason to exist — build tasks\nname them, and a moved ref orphans the task that produced its surface. The same holds for milestone\nidentifiers and guidance refs, with one more reason: people's progress is stored against them.\n\n## What you emit\n\n- The **experience plan** at `specifications/src/experience-plan/index.ts` — the configuration\n surfaces this application composes, the views it carries — each with its kind, its home, what a\n person does on it, the presets it reuses and what it serves — and its journey: the milestones it\n recognises and the guidance toward them.\n\n## Verification\n\n- Every `moduleRef` and `resourceRef` names something the domain plan declares.\n- Every `reusesComponentRefs` entry names a component the catalogue carries.\n- `rg -n \"kind: ExperienceViewKind\" specifications/src/experience-plan/index.ts | wc -l` — the number\n of view tasks the build lane will emit.\n- Every `triggerResourceRef` names a resource the domain plan declares, and no two guidance flows are\n planned on the same moment.\n- Every `gatedByMilestoneRefs` entry names a planned milestone or one the application already declares.\n\n## References — named by REF, because this step cannot open a file\n\nA structured generation has no filesystem, so a path here would be an instruction answered from\nrecollection (#1435). Each skill is named by its REF, and one reaches this step as a BODY\n(`method.skillBodyRefs`): **`frontend-component-catalog`**. That is not a convenience — naming the\npresets each surface reuses is this plan's whole point, and a model without the catalogue in front\nof it invents component names that resolve to nothing.\n\nThe rest are the contracts the CODING AGENT opens when it builds each task:\n\n- `views-composite-authoring` — what a composite view IS, so a planned one is one the build lane can author.\n- `resource-custom-view` — a custom view's shape and its binding.\n- `spec-composite-view-update` — the specification a composite view owes.\n- `views-add-composite-view`, `views-add-custom-view`, `views-execution-authoring`,\n `views-chart-authoring`, `views-app-level`, `engine-component-registration` — one per view KIND,\n bound to the emitted task by `EXPERIENCE_VIEW_SKILL_REF`.\n- `config-app-shell`, `config-navigation`, `config-design-system` — one per configuration SURFACE,\n bound by `EXPERIENCE_CONFIGURATION_SKILL_REF`.\n- `milestones-and-celebrations` — how a planned milestone is declared and celebrated, bound by\n `EXPERIENCE_MILESTONE_SKILL_REF`.\n- `guidance-onboarding-authoring` — how a planned document or flow is authored, bound by\n `EXPERIENCE_GUIDANCE_SKILL_REF`.\n",
44
+ "guidance": "# Experience Plan — What This Application's Experience Is\n\n### Target Application Framing\n\nThis knowledge is for configuring behavior in the target application.\nWildo is the framework surface being used, not the product being built.\n\nRead and apply these patterns from the application-developer point of view:\n\n- how the application should configure the relevant app-level file\n- how the application should use framework-provided factories, enums, and helpers\n- how the application should avoid mixing frontend, backend, and infrastructure concerns\n\n\n## Where you are in the journey\n\nThe domain plan is approved: the modules, resources and relationships exist as decisions, and the\nframework generates a list and a read screen for every resource without being asked. You decide\n**what this application carries beyond that** — the surfaces a person actually works on — **how\nits shell, navigation and palette are composed**, and **the journey a new person takes**: the\nmoments the application recognises, and the guidance that gets them there.\n\nYou do not write any of it. `bottom_up.build-decompose` turns each entry here into a build task\nbound to the skill that authors it.\n\n## This is not the placement plan\n\nPlacement decides WHERE a decided subject sits — which settings category, which sidebar section.\nThis decides WHICH SURFACES EXIST. Run in that order: a placement of a view nobody proposed places\nnothing, and the placement plan is an input here so a proposed surface does not duplicate something\nthe shell already reaches.\n\n## Step 1 — Compose the configuration surfaces\n\n**At least one, and in practice always the shell.** An application whose navigation and app shell\nare left at the scaffold's defaults has no route to its own modules: the generated screens exist and\nnothing reaches them. That is the one thing this plan refuses.\n\n| surface | what you decide | skill |\n|---|---|---|\n| `APP_SHELL` | which sidebar sections exist, what the top bar carries, the quick switcher's scope | `config-app-shell` |\n| `NAVIGATION` | the SHAPE the application navigates in — one thing at a time, list-and-detail, or a canvas with a floating detail — and then the zones and per-operation transitions that say it | `config-navigation` |\n| `DESIGN_SYSTEM` | the palette and typography, from the BRAND's visual tone — never invented here. When the brief says the brand does not apply (an internal tool), keep the scaffold's neutral theme and do not propose this surface | `config-design-system` |\n| `GLOBAL_VIEWS` | which app-level views are registered as launcher entries | `views-app-level` |\n\nEach names the things the file gains (`declarationRefs`) — a sidebar section ref, a zone, a token.\nNever the file: `wildo init` writes all four, so a decision that names nothing was true before any\ntask ran.\n\n**`NAVIGATION` is a product decision before it is a configuration.** The scaffold's default — one\nzone, a detail that replaces the list — is a real shape and it is right for some products and wrong\nfor others, and nothing about the domain plan reveals which. The question is *while a person is\nreading one record, what else must stay on screen*, and its answer comes from the ICPs and the\njobs-to-be-done that are already decided (on an application with no market, from\nthe operating team and the work the vision and the requirements describe): users who triage a queue need the list to stay, users who\nopen one record and finish it do not, and a product whose main surface is a board or a map needs the\ndetail to float over it rather than take a share of it.\n\nDecide it HERE, with the market and definition artifacts in front of you, and put the reasoning in\nthe surface's `rationale` — a later task reading only the layout cannot recover why that shape was\nchosen, and the shape decides whether a detail needs its own page chrome, whether a list wants\nselection affordances, and whether operations must be addressable. `config-navigation`\nopens with that question, translates the product shapes into what to declare, and names the trade\nthat is hardest to reverse: content in an overlay has no URL, so nobody can link to it.\n\n## Step 2 — Decide the surfaces\n\nA surface exists because a person has to do something the generated list and read cannot do. Six\nkinds, each naming the skill that authors it:\n\n| kind | what it is | belongs to |\n|---|---|---|\n| `RESOURCE_COMPOSITE_VIEW` | a workspace composing several resources around one | a resource |\n| `RESOURCE_CUSTOM_VIEW` | a bespoke screen for one operation — a wizard, a rich read | a resource |\n| `RESOURCE_EXECUTION_VIEW` | drives a long-running execution and shows its progress | a resource |\n| `RESOURCE_CHART_VIEW` | a chart over one resource's rows | a resource |\n| `APPLICATION_VIEW` | an application-level view or dashboard — the home a person opens on | a module |\n| `CUSTOM_COMPONENT` | a component several surfaces reuse | a module |\n\nThe first four are declared in ONE resource's ui-behavior, so each names its resource; the last two\nbelong to their module and must not. The plan refuses both mistakes, in both directions.\n\n**Plan an application view.** An application with none opens on whatever the shell defaults to,\nwhich is nobody's decision.\n\n**Decide the home** (`home`): what a person sees first when they open the application. Two earlier\nruns decided none, and both opened on the framework's welcome page. It is one of two things, the two\nthe engine can show at the root:\n\n- `VIEW` — a planned `APPLICATION_VIEW`, shown in place (name its slug). Only an application view: the\n root looks the view up among the application-level views, so a view owned by one resource (a\n `RESOURCE_COMPOSITE_VIEW`) is not found there. When the home is one resource's view, plan an\n application view that is the home, or make the home that resource's operation;\n- `RESOURCE_OPERATION` — a resource's operation the root opens (module, resource, and the operation:\n `list`, `read`, or a custom verb), reached through that operation's default variant.\n\nChoose it for the group that opens the application most, from what the creator stated about the\nuser groups and their devices (the declared `creator_stated_facts` context section of your brief): a field worker on a phone\nlands on today's jobs, an office manager at a desk on the pipeline. Say why in its `rationale`. The\nhome is authored in `GLOBAL_VIEWS`, so compose that surface when you decide one.\n\n## Step 3 — Name the preset components each surface reuses\n\nThis is the field this plan exists for. The framework ships a component catalogue, and a coding\nagent that has not been told which components to reuse builds the surface out of raw elements —\nbypassing the theme, the surface policy and the accessibility behaviour every preset carries. Read\nthe catalogue (`frontend-component-catalog`) and name the components each surface is composed from.\n\nA `CUSTOM_COMPONENT` reuses nothing by definition: it IS the reusable thing.\n\n## Step 4 — Make every surface accountable\n\nEach carries `servesRefs`: the requirement, feature draft, roadmap phase or success criterion that\nasked for it. A surface accountable to nothing is one nobody asked for, and the plan reports it.\n\n## Step 5 — Plan the journey\n\nA new person arrives at an application they have never used. Decide what recognises their progress\nand what tells them what to do first. **Plan at least one of the two** — a plan with neither is\nreported, because a new person then meets a product that neither welcomes nor guides them. An\ninternal tool may rightly have neither; say so by leaving both empty on purpose.\n\n**Milestones** — the moments worth recognising: a person's first record of the thing the product is\nfor, a count that shows it is working for them, a moment a whole organization reaches together. Each\nnames its identifier as a slug (`first-deal-won`, declared `FIRST_DEAL_WON` in code), its module,\nthe resource whose operation earns it, and the moment in the person's own terms. How loudly each one\ncelebrates is decided when it is built, not here.\n\n**Guidance** — two shapes, and choosing between them is the decision:\n\n| kind | what it is | use it when |\n|---|---|---|\n| `ONBOARDING_DOCUMENT` | embedded on a screen — a welcome announcement, a getting-started stepper | the guidance belongs to a place, and should be there whenever that place is |\n| `GUIDANCE_FLOW` | triggered by an event — a banner after the first X, a tour, a one-question survey | the guidance belongs to a moment, and should appear once, right after something happened |\n\nFive rules decide whether planned guidance will ever be seen — plan against them:\n\n- **Only one triggered overlay shows at a time.** The others wait behind it until it is finished,\n skipped or dismissed, and a waiting one is dropped if the page reloads first — so a second flow\n planned on the same moment is often never seen. Give each flow its own moment.\n- **A flow shows once per person.** Guidance that should appear every time — an empty-list message —\n is not a flow; it belongs to the resource's own screen.\n- **A gate is a milestone the person already holds.** `gatedByMilestoneRefs` must name milestones\n earned BEFORE the flow's moment, never the one that same moment earns.\n- **Keep refs stable.** A guidance ref keys every person's saved progress; renaming it forgets it.\n- **A document names its host.** An `ONBOARDING_DOCUMENT` is seen only where a view embeds it, so it\n names that view in `hostViewRef` — a view you plan above (this plan lists every view the application\n keeps, so a view it already has is restated here), written as that view's `slug`, and a view of the\n document's OWN module: a document is declared by the module whose view shows it, and its build task\n writes only there. A host you did not plan is reported back to you; if it is still unplanned on the\n last attempt, the document is dropped when the plan lands, never the plan. A flow names none: its\n trigger shows it.\n\nBoth carry `servesRefs`, like every surface.\n\n## Refine, don't re-author\n\nYour own prior plan is an input. Keep every view ref that still has a reason to exist — build tasks\nname them, and a moved ref orphans the task that produced its surface. The same holds for milestone\nidentifiers and guidance refs, with one more reason: people's progress is stored against them.\n\n## What you emit\n\n- The **experience plan** at `specifications/src/experience-plan/index.ts` — the configuration\n surfaces this application composes, the views it carries — each with its kind, the module (and\n resource) it belongs to, what a person does on it, the presets it reuses and what it serves — its\n journey (the milestones it recognises and the guidance toward them), and the application's `home`:\n what a person sees first.\n\n## Verification\n\n- Every `moduleRef` and `resourceRef` names something the domain plan declares.\n- Every `reusesComponentRefs` entry names a component the catalogue carries.\n- `rg -n \"kind: ExperienceViewKind\" specifications/src/experience-plan/index.ts | wc -l` — the number\n of view tasks the build lane will emit.\n- Every `triggerResourceRef` names a resource the domain plan declares, and no two guidance flows are\n planned on the same moment.\n- Every `gatedByMilestoneRefs` entry names a planned milestone or one the application already declares.\n- A home is decided; a `VIEW` home names a planned `APPLICATION_VIEW`, a `RESOURCE_OPERATION` home names a\n module and resource the domain plan declares, and `GLOBAL_VIEWS` is composed.\n\n## References — named by REF, because this step cannot open a file\n\nA structured generation has no filesystem, so a path here would be an instruction answered from\nrecollection (#1435). Each skill is named by its REF, and one reaches this step as a BODY\n(`method.skillBodyRefs`): **`frontend-component-catalog`**. That is not a convenience — naming the\npresets each surface reuses is this plan's whole point, and a model without the catalogue in front\nof it invents component names that resolve to nothing.\n\nThe rest are the contracts the CODING AGENT opens when it builds each task:\n\n- `views-composite-authoring` — what a composite view IS, so a planned one is one the build lane can author.\n- `resource-custom-view` — a custom view's shape and its binding.\n- `spec-composite-view-update` — the specification a composite view owes.\n- `views-add-composite-view`, `views-add-custom-view`, `views-execution-authoring`,\n `views-chart-authoring`, `views-app-level`, `engine-component-registration` — one per view KIND,\n bound to the emitted task by `EXPERIENCE_VIEW_SKILL_REF`.\n- `config-app-shell`, `config-navigation`, `config-design-system` — one per configuration SURFACE,\n bound by `EXPERIENCE_CONFIGURATION_SKILL_REF`.\n- `milestones-and-celebrations` — how a planned milestone is declared and celebrated, bound by\n `EXPERIENCE_MILESTONE_SKILL_REF`.\n- `guidance-onboarding-authoring` — how a planned document or flow is authored, bound by\n `EXPERIENCE_GUIDANCE_SKILL_REF`.\n",
45
45
  "skillRefs": [
46
46
  "frontend-component-catalog",
47
47
  "views-composite-authoring",
@@ -57,7 +57,8 @@
57
57
  "frontend-component-catalog"
58
58
  ],
59
59
  "contextSources": [
60
- "workspace_truth"
60
+ "workspace_truth",
61
+ "creator_stated_facts"
61
62
  ],
62
63
  "draftableDocumentDefinitionRefs": [],
63
64
  "suspendsForClarification": false,
@@ -68,17 +68,23 @@
68
68
  "sameDecisionAs": {
69
69
  "playbookRef": "bottom_up.domain-plan",
70
70
  "questionRef": "tenancy"
71
- }
71
+ },
72
+ "depth": "essential"
72
73
  },
73
74
  {
74
75
  "ref": "operating-entity",
75
76
  "question": "Which legal entity operates this service? Give the registered company name, its registered address, and the route a person uses to reach you about privacy (an email, a URL or a postal address). Answer only the parts you actually know today — anything you leave out is recorded as outstanding and nothing is blocked by it. Do NOT supply a placeholder or a plausible-looking value: a produced privacy notice quotes these as fact, and the address is what a person would use to serve a legal request on a real company.",
76
- "kind": "free_text"
77
+ "kind": "free_text",
78
+ "depth": "essential",
79
+ "whenUnknown": "ask",
80
+ "regulatedDomain": true
77
81
  },
78
82
  {
79
83
  "ref": "operating-jurisdictions",
80
84
  "question": "Which jurisdictions does this application operate in, and why does each one reach it — are you established there, do you sell there, or do you hold data about people there? Use country codes (`fr`, `us`), the supranational `eu`, or a subdivision (`us-ca`). Answer \"not decided\" if the market is genuinely unsettled; an absent answer is read as unanswered, never as \"nowhere\".",
81
- "kind": "free_text"
85
+ "kind": "free_text",
86
+ "depth": "essential",
87
+ "regulatedDomain": true
82
88
  },
83
89
  {
84
90
  "ref": "billing-provider",
@@ -87,7 +93,8 @@
87
93
  "options": [
88
94
  "stripe",
89
95
  "none"
90
- ]
96
+ ],
97
+ "depth": "detail"
91
98
  },
92
99
  {
93
100
  "ref": "sms-provider",
@@ -96,7 +103,8 @@
96
103
  "options": [
97
104
  "twilio",
98
105
  "none"
99
- ]
106
+ ],
107
+ "depth": "detail"
100
108
  }
101
109
  ]
102
110
  },
@@ -91,6 +91,56 @@ from forgetting the audit log existed.
91
91
  So: if a destination should not appear anywhere in this application, say so, and say
92
92
  why.
93
93
 
94
+ ## First: does this application need it at all? (the fit test)
95
+
96
+ Before WHERE comes WHETHER. Every engine settings destination exists in the framework; that is not
97
+ a reason to show it. A destination is placed only when something this application declared calls
98
+ for it:
99
+
100
+ - **a requirement** that needs it (single sign-on because a requirement says customers sign in with
101
+ their company identity);
102
+ - **an attribute of the customer profile** in your `market-snapshot` input (the ICPs and personas:
103
+ company size, the tools they already run, their technical staff); or
104
+ - **a capability the application enables** (billing settings because billing is on). What is on is
105
+ not yours to guess: the declared `application_enabled_surface` context section of your brief lists the enabled engine
106
+ capabilities, the billing declaration and each user type's sign-in methods, read from the
107
+ configuration. A capability it does not list is off; one it marks UNREADABLE is unknown, and you
108
+ say so rather than treating it as off. A destination whose capability is off serves nothing yet:
109
+ offer it only when the customer evidence asks for it, and say its capability must be switched on.
110
+
111
+ Otherwise it is DECLINED, with the profile reason. One earlier run, for a 1–20 person trade firm,
112
+ declined single sign-on because such a firm "is not assumed to operate an enterprise identity
113
+ provider". Another, from the same inputs, placed SSO, SCIM, SIEM export, webhooks and legal holds
114
+ because "an admin would look here". Only the first answered the question that comes first.
115
+
116
+ The test cuts both ways. For a 2,000-person insurer whose personas name an identity team and whose
117
+ requirements say staff sign in with their company account, declining single sign-on would be the
118
+ error: there the profile and a requirement both call for it, and it is placed, with both cited. Fit
119
+ is read from THIS application's evidence, never from a habit of declining enterprise features.
120
+
121
+ **Enterprise destinations cite their evidence in the rationale.** Single sign-on, directory sync
122
+ (SCIM), security-event export (SIEM), webhooks, legal holds, API clients and data residency are
123
+ placed only with the requirement, profile attribute or capability named in the rationale. "An admin
124
+ would look here" is findability, not fit; it answers a question you have not earned yet.
125
+
126
+ Read who uses the product from what the creator stated (the declared `creator_stated_facts` context section of your brief):
127
+ the user groups and the devices they use. A field worker on a phone and an office manager at a desk
128
+ want different things first, and the sidebar's order should serve the group that opens it most.
129
+
130
+ **When a section or an entry is for one audience only, say so with `visibleToRoles`.** A sidebar group and
131
+ a sidebar or command-menu decision may carry `visibleToRoles`: the role keys that see it (a field
132
+ technician does not see the office's "Invoices" section). Use it only when the creator's user groups
133
+ really differ in what they open, and name the application's own roles, or core ones like `ORG_ADMIN`.
134
+ A custom role counts only as itself, so list every role that should see it. Absent means everyone,
135
+ and that is the right answer for most groups. It is refused on the settings rail and the user menu,
136
+ whose destinations carry their own role gating.
137
+
138
+ Hiding is not access control: the person who cannot see "Invoices" can still be allowed to open it.
139
+ If the field technician must not read invoices, that is a role decision on the operation, not a
140
+ placement, and an entry for an operation a viewer cannot perform is hidden from them already. So
141
+ `visibleToRoles` is only for narrowing further: an operation everyone may use that only one group
142
+ needs in its navigation.
143
+
94
144
  ## The criteria, in the order you apply them
95
145
 
96
146
  1. **Scope correctness.** A thing that acts on the whole organization does not sit