nexus-core-v3 3.0.0

package/dist/constitution.yaml

@@ -0,0 +1,76 @@
+# Constitution do Nexus Core v3 — FONTE ÚNICA (INV-6).
+# ConstitutionProjector deriva daqui: markdown (docs), gates.json (enforcement) e l0Domain (SYNAPSE L0).
+# NÃO editar a projeção materializada; editar apenas este arquivo.
+version: 3.0.0
+
+articles:
+  - id: "I"
+    title: CLI First
+    severity: NON-NEGOTIABLE
+    body: >
+      Toda inteligência, execução e automação vive no CLI. Observabilidade é secundária;
+      UI é terciária. Nenhuma capacidade essencial pode existir apenas na UI.
+  - id: "II"
+    title: Agent Authority
+    severity: NON-NEGOTIABLE
+    body: >
+      Operações exclusivas pertencem a um único agente dono. Outros agentes são bloqueados
+      (fail-closed). Delegação é o padrão para trabalho especializado.
+  - id: "III"
+    title: Story-Driven Development
+    severity: MUST
+    body: >
+      Todo desenvolvimento parte de uma story com critérios de aceite. Progresso é rastreável
+      por ID; nada é entregue sem rastreabilidade.
+  - id: "IV"
+    title: No Invention
+    severity: MUST
+    body: >
+      Cada afirmação de spec/feature rastreia a um requisito, restrição ou achado de pesquisa.
+      Nenhuma feature inventada. Declarado = real, verificável em CI.
+  - id: "V"
+    title: Quality First
+    severity: MUST
+    body: >
+      Typecheck, lint e testes passam antes de qualquer entrega. Cobertura com ratchet.
+      Degradação graciosa nunca esconde código morto.
+  - id: "VI"
+    title: Absolute Imports
+    severity: SHOULD
+    body: >
+      Preferir imports por pacote (@nexus/*) a caminhos relativos profundos, mantendo o grafo
+      de dependências explícito e acíclico.
+  - id: "VII"
+    title: Squad Charter
+    severity: NON-NEGOTIABLE
+    body: >
+      Squads herdam a constituição INTEGRAL. Operações exclusivas do core (git_push, pr_create,
+      pr_merge, mcp_manage → devops) JAMAIS são sobrescritas ou duplicadas por squad. Autoridades
+      de squad são ADITIVAS e namespaced 'squad.{id}.{operation}'; conflito com operação exclusiva
+      bloqueia a composição do gate (fail-closed) — o gate permanece único.
+
+authorities:
+  - operation: git_push
+    owner: devops
+    exclusive: true
+    matchPatterns:
+      - tool: Bash
+        subcommand: git push
+  - operation: pr_create
+    owner: devops
+    exclusive: true
+    matchPatterns:
+      - tool: Bash
+        subcommand: gh pr create
+  - operation: pr_merge
+    owner: devops
+    exclusive: true
+    matchPatterns:
+      - tool: Bash
+        subcommand: gh pr merge
+  - operation: mcp_manage
+    owner: devops
+    exclusive: true
+    matchPatterns:
+      - tool: Bash
+        subcommand: claude mcp

package/knowledge/README.md

@@ -0,0 +1,57 @@
+# NEXUS Knowledge — os skills dos agentes
+
+Esta é a 5ª camada de conteúdo. Se o DNA é *quem* o agente é e a task é *o que ele faz*, o **knowledge
+pack** é o **craft diferenciado** — o conhecimento que faz o agente produzir trabalho que se destaca,
+não trabalho genérico. É a forma estruturada e versionada de "dar habilidade pro agente".
+
+> No design antigo isso se fazia jogando repositórios soltos no contexto. Aqui é **curado**: cada pack
+> é conhecimento focado, específico e reutilizável — não um dump de arquivos.
+
+## Formato canônico
+
+```markdown
+---
+id: anti-ai-look
+domain: web-craft            # web-craft | copy | ...
+agents: [ux-design-expert]   # quem puxa este pack
+when: "quando desenhar/implementar uma página que precisa parecer bespoke"
+---
+
+# {título}
+
+## O problema / o tell        ← o que torna o trabalho medíocre (concreto, nomeado)
+## Os princípios do craft     ← como o expert faz diferente (específico, com exemplos)
+## Checklist                  ← auto-verificação objetiva ("isto parece de IA?")
+## Antes → depois             ← exemplos concretos do ruim vs do bom
+```
+
+## Regra de qualidade (o que separa skill de listicle)
+
+- **Específico, nunca genérico.** "Use boa tipografia" é lixo. "Pareie uma display face de caráter com
+  uma workhorse de texto numa escala modular (~1.25); não use Inter em tudo" é craft. Se um modelo
+  capaz já faria sem ser instruído, a linha não é skill — é ruído.
+- **Nomeia os tells.** Um bom pack lista os sinais concretos do trabalho ruim (ex.: gradiente
+  índigo→violeta, grid de 3 cards com emoji) para o agente reconhecer e fugir.
+- **Tem exemplo.** Antes (o tell) → depois (o craft). Concreto vence abstrato.
+
+## Como o agente consome
+
+- **Modo interativo:** o agente carrega o pack sob demanda quando faz aquela classe de trabalho (igual
+  o DNA referencia em `knowledge:`).
+- **Modo motor (`nexus run`):** o pack é injetado no prompt do agente spawnado pela camada
+  `@nexus/synapse` (recall por palavra-chave do domínio).
+
+## Ética (importante — isto vai pra produção)
+
+Skills de "clonar estilo" ensinam a **técnica** (extrair a linguagem de design: cor, tipo, espaço,
+motion) — nunca copiar assets/conteúdo de terceiros. Linguagem de design é craft; pirataria de
+asset é problema de IP. Os packs reforçam essa linha.
+
+## Packs
+
+| Pack | Domínio | O que dá ao agente |
+|---|---|---|
+| `web-craft/anti-ai-look` | web-craft | páginas bespoke que não parecem de IA |
+| `web-craft/style-cloning` | web-craft | extrair e reaplicar a linguagem de design de uma referência |
+| `web-craft/design-system-from-code` | web-craft | consolidar um design system a partir de um codebase |
+| `copy/landing-copy-that-converts` | copy | copy de landing com voz e gatilhos reais, não texto genérico |

package/knowledge/architecture/architectural-styles-map.md

@@ -0,0 +1,182 @@
+---
+id: architectural-styles-map
+domain: architecture
+agents: [architect]
+when: "ao decidir a forma estrutural de um projeto (camadas, fronteiras, organização)"
+---
+
+# Mapa de estilos arquiteturais — escolher a forma estrutural sem cargo-cult
+
+## O problema
+
+A decisão de forma estrutural quase nunca é tomada por critério — é tomada por hábito ("foi o que usei no
+último projeto"), por moda ("todo mundo faz Clean + CQRS + Event Sourcing") ou por medo ("melhor sobrar
+camada do que faltar"). O resultado tem cara reconhecível e é o equivalente arquitetural do "look de IA":
+
+1. **Clean/Onion/Hexagonal aplicado a um CRUD de 4 tabelas** — 5 projetos na solution, mappers de DTO para
+   entidade para DTO, e a "regra de dependência" defendida com unhas e dentes num sistema que nunca terá
+   uma segunda implementação de repositório.
+2. **CQRS com bancos de leitura e escrita separados** num domínio onde leitura e escrita têm o mesmo
+   modelo e a mesma carga. A própria fonte tem um artigo chamado *"CQRS is not a general purpose style of
+   architecture"* exatamente por causa disso.
+3. **Event Sourcing "porque dá auditoria"** num sistema que só precisava de uma coluna `updated_at` e uma
+   tabela de log. Append-only log, versionamento de evento, projeções e *eventual consistency* — três
+   problemas novos para resolver um que não existia.
+4. **Layered/N-tier chamado de "arquitetura"** quando na verdade é uma `Controller → Service → Repository`
+   anêmica: a camada de domínio não tem comportamento, só getters/setters (o *anemic domain model*, listado
+   como anti-padrão na própria fonte).
+5. **Bounded contexts demais** — cada agregado virou um "microsserviço" antes de existir uma única regra de
+   negócio estável. Fronteira de contexto sem *context mapping*, então tudo acopla via banco compartilhado.
+6. **Zero documentação de decisão** — ninguém sabe *por que* o sistema é Hexagonal e não Layered. Sem ADR,
+   a decisão não tem rastro; seis meses depois alguém "simplifica" e quebra a fronteira de propósito.
+
+A regra-mãe: **estilo arquitetural é resposta a uma força concreta (taxa de mudança, número de
+integrações, criticidade, assimetria leitura/escrita), não um default.** Se você não consegue nomear a
+força que justifica a camada, a camada é custo sem retorno. Estrutura existe para *isolar o que muda por
+razões diferentes* — não para parecer sofisticada.
+
+> Fonte de referência (curadoria real): `mehdihadeli/awesome-software-architecture`
+> (`awesome-architecture.com`) — seções *Architectural Styles* (Clean, Hexagonal, Onion, Layered, Vertical
+> Slice, Modular Monolith), *Domain Driven Design* (strategic/tactical), *CQRS*, *Event Sourcing*,
+> *Architecture Documentation* (C4, ADR, arc42).
+
+## Os princípios / o conhecimento
+
+### 1. A família "regra de dependência" — Clean, Hexagonal, Onion são a MESMA ideia com nomes diferentes
+
+Os três compartilham um único princípio: **dependências apontam para dentro, em direção ao domínio; o
+domínio não conhece infraestrutura.** Isso é a aplicação do *Dependency Inversion Principle* (listado em
+*architectural-design-principles* na fonte) na escala de toda a aplicação. A diferença entre eles é
+*vocabulário e ênfase*, não mecânica.
+
+| Estilo | Autor / origem | A regra de dependência (exata) | Vocabulário próprio | Ênfase distintiva |
+|---|---|---|---|---|
+| **Layered / N-tier** | Clássico (Fowler, PoEAA) | Cada camada depende **da de baixo** (UI → App → Domínio → Dados). Dependência desce. | Presentation, Business, Data Access | Simplicidade; mas o domínio acaba dependendo do banco |
+| **Hexagonal (Ports & Adapters)** | Alistair Cockburn (2005) | O núcleo define **ports** (interfaces); **adapters** externos dependem do núcleo, nunca o contrário. Simétrico: driving (entrada) e driven (saída). | Port, Adapter, driving/driven side | Testabilidade: troca-se qualquer adapter (DB, UI, fila) sem tocar no núcleo |
+| **Onion** | Jeffrey Palermo (2008) | Camadas **concêntricas**; dependência aponta para o centro. Centro = Domain Model; fora = Infra/UI. | Domain Model → Domain Services → App Services → Infra | Domínio no centro absoluto; infraestrutura é a casca mais externa |
+| **Clean** | Robert C. Martin / "Uncle Bob" (2012) | **The Dependency Rule:** "source code dependencies can only point inwards". Entities → Use Cases → Interface Adapters → Frameworks & Drivers. | Entities, Use Cases, Interface Adapters, Frameworks | Síntese de Onion + Hexagonal + DDD; nomeia explicitamente *Use Cases* como anel próprio |
+
+**Como decidir entre eles** (não confunda "diferente" com "melhor"):
+
+| Sua situação | Estilo indicado | Por quê |
+|---|---|---|
+| CRUD simples, pouca regra, time pequeno | **Layered** (ou Vertical Slice) | A inversão completa é custo sem retorno; descer a dependência é honesto e barato |
+| Muitos pontos de I/O (DB + filas + APIs externas + UI) que mudam independentemente | **Hexagonal** | Ports/adapters isolam cada integração; cada uma vira um adapter trocável |
+| Domínio rico, regras no centro, quero proteger o modelo de qualquer tecnologia | **Onion** ou **Clean** | Domínio no centro, infra na casca; *persistence ignorance* garantida |
+| Quero um nome de camada explícito para "o que o sistema faz" (orquestração de caso de uso) | **Clean** | É o único que dá ao anel de *Use Cases* status de primeira classe |
+| Feature-oriented, quero minimizar acoplamento horizontal entre camadas | **Vertical Slice** | Corta por funcionalidade, não por camada técnica; cada slice é coeso ponta a ponta |
+
+> Pragmatismo: para a maioria dos sistemas de negócio, **Hexagonal e Clean convergem na prática**. Escolha
+> um vocabulário e seja consistente. O erro caro não é escolher "errado" entre eles — é aplicar qualquer
+> um dos três a um problema que era Layered.
+
+### 2. DDD não é um estilo de camada — é tático **e** estratégico, e você quase sempre quer o estratégico primeiro
+
+A fonte separa DDD em dois blocos, e essa separação é a decisão mais subestimada:
+
+| | DDD **Tático** | DDD **Estratégico** |
+|---|---|---|
+| Pergunta que responde | "Como modelo *dentro* de uma fronteira?" | "*Onde* ficam as fronteiras?" |
+| Artefatos (da fonte) | Entities, **Value Objects**, **Aggregates** (aggregation), Domain Services, Application Services, Domain Events, Repositories, Rich Domain Model | **Bounded Contexts**, **Context Mapping**, Ubiquitous Language, Core/Supporting/Generic **Subdomains**, Strategic Design Patterns |
+| Quando aplicar | Quando o domínio tem invariantes e comportamento (não é CRUD) | Quando o sistema cobre múltiplas áreas de negócio que evoluem em ritmos diferentes |
+| Erro comum | *Anemic Domain Model* — entidade sem comportamento, só getters/setters (anti-padrão na fonte) | Fatiar em microsserviços por agregado, sem *context mapping*, criando acoplamento por banco compartilhado |
+
+**Sequência correta:** estratégico **antes** de tático. Primeiro descubra os *bounded contexts* (onde a
+linguagem ubíqua muda de significado é onde a fronteira está), depois aplique o modelo tático *dentro* de
+cada contexto. Decidir Aggregates antes de saber o Core Domain é otimizar a parte errada.
+
+**Quando NÃO fazer DDD tático:** se o domínio é genérico (autenticação, notificação, billing de
+prateleira) ou é CRUD puro, o modelo rico é over-engineering. Use *Transaction Script* (também listado na
+fonte como design pattern) — é honesto para lógica procedural simples.
+
+Mapeamento de aggregate ↔ estilo: o **Aggregate** é a fronteira de consistência *transacional*; o
+**Bounded Context** é a fronteira de *modelo/linguagem* (e candidato a fronteira de deploy/serviço). Não
+confunda os dois — um contexto contém vários agregados.
+
+### 3. CQRS e Event Sourcing — dois eixos independentes, ambos com alto custo de entrada
+
+O erro número um é tratá-los como pacote ("Clean + CQRS + ES"). São **decisões ortogonais**: dá para ter
+CQRS sem Event Sourcing, Event Sourcing sem CQRS separado, e a maioria dos sistemas não quer nenhum dos
+dois.
+
+**CQRS** = separar o modelo de *escrita* (commands) do modelo de *leitura* (queries). É a aplicação do
+princípio **CQS** (Command Query Separation, listado na fonte) na escala de arquitetura. Pode ser leve (dois
+modelos, um banco) ou pesado (dois bancos, sincronizados por eventos).
+
+| Use CQRS quando… | NÃO use CQRS quando… |
+|---|---|
+| Leitura e escrita têm **modelos genuinamente diferentes** (escrita normalizada, leitura em projeções desnormalizadas) | Leitura e escrita compartilham o mesmo modelo — separar é duplicação pura |
+| Assimetria de carga forte (ex.: 100x mais leitura que escrita) que justifica escalar os lados separadamente | Carga simétrica e modesta — um modelo único escala bem |
+| Domínio complexo onde a lógica de escrita se beneficia de não carregar concern de leitura | CRUD; a própria fonte: *"CQRS is not a general purpose style of architecture"* |
+| Já existe Event Sourcing (projeções de leitura caem naturalmente) | Time pequeno sem experiência — *eventual consistency* entre os lados é armadilha sutil |
+
+**Event Sourcing** = persistir o estado como uma **sequência imutável de eventos** (append-only log), não
+como snapshot do estado atual. Reconstrói qualquer estado passado por replay.
+
+| Use Event Sourcing quando… | NÃO use Event Sourcing quando… |
+|---|---|
+| **Auditoria/compliance** exige histórico completo e imutável de cada mudança | Um `updated_at` + tabela de log resolve a auditoria que você realmente precisa |
+| Você precisa de **queries temporais** (estado em qualquer ponto no tempo) | Você só precisa do estado atual e consistência imediata |
+| Domínio rico onde o *evento* é a verdade do negócio (financeiro, logística, jogos) | CRUD simples — ES introduz versionamento de evento, projeções e *eventual consistency* sem retorno |
+| Forense/debug: replay do log reproduz o caminho até o bug | Time sem maturidade para lidar com migração de schema de eventos antigos |
+
+**Sinal de over-engineering (qualquer um destes = pare):** o domínio é CRUD; não há requisito de auditoria
+temporal nem de histórico; a leitura e a escrita têm o mesmo modelo; o time nunca operou *eventual
+consistency* em produção. Nesses casos, Layered + um modelo de domínio honesto entrega mais valor com
+ordens de magnitude menos risco.
+
+### 4. Documentar a decisão — C4 (a forma) + ADR (o porquê)
+
+Estrutura sem documentação de decisão apodrece: a próxima pessoa não sabe *por que* a fronteira existe e a
+quebra "simplificando". A fonte (*Architecture Documentation*) aponta o par canônico:
+
+| Ferramenta | O que captura | Granularidade | Quando produzir |
+|---|---|---|---|
+| **C4 Model** (Simon Brown) | A **forma** do sistema em 4 níveis: **Context** (sistema + atores) → **Container** (apps/serviços/bancos) → **Component** (dentro de um container) → **Code** (raro, gerado) | Do macro ao micro; pare no nível que agrega valor (geralmente Context + Container) | No design inicial e quando a topologia muda |
+| **ADR** (Architecture Decision Record, Michael Nygard) | O **porquê** de cada decisão: contexto, decisão, alternativas, consequências. "A LOG that answers WHY" | Uma decisão por arquivo, numerado, imutável (decisões revogadas viram "superseded") | Toda decisão estrutural com trade-off (escolha de estilo, fronteira, CQRS sim/não) |
+| **arc42** | Template guarda-chuva de documentação (a fonte: *"the template for software architecture documentation"*) | Documento vivo do sistema | Quando se quer um doc de arquitetura completo e padronizado |
+
+Regra prática: **C4 mostra o que você construiu; ADR explica por que não construiu de outro jeito.** Os dois
+juntos. Diagrama sem ADR vira desenho bonito sem rastro de decisão; ADR sem C4 vira prosa sem mapa.
+Mantenha ambos versionados junto do código (*Architecture as Code*, citado na fonte).
+
+## Checklist — "esta forma estrutural é justificada ou é cargo-cult?"
+
+Antes de fechar a decisão de estilo, responda. Qualquer "sim" da coluna errada é um tell a corrigir:
+
+- [ ] Consigo **nomear a força concreta** (taxa de mudança, número de integrações, criticidade, assimetria
+      leitura/escrita) que justifica cada camada/fronteira que estou adicionando?
+- [ ] Estou aplicando Clean/Onion/Hexagonal a um **CRUD simples**? (Se sim → Layered ou Vertical Slice.)
+- [ ] Defini os **bounded contexts** (estratégico) **antes** de detalhar Aggregates/Value Objects (tático)?
+- [ ] Meu modelo de domínio tem **comportamento**, ou é anêmico (só getters/setters)?
+- [ ] Estou adotando **CQRS** sem que leitura e escrita tenham modelos genuinamente diferentes ou
+      assimetria de carga real?
+- [ ] Estou adotando **Event Sourcing** sem requisito real de auditoria temporal / histórico imutável?
+- [ ] O time **já operou** *eventual consistency* em produção, se estou indo para CQRS pesado ou ES?
+- [ ] Cada agregado virou microsserviço **antes** de ter *context mapping* definido? (Se sim → recue.)
+- [ ] Existe um **ADR** registrando *por que* este estilo e não os alternativos?
+- [ ] Existe um **C4** (ao menos Context + Container) mostrando a forma para quem chega depois?
+- [ ] Se eu remover esta camada/separação, **algo concreto quebra** — ou só fica "menos sofisticado"?
+
+## Tabela de decisão — "use o estilo X quando o sistema tem a característica Y"
+
+| Característica do sistema (Y) | Estilo / decisão (X) | Evite |
+|---|---|---|
+| CRUD, poucas regras, time pequeno, baixa criticidade | **Layered / N-tier** ou **Vertical Slice** | Clean/Onion/Hexagonal, CQRS, ES |
+| Feature-oriented, quer coesão ponta a ponta por funcionalidade | **Vertical Slice Architecture** | Camadas horizontais espessas |
+| Muitos I/O independentes (DB + filas + APIs + UI) que trocam separadamente | **Hexagonal (Ports & Adapters)** | Layered (acopla domínio ao DB) |
+| Domínio rico, modelo precisa ser protegido de qualquer tecnologia | **Onion** ou **Clean** | Anemic domain model |
+| Preciso de status explícito para "casos de uso" / orquestração | **Clean Architecture** | — |
+| Sistema cobre várias áreas de negócio em ritmos diferentes | **DDD estratégico**: bounded contexts + context mapping | Microsserviço por agregado sem mapping |
+| Dentro de uma fronteira com invariantes e comportamento | **DDD tático**: Aggregates, Value Objects, Domain Events, Repositories | Transaction script com regra espalhada |
+| Lógica procedural simples, domínio genérico (auth, notificação) | **Transaction Script** | DDD tático completo |
+| Leitura e escrita com modelos diferentes OU assimetria de carga forte | **CQRS** (leve: 1 banco; pesado: 2 bancos só se a escala exigir) | CQRS em CRUD simétrico |
+| Auditoria/compliance com histórico imutável + queries temporais | **Event Sourcing** (+ projeções; geralmente com CQRS) | ES "pela auditoria" quando log+timestamp basta |
+| Só precisa do estado atual, consistência imediata | **Snapshot/estado** (persistência tradicional) | Event Sourcing |
+| Múltiplos contextos mas ainda sem regra estável / time pequeno | **Modular Monolith** (módulos com fronteira interna) | Microsserviços prematuros |
+| Qualquer decisão estrutural com trade-off | **Registrar um ADR** + diagrama **C4** (Context + Container) | Decisão sem rastro |
+
+> Princípio de fechamento: **comece no estilo mais simples que respeita as forças do sistema e evolua sob
+> pressão real.** É barato promover Layered → Hexagonal quando as integrações crescerem; é caro desmontar
+> Event Sourcing aplicado cedo demais. A sofisticação correta é a que você consegue justificar num ADR — o
+> resto é o "look de IA" da arquitetura.

package/knowledge/architecture/design-patterns-gof.md

@@ -0,0 +1,192 @@
+---
+id: design-patterns-gof
+domain: architecture
+agents: [architect]
+when: "ao reconhecer um problema recorrente de design e escolher (ou descartar) um padrão"
+---
+
+# Design Patterns (GoF) — índice sintoma → padrão → trade-off
+
+23 soluções nomeadas para problemas recorrentes de design OO, catalogadas pelo Gang of Four (1994)
+e mantidas com critérios atuais em [refactoring.guru](https://refactoring.guru/design-patterns).
+Este pack é o **índice de decisão**: para cada padrão, o problema que resolve, o code smell que
+sinaliza que ele cabe, um exemplo minimal em TypeScript, e — o que mais importa — **quando NÃO usar**,
+porque um padrão aplicado fora de hora é a forma mais cara de over-engineering.
+
+## O problema
+
+Reconhecer um padrão é fácil; saber se ele **cabe** é o craft. Dois erros simétricos:
+
+1. **Reinventar.** Resolver na unha um problema que já tem solução nomeada, testada e comunicável —
+   e errar nos casos de borda que o padrão já cobre.
+2. **Cargo-culting.** Aplicar o padrão porque você sabe o nome, não porque o problema pediu. Uma
+   `AbstractFactoryBuilderStrategy` para instanciar uma struct de config. Isto é o tell de IA da
+   arquitetura: estrutura sem justificativa. A régua do pack-âncora vale aqui — **uma decisão de
+   design só existe se você consegue justificar por que ela é assim e não o default.**
+
+A fonte é explícita sobre o custo: quase todo padrão lista, nas próprias contras, *"o código fica
+mais complicado"* / *"novas interfaces e classes são introduzidas"*. Padrão é dívida de indireção
+paga adiantada na esperança de flexibilidade futura. Só vale se a flexibilidade **vier**.
+
+> Os padrões variam em escala: **idiomas** são o nível mais baixo (presos a uma linguagem);
+> **padrões arquiteturais** são o mais alto (desenham a aplicação inteira). Os 23 GoF ficam no meio —
+> design de classes e objetos, não arquitetura de sistema. Não confunda escolher um GoF com decidir
+> arquitetura.
+
+## Os princípios / o conhecimento
+
+### As 3 categorias (intenção — definição da fonte)
+
+| Categoria | O que resolve (definição refactoring.guru) | Eixo |
+|---|---|---|
+| **Creational** (5) | "mecanismos de criação de objetos que aumentam flexibilidade e reuso do código existente" | *como nascem* os objetos |
+| **Structural** (7) | "como montar objetos e classes em estruturas maiores, mantendo-as flexíveis e eficientes" | *como se compõem* |
+| **Behavioral** (11) | "comunicação efetiva e atribuição de responsabilidades entre objetos" | *como conversam* |
+
+### Creational — sintoma → padrão → quando NÃO
+
+| Padrão | Code smell que sinaliza | Resolve | NÃO use quando |
+|---|---|---|---|
+| **Factory Method** | `new ConcreteX()` espalhado; `switch(type)` para instanciar | criar objetos cujo tipo exato você não sabe de antemão; deixar o framework ser estendido por subclasse | só há 1 tipo concreto e não há hierarquia de criadores — vira subclasse à toa |
+| **Abstract Factory** | criar **famílias** de objetos que precisam ser compatíveis entre si (botão+checkbox do mesmo tema) | produzir famílias relacionadas sem amarrar a classes concretas | os produtos não formam família / não precisam casar — interfaces demais sem ganho |
+| **Builder** | **construtor telescópico**: `new X(a,b,c,d,null,null,true)` | construir objeto complexo passo a passo; mesmas etapas, representações diferentes | objeto simples com poucos campos — o builder é mais código que o construtor |
+| **Prototype** | subclasses que só diferem em **como inicializam**; código de init repetido | clonar objetos sem depender da classe concreta | objetos com referências circulares (a própria fonte avisa: clonar fica "muito complicado") |
+| **Singleton** | querer "uma instância só" e ponto de acesso global | garantir instância única + acesso global | **quase sempre.** Viola SRP, mascara acoplamento, complica teste (construtor privado, sem mock por herança), exige cuidado com threads. Prefira injeção de dependência |
+
+```ts
+// Factory Method — esconde o `new` concreto atrás de uma escolha
+interface Transport { deliver(): string; }
+class Truck implements Transport { deliver() { return "via estrada"; } }
+class Ship implements Transport { deliver() { return "via mar"; } }
+
+abstract class Logistics {
+  abstract createTransport(): Transport;       // o "factory method"
+  planDelivery() { return this.createTransport().deliver(); }
+}
+class RoadLogistics extends Logistics { createTransport() { return new Truck(); } }
+class SeaLogistics  extends Logistics { createTransport() { return new Ship(); } }
+```
+
+### Structural — sintoma → padrão → quando NÃO
+
+| Padrão | Code smell que sinaliza | Resolve | NÃO use quando |
+|---|---|---|---|
+| **Adapter** | interface incompatível: classe legada/3rd-party não encaixa no seu código | fazer interfaces incompatíveis colaborarem (tradutor) | você pode simplesmente alterar a classe de serviço — a fonte diz: às vezes editar direto é mais simples |
+| **Bridge** | explosão combinatória de subclasses em 2 eixos (Forma × Cor) | separar abstração de implementação em hierarquias independentes; trocar impl em runtime | a classe é altamente coesa — a fonte avisa que aplicar aqui só complica |
+| **Composite** | `if (isLeaf) … else (itera filhos) …`; tratar nó e folha diferente | árvore de objetos tratada uniformemente via interface comum (polimorfismo + recursão) | as classes diferem demais para uma interface comum — você supergeneraliza |
+| **Decorator** | subclasses combinatórias para empilhar comportamentos (`BufferedEncryptedStream`) | adicionar comportamento em runtime empilhando wrappers | comportamento depende da **ordem** do empilhamento, ou você precisa remover um wrapper específico (a fonte cita ambos como difíceis) |
+| **Facade** | cliente precisa orquestrar 10 classes do subsistema na ordem certa | uma interface simples para um subsistema complexo | a facade vira **god object** acoplado a tudo — sinal de que virou problema, não solução |
+| **Flyweight** | **milhões** de objetos similares estourando a RAM, com estado duplicável | compartilhar estado intrínseco entre muitos objetos para caber na RAM | NÃO há problema real de RAM. A fonte é taxativa: *"use only when"* há explosão de objetos drenando memória. Caso contrário troca RAM por CPU e ofusca o código |
+| **Proxy** | precisa de lazy-init / controle de acesso / cache / log **transparente** ao redor de um objeto | substituto que controla acesso (virtual, protection, remote, logging, caching, smart-ref) | uma chamada direta resolve — proxy adiciona classe e latência sem motivo |
+
+```ts
+// Decorator — empilha comportamento sem subclasse combinatória
+interface DataSource { write(s: string): string; }
+class FileSource implements DataSource { write(s: string) { return s; } }
+
+abstract class Decorator implements DataSource {
+  constructor(protected wrappee: DataSource) {}
+  write(s: string) { return this.wrappee.write(s); }
+}
+class Encrypt extends Decorator { write(s: string) { return super.write(`enc(${s})`); } }
+class Compress extends Decorator { write(s: string) { return super.write(`zip(${s})`); } }
+
+new Encrypt(new Compress(new FileSource())).write("dado"); // enc(zip(dado)) — ordem importa!
+```
+
+### Behavioral — sintoma → padrão → quando NÃO
+
+| Padrão | Code smell que sinaliza | Resolve | NÃO use quando |
+|---|---|---|---|
+| **Chain of Responsibility** | série de `if/else` decidindo quem trata o request, em ordem | passar request por cadeia de handlers; cada um trata ou repassa | a fonte avisa: um request pode **acabar sem tratamento** — ruim se todo request precisa de resposta |
+| **Command** | querer enfileirar / agendar / desfazer / logar operações | encapsular request como objeto (undo/redo, fila, log, remoto) | a operação é direta e nunca precisa ser adiada/revertida — só adiciona camada sender↔receiver |
+| **Iterator** | código de travessia duplicado; expor estrutura interna da coleção | percorrer coleção sem expor sua representação | coleção simples (array) — a fonte diz: overhead desnecessário e menos eficiente que acesso direto |
+| **Mediator** | teia de dependências diretas N×N entre componentes (UI clássico) | centralizar a comunicação em um mediador | poucos componentes pouco acoplados — o mediador vira **god object** com o tempo |
+| **Memento** | precisar de snapshot/restore sem violar encapsulamento (undo) | salvar/restaurar estado sem expor campos internos | snapshots frequentes (estoura RAM) ou linguagem dinâmica que não garante imutabilidade do memento (JS/TS incluídos — a fonte cita) |
+| **Observer** | objetos que precisam reagir a mudanças de outro, lista dinâmica | pub/sub: notificar muitos assinantes sobre eventos | ordem de notificação importa — a fonte avisa que assinantes são notificados em ordem imprevisível |
+| **State** | conditionals gigantes sobre `this.status` espalhados pela classe | objeto muda comportamento conforme estado interno (máquina de estados) | poucos estados que raramente mudam — a fonte diz que é exagero |
+| **Strategy** | `switch` entre variantes do **mesmo** algoritmo; classes que só diferem num comportamento | família de algoritmos intercambiáveis em runtime | só há 1-2 algoritmos estáveis; ou a linguagem tem funções de 1ª classe — a fonte sugere passar uma função/lambda em vez de criar classes |
+| **Template Method** | classes com algoritmos quase idênticos, diferindo em poucos passos | esqueleto do algoritmo na superclasse, passos sobrescritos por subclasse | cliente fica preso ao esqueleto; cresce em passos → difícil manter; risco de violar LSP ao suprimir passo |
+| **Visitor** | adicionar operações a uma hierarquia estável sem tocar nas classes | separar algoritmo dos objetos sobre os quais opera (acumula info na travessia) | a hierarquia de elementos muda muito — a fonte avisa: cada novo elemento força atualizar **todos** os visitors |
+| **Interpreter** *(GoF clássico, fora do catálogo refactoring.guru)** | gramática simples e recorrente a avaliar (filtros, expressões) | representar uma gramática como classes e interpretá-la | gramática não-trivial → use parser/AST de verdade. Raro o suficiente para a fonte nem catalogar |
+
+```ts
+// Strategy — algoritmos intercambiáveis. Em TS, muitas vezes uma função basta:
+type PricingStrategy = (base: number) => number;
+const retail: PricingStrategy  = b => b;
+const black:  PricingStrategy  = b => b * 0.7;
+
+class Cart {
+  constructor(private price: PricingStrategy) {}        // injete a estratégia
+  total(base: number) { return this.price(base); }
+}
+new Cart(black).total(100); // 70 — sem classes Strategy/ConcreteStrategy: a fonte aceita
+```
+
+### Pares que se confundem (escolha por intenção, não por estrutura)
+
+| Você quer… | Use | NÃO confunda com |
+|---|---|---|
+| compatibilizar interface existente | **Adapter** | Facade (simplifica subsistema inteiro, não 1 classe) |
+| adicionar responsabilidade transparente | **Decorator** | Proxy (controla acesso, mesma interface mas outro intento) / Adapter (muda interface) |
+| trocar algoritmo de fora | **Strategy** | State (muda sozinho conforme estado interno; estados se conhecem) |
+| esconder criação por subclasse | **Factory Method** | Abstract Factory (famílias) / Builder (passo a passo) |
+| eixos independentes que variam | **Bridge** | Strategy (Bridge é decisão estrutural maior; Strategy é tática) |
+
+### Padrões e refactoring — a relação
+
+A fonte (refactoring.guru) trata os dois como complementares: **refactoring** é *"o processo
+sistemático de melhorar código sem criar funcionalidade nova"*, e **code smells** são *"indicadores
+de problemas… fáceis de notar, mas podem ser sintoma de um problema mais profundo."* O fluxo natural:
+
+```
+code smell  →  refactoring  →  (às vezes)  design pattern como destino do refactoring
+```
+
+Os smells **são** os gatilhos da coluna "sintoma" das tabelas acima — `switch(type)` pede Strategy/
+State/Factory; construtor telescópico pede Builder; conditionals sobre status pedem State. O padrão
+é o **alvo** de um refactoring guiado por smell — não um ponto de partida. Comece pelo smell, não
+pelo padrão. Se não há smell, não há padrão a aplicar.
+
+## Checklist — antes de introduzir um padrão
+
+Qualquer "não" é um sinal de over-engineering — pare:
+
+- [ ] Existe um **code smell concreto e nomeável** hoje (não "pode ser que no futuro")?
+- [ ] Consigo justificar por que a indireção extra **se paga** com flexibilidade que vou usar?
+- [ ] Escolhi pela **intenção** do padrão, não pela estrutura parecida (Strategy vs State, Adapter vs Facade)?
+- [ ] Considerei a alternativa mais simples da própria fonte (função/lambda em vez de Strategy; editar a classe em vez de Adapter; DI em vez de Singleton)?
+- [ ] Li a seção **"NÃO use quando"** deste padrão e nenhum item bate no meu caso?
+- [ ] Se é Singleton/Facade/Mediator: tenho como evitar o god-object / o acoplamento global?
+- [ ] Estou no nível certo (design de classe), e não confundindo isto com decisão **arquitetural**?
+
+## Tabela de decisão "use X quando Y"
+
+| Quando Y (o sintoma)… | Use X | Categoria |
+|---|---|---|
+| não sei o tipo concreto a instanciar | Factory Method | Creational |
+| preciso de famílias de objetos compatíveis | Abstract Factory | Creational |
+| construtor com muitos parâmetros opcionais | Builder | Creational |
+| subclasses só diferem na inicialização | Prototype | Creational |
+| (raramente) instância única global controlada | Singleton — prefira DI | Creational |
+| interface incompatível com a minha | Adapter | Structural |
+| explosão de subclasses em 2+ eixos | Bridge | Structural |
+| estrutura em árvore tratada uniformemente | Composite | Structural |
+| empilhar comportamentos em runtime | Decorator | Structural |
+| esconder a complexidade de um subsistema | Facade | Structural |
+| milhões de objetos similares estourando RAM | Flyweight | Structural |
+| controlar acesso (lazy/cache/log/remoto) transparente | Proxy | Structural |
+| múltiplos handlers possíveis, em ordem | Chain of Responsibility | Behavioral |
+| enfileirar / agendar / desfazer operações | Command | Behavioral |
+| percorrer coleção sem expor a estrutura | Iterator | Behavioral |
+| teia N×N de dependências entre componentes | Mediator | Behavioral |
+| snapshot/restore sem violar encapsulamento | Memento | Behavioral |
+| muitos objetos reagindo a um evento | Observer | Behavioral |
+| comportamento muda conforme estado interno | State | Behavioral |
+| trocar variante de algoritmo em runtime | Strategy | Behavioral |
+| algoritmos quase iguais com poucos passos variáveis | Template Method | Behavioral |
+| operações novas sobre hierarquia estável | Visitor | Behavioral |
+| avaliar uma gramática simples recorrente | Interpreter | Behavioral |
+
+> Fonte dos critérios, intents e prós/contras: [refactoring.guru/design-patterns](https://refactoring.guru/design-patterns).
+> O catálogo da fonte cobre 22 padrões; o GoF clássico inclui **Interpreter** (23º), aqui mantido por completude.