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,14 @@
1
+ # Skills do projeto
2
+
3
+ Instaladas pelo `forja project:wire` em `.claude/skills/` (Claude Code) e `.agents/skills/` (Codex).
4
+ Cada pasta tem um `SKILL.md` com frontmatter (`name`, `description`); o `name` é igual ao nome da pasta.
5
+
6
+ ## Origem
7
+
8
+ As skills de produto, requisitos, design, qualidade, TypeScript, segurança, operações, entrega, IA,
9
+ compliance, comunicação e git vêm do skill ledger de Allan Pablo (`allus-co/my-skill-ledger`),
10
+ traduzidas para pt-BR, com a trilha de Go convertida para TypeScript e publicadas no Forja sob a licença
11
+ MIT com autorização do autor. As seções "No Forja" são a integração com o processo do Forja.
12
+ `llm-provider-routing` é do próprio Forja.
13
+
14
+ Para atualizar a partir do ledger: copie as skills e reaplique as seções "No Forja" (ADR-0089).
@@ -0,0 +1,89 @@
1
+ ---
2
+ name: accessibility-review
3
+ description: Use quando criar ou revisar telas, componentes ou fluxos de interface: verifica a conformidade com a WCAG 2.2 nível AA (teclado, foco, semântica, nomes acessíveis, contraste, formulários, movimento) com ferramentas automáticas e testes manuais, e reporta os achados por severidade.
4
+ ---
5
+
6
+ # Revisão de Acessibilidade
7
+
8
+ Acessibilidade é se uma pessoa consegue concluir a tarefa: com teclado, com leitor de tela, com zoom, com pouca visão de cor. Ferramentas automáticas encontram só parte dos problemas; o resto aparece navegando de verdade.
9
+
10
+ A saída padrão é uma **tabela de achados ligados aos critérios da WCAG 2.2**. Edite código só quando o usuário pedir.
11
+
12
+ ## Convenções
13
+
14
+ - Alvo: WCAG 2.2 nível AA, a menos que o projeto declare outro. No Brasil, a Lei Brasileira de Inclusão (Lei nº 13.146/2015) e o eMAG se aplicam a serviços públicos; sinalize quando for o caso.
15
+ - Escopo: as telas ou componentes que o usuário nomear, ou o diff.
16
+ - Todo achado cita o critério (por exemplo, `2.4.7 Foco Visível`), onde ocorre e como reproduzir.
17
+ - Componentes do design system: um achado no componente vale para todas as telas que o usam; corrija na origem.
18
+
19
+ ## Verifique
20
+
21
+ **Automático** (encontra o óbvio, não aprova nada sozinho):
22
+ - `axe` no navegador ou nos testes (`@axe-core/playwright`, `vitest-axe`), e o Lighthouse de acessibilidade.
23
+ - Lint de JSX (`eslint-plugin-jsx-a11y` ou as regras equivalentes do oxlint/biome).
24
+
25
+ **Manual** (obrigatório):
26
+ 1. **Só teclado**: percorra a tarefa inteira com Tab, Shift+Tab, Enter, Espaço, Esc e setas. Tudo alcançável, na ordem visual, sem armadilhas de foco.
27
+ 2. **Foco visível** em todo elemento interativo; o foco nunca fica escondido atrás de cabeçalhos fixos (`2.4.11`).
28
+ 3. **Leitor de tela** (NVDA ou VoiceOver): títulos, regiões, nomes de botões e links, mensagens de erro e de status anunciados.
29
+ 4. **Zoom a 200% e largura de 320 px**: nada some, nada exige rolagem horizontal (`1.4.10`).
30
+ 5. **Contraste**: texto 4,5:1 (texto grande 3:1); componentes e ícones informativos 3:1 (`1.4.3`, `1.4.11`).
31
+ 6. **Movimento**: animações respeitam `prefers-reduced-motion`; nada pisca mais de 3 vezes por segundo.
32
+
33
+ ## Checklist
34
+
35
+ **Semântica e estrutura**
36
+ - Um `h1` por página e títulos em ordem; regiões (`header`, `nav`, `main`, `footer`).
37
+ - Elementos nativos antes de ARIA: `button` para ações, `a` para navegação. ARIA só quando não houver elemento nativo, e completo (papel, estado, propriedades).
38
+ - `lang` da página definido.
39
+
40
+ **Nomes e textos**
41
+ - Todo controle tem um nome acessível; ícones sem texto têm `aria-label`.
42
+ - Imagens informativas com `alt` que descreve a função; decorativas com `alt=""`.
43
+ - Links com texto que faz sentido fora do contexto ("Baixar a fatura de março", não "clique aqui").
44
+
45
+ **Formulários**
46
+ - Cada campo com `label` associado; obrigatoriedade indicada além da cor.
47
+ - Erros identificados no campo, descritos em texto e anunciados (`aria-describedby`, região de status).
48
+ - Não exigir digitar de novo o que já foi informado (`3.3.7`); autenticação sem teste cognitivo (`3.3.8`).
49
+
50
+ **Interação**
51
+ - Alvos de toque com pelo menos 24×24 px (`2.5.8`).
52
+ - Ações de arrastar têm alternativa de clique (`2.5.7`).
53
+ - Diálogos prendem o foco enquanto abertos e devolvem o foco ao fechar; Esc fecha.
54
+ - Conteúdo que aparece no hover ou foco pode ser dispensado e não some sob o ponteiro (`1.4.13`).
55
+
56
+ **Conteúdo dinâmico**
57
+ - Mudanças de rota anunciadas e com o foco movido para o conteúdo novo.
58
+ - Mensagens de status (salvo, erro, carregando) em `role="status"` ou `aria-live`.
59
+ - Tempo limite avisado e extensível.
60
+
61
+ ## Severidade
62
+
63
+ Bloqueador (impede concluir a tarefa: armadilha de teclado, controle sem nome, formulário sem rótulo) · Maior (dificulta muito: contraste insuficiente, foco invisível) · Menor · Detalhe.
64
+
65
+ ## Formato
66
+
67
+ ```
68
+ ## Escopo e método
69
+ <telas, ferramentas rodadas, leitor de tela e navegador usados>
70
+
71
+ ## Achados
72
+ | # | Onde | Critério WCAG | Severidade | Problema | Como reproduzir | Correção |
73
+ |---|---|---|---|---|---|---|
74
+
75
+ ## O que foi verificado sem achados
76
+ ```
77
+
78
+ ## Próximo
79
+
80
+ - `testing`: um teste automático (axe) por tela e um caso de teclado para cada fluxo crítico.
81
+ - `frontend-architecture` quando o problema vem de um componente compartilhado.
82
+
83
+ ## Evite
84
+
85
+ - Aprovar uma tela só porque o axe não acusou nada.
86
+ - ARIA em cima de `div` clicável em vez de um `button`.
87
+ - `outline: none` sem um estilo de foco no lugar.
88
+ - Indicar erro ou obrigatoriedade só pela cor.
89
+ - Corrigir tela a tela o que é defeito de um componente compartilhado.
@@ -0,0 +1,77 @@
1
+ ---
2
+ name: api-design
3
+ description: Use quando desenhar ou revisar uma API HTTP: deriva recursos do modelo de domínio, define métodos, códigos de status, modelo de erro, paginação, idempotência, versionamento e autorização por endpoint, e rascunha um contrato OpenAPI.
4
+ ---
5
+
6
+ # Design de API
7
+
8
+ Uma API é um contrato que sobrevive à sua primeira implementação. Os clientes vão depender de cada campo, código de status e erro que você expuser, então o momento mais barato de acertá-los é antes de o primeiro cliente existir.
9
+
10
+ A saída padrão é uma **especificação de endpoints e um esqueleto OpenAPI 3.1**. Escreva código de handler só quando o usuário pedir.
11
+
12
+ ## Convenções
13
+
14
+ - Entradas: agregados, invariantes e eventos de domínio de `domain-modeling`; `RF-NN` / `RNF-NN` de `requirements-gathering`; classificação de dados de `lgpd-compliance`.
15
+ - Nomes de recursos e campos na linguagem ubíqua, como no modelo de domínio. Escolha um estilo para os campos JSON (`camelCase` ou `snake_case`) e use-o em todo lugar.
16
+ - Siga o código existente: o estilo, o formato de erro e o versionamento de uma API que já existe prevalecem sobre os padrões desta skill. Quando a API for gRPC ou GraphQL, aplique as mesmas regras nos idiomas desse protocolo.
17
+ - Incógnitas vão para **Perguntas em aberto**. Não invente consumidores, limites ou SLAs.
18
+
19
+ ## Do modelo de domínio aos recursos
20
+
21
+ - **Raiz do agregado** → recurso de coleção + item (`/orders`, `/orders/{orderId}`). Entidades dentro de um agregado são alcançadas pela raiz (`/orders/{orderId}/items`), nunca como recursos independentes de primeiro nível.
22
+ - **Objetos de valor** → objetos JSON aninhados, validados como um todo (`period: {start, end}`), nunca divididos em campos soltos.
23
+ - **Comportamento / transição de estado** que não é simples edição de campo → um sub-recurso de ação (`POST /orders/{orderId}/cancel`), não `PATCH status`. As invariantes da transição ficam no servidor.
24
+ - **Evento de domínio** → webhook ou payload de evento, quando um consumidor precisa reagir.
25
+ - **Violação de invariante** → `409` ou `422` com um tipo de erro específico, nunca `500`.
26
+ - **Modelos de leitura** que cruzam agregados → endpoints de consulta separados, somente leitura.
27
+
28
+ ## Regras
29
+
30
+ - **Métodos**: `GET` seguro; `PUT` e `DELETE` idempotentes; `POST` cria ou executa uma ação; `PATCH` atualização parcial (JSON Merge Patch, a menos que o código use outro formato).
31
+ - **Códigos de status**: `200`, `201` + `Location`, `202` para trabalho assíncrono, `204`; `400` malformado, `401` não autenticado, `403` proibido, `404`, `409` conflito de estado, `412` pré-condição falhou, `422` violação de regra, `429` limite de taxa. `5xx` só para falhas do servidor.
32
+ - **Erros**: [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) `application/problem+json` com uma URI `type` estável por tipo de erro, mais `errors[]` com ponteiros de campo para validação. Os clientes decidem pelo `type`, nunca pelo `detail`.
33
+ - **Paginação**: baseada em cursor para listas que crescem (`?limit=&cursor=`, resposta com `nextCursor`); offset só para listas pequenas e estáveis. Sempre um `limit` máximo.
34
+ - **Filtros e ordenação**: só campos explicitamente permitidos (`?status=open&sort=-createdAt`).
35
+ - **Idempotência**: `POST` que cria ou cobra aceita `Idempotency-Key`; o servidor guarda a primeira resposta por chave durante uma janela declarada.
36
+ - **Concorrência**: `ETag` + `If-Match` em atualizações de agregados editados por vários atores; `412` quando não bater.
37
+ - **Tempo e dinheiro**: timestamps em RFC 3339 UTC; dinheiro como `{amount: "10.50", currency: "BRL"}` com string decimal, nunca float.
38
+ - **IDs**: strings opacas. Nunca exponha IDs sequenciais do banco quando eles revelam volume ou permitem enumeração.
39
+ - **Versionamento**: mudanças aditivas não precisam de versão nova. Mudanças incompatíveis (remover ou renomear campos, mudar tipos ou significado, nova entrada obrigatória) precisam de uma nova versão principal (`/v2` ou um header, seguindo o código) e de uma janela de descontinuação com os headers `Deprecation` e `Sunset`.
40
+ - **Autorização**: declare, por endpoint, quem pode chamá-lo e quais recursos pode ver. Verificações no nível do objeto (este usuário, este pedido) são obrigatórias, não só verificações de papel.
41
+ - **Dados pessoais**: marque os campos classificados por `lgpd-compliance`. Nunca os coloque em URLs ou query strings (eles acabam nos logs). Devolva só o que a finalidade exige.
42
+ - **Limites**: tamanho de requisição, tamanho de página e limites de taxa declarados explicitamente.
43
+
44
+ ## Especificação de endpoint
45
+
46
+ ```
47
+ ### <MÉTODO> <caminho> — <finalidade na linguagem ubíqua>
48
+ Cobre: RF-NN, RN-NN
49
+ Auth: <quem pode chamar; regra no nível do objeto>
50
+ Requisição: <corpo / parâmetros, com campos obrigatórios e validação>
51
+ Respostas:
52
+ - 2xx: <formato>
53
+ - 4xx: <status> <tipo de problem> — <quando>
54
+ Idempotência / concorrência: <chave, ETag, ou nenhuma>
55
+ Dados pessoais: <campos e classificação, ou nenhum>
56
+ ```
57
+
58
+ Depois, o esqueleto OpenAPI 3.1: `paths`, `components.schemas` para cada recurso e objeto de valor, `components.responses` para os tipos de problem compartilhados, e `securitySchemes`.
59
+
60
+ Feche com **Verificação de mudanças incompatíveis** (ao alterar uma API existente: cada mudança classificada como aditiva ou incompatível) e **Perguntas em aberto**.
61
+
62
+ ## Próximo
63
+
64
+ - `data-migrations` para o armazenamento por trás dos recursos.
65
+ - `threat-modeling` usa os endpoints e as fronteiras de confiança.
66
+ - `testing` transforma cada caso de resposta em testes de handler.
67
+ - `architecture-decision-record` para escolhas como esquema de versionamento ou REST vs. gRPC.
68
+
69
+ ## Evite
70
+
71
+ - Um endpoint por tabela do banco, ou expor o esquema de armazenamento como API.
72
+ - Verbos nos caminhos de recurso para CRUD (`/getOrders`, `/createOrder`).
73
+ - `200` com um erro no corpo.
74
+ - Booleanos que vão virar estados (`isCancelled` → `status`).
75
+ - Vazar stack traces, SQL ou IDs internos nos erros.
76
+ - Mudanças incompatíveis sem versão nova e janela de descontinuação.
77
+ - Desenhar para clientes hipotéticos. Desenhe para os requisitos declarados.
@@ -0,0 +1,92 @@
1
+ ---
2
+ name: architecture-decision-record
3
+ description: Use quando uma decisão técnica precisa ser registrada ou revisitada: escreve um Registro de Decisão de Arquitetura curto, com contexto, decisão, alternativas, consequências e reversibilidade.
4
+ ---
5
+
6
+ # Registro de Decisão de Arquitetura (ADR)
7
+
8
+ Registra uma decisão técnica relevante e, acima de tudo, **por que** ela foi tomada, para que qualquer pessoa (inclusive o autor, meses depois) consiga entendê-la sem reconstruir a discussão.
9
+
10
+ Um ADR é curto. Se precisa de mais de uma página, provavelmente é mais de uma decisão.
11
+
12
+ ## Quando escrever
13
+
14
+ Escreva um ADR quando a decisão:
15
+ - for cara de reverter (banco de dados, linguagem, framework, modelo de implantação, fronteiras do modelo de dados);
16
+ - afetar mais de um módulo, contexto ou time;
17
+ - não for óbvia, a ponto de alguém depois perguntar "por que fizemos assim?";
18
+ - for o resultado de uma prova de conceito (spike).
19
+
20
+ Não escreva ADRs para escolhas rotineiras que qualquer pessoa do time faria do mesmo jeito.
21
+
22
+ ## Regras
23
+
24
+ - **Uma decisão por ADR.**
25
+ - **Imutável depois de aceito.** Não edite a decisão; escreva um ADR novo que o substitua e atualize só o status do antigo.
26
+ - **Escrito no repositório**, junto ao código, numerado em sequência e nunca renumerado. Use a pasta que o projeto já usa (`docs/adr/NNNN-slug-curto.md` quando não houver uma).
27
+ - **O contexto enuncia forças, não opiniões**: requisitos, restrições, prazos, habilidades do time, evidência de spikes ou de produção.
28
+ - **As alternativas são reais.** Cada uma traz o motivo de ter perdido. Uma decisão sem alternativas consideradas é um anúncio, não uma decisão.
29
+ - **As consequências incluem as ruins.** Toda decisão tem custos; nomeá-los é o que torna o registro confiável.
30
+ - **Declare a reversibilidade e um gatilho de revisão**: o que faria valer a pena revisitar esta decisão.
31
+ - Se um fato é desconhecido, escreva-o como suposição. Não invente evidência.
32
+
33
+ ## Status
34
+
35
+ `Proposed` → `Accepted` → (`Deprecated` | `Superseded by NNNN`)
36
+
37
+ `Rejected` também é válido: registrar a decisão de não fazer algo impede que a mesma discussão recomece.
38
+
39
+ ## Modelo
40
+
41
+ ```
42
+ # NNNN. <Decisão como uma frase curta no imperativo>
43
+
44
+ - Status: <Proposed | Accepted | Rejected | Deprecated | Superseded by NNNN>
45
+ - Data: <AAAA-MM-DD>
46
+ - Decisores: <nomes ou papéis>
47
+ - Relacionados: <ADRs, spikes, issues>
48
+
49
+ ## Contexto
50
+ <O problema e as forças em jogo. Restrições, requisitos, evidência. Ainda sem solução.>
51
+
52
+ ## Decisão
53
+ <O que foi decidido, de forma direta. "Vamos ...">
54
+
55
+ ## Alternativas consideradas
56
+ - <Alternativa> — <por que não foi escolhida>
57
+
58
+ ## Consequências
59
+ - Positivas: <...>
60
+ - Negativas: <...>
61
+ - Neutras / desdobramentos: <trabalho que isso cria, riscos a acompanhar>
62
+
63
+ ## Reversibilidade
64
+ <Barata | Custosa | Sem volta>. <O que reverter envolveria.>
65
+
66
+ ## Gatilho de revisão
67
+ <Condição que deve levar a revisitar esta decisão, por exemplo volume acima de X, crescimento do time, uma dependência chegando ao fim do suporte.>
68
+ ```
69
+
70
+ ## Processo
71
+
72
+ 1. Confirme que a decisão merece um ADR (veja "Quando escrever").
73
+ 2. Reúna o contexto da conversa, do código e de resultados de spikes. Liste os fatos faltantes como suposições.
74
+ 3. Escreva a decisão em uma ou duas frases antes de qualquer outra coisa; se não couber nisso, divida.
75
+ 4. Preencha alternativas e consequências, depois reversibilidade e gatilho de revisão.
76
+ 5. Se ele substitui um ADR anterior, marque o antigo como `Superseded by NNNN`.
77
+
78
+ ## No Forja
79
+
80
+ No Forja, os ADRs ficam em `memory/90-decisions/NNNN-slug.md`, a partir de `memory/90-decisions/_template.md` (cabeçalho `- **Status**:`, `- **Data**:`, `- **Autor(es)**:`, `- **Tags**:`). Use os status do template do projeto (`proposed`, `accepted`, `superseded by ADR-NNNN`, `deprecated`) e mantenha **Reversibilidade** e **Gatilho de revisão** como seções ao final.
81
+
82
+ - Próximo número e status: `forja adr:list`; detalhe de um ADR: `forja adr:show <id>`.
83
+ - Depois de gravar: `forja sync:universal`, para o ADR entrar na memória consultável.
84
+ - Mudança estrutural sem ADR é reprovada pelo papel governance.
85
+
86
+ ## Evite
87
+
88
+ - Escrever o ADR como documento de design ou tutorial.
89
+ - Um contexto que defende a decisão em vez de descrever a situação.
90
+ - Esconder consequências negativas.
91
+ - Editar um ADR aceito para mudar a decisão.
92
+ - Registrar decisões que ninguém nunca vai questionar.
@@ -0,0 +1,82 @@
1
+ ---
2
+ name: backlog-slicing
3
+ description: Use quando transformar uma especificação de requisitos em trabalho entregável: divide os requisitos em histórias de usuário pequenas e verticais, com critérios de aceite, tamanhos e dependências, e sinaliza o que precisa de um spike antes.
4
+ ---
5
+
6
+ # Fatiamento do Backlog
7
+
8
+ Transforma uma especificação de requisitos em histórias que entregam, cada uma, algo que o usuário consegue ver, atravessando todas as camadas, em poucos dias. Fatias verticais pequenas dão feedback cedo, mantêm os pull requests revisáveis e tornam o progresso real em vez de percentual.
9
+
10
+ A saída padrão é uma **lista ordenada de histórias**. Crie issues num gerenciador só quando o usuário pedir.
11
+
12
+ ## Convenções
13
+
14
+ - Entrada: a especificação de `requirements-gathering` (`RF-NN`, `RN-NN`, `RNF-NN`, prioridades, critérios de aceite).
15
+ - As histórias mantêm os IDs dos requisitos que cobrem. Todo `RF-NN` termina em pelo menos uma história; uma história sem requisito está fora do escopo ou é um requisito faltando.
16
+ - IDs de história: `ST-NN`. Nunca reutilizados.
17
+ - Histórias na linguagem ubíqua do usuário. Nada de tarefas técnicas disfarçadas de história.
18
+ - Incógnitas vão para **Perguntas em aberto**. Não invente requisitos para preencher uma fatia.
19
+
20
+ ## Vertical, não horizontal
21
+
22
+ Uma fatia vertical atravessa UI/API, aplicação, domínio e armazenamento para um pedaço estreito de comportamento. "Criar as tabelas do banco" ou "construir a camada de API" são horizontais e não entregam nada sozinhas.
23
+
24
+ Formas de dividir, em ordem de preferência:
25
+
26
+ 1. **Passos do fluxo**: uma história por passo da jornada do usuário (fazer pedido → pagar → acompanhar).
27
+ 2. **Caminho feliz primeiro**: o caminho de sucesso mais simples, e depois cada caminho alternativo e de erro como história própria.
28
+ 3. **Regras de negócio**: o fluxo central com uma regra, e depois uma história por `RN-NN` acrescentada.
29
+ 4. **Variações de dados**: um meio de pagamento primeiro, os outros depois; um país, depois mais.
30
+ 5. **Operações (CRUD)**: criar e visualizar primeiro; editar e excluir quando necessário.
31
+ 6. **Interface**: uma versão simples primeiro, a interface rica depois.
32
+ 7. **Adiar desempenho**: faça funcionar, e depois uma história para a meta do `RNF-NN`, quando o requisito permitir.
33
+
34
+ ## Verificações
35
+
36
+ - **INVEST**: Independente, Negociável, Valiosa, Estimável, Pequena (Small), Testável. Uma história que falha em "Estimável" precisa de um spike (`technical-spike`) antes. Uma história que falha em "Pequena" é dividida de novo.
37
+ - **Tamanho**: P (≤ 1 dia), M (2–3 dias), G (uma semana). G é um alerta; qualquer coisa maior precisa ser dividida.
38
+ - **Critérios de aceite**: Dado/Quando/Então, tirados dos requisitos, estreitados ao que esta fatia faz. Eles alimentam `testing` diretamente.
39
+ - **Requisitos não funcionais** são anexados às histórias que restringem, como critérios de aceite. Uma história separada só quando o trabalho é real e separável (por exemplo, um teste de carga).
40
+ - **Habilitadores** (CI, infraestrutura, uma migração) só são permitidos quando uma história precisa deles, e ficam ligados a essa história.
41
+
42
+ ## Ordenação
43
+
44
+ 1. Esqueleto andante (walking skeleton): o caminho ponta a ponta mais fino, implantável.
45
+ 2. Depois por prioridade (`Must` antes de `Should`) e por risco: a suposição mais arriscada é testada mais cedo.
46
+ 3. Respeite as dependências e evite cadeias: se B não pode começar até A ser entregue, verifique se a divisão está certa.
47
+
48
+ ## Formato
49
+
50
+ ```
51
+ ## ST-01 — <título na linguagem ubíqua> [<tamanho>] [<Must/Should/Could>]
52
+ Como <ator>, quero <capacidade>, para <benefício>.
53
+ Cobre: RF-NN, RN-NN, RNF-NN
54
+ Critérios de aceite:
55
+ - Dado <estado>, quando <ação>, então <resultado>.
56
+ Depende de: <ST-NN | nenhuma>
57
+ Notas: <spike necessário, pergunta em aberto, fora da fatia>
58
+ ```
59
+
60
+ Feche com:
61
+ - **Cobertura**: tabela `RF-NN` → histórias. Requisitos não cobertos listados explicitamente.
62
+ - **Spikes**: incertezas a resolver com `technical-spike` antes de estimar.
63
+ - **Perguntas em aberto**.
64
+
65
+ ## Próximo
66
+
67
+ - `domain-modeling` e `api-design` por história ou grupo de histórias.
68
+ - `testing` transforma os critérios de aceite em casos.
69
+ - `pull-request`: uma história por PR é um bom padrão.
70
+
71
+ ## No Forja
72
+
73
+ No Forja, as histórias viram as tasks da spec: depois de `forja spec:plan <slug>`, rode `forja spec:tasks <slug>` e escreva cada `ST-NN` como uma seção de `specs/<slug>/tasks.md`, mantendo os IDs dos requisitos e os critérios de aceite. Uma corrida guardada por gates: `forja orchestrate "<objetivo>" --slug <slug>`.
74
+
75
+ ## Evite
76
+
77
+ - Histórias horizontais por camada ("backend de X", "frontend de X").
78
+ - Histórias que são tarefas ("refatorar serviço", "escrever testes").
79
+ - Histórias sem critérios de aceite.
80
+ - Épicos rotulados como histórias.
81
+ - Estimar em horas ou prometer datas a partir dos tamanhos.
82
+ - Descartar em silêncio um requisito que não coube numa fatia.
@@ -0,0 +1,88 @@
1
+ ---
2
+ name: bounded-context-mapping
3
+ description: Use quando um sistema abrange mais de um modelo ou time: identifica contextos delimitados, classifica subdomínios e mapeia as relações entre contextos (Parceria, Kernel Compartilhado, Cliente–Fornecedor, Conformista, Camada Anticorrupção, Serviço de Host Aberto) com seu estilo de integração.
4
+ ---
5
+
6
+ # Mapeamento de Contextos Delimitados
7
+
8
+ Um mapa de contextos mostra onde cada modelo é válido e como os modelos conversam entre si. A maior parte da dor de integração vem de relações que ninguém nomeou: um time se conformando em silêncio ao modelo de outro, ou uma tabela compartilhada que acopla dois contextos.
9
+
10
+ A saída é um **mapa de contextos e uma tabela de relações**. Ela descreve o estado atual, o estado alvo, ou os dois. Diga qual.
11
+
12
+ ## Convenções
13
+
14
+ - Termos estratégicos em pt-BR seguidos do en-US: Contexto Delimitado (Bounded Context), Subdomínio (Subdomain), Núcleo (Core), Suporte (Supporting), Genérico (Generic), Mapa de Contextos (Context Map), Montante (Upstream), Jusante (Downstream), Kernel Compartilhado (Shared Kernel), Camada Anticorrupção (Anticorruption Layer), Serviço de Host Aberto (Open Host Service), Linguagem Publicada (Published Language).
15
+ - Entradas: contextos candidatos e eventos pivô de `event-storming`; contextos do passo 2 de `domain-modeling`; times e sistemas existentes, do usuário.
16
+ - Um contexto é uma fronteira de modelo, não uma unidade de implantação. Pode ser uma pasta ou módulo num monólito (veja `ts-module-layout`).
17
+ - Propriedade ou estrutura de times desconhecida vai para **Perguntas em aberto**.
18
+
19
+ ## Processo
20
+
21
+ ### 1. Encontrar os contextos
22
+ Sinais de fronteira: a mesma palavra significa coisas diferentes ("Cliente" em Vendas vs. Faturamento); regras diferentes para o mesmo conceito; um evento pivô onde a propriedade muda; um time ou sistema externo diferente. Nomeie cada contexto pela capacidade de negócio, não por uma tecnologia.
23
+
24
+ ### 2. Classificar os subdomínios
25
+ - **Núcleo**: onde o negócio compete. Construa, com as melhores pessoas e o modelo mais rico.
26
+ - **Suporte**: necessário e específico, mas não diferencia. Construa de forma simples.
27
+ - **Genérico**: problemas resolvidos (autenticação, pagamentos, e-mail). Compre ou use uma biblioteca.
28
+
29
+ ### 3. Mapear cada relação
30
+ Para cada par de contextos que trocam dados ou chamadas, declare a direção (**montante** influencia, **jusante** depende) e o padrão:
31
+
32
+ | Padrão | Significado | Use quando |
33
+ |---|---|---|
34
+ | Parceria (Partnership) | Dois times têm sucesso ou fracassam juntos; coordenam as mudanças | Objetivos muito ligados, times próximos |
35
+ | Kernel Compartilhado (Shared Kernel) | Um modelo/código pequeno que os dois mantêm | Conceitos compartilhados muito estáveis; mantenha-o mínimo |
36
+ | Cliente–Fornecedor (Customer–Supplier) | O montante planeja para as necessidades do jusante | O jusante tem voz nas prioridades do montante |
37
+ | Conformista (Conformist) | O jusante adota o modelo do montante como ele é | O montante não vai mudar e o modelo dele é aceitável |
38
+ | Camada Anticorrupção (ACL) | O jusante traduz o modelo do montante para o seu | O modelo do montante é ruim, legado ou externo; protege o núcleo |
39
+ | Serviço de Host Aberto + Linguagem Publicada | O montante oferece um protocolo estável e um esquema documentado para muitos consumidores | Muitos jusantes; APIs públicas ou de plataforma |
40
+ | Caminhos Separados (Separate Ways) | Sem integração; duplica-se em vez disso | Integrar custa mais do que retorna |
41
+
42
+ Domínios de núcleo que consomem sistemas externos ou legados quase sempre devem usar uma Camada Anticorrupção.
43
+
44
+ ### 4. Escolher o estilo de integração
45
+ Chamada síncrona (API), eventos de domínio assíncronos ou banco compartilhado. Um banco compartilhado entre contextos é um Kernel Compartilhado escondido. Nomeie-o e planeje a saída.
46
+
47
+ ### 5. Sinalizar os problemas
48
+ Relações a corrigir no estado alvo: a grande bola de lama, um kernel compartilhado que não para de crescer, um núcleo conformista, dependências cíclicas entre contextos.
49
+
50
+ ## Formato
51
+
52
+ ~~~
53
+ ## Contextos
54
+ | Contexto | Subdomínio (núcleo/suporte/genérico) | Responsabilidade | Termos-chave | Dono (time) |
55
+
56
+ ## Mapa de contextos
57
+ ```mermaid
58
+ flowchart LR
59
+ Vendas -- "Cliente–Fornecedor (M→J), eventos" --> Faturamento
60
+ Faturamento -- "ACL" --> ERPLegado
61
+ ```
62
+
63
+ ## Relações
64
+ | Montante | Jusante | Padrão | Integração (API/eventos/BD) | Tradução | Notas |
65
+
66
+ ## Problemas e estado alvo
67
+ ## Perguntas em aberto
68
+ ~~~
69
+
70
+ ## Próximo
71
+
72
+ - `domain-modeling` por contexto.
73
+ - `ts-module-layout`: uma pasta de primeiro nível (ou módulo NestJS) por contexto.
74
+ - `api-design`: Serviços de Host Aberto e eventos publicados viram contratos.
75
+ - `architecture-decision-record` para escolhas de relação caras de reverter.
76
+
77
+ ## No Forja
78
+
79
+ No Forja, o mapa de contextos fica em `memory/20-architecture/context-map.md`, e cada contexto ganha sua pasta em `memory/30-domains/<contexto>/`. Relações caras de reverter viram ADR (`architecture-decision-record`).
80
+
81
+ ## Evite
82
+
83
+ - Um contexto por entidade ou por tabela.
84
+ - Contextos com nome de camada técnica ("Banco de Dados", "Frontend").
85
+ - Tratar contextos como microsserviços por padrão.
86
+ - Um Kernel Compartilhado que não para de crescer.
87
+ - Setas sem padrão e sem direção.
88
+ - Inventar estruturas de times. Pergunte.
@@ -0,0 +1,83 @@
1
+ ---
2
+ name: ci-pipeline-review
3
+ description: Use quando escrever ou revisar workflows do GitHub Actions: verifica gatilhos, concorrência, cache, matriz, gates de qualidade, segredos e permissões, fixação de actions, timeouts e custo, e reporta os achados ordenados por severidade.
4
+ ---
5
+
6
+ # Revisão de Pipeline de CI
7
+
8
+ Um pipeline é um gate. Ele precisa barrar código quebrado ou inseguro de forma confiável, rápido o bastante para as pessoas não o contornarem, e sem virar um caminho de ataque para o repositório ou a nuvem.
9
+
10
+ A saída padrão é uma **tabela de achados**. Edite arquivos de workflow só quando o usuário pedir.
11
+
12
+ ## Convenções
13
+
14
+ - Escopo: `.github/workflows/*.yml`, actions compostas em `.github/actions/` e as configurações do repositório que o usuário puder compartilhar (proteção de branch, checks obrigatórios, ambientes).
15
+ - Entradas: os comandos que o projeto de fato usa (scripts do package.json, Makefile) e a divisão de testes de `testing` (suíte rápida vs. integração).
16
+ - A estrutura existente prevalece, a menos que cause um achado.
17
+ - Todo achado cita `arquivo:linha` e um motivo.
18
+
19
+ ## Checklist
20
+
21
+ **Gatilhos e concorrência**
22
+ - `pull_request` para os checks; `push` no branch padrão para builds e deploys. Filtros de caminho só quando não puderem pular checks obrigatórios.
23
+ - `concurrency: { group: ${{ github.workflow }}-${{ github.ref }}, cancel-in-progress: true }` em workflows de PR; nunca cancele deploys no meio.
24
+ - Gatilhos agendados e manuais (`workflow_dispatch`) têm um propósito.
25
+
26
+ **Velocidade e cache**
27
+ - Cache de dependências pela chave dos lockfiles (`actions/setup-node` com `cache: npm|pnpm|yarn`, instalação com `npm ci` / `pnpm install --frozen-lockfile`).
28
+ - Cache de build/teste onde a ferramenta suporta. Cache de camadas Docker (`cache-from`/`cache-to: type=gha`).
29
+ - Jobs independentes rodam em paralelo; `needs:` só para dependências reais.
30
+ - Matriz só onde compensa (versões de Node do `engines`, ou sistemas operacionais que o projeto de fato distribui). `fail-fast` declarado de propósito.
31
+ - `timeout-minutes` em todo job.
32
+
33
+ **Gates**
34
+ - Ordem: formatação/lint → checagem de tipos (`tsc --noEmit`) → testes unitários → build → testes de integração → deploy.
35
+ - Os mesmos comandos que os desenvolvedores rodam localmente (`npm test`), não um script separado que se desvia.
36
+ - Os status checks obrigatórios no branch padrão batem com os nomes dos jobs. Um job renomeado derruba seu gate em silêncio.
37
+ - Deploys passam por `environment:` com regras de proteção; produção exige aprovação ou uma tag de release.
38
+
39
+ **Segurança**
40
+ - `permissions: contents: read` no topo; amplie por job só o necessário.
41
+ - OIDC (`id-token: write`) para provedores de nuvem em vez de chaves de longa duração nos segredos.
42
+ - `pull_request_target` e `workflow_run` nunca fazem checkout e rodam código não confiável de PR com segredos.
43
+ - Nada de `${{ github.event.* }}` interpolado direto em scripts `run:` (injeção de script). Passe por `env:`.
44
+ - Actions de terceiros fixadas num SHA de commit completo, com a versão num comentário. Dependabot ou Renovate as atualizam.
45
+ - Segredos nunca impressos; valores mascarados não transformados em não mascarados.
46
+
47
+ **Confiabilidade e custo**
48
+ - Testes instáveis em quarentena com uma issue, não repetidos em silêncio.
49
+ - Artefatos com `retention-days`; nada de artefatos grandes em todo PR.
50
+ - Tamanho do runner adequado ao job.
51
+
52
+ ## Severidade
53
+
54
+ Bloqueador (brecha de segurança, gate que não barra) · Maior (lento ou instável o bastante para ser contornado, timeout ausente) · Menor (custo, clareza) · Detalhe.
55
+
56
+ ## Formato
57
+
58
+ ```
59
+ ## Resumo
60
+ <forma do pipeline, duração total se conhecida, quantidade de bloqueadores>
61
+
62
+ ## Achados
63
+ | # | Arquivo:linha | Categoria | Severidade | Problema | Correção |
64
+ |---|---|---|---|---|---|
65
+
66
+ ## Mudanças sugeridas
67
+ <trechos de YAML, só a pedido>
68
+ ```
69
+
70
+ ## Próximo
71
+
72
+ - `commit-message`: commits `ci:` para as correções.
73
+ - `release-checklist` depende de os gates serem reais.
74
+ - `docker-compose-review` quando o CI constrói ou executa containers.
75
+
76
+ ## Evite
77
+
78
+ - Actions fixadas em `@main` ou numa tag mutável.
79
+ - `permissions: write-all` ou nenhum bloco `permissions`.
80
+ - `continue-on-error: true` em passos obrigatórios.
81
+ - Scripts só de CI que divergem dos comandos locais.
82
+ - Recomendar uma matriz "por completude".
83
+ - Reescrever o pipeline inteiro quando alguns achados resolvem.