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

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

@@ -1,107 +1,140 @@
-# 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 |
-|------|---------|------|-----------|
-|      |         |      |           |
+# 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
+
+ADRs INFERIDOS (origem /sfw-onboard de projeto brownfield):
+- Quando o /sfw-onboard cria a documentação a partir de código existente, gera
+  ADRs descrevendo decisões OBSERVADAS no código (não tomadas em discussão).
+- Cada ADR inferida tem flag `inferido: true` no início do bloco.
+- Texto descritivo, NÃO prescritivo: "Projeto usa PostgreSQL com JSONB pra X"
+  (não "decidimos usar"). Cartógrafo, não arquiteto.
+- Campo "Contexto" descreve o que o código revela. Campo "Alternativas" pode
+  ficar vazio ou listar "—" — não tem como saber o que foi descartado.
+- Quando dev revisa e confirma/edita o ADR inferido, REMOVE a flag `inferido`.
+- ADRs inferidos podem ser substituídos por novas ADRs (de features futuras)
+  como qualquer outro — flag não afeta imutabilidade.
+
+=============================================================================
+-->
+
+## Formato — ADR normal
+
+```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...
+- **Consequências**:
+  - Positivas: ...
+  - Negativas: ...
+  - Riscos: ...
+```
+
+## Formato — ADR inferida (origem brownfield)
+
+```markdown
+### ADR-NNN: Título descritivo do padrão observado
+- **Status**: aceita
+- **Inferido**: true  <!-- remover este campo após dev revisar e confirmar -->
+- **Data**: YYYY-MM-DD (data do onboarding)
+- **Contexto**: O que o código revela sobre o cenário (não "decidimos" — "projeto usa")
+- **Decisão**: Padrão observado no código + onde ver (arquivo:linha)
+- **Alternativas consideradas**:
+  1. — (não inferível a partir do código)
+- **Consequências**:
+  - Observadas: efeitos visíveis do padrão no código atual
+```
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE — continuação
+=============================================================================
+
+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 | Inferido | Data |
+|-----|--------|--------|----------|------|
+| ADR-001 | {{Título}} | proposta / aceita / substituída / descartada | sim/não | |
+
+---
+
+## Decisões
+
+### ADR-001: {{Título}}
+- **Status**: aceita
+- **Inferido**: <!-- true se veio do /sfw-onboard; omitir após dev revisar -->
+- **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 |
+|------|---------|------|-----------|
+|      |         |      |           |