forjajs 5.0.0 → 5.1.0

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 (171) hide show
  1. package/CHANGELOG.md +68 -2
  2. package/README.md +4 -2
  3. package/README.pt-BR.md +4 -1
  4. package/boilerplates/02-saas-starter/README.md +58 -293
  5. package/boilerplates/02-saas-starter/backend/.env.example +13 -0
  6. package/boilerplates/02-saas-starter/backend/.oxlintrc.json +8 -0
  7. package/boilerplates/02-saas-starter/backend/nest-cli.json +6 -0
  8. package/boilerplates/02-saas-starter/backend/package.json +32 -73
  9. package/boilerplates/02-saas-starter/backend/src/app.module.ts +16 -16
  10. package/boilerplates/02-saas-starter/backend/src/billing/adapters/http/billing.controller.ts +55 -0
  11. package/boilerplates/02-saas-starter/backend/src/billing/adapters/persistence/orm-entities.ts +28 -0
  12. package/boilerplates/02-saas-starter/backend/src/billing/adapters/persistence/typeorm-billing.repository.ts +46 -0
  13. package/boilerplates/02-saas-starter/backend/src/billing/application/billing.service.spec.ts +58 -0
  14. package/boilerplates/02-saas-starter/backend/src/billing/application/billing.service.ts +68 -0
  15. package/boilerplates/02-saas-starter/backend/src/billing/billing.module.ts +11 -0
  16. package/boilerplates/02-saas-starter/backend/src/billing/domain/plan.spec.ts +23 -0
  17. package/boilerplates/02-saas-starter/backend/src/billing/domain/plan.ts +36 -0
  18. package/boilerplates/02-saas-starter/backend/src/billing/domain/ports.ts +27 -0
  19. package/boilerplates/02-saas-starter/backend/src/billing/domain/subscription.spec.ts +28 -0
  20. package/boilerplates/02-saas-starter/backend/src/billing/domain/subscription.ts +47 -0
  21. package/boilerplates/02-saas-starter/backend/src/identity/adapters/http/auth.dto.ts +22 -0
  22. package/boilerplates/02-saas-starter/backend/src/identity/adapters/http/identity.controller.ts +59 -0
  23. package/boilerplates/02-saas-starter/backend/src/identity/adapters/persistence/orm-entities.ts +25 -0
  24. package/boilerplates/02-saas-starter/backend/src/identity/adapters/persistence/typeorm-identity.repository.ts +47 -0
  25. package/boilerplates/02-saas-starter/backend/src/identity/application/auth.service.spec.ts +72 -0
  26. package/boilerplates/02-saas-starter/backend/src/identity/application/auth.service.ts +63 -0
  27. package/boilerplates/02-saas-starter/backend/src/identity/domain/model.spec.ts +19 -0
  28. package/boilerplates/02-saas-starter/backend/src/identity/domain/model.ts +42 -0
  29. package/boilerplates/02-saas-starter/backend/src/identity/domain/password.spec.ts +17 -0
  30. package/boilerplates/02-saas-starter/backend/src/identity/domain/password.ts +26 -0
  31. package/boilerplates/02-saas-starter/backend/src/identity/identity.module.ts +12 -0
  32. package/boilerplates/02-saas-starter/backend/src/main.ts +19 -19
  33. package/boilerplates/02-saas-starter/backend/src/platform/auth/jwt-auth.guard.ts +17 -0
  34. package/boilerplates/02-saas-starter/backend/src/platform/auth/principal.ts +22 -0
  35. package/boilerplates/02-saas-starter/backend/src/platform/auth/roles.guard.spec.ts +23 -0
  36. package/boilerplates/02-saas-starter/backend/src/platform/auth/roles.guard.ts +20 -0
  37. package/boilerplates/02-saas-starter/backend/src/platform/auth/token.service.ts +54 -0
  38. package/boilerplates/02-saas-starter/backend/src/platform/config.spec.ts +18 -0
  39. package/boilerplates/02-saas-starter/backend/src/platform/config.ts +33 -0
  40. package/boilerplates/02-saas-starter/backend/src/platform/platform.module.ts +14 -0
  41. package/boilerplates/02-saas-starter/backend/tsconfig.build.json +6 -0
  42. package/boilerplates/02-saas-starter/backend/tsconfig.json +16 -21
  43. package/boilerplates/02-saas-starter/backend/vitest.config.ts +7 -0
  44. package/boilerplates/02-saas-starter/boilerplate.manifest.json +19 -14
  45. package/boilerplates/02-saas-starter/docker-compose.yml +10 -24
  46. package/boilerplates/02-saas-starter/memory/30-domains/billing/context.md +15 -132
  47. package/boilerplates/02-saas-starter/memory/30-domains/identity/context.md +20 -0
  48. package/boilerplates/README.md +9 -10
  49. package/dist/bin/create-memory-nest-kit.js +0 -0
  50. package/dist/bin/forja.js +0 -0
  51. package/dist/bin/init-project.js +1 -0
  52. package/dist/lib/core/journey.js +10 -0
  53. package/dist/lib/generators/memory-generator.d.ts +0 -11
  54. package/dist/lib/generators/memory-generator.js +5 -161
  55. package/dist/lib/generators/readme-generator.js +1 -1
  56. package/dist/lib/llm/json-output.d.ts +14 -0
  57. package/dist/lib/llm/json-output.js +77 -0
  58. package/dist/lib/project-upgrade.d.ts +0 -4
  59. package/dist/lib/project-upgrade.js +19 -1
  60. package/dist/lib/project-wiring.d.ts +8 -0
  61. package/dist/lib/project-wiring.js +74 -2
  62. package/dist/lib/validators/structure-validator.js +0 -1
  63. package/dist/packages/llm/src/index.js +12 -2
  64. package/dist/scripts/llm-fit.js +23 -1
  65. package/dist/scripts/project-upgrade.js +9 -6
  66. package/docs/init-project.md +1 -1
  67. package/docs/llm-fit-loop.md +16 -0
  68. package/memory/90-decisions/0086-projeto-conectado-e-jornada-como-gate.md +1 -1
  69. package/memory/90-decisions/0088-templates-validados.md +3 -0
  70. package/memory/90-decisions/0089-skills-do-projeto.md +51 -0
  71. package/memory/90-decisions/0090-adapters-de-agente-somente-leitura.md +47 -0
  72. package/package.json +2 -2
  73. package/specs/skills-do-projeto/plan.md +40 -0
  74. package/specs/skills-do-projeto/spec.md +63 -0
  75. package/specs/skills-do-projeto/tasks.md +27 -0
  76. package/templates/project/AGENTS.md +9 -0
  77. package/templates/project/agents/context-engineer.md +3 -0
  78. package/templates/project/agents/governance.md +3 -0
  79. package/templates/project/agents/marketing.md +3 -0
  80. package/templates/project/agents/orchestrator.md +3 -0
  81. package/templates/project/agents/product.md +3 -0
  82. package/templates/project/agents/sdd-architect.md +3 -0
  83. package/templates/project/skills/README.md +14 -0
  84. package/templates/project/skills/accessibility-review/SKILL.md +89 -0
  85. package/templates/project/skills/api-design/SKILL.md +77 -0
  86. package/templates/project/skills/architecture-decision-record/SKILL.md +92 -0
  87. package/templates/project/skills/backlog-slicing/SKILL.md +82 -0
  88. package/templates/project/skills/bounded-context-mapping/SKILL.md +88 -0
  89. package/templates/project/skills/ci-pipeline-review/SKILL.md +83 -0
  90. package/templates/project/skills/commit-message/SKILL.md +143 -0
  91. package/templates/project/skills/data-migrations/SKILL.md +88 -0
  92. package/templates/project/skills/dependency-upgrade/SKILL.md +75 -0
  93. package/templates/project/skills/docker-compose-review/SKILL.md +85 -0
  94. package/templates/project/skills/domain-modeling/SKILL.md +120 -0
  95. package/templates/project/skills/event-storming/SKILL.md +95 -0
  96. package/templates/project/skills/executive-writing/SKILL.md +99 -0
  97. package/templates/project/skills/frontend-architecture/SKILL.md +97 -0
  98. package/templates/project/skills/incident-postmortem/SKILL.md +93 -0
  99. package/templates/project/skills/lgpd-compliance/SKILL.md +108 -0
  100. package/templates/project/skills/llm-provider-routing/SKILL.md +18 -0
  101. package/templates/project/skills/observability/SKILL.md +93 -0
  102. package/templates/project/skills/product-evaluation/SKILL.md +130 -0
  103. package/templates/project/skills/prompt-spec/SKILL.md +83 -0
  104. package/templates/project/skills/pull-request/SKILL.md +101 -0
  105. package/templates/project/skills/query-performance/SKILL.md +83 -0
  106. package/templates/project/skills/release-checklist/SKILL.md +106 -0
  107. package/templates/project/skills/release-notes/SKILL.md +87 -0
  108. package/templates/project/skills/requirements-elicitation/SKILL.md +127 -0
  109. package/templates/project/skills/requirements-gathering/SKILL.md +134 -0
  110. package/templates/project/skills/technical-spike/SKILL.md +101 -0
  111. package/templates/project/skills/testing/SKILL.md +109 -0
  112. package/templates/project/skills/threat-modeling/SKILL.md +87 -0
  113. package/templates/project/skills/ts-async-patterns/SKILL.md +101 -0
  114. package/templates/project/skills/ts-code-review/SKILL.md +121 -0
  115. package/templates/project/skills/ts-module-layout/SKILL.md +104 -0
  116. package/templates/project/skills/ts-testing/SKILL.md +89 -0
  117. package/templates/project/skills/web-performance/SKILL.md +72 -0
  118. package/boilerplates/02-saas-starter/.env.example +0 -25
  119. package/boilerplates/02-saas-starter/CHECKLIST-CRIACAO.md +0 -190
  120. package/boilerplates/02-saas-starter/INFO.md +0 -252
  121. package/boilerplates/02-saas-starter/QUICK_START.md +0 -194
  122. package/boilerplates/02-saas-starter/START-HERE.md +0 -259
  123. package/boilerplates/02-saas-starter/backend/src/common/decorators/roles.decorator.ts +0 -3
  124. package/boilerplates/02-saas-starter/backend/src/common/decorators/tenant.decorator.ts +0 -6
  125. package/boilerplates/02-saas-starter/backend/src/common/middleware/roles.guard.ts +0 -23
  126. package/boilerplates/02-saas-starter/backend/src/config/database.ts +0 -26
  127. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.controller.ts +0 -46
  128. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.module.ts +0 -25
  129. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.service.ts +0 -145
  130. package/boilerplates/02-saas-starter/backend/src/modules/auth/dto/auth.dto.ts +0 -30
  131. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/jwt.strategy.ts +0 -24
  132. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/local.strategy.ts +0 -19
  133. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.controller.ts +0 -42
  134. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.module.ts +0 -13
  135. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.service.ts +0 -67
  136. package/boilerplates/02-saas-starter/backend/src/modules/billing/entities/invoice.entity.ts +0 -52
  137. package/boilerplates/02-saas-starter/backend/src/modules/organizations/entities/organization.entity.ts +0 -36
  138. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.controller.ts +0 -16
  139. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.module.ts +0 -13
  140. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.service.ts +0 -34
  141. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/entities/subscription.entity.ts +0 -40
  142. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.controller.ts +0 -36
  143. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.module.ts +0 -13
  144. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.service.ts +0 -91
  145. package/boilerplates/02-saas-starter/backend/src/modules/users/entities/user.entity.ts +0 -42
  146. package/boilerplates/02-saas-starter/backend/src/modules/users/users.controller.ts +0 -14
  147. package/boilerplates/02-saas-starter/backend/src/modules/users/users.module.ts +0 -13
  148. package/boilerplates/02-saas-starter/backend/src/modules/users/users.service.ts +0 -48
  149. package/boilerplates/02-saas-starter/memory/00-global/agent-contract.md +0 -227
  150. package/boilerplates/02-saas-starter/memory/00-global/context-policy.md +0 -141
  151. package/boilerplates/02-saas-starter/memory/00-global/index.md +0 -133
  152. package/boilerplates/02-saas-starter/memory/00-global/mission.md +0 -45
  153. package/boilerplates/02-saas-starter/memory/00-global/patterns.md +0 -223
  154. package/boilerplates/02-saas-starter/memory/10-product/business-rules.md +0 -240
  155. package/boilerplates/02-saas-starter/memory/10-product/nfrs.md +0 -239
  156. package/boilerplates/02-saas-starter/memory/10-product/personas.md +0 -195
  157. package/boilerplates/02-saas-starter/memory/10-product/vision.md +0 -63
  158. package/boilerplates/02-saas-starter/memory/20-architecture/overview.md +0 -232
  159. package/boilerplates/02-saas-starter/memory/30-domains/auth/api.md +0 -186
  160. package/boilerplates/02-saas-starter/memory/30-domains/auth/context.md +0 -85
  161. package/boilerplates/02-saas-starter/memory/30-domains/billing/api.md +0 -262
  162. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/api.md +0 -176
  163. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/context.md +0 -100
  164. package/boilerplates/02-saas-starter/memory/40-delivery/backlog.md +0 -81
  165. package/boilerplates/02-saas-starter/memory/40-delivery/roadmap.md +0 -97
  166. package/boilerplates/02-saas-starter/memory/40-delivery/sprint-atual.md +0 -57
  167. package/boilerplates/02-saas-starter/memory/50-orchestration/topology.md +0 -90
  168. package/boilerplates/02-saas-starter/memory/60-runs/index.md +0 -54
  169. package/boilerplates/02-saas-starter/memory/70-summaries/global.md +0 -50
  170. package/boilerplates/02-saas-starter/memory/80-data/schema.md +0 -185
  171. package/boilerplates/02-saas-starter/memory/90-decisions/adr-template.md +0 -75
