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

package/templates/.github/templates/feature/Progresso.template.md

@@ -1,141 +1,141 @@
-# Progresso — {{FEATURE}}
-
-> Visão consolidada do andamento da feature.
-> Organizado por **fases de entrega** — cada fase é um entregável independente.
-> Atualizado automaticamente pelo /sf-dev a cada task concluída.
->
-> **Este arquivo rastreia FASES DE ENTREGA, não o pipeline do SFW.**
-> O estado do pipeline (extract_done, design_done, plan_done, dev_in_progress, dev_done, done)
-> vive em `.context.md`. Aqui rastreamos: "as fases de entrega do PRD §11 já foram implementadas?"
-
----
-
-## Status das Fases: `não iniciado`
-
-<!-- não iniciado → em desenvolvimento → em revisão → concluído → arquivado
-(vocabulário PRÓPRIO deste arquivo — não confundir com status da pipeline em .context.md) -->
-
----
-
-<!--
-=============================================================================
-INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
-=============================================================================
-
-COMO GERAR ESTE ARQUIVO:
-
-1. Ler PRD §11 (Fases de Entrega) para definir as fases
-2. Ler TODOS os specs/{nome}/tasks.md da feature
-3. Para cada FASE DE ENTREGA, listar as áreas e contagem de tasks
-4. A visão primária é POR FASE, não por área
-
-COMO ATUALIZAR:
-
-- O /sf-dev atualiza após cada task concluída
-- Status por fase: ⬜ pendente → 🔄 em andamento → ✅ concluída
-- Fase concluída = todas tasks de todas áreas daquela fase estão [x]
-- Ao concluir uma fase: registrar no Histórico + abrir PR
-
-=============================================================================
--->
-
-## Fases de Entrega
-
-| Fase | Nome | Prioridade | Entregável | Status | Tasks |
-|------|------|-----------|------------|--------|-------|
-| 1 | {{Nome}} | P1 | {{Entregável}} | ⬜ pendente | 0/{{N}} |
-| 2 | {{Nome}} | P1 | {{Entregável}} | ⬜ pendente | 0/{{N}} |
-| 3 | {{Nome}} | P2 | {{Entregável}} | ⬜ pendente | 0/{{N}} |
-
----
-
-## Fase 1 — {{Nome}} [P1]
-
-> **Entregável**: {{O que o usuário pode usar}}
-> **Critério de done**: {{Testes E2E que devem passar}}
-> **Branch**: `feature/{{FEATURE}}_fase1`
-> **PR**: (a ser criado)
-
-### Tasks por área
-
-#### {{AREA_1}} ({{N}} tasks)
-
-| Task | Descrição | Tamanho | Repo | Status |
-|------|-----------|---------|------|--------|
-| AREA-001 | | S/M/L | {{repo}} | ⬜ |
-
-#### {{AREA_2}} ({{N}} tasks)
-
-| Task | Descrição | Tamanho | Repo | Status |
-|------|-----------|---------|------|--------|
-| AREA-001 | | S/M/L | {{repo}} | ⬜ |
-
-### Resumo Fase 1
-
-| Área | Total | Feitas | % |
-|------|-------|--------|---|
-| {{AREA_1}} | {{N}} | 0 | 0% |
-| {{AREA_2}} | {{N}} | 0 | 0% |
-| **Total Fase 1** | **{{N}}** | **0** | **0%** |
-
----
-
-## Fase 2 — {{Nome}} [P1]
-
-> **Entregável**: {{...}}
-> **Depende de**: Fase 1 concluída
-
-<!-- Repetir mesma estrutura -->
-
----
-
-## Totais Gerais
-
-| Fase | Total | Feitas | % |
-|------|-------|--------|---|
-| Fase 1 | {{N}} | 0 | 0% |
-| Fase 2 | {{N}} | 0 | 0% |
-| **Total** | **{{N}}** | **0** | **0%** |
-
----
-
-## Ordem de Execução
-
-```
-Fase 1:
-  1. INFRA (setup de repos/ambiente)
-  2. DB (schema/migrations)
-  3. BACK (endpoints) ← pode paralelizar com FRONT após DB
-  4. FRONT (telas)
-  → PR Fase 1 + testes manuais + merge
-
-Fase 2:
-  1. DB (novas tabelas/migrations)
-  2. BACK (endpoints + regras)
-  3. FRONT (telas + integração)
-  → PR Fase 2 + testes manuais + merge
-```
-
----
-
-## Histórico
-
-| Data | Evento | Detalhes |
-|------|--------|----------|
-| | Feature criada | PRD aprovado, SDD gerado |
-
----
-
-## Pós-conclusão (por fase)
-
-- [ ] PR aberto com template detalhado
-- [ ] Ambiente local rodando para testes manuais
-- [ ] Testes automatizados passando (unit + integration + security)
-- [ ] Usuário aprovou e fez merge
-
-## Pós-conclusão (feature completa)
-
-- [ ] Todas fases concluídas e mergeadas
-- [ ] Mergear Delta Specs (SDD §11) nos docs de `docs/`
-- [ ] Atualizar `workspace/Output/progresso.md` (visão global)
-- [ ] Atualizar `.ai/memory/napkin.md` se houver aprendizado relevante
+# Progresso — {{FEATURE}}
+
+> Visão consolidada do andamento da feature.
+> Organizado por **fases de entrega** — cada fase é um entregável independente.
+> Atualizado automaticamente pelo /sf-dev a cada task concluída.
+>
+> **Este arquivo rastreia FASES DE ENTREGA, não o pipeline do SFW.**
+> O estado do pipeline (extract_done, design_done, plan_done, dev_in_progress, dev_done, done)
+> vive em `.context.md`. Aqui rastreamos: "as fases de entrega do PRD §11 já foram implementadas?"
+
+---
+
+## Status das Fases: `não iniciado`
+
+<!-- não iniciado → em desenvolvimento → em revisão → concluído → arquivado
+(vocabulário PRÓPRIO deste arquivo — não confundir com status da pipeline em .context.md) -->
+
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+COMO GERAR ESTE ARQUIVO:
+
+1. Ler PRD §11 (Fases de Entrega) para definir as fases
+2. Ler TODOS os specs/{nome}/tasks.md da feature
+3. Para cada FASE DE ENTREGA, listar as áreas e contagem de tasks
+4. A visão primária é POR FASE, não por área
+
+COMO ATUALIZAR:
+
+- O /sf-dev atualiza após cada task concluída
+- Status por fase: ⬜ pendente → 🔄 em andamento → ✅ concluída
+- Fase concluída = todas tasks de todas áreas daquela fase estão [x]
+- Ao concluir uma fase: registrar no Histórico + abrir PR
+
+=============================================================================
+-->
+
+## Fases de Entrega
+
+| Fase | Nome | Prioridade | Entregável | Status | Tasks |
+|------|------|-----------|------------|--------|-------|
+| 1 | {{Nome}} | P1 | {{Entregável}} | ⬜ pendente | 0/{{N}} |
+| 2 | {{Nome}} | P1 | {{Entregável}} | ⬜ pendente | 0/{{N}} |
+| 3 | {{Nome}} | P2 | {{Entregável}} | ⬜ pendente | 0/{{N}} |
+
+---
+
+## Fase 1 — {{Nome}} [P1]
+
+> **Entregável**: {{O que o usuário pode usar}}
+> **Critério de done**: {{Testes E2E que devem passar}}
+> **Branch**: `feature/{{FEATURE}}_fase1`
+> **PR**: (a ser criado)
+
+### Tasks por área
+
+#### {{AREA_1}} ({{N}} tasks)
+
+| Task | Descrição | Tamanho | Repo | Status |
+|------|-----------|---------|------|--------|
+| AREA-001 | | S/M/L | {{repo}} | ⬜ |
+
+#### {{AREA_2}} ({{N}} tasks)
+
+| Task | Descrição | Tamanho | Repo | Status |
+|------|-----------|---------|------|--------|
+| AREA-001 | | S/M/L | {{repo}} | ⬜ |
+
+### Resumo Fase 1
+
+| Área | Total | Feitas | % |
+|------|-------|--------|---|
+| {{AREA_1}} | {{N}} | 0 | 0% |
+| {{AREA_2}} | {{N}} | 0 | 0% |
+| **Total Fase 1** | **{{N}}** | **0** | **0%** |
+
+---
+
+## Fase 2 — {{Nome}} [P1]
+
+> **Entregável**: {{...}}
+> **Depende de**: Fase 1 concluída
+
+<!-- Repetir mesma estrutura -->
+
+---
+
+## Totais Gerais
+
+| Fase | Total | Feitas | % |
+|------|-------|--------|---|
+| Fase 1 | {{N}} | 0 | 0% |
+| Fase 2 | {{N}} | 0 | 0% |
+| **Total** | **{{N}}** | **0** | **0%** |
+
+---
+
+## Ordem de Execução
+
+```
+Fase 1:
+  1. INFRA (setup de repos/ambiente)
+  2. DB (schema/migrations)
+  3. BACK (endpoints) ← pode paralelizar com FRONT após DB
+  4. FRONT (telas)
+  → PR Fase 1 + testes manuais + merge
+
+Fase 2:
+  1. DB (novas tabelas/migrations)
+  2. BACK (endpoints + regras)
+  3. FRONT (telas + integração)
+  → PR Fase 2 + testes manuais + merge
+```
+
+---
+
+## Histórico
+
+| Data | Evento | Detalhes |
+|------|--------|----------|
+| | Feature criada | PRD e/ou TRD aprovados, specs/ gerado |
+
+---
+
+## Pós-conclusão (por fase)
+
+- [ ] PR aberto com template detalhado
+- [ ] Ambiente local rodando para testes manuais
+- [ ] Testes automatizados passando (unit + integration + security)
+- [ ] Usuário aprovou e fez merge
+
+## Pós-conclusão (feature completa)
+
+- [ ] Todas fases concluídas e mergeadas
+- [ ] Rodar /sf-merge-docs (diff semântico PRD+TRD ↔ docs/) atualizou `docs/`
+- [ ] Atualizar `workspace/Output/progresso.md` (visão global)
+- [ ] Atualizar `.ai/memory/napkin.md` se houver aprendizado relevante

