spec-first-copilot 0.7.0-beta.1 → 0.7.0

package/templates/.github/templates/estrutura/decisions.template.md

@@ -1,107 +1,107 @@
-# Decisões — Architecture Decision Records
-
-> Registro de decisões arquiteturais com contexto, alternativas e consequências.
-> Cada decisão é imutável após aceita. Novas decisões podem substituir anteriores.
-
----
-
-<!--
-=============================================================================
-INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
-=============================================================================
-
-PAPEL: Registro APPEND-ONLY de decisões arquiteturais do projeto.
-Histórico de "por que fizemos assim?" — imutável uma vez aceita.
-Consultado por features pra não refazer decisões; feature que queira contestar
-cria nova ADR com status "substituída por ADR-NNN".
-
-ORIGEM (first-run, via /sf-design):
-- SDD §2 Decisões de Design (ADRs de bootstrap: escolha de stack, arquitetura,
-  auth scheme, estratégia de testes) → transcritas aqui como ADR-001, ADR-002...
-
-ATUALIZAÇÃO (feature): /sf-merge-docs aplica SDD §11 ADDED quando feature
-introduz decisão arquitetural nova (raro mas acontece: mudança de padrão,
-nova dependência crítica, trade-off significativo). REMOVED nunca apaga ADR
-existente — muda status pra "substituída".
-
-COMO GERAR:
-1. Para cada decisão significativa, criar registro com TODOS os campos
-2. Contexto: POR QUE essa decisão foi necessária (não apenas "precisávamos")
-3. Alternativas: OBRIGATÓRIO listar ao menos 1 alternativa (com motivo da rejeição)
-4. Consequências: o que MUDA por causa da decisão (positivo E negativo)
-
-REGRAS:
-- IDs sequenciais: ADR-001, ADR-002... nunca reutilizar
-- NUNCA editar decisão com status "aceita" — criar nova com "substituída por ADR-XXX"
-- Status "proposta" = ainda em discussão, não implementar até aceitar
-- Toda mudança de stack, banco, framework DEVE ter registro aqui
-- Decisões são APPEND-ONLY — histórico importa
-
-QUANDO CRIAR:
-- Escolha de tecnologia/framework (em first-run, alimenta a seção inicial)
-- Mudança de padrão de design (feature que introduz)
-- Decisão de infra (cloud provider, DB engine)
-- Trade-off significativo (performance vs simplicidade, etc.)
-- /sf-merge-docs detecta §11 ADDED com impacto arquitetural
-
-QUANDO NÃO CRIAR:
-- Escolha de nome de variável
-- Implementação seguindo padrão já definido
-- Bug fix
-- Refactor sem mudança de interface
-
-=============================================================================
--->
-
-## Índice
-
-| ADR | Título | Status | Data |
-|-----|--------|--------|------|
-| ADR-001 | {{Título}} | proposta / aceita / substituída / descartada | |
-
-## Formato
-
-Cada decisão segue este modelo:
-
-```markdown
-### ADR-NNN: Título da Decisão
-- **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: ...
-```
-
----
-
-## Decisões
-
-### ADR-001: {{Título}}
-- **Status**: aceita
-- **Data**:
-- **Contexto**:
-- **Decisão**:
-- **Alternativas consideradas**:
-  1. —
-- **Consequências**:
-  - Positivas:
-  - Negativas:
-  - Riscos:
-
----
-
-> **Regra**: Decisões aceitas são imutáveis. Para reverter, criar nova decisão com status "substituída por ADR-XXX" na original.
-
----
-
-## Changelog
-
-| Data | Feature | Tipo | Descrição |
-|------|---------|------|-----------|
-|      |         |      |           |
+# Decisões — Architecture Decision Records
+
+> Registro de decisões arquiteturais com contexto, alternativas e consequências.
+> Cada decisão é imutável após aceita. Novas decisões podem substituir anteriores.
+
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+PAPEL: Registro APPEND-ONLY de decisões arquiteturais do projeto.
+Histórico de "por que fizemos assim?" — imutável uma vez aceita.
+Consultado por features pra não refazer decisões; feature que queira contestar
+cria nova ADR com status "substituída por ADR-NNN".
+
+ORIGEM (first-run, via /sf-design):
+- TRD §9 Decisões Técnicas (ADRs de bootstrap: escolha de stack, arquitetura,
+  auth scheme, estratégia de testes) → transcritas aqui como ADR-001, ADR-002...
+
+ATUALIZAÇÃO (feature): /sf-merge-docs faz diff semântico TRD §9 ↔ docs/decisions.md
+e aplica ADDED quando feature introduz ADR nova (raro mas acontece: mudança
+de padrão, nova dependência crítica, trade-off significativo). REMOVED nunca
+apaga ADR existente — muda status pra "substituída".
+
+COMO GERAR:
+1. Para cada decisão significativa, criar registro com TODOS os campos
+2. Contexto: POR QUE essa decisão foi necessária (não apenas "precisávamos")
+3. Alternativas: OBRIGATÓRIO listar ao menos 1 alternativa (com motivo da rejeição)
+4. Consequências: o que MUDA por causa da decisão (positivo E negativo)
+
+REGRAS:
+- IDs sequenciais: ADR-001, ADR-002... nunca reutilizar
+- NUNCA editar decisão com status "aceita" — criar nova com "substituída por ADR-XXX"
+- Status "proposta" = ainda em discussão, não implementar até aceitar
+- Toda mudança de stack, banco, framework DEVE ter registro aqui
+- Decisões são APPEND-ONLY — histórico importa
+
+QUANDO CRIAR:
+- Escolha de tecnologia/framework (em first-run, alimenta a seção inicial)
+- Mudança de padrão de design (feature que introduz)
+- Decisão de infra (cloud provider, DB engine)
+- Trade-off significativo (performance vs simplicidade, etc.)
+- /sf-merge-docs detecta §11 ADDED com impacto arquitetural
+
+QUANDO NÃO CRIAR:
+- Escolha de nome de variável
+- Implementação seguindo padrão já definido
+- Bug fix
+- Refactor sem mudança de interface
+
+=============================================================================
+-->
+
+## Índice
+
+| ADR | Título | Status | Data |
+|-----|--------|--------|------|
+| ADR-001 | {{Título}} | proposta / aceita / substituída / descartada | |
+
+## Formato
+
+Cada decisão segue este modelo:
+
+```markdown
+### ADR-NNN: Título da Decisão
+- **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: ...
+```
+
+---
+
+## Decisões
+
+### ADR-001: {{Título}}
+- **Status**: aceita
+- **Data**:
+- **Contexto**:
+- **Decisão**:
+- **Alternativas consideradas**:
+  1. —
+- **Consequências**:
+  - Positivas:
+  - Negativas:
+  - Riscos:
+
+---
+
+> **Regra**: Decisões aceitas são imutáveis. Para reverter, criar nova decisão com status "substituída por ADR-XXX" na original.
+
+---
+
+## Changelog
+
+| Data | Feature | Tipo | Descrição |
+|------|---------|------|-----------|
+|      |         |      |           |

