spec-first-claude 0.2.0 → 0.4.0

package/templates/.claude/commands/design.md

@@ -1,107 +1,107 @@
-# /design $ARGUMENTS
-
-Skill atômica de design. Lê PRD/TRD aprovado e gera SDD.
-$ARGUMENTS = nome (ex: setup_projeto, feat_cadastro_cliente)
-
-## Agente: Architect (Opus)
-Técnico e preciso. Gera contratos completos. Toda decisão tem justificativa.
-
-## Pré-condições
-
-| # | Validação | Se falhar |
-|---|-----------|-----------|
-| 1 | $ARGUMENTS informado | Parar |
-| 2 | `.context.md` existe com status `extract_done` ou `approved` | Se anterior → "/extract primeiro". Se posterior → "SDD já gerado" |
-| 3 | PRD.md ou TRD.md existe | Parar → "/extract primeiro" |
-| 4 | `docs/Estrutura/` populado (para features) | Parar → "/setup-projeto primeiro" (não aplica para tipo=setup) |
-
-## Passos
-
-### 1. Checkpoint de aprovação
-Se status é `extract_done`:
-- Perguntar: "O PRD/TRD foi revisado e está aprovado? (s/n)"
-- Se SIM → atualizar .context.md para `approved` → continuar
-- Se NÃO → parar
-
-### 2. Verificar ambiguidades
-- Ler seção de ambiguidades (§13 PRD / §9 TRD)
-- Se há perguntas sem resposta → PARAR, listar pendentes
-
-### 3. Gerar docs/Estrutura/ (APENAS para setup)
-
-> Este passo só executa quando tipo=setup. Para features, docs/Estrutura/ já existe.
-
-Ler TRD e gerar os 8 docs de `docs/Estrutura/` usando os templates correspondentes:
-
-| TRD Seção | Doc gerado | Template |
-|-----------|-----------|---------|
-| §1 Visão + §8 Módulos | Visao.md | `_templates/estrutura/Visao.template.md` |
-| §2 Stack | Stack.md | `_templates/estrutura/Stack.template.md` |
-| §3 Arquitetura | Arquitetura.md | `_templates/estrutura/Arquitetura.template.md` |
-| §4 Modelo de Dados | Modelo_Dados.md | `_templates/estrutura/Modelo_Dados.template.md` |
-| §5 API | API.md | `_templates/estrutura/API.template.md` |
-| §6 Infra | Infraestrutura.md | `_templates/estrutura/Infraestrutura.template.md` |
-| §7 Segurança | Seguranca.md | `_templates/estrutura/Seguranca.template.md` |
-| SDD §2 (após gerar) | ADRs.md | `_templates/estrutura/ADRs.template.md` |
-
-Regras:
-- Ler template → preencher TODAS seções com dados do TRD
-- Remover bloco `<!-- INSTRUÇÕES -->` do doc gerado
-- Changelog inicia vazio (primeira geração)
-- Se TRD não tem dados pra uma seção → marcar "A definir"
-- ADRs.md é gerado APÓS o SDD (usa §2 Decisões de Design)
-
-### 3b. Gerar `projetos.yaml` (APENAS para setup)
-
-Mapeia a arquitetura do TRD §3 para repositórios independentes.
-Cada serviço = 1 repo. Os repos serão criados/clonados pelo /dev (INFRA-001).
-
-1. Identificar serviços separados no TRD §3 (api, worker, web, mobile, etc.)
-2. Perguntar ao usuário:
-   - Organização/usuário do GitHub (ex: `empresa`)
-   - Nome base do projeto (ex: `meu-projeto`)
-   - Se algum repo já existe (para clonar em vez de criar)
-3. Gerar `projetos.yaml` na raiz usando template `projetos.template.yaml`
-4. Mapear áreas de task para repos:
-   - BACK → api (ou worker, se separado)
-   - BANCO → api (se usa EF migrations) ou repo próprio
-   - FRONT → web
-   - MOBILE → mobile
-   - INFRA → todos (cross-repo)
-5. Validar: cada área DEVE mapear para exatamente 1 repo
-
-**Regra**: Se o TRD indica API e Worker como serviços separados, DEVEM ser repos separados.
-Nunca juntar serviços que o TRD definiu como distintos.
-
-### 4. Carregar contexto
-- PRD.md ou TRD.md completo
-- `docs/Estrutura/` (agora já populado, mesmo no setup)
-- `docs/Desenvolvimento/rules.md`
-- Template `sdd.template.md`
-
-### 5. Gerar SDD
-11 seções obrigatórias (usar template). Para cada seção:
-- §1 Visão geral — escopo claro
-- §2 Decisões de design — mini-ADRs com justificativa
-- §3 Modelo de dados — tipos EXATOS, constraints, índices
-- §4 Regras e validações — ref PRD §N RN-NNN, mensagens de erro
-- §5 Endpoints API — contratos JSON completos, erros com códigos
-- §6 Componentes e telas — estados (loading/empty/error/success)
-- §7 Fluxos de dados — sequências front→back
-- §8 Integrações externas — timeout, retry, fallback
-- §9 Estratégia de testes — framework, estrutura, CAs mapeados
-- §10 Fora do escopo — lista explícita
-- §11 Delta Specs — ADDED/MODIFIED/REMOVED
-
-**Setup**: §4-§8 podem ser N/A (normal).
-**Feature**: todas seções aplicáveis preenchidas.
-
-### 6. Gerar ADRs.md (setup — complemento do passo 3)
-Após gerar SDD §2, criar ADRs.md com as decisões iniciais de arquitetura.
-
-### 7. Atualizar `.context.md`
-```yaml
-status: "design_done"
-ultima_skill: "/design"
-atualizado_em: "{{ISO_DATETIME}}"
-```
+# /design $ARGUMENTS
+
+Skill atômica de design. Lê PRD/TRD aprovado e gera SDD.
+$ARGUMENTS = nome (ex: setup_projeto, feat_cadastro_cliente)
+
+## Agente: Architect (Opus)
+Técnico e preciso. Gera contratos completos. Toda decisão tem justificativa.
+
+## Pré-condições
+
+| # | Validação | Se falhar |
+|---|-----------|-----------|
+| 1 | $ARGUMENTS informado | Parar |
+| 2 | `.context.md` existe com status `extract_done` ou `approved` | Se anterior → "/extract primeiro". Se posterior → "SDD já gerado" |
+| 3 | PRD.md ou TRD.md existe | Parar → "/extract primeiro" |
+| 4 | `docs/Estrutura/` populado (para features) | Parar → "/setup-projeto primeiro" (não aplica para tipo=setup) |
+
+## Passos
+
+### 1. Checkpoint de aprovação
+Se status é `extract_done`:
+- Perguntar: "O PRD/TRD foi revisado e está aprovado? (s/n)"
+- Se SIM → atualizar .context.md para `approved` → continuar
+- Se NÃO → parar
+
+### 2. Verificar ambiguidades
+- Ler seção de ambiguidades (§13 PRD / §9 TRD)
+- Se há perguntas sem resposta → PARAR, listar pendentes
+
+### 3. Gerar docs/Estrutura/ (APENAS para setup)
+
+> Este passo só executa quando tipo=setup. Para features, docs/Estrutura/ já existe.
+
+Ler TRD e gerar os 8 docs de `docs/Estrutura/` usando os templates correspondentes:
+
+| TRD Seção | Doc gerado | Template |
+|-----------|-----------|---------|
+| §1 Visão + §8 Módulos | Visao.md | `_templates/estrutura/Visao.template.md` |
+| §2 Stack | Stack.md | `_templates/estrutura/Stack.template.md` |
+| §3 Arquitetura | Arquitetura.md | `_templates/estrutura/Arquitetura.template.md` |
+| §4 Modelo de Dados | Modelo_Dados.md | `_templates/estrutura/Modelo_Dados.template.md` |
+| §5 API | API.md | `_templates/estrutura/API.template.md` |
+| §6 Infra | Infraestrutura.md | `_templates/estrutura/Infraestrutura.template.md` |
+| §7 Segurança | Seguranca.md | `_templates/estrutura/Seguranca.template.md` |
+| SDD §2 (após gerar) | ADRs.md | `_templates/estrutura/ADRs.template.md` |
+
+Regras:
+- Ler template → preencher TODAS seções com dados do TRD
+- Remover bloco `<!-- INSTRUÇÕES -->` do doc gerado
+- Changelog inicia vazio (primeira geração)
+- Se TRD não tem dados pra uma seção → marcar "A definir"
+- ADRs.md é gerado APÓS o SDD (usa §2 Decisões de Design)
+
+### 3b. Gerar `projetos.yaml` (APENAS para setup)
+
+Mapeia a arquitetura do TRD §3 para repositórios independentes.
+Cada serviço = 1 repo. Os repos serão criados/clonados pelo /dev (INFRA-001).
+
+1. Identificar serviços separados no TRD §3 (api, worker, web, mobile, etc.)
+2. Perguntar ao usuário:
+   - Organização/usuário do GitHub (ex: `empresa`)
+   - Nome base do projeto (ex: `meu-projeto`)
+   - Se algum repo já existe (para clonar em vez de criar)
+3. Gerar `projetos.yaml` na raiz usando template `projetos.template.yaml`
+4. Mapear áreas de task para repos:
+   - BACK → api (ou worker, se separado)
+   - BANCO → api (se usa EF migrations) ou repo próprio
+   - FRONT → web
+   - MOBILE → mobile
+   - INFRA → todos (cross-repo)
+5. Validar: cada área DEVE mapear para exatamente 1 repo
+
+**Regra**: Se o TRD indica API e Worker como serviços separados, DEVEM ser repos separados.
+Nunca juntar serviços que o TRD definiu como distintos.
+
+### 4. Carregar contexto
+- PRD.md ou TRD.md completo
+- `docs/Estrutura/` (agora já populado, mesmo no setup)
+- `docs/Desenvolvimento/rules.md`
+- Template `sdd.template.md`
+
+### 5. Gerar SDD
+11 seções obrigatórias (usar template). Para cada seção:
+- §1 Visão geral — escopo claro
+- §2 Decisões de design — mini-ADRs com justificativa
+- §3 Modelo de dados — tipos EXATOS, constraints, índices
+- §4 Regras e validações — ref PRD §N RN-NNN, mensagens de erro
+- §5 Endpoints API — contratos JSON completos, erros com códigos
+- §6 Componentes e telas — estados (loading/empty/error/success)
+- §7 Fluxos de dados — sequências front→back
+- §8 Integrações externas — timeout, retry, fallback
+- §9 Estratégia de testes — framework, estrutura, CAs mapeados
+- §10 Fora do escopo — lista explícita
+- §11 Delta Specs — ADDED/MODIFIED/REMOVED
+
+**Setup**: §4-§8 podem ser N/A (normal).
+**Feature**: todas seções aplicáveis preenchidas.
+
+### 6. Gerar ADRs.md (setup — complemento do passo 3)
+Após gerar SDD §2, criar ADRs.md com as decisões iniciais de arquitetura.
+
+### 7. Atualizar `.context.md`
+```yaml
+status: "design_done"
+ultima_skill: "/design"
+atualizado_em: "{{ISO_DATETIME}}"
+```