package/templates/.github/templates/feature/TRD.template.md

@@ -0,0 +1,358 @@
+# TRD — {{NOME}}
+## Technical Requirements Document
+
+> **Artefato gerado pela IA** a partir do processamento de insumos técnicos em `workspace/Input/{{NOME}}/`.
+> Este é um dos dois docs source do pipeline SFW (peer do PRD).
+> O TRD é aprovado pelo **dev / tech lead** — contém todas as decisões técnicas da feature.
+> Depois de aprovado, alimenta `/sf-merge-docs` (docs/ cross-feature) e `/sf-design` (specs/).
+
+---
+
+## Meta
+
+| Campo | Valor |
+|-------|-------|
+| Scope | `{{NOME}}` |
+| Status | `em extração` → `aguardando aprovação (dev)` → `aprovado` |
+| Insumos processados | {{LISTA_INSUMOS}} |
+| Gerado em | |
+| Aprovado em | |
+| Aprovado por | {{nome do dev}} |
+
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+QUANDO USAR: Gerado pelo /sf-extract (chamado via /sf-start).
+QUEM GERA: Agent Tech-Analyzer (Opus) a partir dos outputs dos Readers (Sonnet).
+
+PAR COM PRD: o TRD é peer do PRD. Ambos podem coexistir (caso mais comum),
+ou o scope pode ter só um dos dois:
+- Scope puro-produto (raro): só PRD, sem TRD
+- Scope puro-técnico (bootstrap de infra, mudança de stack): só TRD, sem PRD
+- Scope misto (maioria): ambos
+
+REGRA DE OURO: o Analyzer decide qual(is) gerar baseado nos insumos. Não existe
+"TRD empty" — se insumos não trazem conteúdo técnico, simplesmente não gera TRD.
+Filtragem é responsabilidade do Analyzer + rastreada em §11 Rastreabilidade.
+
+ZERO OVERLAP COM PRD:
+- Jornadas de usuário, atores, RNs de negócio, UI → PRD
+- Stack, schema, endpoints, validações de schema, deploy, ADRs → TRD
+- Integrações externas: PRD descreve POR QUÊ; TRD descreve COMO
+- Validações: PRD descreve regras de domínio; TRD descreve validações de formato
+
+COMO GERAR:
+1. Readers (Sonnet) leem cada arquivo do Input/ individualmente e catalogam por seção
+2. Tech-Analyzer (Opus) recebe outputs e:
+   a. Consolida conteúdo técnico em visão unificada
+   b. Organiza por área (§Sistema + §Backend + §Frontend + §DB + §Infra)
+   c. Cruza com `docs/` (se existir) pra evitar decisões contraditórias
+   d. Identifica ambiguidades técnicas (ex: "qual DB?", "sync ou async?")
+3. Consultar `docs/` ANTES de marcar ambiguidade — se `docs/architecture.md` já
+   define stack, não perguntar de novo. Marcar "resolvido em docs/X §Y"
+4. Registrar DE QUAL insumo veio cada informação (rastreabilidade §11)
+
+GATES POR ÁREA:
+Cada seção §Área tem GATE: SIM/NÃO.
+- GATE=SIM: feature toca essa área → preencher completo
+- GATE=NÃO: feature não toca → escrever "N/A — feature não toca esta área" e pular
+Em first-run (bootstrap), §Sistema é SEMPRE GATE=SIM (baseline completo).
+
+ARQUIVOS DE INFRA:
+TRD §Infra inclui docker-compose, Dockerfile, CI/CD scripts, env vars esperadas.
+Mas não inclui arquivo de infra em si — só a DECISÃO. Arquivos reais viram tasks
+no /sf-plan.
+
+RELAÇÃO COM ADRs:
+§9 Decisões Técnicas tem ADR-NNN com justificativa e alternativas. Esses ADRs
+são sincronizados em docs/decisions.md via /sf-merge-docs após aprovação.
+
+RE-GERAÇÃO:
+- Merge ADITIVO com TRD existente (novos insumos não apagam decisões já aprovadas)
+- Seções modificadas marcadas com <!-- ATUALIZADO: re-extração ISO_DATE -->
+- IDs de ADR continuam sequência existente
+- Se user quiser recomeçar do zero: deletar TRD.md + .extract-log.md manualmente
+
+=============================================================================
+-->
+
+## 1. §Sistema
+
+> **GATE**: SIM / NÃO
+> Baseline técnico da feature. Em first-run, preenche-se completo (é a base
+> de todo o projeto). Em features subsequentes, preenche APENAS o que MUDA.
+
+### 1.1 Stack
+
+| Camada | Tecnologia | Versão | Justificativa breve |
+|--------|-----------|--------|---------------------|
+|        |           |        |                     |
+
+### 1.2 Arquitetura (C4 Nível 2)
+
+```
+<!-- Representação textual dos containers e suas conexões -->
+<!-- Formato: [Container] --protocolo--> [Container] -->
+```
+
+| Container | Tecnologia | Responsabilidade | Porta | Comunicação |
+|-----------|-----------|-----------------|-------|-------------|
+|           |           |                 |       |             |
+
+### 1.3 Ambientes
+
+| Ambiente | URL | Banco | Branch |
+|----------|-----|-------|--------|
+| Local    |     |       | qualquer |
+| Staging  |     |       | develop |
+| Produção |     |       | main |
+
+### 1.4 Deploy baseline
+
+| Aspecto | Decisão |
+|---------|---------|
+| Plataforma | |
+| Estratégia | rolling / blue-green / canary |
+| Build | |
+
+### 1.5 Segurança baseline
+
+- Autenticação: <!-- JWT/OAuth2/Session --> (detalhes em §7)
+- CORS: <!-- config geral -->
+- TLS: <!-- versão mínima -->
+- Secrets: <!-- onde e como -->
+
+---
+
+## 2. §Área-Backend
+
+> **GATE**: SIM / NÃO
+
+### 2.1 Endpoints
+
+| Método | Rota | Auth | Responsabilidade |
+|--------|------|------|------------------|
+|        |      |      |                  |
+
+### 2.2 Services / Camadas
+
+| Service | Responsabilidade | Depende de |
+|---------|------------------|------------|
+|         |                  |            |
+
+### 2.3 Validações de entrada (schema)
+
+> Formato/tipo/obrigatoriedade de campos — antes da lógica de negócio.
+
+| Endpoint | Campo | Tipo | Obrigatório | Restrição | Erro |
+|----------|-------|------|-------------|-----------|------|
+|          |       |      |             |           |      |
+
+### 2.4 Libs e dependências principais
+
+| Pacote | Versão | Para quê |
+|--------|--------|----------|
+|        |        |          |
+
+---
+
+## 3. §Área-Frontend
+
+> **GATE**: SIM / NÃO
+
+### 3.1 Rotas
+
+| Rota | Tela | Guard | Descrição |
+|------|------|-------|-----------|
+|      |      |       |           |
+
+### 3.2 Componentes principais
+
+| Componente | Responsabilidade | Props principais |
+|------------|------------------|------------------|
+|            |                  |                  |
+
+### 3.3 State management
+
+| Aspecto | Decisão |
+|---------|---------|
+| Server state | <!-- TanStack Query / SWR / RTK Query --> |
+| Client state | <!-- Context / Zustand / Redux --> |
+| Forms | <!-- React Hook Form / Formik --> |
+
+### 3.4 Design system
+
+- <!-- Tailwind / MUI / Fusion / custom -->
+
+---
+
+## 4. §Área-DB
+
+> **GATE**: SIM / NÃO
+
+### 4.1 Schema
+
+```sql
+-- Entidades desta feature ou alterações em tabelas existentes
+```
+
+### 4.2 Índices e constraints
+
+| Nome | Tabela | Colunas | Tipo | Justificativa |
+|------|--------|---------|------|---------------|
+|      |        |         | btree / unique / gin / EXCLUDE | |
+
+### 4.3 Migrations
+
+| # | Arquivo | Descrição | Rollback? |
+|---|---------|-----------|-----------|
+| 001 | | | Sim/Não |
+
+### 4.4 Convenções (se diferem de docs/domain.md)
+
+- <!-- Apenas o que é particular a esta feature -->
+
+---
+
+## 5. §Área-Infra
+
+> **GATE**: SIM / NÃO
+
+### 5.1 Containers
+
+- <!-- docker-compose.dev (só dependências: postgres, redis, etc.) -->
+- <!-- Dockerfiles pra CI/prod se aplicável -->
+
+### 5.2 CI/CD
+
+| Etapa | Ferramenta | Trigger |
+|-------|-----------|---------|
+| Lint  |           | push    |
+| Test  |           | push    |
+| Build |           | push em main/develop |
+| Deploy staging |  | push em develop |
+| Deploy prod | | tag / manual |
+
+### 5.3 Variáveis de ambiente
+
+| Variável | Obrigatória | Ambientes | Exemplo |
+|----------|-------------|-----------|---------|
+|          | Sim/Não     |           |         |
+
+### 5.4 Monitoramento
+
+| Aspecto | Ferramenta | O que monitora |
+|---------|-----------|----------------|
+| Logs    |           |                |
+| Métricas|           |                |
+| Alertas |           |                |
+
+---
+
+## 6. Integrações Externas
+
+> Sistemas terceiros consumidos ou notificados. Timeout + Retry + Fallback são OBRIGATÓRIOS.
+
+| Sistema | Direção | Protocolo | Timeout | Retry | Fallback |
+|---------|---------|-----------|---------|-------|----------|
+|         | envia/recebe/ambos | REST/gRPC/webhook | | | |
+
+---
+
+## 7. Segurança Detalhada
+
+### 7.1 Autenticação
+
+| Aspecto | Implementação |
+|---------|--------------|
+| Método | JWT / OAuth2 / Session |
+| Expiração access | |
+| Refresh token | |
+| Hash de senha | bcrypt rounds N / argon2 |
+
+### 7.2 Autorização
+
+| Aspecto | Decisão |
+|---------|---------|
+| Tipo | RBAC / ABAC / RBAC+ABAC |
+| Onde é verificado | Middleware / Decorator / Service |
+
+#### Papéis e permissões
+
+| Papel | Herda de | Permissões desta feature |
+|-------|----------|--------------------------|
+|       |          |                          |
+
+### 7.3 LGPD / Privacidade (se aplicável)
+
+| Dado | Base legal | Retenção | Criptografado? |
+|------|-----------|----------|----------------|
+|      |           |          |                |
+
+### 7.4 Rate limiting
+
+| Categoria | Limite | Janela | Resposta |
+|-----------|--------|--------|----------|
+|           |        |        | 429 + Retry-After |
+
+---
+
+## 8. Estratégia de Testes
+
+| Nível | Framework | Escopo | Quando roda |
+|-------|-----------|--------|-------------|
+| Unit | | lógica isolada | por task |
+| Integration | | request → DB → response | por fase |
+| E2E | | jornadas completas | por feature |
+
+---
+
+## 9. Decisões Técnicas (ADRs)
+
+> Cada ADR é imutável após aceita. Sincronizada em docs/decisions.md via /sf-merge-docs.
+
+### ADR-001: {{Título}}
+- **Status**: proposta | aceita | substituída por ADR-XXX | descartada
+- **Data**: YYYY-MM-DD
+- **Contexto**: <!-- Por que essa decisão foi necessária? -->
+- **Decisão**: <!-- O que decidimos? -->
+- **Alternativas consideradas**:
+  1. <!-- Alternativa A — rejeitada porque... -->
+  2. <!-- Alternativa B — rejeitada porque... -->
+- **Consequências**:
+  - Positivas: <!-- -->
+  - Negativas: <!-- -->
+  - Riscos: <!-- -->
+
+---
+
+## 10. Ambiguidades Técnicas
+
+> ⚠️ **BLOQUEANTE** — `/sf-design` NÃO avança enquanto houver linha com `Resposta`
+> vazia E `Resolvido em docs/` vazio.
+>
+> **Como responder** (ver `.github/skills/sf-extract/SKILL.md` → "Como responder ambiguidades"):
+> preencher a coluna `Resposta` direto nesta tabela e rodar `/sf-design` de novo.
+
+| ID | Pergunta | Contexto | Fonte | Consultei docs/? | Resposta | Resolvido em docs/ |
+|----|----------|----------|-------|------------------|----------|--------------------|
+| AMB-TRD-001 | ⚠️ | | | sim / não / ausente | (aguardando) | — |
+
+---
+
+## 11. Rastreabilidade
+
+> Mapa de qual insumo originou qual seção. Permite auditoria da extração.
+
+| Insumo | Tipo | Seções alimentadas |
+|--------|------|--------------------|
+| `{{arquivo}}` | {{tipo}} | §1.1, §1.2, §2.1, §9 (ADR-001) |
+
+---
+
+> **Próximo passo**: Após aprovação do dev (campo `trd_aprovado: true` no
+> `.context.md`), este TRD alimenta `/sf-design` (specs/) + `/sf-merge-docs` (docs/).