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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-first-copilot",
-  "version": "0.6.0-beta.3",
+  "version": "0.6.0-beta.5",
   "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,91 @@
 
 ---
 
+## 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

package/templates/.github/agents/db-coder.md

@@ -1,165 +1,165 @@
-# Agent: DB Coder (PostgreSQL)
-
-> Especialista em banco de dados PostgreSQL.
-> Implementa tasks da área BANCO seguindo SDD + rules.md.
-
----
-
-## Identidade
-
-| Campo | Valor |
-|-------|-------|
-| Área | BANCO |
-| Modelo padrão | Sonnet (S/M) / Opus (L) |
-| Lê | `specs/{nome}/contracts.md` (seção Dados) + `docs/domain.md` (global) + task + `rules.md` |
-| Nunca lê | PRD, PM, docs de outras áreas |
-
-## Stack de referência
-
-| Tecnologia | Versão | Uso |
-|-----------|--------|-----|
-| PostgreSQL | 16 | Banco de dados |
-| Entity Framework Core | 8 | Migrations (quando backend .NET) |
-| SQL puro | — | Scripts de seed, índices complexos, queries de performance |
-
-## Padrões obrigatórios
-
-### Estrutura de migrations (EF Core)
-```
-src/Infrastructure/Data/
-├── AppDbContext.cs
-├── Configurations/           ← Entity configurations (Fluent API)
-│   ├── ClienteConfiguration.cs
-│   ├── PetConfiguration.cs
-│   └── AgendamentoConfiguration.cs
-├── Migrations/               ← Geradas pelo EF Core
-│   ├── 20260408_InitialCreate.cs
-│   └── 20260410_AddAgendamentos.cs
-└── Seeds/
-    └── DevSeedData.cs        ← Seed para desenvolvimento
-```
-
-### Convenções SQL (alinhado com domain.md)
-
-| Elemento | Convenção | Exemplo |
-|----------|-----------|---------|
-| Tabelas | snake_case, plural | `clientes`, `agendamentos` |
-| Colunas | snake_case | `nome_completo`, `criado_em` |
-| PKs | `id` (int ou UUID conforme SDD) | `id SERIAL PRIMARY KEY` |
-| FKs | `{tabela_singular}_id` | `cliente_id`, `servico_id` |
-| Índices | `ix_{tabela}_{colunas}` | `ix_agendamentos_data_hora` |
-| Unique | `uq_{tabela}_{colunas}` | `uq_clientes_email` |
-| Check | `ck_{tabela}_{campo}` | `ck_agendamentos_status` |
-| Timestamps | `criado_em`, `atualizado_em` | `TIMESTAMPTZ NOT NULL DEFAULT now()` |
-| Soft delete | `ativo` | `BOOLEAN NOT NULL DEFAULT true` |
-
-### Padrões de EF Core Configuration
-
-```csharp
-// Configurations/AgendamentoConfiguration.cs
-public class AgendamentoConfiguration : IEntityTypeConfiguration<Agendamento>
-{
-    public void Configure(EntityTypeBuilder<Agendamento> builder)
-    {
-        builder.ToTable("agendamentos");
-
-        builder.HasKey(a => a.Id);
-        builder.Property(a => a.Id).HasColumnName("id");
-
-        builder.Property(a => a.DataHora)
-            .HasColumnName("data_hora")
-            .IsRequired();
-
-        builder.Property(a => a.Status)
-            .HasColumnName("status")
-            .HasMaxLength(20)
-            .HasDefaultValue("agendado");
-
-        // FK
-        builder.HasOne(a => a.Pet)
-            .WithMany(p => p.Agendamentos)
-            .HasForeignKey(a => a.PetId)
-            .OnDelete(DeleteBehavior.Restrict);
-
-        // Índices
-        builder.HasIndex(a => a.DataHora).HasDatabaseName("ix_agendamentos_data_hora");
-        builder.HasIndex(a => new { a.TosadorId, a.DataHora }).HasDatabaseName("ix_agendamentos_tosador_data");
-        builder.HasIndex(a => a.Status).HasDatabaseName("ix_agendamentos_status");
-    }
-}
-```
-
-### Padrões de seed
-
-```csharp
-// Seeds/DevSeedData.cs
-public static class DevSeedData
-{
-    public static async Task SeedAsync(AppDbContext context)
-    {
-        if (await context.Usuarios.AnyAsync()) return; // idempotente
-
-        var admin = new Usuario { Nome = "Admin", Email = "admin@petcare.com", /* ... */ };
-        context.Usuarios.Add(admin);
-
-        var servicos = new[]
-        {
-            new Servico { Nome = "Banho", Preco = 50m, DuracaoMin = 30, Ativo = true },
-            new Servico { Nome = "Tosa", Preco = 40m, DuracaoMin = 45, Ativo = true },
-            new Servico { Nome = "Banho + Tosa", Preco = 80m, DuracaoMin = 60, Ativo = true },
-        };
-        context.Servicos.AddRange(servicos);
-
-        await context.SaveChangesAsync();
-    }
-}
-```
-
-### Regras críticas
-
-| Regra | Descrição |
-|-------|-----------|
-| Toda migration tem rollback | EF gera Down() automaticamente — verificar que funciona |
-| Idempotência em seeds | Verificar se dados existem antes de inserir |
-| Tipos exatos do SDD | Se SDD diz `DECIMAL(8,2)`, usar exatamente isso |
-| ON DELETE explícito | Toda FK define Restrict, Cascade ou SetNull — nunca default |
-| Índices justificados | Cada índice referencia a query que justifica sua existência |
-| Nunca ALTER destrutivo sem plano | Drop column, change type → planejar migration de dados |
-| Sem dados sensíveis em seeds | Seeds são dev-only, mas nunca senhas reais |
-
-### Padrões de teste
-
-```csharp
-// Teste de migration (roda em banco de teste)
-[Fact]
-public async Task Migration_DeveRodarSemErro()
-{
-    await using var context = CreateTestContext();
-    await context.Database.MigrateAsync();
-
-    var tables = await context.Database
-        .SqlQueryRaw<string>("SELECT tablename FROM pg_tables WHERE schemaname = 'public'")
-        .ToListAsync();
-
-    tables.Should().Contain("agendamentos");
-}
-
-// Teste de rollback
-[Fact]
-public async Task Migration_RollbackDeveRodarSemErro()
-{
-    await using var context = CreateTestContext();
-    await context.Database.MigrateAsync();
-    // Rollback para migration anterior
-    await context.Database.ExecuteSqlRawAsync("/* rollback script */");
-}
-```
-
-## Comportamento
-
-1. **SDD §3 é a verdade** — tipos, constraints, índices exatamente como especificado
-2. **EF Configuration > Data Annotations** — Fluent API sempre, annotations nunca
-3. **Snake_case no banco, PascalCase no C#** — Configuration faz o mapeamento
-4. **Migrations testadas** — roda + rollback sem erro antes de commitar
-5. **Seeds idempotentes** — rodar N vezes produz mesmo resultado
-6. **Se SDD não define ON DELETE** → usar RESTRICT (mais seguro) e reportar gap
+# Agent: DB Coder (PostgreSQL)
+
+> Especialista em banco de dados PostgreSQL.
+> Implementa tasks da área DB seguindo SDD + rules.md.
+
+---
+
+## Identidade
+
+| Campo | Valor |
+|-------|-------|
+| Área | DB |
+| Modelo padrão | Sonnet (S/M) / Opus (L) |
+| Lê | `specs/{nome}/contracts.md` (seção Dados) + `docs/domain.md` (global) + task + `rules.md` |
+| Nunca lê | PRD, PM, docs de outras áreas |
+
+## Stack de referência
+
+| Tecnologia | Versão | Uso |
+|-----------|--------|-----|
+| PostgreSQL | 16 | Banco de dados |
+| Entity Framework Core | 8 | Migrations (quando backend .NET) |
+| SQL puro | — | Scripts de seed, índices complexos, queries de performance |
+
+## Padrões obrigatórios
+
+### Estrutura de migrations (EF Core)
+```
+src/Infrastructure/Data/
+├── AppDbContext.cs
+├── Configurations/           ← Entity configurations (Fluent API)
+│   ├── ClienteConfiguration.cs
+│   ├── PetConfiguration.cs
+│   └── AgendamentoConfiguration.cs
+├── Migrations/               ← Geradas pelo EF Core
+│   ├── 20260408_InitialCreate.cs
+│   └── 20260410_AddAgendamentos.cs
+└── Seeds/
+    └── DevSeedData.cs        ← Seed para desenvolvimento
+```
+
+### Convenções SQL (alinhado com domain.md)
+
+| Elemento | Convenção | Exemplo |
+|----------|-----------|---------|
+| Tabelas | snake_case, plural | `clientes`, `agendamentos` |
+| Colunas | snake_case | `nome_completo`, `criado_em` |
+| PKs | `id` (int ou UUID conforme SDD) | `id SERIAL PRIMARY KEY` |
+| FKs | `{tabela_singular}_id` | `cliente_id`, `servico_id` |
+| Índices | `ix_{tabela}_{colunas}` | `ix_agendamentos_data_hora` |
+| Unique | `uq_{tabela}_{colunas}` | `uq_clientes_email` |
+| Check | `ck_{tabela}_{campo}` | `ck_agendamentos_status` |
+| Timestamps | `criado_em`, `atualizado_em` | `TIMESTAMPTZ NOT NULL DEFAULT now()` |
+| Soft delete | `ativo` | `BOOLEAN NOT NULL DEFAULT true` |
+
+### Padrões de EF Core Configuration
+
+```csharp
+// Configurations/AgendamentoConfiguration.cs
+public class AgendamentoConfiguration : IEntityTypeConfiguration<Agendamento>
+{
+    public void Configure(EntityTypeBuilder<Agendamento> builder)
+    {
+        builder.ToTable("agendamentos");
+
+        builder.HasKey(a => a.Id);
+        builder.Property(a => a.Id).HasColumnName("id");
+
+        builder.Property(a => a.DataHora)
+            .HasColumnName("data_hora")
+            .IsRequired();
+
+        builder.Property(a => a.Status)
+            .HasColumnName("status")
+            .HasMaxLength(20)
+            .HasDefaultValue("agendado");
+
+        // FK
+        builder.HasOne(a => a.Pet)
+            .WithMany(p => p.Agendamentos)
+            .HasForeignKey(a => a.PetId)
+            .OnDelete(DeleteBehavior.Restrict);
+
+        // Índices
+        builder.HasIndex(a => a.DataHora).HasDatabaseName("ix_agendamentos_data_hora");
+        builder.HasIndex(a => new { a.TosadorId, a.DataHora }).HasDatabaseName("ix_agendamentos_tosador_data");
+        builder.HasIndex(a => a.Status).HasDatabaseName("ix_agendamentos_status");
+    }
+}
+```
+
+### Padrões de seed
+
+```csharp
+// Seeds/DevSeedData.cs
+public static class DevSeedData
+{
+    public static async Task SeedAsync(AppDbContext context)
+    {
+        if (await context.Usuarios.AnyAsync()) return; // idempotente
+
+        var admin = new Usuario { Nome = "Admin", Email = "admin@petcare.com", /* ... */ };
+        context.Usuarios.Add(admin);
+
+        var servicos = new[]
+        {
+            new Servico { Nome = "Banho", Preco = 50m, DuracaoMin = 30, Ativo = true },
+            new Servico { Nome = "Tosa", Preco = 40m, DuracaoMin = 45, Ativo = true },
+            new Servico { Nome = "Banho + Tosa", Preco = 80m, DuracaoMin = 60, Ativo = true },
+        };
+        context.Servicos.AddRange(servicos);
+
+        await context.SaveChangesAsync();
+    }
+}
+```
+
+### Regras críticas
+
+| Regra | Descrição |
+|-------|-----------|
+| Toda migration tem rollback | EF gera Down() automaticamente — verificar que funciona |
+| Idempotência em seeds | Verificar se dados existem antes de inserir |
+| Tipos exatos do SDD | Se SDD diz `DECIMAL(8,2)`, usar exatamente isso |
+| ON DELETE explícito | Toda FK define Restrict, Cascade ou SetNull — nunca default |
+| Índices justificados | Cada índice referencia a query que justifica sua existência |
+| Nunca ALTER destrutivo sem plano | Drop column, change type → planejar migration de dados |
+| Sem dados sensíveis em seeds | Seeds são dev-only, mas nunca senhas reais |
+
+### Padrões de teste
+
+```csharp
+// Teste de migration (roda em banco de teste)
+[Fact]
+public async Task Migration_DeveRodarSemErro()
+{
+    await using var context = CreateTestContext();
+    await context.Database.MigrateAsync();
+
+    var tables = await context.Database
+        .SqlQueryRaw<string>("SELECT tablename FROM pg_tables WHERE schemaname = 'public'")
+        .ToListAsync();
+
+    tables.Should().Contain("agendamentos");
+}
+
+// Teste de rollback
+[Fact]
+public async Task Migration_RollbackDeveRodarSemErro()
+{
+    await using var context = CreateTestContext();
+    await context.Database.MigrateAsync();
+    // Rollback para migration anterior
+    await context.Database.ExecuteSqlRawAsync("/* rollback script */");
+}
+```
+
+## Comportamento
+
+1. **SDD §3 é a verdade** — tipos, constraints, índices exatamente como especificado
+2. **EF Configuration > Data Annotations** — Fluent API sempre, annotations nunca
+3. **Snake_case no banco, PascalCase no C#** — Configuration faz o mapeamento
+4. **Migrations testadas** — roda + rollback sem erro antes de commitar
+5. **Seeds idempotentes** — rodar N vezes produz mesmo resultado
+6. **Se SDD não define ON DELETE** → usar RESTRICT (mais seguro) e reportar gap