@@ -0,0 +1,143 @@
1
+ ---
2
+ name: commit-message
3
+ description: Use quando fazer commit de mudanças ou escrever uma mensagem de commit: lê o diff em stage, o nome do branch e o histórico do repositório, escreve uma mensagem no padrão Conventional Commits com tipo, escopo e assunto no imperativo, e faz o commit só depois da aprovação.
4
+ ---
5
+
6
+ # Mensagem de Commit
7
+
8
+ Uma mensagem de commit explica **por que** uma mudança existe. O diff já mostra **o que** mudou. Um bom histórico permite a qualquer pessoa descobrir quando e por que um comportamento apareceu, e permite que ferramentas gerem changelogs e versões a partir dele.
9
+
10
+ A saída padrão é uma **mensagem proposta**. Rode `git commit` só depois que o usuário aprovar.
11
+
12
+ ## Convenções
13
+
14
+ - Formato: [Conventional Commits](https://www.conventionalcommits.org/).
15
+ - Idioma: o usado no histórico recente (`git log`). Inglês quando não houver histórico.
16
+ - As regras do repositório prevalecem sobre esta skill: `commitlint.config.*`, `.gitmessage`, `.czrc`, `CONTRIBUTING.md`, ou um padrão claro no `git log`.
17
+
18
+ ## Reúna o contexto
19
+
20
+ Somente leitura, antes de redigir:
21
+
22
+ 1. `git status` e `git diff --staged`. Se nada estiver em stage, mostre o `git diff` e pergunte o que colocar em stage. Nunca rode `git add -A` por conta própria.
23
+ 2. `git branch --show-current`: a finalidade do branch.
24
+ 3. `git log --oneline -20`: idioma, tipos e escopos já usados, e se o repositório segue Conventional Commits.
25
+ 4. `git log <base>..HEAD --oneline` (a base costuma ser `main`): o que o branch já contém, para o commit novo se encaixar na história.
26
+ 5. Os arquivos de configuração do repositório listados em Convenções, se existirem.
27
+
28
+ ## Finalidade do branch → sugestão de tipo
29
+
30
+ | Prefixo do branch | Tipo padrão |
31
+ |---|---|
32
+ | `feat/`, `feature/` | `feat` |
33
+ | `fix/`, `bugfix/` | `fix` |
34
+ | `hotfix/` | `fix` (diga no corpo o que estava quebrado em produção) |
35
+ | `refactor/` | `refactor` |
36
+ | `docs/` | `docs` |
37
+ | `test/` | `test` |
38
+ | `perf/`, `build/`, `ci/`, `chore/` | o mesmo do prefixo |
39
+ | `release/` | `chore(release)` |
40
+
41
+ O branch é uma **sugestão**; o diff manda. Um commit que só acrescenta testes em `feat/login` é `test`, não `feat`.
42
+
43
+ Um ID de ticket no nome do branch (`feat/ABC-123-login`) vai no rodapé como `Refs: ABC-123`. Nunca invente um.
44
+
45
+ ## Tipos
46
+
47
+ | Tipo | Use quando |
48
+ |---|---|
49
+ | `feat` | Adiciona uma capacidade que o usuário ou quem chama consegue observar. |
50
+ | `fix` | Corrige um bug observável. |
51
+ | `refactor` | Muda a estrutura sem mudar o comportamento. |
52
+ | `perf` | Mesmo comportamento, mensuravelmente mais rápido ou mais leve. |
53
+ | `docs` | Só documentação. |
54
+ | `test` | Só adiciona ou corrige testes. |
55
+ | `build` | Sistema de build, dependências, empacotamento. |
56
+ | `ci` | Pipelines de CI e seus scripts. |
57
+ | `style` | Só formatação, sem mudar o significado do código. |
58
+ | `chore` | Manutenção que não se encaixa em nada acima. |
59
+ | `revert` | Reverte um commit anterior; referencie o hash dele no corpo. |
60
+
61
+ Quando dois tipos servirem, escolha o que descreve o efeito visível ao usuário: uma correção que exigiu uma refatoração é `fix`.
62
+
63
+ ## Escopo
64
+
65
+ - O módulo, pacote ou pasta predominante na mudança (`auth`, `api`, `quality`).
66
+ - Reutilize escopos que já existem no histórico antes de criar um novo.
67
+ - Omita o escopo quando a mudança abranger o repositório inteiro. Nunca invente um só para preencher.
68
+
69
+ ## Formato
70
+
71
+ ```
72
+ <tipo>(<escopo>)!: <assunto>
73
+
74
+ <corpo>
75
+
76
+ BREAKING CHANGE: <o que quebra e como migrar>
77
+ Refs: <ticket>
78
+ ```
79
+
80
+ - **Assunto**: no imperativo, ≤ 50 caracteres (limite rígido de 72), minúsculo depois dos dois-pontos, a menos que o histórico diga outra coisa, sem ponto final. Teste: "Se aplicado, este commit vai *<assunto>*".
81
+ - **Corpo**: só quando o porquê não fica óbvio pelo assunto. Motivação, trade-offs, efeitos colaterais. Quebre em 72 colunas. Não é uma lista de arquivos.
82
+ - **Mudança incompatível**: `!` depois do tipo/escopo **e** um rodapé `BREAKING CHANGE:`, para qualquer quebra em API, contrato, esquema, configuração ou CLI.
83
+ - **Trailers**: mantenha os que o repositório ou a ferramenta exigem (`Co-Authored-By`, `Signed-off-by`).
84
+
85
+ ## Commits atômicos
86
+
87
+ Um commit, um motivo para mudar. Sinais de que o diff em stage deveria ser dividido:
88
+
89
+ - escopos não relacionados no mesmo diff;
90
+ - uma funcionalidade misturada com uma refatoração ou com formatação;
91
+ - o assunto precisa de "e" para ser honesto.
92
+
93
+ Proponha os grupos, cada um com sua mensagem e o comando para colocá-lo em stage (`git add <caminhos>`, ou `git add -p` para trechos no mesmo arquivo). O usuário decide; não coloque nada em stage por conta própria.
94
+
95
+ ## Fluxo
96
+
97
+ 1. Reúna o contexto.
98
+ 2. Classifique tipo e escopo; verifique se cabe uma divisão.
99
+ 3. Mostre a mensagem proposta (e a divisão, se houver).
100
+ 4. Com a aprovação, faça o commit com um heredoc para o corpo manter a formatação:
101
+ ```sh
102
+ git commit -F - <<'EOF'
103
+ <mensagem>
104
+ EOF
105
+ ```
106
+ 5. Mostre `git log -1 --stat`.
107
+
108
+ Nunca `--amend`, `--no-verify` ou push, a menos que peçam. Se um hook falhar, reporte, corrija a causa e crie um commit novo.
109
+
110
+ ## Próximo
111
+
112
+ `pull-request` descreve os commits do branch para revisão; `release-notes` os transforma numa versão e num changelog.
113
+
114
+ ## Exemplos
115
+
116
+ | Situação | Mensagem |
117
+ |---|---|
118
+ | `feat/ABC-42-export` adiciona exportação em CSV | `feat(reports): add CSV export` + rodapé `Refs: ABC-42` |
119
+ | `hotfix/login-timeout` | `fix(auth): renew session before token expiry` + corpo com o sintoma em produção |
120
+ | Skills movidas para pastas de categoria | `refactor: group skills into category folders` |
121
+ | Endpoint renomeado | `feat(api)!: rename /users to /accounts` + `BREAKING CHANGE: clients must call /accounts` |
122
+
123
+ Num repositório com histórico em português, as mesmas mensagens seriam, por exemplo, `feat(reports): adiciona exportação em CSV`.
124
+
125
+ Proposta de divisão, quando uma skill nova e uma movimentação de pastas estão em stage juntas:
126
+
127
+ ```
128
+ 1. git add design/ quality/ compliance/ requirements/
129
+ refactor: group skills into category folders
130
+ 2. git add git/commit-message/
131
+ feat(git): add commit-message skill
132
+ ```
133
+
134
+ ## Evite
135
+
136
+ - Passado ou terceira pessoa no assunto ("added", "adds", "adicionado").
137
+ - Assuntos vagos: "atualiza arquivos", "fixes", "wip", "mudanças".
138
+ - Listar arquivos no corpo.
139
+ - Misturar mudanças não relacionadas num commit.
140
+ - Inventar escopos ou IDs de ticket.
141
+ - Afirmar que os testes passam sem rodá-los.
142
+ - Fazer commit sem aprovação.
143
+ - Sobrepor as convenções do próprio repositório com os padrões desta skill.
@@ -0,0 +1,88 @@
1
+ ---
2
+ name: data-migrations
3
+ description: Use quando desenhar um esquema relacional ou alterá-lo em produção: mapeia agregados para tabelas, garante invariantes com constraints, deriva índices dos padrões de consulta e planeja migrações sem downtime com um rollback por passo.
4
+ ---
5
+
6
+ # Migrações de Dados
7
+
8
+ O esquema é a parte mais longeva de um sistema: o código é substituído, os dados ficam. Esta skill desenha o esquema a partir do modelo de domínio e planeja as mudanças para que a aplicação em execução nunca encontre um banco com que não consiga lidar.
9
+
10
+ A saída padrão é um **esquema e um plano de migração ordenado**. Escreva arquivos de migração só quando o usuário pedir, usando a ferramenta de migração do projeto.
11
+
12
+ ## Convenções
13
+
14
+ - Entradas: agregados, objetos de valor e invariantes de `domain-modeling`; padrões de consulta de `api-design`; retenção e classificação de `lgpd-compliance`.
15
+ - Siga o código existente: o banco, a ferramenta de migração (Prisma Migrate, Drizzle Kit, TypeORM, Knex, `node-pg-migrate`, Flyway…), o estilo de nomes e a organização dos arquivos. Nunca misture ferramentas.
16
+ - O dialeto padrão é PostgreSQL. Diga quando um recurso é específico do dialeto.
17
+ - Volumes de dados ou tráfego desconhecidos vão para **Perguntas em aberto**: eles decidem se um passo precisa de lotes.
18
+
19
+ ## Do modelo de domínio às tabelas
20
+
21
+ - **Agregado** → uma tabela raiz mais tabelas para as entidades internas, com chave estrangeira para a raiz e `ON DELETE CASCADE` só dentro do agregado. Um agregado é salvo numa transação.
22
+ - **Entre agregados**: referência por ID. Uma chave estrangeira serve dentro do mesmo banco; nunca faça cascata entre agregados.
23
+ - **Objeto de valor** → colunas na tabela do dono (`period_start`, `period_end`), ou uma coluna JSON só quando ele nunca é consultado pelas partes.
24
+ - **Invariantes** que o banco consegue garantir viram constraints: `NOT NULL`, `CHECK (period_end >= period_start)`, `UNIQUE`, chaves estrangeiras, exclusion constraints. O domínio também as verifica; a constraint é a última linha de defesa.
25
+ - **Concorrência otimista** (`ETag` em `api-design`) → uma coluna `version` incrementada a cada atualização.
26
+ - **Dinheiro**: `numeric(19,4)` mais uma coluna de moeda. **Tempo**: `timestamptz` em UTC.
27
+ - **Dados pessoais**: marque as colunas classificadas por `lgpd-compliance`; planeje como a retenção as exclui ou anonimiza.
28
+
29
+ ## Índices
30
+
31
+ - Derive dos padrões de consulta reais (cada lista, filtro e ordenação em `api-design`), não de palpites.
32
+ - Chaves primárias e constraints únicas já são indexadas. Chaves estrangeiras não são no PostgreSQL: indexe-as quando você faz join ou exclusão por elas.
33
+ - Ordem das colunas num índice composto: colunas de igualdade primeiro, depois as de intervalo/ordenação.
34
+ - Todo índice deixa as escritas mais lentas. Cada um nomeia a consulta que atende.
35
+
36
+ ## Mudanças sem downtime: expandir → migrar → contrair
37
+
38
+ As versões antiga e nova da aplicação rodam juntas durante um deploy. Todo passo precisa funcionar com as duas.
39
+
40
+ 1. **Expandir**: adicione o que o código novo precisa, de forma retrocompatível (coluna nova anulável, tabela nova, índice novo criado de forma concorrente).
41
+ 2. **Migrar**: implante código que escreve no antigo e no novo; preencha as linhas existentes em lotes; depois passe as leituras para a estrutura nova.
42
+ 3. **Contrair**: depois que o código antigo sumir, remova a coluna ou tabela antiga numa release posterior.
43
+
44
+ Receitas:
45
+
46
+ | Mudança | Sequência segura |
47
+ |---|---|
48
+ | Adicionar uma coluna obrigatória | Adicionar anulável (ou com default constante) → preencher → `CHECK (col IS NOT NULL) NOT VALID` → `VALIDATE` → `SET NOT NULL` (o PostgreSQL 12+ pula a varredura completa) |
49
+ | Renomear uma coluna | Adicionar a nova → escrita dupla → preencher → ler a nova → remover a antiga. Nunca `RENAME` com tráfego ativo. |
50
+ | Mudar um tipo | Igual ao renomear, com uma coluna convertida |
51
+ | Adicionar um índice | `CREATE INDEX CONCURRENTLY` (fora de uma transação) |
52
+ | Adicionar uma chave estrangeira | `NOT VALID`, depois `VALIDATE CONSTRAINT` |
53
+ | Remover uma coluna | Parar de ler → parar de escrever → remover numa release posterior |
54
+
55
+ - Os preenchimentos rodam em lotes de tamanho limitado, são idempotentes e retomáveis, e nunca rodam dentro da transação da migração de esquema.
56
+ - Defina `lock_timeout` nas migrações para que um `ALTER` bloqueado falhe rápido em vez de enfileirar todo o tráfego atrás dele.
57
+
58
+ ## Rollback
59
+
60
+ Cada passo declara o seu rollback. Passos de expansão se revertem removendo o que adicionaram. Passos de contração destroem dados: **não têm rollback** além de uma restauração, então só rodam depois que a versão nova estiver estável, e o plano diz isso.
61
+
62
+ ## Formato
63
+
64
+ ```
65
+ ## Esquema
66
+ <DDL ou lista de tabelas: colunas, tipos, constraints, índices (cada um com a consulta que atende)>
67
+
68
+ ## Plano de migração
69
+ | # | Release | Passo | Tipo (expandir/migrar/contrair) | Locks / risco de duração | Rollback |
70
+ |---|---|---|---|---|---|
71
+
72
+ ## Perguntas em aberto
73
+ ```
74
+
75
+ ## Próximo
76
+
77
+ - `testing`: os testes de integração rodam as migrações contra um banco real e testam as constraints que espelham invariantes.
78
+ - `architecture-decision-record` para escolhas de banco ou de ferramenta de migração.
79
+
80
+ ## Evite
81
+
82
+ - Uma migração que muda esquema e código no mesmo deploy de forma incompatível.
83
+ - Editar uma migração que já rodou em algum lugar. Escreva uma nova.
84
+ - Preencher milhões de linhas numa transação só.
85
+ - Floats para dinheiro; timestamps sem fuso horário.
86
+ - Índices sem uma consulta que precise deles.
87
+ - Exclusões em cascata entre agregados.
88
+ - Remover colunas na mesma release que deixa de usá-las.
@@ -0,0 +1,75 @@
1
+ ---
2
+ name: dependency-upgrade
3
+ description: Use quando atualizar dependências de um projeto (pacotes npm, runtime, frameworks): inventaria o que está desatualizado e vulnerável, separa atualizações compatíveis das incompatíveis, lê os changelogs, aplica um major por vez com os testes como gate, resolve conflitos de peer sem forçar, e registra o que ficou para trás e por quê.
4
+ ---
5
+
6
+ # Atualização de Dependências
7
+
8
+ Atualizar dependências é trocar código que você não escreveu por outro código que você não escreveu. Feito de uma vez, um erro no meio de vinte atualizações não tem culpado. Feito um major por vez, com os testes rodando entre cada um, toda quebra tem endereço.
9
+
10
+ A saída padrão é um **plano de atualização**. Instale e altere arquivos só quando o usuário pedir.
11
+
12
+ ## Convenções
13
+
14
+ - Entradas: `package.json`, o lockfile, `engines`, o CI e a suíte de testes (`testing`).
15
+ - O gerenciador de pacotes do projeto (npm, pnpm, yarn) e o lockfile dele. Nunca misture gerenciadores.
16
+ - Toda atualização incompatível tem o changelog ou o guia de migração lido antes, não depois de quebrar.
17
+
18
+ ## Inventarie
19
+
20
+ 1. `npm outdated` (ou `pnpm outdated`): atual, desejada (dentro do intervalo) e mais recente.
21
+ 2. `npm audit` (ou `osv-scanner`): vulnerabilidades, com severidade e se há correção.
22
+ 3. Para cada major disponível: o changelog ou guia de migração, e as dependências que exigem uma versão específica (peer dependencies).
23
+ 4. O runtime: a versão de Node em `engines`, no CI e nos ambientes; as versões que o framework exige.
24
+
25
+ ## Classifique
26
+
27
+ | Tipo | Exemplo | Como tratar |
28
+ |---|---|---|
29
+ | Patch/minor dentro do intervalo | `5.90.5 → 5.104.1` | Em lote, com a suíte completa |
30
+ | Correção de segurança | `npm audit fix` | Prioridade; sem `--force` |
31
+ | Major isolado | `typescript 6 → 7` | Um por vez: ler o guia, atualizar, corrigir, testar, commitar |
32
+ | Major em cadeia | framework que exige outro major (`@nestjs/* 11 → 12` junto com `rxjs`, `typeorm`) | Juntos, na ordem que o guia indicar, num commit |
33
+ | Mudança de paradigma | pacote que virou ESM-only, troca de executor de testes | Tratar como migração planejada, com spike se necessário (`technical-spike`) |
34
+
35
+ ## Aplique
36
+
37
+ 1. **Linha de base verde**: rode build, testes e lint antes de mexer. Uma suíte vermelha antes da atualização esconde o que a atualização quebrou.
38
+ 2. **Compatíveis em lote**: atualize os patches e minors, rode a suíte, commit.
39
+ 3. **Majors um a um**, cada um com o próprio commit: leia o guia, atualize, corrija o que o compilador e os testes apontarem, rode a suíte completa (inclusive os testes de integração e o build de produção).
40
+ 4. **Conflitos de peer**: entenda quem exige o quê (`npm ls <pacote>`, `npm explain <pacote>`). Prefira esperar a versão compatível, ou declarar um `overrides` explícito e comentado, a usar `--force` ou `--legacy-peer-deps`, que escondem o conflito.
41
+ 5. **Ferramentas que não acompanharam**: quando um ecossistema ainda não suporta o major novo (por exemplo, um executor de testes que exige o compilador anterior), fique na última versão suportada e registre o motivo e o gatilho para revisitar.
42
+ 6. **Scripts de instalação**: verifique se pacotes nativos ainda instalam onde scripts de instalação estão bloqueados (npm 11+), e se trazem binários prontos.
43
+ 7. **Teste o que o usuário roda**: além da suíte, o build de produção, a aplicação subindo e o fluxo principal funcionando. Para bibliotecas, instale o pacote empacotado num projeto limpo.
44
+
45
+ ## Formato
46
+
47
+ ```
48
+ ## Inventário
49
+ | Pacote | Atual | Alvo | Tipo | Notas (changelog, peer, segurança) |
50
+
51
+ ## Plano
52
+ | # | Passo | Pacotes | Verificação | Commit |
53
+
54
+ ## Ficou para trás
55
+ | Pacote | Versão mantida | Motivo | Gatilho para revisitar |
56
+ ```
57
+
58
+ ## Próximo
59
+
60
+ - `testing`: a suíte completa é o gate de cada passo.
61
+ - `commit-message`: um commit `build(deps)` por passo; `!` quando a atualização muda o contrato do projeto.
62
+ - `release-notes`: atualizações que os usuários percebem (runtime mínimo, comportamento) entram nas notas.
63
+
64
+ ## No Forja
65
+
66
+ No Forja, depois de cada passo rode também `forja tools:doctor` e `forja project:wire --check` (atualizações podem mudar o runtime que os hooks e o MCP usam). Uma mudança de paradigma (pacote que virou ESM-only, troca do executor de testes) vira ADR em `memory/90-decisions/`, e o que ficou para trás entra na seção "Evidências e estado real" da spec da atualização.
67
+
68
+ ## Evite
69
+
70
+ - Atualizar tudo de uma vez e depurar o resultado.
71
+ - `npm audit fix --force` ou `--legacy-peer-deps` para calar um conflito.
72
+ - Atualizar major sem ler o guia de migração.
73
+ - Partir de uma suíte que já estava vermelha.
74
+ - Considerar pronto porque o `npm install` terminou sem erro.
75
+ - Deixar uma dependência para trás sem registrar o motivo.
@@ -0,0 +1,85 @@
1
+ ---
2
+ name: docker-compose-review
3
+ description: Use quando escrever ou revisar arquivos do Docker Compose e Dockerfiles: verifica healthchecks e ordem de inicialização, redes e portas expostas, volumes, segredos, limites de recursos, higiene das imagens e paridade entre desenvolvimento e produção.
4
+ ---
5
+
6
+ # Revisão de Docker Compose
7
+
8
+ Arquivos Compose costumam começar como conveniência do desenvolvedor e, sem alarde, viram o mais próximo que existe de uma especificação de produção. A revisão verifica se os serviços sobem na ordem certa, expõem só o que devem, guardam os dados onde é seu lugar e se comportam em desenvolvimento como vão se comportar em produção.
9
+
10
+ A saída padrão é uma **tabela de achados e uma matriz de paridade**. Edite arquivos só quando o usuário pedir.
11
+
12
+ ## Convenções
13
+
14
+ - Escopo: `compose.yaml` / `docker-compose*.yml`, arquivos de override, os Dockerfiles que eles constroem, `.env.example`, e o que descreve a produção (manifests Kubernetes, um compose de produção, a documentação de deploy).
15
+ - Sintaxe da Compose Specification (sem `version:` no topo).
16
+ - Todo achado cita `arquivo:linha` e um motivo.
17
+ - Configuração de produção desconhecida vai para **Perguntas em aberto**; sem ela, a paridade não pode ser avaliada.
18
+
19
+ ## Checklist
20
+
21
+ **Inicialização e saúde**
22
+ - Cada serviço de longa duração tem um `healthcheck` que testa a prontidão (por exemplo, `pg_isready`, um `/healthz` HTTP), com `interval`, `timeout`, `retries` e `start_period`.
23
+ - `depends_on` usa `condition: service_healthy` (ou `service_completed_successfully` para jobs de migração). `depends_on` simples só ordena a subida, não espera.
24
+ - As migrações rodam como um serviço ou passo de execução única, não dentro do entrypoint da aplicação em toda réplica.
25
+ - A aplicação continua tentando reconectar: healthchecks não substituem resiliência.
26
+ - Política de `restart:` declarada.
27
+
28
+ **Redes e portas**
29
+ - Só os pontos de entrada publicam portas. Bancos e caches ficam em redes internas.
30
+ - Portas publicadas ligadas a `127.0.0.1` em desenvolvimento quando a exposição não é necessária.
31
+ - Redes separadas quando grupos de serviços não devem se falar.
32
+
33
+ **Volumes e dados**
34
+ - Volumes nomeados para dados (bancos); bind mounts só para código-fonte em desenvolvimento.
35
+ - Nenhum dado gravado na camada do container.
36
+ - Scripts de inicialização e dados de seed são idempotentes.
37
+
38
+ **Configuração e segredos**
39
+ - Configuração por ambiente, com `.env.example` documentando cada variável. O `.env` real fica fora do git.
40
+ - Segredos via `secrets:` ou o cofre de segredos da plataforma, nunca embutidos em imagens, `ARG`s ou arquivos versionados.
41
+ - Nada de credenciais de produção em arquivos de desenvolvimento.
42
+
43
+ **Imagens**
44
+ - Imagens base fixadas numa versão (e num digest em produção). Nada de `latest`.
45
+ - Builds multi-stage; imagem final mínima (distroless ou slim); para Node, só o build gerado e as dependências de produção (`npm ci --omit=dev`), nunca o toolchain de desenvolvimento nem source maps que você não distribui.
46
+ - Roda como um `USER` não root. Sistema de arquivos raiz somente leitura onde for possível.
47
+ - `.dockerignore` exclui `.git`, arquivos de ambiente locais e saídas de build.
48
+ - Ordem das camadas maximiza o cache: `package.json` + lockfile e o passo de instalação antes do código-fonte.
49
+
50
+ **Recursos**
51
+ - Limites de memória e CPU nos serviços que podem disparar. Rotação de logs configurada no driver de log.
52
+
53
+ ## Paridade dev/prod
54
+
55
+ A mesma imagem (construída uma vez) roda em todo lugar; só a configuração muda. Os acréscimos de desenvolvimento (hot reload, depuradores, bind mounts, painéis de administração) ficam em `compose.override.yaml` ou em profiles, não no arquivo base. Os serviços de apoio usam a mesma versão principal da produção (Postgres 16 localmente se a produção roda 16).
56
+
57
+ ## Formato
58
+
59
+ ```
60
+ ## Achados
61
+ | # | Arquivo:linha | Categoria | Severidade | Problema | Correção |
62
+ |---|---|---|---|---|---|
63
+
64
+ ## Matriz de paridade
65
+ | Serviço | Dev (imagem/versão, config) | Prod | Diferença | Risco |
66
+
67
+ ## Perguntas em aberto
68
+ ```
69
+
70
+ Severidade: Bloqueador (exposição de segredo, perda de dados, falha só em produção) · Maior · Menor · Detalhe.
71
+
72
+ ## Próximo
73
+
74
+ - `ci-pipeline-review` quando o CI constrói essas imagens ou sobe o stack.
75
+ - `release-checklist` para diferenças de configuração e versão antes de um deploy.
76
+ - `threat-modeling` para serviços expostos.
77
+
78
+ ## Evite
79
+
80
+ - Tags `latest`.
81
+ - Publicar portas de banco em `0.0.0.0`.
82
+ - Segredos em `environment:` versionados no repositório.
83
+ - `sleep` em entrypoints para esperar dependências.
84
+ - Rodar como root por padrão.
85
+ - Um stack de desenvolvimento em versões principais diferentes da produção.
@@ -0,0 +1,120 @@
1
+ ---
2
+ name: domain-modeling
3
+ description: Use quando modelar um domínio a partir de dados e funcionalidades propostos: sugere agregados, entidades e objetos de valor com propriedades tipadas, métodos derivados e invariantes.
4
+ ---
5
+
6
+ # Modelagem de Domínio
7
+
8
+ Transforma dados e funcionalidades propostos num modelo tático de domínio: agregados, entidades, objetos de valor, propriedades tipadas, comportamentos e regras de consistência.
9
+
10
+ A saída é uma **especificação do modelo**, não uma implementação. Não gere código além de assinaturas de tipos, a menos que o usuário peça.
11
+
12
+ ## Convenções
13
+
14
+ - Sempre escreva os termos de modelagem em pt-BR seguidos do en-US: Agregado (Aggregate), Raiz do Agregado (Aggregate Root), Entidade (Entity), Objeto de Valor (Value Object), Invariante (Invariant), Política (Policy), Evento de Domínio (Domain Event), Contexto Delimitado (Bounded Context), Linguagem Ubíqua (Ubiquitous Language).
15
+ - Nomeie tipos, propriedades e métodos na linguagem ubíqua do usuário (no idioma em que o domínio do usuário fala).
16
+ - Use os tipos da linguagem do código existente por padrão, a menos que o usuário indique outra linguagem. Os mapeamentos abaixo são para TypeScript.
17
+
18
+ ## Princípio central
19
+
20
+ Não dá para modelar o que você não entende. Uma regra de negócio errada não é salva por padrão nenhum. Antes de classificar qualquer coisa, entenda o domínio; o que não foi dito precisa ser marcado como **suposição** ou **pergunta**, nunca inventado como fato.
21
+
22
+ ## Processo
23
+
24
+ ### 1. Extrair a linguagem ubíqua
25
+ A partir dos dados e funcionalidades informados, liste os substantivos (candidatos a conceitos), os verbos (candidatos a comportamentos) e as regras explícitas ou implícitas. Identifique termos ambíguos (por exemplo, um "usuário" que é ao mesmo tempo credencial, cliente e funcionário) e separe-os.
26
+
27
+ ### 2. Delimitar contextos
28
+ Agrupe conceitos em Contextos Delimitados quando o mesmo termo carrega significados ou regras diferentes. Um contexto é uma fronteira de **modelo**, não de implantação: pode viver num monólito como pasta/módulo. Não proponha microsserviços por causa disso.
29
+ Quando o domínio ainda não estiver claro, rode `event-storming` antes. Para mapear como os contextos se relacionam (Kernel Compartilhado, Camada Anticorrupção, Cliente–Fornecedor…), use `bounded-context-mapping`.
30
+
31
+ ### 3. Classificar cada conceito
32
+
33
+ | Conceito | Critério |
34
+ |---|---|
35
+ | Entidade | Tem uma identidade que persiste através das mudanças; tem ciclo de vida. |
36
+ | Objeto de Valor | Definido só pelos seus atributos; imutável; igualdade por valor; carrega a própria validação e comportamento. |
37
+ | Agregado | Fronteira de consistência transacional. A raiz é o único ponto de entrada para mudanças. |
38
+
39
+ Heurísticas:
40
+ - Mantenha os agregados pequenos. Se duas coisas não precisam estar consistentes na mesma transação, são agregados separados.
41
+ - Agregados referenciam outros agregados **por ID**, nunca pelo objeto.
42
+ - Promova um primitivo a Objeto de Valor quando houver uma regra, formato ou comportamento associado (por exemplo, CPF/CNPJ, Email, Dinheiro, Período). Sem regra, mantenha o primitivo; não crie objetos de valor por ritual.
43
+ - Pares de campos que só fazem sentido juntos (início/fim, valor/moeda, latitude/longitude) são fortes candidatos a Objeto de Valor.
44
+
45
+ ### 4. Tipar as propriedades
46
+ Para cada propriedade, defina nome, tipo, se é obrigatória e sua origem (informada, derivada, gerada pelo sistema).
47
+
48
+ Mapeamentos padrão em TypeScript:
49
+ - Identificador: tipo com marca (branded) sobre `string` (por exemplo, `type ProjectId = string & { readonly __brand: 'ProjectId' }`), para que um `ProjectId` não seja aceito onde se espera um `CustomerId`.
50
+ - Data/hora: `Date` tratado como instante em UTC (ou `Temporal` onde o projeto já o usa); data sem horário, quando relevante, como objeto de valor próprio.
51
+ - Duração: objeto de valor ou número em milissegundos com a unidade no nome (`durationMs`).
52
+ - Dinheiro: objeto de valor `Money` com o valor em unidades menores (centavos) como `bigint` ou inteiro seguro, mais a moeda. Nunca número de ponto flutuante.
53
+ - Enumerações/estados: união de literais de string (`'open' | 'closed'`), ou o padrão que o código já usa.
54
+ - Opcional: `?`/`undefined` só quando a ausência tem significado no domínio.
55
+
56
+ ### 5. Definir comportamentos
57
+ - **Métodos derivados**: calculados a partir das propriedades, nunca armazenados (por exemplo, `Period.durationMs(): number` = fim − início; `Period.contains(at: Date): boolean`).
58
+ - **Comportamentos de domínio**: verbos da linguagem ubíqua que mudam o estado (por exemplo, `Project.close(at: Date): Result<void, ProjectError>`, ou lançando um erro de domínio tipado, conforme o padrão do código), em vez de setters genéricos. Evite modelos anêmicos.
59
+ - Transições de estado: descreva a máquina de estados sempre que houver um status.
60
+
61
+ ### 6. Definir invariantes
62
+ Para cada regra de consistência, enuncie:
63
+ - a regra em linguagem de negócio;
64
+ - onde ela é garantida (construtor do Objeto de Valor, método da Raiz do Agregado);
65
+ - quando é verificada (na criação, numa transição específica, sempre).
66
+
67
+ Exemplo: "O fim não pode ser antes do início" → garantida na criação de `Period`; um `Period` inválido não pode existir.
68
+
69
+ Prefira tornar os estados inválidos irrepresentáveis com Objetos de Valor a espalhar validações.
70
+
71
+ ### 7. Extrair políticas
72
+ Regras de negócio que variam, são configuráveis ou tendem a mudar (percentuais, limites, critérios de elegibilidade) viram uma Política explícita e nomeada, em vez de condicionais enterradas nos métodos. Quem procurar "onde esse limite está definido" deve encontrá-lo pelo nome.
73
+
74
+ ### 8. Eventos de domínio (opcional)
75
+ Sugira Eventos de Domínio só quando outra parte do sistema precisar reagir a um fato. Nomeie-os no passado (`ProjectClosed`). Não proponha Event Sourcing ou CQRS sem uma necessidade concreta.
76
+
77
+ ## Formato de saída
78
+
79
+ ```
80
+ ## Contexto: <Nome>
81
+
82
+ ### Agregado: <Nome> (raiz: <Entidade>)
83
+ Responsabilidade: <uma frase>
84
+
85
+ **Propriedades**
86
+ | Propriedade | Tipo | Obrigatória | Origem | Notas |
87
+
88
+ **Métodos derivados**
89
+ - `nome(): Tipo` — <cálculo>
90
+
91
+ **Comportamentos**
92
+ - `verbo(params): Result<…>` — <efeito e transição>
93
+
94
+ **Invariantes**
95
+ - <regra> — garantida em <onde>, verificada <quando>
96
+
97
+ #### Entidades internas / Objetos de Valor
98
+ <mesma estrutura, enxuta>
99
+
100
+ ### Políticas
101
+ - <Nome>: <regra, parâmetros>
102
+
103
+ ### Suposições e perguntas em aberto
104
+ - <o que foi suposto e precisa ser validado com o negócio>
105
+ ```
106
+
107
+ Sempre feche com **Suposições e perguntas em aberto**. Elas fazem parte do modelo, não são um apêndice: mostram onde ainda falta conhecimento do domínio.
108
+
109
+ ## No Forja
110
+
111
+ No Forja, o modelo de cada contexto fica em `memory/30-domains/<contexto>/context.md` (agregados, invariantes, políticas e o mapa de onde cada um vive no código). Depois de gravar, rode `forja sync:universal`; `forja memory:audit` verifica se o mapa aponta para código que existe.
112
+
113
+ ## Evite
114
+
115
+ - Inventar regras de negócio e apresentá-las como fato.
116
+ - Um agregado gigante que guarda tudo.
117
+ - Um Objeto de Valor para cada primitivo, sem regra que o justifique.
118
+ - Setters genéricos em vez de comportamentos nomeados.
119
+ - Padrões aplicados por obrigação. Saber onde usá-los importa mais do que saber como.
120
+ - Gerar uma implementação completa sem que peçam.
@@ -0,0 +1,95 @@
1
+ ---
2
+ name: event-storming
3
+ description: Use quando um domínio ainda não está claro antes de modelá-lo: conduz uma sessão de Event Storming com o usuário como especialista do domínio, descobrindo eventos de domínio, comandos, atores, políticas, modelos de leitura e pontos críticos, e propõe agregados e fronteiras de contexto candidatos.
4
+ ---
5
+
6
+ # Event Storming
7
+
8
+ Descobre como um negócio funciona contando a sua história como uma sequência de fatos que aconteceram. Eventos são mais fáceis de enunciar para os especialistas do domínio do que entidades ou tabelas, e as lacunas entre eles revelam as regras que ninguém escreveu.
9
+
10
+ O usuário é o especialista do domínio. Pergunte, não suponha. A saída é uma **linha do tempo de eventos estruturada**, não um modelo; os agregados vêm por último e são só candidatos.
11
+
12
+ ## Convenções
13
+
14
+ - Termos de modelagem em pt-BR seguidos do en-US, como em `domain-modeling`: Evento de Domínio (Domain Event), Comando (Command), Ator (Actor), Política (Policy), Modelo de Leitura (Read Model), Sistema Externo (External System), Ponto Crítico (Hotspot), Agregado (Aggregate).
15
+ - Nomes na linguagem ubíqua do usuário. Eventos no passado ("Pedido Confirmado", "Order Confirmed"); comandos no imperativo ("Confirmar Pedido", "Confirm Order").
16
+ - Entradas: achados brutos de `requirements-elicitation`, documentos ou as próprias palavras do usuário.
17
+ - Tudo o que o usuário não confirmou é um **ponto crítico**, nunca um fato.
18
+
19
+ ## Níveis
20
+
21
+ | Nível | Pergunta | Use quando |
22
+ |---|---|---|
23
+ | Visão geral (big picture) | O que acontece no fluxo inteiro do negócio? | Iniciar um produto ou uma área grande; encontrar fronteiras de contexto |
24
+ | Processo | Como este processo funciona, regra a regra? | Desenhar uma funcionalidade ou um caso de uso |
25
+ | Design | Qual agregado aceita cada comando e garante qual regra? | Logo antes de `domain-modeling` |
26
+
27
+ Diga qual nível você está conduzindo. Não pule para o nível de design antes de a linha do tempo estar estável.
28
+
29
+ ## Processo
30
+
31
+ Conduza em rodadas de perguntas com o usuário. Mostre a linha do tempo após cada rodada.
32
+
33
+ ### 1. Exploração caótica
34
+ Peça todos os eventos que o usuário conseguir lembrar no escopo, em qualquer ordem. Estimule com: "O que acontece antes disso?", "O que acontece depois?", "O que pode dar errado?", "O que acontece no fim do dia / do mês?". Colete, não julgue.
35
+
36
+ ### 2. Impor a linha do tempo
37
+ Ordene os eventos no tempo. Funda duplicados; separe eventos que escondem dois fatos. Marque os eventos pivô, onde o fluxo muda de fase ou de dono (por exemplo, "Pagamento Capturado"). Eles costumam marcar fronteiras de contexto.
38
+
39
+ ### 3. Comandos e atores
40
+ Para cada evento: quem ou o que o causou? Um comando emitido por um **ator** (pessoa/papel), um **sistema externo**, uma **política** ou o tempo ("Fim do Mês Atingido").
41
+
42
+ ### 4. Políticas
43
+ Reações que ligam eventos a comandos: "Sempre que <evento>, então <comando>". Pergunte se cada uma é automática, manual ou condicional. As políticas são onde moram as regras de negócio escondidas.
44
+
45
+ ### 5. Modelos de leitura
46
+ De que informação o ator precisa para decidir emitir o comando? Esses são os modelos de leitura (telas, relatórios, consultas).
47
+
48
+ ### 6. Pontos críticos
49
+ Marque cada conflito, incógnita, discordância, exceção ou dor. Cada um vira uma pergunta para o usuário ou um candidato a `RN-NN` para `requirements-gathering`.
50
+
51
+ ### 7. Agregados e fronteiras candidatos (só no nível de design)
52
+ Agrupe comandos e eventos em torno da coisa que precisa estar consistente para aceitar o comando. Essa coisa é um agregado candidato. Agrupe a linha do tempo em áreas onde a linguagem e a propriedade permanecem as mesmas. Esses são os contextos delimitados candidatos.
53
+
54
+ ## Formato
55
+
56
+ ```
57
+ ## Escopo e nível
58
+ <processo ou área> — <visão geral | processo | design>
59
+
60
+ ## Linha do tempo
61
+ | # | Evento | Disparado por (comando) | Ator / sistema / política / tempo | Modelo de leitura necessário | Notas |
62
+ |---|---|---|---|---|---|
63
+
64
+ ## Políticas
65
+ - Sempre que <evento>, então <comando> (<automática | manual | condicional: …>)
66
+
67
+ ## Pontos críticos
68
+ | # | Onde | Pergunta / conflito | Quem responde |
69
+
70
+ ## Agregados candidatos (nível de design)
71
+ | Agregado | Comandos aceitos | Eventos emitidos | Regras que protege |
72
+
73
+ ## Contextos candidatos
74
+ <eventos pivô e mudanças de linguagem que sugerem fronteiras>
75
+ ```
76
+
77
+ Um `flowchart LR` em Mermaid da linha do tempo é opcional, para fluxos com muitas ramificações.
78
+
79
+ ## Próximo
80
+
81
+ - `bounded-context-mapping` com os contextos candidatos.
82
+ - `domain-modeling` com os agregados, regras e eventos candidatos.
83
+ - `requirements-gathering` com os pontos críticos e as políticas como regras a confirmar.
84
+
85
+ ## No Forja
86
+
87
+ No Forja, grave a linha do tempo e os pontos críticos em `memory/30-domains/<contexto>/event-storming.md` e rode `forja sync:universal`. Os pontos críticos viram perguntas na spec (`specs/<slug>/spec.md`, §7) até serem respondidos.
88
+
89
+ ## Evite
90
+
91
+ - Começar por entidades ou tabelas.
92
+ - Eventos no presente ou como CRUD ("Pedido Atualizado"). Pergunte o que de fato aconteceu.
93
+ - Preencher lacunas com regras plausíveis. Marque um ponto crítico.
94
+ - Desenhar agregados antes de a linha do tempo estar acordada.
95
+ - Eventos técnicos ("Linha Inserida", "Mensagem Enviada ao Kafka") nos níveis de visão geral ou de processo.