package/templates/.github/templates/estrutura/domain.template.md

@@ -1,160 +1,161 @@
-# Domínio
-
-> Visão de negócio + modelo de dados.
-> O que o sistema é, quem usa, com o que integra, quais entidades existem e como se relacionam.
-
----
-
-<!--
-=============================================================================
-INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
-=============================================================================
-
-PAPEL: Síntese da visão de negócio + modelo de dados cross-feature.
-Onboarding responde: "o que este sistema é? quem usa? com o que integra? quais tabelas existem?"
-Modelo de dados detalhado por feature vive no SDD §6 do scope; aqui é o consolidado.
-
-ORIGEM (first-run, via /sf-design):
-- PRD §1 Contexto + §2 Atores + §8 Integrações → "O que é este sistema" + "Usuários" + "Integrações"
-- SDD §6 §Área-DB (do setup) → "Modelo de Dados" (diagrama ER, catálogo, convenções)
-- SDD §3.2 Arquitetura (integrações listadas em containers) → complementa Integrações
-
-ATUALIZAÇÃO (feature): /sf-merge-docs aplica SDD §11 ADDED/MODIFIED/REMOVED
-quando feature adiciona/altera tabelas, entidades, atores, integrações externas
-ou termos de domínio. Catálogo de tabelas cresce; glossário expande.
-
-COMO GERAR (first-run):
-1. Ler PRD §1 + §2 + §8 — contexto, atores, integrações (se PRD não-empty)
-2. Ler SDD §6 §Área-DB — tabelas iniciais, convenções de nomenclatura
-3. Ler SDD §3.2 Arquitetura — integrações que aparecem como containers/serviços
-4. Descrever o sistema em 2-3 frases objetivas (O QUE, PARA QUEM, QUAL PROBLEMA)
-5. Listar TODOS os atores com permissões gerais (o que PODE e o que NÃO pode)
-6. Listar TODAS as integrações externas com direção explícita
-7. Gerar diagrama ER textual com TODAS as relações
-8. Catálogo de tabelas com tipos EXATOS do banco (varchar(255), não "string")
-9. Glossário (DDD ubiquitous language) é obrigatório
-10. Se PRD empty (bootstrap puro-técnico): atores e integrações podem ficar vazios
-   — preencher só o que vier do SDD
-
-O QUE NÃO VAI AQUI:
-- Roadmap de módulos → vive no backlog faseado, não no Estrutura
-- Containers, stack, deploy → architecture.md
-- Autorização, LGPD, auditoria → conventions.md
-
-REGRAS:
-- Atores devem ter permissões gerais claras
-- Integrações devem ter direção explícita (envia/recebe/ambos)
-- Toda FK define ON DELETE/ON UPDATE
-- Índices precisam de justificativa (query que justifica)
-- Convenções de nomenclatura são LEI — SDDs seguem à risca
-- Glossário não é opcional — termos ambíguos geram bugs
-
-=============================================================================
--->
-
-## O que é este sistema?
-
-<!-- Descrição em 2-3 frases. O que ele faz, para quem, qual problema resolve. -->
-
-
-## Usuários e Papéis
-
-| Papel | O que faz | O que NÃO pode fazer | Nível de acesso |
-|-------|-----------|----------------------|-----------------|
-|       |           |                      |                 |
-
-## Integrações Externas
-
-| Sistema/Serviço | Tipo (API/Webhook/Arquivo/Fila) | Direção (Envia/Recebe/Ambos) | Descrição | SLA/Disponibilidade |
-|-----------------|--------------------------------|------------------------------|-----------|---------------------|
-|                 |                                |                              |           |                     |
-
-## Restrições e Premissas
-
-### Restrições técnicas
--
-
-### Restrições de negócio
--
-
-### Premissas
--
-
-## Glossário
-
-> Termos do domínio usados em todo o projeto. Linguagem ubíqua (DDD).
-
-| Termo | Definição | Exemplo de uso |
-|-------|-----------|----------------|
-|       |           |                |
-
-## Modelo de Dados
-
-### Diagrama ER
-
-```
-<!-- Representação textual do ER -->
-<!-- Formato: [tabela_a] 1---N [tabela_b] (campo_fk) -->
-```
-
-### Convenções de Nomenclatura
-
-| Elemento | Convenção | Exemplo |
-|----------|-----------|---------|
-| Tabelas | snake_case, plural | `clientes`, `pedidos` |
-| Colunas | snake_case | `nome_completo`, `criado_em` |
-| PKs | `id` (UUID ou SERIAL) | `id UUID PRIMARY KEY DEFAULT gen_random_uuid()` |
-| FKs | `{tabela_singular}_id` | `cliente_id`, `cidade_id` |
-| Índices | `idx_{tabela}_{colunas}` | `idx_clientes_cpf` |
-| Unique | `uq_{tabela}_{colunas}` | `uq_clientes_email` |
-| Timestamps | `criado_em`, `atualizado_em` | `TIMESTAMPTZ NOT NULL DEFAULT now()` |
-| Soft delete | `ativo` (boolean) | `ativo BOOLEAN DEFAULT true` |
-| Auditoria | `criado_por`, `atualizado_por` | `UUID REFERENCES usuarios(id)` |
-
-### Catálogo de Tabelas
-
-<!-- Repetir bloco para cada tabela -->
-
-#### {{tabela}}
-
-> Descrição breve da tabela.
-
-| Coluna | Tipo | Nullable | Default | Constraint | Descrição |
-|--------|------|----------|---------|------------|-----------|
-|        |      |          |         |            |           |
-
-**Relações:**
-- `campo_id` → `tabela_ref(id)` — ON DELETE CASCADE / SET NULL / RESTRICT
-
-**Índices:**
-
-| Nome | Colunas | Tipo | Justificativa |
-|------|---------|------|---------------|
-|      |         | btree / unique / gin | <!-- Qual query justifica este índice? --> |
-
-### Estratégia de Migrations
-
-| Aspecto | Convenção |
-|---------|-----------|
-| Ferramenta | <!-- Ex: knex, prisma, flyway, alembic, EF Core --> |
-| Nomenclatura | <!-- Ex: 001_create_tabela.sql, YYYYMMDD_descricao --> |
-| Rollback | <!-- Toda migration TEM rollback? Testado como? --> |
-| Execução | <!-- Sequencial? Transacional? --> |
-| Dados existentes | <!-- Como lidar com migrations em tabelas com dados? --> |
-
-### Regras Globais de Dados
-
-| Regra | Descrição |
-|-------|-----------|
-| Soft delete | <!-- Todas as tabelas usam? Quais exceções? --> |
-| Auditoria | <!-- criado_por/atualizado_por em todas? --> |
-| Timestamps | <!-- criado_em/atualizado_em obrigatórios? --> |
-| Encoding | <!-- UTF-8? Collation? --> |
-
----
-
-## Changelog
-
-| Data | Feature | Tipo | Descrição |
-|------|---------|------|-----------|
-|      |         |      |           |
+# Domínio
+
+> Visão de negócio + modelo de dados.
+> O que o sistema é, quem usa, com o que integra, quais entidades existem e como se relacionam.
+
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+PAPEL: Síntese da visão de negócio + modelo de dados cross-feature.
+Onboarding responde: "o que este sistema é? quem usa? com o que integra? quais tabelas existem?"
+Modelo de dados detalhado por feature vive no TRD §4 §Área-DB do scope; aqui é o consolidado.
+
+ORIGEM (first-run, via /sf-design):
+- PRD §1 Contexto + §2 Atores + §8 Integrações → "O que é este sistema" + "Usuários" + "Integrações"
+- TRD §4 §Área-DB (do setup) → "Modelo de Dados" (diagrama ER, catálogo, convenções)
+- TRD §1.2 Arquitetura (integrações listadas em containers) + §6 Integrações Externas → complementa Integrações
+
+ATUALIZAÇÃO (feature): /sf-merge-docs faz diff semântico PRD+TRD ↔ docs/
+e aplica ADDED/MODIFIED/REMOVED quando feature adiciona/altera tabelas,
+entidades, atores, integrações externas ou termos de domínio. Catálogo
+de tabelas cresce; glossário expande.
+
+COMO GERAR (first-run):
+1. Ler PRD §1 + §2 + §8 — contexto, atores, integrações (se PRD existe)
+2. Ler TRD §4 §Área-DB — tabelas iniciais, convenções de nomenclatura
+3. Ler TRD §1.2 Arquitetura + §6 Integrações Externas — containers/serviços e integrações
+4. Descrever o sistema em 2-3 frases objetivas (O QUE, PARA QUEM, QUAL PROBLEMA)
+5. Listar TODOS os atores com permissões gerais (o que PODE e o que NÃO pode)
+6. Listar TODAS as integrações externas com direção explícita
+7. Gerar diagrama ER textual com TODAS as relações
+8. Catálogo de tabelas com tipos EXATOS do banco (varchar(255), não "string")
+9. Glossário (DDD ubiquitous language) é obrigatório
+10. Se PRD ausente (bootstrap puro-técnico): atores e integrações podem ficar vazios
+   — preencher só o que vier do TRD
+
+O QUE NÃO VAI AQUI:
+- Roadmap de módulos → vive no backlog faseado, não no Estrutura
+- Containers, stack, deploy → architecture.md
+- Autorização, LGPD, auditoria → conventions.md
+
+REGRAS:
+- Atores devem ter permissões gerais claras
+- Integrações devem ter direção explícita (envia/recebe/ambos)
+- Toda FK define ON DELETE/ON UPDATE
+- Índices precisam de justificativa (query que justifica)
+- Convenções de nomenclatura são LEI — TRDs seguem à risca
+- Glossário não é opcional — termos ambíguos geram bugs
+
+=============================================================================
+-->
+
+## O que é este sistema?
+
+<!-- Descrição em 2-3 frases. O que ele faz, para quem, qual problema resolve. -->
+
+
+## Usuários e Papéis
+
+| Papel | O que faz | O que NÃO pode fazer | Nível de acesso |
+|-------|-----------|----------------------|-----------------|
+|       |           |                      |                 |
+
+## Integrações Externas
+
+| Sistema/Serviço | Tipo (API/Webhook/Arquivo/Fila) | Direção (Envia/Recebe/Ambos) | Descrição | SLA/Disponibilidade |
+|-----------------|--------------------------------|------------------------------|-----------|---------------------|
+|                 |                                |                              |           |                     |
+
+## Restrições e Premissas
+
+### Restrições técnicas
+-
+
+### Restrições de negócio
+-
+
+### Premissas
+-
+
+## Glossário
+
+> Termos do domínio usados em todo o projeto. Linguagem ubíqua (DDD).
+
+| Termo | Definição | Exemplo de uso |
+|-------|-----------|----------------|
+|       |           |                |
+
+## Modelo de Dados
+
+### Diagrama ER
+
+```
+<!-- Representação textual do ER -->
+<!-- Formato: [tabela_a] 1---N [tabela_b] (campo_fk) -->
+```
+
+### Convenções de Nomenclatura
+
+| Elemento | Convenção | Exemplo |
+|----------|-----------|---------|
+| Tabelas | snake_case, plural | `clientes`, `pedidos` |
+| Colunas | snake_case | `nome_completo`, `criado_em` |
+| PKs | `id` (UUID ou SERIAL) | `id UUID PRIMARY KEY DEFAULT gen_random_uuid()` |
+| FKs | `{tabela_singular}_id` | `cliente_id`, `cidade_id` |
+| Índices | `idx_{tabela}_{colunas}` | `idx_clientes_cpf` |
+| Unique | `uq_{tabela}_{colunas}` | `uq_clientes_email` |
+| Timestamps | `criado_em`, `atualizado_em` | `TIMESTAMPTZ NOT NULL DEFAULT now()` |
+| Soft delete | `ativo` (boolean) | `ativo BOOLEAN DEFAULT true` |
+| Auditoria | `criado_por`, `atualizado_por` | `UUID REFERENCES usuarios(id)` |
+
+### Catálogo de Tabelas
+
+<!-- Repetir bloco para cada tabela -->
+
+#### {{tabela}}
+
+> Descrição breve da tabela.
+
+| Coluna | Tipo | Nullable | Default | Constraint | Descrição |
+|--------|------|----------|---------|------------|-----------|
+|        |      |          |         |            |           |
+
+**Relações:**
+- `campo_id` → `tabela_ref(id)` — ON DELETE CASCADE / SET NULL / RESTRICT
+
+**Índices:**
+
+| Nome | Colunas | Tipo | Justificativa |
+|------|---------|------|---------------|
+|      |         | btree / unique / gin | <!-- Qual query justifica este índice? --> |
+
+### Estratégia de Migrations
+
+| Aspecto | Convenção |
+|---------|-----------|
+| Ferramenta | <!-- Ex: knex, prisma, flyway, alembic, EF Core --> |
+| Nomenclatura | <!-- Ex: 001_create_tabela.sql, YYYYMMDD_descricao --> |
+| Rollback | <!-- Toda migration TEM rollback? Testado como? --> |
+| Execução | <!-- Sequencial? Transacional? --> |
+| Dados existentes | <!-- Como lidar com migrations em tabelas com dados? --> |
+
+### Regras Globais de Dados
+
+| Regra | Descrição |
+|-------|-----------|
+| Soft delete | <!-- Todas as tabelas usam? Quais exceções? --> |
+| Auditoria | <!-- criado_por/atualizado_por em todas? --> |
+| Timestamps | <!-- criado_em/atualizado_em obrigatórios? --> |
+| Encoding | <!-- UTF-8? Collation? --> |
+
+---
+
+## Changelog
+
+| Data | Feature | Tipo | Descrição |
+|------|---------|------|-----------|
+|      |         |      |           |