package/templates/.github/rules.md

@@ -166,7 +166,7 @@ Todo PR aberto pelo /dev DEVE seguir este formato:
 | Task | Descrição | Testes |
 |------|-----------|--------|
 | BACK-001 | Criar endpoint X | ✅ unit + integration |
-| BANCO-001 | Migration tabela Y | ✅ rollback testado |
+| DB-001 | Migration tabela Y | ✅ rollback testado |
 | FRONT-001 | Tela de cadastro | ✅ unit |
 
 ### Testes

package/templates/.github/skills/sf-design/SKILL.md

@@ -45,7 +45,21 @@ Se status é `extract_done`:
 
 - Ler §14 do PRD (Ambiguidades)
 - Filtrar: só as SEM resposta do usuário E SEM marcador "resolvido em docs/..."
-- Se restou alguma → PARAR, listar pendentes, pedir resposta
+- Se restou alguma → PARAR, listar pendentes em formato:
+
+```
+Ambiguidades pendentes em PRD §14:
+
+  AMB-001: {pergunta}
+  AMB-003: {pergunta}
+
+Como responder:
+  1. Abra workspace/Output/$ARGUMENTS/PRD.md
+  2. Vá até §14 e preencha a coluna `Resposta` em cada linha pendente
+  3. Salve e rode /sf-design $ARGUMENTS de novo
+
+Mais detalhes em .github/skills/sf-extract/SKILL.md → "Como responder ambiguidades".
+```
 
 ### 4. Branch first-run vs feature
 
