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

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

@@ -71,29 +71,14 @@ function loadScope(pageId, targetDir):
   collectAllPages(pageId, allPages)
 
   para cada page em allPages:
-    // IMPORTANTE: SEMPRE pedir markdown, NUNCA storage format (HTML)
+    // PEDIR MARKDOWN PRIMEIRO (MCP converte do storage format)
     result = mcp__atlassian__confluence_get_page(page_id=page.id, convert_to_markdown=true)
-    content = result.content (ou result.body — depende da resposta do MCP)
-
-    // LIMPEZA OBRIGATÓRIA — Confluence pode vazar HTML mesmo com convert_to_markdown
-    // Se o conteúdo contém tags HTML (<p>, <div>, <span>, <table>, etc.):
-    //   1. Remover tags de metadata: <p local-id="...">, <ri:...>, <ac:...>
-    //   2. Converter tags semânticas pra markdown:
-    //      <h1> → #, <h2> → ##, <h3> → ###
-    //      <strong>/<b> → **texto**
-    //      <em>/<i> → *texto*
-    //      <a href="url"> → [texto](url)
-    //      <ul>/<li> → - item
-    //      <ol>/<li> → 1. item
-    //      <code> → `código`
-    //      <pre> → ```bloco```
-    //      <table>/<tr>/<td> → tabela markdown
-    //   3. Remover tags restantes sem equivalente markdown (strip tags, manter texto)
-    //   4. Limpar linhas vazias excessivas
-    // O arquivo salvo DEVE ser markdown limpo, sem nenhuma tag HTML.
+    content = result.content (ou result.body — depende do MCP)
+
+    content = preservarFormatacao(content)
 
     filename = sanitize(page.title) + ".md"
-    salvar content LIMPO em {targetDir}/{filename}
+    salvar content em {targetDir}/{filename}
     registrar no load-log
 
   // Attachments de CADA page
@@ -111,6 +96,86 @@ function collectAllPages(pageId, result):
     collectAllPages(child.id, result)    // recursão total
 ```
 
+### 3.1 Função `preservarFormatacao(content)` — regras obrigatórias
+
+O MCP pode retornar markdown "parcial" (com tags HTML misturadas) ou storage format
+(XHTML do Confluence). A função DEVE preservar toda a estrutura semântica:
+
+**Passo 1 — Macros do Confluence (prioridade alta — preservar semântica)**
+
+| Macro Confluence | Converter pra markdown |
+|------------------|------------------------|
+| `<ac:structured-macro ac:name="code">...<ac:plain-text-body><![CDATA[...]]></>` | ```` ```{lang}\n{código}\n``` ```` (pegar linguagem de `<ac:parameter ac:name="language">`) |
+| `<ac:structured-macro ac:name="info\|note\|warning\|tip">` | `> ℹ️` (info), `> 📝` (note), `> ⚠️` (warning), `> 💡` (tip) + conteúdo como blockquote |
+| `<ac:structured-macro ac:name="expand">` | `<details><summary>{title}</summary>\n{body}\n</details>` |
+| `<ac:structured-macro ac:name="panel">` | blockquote simples `> ` |
+| `<ac:link><ri:page ri:content-title="X" /></>` | `[X](../X.md)` (link interno) |
+| `<ac:image><ri:attachment ri:filename="X" /></>` | `![X](X)` (imagem inline — attachment já é baixado) |
+
+**Passo 2 — Tabelas (crítico — fidelidade alta)**
+
+Preservar estrutura completa:
+```
+<table>
+  <tbody>
+    <tr><th>Col A</th><th>Col B</th></tr>
+    <tr><td>val1</td><td>val2</td></tr>
+  </tbody>
+</table>
+```
+vira:
+```
+| Col A | Col B |
+|-------|-------|
+| val1 | val2 |
+```
+
+**NUNCA** achatar tabela em lista ou parágrafo — perde dados estruturados.
+Se célula tem formatação inline (bold, link), preservar dentro da célula.
+
+**Passo 3 — Tags semânticas padrão**
+
+| HTML | Markdown |
+|------|----------|
+| `<h1>` → `<h6>` | `#` → `######` |
+| `<strong>`, `<b>` | `**texto**` |
+| `<em>`, `<i>` | `*texto*` |
+| `<u>` | `<u>texto</u>` (markdown não tem underline nativo — manter tag) |
+| `<s>`, `<del>` | `~~texto~~` |
+| `<a href="URL">` | `[texto](URL)` |
+| `<ul><li>` | `- item` |
+| `<ol><li>` | `1. item` |
+| `<code>` inline | `` `código` `` |
+| `<pre>` sem macro code | ```` ``` ```` bloco |
+| `<blockquote>` | `> texto` |
+| `<hr>` | `---` |
+| `<br>` | quebra de linha |
+| `<p>` (simples) | parágrafo (linha em branco antes/depois) |
+
+**Passo 4 — Remover metadata/lixo do Confluence**
+
+Strip silencioso (sem manter nada):
+- `<p local-id="uuid">` → remove tag, mantém conteúdo
+- Atributos `ac:schema-version`, `ac:macro-id`, `ac:local-id`, `ri:version-at-save`
+- `<ri:user>`, `<ri:space>` sem contexto útil
+- Comentários HTML `<!-- ... -->`
+- Entidades HTML: `&nbsp;` → espaço, `&amp;` → `&`, `&lt;` → `<`, `&gt;` → `>`
+
+**Passo 5 — Limpeza final**
+
+- Colapsar 3+ linhas em branco consecutivas em 2
+- Trim whitespace no fim de cada linha
+- Garantir que arquivo termine com uma única newline
+
+**Passo 6 — Validação**
+
+Após conversão, o markdown resultante NÃO deve conter:
+- Nenhuma tag `<ac:...>`, `<ri:...>`, `<p local-id=...>`
+- Nenhum `&nbsp;` ou entidade HTML não convertida
+- Tabelas sem pipes markdown
+
+Se qualquer um aparecer, é bug da função — reportar ao user no load-log com flag `FORMAT_WARN`.
+
 **Para cada scope de Output — materializar em `workspace/Output/{nome}/`:**
 
 Mesmo processo, mas:
@@ -178,8 +243,7 @@ Scope "{nome}" carregado:
           ou "nenhum artefato publicado ainda"
 
 Próximo passo:
-  /sf-start {nome}    ← bootstrap técnico ou feature (gera PRD)
-
+  /sf-start {nome}    ← entrada única (bootstrap ou feature, detecta via docs/)
 
 Log: .ai/sf-load-log.md
 ```

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

