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

package/templates/.github/CHANGELOG.md

@@ -1,533 +1,560 @@
-# SFW Changelog — spec-first-copilot
-
-> Este arquivo é atualizado automaticamente pelo `spec-first-copilot update`.
-> O agent deve ler este arquivo quando o usuário perguntar sobre mudanças,
-> funcionalidades novas, ou o que está disponível no framework.
->
-> **Não editar manualmente** — será sobrescrito no próximo update.
-
----
-
-## 0.7.0-beta.1 (2026-04-13) — Redesign v4 (BREAKING)
-
-Reestruturação arquitetural baseada em feedback de uso real do v3. TRD ressuscitado
-como peer do PRD, SDD eliminado, aprovação por persona. Pipeline continua unificado
-via `/sf-start`.
-
-### Breaking
-
-- **TRD ressuscitado** — peer do PRD, aprovado pelo dev. Não é o TRD antigo
-  transiente: agora tem papel próprio (source técnica autoritativa).
-- **SDD eliminado** — camada intermediária desnecessária quando PRD+TRD são bem
-  estruturados. `specs/{nome}/` deriva direto de PRD+TRD. `docs/` atualizado via
-  `/sf-merge-docs` a partir de PRD+TRD.
-- **Aprovação por persona** — PM aprova PRD (`prd_aprovado: true`), dev aprova TRD
-  (`trd_aprovado: true`). Flags no `.context.md`. Em time pequeno, user faz as 2
-  aprovações — não pula.
-- **Discovery obrigatório** — `/sf-discovery` deixou de ser skill opcional e virou
-  passo obrigatório dentro do `/sf-start`. Força entendimento antes da extração.
-- **PRD `empty` removido** — conceito obsoleto. Agora: scope puro-técnico tem
-  `prd_existe=false`; scope puro-produto tem `trd_existe=false`. Maioria tem ambos.
-- **backlog_extraido.md eliminado** — features futuras viram itens em PRD §11
-  Fora de Escopo com sugestão de `/sf-start <nome>` próprio.
-- **Schema do `.context.md` mudou**: `prd_empty` → `prd_existe` + `prd_aprovado`;
-  adicionado `trd_existe` + `trd_aprovado`. Status fluxo tem novos estados:
-  `discovery_done → extract_done → prd_approved → trd_approved → design_done`.
-
-### Templates
-
-- `TRD.template.md` novo — 11 seções, organizado por área (§Sistema + §Área-X)
-- `PRD.template.md` refatorado — 13 seções puro-produto, sem conteúdo técnico
-- `sdd.template.md` deletado
-- `backlog-extraido.template.md` deletado
-- `context.template.md` schema v4
-- `extract-log.template.md` sem categorização "produto/tech" (obsoleta)
-- `specs/*.template.md` com ORIGEM atualizada: PRD+TRD em vez de SDD
-
-### Skills
-
-- `/sf-start` — 2 aprovações + discovery obrigatório
-- `/sf-extract` — gera PRD e/ou TRD conforme conteúdo dos insumos (Reader + Produto-Analyzer + Tech-Analyzer)
-- `/sf-design` — consome PRD+TRD aprovados, gera docs/ (first-run) + specs/
-- `/sf-merge-docs` — diff semântico PRD+TRD ↔ docs/ (agente Integrator promovido pra Opus)
-- `/sf-plan` — entrada PRD+TRD+specs/, tasks com `Ref TRD` em vez de `Ref SDD`
-- `/sf-publish` — adicionado TRD à whitelist; SDD removido
-
-### Agents
-
-- Doc Writer reescrito: fonte muda de "SDD §Sistema" para "PRD + TRD"
-- Coders (backend/frontend/db/infra) e Reviewers: refs de "SDD §X" → "TRD §X" ou "specs/{nome}/"
-
-### Migração de v3 (0.6.x) pra v4
-
-```bash
-# 1. Atualizar kit
-npx spec-first-copilot@beta update
-
-# 2. Para cada scope em andamento: migrar .context.md
-#    - Remover `prd_empty`
-#    - Adicionar `prd_existe`, `trd_existe`, `prd_aprovado`, `trd_aprovado`
-#    - Se scope já tem SDD: extrair conteúdo técnico pra TRD.md manual
-
-# 3. SDDs antigos em workspace/Output/{nome}/sdd.md ficam como legado
-#    (nenhum skill v4 lê eles). Deletar quando confortável.
-```
-
-### Versionamento
-
-- Bump **minor** (0.6 → 0.7) pelo breaking. v3 (`0.6.0-beta.10`) permanece no npm
-  como histórico.
-- Publicado com tag `beta`. Promoção para `latest` apenas após validação em uso real.
-
----
-
-## 0.6.0-beta.10 (2026-04-13)
-
-### `bootstrap-confluence.js` agora é idempotente
-
-Script agora lê `.mcp.json` existente e reusa valores da entry `atlassian` em
-vez de perguntar tudo de novo:
-
-- Se `CONFLUENCE_URL` já existe: mostra URL atual, pergunta "Manter? [S/n]"
-- Se `CONFLUENCE_USERNAME` já existe: mostra email atual, pergunta "Manter? [S/n]"
-- Se `CONFLUENCE_API_TOKEN` já existe: mostra token mascarado (`abcd…wxyz`), pergunta "Manter? [S/n]"
-- Default ENTER = manter. Responder `n` abre o prompt completo da informação.
-
-Se todos os 3 campos foram mantidos: detecta que nada mudou e **não reescreve**
-`.mcp.json` (evita dirty git). Se mudou algo: reescreve preservando outras
-entries MCP (Supabase, GitHub, etc.).
-
-Útil pra: reexecução após novo rebuild do MCP, rotação apenas do token, debug
-de setup sem perder credenciais já válidas.
-
----
-
-## 0.6.0-beta.9 (2026-04-13)
-
-### CLI em pt-BR + dica de bootstrap-confluence no init
-
-Mensagens do CLI (`init` e `update`) traduzidas para pt-BR — usuário final é o público.
-
-Mensagem do `init` reescrita para deixar **explícito o passo opcional de pré-setup
-do Confluence**:
-
-```
-Pronto! Projeto "X" criado.
-
-Próximos passos:
-  1. cd X
-  2. Crie uma pasta em workspace/Input/ com os insumos do seu projeto
-  3. (Opcional) Configure o backend de input/output:
-       cp sfw.config.yml.example sfw.config.yml
-  4. (Opcional, se vai usar Confluence) Prepare o ambiente ANTES de abrir o VS Code:
-       node .github/scripts/bootstrap-confluence.js
-  5. Abra o VS Code com Copilot Chat e rode: /sf-start <nome-da-pasta>
-```
-
-O passo 4 era invisível antes — só aparecia inline na "Dica" do skill `/sf-mcp`.
-Agora aparece logo no fim do `init`, no momento exato em que o usuário vai decidir
-se prepara o Confluence ou não.
-
----
-
-## 0.6.0-beta.8 (2026-04-13)
-
-### Novo: `bootstrap-confluence.js` (opcional, pré-Copilot)
-
-Script Node cross-platform em `.github/scripts/bootstrap-confluence.js` que prepara
-o ambiente para o backend Confluence **antes** de abrir o VS Code com Copilot. Evita
-o ciclo "abrir Copilot → descobrir que falta `uvx` ou credenciais → sair, ajustar,
-reiniciar".
-
-O que faz:
-1. Valida `uvx` instalado (orienta install se faltar — não instala automaticamente)
-2. Coleta URL do Confluence, email Atlassian e API Token (com link pra gerar o token)
-3. Gera/mescla `.mcp.json` preservando outras entries de MCP existentes
-4. Garante `.mcp.json` no `.gitignore`
-5. Pré-cacheia o pacote `mcp-atlassian` via `uvx` (100+ deps no primeiro uso)
-
-Depois é só abrir o VS Code e rodar `/sf-mcp confluence` — vai direto pra descoberta
-da árvore no Confluence, sem reiniciar.
-
-Uso: `node .github/scripts/bootstrap-confluence.js`
-Opcional — `/sf-mcp confluence` sozinho também cobre esses passos, mas exige reiniciar
-VS Code após criar `.mcp.json`.
-
-Skill `/sf-mcp` ganhou nota referenciando o script como atalho recomendado.
-
-### Primeira release sincronizada automaticamente
-
-Primeira release onde o conteúdo compartilhado entre kits veio direto do script
-`npm run sync-kits` no repo SFW — sem cópia manual. Zero drift entre Claude e Copilot
-validado antes do publish.
-
----
-
-## 0.6.0-beta.7 (2026-04-13)
-
-### Fix: 27 referências a slash-commands faltando prefix `sf-`
-
-Ao sincronizar os templates refinados entre os kits (nas releases `beta.5`/`beta.6`),
-cópias manuais deixaram referências estilo `/design`, `/extract`, `/plan` nos
-arquivos do kit Copilot — deveriam ser `/sf-design`, `/sf-extract`, `/sf-plan`.
-
-Corrigido em 27 arquivos: `rules.md`, 2 agents (infra-coder, security-reviewer),
-7 adapters, 5 docs/estrutura templates, 7 feature templates, 4 specs templates e
-progresso_global.
-
-**Impacto**: usuários Copilot que rodaram `init` em `beta.6` devem rodar
-`npx spec-first-copilot update` para aplicar a correção nos templates.
-
-### Script de sync entre kits (interno)
-
-Drift detectado pelo novo `scripts/sync-kits.js` — ferramenta no repo SFW que
-mantém os 2 kits alinhados automaticamente. Fluxo passa a ser: editar em
-`spec-first-claude`, rodar `npm run sync-kits`, commit dos 2 juntos.
-
----
-
-## 0.6.0-beta.6 (2026-04-13)
-
-### Fixes detectados no smoke test de `beta.5`
-
-Rodamos o pipeline completo (`/sf-start → /sf-extract → /sf-design → /sf-plan`) em
-projeto novo com feature simples (todo app backend) e detectamos 6 inconsistências
-entre skills e templates. Todas corrigidas:
-
-**1. PRD §14 — coluna "Resolvido em docs/" adicionada**
-
-Skill `/sf-extract` (beta.5) descreveu mecanismo do Analyzer marcar ambiguidades
-como "resolvido em docs/X §Y", mas o template do PRD não tinha coluna para isso.
-Agora a tabela de §14 tem 6 colunas: `ID | Pergunta | Contexto | Fonte | Resposta | Resolvido em docs/`.
-
-**2. PRD §14 — renomeada "Resposta do usuário" → "Resposta"**
-
-Skill `/sf-extract` fala em preencher "coluna `Resposta`" mas o template tinha
-"Resposta do usuário". Alinhado com o skill. Também adicionado ID padronizado
-`AMB-NNN` na primeira coluna (antes era só `#`).
-
-**3. PRD §14 e SDD §12 padronizados**
-
-SDD §12 Ambiguidades também passou a usar ID `AMB-NNN` continuando a sequência
-do PRD §14. Texto do bloqueio do SDD corrigido: não é o `/sf-design` que bloqueia
-no §12 (ele já gerou), é o `/sf-plan` (que lê o SDD como input).
-
-**4. Status do Progresso.md clarificado**
-
-`Status Geral` do Progresso.md era confundido com o status da pipeline em
-`.context.md`. Renomeado para `Status das Fases` + bloco explicativo deixando
-claro que **este arquivo rastreia fases de entrega do PRD §11, não o pipeline**.
-
-**5. Bool tipado corretamente no `.context.md`**
-
-Antes: `first_run: "{{true|false}}"` (string com aspas). Depois: `first_run: {{true|false}}`
-(bool YAML real). Instruções do template reforçam: "SEM aspas".
-
-**6. `projetos.yaml` sem stack hardcoded**
-
-Template tinha `stack: ".NET 8"` literal no exemplo `api`. Podia induzir projetos
-Node/Python a errar. Agora usa `{{STACK_BACKEND}}` como placeholder + bloco
-explicativo listando exemplos por stack (Backend/Frontend/Mobile) como referência.
-Instruções reforçam: "stack DEVE vir do SDD §3.1".
-
-### Extras
-
-**SDD template com guidance sobre escopo pequeno**
-
-Adicionado bloco no topo do template explicando que 3-4 seções preenchidas + o
-resto como "N/A" é comportamento esperado para apps simples — não inflar conteúdo
-pra "preencher" seções vazias. Áreas não tocadas (§4-§7) usam `GATE: NÃO`.
-
----
-
-## 0.6.0-beta.5 (2026-04-13)
-
-### Refino dos templates de specs/
-
-Templates de projeção do SDD (`specs/{scope}/`) refinados com padrões consolidados de BDD/contract-first. Dois passos de refino fizeram parte desta release.
-
-**`scenarios.template.md`** — mudanças:
-- Seção "Fluxos de Erro e Edge Cases" separada do happy path com coluna "Ref CA" (antes ficavam perdidos e soltos)
-- Seção "Pré-condições Globais" no topo (setup do contexto que aplica a todos os cenários)
-- Campo "Pré-condição" em cada CA (estado adicional específico daquele CA — não repete as globais)
-- Tabela de fluxos com colunas Ator/Ação/Resultado em vez de texto linear
-- UI/Componentes: orientação explícita para features backend-only ("N/A — backend-only")
-- Estratégia de testes: coluna "Responsável" (em vez de "Quem dispara"), sem redefinir frameworks (referencia docs/)
-- Bloco de terminologia explica diferença entre Pré-condições Globais vs Pré-condição do CA
-
-**`contracts.template.md`** — mudanças:
-- Separação explícita em **3 camadas**: Dados (schema do banco) → Validações de Entrada (formato/tipo do request) → Regras de Negócio (invariantes do domínio)
-- "Validações de Entrada" virou seção top-level (antes estava enfiada dentro de Dados)
-- Dados: subseção "Alterações em tabelas existentes" (ADD/ALTER/DROP COLUMN) — antes só tinha formato para tabela nova
-- API: erros têm coluna "Código de domínio" (linkado às RN)
-- Instrução explícita para não duplicar convenções globais de docs/apiContracts.md
-
-**`tasks.template.md`** — mudanças:
-- Padronização de áreas: `DB` (antes inconsistente com `BANCO`)
-- Coluna "Ref SDD" (obrigatória) adicionada — rastreabilidade ao documento fonte para tasks sem CA (INFRA/DOC)
-- Coluna "Ref CA" agora é opcional
-- Seção "Done When" com placeholder real (antes só tinha exemplo em comentário)
-- Removida seção "Regras por área" (era estática, contradiz áreas dinâmicas)
-- Removida seção "Convenções desta feature" (dumping ground — convenções pertencem ao SDD ou docs/)
-- Instrução explícita: bootstrap/first-run → toda task na Fase 1
-
-**`brief.template.md`** — mudanças:
-- Nova seção "Serviços tocados" (quais repos de projetos.yaml esta feature modifica + áreas)
-
-### Padronização de nome de área: `BANCO` → `DB`
-
-Inconsistência detectada entre commands/agents/templates: alguns usavam `BANCO` (português),
-outros usavam `DB`. Padronizado para **`DB`** (alinhado com nome do agente `db-coder.md` e
-com `skills/sf-design/SKILL.md`). 14 arquivos atualizados:
-
-- `.github/agents/db-coder.md`
-- `.github/skills/sf-dev/SKILL.md` (tabela de agents + seletor por prefixo)
-- `.github/skills/sf-plan/SKILL.md` (mapeamento SDD → área + exemplo)
-- `.github/rules.md` (exemplo de quality gate)
-- `.github/templates/feature/projetos.template.yaml` (mapeamento de áreas)
-- `.github/templates/feature/Progresso.template.md` (ordem de execução)
-- `.github/templates/global/progresso_global.template.md` (exemplo)
-
-**Breaking**: IDs de task geradas anteriormente com prefixo `BANCO-*` continuam válidas (IDs
-estáveis, não renomear). Novas features geram `DB-*`.
-
-### `/sf-discovery` declara modelo Opus
-
-Skill não tinha declaração explícita de modelo — rodava com o default da sessão. Descrição
-do skill ("arquiteto senior com mentalidade de consultor crítico... análises profundas e
-honestas") é trabalho Opus. Adicionado bloco **"Agente: Discovery Analyst (Opus)"** no topo.
-
-### Doc gap: como responder ambiguidades do PRD §14
-
-Skill `/sf-extract` ganhou seção dedicada **"Como responder ambiguidades"** com fluxo
-passo a passo (caminho oficial: editar coluna `Resposta` direto no PRD §14 e re-rodar
-`/sf-design`). Skill `/sf-design` agora exibe instrução completa de retomada quando
-bloqueia por ambiguidades pendentes, em vez de só "pedir resposta".
-
-Caminho alternativo (adicionar `ajustes_v1.md` em Input + re-rodar `/sf-extract`) está
-documentado como exceção para mudanças estruturais.
-
----
-
-## 0.6.0-beta.4 (2026-04-13)
-
-### UX: `/sf-mcp confluence` self-contained pra usuário leigo
-
-Perguntas do skill agora mostram EXATAMENTE onde achar cada informação inline,
-sem depender de consulta externa ao SETUP.md:
-
-- **URL do Confluence**: "abra no browser, copie URL base com /wiki"
-- **API Token**: 4 sub-passos numerados (URL Atlassian, Create button, nome, copiar antes que suma)
-- **Space Key**: mostra URL pattern `/wiki/spaces/XXX/` com seta + exemplos ("ST", "DEV", "PROJ")
-- **Root Page ID**: 2 opções (A: Page ID com URL pattern `/pages/NNNN/`, B: título exato com aviso de match)
-
-Qualquer modelo / usuário leigo consegue responder sem ficar travado.
-
----
-
-## 0.6.0-beta.3 (2026-04-13)
-
-### Fix: `/sf-mcp confluence` idempotente com `root_page_id` como âncora
-
-Antes a skill era linear e podia pular a coleta do Page ID raiz do projeto depois de
-um restart (caso user tivesse que reiniciar o Claude após criar `.mcp.json`), resultando
-em `sfw.config.yml` sem `project.root_page_id` — framework ficava sem âncora.
-
-Novo fluxo:
-1. Detecta estado de `sfw.config.yml` (tem root_page_id?) + `.mcp.json` (tem credenciais?)
-2. Se AMBOS existem → testa conexão e reconfirma Input/Output
-3. Se algo falta → pede só o que falta (idempotente)
-4. `root_page_id` validado contra `get_page(id)` antes de mapear árvore
-5. Handler explícito pra 401 (credencial expirou) e 404 (root inválido)
-
-### Fix: Auto-publish imperativo em `/sf-extract`, `/sf-design`, `/sf-plan`
-
-Antes a instrução era "Se `sfw.config.yml` com output.targets[] ativo: Executar /sf-publish" —
-ambígua, agent podia interpretar como opcional e pular.
-
-Agora:
-- Instrução imperativa: "Se `sfw.config.yml` existe → Chamar `/sf-publish`. Execute."
-- Cada skill adiciona **seção "Saída obrigatória"** reportando status do publish
-  (CREATED/UPDATED/SKIPPED/CONFLICT/ERROR) ou "SKIPPED (no sfw.config.yml)"
-- User vê explicitamente o que aconteceu no Confluence
-
-### Fix: `publishes: [PRD, PRD, SDD, Progresso]` → `[PRD, SDD, Progresso]`
-
-Resquício do rename `TRD → PRD` na seção de template do `/sf-mcp confluence`. Agora gera yaml correto.
-
----
-
-## 0.6.0-beta.2 (2026-04-12)
-
-### Fix: CLI `init` output
-
-- Mensagem "Next steps" do `npx spec-first-copilot init` apontava pro `/sf-new-project` removido no v3
-- Agora aponta pro `/sf-start <folder-name>` + nota que framework detecta first-run automaticamente
-- sfw.config.yml.example marcado como opcional (projeto funciona 100% local)
-
----
-
-## 0.6.0-beta.1 (2026-04-12) — Redesign v3 (BREAKING)
-
-Redesign estrutural eliminando o TRD e unificando o pipeline em uma skill única.
-Ver `planodetarefas.md §10` (no repo SFW) pra racional completo e 9 decisões arquiteturais.
-
-### Breaking
-
-- **TRD eliminado** — template `TRD.template.md` removido; conteúdo técnico agora vive no SDD §Sistema (novas subseções 3.1-3.7) e é sintetizado em `docs/` cross-feature
-- **`/sf-new-project` + `/sf-feature` → `/sf-start <nome>`** — entrada única. Detecta automaticamente:
-  - `docs/` ausente → first_run (bootstrap: popula SDD §Sistema completo + cria docs/ + projetos.yaml)
-  - `docs/` existe → feature (popula §Área-X tocadas + §11 Delta Specs)
-- **`/sf-merge-delta` → `/sf-merge-docs`** — nome alinhado ao outcome. "Delta Specs" continua como conceito no SDD §11
-- **PRD empty-allowed** — scopes puro-técnicos marcam `empty: true` em vez de forçar PRD vazio
-- **SDD template reorganizado** — §Sistema (baseline técnico) + §Área-Backend/Frontend/DB/Infra gateáveis por scope
-- **docs/ = síntese cross-feature** (não projeção) — estável, referencia SDDs quando precisa detalhe
-- **Checklist de temas críticos FIXO** — 8 temas unificados (antes era split TRD/PRD). Analyzer consulta `docs/` antes de marcar ambiguidade
-- **Skills: 12 → 11** — `sf-new-project`, `sf-feature`, `sf-merge-delta` removidas; `sf-start`, `sf-merge-docs` adicionadas
-
-### Migração
-
-Projetos em `0.5.0-beta.X` precisam:
-
-1. Rodar `npx spec-first-copilot update` (atualiza .github/, CHANGELOG, templates)
-2. Se tiver `.context.md` com `tipo: feature|setup` ou `documento: PRD|TRD`: migrar pra schema v3:
-   ```yaml
-   first_run: true|false    # true se docs/ não existia quando bootstrap rodou
-   prd_empty: false         # true se TRD existia mas PRD não (raro)
-   areas_tocadas: [BACK, DB]  # derivar do SDD existente
-   ```
-3. Se tiver `TRD.md` em `workspace/Output/{scope}/`: manter como referência histórica ou deletar
-4. Rodar `/sf-merge-docs <scope>` manualmente pra features que estavam em `dev_done` (aplica §11 em `docs/`)
-
-### Novo fluxo (v3)
-
-```
-/sf-start <nome>
-  → /sf-load (se sfw.config.yml)
-  → /sf-discovery (opcional)
-  → /sf-extract → PRD.md (pode ser empty) + .extract-log.md com tech chunks
-  ↓ checkpoint
-/sf-design → SDD (§Sistema + §Área-X) + specs/{nome}/
-  → first_run: cria docs/ + projetos.yaml
-  → feature: §11 Delta Specs pro /sf-merge-docs
-/sf-plan → specs/{nome}/tasks.md + Progresso.md
-/sf-dev → código + Security Review + /sf-merge-docs automático
-```
-
-### Templates atualizados
-
-- `PRD.template.md` — campo `empty` no Meta; rodapé pra caso empty
-- `sdd.template.md` — 552 linhas, §Sistema + §Área-X gateáveis + §12 Ambiguidades com "Consultei docs/?"
-- `context.template.md` — schema v3 (`first_run`, `prd_empty`, `areas_tocadas`)
-- 5 templates em `estrutura/` — papel de síntese cross-feature, origem SDD §Sistema
-- `backlog-extraido.template.md` — scope agnóstico, sugere `/sf-start <nome>` pra promover items
-
-### Arquivos removidos
-
-- `.github/templates/feature/TRD.template.md`
-- `.github/skills/sf-new-project/`, `sf-feature/`, `sf-merge-delta/`
-
----
-
-## 0.5.0-beta.7 (2026-04-12)
-
-### Novo: Comando `/sf-load <nome>`
-Puxa insumos do backend configurado (Confluence ou filesystem) para `workspace/Input/{nome}/`.
-- Busca o scope pelo nome no backend (match exato)
-- Desce recursivamente na árvore (Confluence `get_page_children` é apenas direto — `/sf-load` faz loop)
-- Baixa conteúdo + attachments
-- Log incremental em `.ai/sf-load-log.md` (NOVO/MODIFICADO/INALTERADO via sha256)
-- Idempotente — rodar N vezes sem mudanças no backend não altera nada
-- Referência: `.github/commands/sf-load.md`
-
-### Novo: Adapter layer (Confluence + Filesystem)
-Pipeline agora é backend-agnóstico via adapters plugáveis.
-- **ConfluenceAdapter** — fala com Confluence via MCP `sooperset/mcp-atlassian`
-- **FilesystemAdapter** — lê/escreve direto no disco (também serve como mock pra testes)
-- Configurado em `sfw.config.yml` (copiar de `sfw.config.yml.example`)
-- Interface: `.github/adapters/interface.md` (7 métodos)
-- Erros tipados: `.github/adapters/errors.md` (6 classes)
-- Naming engine: `.github/adapters/naming.md` (placeholders `{scope}`, `{type}`)
-- Registry: `.github/adapters/registry.md`
-- Setup guide: `.github/adapters/SETUP.md` (passo a passo de MCP + Confluence)
-
-### Novo: `sfw.config.yml`
-Manifesto do projeto que define de onde vêm e pra onde vão os artefatos.
-- `input.adapter` — de onde puxar insumos (`confluence` ou `filesystem`)
-- `output.targets[].mode` — ligar/desligar publish (`auto`, `manual`, `off`)
-- `naming.output_container` — template do nome da subpasta no Output (ex: `out_{scope}`)
-- `naming.output_artifact` — template do nome do artefato (ex: `{scope} - {type}`)
-- Copiar `sfw.config.yml.example` e preencher. Zero segredos neste arquivo.
-
-### Novo: `SETUP.md` — Guia de configuração
-Guia passo a passo em `.github/adapters/SETUP.md`:
-- Setup Confluence: uvx, .mcp.json, token Atlassian, space key, page IDs
-- Setup 100% local (filesystem, zero dependências)
-- Como ligar/desligar Confluence via `mode: auto|manual|off`
-- Troubleshooting: tabela com todos os gotchas conhecidos
-- **IMPORTANTE**: Confluence NÃO é CLI. Acesso via MCP tools prefixadas `mcp__atlassian__confluence_*`
-
-### Novo: CLI `update`
-```bash
-npx spec-first-copilot update           # adiciona novos, atualiza framework
-npx spec-first-copilot update --force   # sobrescreve tudo incluindo copilot-instructions.md
-```
-Atualiza projeto existente sem perder arquivos do usuário.
-
-### Breaking: `/sf-setup-projeto` → `/sf-new-project <nome>`
-- Antes: `/sf-setup-projeto` era hardcoded pra pasta `setup_projeto`
-- Agora: `/sf-new-project <nome>` recebe o nome como argumento (simétrico com `/sf-feature <nome>`)
-- `/sf-new-project` gera TRD (bootstrap técnico), `/sf-feature` gera PRD (feature)
-- **Não existe mais pasta mágica** — usuário nomeia livremente em `workspace/Input/`
-- O antigo `setup-projeto.md` foi removido. Usar `new-project.md`
-
-### Breaking: `{sequence}` removido
-- Antes: todo item tinha prefixo numérico `001 - ` pra unicidade no Confluence
-- Agora: usuário nomeia livremente, agent segue o nome do Input
-- Naming simplificado: só `{scope}` e `{type}` como placeholders
-- Premissa: 1 space Confluence = 1 projeto (multi-projeto no mesmo space requer nomes únicos no Input)
-
-### Breaking: Output agrupado por scope
-- Antes: artefatos flat no Output (ex: `001 - TRD setup_projeto`)
-- Agora: subpasta por scope (ex: `out_app_barbearia/app_barbearia - TRD`)
-- Container configurável via `naming.output_container` (default: `out_{scope}`)
-- Artifact configurável via `naming.output_artifact` (default: `{scope} - {type}`)
-
----
-
-## 0.5.0-beta.2 (2026-04-11)
-
-### Refactor: `docs/specs/` → `specs/` (top-level)
-- Projeções do SDD (brief, contracts, scenarios, tasks) movidas pra raiz
-- Regra: humano lê `workspace/Output/`, agent lê `specs/`
-
-### Refactor: 3-zone separation
-- `.github/` = AI config (rules, templates, commands, agents)
-- `docs/` = system knowledge (5 docs de sistema)
-- `workspace/` = team content (Input/ + Output/)
-
----
-
-## 0.4.0 (2026-04-10) — v1 stable
-
-### Funcionalidades base
-- 9 commands: setup-projeto, feature, discovery, extract, design, plan, dev, merge-delta, session-finish
-- 7 agents: backend-coder, frontend-coder, db-coder, infra-coder, doc-writer, reviewer, security-reviewer
-- Templates: PRD, TRD, SDD, tasks, Progresso, context, extract-log, backlog, projetos.yaml
-- Templates de estrutura: architecture, domain, conventions, apiContracts, decisions
-- Pipeline: extract → design → plan → dev com checkpoints de aprovação
-- Delta Specs (SDD §11) + merge-delta automático
-- Security Reviewer como gate pós-dev
-- Multi-repo via projetos.yaml
-- Entregáveis contínuos (fases de entrega)
-
----
-
-## Como usar este arquivo
-
-Se o usuário perguntar:
-- **"O que tem de novo?"** → ler a versão mais recente acima
-- **"Como uso o /sf-load?"** → apontar pra `.github/commands/sf-load.md`
-- **"Como configuro Confluence?"** → apontar pra `.github/adapters/SETUP.md`
-- **"O que é adapter?"** → apontar pra `.github/adapters/interface.md`
-- **"O que mudou de setup-projeto?"** → seção "Breaking" do 0.5.0-beta.7
+# SFW Changelog — spec-first-copilot
+
+> Este arquivo é atualizado automaticamente pelo `spec-first-copilot update`.
+> O agent deve ler este arquivo quando o usuário perguntar sobre mudanças,
+> funcionalidades novas, ou o que está disponível no framework.
+>
+> **Não editar manualmente** — será sobrescrito no próximo update.
+
+---
+
+## 0.7.0 (2026-04-14) — Redesign v4 estável
+
+Promoção de `0.7.0-beta.1` para versão estável. Inclui fix crítico:
+purga de referências SDD residuais que sobreviveram ao beta (incluindo
+whitelist do `/sf-publish`, que silenciosamente pulava TRD).
+
+### Fix — limpeza de resíduos v3
+
+Varredura de 23 arquivos no projeto:
+- `sfw.config.yml.example`: `publishes: [PRD, SDD, Progresso]` → `[PRD, TRD, Progresso]` (bug runtime)
+- `adapters/registry.md` e `naming.md`: refs a SDD como tipo válido → TRD
+- `rules.md`: regras invioláveis 1-4 reescritas ("SDD aprovado" → "PRD/TRD aprovados + specs/")
+- Templates de `estrutura/` (architecture, domain, conventions, apiContracts, decisions):
+  mapeamento completo SDD §X → TRD §Y nas instruções de ORIGEM/ATUALIZAÇÃO
+- Templates de `feature/` (Progresso, projetos.yaml): refs SDD §3.2 → TRD §1.2, etc.
+- `progresso_global.template.md`: legenda de status reescrita com fluxo v4 completo
+- `docs.instructions.md`: reescrito integralmente para v4
+- `sensitive-files.instructions.md`: `sdd.md` → `TRD.md`
+- `copilot-instructions.md`: refs `sdd.md` → `TRD.md`
+- `.ai/memory/napkin.md` (template): princípios invioláveis atualizados
+- READMEs dos 2 packages: narrativa + estrutura + diagrama v4
+
+Refs legítimas mantidas: CHANGELOGs (histórico), `doc-writer.md` e
+`sf-merge-docs/SKILL.md` (explicam a migração v3→v4).
+
+---
+
+## 0.7.0-beta.1 (2026-04-13) — Redesign v4 (BREAKING)
+
+Reestruturação arquitetural baseada em feedback de uso real do v3. TRD ressuscitado
+como peer do PRD, SDD eliminado, aprovação por persona. Pipeline continua unificado
+via `/sf-start`.
+
+### Breaking
+
+- **TRD ressuscitado** — peer do PRD, aprovado pelo dev. Não é o TRD antigo
+  transiente: agora tem papel próprio (source técnica autoritativa).
+- **SDD eliminado** — camada intermediária desnecessária quando PRD+TRD são bem
+  estruturados. `specs/{nome}/` deriva direto de PRD+TRD. `docs/` atualizado via
+  `/sf-merge-docs` a partir de PRD+TRD.
+- **Aprovação por persona** — PM aprova PRD (`prd_aprovado: true`), dev aprova TRD
+  (`trd_aprovado: true`). Flags no `.context.md`. Em time pequeno, user faz as 2
+  aprovações — não pula.
+- **Discovery obrigatório** — `/sf-discovery` deixou de ser skill opcional e virou
+  passo obrigatório dentro do `/sf-start`. Força entendimento antes da extração.
+- **PRD `empty` removido** — conceito obsoleto. Agora: scope puro-técnico tem
+  `prd_existe=false`; scope puro-produto tem `trd_existe=false`. Maioria tem ambos.
+- **backlog_extraido.md eliminado** — features futuras viram itens em PRD §11
+  Fora de Escopo com sugestão de `/sf-start <nome>` próprio.
+- **Schema do `.context.md` mudou**: `prd_empty` → `prd_existe` + `prd_aprovado`;
+  adicionado `trd_existe` + `trd_aprovado`. Status fluxo tem novos estados:
+  `discovery_done → extract_done → prd_approved → trd_approved → design_done`.
+
+### Templates
+
+- `TRD.template.md` novo — 11 seções, organizado por área (§Sistema + §Área-X)
+- `PRD.template.md` refatorado — 13 seções puro-produto, sem conteúdo técnico
+- `sdd.template.md` deletado
+- `backlog-extraido.template.md` deletado
+- `context.template.md` schema v4
+- `extract-log.template.md` sem categorização "produto/tech" (obsoleta)
+- `specs/*.template.md` com ORIGEM atualizada: PRD+TRD em vez de SDD
+
+### Skills
+
+- `/sf-start` — 2 aprovações + discovery obrigatório
+- `/sf-extract` — gera PRD e/ou TRD conforme conteúdo dos insumos (Reader + Produto-Analyzer + Tech-Analyzer)
+- `/sf-design` — consome PRD+TRD aprovados, gera docs/ (first-run) + specs/
+- `/sf-merge-docs` — diff semântico PRD+TRD ↔ docs/ (agente Integrator promovido pra Opus)
+- `/sf-plan` — entrada PRD+TRD+specs/, tasks com `Ref TRD` em vez de `Ref SDD`
+- `/sf-publish` — adicionado TRD à whitelist; SDD removido
+
+### Agents
+
+- Doc Writer reescrito: fonte muda de "SDD §Sistema" para "PRD + TRD"
+- Coders (backend/frontend/db/infra) e Reviewers: refs de "SDD §X" → "TRD §X" ou "specs/{nome}/"
+
+### Migração de v3 (0.6.x) pra v4
+
+```bash
+# 1. Atualizar kit
+npx spec-first-copilot@beta update
+
+# 2. Para cada scope em andamento: migrar .context.md
+#    - Remover `prd_empty`
+#    - Adicionar `prd_existe`, `trd_existe`, `prd_aprovado`, `trd_aprovado`
+#    - Se scope já tem SDD: extrair conteúdo técnico pra TRD.md manual
+
+# 3. SDDs antigos em workspace/Output/{nome}/sdd.md ficam como legado
+#    (nenhum skill v4 lê eles). Deletar quando confortável.
+```
+
+### Versionamento
+
+- Bump **minor** (0.6 → 0.7) pelo breaking. v3 (`0.6.0-beta.10`) permanece no npm
+  como histórico.
+- Publicado com tag `beta`. Promoção para `latest` apenas após validação em uso real.
+
+---
+
+## 0.6.0-beta.10 (2026-04-13)
+
+### `bootstrap-confluence.js` agora é idempotente
+
+Script agora lê `.mcp.json` existente e reusa valores da entry `atlassian` em
+vez de perguntar tudo de novo:
+
+- Se `CONFLUENCE_URL` já existe: mostra URL atual, pergunta "Manter? [S/n]"
+- Se `CONFLUENCE_USERNAME` já existe: mostra email atual, pergunta "Manter? [S/n]"
+- Se `CONFLUENCE_API_TOKEN` já existe: mostra token mascarado (`abcd…wxyz`), pergunta "Manter? [S/n]"
+- Default ENTER = manter. Responder `n` abre o prompt completo da informação.
+
+Se todos os 3 campos foram mantidos: detecta que nada mudou e **não reescreve**
+`.mcp.json` (evita dirty git). Se mudou algo: reescreve preservando outras
+entries MCP (Supabase, GitHub, etc.).
+
+Útil pra: reexecução após novo rebuild do MCP, rotação apenas do token, debug
+de setup sem perder credenciais já válidas.
+
+---
+
+## 0.6.0-beta.9 (2026-04-13)
+
+### CLI em pt-BR + dica de bootstrap-confluence no init
+
+Mensagens do CLI (`init` e `update`) traduzidas para pt-BR — usuário final é o público.
+
+Mensagem do `init` reescrita para deixar **explícito o passo opcional de pré-setup
+do Confluence**:
+
+```
+Pronto! Projeto "X" criado.
+
+Próximos passos:
+  1. cd X
+  2. Crie uma pasta em workspace/Input/ com os insumos do seu projeto
+  3. (Opcional) Configure o backend de input/output:
+       cp sfw.config.yml.example sfw.config.yml
+  4. (Opcional, se vai usar Confluence) Prepare o ambiente ANTES de abrir o VS Code:
+       node .github/scripts/bootstrap-confluence.js
+  5. Abra o VS Code com Copilot Chat e rode: /sf-start <nome-da-pasta>
+```
+
+O passo 4 era invisível antes — só aparecia inline na "Dica" do skill `/sf-mcp`.
+Agora aparece logo no fim do `init`, no momento exato em que o usuário vai decidir
+se prepara o Confluence ou não.
+
+---
+
+## 0.6.0-beta.8 (2026-04-13)
+
+### Novo: `bootstrap-confluence.js` (opcional, pré-Copilot)
+
+Script Node cross-platform em `.github/scripts/bootstrap-confluence.js` que prepara
+o ambiente para o backend Confluence **antes** de abrir o VS Code com Copilot. Evita
+o ciclo "abrir Copilot → descobrir que falta `uvx` ou credenciais → sair, ajustar,
+reiniciar".
+
+O que faz:
+1. Valida `uvx` instalado (orienta install se faltar — não instala automaticamente)
+2. Coleta URL do Confluence, email Atlassian e API Token (com link pra gerar o token)
+3. Gera/mescla `.mcp.json` preservando outras entries de MCP existentes
+4. Garante `.mcp.json` no `.gitignore`
+5. Pré-cacheia o pacote `mcp-atlassian` via `uvx` (100+ deps no primeiro uso)
+
+Depois é só abrir o VS Code e rodar `/sf-mcp confluence` — vai direto pra descoberta
+da árvore no Confluence, sem reiniciar.
+
+Uso: `node .github/scripts/bootstrap-confluence.js`
+Opcional — `/sf-mcp confluence` sozinho também cobre esses passos, mas exige reiniciar
+VS Code após criar `.mcp.json`.
+
+Skill `/sf-mcp` ganhou nota referenciando o script como atalho recomendado.
+
+### Primeira release sincronizada automaticamente
+
+Primeira release onde o conteúdo compartilhado entre kits veio direto do script
+`npm run sync-kits` no repo SFW — sem cópia manual. Zero drift entre Claude e Copilot
+validado antes do publish.
+
+---
+
+## 0.6.0-beta.7 (2026-04-13)
+
+### Fix: 27 referências a slash-commands faltando prefix `sf-`
+
+Ao sincronizar os templates refinados entre os kits (nas releases `beta.5`/`beta.6`),
+cópias manuais deixaram referências estilo `/design`, `/extract`, `/plan` nos
+arquivos do kit Copilot — deveriam ser `/sf-design`, `/sf-extract`, `/sf-plan`.
+
+Corrigido em 27 arquivos: `rules.md`, 2 agents (infra-coder, security-reviewer),
+7 adapters, 5 docs/estrutura templates, 7 feature templates, 4 specs templates e
+progresso_global.
+
+**Impacto**: usuários Copilot que rodaram `init` em `beta.6` devem rodar
+`npx spec-first-copilot update` para aplicar a correção nos templates.
+
+### Script de sync entre kits (interno)
+
+Drift detectado pelo novo `scripts/sync-kits.js` — ferramenta no repo SFW que
+mantém os 2 kits alinhados automaticamente. Fluxo passa a ser: editar em
+`spec-first-claude`, rodar `npm run sync-kits`, commit dos 2 juntos.
+
+---
+
+## 0.6.0-beta.6 (2026-04-13)
+
+### Fixes detectados no smoke test de `beta.5`
+
+Rodamos o pipeline completo (`/sf-start → /sf-extract → /sf-design → /sf-plan`) em
+projeto novo com feature simples (todo app backend) e detectamos 6 inconsistências
+entre skills e templates. Todas corrigidas:
+
+**1. PRD §14 — coluna "Resolvido em docs/" adicionada**
+
+Skill `/sf-extract` (beta.5) descreveu mecanismo do Analyzer marcar ambiguidades
+como "resolvido em docs/X §Y", mas o template do PRD não tinha coluna para isso.
+Agora a tabela de §14 tem 6 colunas: `ID | Pergunta | Contexto | Fonte | Resposta | Resolvido em docs/`.
+
+**2. PRD §14 — renomeada "Resposta do usuário" → "Resposta"**
+
+Skill `/sf-extract` fala em preencher "coluna `Resposta`" mas o template tinha
+"Resposta do usuário". Alinhado com o skill. Também adicionado ID padronizado
+`AMB-NNN` na primeira coluna (antes era só `#`).
+
+**3. PRD §14 e SDD §12 padronizados**
+
+SDD §12 Ambiguidades também passou a usar ID `AMB-NNN` continuando a sequência
+do PRD §14. Texto do bloqueio do SDD corrigido: não é o `/sf-design` que bloqueia
+no §12 (ele já gerou), é o `/sf-plan` (que lê o SDD como input).
+
+**4. Status do Progresso.md clarificado**
+
+`Status Geral` do Progresso.md era confundido com o status da pipeline em
+`.context.md`. Renomeado para `Status das Fases` + bloco explicativo deixando
+claro que **este arquivo rastreia fases de entrega do PRD §11, não o pipeline**.
+
+**5. Bool tipado corretamente no `.context.md`**
+
+Antes: `first_run: "{{true|false}}"` (string com aspas). Depois: `first_run: {{true|false}}`
+(bool YAML real). Instruções do template reforçam: "SEM aspas".
+
+**6. `projetos.yaml` sem stack hardcoded**
+
+Template tinha `stack: ".NET 8"` literal no exemplo `api`. Podia induzir projetos
+Node/Python a errar. Agora usa `{{STACK_BACKEND}}` como placeholder + bloco
+explicativo listando exemplos por stack (Backend/Frontend/Mobile) como referência.
+Instruções reforçam: "stack DEVE vir do SDD §3.1".
+
+### Extras
+
+**SDD template com guidance sobre escopo pequeno**
+
+Adicionado bloco no topo do template explicando que 3-4 seções preenchidas + o
+resto como "N/A" é comportamento esperado para apps simples — não inflar conteúdo
+pra "preencher" seções vazias. Áreas não tocadas (§4-§7) usam `GATE: NÃO`.
+
+---
+
+## 0.6.0-beta.5 (2026-04-13)
+
+### Refino dos templates de specs/
+
+Templates de projeção do SDD (`specs/{scope}/`) refinados com padrões consolidados de BDD/contract-first. Dois passos de refino fizeram parte desta release.
+
+**`scenarios.template.md`** — mudanças:
+- Seção "Fluxos de Erro e Edge Cases" separada do happy path com coluna "Ref CA" (antes ficavam perdidos e soltos)
+- Seção "Pré-condições Globais" no topo (setup do contexto que aplica a todos os cenários)
+- Campo "Pré-condição" em cada CA (estado adicional específico daquele CA — não repete as globais)
+- Tabela de fluxos com colunas Ator/Ação/Resultado em vez de texto linear
+- UI/Componentes: orientação explícita para features backend-only ("N/A — backend-only")
+- Estratégia de testes: coluna "Responsável" (em vez de "Quem dispara"), sem redefinir frameworks (referencia docs/)
+- Bloco de terminologia explica diferença entre Pré-condições Globais vs Pré-condição do CA
+
+**`contracts.template.md`** — mudanças:
+- Separação explícita em **3 camadas**: Dados (schema do banco) → Validações de Entrada (formato/tipo do request) → Regras de Negócio (invariantes do domínio)
+- "Validações de Entrada" virou seção top-level (antes estava enfiada dentro de Dados)
+- Dados: subseção "Alterações em tabelas existentes" (ADD/ALTER/DROP COLUMN) — antes só tinha formato para tabela nova
+- API: erros têm coluna "Código de domínio" (linkado às RN)
+- Instrução explícita para não duplicar convenções globais de docs/apiContracts.md
+
+**`tasks.template.md`** — mudanças:
+- Padronização de áreas: `DB` (antes inconsistente com `BANCO`)
+- Coluna "Ref SDD" (obrigatória) adicionada — rastreabilidade ao documento fonte para tasks sem CA (INFRA/DOC)
+- Coluna "Ref CA" agora é opcional
+- Seção "Done When" com placeholder real (antes só tinha exemplo em comentário)
+- Removida seção "Regras por área" (era estática, contradiz áreas dinâmicas)
+- Removida seção "Convenções desta feature" (dumping ground — convenções pertencem ao SDD ou docs/)
+- Instrução explícita: bootstrap/first-run → toda task na Fase 1
+
+**`brief.template.md`** — mudanças:
+- Nova seção "Serviços tocados" (quais repos de projetos.yaml esta feature modifica + áreas)
+
+### Padronização de nome de área: `BANCO` → `DB`
+
+Inconsistência detectada entre commands/agents/templates: alguns usavam `BANCO` (português),
+outros usavam `DB`. Padronizado para **`DB`** (alinhado com nome do agente `db-coder.md` e
+com `skills/sf-design/SKILL.md`). 14 arquivos atualizados:
+
+- `.github/agents/db-coder.md`
+- `.github/skills/sf-dev/SKILL.md` (tabela de agents + seletor por prefixo)
+- `.github/skills/sf-plan/SKILL.md` (mapeamento SDD → área + exemplo)
+- `.github/rules.md` (exemplo de quality gate)
+- `.github/templates/feature/projetos.template.yaml` (mapeamento de áreas)
+- `.github/templates/feature/Progresso.template.md` (ordem de execução)
+- `.github/templates/global/progresso_global.template.md` (exemplo)
+
+**Breaking**: IDs de task geradas anteriormente com prefixo `BANCO-*` continuam válidas (IDs
+estáveis, não renomear). Novas features geram `DB-*`.
+
+### `/sf-discovery` declara modelo Opus
+
+Skill não tinha declaração explícita de modelo — rodava com o default da sessão. Descrição
+do skill ("arquiteto senior com mentalidade de consultor crítico... análises profundas e
+honestas") é trabalho Opus. Adicionado bloco **"Agente: Discovery Analyst (Opus)"** no topo.
+
+### Doc gap: como responder ambiguidades do PRD §14
+
+Skill `/sf-extract` ganhou seção dedicada **"Como responder ambiguidades"** com fluxo
+passo a passo (caminho oficial: editar coluna `Resposta` direto no PRD §14 e re-rodar
+`/sf-design`). Skill `/sf-design` agora exibe instrução completa de retomada quando
+bloqueia por ambiguidades pendentes, em vez de só "pedir resposta".
+
+Caminho alternativo (adicionar `ajustes_v1.md` em Input + re-rodar `/sf-extract`) está
+documentado como exceção para mudanças estruturais.
+
+---
+
+## 0.6.0-beta.4 (2026-04-13)
+
+### UX: `/sf-mcp confluence` self-contained pra usuário leigo
+
+Perguntas do skill agora mostram EXATAMENTE onde achar cada informação inline,
+sem depender de consulta externa ao SETUP.md:
+
+- **URL do Confluence**: "abra no browser, copie URL base com /wiki"
+- **API Token**: 4 sub-passos numerados (URL Atlassian, Create button, nome, copiar antes que suma)
+- **Space Key**: mostra URL pattern `/wiki/spaces/XXX/` com seta + exemplos ("ST", "DEV", "PROJ")
+- **Root Page ID**: 2 opções (A: Page ID com URL pattern `/pages/NNNN/`, B: título exato com aviso de match)
+
+Qualquer modelo / usuário leigo consegue responder sem ficar travado.
+
+---
+
+## 0.6.0-beta.3 (2026-04-13)
+
+### Fix: `/sf-mcp confluence` idempotente com `root_page_id` como âncora
+
+Antes a skill era linear e podia pular a coleta do Page ID raiz do projeto depois de
+um restart (caso user tivesse que reiniciar o Claude após criar `.mcp.json`), resultando
+em `sfw.config.yml` sem `project.root_page_id` — framework ficava sem âncora.
+
+Novo fluxo:
+1. Detecta estado de `sfw.config.yml` (tem root_page_id?) + `.mcp.json` (tem credenciais?)
+2. Se AMBOS existem → testa conexão e reconfirma Input/Output
+3. Se algo falta → pede só o que falta (idempotente)
+4. `root_page_id` validado contra `get_page(id)` antes de mapear árvore
+5. Handler explícito pra 401 (credencial expirou) e 404 (root inválido)
+
+### Fix: Auto-publish imperativo em `/sf-extract`, `/sf-design`, `/sf-plan`
+
+Antes a instrução era "Se `sfw.config.yml` com output.targets[] ativo: Executar /sf-publish" —
+ambígua, agent podia interpretar como opcional e pular.
+
+Agora:
+- Instrução imperativa: "Se `sfw.config.yml` existe → Chamar `/sf-publish`. Execute."
+- Cada skill adiciona **seção "Saída obrigatória"** reportando status do publish
+  (CREATED/UPDATED/SKIPPED/CONFLICT/ERROR) ou "SKIPPED (no sfw.config.yml)"
+- User vê explicitamente o que aconteceu no Confluence
+
+### Fix: `publishes: [PRD, PRD, SDD, Progresso]` → `[PRD, SDD, Progresso]`
+
+Resquício do rename `TRD → PRD` na seção de template do `/sf-mcp confluence`. Agora gera yaml correto.
+
+---
+
+## 0.6.0-beta.2 (2026-04-12)
+
+### Fix: CLI `init` output
+
+- Mensagem "Next steps" do `npx spec-first-copilot init` apontava pro `/sf-new-project` removido no v3
+- Agora aponta pro `/sf-start <folder-name>` + nota que framework detecta first-run automaticamente
+- sfw.config.yml.example marcado como opcional (projeto funciona 100% local)
+
+---
+
+## 0.6.0-beta.1 (2026-04-12) — Redesign v3 (BREAKING)
+
+Redesign estrutural eliminando o TRD e unificando o pipeline em uma skill única.
+Ver `planodetarefas.md §10` (no repo SFW) pra racional completo e 9 decisões arquiteturais.
+
+### Breaking
+
+- **TRD eliminado** — template `TRD.template.md` removido; conteúdo técnico agora vive no SDD §Sistema (novas subseções 3.1-3.7) e é sintetizado em `docs/` cross-feature
+- **`/sf-new-project` + `/sf-feature` → `/sf-start <nome>`** — entrada única. Detecta automaticamente:
+  - `docs/` ausente → first_run (bootstrap: popula SDD §Sistema completo + cria docs/ + projetos.yaml)
+  - `docs/` existe → feature (popula §Área-X tocadas + §11 Delta Specs)
+- **`/sf-merge-delta` → `/sf-merge-docs`** — nome alinhado ao outcome. "Delta Specs" continua como conceito no SDD §11
+- **PRD empty-allowed** — scopes puro-técnicos marcam `empty: true` em vez de forçar PRD vazio
+- **SDD template reorganizado** — §Sistema (baseline técnico) + §Área-Backend/Frontend/DB/Infra gateáveis por scope
+- **docs/ = síntese cross-feature** (não projeção) — estável, referencia SDDs quando precisa detalhe
+- **Checklist de temas críticos FIXO** — 8 temas unificados (antes era split TRD/PRD). Analyzer consulta `docs/` antes de marcar ambiguidade
+- **Skills: 12 → 11** — `sf-new-project`, `sf-feature`, `sf-merge-delta` removidas; `sf-start`, `sf-merge-docs` adicionadas
+
+### Migração
+
+Projetos em `0.5.0-beta.X` precisam:
+
+1. Rodar `npx spec-first-copilot update` (atualiza .github/, CHANGELOG, templates)
+2. Se tiver `.context.md` com `tipo: feature|setup` ou `documento: PRD|TRD`: migrar pra schema v3:
+   ```yaml
+   first_run: true|false    # true se docs/ não existia quando bootstrap rodou
+   prd_empty: false         # true se TRD existia mas PRD não (raro)
+   areas_tocadas: [BACK, DB]  # derivar do SDD existente
+   ```
+3. Se tiver `TRD.md` em `workspace/Output/{scope}/`: manter como referência histórica ou deletar
+4. Rodar `/sf-merge-docs <scope>` manualmente pra features que estavam em `dev_done` (aplica §11 em `docs/`)
+
+### Novo fluxo (v3)
+
+```
+/sf-start <nome>
+  → /sf-load (se sfw.config.yml)
+  → /sf-discovery (opcional)
+  → /sf-extract → PRD.md (pode ser empty) + .extract-log.md com tech chunks
+  ↓ checkpoint
+/sf-design → SDD (§Sistema + §Área-X) + specs/{nome}/
+  → first_run: cria docs/ + projetos.yaml
+  → feature: §11 Delta Specs pro /sf-merge-docs
+/sf-plan → specs/{nome}/tasks.md + Progresso.md
+/sf-dev → código + Security Review + /sf-merge-docs automático
+```
+
+### Templates atualizados
+
+- `PRD.template.md` — campo `empty` no Meta; rodapé pra caso empty
+- `sdd.template.md` — 552 linhas, §Sistema + §Área-X gateáveis + §12 Ambiguidades com "Consultei docs/?"
+- `context.template.md` — schema v3 (`first_run`, `prd_empty`, `areas_tocadas`)
+- 5 templates em `estrutura/` — papel de síntese cross-feature, origem SDD §Sistema
+- `backlog-extraido.template.md` — scope agnóstico, sugere `/sf-start <nome>` pra promover items
+
+### Arquivos removidos
+
+- `.github/templates/feature/TRD.template.md`
+- `.github/skills/sf-new-project/`, `sf-feature/`, `sf-merge-delta/`
+
+---
+
+## 0.5.0-beta.7 (2026-04-12)
+
+### Novo: Comando `/sf-load <nome>`
+Puxa insumos do backend configurado (Confluence ou filesystem) para `workspace/Input/{nome}/`.
+- Busca o scope pelo nome no backend (match exato)
+- Desce recursivamente na árvore (Confluence `get_page_children` é apenas direto — `/sf-load` faz loop)
+- Baixa conteúdo + attachments
+- Log incremental em `.ai/sf-load-log.md` (NOVO/MODIFICADO/INALTERADO via sha256)
+- Idempotente — rodar N vezes sem mudanças no backend não altera nada
+- Referência: `.github/commands/sf-load.md`
+
+### Novo: Adapter layer (Confluence + Filesystem)
+Pipeline agora é backend-agnóstico via adapters plugáveis.
+- **ConfluenceAdapter** — fala com Confluence via MCP `sooperset/mcp-atlassian`
+- **FilesystemAdapter** — lê/escreve direto no disco (também serve como mock pra testes)
+- Configurado em `sfw.config.yml` (copiar de `sfw.config.yml.example`)
+- Interface: `.github/adapters/interface.md` (7 métodos)
+- Erros tipados: `.github/adapters/errors.md` (6 classes)
+- Naming engine: `.github/adapters/naming.md` (placeholders `{scope}`, `{type}`)
+- Registry: `.github/adapters/registry.md`
+- Setup guide: `.github/adapters/SETUP.md` (passo a passo de MCP + Confluence)
+
+### Novo: `sfw.config.yml`
+Manifesto do projeto que define de onde vêm e pra onde vão os artefatos.
+- `input.adapter` — de onde puxar insumos (`confluence` ou `filesystem`)
+- `output.targets[].mode` — ligar/desligar publish (`auto`, `manual`, `off`)
+- `naming.output_container` — template do nome da subpasta no Output (ex: `out_{scope}`)
+- `naming.output_artifact` — template do nome do artefato (ex: `{scope} - {type}`)
+- Copiar `sfw.config.yml.example` e preencher. Zero segredos neste arquivo.
+
+### Novo: `SETUP.md` — Guia de configuração
+Guia passo a passo em `.github/adapters/SETUP.md`:
+- Setup Confluence: uvx, .mcp.json, token Atlassian, space key, page IDs
+- Setup 100% local (filesystem, zero dependências)
+- Como ligar/desligar Confluence via `mode: auto|manual|off`
+- Troubleshooting: tabela com todos os gotchas conhecidos
+- **IMPORTANTE**: Confluence NÃO é CLI. Acesso via MCP tools prefixadas `mcp__atlassian__confluence_*`
+
+### Novo: CLI `update`
+```bash
+npx spec-first-copilot update           # adiciona novos, atualiza framework
+npx spec-first-copilot update --force   # sobrescreve tudo incluindo copilot-instructions.md
+```
+Atualiza projeto existente sem perder arquivos do usuário.
+
+### Breaking: `/sf-setup-projeto` → `/sf-new-project <nome>`
+- Antes: `/sf-setup-projeto` era hardcoded pra pasta `setup_projeto`
+- Agora: `/sf-new-project <nome>` recebe o nome como argumento (simétrico com `/sf-feature <nome>`)
+- `/sf-new-project` gera TRD (bootstrap técnico), `/sf-feature` gera PRD (feature)
+- **Não existe mais pasta mágica** — usuário nomeia livremente em `workspace/Input/`
+- O antigo `setup-projeto.md` foi removido. Usar `new-project.md`
+
+### Breaking: `{sequence}` removido
+- Antes: todo item tinha prefixo numérico `001 - ` pra unicidade no Confluence
+- Agora: usuário nomeia livremente, agent segue o nome do Input
+- Naming simplificado: só `{scope}` e `{type}` como placeholders
+- Premissa: 1 space Confluence = 1 projeto (multi-projeto no mesmo space requer nomes únicos no Input)
+
+### Breaking: Output agrupado por scope
+- Antes: artefatos flat no Output (ex: `001 - TRD setup_projeto`)
+- Agora: subpasta por scope (ex: `out_app_barbearia/app_barbearia - TRD`)
+- Container configurável via `naming.output_container` (default: `out_{scope}`)
+- Artifact configurável via `naming.output_artifact` (default: `{scope} - {type}`)
+
+---
+
+## 0.5.0-beta.2 (2026-04-11)
+
+### Refactor: `docs/specs/` → `specs/` (top-level)
+- Projeções do SDD (brief, contracts, scenarios, tasks) movidas pra raiz
+- Regra: humano lê `workspace/Output/`, agent lê `specs/`
+
+### Refactor: 3-zone separation
+- `.github/` = AI config (rules, templates, commands, agents)
+- `docs/` = system knowledge (5 docs de sistema)
+- `workspace/` = team content (Input/ + Output/)
+
+---
+
+## 0.4.0 (2026-04-10) — v1 stable
+
+### Funcionalidades base
+- 9 commands: setup-projeto, feature, discovery, extract, design, plan, dev, merge-delta, session-finish
+- 7 agents: backend-coder, frontend-coder, db-coder, infra-coder, doc-writer, reviewer, security-reviewer
+- Templates: PRD, TRD, SDD, tasks, Progresso, context, extract-log, backlog, projetos.yaml
+- Templates de estrutura: architecture, domain, conventions, apiContracts, decisions
+- Pipeline: extract → design → plan → dev com checkpoints de aprovação
+- Delta Specs (SDD §11) + merge-delta automático
+- Security Reviewer como gate pós-dev
+- Multi-repo via projetos.yaml
+- Entregáveis contínuos (fases de entrega)
+
+---
+
+## Como usar este arquivo
+
+Se o usuário perguntar:
+- **"O que tem de novo?"** → ler a versão mais recente acima
+- **"Como uso o /sf-load?"** → apontar pra `.github/commands/sf-load.md`
+- **"Como configuro Confluence?"** → apontar pra `.github/adapters/SETUP.md`
+- **"O que é adapter?"** → apontar pra `.github/adapters/interface.md`
+- **"O que mudou de setup-projeto?"** → seção "Breaking" do 0.5.0-beta.7