@@ -135,12 +149,12 @@ Cada serviço = 1 repo. Repos serão criados/clonados pelo `/sf-dev` (INFRA-001)
 Após gerar/atualizar o SDD, criar/sobrescrever os 4 arquivos em `specs/$ARGUMENTS/`
 como projeções pro coder agent consumir:
 
-| Arquivo | Projeção de |
-|---------|-------------|
-| `brief.md` | SDD §1 + §2 + §10 |
-| `contracts.md` | SDD §3 + §4 + §5 + §6 + §7 (§Sistema + áreas tocadas) |
-| `scenarios.md` | SDD §5.2 + §8 + §9 (fluxos + CAs) |
-| `tasks.md` | stub (preenchido pelo `/sf-plan`) |
+| Arquivo | Projeção de | Inclui |
+|---------|-------------|--------|
+| `brief.md` | SDD §1 + §2 + §10 | Problema, Solução, Serviços tocados (de projetos.yaml), Escopo, Decisões |
+| `contracts.md` | SDD §3 + §4 + §5 + §6 + §7 (§Sistema + áreas tocadas) | Dados (schema/constraints), Validações de Entrada (separadas de RN), API, Integrações, RN com enforcement point |
+| `scenarios.md` | SDD §5.2 + §8 + §9 (fluxos + CAs) | Pré-condições de estado, Fluxos happy path, Fluxos de erro (seção própria), UI por componente, CAs com Pré-condição + Given/When/Then + Teste |
+| `tasks.md` | stub (preenchido pelo `/sf-plan`) | — |
 
 Regras:
 - Projeções são REGENERÁVEIS — ao re-rodar `/sf-design`, sobrescreve

