spec-first-copilot 0.2.0 → 0.4.0

package/templates/.github/skills/sf-dev/SKILL.md

@@ -1,326 +1,349 @@
----
-name: sf-dev
-description: |
-  Desenvolvimento. Implementa tasks com loop implement/test/review.
-  Trigger: /sf-dev
-author: GustavoMaritan
-version: 1.0.0
-date: 2026-04-08
----
-
-# Skill: /sf-dev
-
-> Skill atômica de execução. Implementa tasks em loop (implement → test → fix → review)
-> até quality gate aprovado, depois valida integração e E2E por feature.
-
-## Tipo
-Atômica — Multi-agent (agentes especializados por área)
-
-## Uso
-```
-/sf-dev <nome>
-/sf-dev <nome> --area banco
-/sf-dev <nome> --task BACK-003
-```
-
----
-
-## Agentes
-
-Cada área tem seu agente especializado. Perfis completos em `.github/agents/`.
-
-| Área | Agente | Perfil | Modelo |
-|------|--------|--------|--------|
-| BANCO | DB Coder | `agents/db-coder.md` | Sonnet (S/M) / Opus (L) |
-| BACK | Backend Coder | `agents/backend-coder.md` | Sonnet (S/M) / Opus (L) |
-| FRONT | Frontend Coder | `agents/frontend-coder.md` | Sonnet (S/M) / Opus (L) |
-| INFRA | Infra Coder | `agents/infra-coder.md` | Sonnet (S/M) / Opus (L) |
-| DOC | Doc Writer | `agents/doc-writer.md` | Sonnet |
-| — | Reviewer | `agents/reviewer.md` | Sonnet |
-| — | Security Reviewer | `agents/security-reviewer.md` | Opus |
-
-O agente é selecionado pelo prefixo da task: `BANCO-*` → DB Coder, `BACK-*` → Backend Coder, etc.
-
----
-
-## Pré-condições
-
-| # | Validação | Se falhar |
-|---|-----------|-----------|
-| 1 | Argumento `nome` foi informado | Parar → "Informe o nome. Ex: /sf-dev feat_cadastro_cliente" |
-| 2 | `.context.md` existe com status `plan_done` ou `dev_in_progress` | Se anterior → "Execute /sf-plan {nome} primeiro" |
-| 3 | `*_tasks.md` e `Progresso.md` existem | Parar → "Tasks não encontradas. Execute /sf-plan {nome}" |
-| 4 | `sdd.md` existe | Parar → "SDD não encontrado" |
-| 5 | `docs/Desenvolvimento/rules.md` existe | Parar → "rules.md não encontrado" |
-| 6 | `projetos.yaml` existe na raiz | Parar → "Execute /sf-design primeiro (gera projetos.yaml)" |
-| 7 | Infra local rodando (`docker compose ps` → containers healthy) | Parar → "Suba a infra primeiro: `docker compose up -d` e aguarde healthy" |
-
-> **Nota**: A validação #7 verifica se os containers de infra (banco, redis, etc.) estão rodando.
-> Não valida apps (api, web) — essas são iniciadas durante o /dev.
-
-## Modalidades
-
-| Modo | Comando | Comportamento |
-|------|---------|---------------|
-| **Por fase** | `/sf-dev feat_nome --fase 1` | Todas tasks da fase de entrega (RECOMENDADO) |
-| **Completo** | `/sf-dev feat_nome` | Executa todas tasks pendentes, respeitando ordem de fases |
-| **Por área** | `/sf-dev feat_nome --area banco` | Só tasks da área especificada |
-| **Task individual** | `/sf-dev feat_nome --task BACK-003` | Só a task especificada (valida dependências) |
-
-> **Recomendado**: Usar `--fase N` para desenvolvimento incremental. Cada fase gera 1 PR.
-
----
-
-## Fluxo de Execução
-
-```
-/sf-dev feat_nome
-│
-│  ╔═══════════════════════════════════════════════╗
-│  ║  LOOP POR TASK                                ║
-│  ║                                               ║
-│  ║  1. Selecionar agente pela área (BACK-* etc)  ║
-│  ║  2. Agente implementa código + testes unit    ║
-│  ║  3. Rodar testes unit                         ║
-│  ║     → Falhou? Agente corrige → volta pro 3    ║
-│  ║  4. Rodar lint                                ║
-│  ║     → Falhou? Agente corrige → volta pro 4    ║
-│  ║  5. Commit: tipo(TASK-ID): descrição          ║
-│  ║  6. Reviewer valida quality gate              ║
-│  ║     → Reprovado? Agente corrige → volta pro 3 ║
-│  ║     → 3 reprovações? Escalar pro usuário      ║
-│  ║  7. Marcar task concluída ✅                   ║
-│  ║  8. Atualizar Progresso.md                    ║
-│  ╚═══════════════════════════════════════════════╝
-│         ↓ (todas tasks da fase concluídas)
-│  ╔═══════════════════════════════════════════════╗
-│  ║  VALIDAÇÃO POR FASE                           ║
-│  ║                                               ║
-│  ║  1. Rodar testes integration da área/fase     ║
-│  ║     → Falhou? Criar fix inline → loop         ║
-│  ║  2. Fase aprovada → próxima fase              ║
-│  ╚═══════════════════════════════════════════════╝
-│         ↓ (todas fases/áreas concluídas)
-│  ╔═══════════════════════════════════════════════╗
-│  ║  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 testes E2E (SDD §9.3 CAs)          ║
-│  ║     → Falhou? Identificar task → fix → loop   ║
-│  ║  2. Todos CAs passam? → dev_done ✅            ║
-│  ╚═══════════════════════════════════════════════╝
-```
-
----
-
-## Passos detalhados
-
-### 1. Carregar contexto
-- Ler `.context.md` → validar status
-- Ler `projetos.yaml` → mapeamento área → repo → path local
-- Ler `Progresso.md` → ordem de execução e estado atual
-- Ler `rules.md` → convenções
-- Ler `sdd.md` → fonte de verdade (§9 para estratégia de testes)
-- Carregar perfil do agente correspondente à área
-- Validar que repos em `projetos/` existem (se não, INFRA-001 ainda não rodou)
-
-### 2. Preparar repos (multi-repo)
-
-#### 2a. Verificar working tree (OBRIGATÓRIO)
-Em cada repo que será afetado:
-- `git status` — verificar se há mudanças pendentes
-- Se working tree sujo → sugerir commit ou stash antes de prosseguir
-- NUNCA começar a codar com working tree sujo
-
-#### 2b. INFRA-001 (setup — primeira execução)
-No setup, INFRA-001 é responsável por criar/clonar os repos:
-- Ler `projetos.yaml` → para cada repo:
-  - Se `existing: true` → `git clone {repo} projetos/{name}`
-  - Se `existing: false` → criar repo no GitHub (`gh repo create {repo} --private`) + clone local
-- Criar estrutura base em cada repo (conforme stack: .NET → `dotnet new`, React → `create-react-app`, etc.)
-- Criar `projetos/.gitkeep` na raiz (pasta existe mas conteúdo é ignorado)
-
-#### 2c. Branch por fase (NUNCA na main)
-Para cada repo que será afetado por esta fase:
-- `cd projetos/{repo_path}`
-- `git checkout main && git pull origin main` (garantir main atualizada)
-- `git checkout -b feature/{nome}_fase{N}` (se branch não existe)
-- Se branch já existe → `git checkout feature/{nome}_fase{N}`
-- NUNCA desenvolver direto na main
-
-#### 2c. Resolver próxima task
-- Filtrar tasks pendentes (`- [ ]`) conforme modalidade
-- Ler campo `Repo:` da task → identificar em qual repo trabalhar
-- Validar dependências: todas tasks em `Depende:` devem estar `- [x]`
-- Se dependência pendente → listar o que falta
-
-### 3. Loop por task
-
-#### 3a. Implementar
-- Ler campo `Repo:` da task → navegar para `projetos/{repo_path}/`
-- Selecionar agente pela área da task (BACK-* → Backend Coder)
-- Selecionar modelo pelo tamanho (S/M → Sonnet, L → Opus)
-- Input para o agente:
-  - Task completa (ID, título, arquivos, SDD ref, dependências)
-  - Seções do SDD referenciadas (apenas as seções necessárias)
-  - Perfil do agente (`.github/agents/*.md`)
-  - `rules.md`
-  - **Working directory**: `projetos/{repo_path}/` (caminhos de arquivo são relativos ao repo)
-- Agente implementa código **E testes unit** na mesma task
-
-#### 3b. Test loop
-```
-Rodar testes unit → passou? → continuar
-                  → falhou? → agente analisa erro → corrige → rodar de novo
-                  → 5 falhas seguidas? → parar, reportar ao usuário
-```
-
-#### 3c. Lint
-```
-Rodar lint → passou? → continuar
-          → falhou? → agente corrige → rodar de novo
-```
-
-#### 3d. Commit (no repo do serviço)
-- Working directory: `projetos/{repo_path}/`
-- `git add` + `git commit -m "tipo(TASK-ID): descrição curta"`
-- Commit acontece no repo do serviço, NÃO no projeto-base
-- Corpo opcional se Senior Coder tomou decisão (mini-ADR)
-
-#### 3e. Review
-- Spawn Reviewer (Sonnet) com: código + testes + quality gate checklist
-- Se APROVADO → marcar task `- [x]`, atualizar Progresso.md
-- Se REPROVADO → agente recebe problemas, corrige, volta pro 3b
-- Limite: **3 reprovações** → escalar pro usuário
-
-### 4. Validação por fase
-Ao concluir todas tasks de uma fase:
-- Rodar testes integration da área (SDD §9.1)
-- Se falhou → identificar causa, corrigir no código da task afetada, recommit
-- Se passou → avançar pra próxima fase
-
-### 5. Security Review (cross-area)
-Ao concluir todas tasks de todas áreas, ANTES dos testes E2E:
-- Spawn Security Reviewer (Opus) com: todo código produzido + SDD §5 + Seguranca.md
-- Audita 6 categorias: Auth, AuthZ, Injeção, Dados Sensíveis, Headers, Banco
-- Se findings CRÍTICO ou ALTO:
-  - Identificar área responsável (BACK, FRONT, BANCO, INFRA)
-  - Coder da área corrige → recommit
-  - Security Reviewer reavalia apenas os findings
-- Se aprovado → prosseguir para E2E
-- Limite: **2 tentativas** → escalar pro usuário
-
-### 6. Validação por feature
-Ao concluir security review com aprovação:
-- Rodar testes E2E (SDD §9.3 — cada CA deve ter teste correspondente)
-- Se falhou:
-  - Identificar qual CA falhou
-  - Mapear pra task/área responsável
-  - Criar fix inline (não cria nova task)
-  - Rodar E2E de novo
-- Se passou → dev_done
-
-### 7. Finalizar fase — PR + ambiente ON
-Ao concluir todos testes da fase:
-
-1. **Atualizar Progresso.md** com status da fase
-2. **Push da branch** em cada repo afetado:
-   ```bash
-   cd projetos/{repo_path}
-   git push origin feature/{nome}_fase{N}
-   ```
-3. **Abrir PR** em cada repo com template detalhado (ver `rules.md` → Template de PR):
-   - Tasks concluídas, testes passando, como testar manualmente
-   - Usar `gh pr create`
-4. **Deixar ambiente local rodando**:
-   - `docker compose up -d` (infra)
-   - `dotnet run` / `npm run dev` (apps)
-   - Informar URLs ao usuário
-5. **PARAR e aguardar** — o usuário testa manualmente e aprova o PR
-   - O agente NUNCA faz merge — merge é manual pelo usuário
-   - Se o usuário pedir ajustes → corrigir na mesma branch, push, atualizar PR
-
-### 8. Após merge (quando usuário confirmar)
-```bash
-# Em cada repo afetado:
-cd projetos/{repo_path}
-git checkout main
-git pull origin main
-git branch -d feature/{nome}_fase{N}
-git remote prune origin
-```
-
-### 9. Atualizar `.context.md`
-```yaml
-status: "dev_in_progress"  # durante execução
-# ou
-status: "dev_done"         # todas fases + integration + security + E2E passaram
-ultima_skill: "/sf-dev"
-atualizado_em: "{{ISO_DATETIME}}"
-```
-
----
-
-## Limites de retry
-
-| Nível | Limite | Ação ao exceder |
-|-------|--------|-----------------|
-| Test loop (unit) | 5 tentativas por task | Parar, reportar erro persistente |
-| Review loop | 3 reprovações por task | Parar, escalar pro usuário |
-| Integration fix | 3 tentativas por fase | Parar, reportar ao usuário |
-| Security fix | 2 tentativas por feature | Parar, escalar findings não resolvidos |
-| E2E fix | 3 tentativas por feature | Parar, reportar ao usuário |
-
-Mensagem de escalação:
-```
-⚠️ Task {ID} não passou após {N} tentativas.
-Problemas persistentes:
-1. ...
-2. ...
-Ação necessária: revisar SDD ou intervir manualmente.
-```
-
----
-
-## Saídas
-
-| Saída | Descrição |
-|-------|-----------|
-| Código implementado | Em `projetos/{repo}/` — arquivos criados/modificados conforme tasks |
-| Testes | Unit + integration + E2E nos repos correspondentes |
-| Commits | 1 commit por task no repo do serviço: `tipo(TASK-ID): descrição` |
-| Branches | `feature/{nome}` criado em cada repo afetado |
-| `*_tasks.md` | Tasks marcadas como concluídas (no projeto-base) |
-| `Progresso.md` | Atualizado com status real (no projeto-base) |
-| `progresso.md` (global) | Atualizado (no projeto-base) |
-| `.context.md` | Status atualizado (no projeto-base) |
-
-## Pós-condições
-- Todas tasks concluídas = status `dev_done`
-- Quality gate aprovado em cada task
-- Integration tests passam por fase
-- Security Review aprovado (zero findings CRÍTICO/ALTO)
-- E2E tests passam por feature (todos CAs do SDD §9.3)
-- Pronto para `/merge-delta` (se feature) ou conclusão (se setup)
-
-## Erros
-
-| Erro | Ação |
-|------|------|
-| Nome não informado | Parar, mostrar exemplo |
-| Status anterior a plan_done | Parar, sugerir skill correspondente |
-| Dependência não concluída | Parar, listar dependências pendentes |
-| Test loop excedeu limite | Parar, reportar erro + stack trace |
-| Review excedeu 3 tentativas | Parar, escalar com lista de problemas |
-| Integration/E2E persistente | Parar, reportar CAs que falharam |
-| SDD ambíguo | Parar, reportar ambiguidade |
-| --task com ID inexistente | Parar, listar tasks disponíveis |
-| --area com área inexistente | Parar, listar áreas disponíveis |
+---
+name: sf-dev
+description: |
+  Desenvolvimento. Implementa tasks com loop implement/test/review.
+  Trigger: /sf-dev
+author: GustavoMaritan
+version: 1.0.0
+date: 2026-04-08
+---
+
+# Skill: /sf-dev
+
+> Skill atômica de execução. Implementa tasks em loop (implement → test → fix → review)
+> até quality gate aprovado, depois valida integração e E2E por feature.
+
+## Tipo
+Atômica — Multi-agent (agentes especializados por área)
+
+## Uso
+```
+/sf-dev <nome>
+/sf-dev <nome> --area banco
+/sf-dev <nome> --task BACK-003
+```
+
+---
+
+## Agentes
+
+Cada área tem seu agente especializado. Perfis completos em `.github/agents/`.
+
+| Área | Agente | Perfil | Modelo |
+|------|--------|--------|--------|
+| BANCO | DB Coder | `agents/db-coder.md` | Sonnet (S/M) / Opus (L) |
+| BACK | Backend Coder | `agents/backend-coder.md` | Sonnet (S/M) / Opus (L) |
+| FRONT | Frontend Coder | `agents/frontend-coder.md` | Sonnet (S/M) / Opus (L) |
+| INFRA | Infra Coder | `agents/infra-coder.md` | Sonnet (S/M) / Opus (L) |
+| DOC | Doc Writer | `agents/doc-writer.md` | Sonnet |
+| — | Reviewer | `agents/reviewer.md` | Sonnet |
+| — | Security Reviewer | `agents/security-reviewer.md` | Opus |
+
+O agente é selecionado pelo prefixo da task: `BANCO-*` → DB Coder, `BACK-*` → Backend Coder, etc.
+
+---
+
+## Pré-condições
+
+| # | Validação | Se falhar |
+|---|-----------|-----------|
+| 1 | Argumento `nome` foi informado | Parar → "Informe o nome. Ex: /sf-dev feat_cadastro_cliente" |
+| 2 | `.context.md` existe com status `plan_done` ou `dev_in_progress` | Se anterior → "Execute /sf-plan {nome} primeiro" |
+| 3 | `*_tasks.md` e `Progresso.md` existem | Parar → "Tasks não encontradas. Execute /sf-plan {nome}" |
+| 4 | `sdd.md` existe | Parar → "SDD não encontrado" |
+| 5 | `docs/Desenvolvimento/rules.md` existe | Parar → "rules.md não encontrado" |
+| 6 | `projetos.yaml` existe na raiz | Parar → "Execute /sf-design primeiro (gera projetos.yaml)" |
+| 7 | Infra local rodando (`docker compose ps` → containers healthy) | Parar → "Suba a infra primeiro: `docker compose up -d` e aguarde healthy" |
+
+> **Nota**: A validação #7 verifica se os containers de infra (banco, redis, etc.) estão rodando.
+> Não valida apps (api, web) — essas são iniciadas durante o /dev.
+
+## Modalidades
+
+| Modo | Comando | Comportamento |
+|------|---------|---------------|
+| **Por fase** | `/sf-dev feat_nome --fase 1` | Todas tasks da fase de entrega (RECOMENDADO) |
+| **Completo** | `/sf-dev feat_nome` | Executa todas tasks pendentes, respeitando ordem de fases |
+| **Por área** | `/sf-dev feat_nome --area banco` | Só tasks da área especificada |
+| **Task individual** | `/sf-dev feat_nome --task BACK-003` | Só a task especificada (valida dependências) |
+
+> **Recomendado**: Usar `--fase N` para desenvolvimento incremental. Cada fase gera 1 PR.
+
+---
+
+## Fluxo de Execução
+
+```
+/sf-dev feat_nome
+│
+│  ╔═══════════════════════════════════════════════╗
+│  ║  LOOP POR TASK                                ║
+│  ║                                               ║
+│  ║  1. Selecionar agente pela área (BACK-* etc)  ║
+│  ║  2. Agente implementa código + testes unit    ║
+│  ║  3. Rodar testes unit                         ║
+│  ║     → Falhou? Agente corrige → volta pro 3    ║
+│  ║  4. Rodar lint                                ║
+│  ║     → Falhou? Agente corrige → volta pro 4    ║
+│  ║  5. Commit: tipo(TASK-ID): descrição          ║
+│  ║  6. Reviewer valida quality gate              ║
+│  ║     → Reprovado? Agente corrige → volta pro 3 ║
+│  ║     → 3 reprovações? Escalar pro usuário      ║
+│  ║  7. Marcar task concluída ✅                   ║
+│  ║  8. Atualizar Progresso.md                    ║
+│  ╚═══════════════════════════════════════════════╝
+│         ↓ (todas tasks da fase concluídas)
+│  ╔═══════════════════════════════════════════════╗
+│  ║  VALIDAÇÃO POR FASE                           ║
+│  ║                                               ║
+│  ║  1. Rodar testes integration da área/fase     ║
+│  ║     → Falhou? Criar fix inline → loop         ║
+│  ║  2. Fase aprovada → próxima fase              ║
+│  ╚═══════════════════════════════════════════════╝
+│         ↓ (todas fases/áreas concluídas)
+│  ╔═══════════════════════════════════════════════╗
+│  ║  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 testes E2E (SDD §9.3 CAs)          ║
+│  ║     → Falhou? Identificar task → fix → loop   ║
+│  ║  2. Todos CAs passam? → 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 ✅                                ║
+│  ╚═══════════════════════════════════════════════╝
+```
+
+---
+
+## Passos detalhados
+
+### 1. Carregar contexto
+- Ler `.context.md` → validar status
+- Ler `projetos.yaml` → mapeamento área → repo → path local
+- Ler `Progresso.md` → ordem de execução e estado atual
+- Ler `rules.md` → convenções
+- Ler `sdd.md` → fonte de verdade (§9 para estratégia de testes)
+- Carregar perfil do agente correspondente à área
+- Validar que repos em `projetos/` existem (se não, INFRA-001 ainda não rodou)
+
+### 2. Preparar repos (multi-repo)
+
+#### 2a. Verificar working tree (OBRIGATÓRIO)
+Em cada repo que será afetado:
+- `git status` — verificar se há mudanças pendentes
+- Se working tree sujo → sugerir commit ou stash antes de prosseguir
+- NUNCA começar a codar com working tree sujo
+
+#### 2b. INFRA-001 (setup — primeira execução)
+No setup, INFRA-001 é responsável por criar/clonar os repos:
+- Ler `projetos.yaml` → para cada repo:
+  - Se `existing: true` → `git clone {repo} projetos/{name}`
+  - Se `existing: false` → criar repo no GitHub (`gh repo create {repo} --private`) + clone local
+- Criar estrutura base em cada repo (conforme stack: .NET → `dotnet new`, React → `create-react-app`, etc.)
+- Criar `projetos/.gitkeep` na raiz (pasta existe mas conteúdo é ignorado)
+
+#### 2c. Branch por fase (NUNCA na main)
+Para cada repo que será afetado por esta fase:
+- `cd projetos/{repo_path}`
+- `git checkout main && git pull origin main` (garantir main atualizada)
+- `git checkout -b feature/{nome}_fase{N}` (se branch não existe)
+- Se branch já existe → `git checkout feature/{nome}_fase{N}`
+- NUNCA desenvolver direto na main
+
+#### 2c. Resolver próxima task
+- Filtrar tasks pendentes (`- [ ]`) conforme modalidade
+- Ler campo `Repo:` da task → identificar em qual repo trabalhar
+- Validar dependências: todas tasks em `Depende:` devem estar `- [x]`
+- Se dependência pendente → listar o que falta
+
+### 3. Loop por task
+
+#### 3a. Implementar
+- Ler campo `Repo:` da task → navegar para `projetos/{repo_path}/`
+- Selecionar agente pela área da task (BACK-* → Backend Coder)
+- Selecionar modelo pelo tamanho (S/M → Sonnet, L → Opus)
+- Input para o agente:
+  - Task completa (ID, título, arquivos, SDD ref, dependências)
+  - Seções do SDD referenciadas (apenas as seções necessárias)
+  - Perfil do agente (`.github/agents/*.md`)
+  - `rules.md`
+  - **Working directory**: `projetos/{repo_path}/` (caminhos de arquivo são relativos ao repo)
+- Agente implementa código **E testes unit** na mesma task
+
+#### 3b. Test loop
+```
+Rodar testes unit → passou? → continuar
+                  → falhou? → agente analisa erro → corrige → rodar de novo
+                  → 5 falhas seguidas? → parar, reportar ao usuário
+```
+
+#### 3c. Lint
+```
+Rodar lint → passou? → continuar
+          → falhou? → agente corrige → rodar de novo
+```
+
+#### 3d. Commit (no repo do serviço)
+- Working directory: `projetos/{repo_path}/`
+- `git add` + `git commit -m "tipo(TASK-ID): descrição curta"`
+- Commit acontece no repo do serviço, NÃO no projeto-base
+- Corpo opcional se Senior Coder tomou decisão (mini-ADR)
+
+#### 3e. Review
+- Spawn Reviewer (Sonnet) com: código + testes + quality gate checklist
+- Se APROVADO → marcar task `- [x]`, atualizar Progresso.md
+- Se REPROVADO → agente recebe problemas, corrige, volta pro 3b
+- Limite: **3 reprovações** → escalar pro usuário
+
+### 4. Validação por fase
+Ao concluir todas tasks de uma fase:
+- Rodar testes integration da área (SDD §9.1)
+- Se falhou → identificar causa, corrigir no código da task afetada, recommit
+- Se passou → avançar pra próxima fase
+
+### 5. Security Review (cross-area)
+Ao concluir todas tasks de todas áreas, ANTES dos testes E2E:
+- Spawn Security Reviewer (Opus) com: todo código produzido + SDD §5 + Seguranca.md
+- Audita 6 categorias: Auth, AuthZ, Injeção, Dados Sensíveis, Headers, Banco
+- Se findings CRÍTICO ou ALTO:
+  - Identificar área responsável (BACK, FRONT, BANCO, INFRA)
+  - Coder da área corrige → recommit
+  - Security Reviewer reavalia apenas os findings
+- Se aprovado → prosseguir para E2E
+- Limite: **2 tentativas** → escalar pro usuário
+
+### 6. Validação por feature
+Ao concluir security review com aprovação:
+- Rodar testes E2E (SDD §9.3 — cada CA deve ter teste correspondente)
+- Se falhou:
+  - Identificar qual CA falhou
+  - Mapear pra task/área responsável
+  - Criar fix inline (não cria nova task)
+  - Rodar E2E de novo
+- Se passou → prosseguir para merge-delta (features) ou dev_done (setup)
+
+### 7. Finalizar fase — PR + ambiente ON
+Ao concluir todos testes da fase:
+
+1. **Atualizar Progresso.md** com status da fase
+2. **Push da branch** em cada repo afetado:
+   ```bash
+   cd projetos/{repo_path}
+   git push origin feature/{nome}_fase{N}
+   ```
+3. **Abrir PR** em cada repo com template detalhado (ver `rules.md` → Template de PR):
+   - Tasks concluídas, testes passando, como testar manualmente
+   - Usar `gh pr create`
+4. **Deixar ambiente local rodando**:
+   - `docker compose up -d` (infra)
+   - `dotnet run` / `npm run dev` (apps)
+   - Informar URLs ao usuário
+5. **PARAR e aguardar** — o usuário testa manualmente e aprova o PR
+   - O agente NUNCA faz merge — merge é manual pelo usuário
+   - Se o usuário pedir ajustes → corrigir na mesma branch, push, atualizar PR
+
+### 8. Após merge (quando usuário confirmar)
+```bash
+# Em cada repo afetado:
+cd projetos/{repo_path}
+git checkout main
+git pull origin main
+git branch -d feature/{nome}_fase{N}
+git remote prune origin
+```
+
+### 9. 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 `/sf-merge-delta` continua existindo como skill atômica para re-execução manual se necessário.
+
+### 10. Atualizar `.context.md`
+```yaml
+status: "dev_in_progress"  # durante execução
+# ou
+status: "dev_done"         # todas fases + integration + security + E2E + merge-delta
+ultima_skill: "/sf-dev"
+atualizado_em: "{{ISO_DATETIME}}"
+```
+
+---
+
+## Limites de retry
+
+| Nível | Limite | Ação ao exceder |
+|-------|--------|-----------------|
+| Test loop (unit) | 5 tentativas por task | Parar, reportar erro persistente |
+| Review loop | 3 reprovações por task | Parar, escalar pro usuário |
+| Integration fix | 3 tentativas por fase | Parar, reportar ao usuário |
+| Security fix | 2 tentativas por feature | Parar, escalar findings não resolvidos |
+| E2E fix | 3 tentativas por feature | Parar, reportar ao usuário |
+
+Mensagem de escalação:
+```
+⚠️ Task {ID} não passou após {N} tentativas.
+Problemas persistentes:
+1. ...
+2. ...
+Ação necessária: revisar SDD ou intervir manualmente.
+```
+
+---
+
+## Saídas
+
+| Saída | Descrição |
+|-------|-----------|
+| Código implementado | Em `projetos/{repo}/` — arquivos criados/modificados conforme tasks |
+| Testes | Unit + integration + E2E nos repos correspondentes |
+| Commits | 1 commit por task no repo do serviço: `tipo(TASK-ID): descrição` |
+| Branches | `feature/{nome}` criado em cada repo afetado |
+| `*_tasks.md` | Tasks marcadas como concluídas (no projeto-base) |
+| `Progresso.md` | Atualizado com status real (no projeto-base) |
+| `progresso.md` (global) | Atualizado (no projeto-base) |
+| `.context.md` | Status atualizado (no projeto-base) |
+
+## Pós-condições
+- Todas tasks concluídas = status `dev_done`
+- Quality gate aprovado em cada task
+- Integration tests passam por fase
+- Security Review aprovado (zero findings CRÍTICO/ALTO)
+- E2E tests passam por feature (todos CAs do SDD §9.3)
+- Merge-delta aplicado automaticamente (features) — docs/Estrutura/ atualizado
+
+## Erros
+
+| Erro | Ação |
+|------|------|
+| Nome não informado | Parar, mostrar exemplo |
+| Status anterior a plan_done | Parar, sugerir skill correspondente |
+| Dependência não concluída | Parar, listar dependências pendentes |
+| Test loop excedeu limite | Parar, reportar erro + stack trace |
+| Review excedeu 3 tentativas | Parar, escalar com lista de problemas |
+| Integration/E2E persistente | Parar, reportar CAs que falharam |
+| SDD ambíguo | Parar, reportar ambiguidade |
+| --task com ID inexistente | Parar, listar tasks disponíveis |
+| --area com área inexistente | Parar, listar áreas disponíveis |