@polymorphism-tech/morph-spec 4.6.0 → 4.7.1

package/docs/plans/2026-02-23-ddd-architecture-refactor.md

@@ -0,0 +1,1153 @@
+# DDD Architecture Refactor Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Integrar DDD tático de forma calibrada ao MORPH-SPEC — sem overengineering. 3 níveis de complexidade, detecção automática na fase de design, domain-architect como Tier 2 líder de modelagem de domínio.
+
+**Architecture:** Mantém Clean Architecture como estrutura de camadas. Adiciona DDD tático (Aggregates, Value Objects, Domain Events) como padrão obrigatório calibrado por nível. O `domain-architect` (Tier 2) detecta o nível correto antes de gerar `contracts.cs`. Nível 1 = CRUD simples. Nível 2 = regras de negócio + Aggregate. Nível 3 = múltiplos domínios distintos (opt-in explícito).
+
+**Tech Stack:** Node.js (ESM), Handlebars v2.0, `node:test`, C# templates (não compilados), Markdown.
+
+---
+
+## Contexto Importante
+
+- `framework/agents.json` — 38 agentes, 4 tiers. `ddd-expert` está em Tier 3 sob `dotnet-senior`
+- `framework/templates/code/dotnet/contracts/contracts.cs` — template único flat (domain entity **comentado**)
+- `framework/templates/docs/spec.md` — sem seções de DDD ou complexidade de domínio
+- `framework/skills/level-1-workflows/phase-design/SKILL.md` — sem detecção de nível de domínio
+- `framework/standards/architecture/ddd/` — 3 arquivos existem (aggregates, entities, value-objects) mas não são referenciados na fase de design
+- `test/commands/doctor.test.js` — valida tier sums; Tier 2 hoje = 3 agentes
+- Standards Registry: `framework/standards/STANDARDS.json` — 74 entradas, regenerar após novos standards
+
+---
+
+## Parte A — Standards (base de tudo)
+
+### Task 1: Criar `complexity-levels.md`
+
+**Files:**
+- Create: `framework/standards/architecture/ddd/complexity-levels.md`
+
+**Step 1: Escrever o standard**
+
+```markdown
+# DDD Complexity Levels
+
+> **Scope:** universal
+> **Layer:** 2 (load when: ddd, domain, aggregate, entity, bounded context)
+> **Keywords:** ddd, complexity, aggregate, crud, bounded-context, domain
+
+Define o nível de complexidade de domínio para cada feature. O nível determina qual
+template de contracts.cs será usado e quais padrões DDD são mandatórios.
+
+---
+
+## Os 3 Níveis
+
+### Nível 1 — CRUD
+
+**Quando usar:**
+- Feature é essencialmente Create/Read/Update/Delete
+- Entidade não tem regras de negócio (apenas validações de campos)
+- Nenhum outro domínio precisa reagir às mudanças desta entidade
+- Exemplos: `Category`, `Tag`, `UserProfile`, `Notification`
+
+**O que gerar:**
+- `Entity` simples (sem AggregateRoot)
+- Service interface CRUD
+- DTOs (record)
+- Repository interface básica
+- **SEM** Domain Events, **SEM** Value Objects (a menos que óbvio), **SEM** CQRS
+
+---
+
+### Nível 2 — Business Logic
+
+**Quando usar:**
+- Entidade tem estados com transições controladas por regras (ex: Draft → Confirmed → Shipped)
+- Invariants existem: "só pode cancelar se estiver Ativo"
+- Cálculos derivados (Total, Saldo, Desconto)
+- Outros módulos precisam reagir a mudanças desta entidade
+- Exemplos: `Order`, `Subscription`, `Invoice`, `Project`, `Ticket`
+
+**O que gerar:**
+- `AggregateRoot` com factory method estático
+- Value Objects para tipos com regras (Money, Email, PhoneNumber)
+- Domain Events para mudanças de estado relevantes
+- Commands + Queries (CQRS com MediatR)
+- Repository interface por aggregate root
+- **SEM** Bounded Context isolation (módulos se comunicam diretamente)
+
+---
+
+### Nível 3 — Bounded Context
+
+**Quando usar (opt-in explícito apenas):**
+- Sistema tem 3+ domínios distintos onde o mesmo conceito tem modelos diferentes
+  - Exemplo: "Customer" em Billing ≠ "Customer" em Support
+- Times distintos vão trabalhar em cada domínio
+- Domínios precisam evoluir independentemente
+- Exemplos: plataforma multi-produto, marketplace, ERP
+
+**O que gerar:**
+- Tudo do Nível 2 +
+- Pasta `{BoundedContext}/` em Domain + Application
+- Domain Events para comunicação cross-BC (via MediatR/Service Bus)
+- Referências cross-BC por ID (nunca navigation properties)
+- Glossário de Linguagem Ubíqua por BC
+
+**⚠️ Não use Nível 3 por default.** Declare explicitamente na proposta.
+
+---
+
+## Como Detectar o Nível (fase de design)
+
+O `domain-architect` analisa a proposta e responde:
+
+```
+1. A entidade principal tem estados com transições? → Sim = Nível 2+
+2. Existem invariants de negócio? → Sim = Nível 2+
+3. Outros domínios precisam reagir a mudanças? → Sim = Nível 2+
+4. Diferentes contextos usam modelos diferentes do mesmo conceito? → Sim = Nível 3
+5. O usuário declarou explicitamente Bounded Context? → Sim = Nível 3
+Se nenhuma das anteriores: Nível 1
+```
+
+---
+
+## Anti-Patterns por Nível
+
+| Anti-Pattern | Nível Afetado | Correção |
+|---|---|---|
+| AggregateRoot para CRUD simples | Nível 1 desnecessário | Use Entity simples |
+| Domain Events sem consumidores | Nível 2 excessivo | Remova ou use Nível 1 |
+| Bounded Context para app single-domain | Nível 3 prematuro | Use Nível 2 |
+| Entidade anêmica com regras no Service | Todos | Mova regras para o Aggregate |
+| Value Objects para todo primitivo | Nível 2 excessivo | Só quando há regras/validação |
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*
+```
+
+**Step 2: Verificar que o arquivo foi criado corretamente**
+
+```bash
+ls framework/standards/architecture/ddd/
+```
+Esperado: `aggregates.md`, `complexity-levels.md`, `entities.md`, `value-objects.md`
+
+**Step 3: Commit**
+
+```bash
+git add framework/standards/architecture/ddd/complexity-levels.md
+git commit -m "feat(standards): add DDD complexity levels — Level 1 CRUD, Level 2 Aggregate, Level 3 BC"
+```
+
+---
+
+### Task 2: Criar `bounded-contexts.md`
+
+**Files:**
+- Create: `framework/standards/architecture/ddd/bounded-contexts.md`
+
+**Step 1: Escrever o standard**
+
+```markdown
+# DDD Bounded Contexts
+
+> **Scope:** universal
+> **Layer:** 2 (load when: bounded context, bc, multi-domain, context map)
+> **Keywords:** bounded-context, ddd, domain, ubiquitous-language, context-map
+
+Bounded Context (BC) é a fronteira onde um modelo de domínio tem significado único.
+Use apenas em sistemas com múltiplos domínios distintos (Nível 3 de complexidade).
+
+---
+
+## Estrutura de Pastas (Nível 3)
+
+```
+src/{App}.Domain/
+  Billing/                    ← Bounded Context
+    Aggregates/
+      Subscription.cs
+      Invoice.cs
+    ValueObjects/
+      PlanTier.cs
+      BillingCycle.cs
+    Events/
+      SubscriptionCreatedEvent.cs
+      SubscriptionCancelledEvent.cs
+    Exceptions/
+      SubscriptionNotFoundException.cs
+
+  Orders/                     ← Bounded Context
+    Aggregates/
+      Order.cs
+    ValueObjects/
+      Money.cs
+    Events/
+      OrderConfirmedEvent.cs
+
+src/{App}.Application/
+  Billing/                    ← espelha Domain
+    Commands/
+      CreateSubscriptionCommand.cs
+    Queries/
+      GetActiveSubscriptionQuery.cs
+    Handlers/
+      CreateSubscriptionHandler.cs
+
+src/{App}.Infrastructure/
+  Billing/                    ← espelha Application
+    Repositories/
+      SubscriptionRepository.cs
+    Configurations/
+      SubscriptionConfiguration.cs
+```
+
+---
+
+## Regras de Comunicação Cross-BC
+
+```csharp
+// ✅ CORRETO: referenciar outro BC por ID
+public class Order : AggregateRoot
+{
+    public Guid CustomerId { get; private set; }  // ID, não navigation property
+    // NÃO: public Customer Customer { get; }    // cross-BC navigation PROIBIDO
+}
+
+// ✅ CORRETO: comunicação via Domain Events (MediatR ou Service Bus)
+public class OrderConfirmedHandler : INotificationHandler<OrderConfirmedEvent>
+{
+    // Billing BC reage ao evento do Orders BC
+    public async Task Handle(OrderConfirmedEvent notification, CancellationToken ct)
+    {
+        await _billingService.ChargeForOrderAsync(notification.OrderId, ct);
+    }
+}
+
+// ❌ ERRADO: acesso direto ao repositório de outro BC
+public class OrderService
+{
+    private readonly ICustomerRepository _customerRepo; // cross-BC — PROIBIDO
+}
+```
+
+---
+
+## Linguagem Ubíqua por BC
+
+Cada BC define seu próprio glossário. O mesmo termo pode ter significados diferentes:
+
+| Termo | BC: Orders | BC: Support |
+|-------|-----------|-------------|
+| `Customer` | Quem fez um pedido, tem `Orders[]` | Quem abriu ticket, tem `SLA` e `Priority` |
+| `Status` | `Draft/Confirmed/Shipped` | `Open/InProgress/Resolved` |
+
+Documente em `1-design/ubiquitous-language.md` por feature (ver standard).
+
+---
+
+## Quando NÃO usar Bounded Contexts
+
+- App single-domain (ex: sistema de agendamentos)
+- MVP ou projeto com um único time
+- Quando os "domínios" compartilham o mesmo modelo de dados sem conflito
+
+Em todos esses casos: use Nível 2 (Aggregates sem BC isolation).
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*
+```
+
+**Step 2: Commit**
+
+```bash
+git add framework/standards/architecture/ddd/bounded-contexts.md
+git commit -m "feat(standards): add Bounded Contexts standard — structure, cross-BC rules, when NOT to use"
+```
+
+---
+
+### Task 3: Criar `ubiquitous-language.md`
+
+**Files:**
+- Create: `framework/standards/architecture/ddd/ubiquitous-language.md`
+
+**Step 1: Escrever o standard**
+
+```markdown
+# DDD Ubiquitous Language
+
+> **Scope:** universal
+> **Layer:** 2 (load when: ubiquitous language, glossary, domain language)
+> **Keywords:** ubiquitous-language, ddd, glossary, domain-terms
+
+Linguagem Ubíqua é o vocabulário compartilhado entre devs e domínio de negócio.
+Usada em Nível 2+ para nomear Aggregates, Value Objects, Events e métodos.
+
+---
+
+## Formato do Glossário (output: `ubiquitous-language.md`)
+
+```markdown
+# Ubiquitous Language: {Feature/BoundedContext}
+
+## Termos do Domínio
+
+| Termo | Definição | Contexto | Mapeamento em Código |
+|-------|-----------|----------|---------------------|
+| Subscription | Contrato ativo de uso da plataforma por um tenant | Billing | `Subscription` (AggregateRoot) |
+| PlanTier | Nível do plano (Free/Pro/Enterprise) | Billing | `PlanTier` (ValueObject) |
+| Activation | Ato de ativar uma Subscription após pagamento | Billing | `Subscription.Activate()` |
+| Churn | Cancelamento não-renovado de Subscription | Billing | `SubscriptionCancelledEvent` |
+
+## Estados e Transições
+
+| Estado | Descrição | Transições Permitidas |
+|--------|-----------|----------------------|
+| Draft | Subscription criada, aguardando pagamento | → Active |
+| Active | Subscription paga e em uso | → Suspended, Cancelled |
+| Suspended | Pagamento falhou, acesso bloqueado | → Active, Cancelled |
+| Cancelled | Encerrada definitivamente | (terminal) |
+
+## Invariants em Linguagem Natural
+
+- "Uma Subscription só pode ser Cancelada se estiver Active ou Suspended"
+- "Um Tenant não pode ter duas Subscriptions Active simultaneamente"
+- "PlanTier não pode ser rebaixado durante um ciclo de cobrança ativo"
+```
+
+---
+
+## Regras de Nomenclatura
+
+1. Use termos do glossário como nomes de classe/método — nunca invente sinonimos
+2. Eventos no passado: `OrderConfirmed`, não `OrderConfirmation` ou `ConfirmOrder`
+3. Commands no imperativo: `CreateOrder`, não `OrderCreation`
+4. Value Objects no substantivo: `Money`, `Email`, não `MoneyValue` ou `EmailAddress`
+5. Métodos do Aggregate espelham ações do negócio: `order.Confirm()`, não `order.SetStatusToConfirmed()`
+
+---
+
+## Quando Gerar
+
+- **Nível 2:** Gerar junto com `contracts.cs` na fase de design (seção inline no spec.md)
+- **Nível 3:** Gerar arquivo separado `1-design/ubiquitous-language.md` por BC
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*
+```
+
+**Step 2: Commit**
+
+```bash
+git add framework/standards/architecture/ddd/ubiquitous-language.md
+git commit -m "feat(standards): add Ubiquitous Language standard — glossary format, naming rules, when to generate"
+```
+
+---
+
+### Task 4: Regenerar Standards Registry
+
+**Files:**
+- Modify: `framework/standards/STANDARDS.json` (via script)
+
+**Step 1: Rodar o script gerador**
+
+```bash
+node scripts/generate-standards-registry.js
+```
+
+**Step 2: Verificar que os 3 novos standards foram adicionados**
+
+```bash
+node -e "
+const s = JSON.parse(require('fs').readFileSync('framework/standards/STANDARDS.json'));
+const ddd = s.filter(x => x.id.includes('ddd'));
+console.log(ddd.map(x => x.id));
+"
+```
+Esperado: lista incluindo `complexity-levels`, `bounded-contexts`, `ubiquitous-language`.
+
+**Step 3: Commit**
+
+```bash
+git add framework/standards/STANDARDS.json
+git commit -m "chore(standards): regenerate registry — 3 new DDD standards (77 total)"
+```
+
+---
+
+## Parte B — Templates
+
+### Task 5: Atualizar `spec.md` — Adicionar seções DDD
+
+**Files:**
+- Modify: `framework/templates/docs/spec.md`
+
+Adicionar **após** a seção `## Technical Design` e **antes** de `## UI/UX Design`:
+
+```markdown
+---
+
+## Domain Complexity
+
+**Nível:** {1 — CRUD / 2 — Business Logic / 3 — Bounded Context}
+
+**Justificativa:** {Por que este nível foi escolhido — mencionar invariants, eventos ou BCs se Nível 2+}
+
+**Padrões Aplicados:**
+- {Nível 1: Entity simples, Service CRUD, DTOs}
+- {Nível 2: AggregateRoot, Value Objects, Domain Events, CQRS}
+- {Nível 3: Bounded Context isolation, cross-BC events, ubiquitous language por BC}
+
+**Padrões Omitidos e Motivo:**
+- {ex: Bounded Contexts — sistema single-domain, desnecessário}
+
+---
+
+## Aggregate Blueprint (Nível 2+ apenas)
+
+> Omitir esta seção se Nível 1 (CRUD).
+
+### Aggregate Root: {EntityName}
+
+**Invariants:**
+- {Invariant 1 em linguagem natural}
+- {Invariant 2}
+
+**Estados e Transições:**
+```
+{Status.Draft} → Confirm() → {Status.Confirmed} → Ship() → {Status.Shipped}
+                            → Cancel() → {Status.Cancelled}
+```
+
+**Domain Events:**
+- `{EntityName}CreatedEvent` — publicado ao criar
+- `{EntityName}ConfirmedEvent` — publicado ao confirmar
+
+**Value Objects:**
+- `{ValueObjectName}` — {por que não é um primitivo simples}
+
+**Referências Cross-Aggregate (por ID apenas):**
+- `{OtherEntity}Id: Guid` — nunca navigation property
+
+### Ubiquitous Language (Nível 2)
+
+| Termo | Definição | Código |
+|-------|-----------|--------|
+| {Termo} | {Definição do negócio} | `{ClassName.MethodName()}` |
+
+---
+```
+
+**Step 1: Ler o template atual para confirmar localização exata**
+
+```bash
+# Verificar linha da seção Technical Design
+grep -n "Technical Design\|UI/UX Design" framework/templates/docs/spec.md
+```
+
+**Step 2: Editar o template** — inserir o bloco acima entre as duas seções.
+
+**Step 3: Verificar que o template ainda renderiza corretamente**
+
+```bash
+npx morph-spec template validate docs/spec
+```
+
+**Step 4: Commit**
+
+```bash
+git add framework/templates/docs/spec.md
+git commit -m "feat(templates): add Domain Complexity + Aggregate Blueprint sections to spec.md"
+```
+
+---
+
+### Task 6: Criar `contracts-level1.cs` (CRUD)
+
+**Files:**
+- Create: `framework/templates/code/dotnet/contracts/contracts-level1.cs`
+
+O template Nível 1 é o que existe hoje, porém sem domain entity comentada e sem Aggregate patterns. Cópia limpa do atual com ajustes:
+
+```csharp
+// ============================================================
+// CONTRACTS: {{titleCase FEATURE_NAME}} — Level 1 (CRUD)
+// Generated by MORPH Framework | Date: {{DATE}}
+// Domain Complexity: CRUD — Entity simples, sem invariants de negócio
+// ============================================================
+
+using System;
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace {{NAMESPACE}}.Application.Features.{{pascalCase FEATURE_NAME}};
+
+#region Service Interfaces
+
+public interface I{{pascalCase FEATURE_NAME}}Service
+{
+    Task<{{pascalCase FEATURE_NAME}}Dto?> GetByIdAsync(Guid id, CancellationToken ct = default);
+    Task<List<{{pascalCase FEATURE_NAME}}Dto>> GetAllAsync(CancellationToken ct = default);
+    Task<{{pascalCase FEATURE_NAME}}Dto> CreateAsync(Create{{pascalCase FEATURE_NAME}}Request request, CancellationToken ct = default);
+    Task UpdateAsync(Guid id, Update{{pascalCase FEATURE_NAME}}Request request, CancellationToken ct = default);
+    Task DeleteAsync(Guid id, CancellationToken ct = default);
+}
+
+#endregion
+
+#region DTOs
+
+public record {{pascalCase FEATURE_NAME}}Dto(
+    Guid Id,
+    string Name,
+    DateTime CreatedAt,
+    DateTime? UpdatedAt
+);
+
+public record Create{{pascalCase FEATURE_NAME}}Request(
+    string Name
+    // Add fields
+);
+
+public record Update{{pascalCase FEATURE_NAME}}Request(
+    string Name
+    // Add fields
+);
+
+#endregion
+
+#region Repository Interface
+
+public interface I{{pascalCase FEATURE_NAME}}Repository
+{
+    Task<{{pascalCase FEATURE_NAME}}?> GetByIdAsync(Guid id, CancellationToken ct = default);
+    Task<List<{{pascalCase FEATURE_NAME}}>> GetAllAsync(CancellationToken ct = default);
+    Task AddAsync({{pascalCase FEATURE_NAME}} entity, CancellationToken ct = default);
+    void Update({{pascalCase FEATURE_NAME}} entity);
+    void Remove({{pascalCase FEATURE_NAME}} entity);
+    Task SaveChangesAsync(CancellationToken ct = default);
+}
+
+#endregion
+
+#region Exceptions
+
+public class {{pascalCase FEATURE_NAME}}NotFoundException(Guid id)
+    : Exception($"{{pascalCase FEATURE_NAME}} '{id}' not found.");
+
+#endregion
+```
+
+**Step 1: Criar o arquivo** com o conteúdo acima.
+
+**Step 2: Verificar que o template renderiza sem erros**
+
+```bash
+npx morph-spec template render \
+  code/dotnet/contracts/contracts-level1.cs \
+  /tmp/test-level1.cs \
+  '{"FEATURE_NAME":"category","NAMESPACE":"MyApp","DATE":"2026-02-23"}'
+cat /tmp/test-level1.cs
+```
+Esperado: C# válido sem placeholders Handlebars não substituídos.
+
+**Step 3: Commit**
+
+```bash
+git add framework/templates/code/dotnet/contracts/contracts-level1.cs
+git commit -m "feat(templates): add contracts-level1.cs — CRUD pattern, no Domain Events or Aggregates"
+```
+
+---
+
+### Task 7: Criar `contracts-level2.cs` (Aggregate)
+
+**Files:**
+- Create: `framework/templates/code/dotnet/contracts/contracts-level2.cs`
+
+```csharp
+// ============================================================
+// CONTRACTS: {{titleCase FEATURE_NAME}} — Level 2 (Business Logic)
+// Generated by MORPH Framework | Date: {{DATE}}
+// Domain Complexity: Aggregate com invariants, Domain Events, CQRS
+// Ref: framework/standards/architecture/ddd/aggregates.md
+// ============================================================
+
+using System;
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+using MediatR;
+
+namespace {{NAMESPACE}}.Domain.{{pascalCase FEATURE_NAME}}s;
+
+// ===== AGGREGATE ROOT =====
+// Implemente em: Domain/{{pascalCase FEATURE_NAME}}s/Aggregates/{{pascalCase FEATURE_NAME}}.cs
+//
+// Invariants documentados no spec.md > Aggregate Blueprint:
+//   - {Invariant 1}
+//   - {Invariant 2}
+//
+// public sealed class {{pascalCase FEATURE_NAME}} : AggregateRoot
+// {
+//     private {{pascalCase FEATURE_NAME}}() { } // EF constructor
+//
+//     public static {{pascalCase FEATURE_NAME}} Create(/* params */) { /* validate + RaiseDomainEvent */ }
+//     public void {Action}() { /* validate invariant + mutate + RaiseDomainEvent */ }
+// }
+
+// ===== VALUE OBJECTS =====
+// Implemente em: Domain/{{pascalCase FEATURE_NAME}}s/ValueObjects/
+// (inclua apenas se houver primitivos com regras de validação/negócio)
+
+// ===== DOMAIN EVENTS =====
+
+namespace {{NAMESPACE}}.Domain.{{pascalCase FEATURE_NAME}}s.Events;
+
+public record {{pascalCase FEATURE_NAME}}CreatedEvent(
+    Guid {{pascalCase FEATURE_NAME}}Id,
+    Guid UserId
+) : DomainEvent;
+
+// Adicione eventos para cada mudança de estado relevante
+// public record {{pascalCase FEATURE_NAME}}ConfirmedEvent(Guid {{pascalCase FEATURE_NAME}}Id) : DomainEvent;
+
+// ===== COMMANDS (CQRS) =====
+
+namespace {{NAMESPACE}}.Application.{{pascalCase FEATURE_NAME}}s.Commands;
+
+public record Create{{pascalCase FEATURE_NAME}}Command(
+    Guid UserId
+    // Add fields
+) : IRequest<Create{{pascalCase FEATURE_NAME}}Result>;
+
+public record Create{{pascalCase FEATURE_NAME}}Result(Guid Id);
+
+// public record Update{{pascalCase FEATURE_NAME}}Command(...) : IRequest;
+// public record Delete{{pascalCase FEATURE_NAME}}Command(Guid Id) : IRequest;
+
+// ===== QUERIES =====
+
+namespace {{NAMESPACE}}.Application.{{pascalCase FEATURE_NAME}}s.Queries;
+
+public record Get{{pascalCase FEATURE_NAME}}Query(Guid Id) : IRequest<{{pascalCase FEATURE_NAME}}Dto?>;
+public record List{{pascalCase FEATURE_NAME}}sQuery(/* filters */) : IRequest<List<{{pascalCase FEATURE_NAME}}Dto>>;
+
+// ===== DTOs (read models — nunca expõe o Aggregate) =====
+
+namespace {{NAMESPACE}}.Application.{{pascalCase FEATURE_NAME}}s;
+
+public record {{pascalCase FEATURE_NAME}}Dto(
+    Guid Id,
+    string Status,
+    DateTime CreatedAt,
+    DateTime? UpdatedAt
+);
+
+// ===== REPOSITORY (um por Aggregate Root) =====
+
+namespace {{NAMESPACE}}.Domain.{{pascalCase FEATURE_NAME}}s;
+
+public interface I{{pascalCase FEATURE_NAME}}Repository
+{
+    Task<{{pascalCase FEATURE_NAME}}?> GetAsync(Guid id, CancellationToken ct = default);
+    Task AddAsync({{pascalCase FEATURE_NAME}} aggregate, CancellationToken ct = default);
+    Task UpdateAsync({{pascalCase FEATURE_NAME}} aggregate, CancellationToken ct = default);
+    Task<bool> ExistsAsync(Guid id, CancellationToken ct = default);
+}
+
+// ===== EXCEPTIONS =====
+
+public class {{pascalCase FEATURE_NAME}}NotFoundException(Guid id)
+    : DomainException($"{{pascalCase FEATURE_NAME}} '{id}' not found.");
+
+public class {{pascalCase FEATURE_NAME}}InvalidStateException(string message)
+    : DomainException(message);
+```
+
+**Step 1: Criar o arquivo.**
+
+**Step 2: Verificar renderização**
+
+```bash
+npx morph-spec template render \
+  code/dotnet/contracts/contracts-level2.cs \
+  /tmp/test-level2.cs \
+  '{"FEATURE_NAME":"order","NAMESPACE":"MyApp","DATE":"2026-02-23"}'
+```
+Esperado: sem placeholders não resolvidos, namespaces corretos.
+
+**Step 3: Commit**
+
+```bash
+git add framework/templates/code/dotnet/contracts/contracts-level2.cs
+git commit -m "feat(templates): add contracts-level2.cs — Aggregate, Domain Events, CQRS pattern"
+```
+
+---
+
+### Task 8: Criar `contracts-level3.cs` (Bounded Context)
+
+**Files:**
+- Create: `framework/templates/code/dotnet/contracts/contracts-level3.cs`
+
+Nível 3 estende o Nível 2 com isolamento de BC e comunicação cross-BC explícita:
+
+```csharp
+// ============================================================
+// CONTRACTS: {{titleCase FEATURE_NAME}} — Level 3 (Bounded Context)
+// Generated by MORPH Framework | Date: {{DATE}}
+// Bounded Context: {{BOUNDED_CONTEXT}}
+// Ref: framework/standards/architecture/ddd/bounded-contexts.md
+// ============================================================
+//
+// ⚠️  LEMBRE-SE DAS REGRAS DE BC:
+//   1. Referências cross-BC APENAS por ID (nunca navigation property)
+//   2. Comunicação cross-BC APENAS via Domain Events
+//   3. Cada BC tem seu próprio repositório (nunca compartilhar DbContext)
+//   4. Linguagem Ubíqua documentada em 1-design/ubiquitous-language.md
+
+// ===== TUDO DO NÍVEL 2 + ISOLAMENTO DE BC =====
+// (inclua todos os contracts do Level 2 aqui com o namespace do BC)
+
+namespace {{NAMESPACE}}.Domain.{{BOUNDED_CONTEXT}}.{{pascalCase FEATURE_NAME}}s;
+
+// Aggregates, Value Objects, Domain Events — mesma estrutura do Level 2
+// mas dentro do namespace do Bounded Context
+
+// ===== INTEGRATION EVENTS (comunicação cross-BC) =====
+
+namespace {{NAMESPACE}}.Domain.{{BOUNDED_CONTEXT}}.IntegrationEvents;
+
+// Integration Events são diferentes de Domain Events:
+// - Domain Event: dentro do mesmo BC (MediatR, síncrono)
+// - Integration Event: cross-BC (Service Bus ou MediatR INotification, assíncrono)
+
+public record {{pascalCase FEATURE_NAME}}IntegrationEvent(
+    Guid {{pascalCase FEATURE_NAME}}Id,
+    string EventType,
+    DateTime OccurredAt
+);
+
+// ===== CROSS-BC REFERENCES (por ID apenas) =====
+//
+// Exemplo de como referenciar outro BC:
+// public sealed class {{pascalCase FEATURE_NAME}} : AggregateRoot
+// {
+//     public Guid ExternalBcEntityId { get; private set; }  // ✅ por ID
+//     // public ExternalEntity External { get; }             // ❌ proibido
+// }
+```
+
+**Step 1: Criar o arquivo.**
+
+**Step 2: Verificar renderização com BOUNDED_CONTEXT**
+
+```bash
+npx morph-spec template render \
+  code/dotnet/contracts/contracts-level3.cs \
+  /tmp/test-level3.cs \
+  '{"FEATURE_NAME":"subscription","NAMESPACE":"MyApp","BOUNDED_CONTEXT":"Billing","DATE":"2026-02-23"}'
+```
+
+**Step 3: Commit**
+
+```bash
+git add framework/templates/code/dotnet/contracts/contracts-level3.cs
+git commit -m "feat(templates): add contracts-level3.cs — Bounded Context, Integration Events, cross-BC rules"
+```
+
+---
+
+### Task 9: Criar template de estrutura de pastas por nível
+
+**Files:**
+- Create: `framework/templates/project-structure/dotnet-ddd.md`
+
+```markdown
+# Estrutura de Pastas .NET + DDD
+
+> Template de referência. O nível determina quais subpastas são criadas.
+> Gerado durante a fase de Design baseado no Domain Complexity Level.
+
+## Nível 1 — CRUD
+
+```
+src/{App}.Domain/
+  Entities/
+    {EntityName}.cs
+  Interfaces/
+    I{EntityName}Repository.cs
+
+src/{App}.Application/
+  Features/{FeatureName}/
+    {FeatureName}Service.cs
+    DTOs/
+      {FeatureName}Dto.cs
+      Create{FeatureName}Request.cs
+```
+
+## Nível 2 — Business Logic
+
+```
+src/{App}.Domain/
+  {EntityName}s/                 ← pasta por aggregate
+    Aggregates/
+      {EntityName}.cs            ← AggregateRoot
+    ValueObjects/
+      {ValueObjectName}.cs
+    Events/
+      {EntityName}CreatedEvent.cs
+    Exceptions/
+      {EntityName}NotFoundException.cs
+    I{EntityName}Repository.cs
+
+src/{App}.Application/
+  {EntityName}s/
+    Commands/
+      Create{EntityName}Command.cs
+      Create{EntityName}Handler.cs
+    Queries/
+      Get{EntityName}Query.cs
+      Get{EntityName}Handler.cs
+    {EntityName}Dto.cs
+```
+
+## Nível 3 — Bounded Context
+
+```
+src/{App}.Domain/
+  {BoundedContext}/              ← pasta por BC
+    {EntityName}s/               ← mesma estrutura do Nível 2
+      Aggregates/
+      ValueObjects/
+      Events/
+    IntegrationEvents/           ← eventos cross-BC
+
+src/{App}.Application/
+  {BoundedContext}/              ← espelha Domain
+    {EntityName}s/
+      Commands/
+      Queries/
+```
+```
+
+**Step 1: Criar o arquivo.**
+
+**Step 2: Commit**
+
+```bash
+git add framework/templates/project-structure/dotnet-ddd.md
+git commit -m "feat(templates): add dotnet-ddd.md folder structure template — 3 levels"
+```
+
+---
+
+## Parte C — Agentes
+
+### Task 10: Elevar `domain-architect` para Tier 2 em `agents.json`
+
+**Files:**
+- Modify: `framework/agents.json`
+
+**Contexto:**
+- `ddd-expert` está em Tier 3 na lista de coordinatedBy `dotnet-senior`
+- Precisamos: elevar para Tier 2, renomear para `domain-architect`, remover de `dotnet-senior`
+
+**Step 1: Ler o agents.json para localizar ddd-expert e dotnet-senior**
+
+```bash
+node -e "
+const a = JSON.parse(require('fs').readFileSync('framework/agents.json'));
+const ddd = a.agents.find(x => x.id === 'ddd-expert');
+const dotnet = a.agents.find(x => x.id === 'dotnet-senior');
+console.log('ddd-expert tier:', ddd?.tier);
+console.log('ddd-expert:', JSON.stringify(ddd, null, 2));
+console.log('dotnet-senior coordinates:', dotnet?.coordinates);
+"
+```
+
+**Step 2: Aplicar as mudanças no agents.json**
+
+Mudanças necessárias:
+1. Localizar o agente `ddd-expert` (Tier 3)
+2. Alterar:
+   - `id`: `ddd-expert` → `domain-architect`
+   - `tier`: `3` → `2`
+   - `name`: atualizar para "Domain Architect"
+   - `role`: "Domain modeling leader — detects complexity level, designs aggregates and bounded contexts"
+   - `alwaysActive`: `false` → `true` (ativo nas fases design + implement)
+   - `activePhases`: adicionar `["design", "implement"]`
+   - `coordinates`: adicionar `["ef-modeler", "event-architect"]` (especialistas que o domain-architect precisa)
+   - `reportsTo`: `"dotnet-senior"` → `"standards-architect"`
+3. Em `dotnet-senior.coordinates`: remover `"ddd-expert"`, adicionar `"domain-architect"` como peer (não subordinado)
+4. Atualizar tier sums: Tier 2 de `3` → `4`
+5. Atualizar total de agentes se necessário (renomear não muda count)
+6. Atualizar `version` de `3.1.0-hierarchical` → `3.2.0-hierarchical`
+
+**Step 3: Verificar integridade do JSON**
+
+```bash
+node -e "
+const a = JSON.parse(require('fs').readFileSync('framework/agents.json'));
+const tier2 = a.agents.filter(x => x.tier === 2);
+console.log('Tier 2 agents:', tier2.map(x => x.id));
+console.log('Count:', tier2.length);
+const da = a.agents.find(x => x.id === 'domain-architect');
+console.log('domain-architect:', da ? 'FOUND' : 'NOT FOUND');
+"
+```
+Esperado: Tier 2 com 4 agentes: `dotnet-senior`, `infra-architect`, `ui-designer`, `domain-architect`.
+
+**Step 4: Commit**
+
+```bash
+git add framework/agents.json
+git commit -m "feat(agents): elevate domain-architect to Tier 2 — leads domain modeling, detects complexity level"
+```
+
+---
+
+## Parte D — Skills
+
+### Task 11: Atualizar `phase-design` — Adicionar detecção de nível de domínio
+
+**Files:**
+- Modify: `framework/skills/level-1-workflows/phase-design/SKILL.md`
+
+Adicionar **entre** "Passo 1: Carregar Contexto" e "Passo 2: Analisar Código Existente":
+
+```markdown
+### Passo 1.5: Detectar Nível de Domínio (domain-architect)
+
+**⚠️ OBRIGATÓRIO:** Execute antes de gerar qualquer contrato.
+
+**Ref:** `framework/standards/architecture/ddd/complexity-levels.md`
+
+O `domain-architect` analisa a proposta e determina o nível:
+
+```
+Responda às perguntas (da proposal.md):
+1. A entidade principal tem estados com transições? (Draft → Confirmed → Shipped)
+2. Existem invariants de negócio? ("só cancela se estiver Ativo")
+3. Cálculos derivados existem? (Total, Saldo, Desconto)
+4. Outros módulos precisam reagir a mudanças? (Domain Events com consumidores)
+5. O usuário declarou Bounded Context na proposta?
+
+→ Nenhuma acima: Nível 1 (CRUD)
+→ 1-4 verdadeiros: Nível 2 (Business Logic)
+→ 5 verdadeiro OU múltiplos domínios com modelos conflitantes: Nível 3 (BC)
+```
+
+**Documente no spec.md** (seção Domain Complexity) antes de continuar.
+
+**Template a usar no Passo 4:**
+
+| Nível | Template |
+|-------|----------|
+| 1 | `code/dotnet/contracts/contracts-level1.cs` |
+| 2 | `code/dotnet/contracts/contracts-level2.cs` |
+| 3 | `code/dotnet/contracts/contracts-level3.cs` |
+
+**Para Nível 2+:** Defina o Aggregate Blueprint (section no spec.md) antes de gerar contracts.cs.
+
+**Para Nível 3:** Adicione `BOUNDED_CONTEXT` como variável ao renderizar o template.
+```
+
+**Step 1: Editar o SKILL.md** — inserir o bloco acima na posição correta.
+
+**Step 2: Verificar que a referência ao template de complexity-levels.md está correta**
+
+```bash
+grep -n "complexity-levels" framework/skills/level-1-workflows/phase-design/SKILL.md
+```
+
+**Step 3: Commit**
+
+```bash
+git add framework/skills/level-1-workflows/phase-design/SKILL.md
+git commit -m "feat(skills): add domain complexity detection step to phase-design — levels 1/2/3 drive template choice"
+```
+
+---
+
+## Parte E — Tests
+
+### Task 12: Atualizar testes do doctor para Tier 2 = 4 agentes
+
+**Files:**
+- Modify: `test/commands/doctor.test.js`
+
+**Step 1: Ler o arquivo de teste para localizar as asserções de tier**
+
+```bash
+grep -n "tier\|Tier\|domain-architect\|ddd-expert" test/commands/doctor.test.js
+```
+
+**Step 2: Atualizar as asserções**
+
+Mudar qualquer asserção que espera Tier 2 = 3 agentes para Tier 2 = 4 agentes.
+Mudar referências a `ddd-expert` para `domain-architect` se existirem.
+
+**Step 3: Rodar os testes do doctor**
+
+```bash
+node --test test/commands/doctor.test.js
+```
+Esperado: todos os testes passam.
+
+**Step 4: Se falhar**, revisar o agents.json — verificar que tier sums no JSON batem com o que o doctor valida.
+
+**Step 5: Commit**
+
+```bash
+git add test/commands/doctor.test.js
+git commit -m "test(doctor): update tier-2 count to 4 — domain-architect elevated from Tier 3"
+```
+
+---
+
+### Task 13: Adicionar testes de renderização dos 3 templates de contracts
+
+**Files:**
+- Create: `test/templates/contracts-levels.test.js`
+
+**Step 1: Escrever os testes**
+
+```javascript
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { execSync } from 'node:child_process';
+import { existsSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+const BASE_VARS = { NAMESPACE: 'MyApp', DATE: '2026-01-01' };
+
+function renderTemplate(templateId, vars) {
+  const out = join(tmpdir(), `morph-test-${Date.now()}.cs`);
+  const varsJson = JSON.stringify({ ...BASE_VARS, ...vars });
+  execSync(`node bin/morph-spec.js template render "${templateId}" "${out}" '${varsJson}'`);
+  const content = require('fs').readFileSync(out, 'utf8');
+  try { unlinkSync(out); } catch {}
+  return content;
+}
+
+test('Level 1 contracts render without Handlebars placeholders', () => {
+  const out = renderTemplate('code/dotnet/contracts/contracts-level1.cs', {
+    FEATURE_NAME: 'category'
+  });
+  assert.ok(!out.includes('{{'), 'Should have no unresolved Handlebars');
+  assert.ok(out.includes('ICategoryService'), 'Should contain service interface');
+  assert.ok(!out.includes('AggregateRoot'), 'Level 1 should NOT have AggregateRoot');
+  assert.ok(!out.includes('DomainEvent'), 'Level 1 should NOT have Domain Events');
+});
+
+test('Level 2 contracts render without Handlebars placeholders', () => {
+  const out = renderTemplate('code/dotnet/contracts/contracts-level2.cs', {
+    FEATURE_NAME: 'order'
+  });
+  assert.ok(!out.includes('{{'), 'Should have no unresolved Handlebars');
+  assert.ok(out.includes('DomainEvent'), 'Level 2 should have Domain Events');
+  assert.ok(out.includes('IRequest'), 'Level 2 should have CQRS commands');
+  assert.ok(out.includes('IOrderRepository'), 'Level 2 should have Repository');
+});
+
+test('Level 3 contracts render with BOUNDED_CONTEXT variable', () => {
+  const out = renderTemplate('code/dotnet/contracts/contracts-level3.cs', {
+    FEATURE_NAME: 'subscription',
+    BOUNDED_CONTEXT: 'Billing'
+  });
+  assert.ok(!out.includes('{{'), 'Should have no unresolved Handlebars');
+  assert.ok(out.includes('Billing'), 'Should include Bounded Context name');
+  assert.ok(out.includes('IntegrationEvent'), 'Level 3 should have Integration Events');
+});
+
+test('Level 1 uses Guid not int for Id', () => {
+  const out = renderTemplate('code/dotnet/contracts/contracts-level1.cs', {
+    FEATURE_NAME: 'tag'
+  });
+  assert.ok(out.includes('Guid id'), 'Should use Guid not int');
+  assert.ok(!out.includes('int id'), 'Should NOT use int id');
+});
+```
+
+**Step 2: Rodar os testes**
+
+```bash
+node --test test/templates/contracts-levels.test.js
+```
+Esperado: 4 testes passam.
+
+**Step 3: Rodar a suite completa para garantir nada quebrou**
+
+```bash
+node --test
+```
+Esperado: todos os testes anteriores continuam passando.
+
+**Step 4: Commit**
+
+```bash
+git add test/templates/contracts-levels.test.js
+git commit -m "test(templates): add Level 1/2/3 contracts rendering tests — 4 tests"
+```
+
+---
+
+## Verificação Final
+
+```bash
+# 1. Suite completa de testes
+node --test
+
+# 2. Verificar standards adicionados
+npx morph-spec standards --list --category ddd
+
+# 3. Verificar templates existem
+ls framework/templates/code/dotnet/contracts/
+
+# 4. Verificar domain-architect no Tier 2
+node -e "
+const a = JSON.parse(require('fs').readFileSync('framework/agents.json'));
+const tier2 = a.agents.filter(x => x.tier === 2).map(x => x.id);
+console.log('Tier 2:', tier2);
+"
+
+# 5. Verificar phase-design skill atualizado
+grep -n "1.5\|Detectar Nível\|complexity-levels" \
+  framework/skills/level-1-workflows/phase-design/SKILL.md
+```
+
+---
+
+## Resumo das Mudanças
+
+| Categoria | Arquivos | Tipo |
+|-----------|---------|------|
+| Standards | `complexity-levels.md`, `bounded-contexts.md`, `ubiquitous-language.md` | Novo |
+| Standards | `STANDARDS.json` | Atualizado (77 entradas) |
+| Templates | `contracts-level1.cs`, `contracts-level2.cs`, `contracts-level3.cs` | Novo |
+| Templates | `spec.md` | Atualizado (+2 seções) |
+| Templates | `project-structure/dotnet-ddd.md` | Novo |
+| Agents | `agents.json` | Atualizado (domain-architect → Tier 2) |
+| Skills | `phase-design/SKILL.md` | Atualizado (+Passo 1.5) |
+| Tests | `doctor.test.js` | Atualizado (tier 2 count) |
+| Tests | `contracts-levels.test.js` | Novo (4 testes) |
+
+**13 tarefas — ~2h de execução com TDD.**
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*