spec-first-copilot 0.6.0-beta.9 → 0.7.0

package/templates/.github/skills/sf-merge-docs/SKILL.md

@@ -1,100 +1,152 @@
-# /sf-merge-docs $ARGUMENTS
-
-Skill atômica pós-dev. Aplica SDD §11 Delta Specs em `docs/` pra manter a síntese cross-feature sincronizada com o estado do sistema.
-`$ARGUMENTS` = nome do scope (ex: `feat_cadastro_cliente`).
-
-Chamado automaticamente pelo `/sf-dev` ao final. Re-executável manualmente se precisar.
-
-> **Renomeado de `/sf-merge-delta` em v3**. "Delta Specs" fica como conceito interno no SDD §11 (mecanismo OpenSpec). O nome do command alinha ao outcome (atualiza docs/).
-
-## Agente: Integrator (Sonnet)
-
-Meticuloso com consistência. Aplica apenas o que §11 diz. Merge idempotente — re-aplicar o mesmo delta não duplica.
-
-## Pré-condições
-
-| # | Validação | Se falhar |
-|---|-----------|-----------|
-| 1 | `$ARGUMENTS` informado | Parar |
-| 2 | `.context.md` com status `dev_done` | Se anterior → "Rode /sf-dev primeiro" |
-| 3 | `workspace/Output/$ARGUMENTS/sdd.md` §11 Delta Specs presente | Parar |
-| 4 | `docs/` populado | Parar — "docs/ não existe. /sf-design com first_run=true é quem cria docs/" |
-
-Note: **serve pra first-run e feature**. Em first-run, `/sf-design` já criou `docs/` a partir do SDD §Sistema (passo 6 do /sf-design). §11 de first-run geralmente lista tudo em ADDED refletindo o estado criado — `/sf-merge-docs` nesse caso é idempotente (merge não duplica). Em feature, aplica as mudanças incrementais de verdade.
-
-## Passos
-
-### 1. Ler SDD §11 Delta Specs
-
-| Tipo | Significado |
-|------|-------------|
-| ADDED | Elemento novo (tabela, endpoint, tela, env var, ADR) |
-| MODIFIED | Elemento existente alterado (campo mudou tipo, auth expandida) |
-| REMOVED | Elemento removido ou deprecado |
-
-Cada item referencia arquivo-alvo: `docs/conventions.md §Autenticação`.
-
-### 2. Mapear elementos → arquivo alvo em docs/
-
-| Elemento do delta | Doc alvo |
-|-------------------|----------|
-| Tabelas, colunas, índices, entidades, FKs | `domain.md` |
-| Atores, permissões (modelo), integrações externas, glossário | `domain.md` |
-| Endpoints (catálogo), rotas, paginação, filtros, erros HTTP | `apiContracts.md` |
-| Containers, stack, ambientes, deploy, CI/CD, rollback | `architecture.md` |
-| Padrões de comunicação, padrões de design | `architecture.md` |
-| Auth, authz, roles, matriz de permissões, CORS, rate limiting | `conventions.md` |
-| LGPD, auditoria, TLS, criptografia | `conventions.md` |
-| Env vars, domínios, monitoramento, observabilidade | `conventions.md` |
-| Códigos de erro do domínio, alternativas tech descartadas, versionamento | `conventions.md` |
-| Decisões arquiteturais (ADR-*) | `decisions.md` |
-
-### 3. Aplicar deltas (merge idempotente)
-
-Para cada delta:
-- **ADDED** — localizar seção apropriada no doc, adicionar conteúdo. Se já existe conteúdo idêntico → skip (idempotente).
-- **MODIFIED** — localizar elemento pelo ID/nome, atualizar campos. Se elemento ausente → criar como ADDED.
-- **REMOVED** — marcar como deprecated (não apagar). ADRs sempre viram `status: substituída por ADR-XXX`.
-
-### 4. Registrar changelog em cada doc afetado
-
-```markdown
-## Changelog
-
-| Data | Feature | Tipo | Descrição |
-|------|---------|------|-----------|
-| {{data}} | $ARGUMENTS | ADDED | Endpoint POST /api/v1/users |
-| {{data}} | $ARGUMENTS | MODIFIED | Matriz de permissões: novo role `manager` |
-```
-
-### 5. Validar consistência
-
-- Referências quebradas (endpoint deletado mas mencionado em outro lugar) → reportar
-- REMOVED deixou órfãos (role que ainda aparece em policies ativas) → reportar
-- ADR-NNN substituída mas ainda referenciada → reportar
-
-### 6. Atualizar status
-
-- `.context.md` → `status: done`, `ultima_skill: /sf-merge-docs`
-- `progresso.md` global → scope concluído
-
-### 7. Informar ao usuário
-
-```
-docs/ sincronizada com SDD de $ARGUMENTS.
-Arquivos afetados:
-- docs/apiContracts.md (3 endpoints ADDED)
-- docs/conventions.md (1 role ADDED, matriz atualizada)
-- docs/decisions.md (ADR-005 ADDED)
-```
-
-## Erros
-
-| Erro | Ação |
-|------|------|
-| Status não é `dev_done` | Parar — pedir rodar /sf-dev primeiro |
-| `docs/` não existe | Parar — explicar que /sf-design em first-run é quem cria docs/ |
-| §11 Delta Specs vazia | Marcar `done` (legítimo em refactors que não mudam sistema) |
-| Elemento MODIFIED não encontrado no doc | Converter pra ADDED (doc estava desatualizado) + reportar |
-| Elemento REMOVED não encontrado | Skip + reportar (provavelmente já foi removido antes) |
-| Referências quebradas detectadas | Parar, listar inconsistências, pedir resolução manual |
+
+# /sf-merge-docs $ARGUMENTS
+
+Skill atômica pós-dev. Aplica as decisões de **PRD + TRD aprovados** em `docs/` pra manter a síntese cross-feature sincronizada com o estado do sistema.
+`$ARGUMENTS` = nome do scope (ex: `feat_cadastro_cliente`).
+
+Chamado automaticamente pelo `/sf-dev` ao final. Re-executável manualmente quando precisa.
+
+> **Mudança v3 → v4**: antes aplicava `SDD §11 Delta Specs` (mecanismo OpenSpec).
+> Agora lê **PRD + TRD aprovados diretamente** e infere o delta comparando com
+> o estado atual de `docs/` (diff semântico). SDD não existe mais em v4.
+
+## Agente: Integrator (Opus)
+
+Em v4 promovido de Sonnet → Opus: diff semântico PRD/TRD ↔ docs/ exige reasoning
+de maior nível que o antigo "aplicar §11 explícito". Meticuloso com consistência.
+Merge idempotente — re-aplicar os mesmos docs source não duplica conteúdo.
+
+## Pré-condições
+
+| # | Validação | Se falhar |
+|---|-----------|-----------|
+| 1 | `$ARGUMENTS` informado | Parar |
+| 2 | `.context.md` com status `dev_done` (uso auto no /sf-dev) OU `design_done` a mais (uso manual) | Se anterior → "Rode /sf-design primeiro" |
+| 3 | Pelo menos PRD.md OU TRD.md existe e está aprovado | Parar — "Nenhum doc source aprovado pra mergear" |
+| 4 | `docs/` populado (veio de first-run anterior) | Parar — "/sf-design com first_run=true é quem cria docs/" |
+
+> `/sf-merge-docs` **só se aplica a features**, não a first-run. Em first-run, é o
+> próprio `/sf-design` que cria `docs/` a partir de PRD+TRD — não há o que mergear.
+
+## Passos
+
+### 1. Snapshot do estado atual de docs/
+
+Ler `docs/{architecture,domain,conventions,apiContracts,decisions}.md`.
+Indexar por elementos (tabelas, endpoints, ADRs, papéis, env vars...) pra diff.
+
+### 2. Extrair elementos-destino do PRD e TRD aprovados
+
+| Fonte (PRD/TRD) | Elemento | Destino em docs/ |
+|-----------------|----------|------------------|
+| TRD §1.1 Stack | Nova tecnologia / versão | `architecture.md` §Stack |
+| TRD §1.2 Arquitetura | Novo container / padrão | `architecture.md` §Containers/Padrões |
+| TRD §1.3 Ambientes | Novo ambiente / mudança | `architecture.md` §Ambientes |
+| TRD §1.4 Deploy | Mudança na estratégia | `architecture.md` §Deploy |
+| TRD §4 §Área-DB | Nova tabela / índice / FK | `domain.md` §Catálogo de Tabelas |
+| TRD §2.1 Endpoints | Novo endpoint | `apiContracts.md` §Catálogo |
+| TRD §7.1 Auth | Mudança em auth | `conventions.md` §Autenticação |
+| TRD §7.2 Autorização | Novo papel / permissão | `conventions.md` §Autorização |
+| TRD §7.3 LGPD | Novo dado pessoal | `conventions.md` §LGPD |
+| TRD §7.4 Rate limit | Nova categoria | `conventions.md` §Rate Limiting |
+| TRD §5.3 Env vars | Nova variável | `conventions.md` §Variáveis de Ambiente |
+| TRD §6 Integrações | Novo sistema externo | `domain.md` §Integrações Externas |
+| TRD §9 ADRs | Nova decisão | `decisions.md` (append-only, imutável) |
+| PRD §2 Atores | Novo papel/persona | `domain.md` §Usuários e Papéis |
+| PRD §5 RNs | Nova regra de negócio | (não vai pra docs/ — fica em specs/{nome}/contracts.md) |
+
+> **Regra**: PRD alimenta poucas seções de `docs/` (só atores e alto-nível).
+> O grosso vem do TRD — `docs/` é síntese técnica + negócio cross-feature.
+
+### 3. Diff semântico: calcular ADDED / MODIFIED / REMOVED
+
+Pra cada elemento-destino extraído (passo 2), comparar com snapshot (passo 1):
+
+| Resultado | Condição | Ação |
+|-----------|----------|------|
+| ADDED | Elemento não existe em docs/ | Adicionar na seção apropriada |
+| MODIFIED | Elemento existe mas mudou (nome igual, valor diferente) | Atualizar campos |
+| UNCHANGED | Elemento existe e está igual | Skip (idempotente) |
+| REMOVED | Elemento estava em docs/ mas não aparece em PRD+TRD aprovados | **NÃO remover** — apenas registrar no output como "possivelmente orfão" |
+
+> **Conservadorismo em REMOVED**: PRD/TRD falam só da feature atual. Algo que
+> "não aparece" pode ser de outra feature (que continua válida). NUNCA deletar
+> automaticamente. Reportar e deixar remoção manual.
+
+### 4. Aplicar ADDED e MODIFIED
+
+- Localizar seção apropriada no doc destino
+- Preservar estrutura do template (não quebrar tabelas)
+- ADRs em `decisions.md`: SEMPRE append; ADR com status=aceita é imutável
+- Registrar cada mudança em changelog do doc afetado
+
+### 5. Changelog em cada doc afetado
+
+Adicionar linha no `## Changelog` do doc:
+
+```markdown
+| Data | Feature | Tipo | Descrição |
+|------|---------|------|-----------|
+| {{ISO_DATE}} | $ARGUMENTS | ADDED | Endpoint POST /api/v1/users |
+| {{ISO_DATE}} | $ARGUMENTS | MODIFIED | Matriz de permissões: novo role `manager` |
+```
+
+### 6. Validar consistência cross-doc
+
+- Referências quebradas (endpoint do apiContracts referencia tabela que não existe em domain) → reportar
+- Papel novo em conventions mas não aparece em matriz de autorização → reportar
+- ADR substituída mas ainda referenciada → reportar
+
+Validação reporta, não bloqueia. Usuário decide se resolve manualmente.
+
+### 7. Atualizar status
+
+```yaml
+status: "done"
+ultima_skill: "/sf-merge-docs"
+atualizado_em: "{{ISO_DATETIME}}"
+```
+
+### 8. Saída obrigatória
+
+```
+/sf-merge-docs $ARGUMENTS — completo
+
+docs/ sincronizado com PRD + TRD aprovados:
+- docs/architecture.md    (2 ADDED, 0 MODIFIED)
+- docs/apiContracts.md    (3 ADDED, 1 MODIFIED)
+- docs/conventions.md     (0 ADDED, 1 MODIFIED — novo role)
+- docs/decisions.md       (1 ADDED — ADR-007)
+- docs/domain.md          (0 mudanças)
+
+Possivelmente órfãos (NÃO removidos — revisão manual):
+  - docs/apiContracts.md: endpoint `/legacy/foo` não aparece em PRD+TRD novos
+    (pode ser de outra feature; deletar manualmente se confirmado deprecated)
+
+Validação: passed / N issues
+```
+
+## Erros
+
+| Erro | Ação |
+|------|------|
+| Status != `dev_done` (auto) nem >= `design_done` (manual) | Parar — pedir rodar /sf-dev ou /sf-design primeiro |
+| `docs/` não existe | Parar — explicar que `/sf-design` em first-run cria docs/ (feature só atualiza) |
+| PRD+TRD sem nada novo vs docs/ | Marcar `done` (legítimo — feature sem impacto cross-feature) |
+| Elemento MODIFIED não encontrado no doc | Converter pra ADDED + reportar (doc estava desatualizado) |
+| Referências quebradas detectadas | Reportar, não bloqueia |
+
+## Uso automático (pelo `/sf-dev`)
+
+`/sf-dev` chama `/sf-merge-docs` automaticamente ao final de feature (não first-run):
+
+- Condição: `status=dev_done` E `first_run=false` E (`prd_aprovado=true` OU `trd_aprovado=true`)
+- Rodado inline, sem nova interação
+- Falha em `/sf-merge-docs` não derruba `/sf-dev` — apenas reporta; user pode re-rodar manualmente
+
+## Uso manual
+
+Rodar `/sf-merge-docs $ARGUMENTS` quando:
+- `/sf-dev` falhou e você quer sincronizar docs/ com o que já foi aprovado
+- Fez edição direta em PRD/TRD aprovados e quer propagar pra docs/
+- Quer forçar um re-merge (idempotente — não duplica)

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