package/templates/.claude/commands/dev.md

@@ -1,167 +1,189 @@
-# /dev $ARGUMENTS
-
-Skill atômica de execução. Implementa tasks em loop até quality gate aprovado.
-$ARGUMENTS = nome (ex: feat_mvp)
-Flags opcionais: --fase 1 (RECOMENDADO) | --area banco | --task BACK-003
-
-## Agents por área (perfis em `.claude/agents/`)
-
-| Área | Agente | Stack | Modelo |
-|------|--------|-------|--------|
-| BANCO | DB Coder | PostgreSQL 16 | Sonnet (S/M) / Opus (L) |
-| BACK | Backend Coder | .NET 8 / C# | Sonnet (S/M) / Opus (L) |
-| FRONT | Frontend Coder | React + Fusion | Sonnet (S/M) / Opus (L) |
-| INFRA | Infra Coder | Docker | Sonnet (S/M) / Opus (L) |
-| DOC | Doc Writer | — | Sonnet |
-| Todas | Reviewer | — | Sonnet |
-| Todas | Security Reviewer | — | Opus |
-
-Agente selecionado pelo prefixo: BACK-* → Backend Coder, BANCO-* → DB Coder, etc.
-Ler o perfil do agente em `.claude/agents/` antes de implementar.
-
-## Pré-condições
-
-| # | Validação | Se falhar |
-|---|-----------|-----------|
-| 1 | $ARGUMENTS informado | Parar |
-| 2 | `.context.md` com status `plan_done` ou `dev_in_progress` | Se anterior → "/plan primeiro" |
-| 3 | `*_tasks.md` e `Progresso.md` existem | Parar |
-| 4 | `sdd.md` existe | Parar |
-| 5 | `rules.md` existe | Parar |
-| 6 | `projetos.yaml` existe | Parar → "Execute /design primeiro" |
-| 7 | Infra local rodando (`docker compose ps` → healthy) | Parar → "Suba a infra: `docker compose up -d`" |
-
-## Fluxo de execução
-
-```
-╔═══════════════════════════════════════════════╗
-║  LOOP POR TASK                                ║
-║                                               ║
-║  1. Selecionar agente pela área               ║
-║  2. Ler perfil do agente (.claude/agents/)    ║
-║  3. Implementar código + testes unit          ║
-║  4. Rodar testes unit                         ║
-║     → Falhou? Corrigir → volta pro 4          ║
-║     → 5 falhas? Parar, reportar               ║
-║  5. Rodar lint                                ║
-║     → Falhou? Corrigir → volta pro 5          ║
-║  6. Commit: tipo(TASK-ID): descrição          ║
-║  7. Review (quality gate)                     ║
-║     → Reprovado? Corrigir → volta pro 4       ║
-║     → 3 reprovações? Escalar pro usuário      ║
-║  8. Marcar task concluída ✅                   ║
-╚═══════════════════════════════════════════════╝
-        ↓ (todas tasks da fase)
-╔═══════════════════════════════════════════════╗
-║  VALIDAÇÃO POR FASE                           ║
-║  1. Rodar testes integration da área          ║
-║     → Falhou? Fix → loop (max 3)             ║
-╚═══════════════════════════════════════════════╝
-        ↓ (tudo concluído)
-╔═══════════════════════════════════════════════╗
-║  SECURITY REVIEW (cross-area)                 ║
-║  1. Security Reviewer audita todo código      ║
-║     → CRÍTICO/ALTO? Coder corrige → re-audit  ║
-║     → 2 falhas? Escalar pro usuário           ║
-║  2. Aprovado → prosseguir para E2E            ║
-╚═══════════════════════════════════════════════╝
-        ↓ (security aprovado)
-╔═══════════════════════════════════════════════╗
-║  VALIDAÇÃO POR FEATURE                        ║
-║  1. Rodar E2E (SDD §9.3 CAs)                 ║
-║     → Falhou? Identificar → fix → loop (max 3)║
-║  2. Tudo passou? → dev_done ✅                 ║
-╚═══════════════════════════════════════════════╝
-```
-
-## Multi-repo + Git Workflow
-
-### Contexto inicial
-- Ler `projetos.yaml` → mapeamento área → repo → path local
-- Validar que repos em `projetos/` existem (se não, INFRA-001 ainda não rodou)
-
-### Passo 1 — Verificar working tree (OBRIGATÓRIO)
-Em cada repo afetado: `git status`
-- Se working tree sujo → sugerir commit ou stash antes de prosseguir
-- NUNCA começar a codar com working tree sujo
-
-### INFRA-001 (setup — primeira execução)
-No setup, INFRA-001 cria/clona os repos:
-- Ler `projetos.yaml` → para cada repo:
-  - Se `existing: true` → `git clone {repo} projetos/{name}`
-  - Se `existing: false` → criar repo (`gh repo create {repo} --private`) + clone
-- Criar estrutura base em cada repo (conforme stack)
-
-### Passo 2 — Branch por fase (NUNCA na main)
-Para cada repo afetado por esta fase:
-```bash
-cd projetos/{repo_path}
-git checkout main && git pull origin main
-git checkout -b feature/{nome}_fase{N}
-```
-- NUNCA desenvolver direto na main
-
-## Implementação por task
-
-1. **Navegar**: ler campo `Repo:` da task → `cd projetos/{repo_path}/`
-2. **Ler**: task completa + seções do SDD referenciadas + perfil do agente + rules.md
-3. **Implementar**: código nos arquivos listados (caminhos relativos ao repo)
-4. **Testar**: testes unit nos arquivos de teste listados na task
-5. **Commit**: no repo do serviço — `tipo(TASK-ID): descrição curta`
-6. **Review**: quality gate (compilar, testes, lint, conformidade SDD, convenções)
-
-## Quality gate (Reviewer)
-
-| Check | Critério |
-|-------|----------|
-| Compila | Sem erros |
-| Testes unit | Passam |
-| Lint | Limpo |
-| Conformidade SDD | Contratos, tipos, regras conforme SDD |
-| Convenções | rules.md respeitado |
-| Sem TODOs | Injustificados |
-| Sem secrets | Hardcoded |
-| Arquivos corretos | Só os listados na task modificados |
-
-## Limites de retry
-
-| Nível | Limite | Ação ao exceder |
-|-------|--------|-----------------|
-| Test unit | 5 por task | Parar, reportar |
-| Review | 3 por task | Escalar pro usuário |
-| Integration | 3 por fase | Parar, reportar |
-| Security | 2 por feature | Escalar findings não resolvidos |
-| E2E | 3 por feature | Parar, reportar |
-
-## Passo 3 — Ao terminar fase: PR + ambiente ON
-
-1. Atualizar Progresso.md com status da fase
-2. Push da branch em cada repo: `git push origin feature/{nome}_fase{N}`
-3. Abrir PR com template detalhado (ver rules.md → Template de PR):
-   - Tasks concluídas, testes passando, como testar manualmente
-   - `gh pr create`
-4. Deixar ambiente local rodando:
-   - `docker compose up -d` (infra)
-   - `dotnet run` / `npm run dev` (apps nos repos)
-   - Informar URLs ao usuário
-5. **PARAR e aguardar** — merge é MANUAL pelo usuário
-
-## Passo 4 — Aguardar aprovação
-
-- O agente NUNCA faz merge
-- Se o usuário pedir ajustes → corrigir na mesma branch, push, atualizar PR
-
-## Passo 5 — Após merge (quando usuário confirmar)
-
-```bash
-cd projetos/{repo_path}
-git checkout main && git pull origin main
-git branch -d feature/{nome}_fase{N}
-git remote prune origin
-```
-
-## Atualizar `.context.md`
-```yaml
-status: "dev_in_progress"  # durante
-status: "dev_done"         # ao final (todas fases mergeadas)
-```
+# /dev $ARGUMENTS
+
+Skill atômica de execução. Implementa tasks em loop até quality gate aprovado.
+$ARGUMENTS = nome (ex: feat_mvp)
+Flags opcionais: --fase 1 (RECOMENDADO) | --area banco | --task BACK-003
+
+## Agents por área (perfis em `.claude/agents/`)
+
+| Área | Agente | Stack | Modelo |
+|------|--------|-------|--------|
+| BANCO | DB Coder | PostgreSQL 16 | Sonnet (S/M) / Opus (L) |
+| BACK | Backend Coder | .NET 8 / C# | Sonnet (S/M) / Opus (L) |
+| FRONT | Frontend Coder | React + Fusion | Sonnet (S/M) / Opus (L) |
+| INFRA | Infra Coder | Docker | Sonnet (S/M) / Opus (L) |
+| DOC | Doc Writer | — | Sonnet |
+| Todas | Reviewer | — | Sonnet |
+| Todas | Security Reviewer | — | Opus |
+
+Agente selecionado pelo prefixo: BACK-* → Backend Coder, BANCO-* → DB Coder, etc.
+Ler o perfil do agente em `.claude/agents/` antes de implementar.
+
+## Pré-condições
+
+| # | Validação | Se falhar |
+|---|-----------|-----------|
+| 1 | $ARGUMENTS informado | Parar |
+| 2 | `.context.md` com status `plan_done` ou `dev_in_progress` | Se anterior → "/plan primeiro" |
+| 3 | `*_tasks.md` e `Progresso.md` existem | Parar |
+| 4 | `sdd.md` existe | Parar |
+| 5 | `rules.md` existe | Parar |
+| 6 | `projetos.yaml` existe | Parar → "Execute /design primeiro" |
+| 7 | Infra local rodando (`docker compose ps` → healthy) | Parar → "Suba a infra: `docker compose up -d`" |
+
+## Fluxo de execução
+
+```
+╔═══════════════════════════════════════════════╗
+║  LOOP POR TASK                                ║
+║                                               ║
+║  1. Selecionar agente pela área               ║
+║  2. Ler perfil do agente (.claude/agents/)    ║
+║  3. Implementar código + testes unit          ║
+║  4. Rodar testes unit                         ║
+║     → Falhou? Corrigir → volta pro 4          ║
+║     → 5 falhas? Parar, reportar               ║
+║  5. Rodar lint                                ║
+║     → Falhou? Corrigir → volta pro 5          ║
+║  6. Commit: tipo(TASK-ID): descrição          ║
+║  7. Review (quality gate)                     ║
+║     → Reprovado? Corrigir → volta pro 4       ║
+║     → 3 reprovações? Escalar pro usuário      ║
+║  8. Marcar task concluída ✅                   ║
+╚═══════════════════════════════════════════════╝
+        ↓ (todas tasks da fase)
+╔═══════════════════════════════════════════════╗
+║  VALIDAÇÃO POR FASE                           ║
+║  1. Rodar testes integration da área          ║
+║     → Falhou? Fix → loop (max 3)             ║
+╚═══════════════════════════════════════════════╝
+        ↓ (tudo concluído)
+╔═══════════════════════════════════════════════╗
+║  SECURITY REVIEW (cross-area)                 ║
+║  1. Security Reviewer audita todo código      ║
+║     → CRÍTICO/ALTO? Coder corrige → re-audit  ║
+║     → 2 falhas? Escalar pro usuário           ║
+║  2. Aprovado → prosseguir para E2E            ║
+╚═══════════════════════════════════════════════╝
+        ↓ (security aprovado)
+╔═══════════════════════════════════════════════╗
+║  VALIDAÇÃO POR FEATURE                        ║
+║  1. Rodar E2E (SDD §9.3 CAs)                 ║
+║     → Falhou? Identificar → fix → loop (max 3)║
+║  2. Tudo passou? → prosseguir                 ║
+╚═══════════════════════════════════════════════╝
+        ↓ (E2E aprovado, só features)
+╔═══════════════════════════════════════════════╗
+║  MERGE-DELTA (automático, só features)        ║
+║  1. Ler SDD §11 (Delta Specs)                ║
+║  2. Aplicar ADDED/MODIFIED/REMOVED em         ║
+║     docs/Estrutura/                           ║
+║  3. Registrar changelog em cada doc alterado  ║
+║  4. dev_done ✅                                ║
+╚═══════════════════════════════════════════════╝
+```
+
+## Multi-repo + Git Workflow
+
+### Contexto inicial
+- Ler `projetos.yaml` → mapeamento área → repo → path local
+- Validar que repos em `projetos/` existem (se não, INFRA-001 ainda não rodou)
+
+### Passo 1 — Verificar working tree (OBRIGATÓRIO)
+Em cada repo afetado: `git status`
+- Se working tree sujo → sugerir commit ou stash antes de prosseguir
+- NUNCA começar a codar com working tree sujo
+
+### INFRA-001 (setup — primeira execução)
+No setup, INFRA-001 cria/clona os repos:
+- Ler `projetos.yaml` → para cada repo:
+  - Se `existing: true` → `git clone {repo} projetos/{name}`
+  - Se `existing: false` → criar repo (`gh repo create {repo} --private`) + clone
+- Criar estrutura base em cada repo (conforme stack)
+
+### Passo 2 — Branch por fase (NUNCA na main)
+Para cada repo afetado por esta fase:
+```bash
+cd projetos/{repo_path}
+git checkout main && git pull origin main
+git checkout -b feature/{nome}_fase{N}
+```
+- NUNCA desenvolver direto na main
+
+## Implementação por task
+
+1. **Navegar**: ler campo `Repo:` da task → `cd projetos/{repo_path}/`
+2. **Ler**: task completa + seções do SDD referenciadas + perfil do agente + rules.md
+3. **Implementar**: código nos arquivos listados (caminhos relativos ao repo)
+4. **Testar**: testes unit nos arquivos de teste listados na task
+5. **Commit**: no repo do serviço — `tipo(TASK-ID): descrição curta`
+6. **Review**: quality gate (compilar, testes, lint, conformidade SDD, convenções)
+
+## Quality gate (Reviewer)
+
+| Check | Critério |
+|-------|----------|
+| Compila | Sem erros |
+| Testes unit | Passam |
+| Lint | Limpo |
+| Conformidade SDD | Contratos, tipos, regras conforme SDD |
+| Convenções | rules.md respeitado |
+| Sem TODOs | Injustificados |
+| Sem secrets | Hardcoded |
+| Arquivos corretos | Só os listados na task modificados |
+
+## Limites de retry
+
+| Nível | Limite | Ação ao exceder |
+|-------|--------|-----------------|
+| Test unit | 5 por task | Parar, reportar |
+| Review | 3 por task | Escalar pro usuário |
+| Integration | 3 por fase | Parar, reportar |
+| Security | 2 por feature | Escalar findings não resolvidos |
+| E2E | 3 por feature | Parar, reportar |
+
+## Passo 3 — Ao terminar fase: PR + ambiente ON
+
+1. Atualizar Progresso.md com status da fase
+2. Push da branch em cada repo: `git push origin feature/{nome}_fase{N}`
+3. Abrir PR com template detalhado (ver rules.md → Template de PR):
+   - Tasks concluídas, testes passando, como testar manualmente
+   - `gh pr create`
+4. Deixar ambiente local rodando:
+   - `docker compose up -d` (infra)
+   - `dotnet run` / `npm run dev` (apps nos repos)
+   - Informar URLs ao usuário
+5. **PARAR e aguardar** — merge é MANUAL pelo usuário
+
+## Passo 4 — Aguardar aprovação
+
+- O agente NUNCA faz merge
+- Se o usuário pedir ajustes → corrigir na mesma branch, push, atualizar PR
+
+## Passo 5 — Após merge (quando usuário confirmar)
+
+```bash
+cd projetos/{repo_path}
+git checkout main && git pull origin main
+git branch -d feature/{nome}_fase{N}
+git remote prune origin
+```
+
+## Merge-Delta automático (só features)
+
+Após E2E aprovado, SE `.context.md` tipo = `feature`:
+1. Ler SDD §11 (seção Delta Specs: ADDED/MODIFIED/REMOVED)
+2. Para cada delta, mapear para o doc de `docs/Estrutura/` correspondente
+3. Aplicar as mudanças (adicionar, modificar ou remover seções)
+4. Registrar changelog em cada doc alterado: `| {{DATA}} | {{NOME}} | {{TIPO}} | {{DESCRIÇÃO}} |`
+5. Validar consistência cross-doc (ex: endpoint no API.md referencia tabela no Modelo_Dados.md)
+
+Se tipo = `setup` → pular (docs/Estrutura/ já foi criado pelo /design).
+
+> O `/merge-delta` continua existindo como command atômico para re-execução manual se necessário.
+
+## Atualizar `.context.md`
+```yaml
+status: "dev_in_progress"  # durante
+status: "dev_done"         # ao final (todas fases mergeadas + merge-delta aplicado)
+```