@@ -171,27 +171,32 @@ mcp__atlassian__confluence_get_page(page_id={resposta})
 - Se 404 e user colou ID → pedir de novo
 - Se OK → seguir
 
-### Passo 4 — Mapear árvore do projeto
+### Passo 4 — Listar filhos diretos do root (NÃO recursivo)
+
+Nesta etapa queremos só o **primeiro nível** da árvore. Pra identificar Input/Output,
+basta saber quais pages estão logo abaixo do root. A árvore profunda vem depois via
+`/sf-load` quando o agent realmente precisa do conteúdo.
 
-Chamar recursivamente:
 ```
 mcp__atlassian__confluence_get_page_children(page_id={root_page_id})
-  → pra cada filho, chamar get_page_children até bater em folha
 ```
 
+**APENAS 1 chamada**. Sem loop recursivo.
+
 Mostrar ao usuário:
 ```
 Projeto: "Barbearia Digital" (root_page_id: 65708)
 
-Estrutura encontrada:
-  ├── Requisitos (360668)
-  │   ├── App mobile (294950)
-  │   └── Painel admin (131084)
-  ├── Documentação técnica (294931)
-  ├── Referências (557057)
-  └── Decisões (425998)
+Filhos diretos do root:
+  1. Requisitos (360668)
+  2. Documentação técnica (294931)
+  3. Referências (557057)
+  4. Decisões (425998)
 ```
 
+Se algum desses filhos tiver sub-pages (ex: Requisitos contém scopes), isso será descoberto
+pelo `/sf-load` quando rodar. Aqui só precisamos saber quem é Input e quem é Output no nível 1.
+
 ### Passo 5 — Identificar Input e Output
 
 **Se já existe config com Input/Output**: mostrar o que está salvo + opção de mudar:
