spec-first-copilot 0.6.0-beta.5 → 0.6.0-beta.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-first-copilot",
-  "version": "0.6.0-beta.5",
+  "version": "0.6.0-beta.6",
   "description": "Spec-first workflow kit for GitHub Copilot — AI-driven development with specs, not guesswork",
   "bin": {
     "spec-first-copilot": "bin/cli.js"

package/templates/.github/CHANGELOG.md

@@ -8,6 +8,60 @@
 
 ---
 
+## 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/

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

@@ -259,11 +259,17 @@ RE-EXTRAÇÃO:
 
 ## 14. Ambiguidades e Perguntas
 
-> ⚠️ **BLOQUEANTE** — o fluxo NÃO avança até o usuário responder TODAS.
-
-| # | Pergunta | Contexto | Fonte | Resposta do usuário |
-|---|----------|----------|-------|---------------------|
-| 1 | ⚠️ | | | (aguardando) |
+> ⚠️ **BLOQUEANTE** — o `/design` NÃO avança enquanto houver linha com `Resposta` vazia E `Resolvido em docs/` vazio.
+>
+> **Como responder** (ver `.claude/commands/extract.md` → "Como responder ambiguidades"):
+> preencher a coluna `Resposta` direto nesta tabela e rodar `/design` de novo.
+>
+> **Coluna `Resolvido em docs/`**: preenchida pelo Analyzer quando a resposta já
+> existe em `docs/` — formato `docs/{arquivo}.md §{seção}`. NÃO preencher manualmente.
+
+| ID | Pergunta | Contexto | Fonte | Resposta | Resolvido em docs/ |
+|----|----------|----------|-------|----------|--------------------|
+| AMB-001 | ⚠️ | | | (aguardando) | — |
 
 ---
 

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

@@ -3,12 +3,17 @@
 > Visão consolidada do andamento da feature.
 > Organizado por **fases de entrega** — cada fase é um entregável independente.
 > Atualizado automaticamente pelo /dev a cada task concluída.
+>
+> **Este arquivo rastreia FASES DE ENTREGA, não o pipeline do SFW.**
+> O estado do pipeline (extract_done, design_done, plan_done, dev_in_progress, dev_done, done)
+> vive em `.context.md`. Aqui rastreamos: "as fases de entrega do PRD §11 já foram implementadas?"
 
 ---
 
-## Status Geral: `não iniciado`
+## Status das Fases: `não iniciado`
 
-<!-- não iniciado → em desenvolvimento → em revisão → concluído → arquivado -->
+<!-- não iniciado → em desenvolvimento → em revisão → concluído → arquivado
+(vocabulário PRÓPRIO deste arquivo — não confundir com status da pipeline em .context.md) -->
 
 ---
 

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

@@ -1,7 +1,7 @@
 ---
 nome: "{{NOME}}"
-first_run: "{{true|false}}"
-prd_empty: "{{true|false}}"
+first_run: {{true|false}}
+prd_empty: {{true|false}}
 areas_tocadas: []
 input_path: "workspace/Input/{{NOME}}/"
 status: "not_started"
@@ -16,10 +16,10 @@ INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
 
 CAMPOS:
 - nome: identificador livre do scope (ex: app_barbearia, feat_login, infra_k8s)
-- first_run: "true" se docs/ não existia quando /sfw-start foi chamado (bootstrap)
-  "false" se é feature/incremento em projeto existente
-- prd_empty: "true" se o /extract marcou PRD como empty (scope puro-técnico)
-  "false" se PRD tem conteúdo de produto
+- first_run: bool (true/false, SEM aspas) — true se docs/ não existia quando /sfw-start foi chamado
+  IMUTÁVEL após criação
+- prd_empty: bool (true/false, SEM aspas) — true se /extract marcou PRD como empty (scope puro-técnico)
+  Pode mudar em re-extração (empty → non-empty se novo insumo trouxer produto)
 - areas_tocadas: lista de áreas que o scope toca (ex: [BACK, DB]). Preenchido pelo /design.
   Possíveis: BACK, FRONT, DB, INFRA. Usado pelos GATEs do SDD §Área-X.
 - input_path: caminho relativo da pasta de insumos

package/templates/.github/templates/feature/projetos.template.yaml

@@ -10,16 +10,22 @@
 # COMO GERAR:
 # 1. Ler SDD §3.2 Arquitetura → identificar quais serviços existem (api, worker, web, etc.)
 # 2. Para cada serviço, definir: nome do repo, path local, áreas de task, stack
-# 3. Se o repo já existe no GitHub, marcar existing: true
-# 4. Se é novo, marcar existing: false (será criado pelo /dev INFRA-001)
+# 3. A stack DEVE vir do SDD §3.1 (Stack) — não inventar, não copiar exemplo
+# 4. Se o repo já existe no GitHub, marcar existing: true
+# 5. Se é novo, marcar existing: false (será criado pelo /dev INFRA-001)
 #
 # REGRAS:
 # - Todo serviço identificado no SDD §3.2 DEVE ter uma entrada
 # - O campo `areas` define quais prefixos de task escrevem nesse repo
 # - Uma área NÃO pode pertencer a dois repos (mapeamento 1:1)
-# - DB pode ir junto com api (se usa EF migrations) ou separado (se repo de migrations)
-# - O campo `stack` deve ser consistente com docs/architecture.md (seção Stack Principal)
+# - DB pode ir junto com api (se usa ORM com migrations no mesmo repo) ou separado
+# - O campo `stack` DEVE ser consistente com SDD §3.1 + docs/architecture.md
 # - O `org` é a organização/user do GitHub
+#
+# EXEMPLOS DE STACK (apenas referência — usar a REAL do SDD):
+# - Backend: ".NET 8", "Node.js 20 + Express", "Python 3.12 + FastAPI", "Go 1.22"
+# - Frontend: "React 18 + Vite", "Next.js 15", "Vue 3 + Nuxt", "Angular 17"
+# - Mobile: "React Native", "Flutter", "Swift / Kotlin nativo"
 # =============================================================================
 
 # Organização/usuário no GitHub
@@ -28,42 +34,42 @@ org: "{{GITHUB_ORG}}"
 # Nome base do projeto (usado como prefixo dos repos)
 project: "{{PROJECT_NAME}}"
 
-# Repositórios
+# Repositórios — preencher conforme serviços do SDD §3.2
 repos:
-  # Exemplo: API backend
+  # API backend (exemplo — adaptar stack ao SDD real do projeto)
   api:
-    repo: "{{GITHUB_ORG}}/{{PROJECT_NAME}}-api"    # nome completo do repo
-    path: "projetos/api"                             # path local (relativo à raiz)
-    existing: false                                   # true = clonar, false = criar
-    areas: [BACK, DB]                             # áreas de task que escrevem aqui
-    stack: ".NET 8"                                   # stack principal
-    branch_prefix: "feature/"                         # prefixo de branches de feature
+    repo: "{{GITHUB_ORG}}/{{PROJECT_NAME}}-api"
+    path: "projetos/api"
+    existing: false                # true = clonar existente; false = criar novo
+    areas: [BACK, DB]              # áreas de task que escrevem aqui (1:1 por área)
+    stack: "{{STACK_BACKEND}}"     # do SDD §3.1 (ex: "Node.js 20 + Express")
+    branch_prefix: "feature/"
 
-  # Exemplo: Worker/background jobs
+  # Worker / jobs assíncronos (descomentar se SDD §3.2 define)
   # worker:
   #   repo: "{{GITHUB_ORG}}/{{PROJECT_NAME}}-worker"
   #   path: "projetos/worker"
   #   existing: false
-  #   areas: [BACK]                                  # worker tem tasks BACK separadas
-  #   stack: ".NET 8"
+  #   areas: [BACK]                # ou criar área WORKER dedicada se preferir
+  #   stack: "{{STACK_WORKER}}"
   #   branch_prefix: "feature/"
 
-  # Exemplo: Frontend web
+  # Frontend web (descomentar se SDD §3.2 define)
   # web:
   #   repo: "{{GITHUB_ORG}}/{{PROJECT_NAME}}-web"
   #   path: "projetos/web"
   #   existing: false
   #   areas: [FRONT]
-  #   stack: "React"
+  #   stack: "{{STACK_FRONTEND}}"
   #   branch_prefix: "feature/"
 
-  # Exemplo: App mobile
+  # App mobile (descomentar se SDD §3.2 define)
   # mobile:
   #   repo: "{{GITHUB_ORG}}/{{PROJECT_NAME}}-mobile"
   #   path: "projetos/mobile"
   #   existing: false
   #   areas: [MOBILE]
-  #   stack: "React Native"
+  #   stack: "{{STACK_MOBILE}}"
   #   branch_prefix: "feature/"
 
 # Notas:

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

@@ -4,6 +4,12 @@
 > Gerado pelo `/design` a partir do PRD (se existir) + chunks tech do `/extract`.
 > O Coder lê APENAS este documento + `specs/{{NOME}}/` e seu task específica.
 > Se não está aqui, não será implementado.
+>
+> **Sobre o tamanho do template**: o SDD tem 12 seções para cobrir o range completo
+> (app simples → sistema distribuído com 5 serviços). Escopo pequeno preenche 3-4
+> seções e marca as outras como "N/A" ou "não se aplica" — isso é **esperado**.
+> Áreas não tocadas (§4-§7) usam `GATE: NÃO` e ficam vazias. Não inflar conteúdo
+> pra preencher seção vazia — "N/A" é resposta válida.
 
 ---
 
@@ -12,8 +18,8 @@
 | Campo | Valor |
 |-------|-------|
 | Scope | `{{NOME}}` |
-| PRD | `workspace/Output/{{NOME}}/PRD.md` — `empty: {{true|false}}` |
-| First-run | `{{true|false}}` — true quando `docs/` não existia antes desta execução |
+| PRD | `workspace/Output/{{NOME}}/PRD.md` — `empty: {{true\|false}}` (sem aspas, bool) |
+| First-run | `{{true\|false}}` — true quando `docs/` não existia antes desta execução |
 | Áreas tocadas | `[BACK?, FRONT?, DB?, INFRA?]` |
 | Status | `rascunho` → `em revisão` → `aprovado` → `em dev` → `concluído` |
 | Autor | `/design` |
@@ -507,12 +513,13 @@ Then {{resultado esperado}}
 
 ## 12. Ambiguidades Pendentes
 
-> ⚠️ **BLOQUEANTE** — `/design` não conclui com ambiguidades abertas.
-> Analyzer consultou `docs/` antes de listar — itens aqui são genuínos.
+> ⚠️ **BLOQUEANTE** — `/plan` não conclui com ambiguidades abertas.
+> Architect consultou `docs/` antes de listar — itens aqui são genuínos.
+> IDs começam em `AMB-NNN`, continuando a sequência iniciada no PRD §14 (se houver).
 
-| # | Pergunta | Contexto | Consultei `docs/`? | Resposta |
-|---|----------|----------|--------------------|-----------|
-| 1 | | | sim / não / docs ausente | (aguardando) |
+| ID | Pergunta | Contexto | Consultei `docs/`? | Resposta |
+|----|----------|----------|--------------------|-----------|
+| AMB-001 | | | sim / não / docs ausente | (aguardando) |
 
 ---