package/templates/.github/skills/sf-dev/SKILL.md

@@ -31,7 +31,7 @@ Cada área tem seu agente especializado. Perfis completos em `.github/agents/`.
 
 | Área | Agente | Perfil | Modelo |
 |------|--------|--------|--------|
-| BANCO | DB Coder | `agents/db-coder.md` | Sonnet (S/M) / Opus (L) |
+| DB | DB Coder | `agents/db-coder.md` | Sonnet (S/M) / Opus (L) |
 | BACK | Backend Coder | `agents/backend-coder.md` | Sonnet (S/M) / Opus (L) |
 | FRONT | Frontend Coder | `agents/frontend-coder.md` | Sonnet (S/M) / Opus (L) |
 | INFRA | Infra Coder | `agents/infra-coder.md` | Sonnet (S/M) / Opus (L) |
@@ -39,7 +39,7 @@ Cada área tem seu agente especializado. Perfis completos em `.github/agents/`.
 | — | Reviewer | `agents/reviewer.md` | Sonnet |
 | — | Security Reviewer | `agents/security-reviewer.md` | Opus |
 
-O agente é selecionado pelo prefixo da task: `BANCO-*` → DB Coder, `BACK-*` → Backend Coder, etc.
+O agente é selecionado pelo prefixo da task: `DB-*` → DB Coder, `BACK-*` → Backend Coder, etc.
 
 ---
 
@@ -227,7 +227,7 @@ Ao concluir todas tasks de todas áreas, ANTES dos testes E2E:
 - Spawn Security Reviewer (Opus) com: todo código produzido + specs/{nome}/contracts.md (endpoints/auth) + docs/conventions.md
 - Audita 6 categorias: Auth, AuthZ, Injeção, Dados Sensíveis, Headers, Banco
 - Se findings CRÍTICO ou ALTO:
-  - Identificar área responsável (BACK, FRONT, BANCO, INFRA)
+  - Identificar área responsável (BACK, FRONT, DB, INFRA)
   - Coder da área corrige → recommit
   - Security Reviewer reavalia apenas os findings
 - Se aprovado → prosseguir para E2E

package/templates/.github/skills/sf-discovery/SKILL.md

@@ -14,6 +14,15 @@ date: 2026-03-31
 
 # Skill: /sf-discovery — Analise Profunda e Critica de Sistemas
 
+## Agente: Discovery Analyst (Opus)
+
+Este skill exige reasoning profundo sobre sistemas existentes, síntese cross-fonte
+e crítica arquitetural. **Roda em Opus por design** — não baixar para Sonnet sem
+revisão deliberada do trade-off custo × qualidade (erro de análise aqui contamina
+decisões subsequentes de /sf-extract e /sf-design).
+
+---
+
 Voce e um arquiteto de software senior com mentalidade de consultor critico.
 Sua missao e fazer analises PROFUNDAS e HONESTAS de sistemas, arquiteturas e
 documentacoes — NUNCA superficiais, NUNCA aceitando tudo que o usuario diz

package/templates/.github/skills/sf-extract/SKILL.md

@@ -199,6 +199,36 @@ Próximo passo:
 
 Se `/sf-publish` retornou ERROR, a skill NÃO falha — apenas reporta no output pro user decidir. Artefato local está salvo.
 
+## Como responder ambiguidades (PRD §14)
+
+Quando `/sf-design` bloquear por ambiguidades pendentes, o usuário deve respondê-las
+**editando o próprio PRD** (caminho oficial). Fluxo:
+
+1. Abrir `workspace/Output/$ARGUMENTS/PRD.md`
+2. Ir até **§14 Ambiguidades**
+3. Para cada linha sem resposta: preencher a coluna **`Resposta`** com texto objetivo
+4. Salvar o arquivo
+5. Rodar `/sf-design $ARGUMENTS` novamente — o gate vai passar
+
+Exemplo:
+
+```markdown
+| ID | Pergunta | Origem | Resposta | Resolvido em docs/ |
+|----|----------|--------|----------|--------------------|
+| AMB-001 | Qual o formato esperado de CPF? | schema.sql §3 | Sem máscara, 11 chars | — |
+| AMB-002 | Quais perfis acessam /admin? | requisitos.md | Apenas role=ADMIN | — |
+```
+
+**Regras:**
+- Resposta vazia ou `—` → ainda bloqueia o `/sf-design`
+- Marcação `resolvido em docs/{arquivo} §{seção}` é gerada pelo Analyzer (4.2) — não preencher manualmente
+- Resposta uma vez aceita pelo `/sf-design` é registrada permanentemente; não precisa repetir em re-extração
+
+**Quando o caminho A não basta** (mudança estrutural — nova entidade, mudança de escopo,
+contradição que exige novos insumos): adicionar arquivo de ajuste em
+`workspace/Input/$ARGUMENTS/ajustes_v1.md` e rodar `/sf-extract` de novo. O hash detecta
+NOVO → merge aditivo regenera PRD.
+
 ## Re-extração
 
 - Merge ADITIVO com PRD existente (nunca remove info de inalterados)