@@ -217,23 +222,30 @@ Qual dessas pages contém os INSUMOS (Input, onde PM/PO publica)?
   >
 ```
 
-Após escolher Input, perguntar Output com as pages restantes + opção "Criar nova page 'Output'".
+Opção 1-4: usar o page_id correspondente.
+Opção 5: criar page nova — `mcp__atlassian__confluence_create_page(parent_id={root}, title="Input", content="")`.
+
+Após escolher Input, perguntar Output com as pages **restantes** (remover a escolhida de Input da lista) + opção "Criar nova page 'Output'".
 
 Se escolher "Criar nova" → `mcp__atlassian__confluence_create_page` como filha da raiz.
 
 ### Passo 6 — Sugerir context_pages (opcional)
 
-Pages da árvore que não viraram Input nem Output:
+Das pages do nível 1 (filhos diretos do root) que **não** foram escolhidas como Input ou Output,
+sugerir como contexto adicional pro /sf-extract e /sf-design:
+
 ```
-Encontrei outras pages que podem ser úteis durante o desenvolvimento:
+Das pages restantes no primeiro nível:
 
   - "Referências" (557057) → posso consultar durante /sf-extract e /sf-design
   - "Decisões" (425998) → posso consultar para ADRs no /sf-design
 
-Quer que eu mapeie essas páginas como contexto adicional? (s/n)
+Quer que eu mapeie alguma dessas como contexto adicional? (listar números, ou "não")
 ```
 
-Se sim, incluir em `context_pages[]` no `sfw.config.yml`.
+Se sim, incluir as escolhidas em `context_pages[]` no `sfw.config.yml`.
+
+Obs: `/sf-load` descobre a árvore profunda sob Input/Output quando rodar. Aqui só tratamos nível 1.
 
 ### Passo 7 — Escrever `sfw.config.yml`
 

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

@@ -33,7 +33,7 @@ Ler PRD §11 (Fases de Entrega) — cada fase vira um agrupamento de tasks:
 
 | Seção SDD | Área |
 |-----------|------|
-| §3 Modelo de dados | BANCO |
+| §3 Modelo de dados | DB |
 | §5 Endpoints API | BACK |
 | §6 Componentes/Telas | FRONT |
 | §8 Integrações | INFRA |
@@ -59,14 +59,14 @@ Gerar UM arquivo só em `specs/{nome}/tasks.md` com tabela única de todas as ta
 ```markdown
 | ID | Área | Fase | Tam | Título | Repo | Arquivos | Depende de | Ref spec | Ref CA |
 |----|------|------|-----|--------|------|----------|-----------|----------|--------|
