spec-first-copilot 0.7.0 → 0.8.0-beta.2

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

@@ -1,358 +1,450 @@
-# 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/).
+# 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 -->
+
+### 1.6 Padrões Observados
+
+> **Obrigatório quando `tipo: onboard` em `.context.md`**. Em scopes normais é opcional
+> — preenchido apenas se o time já tem convenções tribais não documentadas em `docs/conventions.md`.
+> Coders de features futuras consultam ESTA seção antes de implementar — devem
+> SEGUIR os padrões existentes, não propor mudanças.
+>
+> **Snippets reais do código** (não pseudo-código). Cite arquivo+linha quando aplicável.
+> Quando padrões divergem internamente, documente o **mais frequente** como padrão
+> e cite divergências sem julgar (ex: "3 controllers seguem X, 1 segue Y").
+
+#### 1.6.1 Estrutura de pastas
+
+```
+<!-- snippet real do tree -->
+```
+
+| Camada | Onde mora | Convenção de nome |
+|--------|-----------|-------------------|
+|        |           |                   |
+
+#### 1.6.2 Naming
+
+| Tipo | Padrão observado | Exemplo do código |
+|------|------------------|-------------------|
+| Classe / módulo | | |
+| Função / método | | |
+| Arquivo | | |
+| Variável | | |
+| Constante | | |
+
+#### 1.6.3 Error handling
+
+```
+<!-- snippet real mostrando como erros são tratados (try/catch, Result, exceptions, errors) -->
+```
+
+| Aspecto | Padrão | Onde ver |
+|---------|--------|----------|
+| Captura | | |
+| Propagação | | |
+| Resposta HTTP de erro | | |
+| Logging do erro | | |
+
+#### 1.6.4 Validação
+
+```
+<!-- snippet real de validação de input -->
+```
+
+| Camada | Como valida | Lib/framework |
+|--------|-------------|---------------|
+| HTTP | | |
+| Domain | | |
+| DB | | |
+
+#### 1.6.5 Testes
+
+```
+<!-- snippet real de teste (nomenclatura, estrutura AAA/given-when-then) -->
+```
+
+| Aspecto | Padrão observado |
+|---------|------------------|
+| Framework | |
+| Localização dos testes | |
+| Naming dos arquivos de teste | |
+| Naming dos métodos de teste | |
+| Mock / stub | |
+| Coverage observada | |
+
+#### 1.6.6 Logging
+
+```
+<!-- snippet real de log estruturado -->
+```
+
+| Aspecto | Padrão |
+|---------|--------|
+| Lib | |
+| Níveis usados | |
+| Formato (json/text) | |
+| Campos padrão | |
+
+#### 1.6.7 Divergências internas observadas
+
+> Quando o código tem mais de um padrão pra mesma coisa. Sem julgar — apenas documentar.
+
+| Tema | Padrão dominante | Divergência | Onde ver |
+|------|------------------|-------------|----------|
+|      |                  |             |          |
+
+---
+
+## 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/).