@@ -1,128 +1,152 @@
-# /sf-plan $ARGUMENTS
-
-Skill atômica de planejamento. Lê SDD + specs/{nome}/ e gera `specs/{nome}/tasks.md` (arquivo único) + `workspace/Output/{nome}/Progresso.md`.
-$ARGUMENTS = nome (ex: setup_projeto, feat_cadastro_cliente)
-
-## Agente: Planner (Opus)
-Metódico e exaustivo. Cada task auto-contida. Prioriza ordem correta.
-
-## Pré-condições
-
-| # | Validação | Se falhar |
-|---|-----------|-----------|
-| 1 | $ARGUMENTS informado | Parar |
-| 2 | `.context.md` com status `design_done` | Se anterior → "/sf-design primeiro". Se posterior → "Tasks já geradas" |
-| 3 | `workspace/Output/{nome}/sdd.md` existe | Parar → "/sf-design primeiro" |
-| 4 | `specs/{nome}/contracts.md` e `scenarios.md` existem (projeções) | Parar → "/sf-design não gerou projeções — re-rode" |
-
-## Passos
-
-### 1. Ler contexto
-- `workspace/Output/{nome}/sdd.md` completo (fonte humana)
-- `specs/{nome}/contracts.md` e `scenarios.md` (projeções já geradas pelo /sf-design)
-- `projetos.yaml` + `docs/` (architecture, domain, conventions) + `.github/rules.md`
-- Template `.github/templates/specs/tasks.template.md`
-
-### 2. Identificar fases de entrega
-Ler PRD §11 (Fases de Entrega) — cada fase vira um agrupamento de tasks:
-- Fases são sequenciais: Fase 2 depende de Fase 1 concluída
-- Cada fase tem entregável e critério de done
-- O `/sf-dev` pode rodar por fase: `/sf-dev feat_nome --fase 1`
-
-### 3. Identificar áreas (por fase)
-
-| Seção SDD | Área |
-|-----------|------|
-| §3 Modelo de dados | DB |
-| §5 Endpoints API | BACK |
-| §6 Componentes/Telas | FRONT |
-| §8 Integrações | INFRA |
-| Outras | MOBILE, DEVOPS, etc. conforme SDD |
-
-> **Nota**: Área DOC NÃO existe mais no setup. `docs/` é gerado pelo /sf-design (passo 3).
-> DOC só aparece em features se houver necessidade explícita de documentação adicional.
-
-Áreas são DINÂMICAS — só criar as que o SDD exige.
-
-**Área INFRA obrigatória no setup:**
-```
-- [ ] INFRA-001: Validar e configurar ambiente local [M]
-- [ ] INFRA-002: Criar docker-compose.yml + Dockerfiles [M]
-- [ ] INFRA-003: Hello world — subir stack completa e validar [M]
-```
-INFRA-001 é a PRIMEIRA task do setup. INFRA-003 é a ÚLTIMA (validação final).
-
-### 4. Gerar `specs/{nome}/tasks.md` (arquivo único)
-
-Gerar UM arquivo só em `specs/{nome}/tasks.md` com tabela única de todas as tasks, coluna `Área` diferencia.
-
-```markdown
-| ID | Área | Fase | Tam | Título | Repo | Arquivos | Depende de | Ref spec | Ref CA |
-|----|------|------|-----|--------|------|----------|-----------|----------|--------|
-| DB-001 | DB | 1 | S | Migration clientes | api | src/Migrations/... | — | SDD §3.1 | — |
-| BACK-001 | BACK | 1 | M | Endpoint POST /clientes | api | src/Api/... | DB-001 | SDD §5.1 | CA-001 |
-```
-
-Regras:
-- Cada task é atômica — coder lê `specs/{nome}/` + task, nada mais
-- **Repo obrigatório** — consultar `projetos.yaml`. Caminhos relativos ao repo
-- Área é COLUNA, não arquivo (DB, BACK, FRONT, INFRA, DOC, MOBILE...)
-- Tamanhos: S (<30min), M (30min-2h), L (2h+). L → avaliar se quebra em M+S
-- IDs sequenciais por área, nunca reutilizar
-- Dependências cross-area permitidas
-- `Ref spec`: seção do SDD (ex: `SDD §3.1`)
-- `Ref CA`: ID do critério em `specs/{nome}/scenarios.md` ou `—`
-- Ordenar tabela por Fase → Área → ID (visual)
-
-### 5. Gerar `workspace/Output/{nome}/Progresso.md` (tracking)
-Progresso.md fica em **workspace/Output** (user tracking, não spec).
-- Resumo Área × Fase com contagem (derivado de `tasks.md`)
-- Ordem de execução com paralelismos
-- Checklist pós-conclusão
-
-**Regra**: status vive SÓ em Progresso.md. `tasks.md` é o plano imutável.
-
-### 6. Atualizar progresso global + `.context.md`
-```yaml
-status: "plan_done"
-ultima_skill: "/sf-plan"
-```
-
-### 7. Publicar Progresso no backend (OBRIGATÓRIO quando config existe)
-
-**Este passo NÃO é opcional**. Tomar decisão baseada em arquivo:
-
-| Detecção | Ação |
-|----------|------|
-| `sfw.config.yml` NÃO existe | Pular silenciosamente. Registrar: "publish: skipped (no sfw.config.yml)" |
-| `sfw.config.yml` existe | **Chamar `/sf-publish $ARGUMENTS Progresso`** — sem condicional. Execute. |
-
-`/sf-publish` respeita `mode` de cada target. Ver `.github/skills/sf-publish/SKILL.md`.
-
-**Nota**: `tasks.md`, `specs/`, `docs/`, `projetos.yaml` são LOCAL ONLY — `/sf-publish` nunca toca neles.
-
-### 8. Saída obrigatória
-
-Antes de terminar, a skill DEVE reportar:
-
-```
-/sf-plan $ARGUMENTS — completo
-
-Artefatos locais:
-  - specs/$ARGUMENTS/tasks.md ({N} tasks em {F} fases, áreas: [{lista}])
-  - workspace/Output/$ARGUMENTS/Progresso.md
-
-Publish:
-  - {target-name}: {CREATED|UPDATED|SKIPPED|CONFLICT|ERROR} — ver .ai/sf-publish-log.md
-  OU
-  - SKIPPED (no sfw.config.yml)
-
-Próximo passo:
-  /sf-dev $ARGUMENTS         ← implementa tudo
-  /sf-dev $ARGUMENTS --fase 1   ← só fase 1
-```
-
-## Saídas
-- `specs/{nome}/tasks.md` — tabela única
-- `workspace/Output/{nome}/Progresso.md` — tracking
-- `workspace/Output/progresso.md` (global) — atualizado
+
+# /sf-plan $ARGUMENTS
+
+Skill atômica de planejamento. Lê **PRD + TRD + specs/{nome}/** e gera
+`specs/{nome}/tasks.md` (arquivo único) + `workspace/Output/{nome}/Progresso.md`.
+`$ARGUMENTS` = nome do scope (ex: `app_barbearia`, `feat_cadastro_cliente`).
+
+## Agente: Planner (Opus)
+
+Metódico e exaustivo. Cada task auto-contida. Prioriza ordem correta.
+
+## Pré-condições
+
+| # | Validação | Se falhar |
+|---|-----------|-----------|
+| 1 | $ARGUMENTS informado | Parar |
+| 2 | `.context.md` com status `design_done` | Se anterior → "/sf-design primeiro". Se posterior → "Tasks já geradas" |
+| 3 | Se `prd_existe=true`: PRD.md existe e `prd_aprovado=true` | Parar (não deveria passar pelo /sf-design, mas defensivo) |
+| 4 | Se `trd_existe=true`: TRD.md existe e `trd_aprovado=true` | Parar |
+| 5 | `specs/{nome}/{contracts,scenarios}.md` existem (projeções do /sf-design) | Parar → "/sf-design não gerou projeções — re-rode" |
+
+## Passos
+
+### 1. Ler contexto
+
+- `workspace/Output/{nome}/PRD.md` (se prd_existe) + `TRD.md` (se trd_existe) — fontes
+- `specs/{nome}/{brief,contracts,scenarios}.md` (projeções já geradas pelo /sf-design)
+- `projetos.yaml` + `docs/` (architecture, domain, conventions) + `.github/rules.md`
+- Template `.github/templates/specs/tasks.template.md`
+
+### 2. Identificar fases de entrega
+
+Ler **PRD §10 (Fases de Entrega)** — cada fase vira um agrupamento de tasks:
+
+- Fases são sequenciais: Fase 2 depende de Fase 1 concluída
+- Cada fase tem entregável + critério de done
+- O `/sf-dev` pode rodar por fase: `/sf-dev feat_nome --fase 1`
+
+**Se scope não tem PRD** (puro-técnico): toda task vai pra **Fase 1**. Não há
+fases de entrega de produto — é bootstrap/infra em uma leva só.
+
+### 3. Identificar áreas (dinâmicas, vêm do TRD)
+
+Ler `.context.md → areas_tocadas` (populado pelo /sf-design a partir dos GATEs do TRD).
+
+| Seção do TRD | Área |
+|--------------|------|
+| §2 §Área-Backend (GATE=SIM) | BACK |
+| §3 §Área-Frontend (GATE=SIM) | FRONT |
+| §4 §Área-DB (GATE=SIM) | DB |
+| §5 §Área-Infra (GATE=SIM) | INFRA |
+
+Áreas com GATE=NÃO não geram tasks nessa área. Se o scope tem apenas PRD (raríssimo
+caso puro-produto sem TRD): área FRONT derivada de PRD §7 Telas.
+
+**INFRA em first-run** (detectado via `first_run=true` no .context):
+
+```
+- [ ] INFRA-001: Validar ambiente local + setup repos (projetos.yaml)
+- [ ] INFRA-002: Docker-compose dev (só dependências) + Dockerfiles prod
+- [ ] INFRA-003: Hello world — subir stack completa e validar
+```
+
+INFRA-001 sempre a PRIMEIRA; INFRA-003 sempre a ÚLTIMA da Fase 1 (validação).
+
+### 4. Gerar `specs/{nome}/tasks.md` (arquivo único)
+
+Tabela única com coluna `Área` diferenciando:
+
+```markdown
+| ID | Área | Fase | Tam | Título | Repo | Arquivos | Depende de | Ref TRD | Ref CA |
+|----|------|------|-----|--------|------|----------|-----------|---------|--------|
+| DB-001 | DB | 1 | S | Migration clientes | api | src/db/migrations/... | — | TRD §4.1 | — |
+| BACK-001 | BACK | 1 | M | Endpoint POST /clientes | api | src/routes/... | DB-001 | TRD §2.1 | CA-001 |
+```
+
+**Regras** (ver `.github/templates/specs/tasks.template.md` pra detalhes):
+
+- Cada task é atômica — coder lê `specs/{nome}/` + task, nada mais
+- **Repo obrigatório** — consultar `projetos.yaml`. Caminhos relativos ao repo.
+- Área é COLUNA, não arquivo (DB, BACK, FRONT, INFRA, MOBILE...)
+- Tamanhos: S (≤2h), M (≤4h), L (≤2 dias). L → considerar dividir (INVEST: Small)
+- IDs sequenciais por área, nunca reutilizar
+- Dependências cross-area permitidas
+- `Ref TRD`: seção do TRD (ex: `§2.1`, `§4.2`) — obrigatório quando TRD existe
+- `Ref CA`: ID do CA em `specs/{nome}/scenarios.md` ou `—`
+- Ordenar por Fase → Área → ID (visual)
+
+**Tasks L**: preencher bloco "Done When — {TASK-ID}" abaixo da tabela com 3-5
+bullets verificáveis.
+
+### 5. Gerar `workspace/Output/{nome}/Progresso.md` (tracking)
+
+Progresso.md vive em **workspace/Output** (tracking de execução, não spec).
+
+- Resumo Área × Fase com contagem (derivado de `tasks.md`)
+- Ordem de execução com paralelismos
+- Checklist pós-conclusão (já coberto pelo /sf-merge-docs automático no fim do /sf-dev)
+
+**Regra**: status das tasks vive SÓ em Progresso.md. `tasks.md` é o plano imutável.
+
+### 6. Atualizar `.context.md`
+
+```yaml
+status: "plan_done"
+ultima_skill: "/sf-plan"
+atualizado_em: "{{ISO_DATETIME}}"
+```
+
+### 7. Publicar Progresso no backend (se `sfw.config.yml` existe)
+
+Chamar `/sf-publish $ARGUMENTS Progresso`. Respeita `mode` de cada target.
+
+**Nota**: `tasks.md`, `specs/*`, `docs/*`, `projetos.yaml` são **LOCAL ONLY** — `/sf-publish`
+nunca toca neles. Apenas PRD/TRD/Progresso vão pro Confluence.
+
+### 8. Saída obrigatória
+
+```
+/sf-plan $ARGUMENTS — completo
+
+Artefatos locais:
+  - specs/$ARGUMENTS/tasks.md ({N} tasks em {F} fases, áreas: [{lista}])
+  - workspace/Output/$ARGUMENTS/Progresso.md
+
+Publish:
+  - {target-name}: Progresso: {{status}}
+  OU
+  - SKIPPED (no sfw.config.yml)
+
+Próximo passo:
+  /sf-dev $ARGUMENTS              ← implementa tudo
+  /sf-dev $ARGUMENTS --fase 1     ← só a primeira fase (RECOMENDADO)
+```
+
+## Saídas
+
+- `specs/{nome}/tasks.md` — plano (tabela única)
+- `workspace/Output/{nome}/Progresso.md` — tracking
+
+## Rastreabilidade
+
+Cada task gerada deve ter:
+- **Ref TRD** (se TRD existe): seção do TRD que motivou — garante que nada do TRD
+  fica sem task correspondente
+- **Ref CA** (se aplicável): garante que cada CA em `scenarios.md` tem pelo menos
+  1 task que o satisfaz
+
+Validação final antes de terminar:
+- Todo endpoint do TRD §2.1 tem task BACK correspondente? ✓
+- Toda tabela/migration do TRD §4 tem task DB correspondente? ✓
+- Todo CA em `scenarios.md` tem task Ref CA correspondente (ou justificativa de why not)? ✓