-| BANCO-001 | BANCO | 1 | S | Migration clientes | api | src/Migrations/... | — | SDD §3.1 | — |
-| BACK-001 | BACK | 1 | M | Endpoint POST /clientes | api | src/Api/... | BANCO-001 | SDD §5.1 | CA-001 |
+| DB-001 | DB | 1 | S | Migration clientes | api | src/Migrations/... | — | SDD §3.1 | — |
+| BACK-001 | BACK | 1 | M | Endpoint POST /clientes | api | src/Api/... | DB-001 | SDD §5.1 | CA-001 |
 ```
 
 Regras:
 - Cada task é atômica — coder lê `specs/{nome}/` + task, nada mais
 - **Repo obrigatório** — consultar `projetos.yaml`. Caminhos relativos ao repo
-- Área é COLUNA, não arquivo (BANCO, BACK, FRONT, INFRA, DOC, MOBILE...)
+- Área é COLUNA, não arquivo (DB, BACK, FRONT, INFRA, DOC, MOBILE...)
 - Tamanhos: S (<30min), M (30min-2h), L (2h+). L → avaliar se quebra em M+S
 - IDs sequenciais por área, nunca reutilizar
 - Dependências cross-area permitidas

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

@@ -1,136 +1,141 @@
-# Progresso — {{FEATURE}}
-
-> 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.
-
----
-
-## Status Geral: `não iniciado`
-
-<!-- não iniciado → em desenvolvimento → em revisão → concluído → arquivado -->
-
----
-
-<!--
-=============================================================================
-INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
-=============================================================================
-
-COMO GERAR ESTE ARQUIVO:
-
-1. Ler PRD §11 (Fases de Entrega) para definir as fases
-2. Ler TODOS os specs/{nome}/tasks.md da feature
-3. Para cada FASE DE ENTREGA, listar as áreas e contagem de tasks
-4. A visão primária é POR FASE, não por área
-
-COMO ATUALIZAR:
-
-- O /dev atualiza após cada task concluída
-- Status por fase: ⬜ pendente → 🔄 em andamento → ✅ concluída
-- Fase concluída = todas tasks de todas áreas daquela fase estão [x]
-- Ao concluir uma fase: registrar no Histórico + abrir PR
-
-=============================================================================
--->
-
-## Fases de Entrega
-
-| Fase | Nome | Prioridade | Entregável | Status | Tasks |
-|------|------|-----------|------------|--------|-------|
-| 1 | {{Nome}} | P1 | {{Entregável}} | ⬜ pendente | 0/{{N}} |
-| 2 | {{Nome}} | P1 | {{Entregável}} | ⬜ pendente | 0/{{N}} |
-| 3 | {{Nome}} | P2 | {{Entregável}} | ⬜ pendente | 0/{{N}} |
-
----
-
-## Fase 1 — {{Nome}} [P1]
-
-> **Entregável**: {{O que o usuário pode usar}}
-> **Critério de done**: {{Testes E2E que devem passar}}
-> **Branch**: `feature/{{FEATURE}}_fase1`
-> **PR**: (a ser criado)
-
-### Tasks por área
-
-#### {{AREA_1}} ({{N}} tasks)
-
-| Task | Descrição | Tamanho | Repo | Status |
-|------|-----------|---------|------|--------|
-| AREA-001 | | S/M/L | {{repo}} | ⬜ |
-
-#### {{AREA_2}} ({{N}} tasks)
-
-| Task | Descrição | Tamanho | Repo | Status |
-|------|-----------|---------|------|--------|
-| AREA-001 | | S/M/L | {{repo}} | ⬜ |
-
-### Resumo Fase 1
-
-| Área | Total | Feitas | % |
-|------|-------|--------|---|
-| {{AREA_1}} | {{N}} | 0 | 0% |
-| {{AREA_2}} | {{N}} | 0 | 0% |
-| **Total Fase 1** | **{{N}}** | **0** | **0%** |
-
----
-
-## Fase 2 — {{Nome}} [P1]
-
-> **Entregável**: {{...}}
-> **Depende de**: Fase 1 concluída
-
-<!-- Repetir mesma estrutura -->
-
----
-
-## Totais Gerais
-
-| Fase | Total | Feitas | % |
-|------|-------|--------|---|
-| Fase 1 | {{N}} | 0 | 0% |
-| Fase 2 | {{N}} | 0 | 0% |
-| **Total** | **{{N}}** | **0** | **0%** |
-
----
-
-## Ordem de Execução
-
-```
-Fase 1:
-  1. INFRA (setup de repos/ambiente)
-  2. BANCO (schema/migrations)
-  3. BACK (endpoints) ← pode paralelizar com FRONT após BANCO
-  4. FRONT (telas)
-  → PR Fase 1 + testes manuais + merge
-
-Fase 2:
-  1. BANCO (novas tabelas/migrations)
-  2. BACK (endpoints + regras)
-  3. FRONT (telas + integração)
-  → PR Fase 2 + testes manuais + merge
-```
-
----
-
-## Histórico
-
-| Data | Evento | Detalhes |
-|------|--------|----------|
-| | Feature criada | PRD aprovado, SDD gerado |
-
----
-
-## Pós-conclusão (por fase)
-
-- [ ] PR aberto com template detalhado
-- [ ] Ambiente local rodando para testes manuais
-- [ ] Testes automatizados passando (unit + integration + security)
-- [ ] Usuário aprovou e fez merge
-
-## Pós-conclusão (feature completa)
-
-- [ ] Todas fases concluídas e mergeadas
-- [ ] Mergear Delta Specs (SDD §11) nos docs de `docs/`
-- [ ] Atualizar `workspace/Output/progresso.md` (visão global)
-- [ ] Atualizar `.ai/memory/napkin.md` se houver aprendizado relevante
+# Progresso — {{FEATURE}}
+
+> 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 das Fases: `não iniciado`
+
+<!-- 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) -->
+
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+COMO GERAR ESTE ARQUIVO:
+
+1. Ler PRD §11 (Fases de Entrega) para definir as fases
+2. Ler TODOS os specs/{nome}/tasks.md da feature
+3. Para cada FASE DE ENTREGA, listar as áreas e contagem de tasks
+4. A visão primária é POR FASE, não por área
+
+COMO ATUALIZAR:
+
+- O /dev atualiza após cada task concluída
+- Status por fase: ⬜ pendente → 🔄 em andamento → ✅ concluída
+- Fase concluída = todas tasks de todas áreas daquela fase estão [x]
+- Ao concluir uma fase: registrar no Histórico + abrir PR
+
+=============================================================================
+-->
+
+## Fases de Entrega
+
+| Fase | Nome | Prioridade | Entregável | Status | Tasks |
+|------|------|-----------|------------|--------|-------|
+| 1 | {{Nome}} | P1 | {{Entregável}} | ⬜ pendente | 0/{{N}} |
+| 2 | {{Nome}} | P1 | {{Entregável}} | ⬜ pendente | 0/{{N}} |
+| 3 | {{Nome}} | P2 | {{Entregável}} | ⬜ pendente | 0/{{N}} |
+
+---
+
+## Fase 1 — {{Nome}} [P1]
+
+> **Entregável**: {{O que o usuário pode usar}}
+> **Critério de done**: {{Testes E2E que devem passar}}
+> **Branch**: `feature/{{FEATURE}}_fase1`
+> **PR**: (a ser criado)
+
+### Tasks por área
+
+#### {{AREA_1}} ({{N}} tasks)
+
+| Task | Descrição | Tamanho | Repo | Status |
+|------|-----------|---------|------|--------|
+| AREA-001 | | S/M/L | {{repo}} | ⬜ |
+
+#### {{AREA_2}} ({{N}} tasks)
+
+| Task | Descrição | Tamanho | Repo | Status |
+|------|-----------|---------|------|--------|
+| AREA-001 | | S/M/L | {{repo}} | ⬜ |
+
+### Resumo Fase 1
+
+| Área | Total | Feitas | % |
+|------|-------|--------|---|
+| {{AREA_1}} | {{N}} | 0 | 0% |
+| {{AREA_2}} | {{N}} | 0 | 0% |
+| **Total Fase 1** | **{{N}}** | **0** | **0%** |
+
+---
+
+## Fase 2 — {{Nome}} [P1]
+
+> **Entregável**: {{...}}
+> **Depende de**: Fase 1 concluída
+
+<!-- Repetir mesma estrutura -->
+
+---
+
+## Totais Gerais
+
+| Fase | Total | Feitas | % |
+|------|-------|--------|---|
+| Fase 1 | {{N}} | 0 | 0% |
+| Fase 2 | {{N}} | 0 | 0% |
+| **Total** | **{{N}}** | **0** | **0%** |
+
+---
+
+## Ordem de Execução
+
+```
+Fase 1:
+  1. INFRA (setup de repos/ambiente)
+  2. DB (schema/migrations)
+  3. BACK (endpoints) ← pode paralelizar com FRONT após DB
+  4. FRONT (telas)
+  → PR Fase 1 + testes manuais + merge
+
+Fase 2:
+  1. DB (novas tabelas/migrations)
+  2. BACK (endpoints + regras)
+  3. FRONT (telas + integração)
+  → PR Fase 2 + testes manuais + merge
+```
+
+---
+
+## Histórico
+
+| Data | Evento | Detalhes |
+|------|--------|----------|
+| | Feature criada | PRD aprovado, SDD gerado |
+
+---
+
+## Pós-conclusão (por fase)
+
+- [ ] PR aberto com template detalhado
+- [ ] Ambiente local rodando para testes manuais
+- [ ] Testes automatizados passando (unit + integration + security)
+- [ ] Usuário aprovou e fez merge
+
+## Pós-conclusão (feature completa)
+
+- [ ] Todas fases concluídas e mergeadas
+- [ ] Mergear Delta Specs (SDD §11) nos docs de `docs/`
+- [ ] Atualizar `workspace/Output/progresso.md` (visão global)
+- [ ] Atualizar `.ai/memory/napkin.md` se houver aprendizado relevante

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)
-# - BANCO 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, BANCO]                             # á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: