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

package/package.json

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

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

@@ -31,7 +31,7 @@ Note: **não validar** presença de `docs/` — ausência é válida (first_run)
 - `docs/` se existir (feature mode: usa como baseline pra §Sistema; não preenche subseções que não mudam)
 - `workspace/Output/$ARGUMENTS/sf-discovery.md` se existir
 - `.github/rules.md`
-- Template `.github/templates/feature/sdd.template.md`
+- Template `.github/templates/sf-feature/sdd.template.md`
 
 ### 2. Checkpoint de aprovação
 
@@ -66,7 +66,7 @@ SDD §Área-X: popular apenas áreas tocadas (GATE=SIM); resto marca N/A.
 
 ### 5. Gerar SDD
 
-Usar template `.github/templates/feature/sdd.template.md`:
+Usar template `.github/templates/sf-feature/sdd.template.md`:
 
 **Meta**: preencher `first_run`, `PRD empty`, `áreas tocadas`.
 
@@ -120,7 +120,7 @@ Cada serviço = 1 repo. Repos serão criados/clonados pelo `/sf-dev` (INFRA-001)
    - Organização/usuário do GitHub (ex: `empresa`)
    - Nome base do projeto (ex: `meu-projeto`)
    - Se algum repo já existe (pra clonar em vez de criar)
-3. Gerar `projetos.yaml` na raiz usando template `.github/templates/feature/projetos.template.yaml`
+3. Gerar `projetos.yaml` na raiz usando template `.github/templates/sf-feature/projetos.template.yaml`
 4. Mapear áreas de task para repos:
    - BACK → api (ou worker, se separado)
    - DB → api (se usa migrations) ou repo próprio
@@ -157,14 +157,41 @@ ultima_skill: "/sf-design"
 atualizado_em: "{{ISO_DATETIME}}"
 ```
 
-### 10. Publicar SDD no backend
+### 10. Publicar SDD no backend (OBRIGATÓRIO quando config existe)
 
-Se `sfw.config.yml` com `output.targets[]` ativo:
-- Executar `/sf-publish $ARGUMENTS SDD`
-- `/sf-publish` respeita `mode` (auto/manual/off) de cada target
-- Se não existe `sfw.config.yml` → pular silenciosamente
+**Este passo NÃO é opcional**. Tomar decisão baseada em arquivo:
 
-Ver `.github/skills/sf-publish/SKILL.md`.
+| Detecção | Ação |
+|----------|------|
+| `sfw.config.yml` NÃO existe | Pular silenciosamente. Registrar no output: "publish: skipped (no sfw.config.yml)" |
+| `sfw.config.yml` existe | **Chamar `/sf-publish $ARGUMENTS SDD`** — sem condicional. Execute. |
+
+`/sf-publish` respeita `mode` de cada target. Ver `.github/skills/sf-publish/SKILL.md`.
+
+### 11. Saída obrigatória
+
+Antes de terminar, a skill DEVE reportar:
+
+```
+/sf-design $ARGUMENTS — completo (first_run={true|false})
+
+Artefatos locais:
+  - workspace/Output/$ARGUMENTS/sdd.md
+  - specs/$ARGUMENTS/{brief,contracts,scenarios}.md
+  {se first_run: + docs/*.md (5 arquivos) + projetos.yaml}
+
+Áreas tocadas: [{lista do Meta do SDD}]
+
+Publish:
+  - {target-name}: {CREATED|UPDATED|SKIPPED|CONFLICT|ERROR} — ver .ai/sf-publish-log.md
+  OU
+  - SKIPPED (no sfw.config.yml)
+
+Próximo passo:
+  /sf-plan $ARGUMENTS   ← gerar tasks por área
+```
+
+Se `/sf-publish` retornou ERROR, a skill NÃO falha — artefato local está salvo.
 
 ## Notas
 

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

@@ -27,9 +27,9 @@ Skill atômica de extração. Lê insumos brutos de `workspace/Input/$ARGUMENTS/
 - `discovery.md` (se existir) → análise profunda prévia dos insumos
 - **`docs/` se existir** — usar como baseline pra responder checklist sem perguntar ao user
 - Templates:
-  - `.github/templates/feature/PRD.template.md` (destino principal)
-  - `.github/templates/feature/sf-extract-log.template.md` (append-only)
-  - `.github/templates/feature/backlog-extraido.template.md` (condicional, ver passo 6)
+  - `.github/templates/sf-feature/PRD.template.md` (destino principal)
+  - `.github/templates/sf-feature/sf-extract-log.template.md` (append-only)
+  - `.github/templates/sf-feature/backlog-extraido.template.md` (condicional, ver passo 6)
 
 > Se `discovery.md` existir: usar mapa do sistema e perguntas respondidas como contexto
 > enriquecido. Resultado: menos ambiguidades, melhor estruturação.
@@ -110,7 +110,7 @@ Temas não cobertos nem por insumos nem por `docs/` viram ambiguidades:
 
 ### 5. Gerar PRD.md
 
-Usar template `.github/templates/feature/PRD.template.md`:
+Usar template `.github/templates/sf-feature/PRD.template.md`:
 
 - Meta: preencher `empty` com resultado do 4.1
 - Se `empty: true`: só preencher Meta + adicionar nota rodapé "scope puro-técnico"
@@ -124,7 +124,7 @@ Gerar `backlog_extraido.md` **APENAS** se:
 - `first_run = true` (detectado do `.context.md`) E
 - Insumos mencionam features/funcionalidades que extrapolam o escopo atual
 
-Usar template `.github/templates/feature/backlog-extraido.template.md`:
+Usar template `.github/templates/sf-feature/backlog-extraido.template.md`:
 - Funcionalidades fora-de-escopo organizadas em roadmap faseado
 - Cada item sugere `/sf-start <nome>` futuro
 - Máximo 4-5 fases, priorizando cadastros/fundação na fase 1
@@ -163,16 +163,42 @@ ultima_skill: "/sf-extract"
 atualizado_em: "{{ISO_DATETIME}}"
 ```
 
-### 9. Publicar no backend
+### 9. Publicar PRD no backend (OBRIGATÓRIO quando config existe)
 
-Se `sfw.config.yml` com `output.targets[]` ativo:
-- Executar `/sf-publish $ARGUMENTS PRD`
-- `/sf-publish` respeita `mode` (auto/manual/off) de cada target
-- Se `empty: true`: publicar mesmo assim — Meta + rodapé já informam o estado ao humano
-- Se não existe `sfw.config.yml` → pular silenciosamente (projeto 100% local)
+**Este passo NÃO é opcional**. Tomar decisão baseada em arquivo, não em intenção:
+
+| Detecção | Ação |
+|----------|------|
+| `sfw.config.yml` NÃO existe | Pular silenciosamente (projeto 100% local). Registrar no output da skill: "publish: skipped (no sfw.config.yml)" |
+| `sfw.config.yml` existe | **Chamar `/sf-publish $ARGUMENTS PRD`** — sem "se", sem "talvez". Execute. |
+
+`/sf-publish` internamente respeita `mode` de cada target (`auto`/`manual`/`off`) e lida com `empty: true` (publica com nota).
 
 Ver `.github/skills/sf-publish/SKILL.md`.
 
+### 10. Saída obrigatória
+
+Antes de terminar, a skill DEVE reportar:
+
+```
+/sf-extract $ARGUMENTS — completo
+
+Artefatos locais:
+  - workspace/Output/$ARGUMENTS/PRD.md (empty: {true|false})
+  - workspace/Output/$ARGUMENTS/.extract-log.md
+  - workspace/Output/$ARGUMENTS/backlog_extraido.md (se aplicável)
+
+Publish:
+  - {target-name}: {CREATED|UPDATED|SKIPPED|CONFLICT|ERROR} — ver .ai/sf-publish-log.md
+  OU
+  - SKIPPED (no sfw.config.yml) — projeto 100% local
+
+Próximo passo:
+  /sf-design $ARGUMENTS   ← após revisar PRD e responder ambiguidades §14
+```
+
+Se `/sf-publish` retornou ERROR, a skill NÃO falha — apenas reporta no output pro user decidir. Artefato local está salvo.
+
 ## Re-extração
 
 - Merge ADITIVO com PRD existente (nunca remove info de inalterados)

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

@@ -1,6 +1,6 @@
 # /sf-mcp <provider>
 
-Setup interativo de backend externo. Pergunta os dados necessários, descobre a estrutura do projeto e cria todos os arquivos de configuração.
+Setup interativo de backend externo. Idempotente — pode rodar múltiplas vezes, só pergunta o que falta.
 
 ## Providers disponíveis
 
@@ -11,57 +11,79 @@ Setup interativo de backend externo. Pergunta os dados necessários, descobre a
 ## Uso
 
 ```
-/sf-mcp confluence
-/sf-mcp confluence test     ← só testa conexão
+/sf-mcp confluence           ← setup ou reconfiguração (idempotente)
+/sf-mcp confluence test      ← só testa conexão
 ```
 
 ---
 
 ## Provider: Confluence
 
-### Passo 1 — Verificar pré-requisitos
+### Passo 1 — Detectar estado atual
+
+Ler os 2 arquivos âncora:
+
+| Arquivo | O que extrair | Se ausente |
+|---------|---------------|------------|
+| `sfw.config.yml` | `project.root_page_id`, `project.name`, credenciais do space (`space_key`) | marcar como "falta config" |
+| `.mcp.json` | entry `mcpServers.atlassian` com `CONFLUENCE_URL`, `CONFLUENCE_USERNAME`, `CONFLUENCE_API_TOKEN` | marcar como "falta credenciais" |
+
+Calcular `state`:
+- **COMPLETO** — `sfw.config.yml` tem `root_page_id` E `.mcp.json` tem credenciais → ir pro Passo 2
+- **INCOMPLETO** — algo falta → ir pro Passo 3
+
+### Passo 2 — Estado COMPLETO: validar conexão
+
+Testar:
+```
+mcp__atlassian__confluence_get_page(page_id={root_page_id})
+```
+
+| Resultado | Ação |
+|-----------|------|
+| 200 OK | → Passo 4 (remapear árvore, reconfirmar Input/Output) |
+| 401 Unauthorized | Credencial expirou. Perguntar novo token, atualizar `.mcp.json`, avisar pra reiniciar Claude Code, PARAR |
+| 404 Not Found | `root_page_id` inválido. Perguntar novo ID, atualizar `sfw.config.yml`, retry teste |
+| MCP não responde | `.mcp.json` foi atualizado mas Claude não recarregou. Avisar pra reiniciar Claude Code, PARAR |
+| Network error | Mostrar erro, instruir troubleshooting (`.github/adapters/SETUP.md`) |
+
+### Passo 3 — Estado INCOMPLETO: coletar o que falta
+
+#### 3.1 Verificar `uvx`
 
-Verificar se `uvx` está instalado:
 ```bash
 uvx --version
 ```
 
-Se NÃO está instalado:
+Se não instalado:
 ```
 uvx não encontrado. Instale com:
   pip install uv
 
 Depois rode /sf-mcp confluence novamente.
 ```
-**Parar aqui** se uvx não estiver disponível.
+**PARAR**.
 
-### Passo 2 — Coletar credenciais
+#### 3.2 Se FALTA credenciais (`.mcp.json` ausente ou incompleto)
 
 Perguntar uma por uma:
-
 ```
-Configurando Confluence para o SFW.
+Configurando acesso ao Confluence.
 
 1. URL do Confluence (ex: https://sua-empresa.atlassian.net/wiki):
    >
 
-2. Email da conta Atlassian (ex: dev@empresa.com):
+2. Email da conta Atlassian:
    >
 
-3. API Token (gere em https://id.atlassian.com/manage-profile/security/api-tokens):
+3. API Token (https://id.atlassian.com/manage-profile/security/api-tokens):
    >
 
-4. Space Key (as letras na URL: /wiki/spaces/XX/...):
+4. Space Key (letras na URL: /wiki/spaces/XX/...):
    >
 ```
 
-### Passo 3 — Criar `.mcp.json`
-
-Verificar se `.mcp.json` já existe:
-- Se existe e já tem entrada `atlassian` → perguntar se quer atualizar
-- Se existe sem `atlassian` → adicionar entrada
-- Se não existe → criar
-
+Criar/atualizar `.mcp.json`:
 ```json
 {
   "mcpServers": {
@@ -78,95 +100,100 @@ Verificar se `.mcp.json` já existe:
 }
 ```
 
-**IMPORTANTE**: Credenciais hardcoded — `${VAR}` NÃO funciona no Claude Code.
+**IMPORTANTE**: credenciais hardcoded — `${VAR}` NÃO funciona no Claude Code.
 
-### Passo 4 — Testar conexão e descobrir projeto
-
-Testar chamando:
-```
-mcp__atlassian__confluence_search(query="space.key={space_key}", limit=5)
-```
-ou
-```
-mcp__atlassian__confluence_get_page_children(page_id=<root do space>)
+Se `.mcp.json` acabou de ser criado/atualizado:
 ```
+.mcp.json pronto. Preciso que você reinicie o Claude Code para o MCP carregar.
 
-**Se MCP não disponível** (primeira vez — `.mcp.json` acabou de ser criado):
+1. Feche o Claude Code
+2. Abra novamente na mesma pasta
+3. Rode /sf-mcp confluence — vou continuar de onde paramos (credenciais já salvas,
+   só vou pedir o que ainda falta)
 ```
-.mcp.json criado. O Claude Code precisa ser reiniciado para carregar o MCP.
+**PARAR**.
+
+#### 3.3 Se FALTA root_page_id (credenciais OK mas config sem root)
 
-1. Reinicie o Claude Code (feche e abra)
-2. Rode /sf-mcp confluence novamente — vou continuar de onde paramos
+Testar conexão básica primeiro:
+```
+mcp__atlassian__confluence_search(query="space.key={space_key}", limit=1)
 ```
-**Parar aqui.**
 
-**Se MCP funcionar** — pedir o projeto:
+Se falha → Passo 2 error table (401/MCP não responde/etc).
+Se OK:
 
 ```
-Conexão OK!
+Conexão OK.
 
-5. Qual é a page raiz do seu projeto no Confluence?
-   Cole o Page ID (número na URL) ou o título exato:
-   >
+Qual é a page RAIZ do seu projeto no Confluence?
+Cole o Page ID (número na URL) ou o título exato:
+  >
 ```
 
-### Passo 5 — Mapear a árvore do projeto
+Validar:
+```
+mcp__atlassian__confluence_get_page(page_id={resposta})
+```
+- Se 404 e user colou título → usar `confluence_search` pra achar
+- Se 404 e user colou ID → pedir de novo
+- Se OK → seguir
 
-Após receber o Page ID ou título da raiz:
+### Passo 4 — Mapear árvore do projeto
 
-1. Chamar `mcp__atlassian__confluence_get_page` pra confirmar que existe
-2. Chamar `mcp__atlassian__confluence_get_page_children` na raiz
-3. Chamar recursivamente nos filhos pra mapear a árvore completa
+Chamar recursivamente:
+```
+mcp__atlassian__confluence_get_page_children(page_id={root_page_id})
+  → pra cada filho, chamar get_page_children até bater em folha
+```
 
 Mostrar ao usuário:
-
 ```
-Projeto: "Barbearia Digital" (page_id: 65708)
+Projeto: "Barbearia Digital" (root_page_id: 65708)
 
 Estrutura encontrada:
-  ├── Requisitos (page_id: 360668)
-  │   ├── App mobile (page_id: 294950)
-  │   └── Painel admin (page_id: 131084)
-  ├── Documentação técnica (page_id: 294931)
-  ├── Referências (page_id: 557057)
-  └── Decisões (page_id: 425998)
+  ├── Requisitos (360668)
+  │   ├── App mobile (294950)
+  │   └── Painel admin (131084)
+  ├── Documentação técnica (294931)
+  ├── Referências (557057)
+  └── Decisões (425998)
 ```
 
-### Passo 6 — Identificar Input e Output
+### Passo 5 — Identificar Input e Output
 
-Perguntar ao usuário:
+**Se já existe config com Input/Output**: mostrar o que está salvo + opção de mudar:
+```
+Config atual:
+  Input:  Requisitos (360668)
+  Output: Documentação técnica (294931)
 
+Manter? (s/n)
 ```
-Preciso saber qual pasta contém os INSUMOS (Input) e onde devo PUBLICAR os artefatos (Output).
 
-Qual dessas é o Input (onde estão os insumos do PM/PO)?
+Se `s` → pular pro Passo 7.
+Se `n` → continuar perguntando (como se fosse setup novo).
+
+**Se é setup novo**:
+```
+Qual dessas pages contém os INSUMOS (Input, onde PM/PO publica)?
   1. Requisitos (360668)
   2. Documentação técnica (294931)
   3. Referências (557057)
   4. Decisões (425998)
-  5. Criar nova page "Input"
+  5. Criar nova page "Input" (filha da raiz)
   >
 ```
 
-Após o user escolher Input:
+Após escolher Input, perguntar Output com as pages restantes + opção "Criar nova page 'Output'".
 
-```
-Qual dessas é o Output (onde publico PRD, SDD, Progresso)?
-  1. Documentação técnica (294931)
-  2. Referências (557057)
-  3. Decisões (425998)
-  4. Criar nova page "Output"
-  >
-```
-
-**Se o user escolher "Criar nova"** → usar `mcp__atlassian__confluence_create_page` como filha da raiz.
+Se escolher "Criar nova" → `mcp__atlassian__confluence_create_page` como filha da raiz.
 
-### Passo 7 — Sugerir mapeamento de páginas úteis (opcional)
-
-Se a árvore tem outras pages relevantes, sugerir:
+### Passo 6 — Sugerir context_pages (opcional)
 
+Pages da árvore que não viraram Input nem Output:
 ```
-Encontrei outras páginas que podem ser úteis durante o desenvolvimento:
+Encontrei outras pages que podem ser úteis durante o desenvolvimento:
 
   - "Referências" (557057) → posso consultar durante /sf-extract e /sf-design
   - "Decisões" (425998) → posso consultar para ADRs no /sf-design
@@ -174,9 +201,11 @@ Encontrei outras páginas que podem ser úteis durante o desenvolvimento:
 Quer que eu mapeie essas páginas como contexto adicional? (s/n)
 ```
 
-Se sim, registrar no `sfw.config.yml` como `context_pages`.
+Se sim, incluir em `context_pages[]` no `sfw.config.yml`.
+
+### Passo 7 — Escrever `sfw.config.yml`
 
-### Passo 8 — Criar `sfw.config.yml`
+Preservar seções existentes (naming, etc) se já havia arquivo. Atualizar/criar:
 
 ```yaml
 project:
@@ -191,12 +220,12 @@ input:
   adapter: confluence
   config:
     space_key: "{space_key}"
-    parent_page_id: "{page_id escolhido como Input}"
+    parent_page_id: "{page_id do Input}"
     recursive: true
     include_attachments: true
   cache:
     local_dir: "workspace/Input/"
-    log: ".ai/load-log.md"
+    log: ".ai/sf-load-log.md"
     incremental: true
 
 output:
@@ -205,44 +234,41 @@ output:
       adapter: confluence
       config:
         space_key: "{space_key}"
-        parent_page_id: "{page_id escolhido como Output}"
-      publishes: [PRD, PRD, SDD, Progresso]
+        parent_page_id: "{page_id do Output}"
+      publishes: [PRD, SDD, Progresso]
       mode: auto
       conflict_detection: version
       approval_mechanism: label
       approval_label: "sfw-approved"
 
-# Pages de contexto adicional (consultadas pelo /sf-extract e /sf-design)
+# Descomente se tiver selecionado context_pages no Passo 6
 # context_pages:
 #   - id: "557057"
 #     title: "Referências"
 #     use_in: [extract, design]
-#   - id: "425998"
-#     title: "Decisões"
-#     use_in: [design]
 ```
 
-### Passo 9 — Ajustar `.gitignore`
+### Passo 8 — Ajustar `.gitignore`
 
-Adicionar se não existem:
-- `.mcp.json`
-- Bloco workspace ignored:
-  ```
-  # SFW: workspace ignored (external backend detected)
-  workspace/Output/**
-  !workspace/Output/.gitkeep
-  ```
+Adicionar se não existe:
+```
+.mcp.json
+
+# SFW: workspace ignored (external backend detected)
+workspace/Output/**
+!workspace/Output/.gitkeep
+```
 
-### Passo 10 — Resumir
+### Passo 9 — Resumir
 
 ```
 Confluence configurado!
 
-Projeto: {nome} ({page_id raiz})
+Projeto: {nome} ({root_page_id})
   Input:  {título Input} ({page_id})
   Output: {título Output} ({page_id})
 
-Arquivos criados/atualizados:
+Arquivos:
   .mcp.json          ← credenciais (gitignored)
   sfw.config.yml     ← configuração do projeto
   .gitignore         ← atualizado
@@ -251,42 +277,50 @@ O projeto tem {N} scopes no Input:
   - {lista dos filhos do Input}
 
 Próximo passo:
-  /sf-start <nome-do-scope>    ← bootstrap técnico
-  /sf-feature <nome-do-scope>        ← nova feature
+  /sf-start <nome-do-scope>
 ```
 
 ---
 
 ## Subcomando: `/sf-mcp confluence test`
 
-Apenas testa a conexão sem criar/modificar arquivos:
-
-1. Verificar que `.mcp.json` existe
-2. Verificar que `sfw.config.yml` existe e tem `adapter: confluence`
-3. Chamar `mcp__atlassian__confluence_get_page_children(page_id={input.parent_page_id})`
-4. Se OK → "Conexão OK! {N} scopes encontrados em Input: {lista}"
-5. Se falha → orientar troubleshooting (ver `.github/adapters/SETUP.md`)
+Apenas testa sem modificar arquivos:
+
+1. Verificar que `sfw.config.yml` existe com `project.root_page_id` e `input.config.parent_page_id`
+2. Verificar que `.mcp.json` existe com credenciais
+3. Testar `confluence_get_page(root_page_id)` → root acessível?
+4. Testar `confluence_get_page_children(input.config.parent_page_id)` → listar scopes
+5. Reportar:
+   ```
+   Conexão OK!
+     Root: "{nome}" ({root_page_id})
+     Input: {N} scopes encontrados
+     Output: {M} artefatos publicados anteriormente
+   ```
+6. Se falha: mostrar qual check falhou + link pro troubleshooting
 
 ---
 
 ## Notas
 
+- **`/sf-mcp confluence` é idempotente** — pode rodar N vezes. Só pergunta o que falta baseado em `sfw.config.yml` + `.mcp.json`
+- **`root_page_id` é âncora** — sem ele o framework não sabe os limites do projeto no space
 - `.mcp.json` é SEMPRE gitignored — contém credenciais
 - `sfw.config.yml` é commitável — zero segredos
-- Após criar `.mcp.json`, Claude Code PRECISA ser reiniciado
+- Após criar/atualizar `.mcp.json`, Claude Code PRECISA ser reiniciado
 - O framework conhece o projeto INTEIRO (raiz + toda a árvore), não só Input/Output
-- `context_pages` permite que /sf-extract e /sf-design consultem páginas extras como referência
-- Token Atlassian pode expirar — se der 401, gerar novo e atualizar `.mcp.json`
+- Token Atlassian pode expirar — se der 401, skill pede novo e atualiza `.mcp.json`
 
 ## Erros
 
 | Erro | Ação |
 |------|------|
 | uvx não instalado | Parar, instruir instalação |
-| MCP não disponível | Pedir reinício do Claude Code |
-| Page raiz não encontrada | Pedir ID/título correto |
-| Sem permissão de escrita | Informar, pedir ao admin |
-| Space key errado | Listar spaces disponíveis se possível |
+| MCP não responde após `.mcp.json` novo | Pedir reinício, retomar depois |
+| `root_page_id` 404 | Pedir ID/título correto, validar |
+| Token expirado (401) | Pedir novo token, atualizar .mcp.json, pedir reinício |
+| Sem permissão de escrita no space | Informar, pedir ao admin |
+| Space key inválido | Listar spaces disponíveis se possível |
 
 ## Referências
 

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

@@ -20,8 +20,8 @@ Metódico e exaustivo. Cada task auto-contida. Prioriza ordem correta.
 ### 1. Ler contexto
 - `workspace/Output/{nome}/sdd.md` completo (fonte humana)
 - `specs/{nome}/contracts.md` e `scenarios.md` (projeções já geradas pelo /sf-design)
-- `projetos.yaml` + `docs/` (architecture, domain, conventions) + `.claude/rules.md`
-- Template `.claude/templates/specs/tasks.template.md`
+- `projetos.yaml` + `docs/` (architecture, domain, conventions) + `.github/rules.md`
+- Template `.github/templates/specs/tasks.template.md`
 
 ### 2. Identificar fases de entrega
 Ler PRD §11 (Fases de Entrega) — cada fase vira um agrupamento de tasks:
@@ -88,15 +88,39 @@ status: "plan_done"
 ultima_skill: "/sf-plan"
 ```
 
-### 7. Publicar Progresso no(s) backend(s)
+### 7. Publicar Progresso no backend (OBRIGATÓRIO quando config existe)
 
-Se existe `sfw.config.yml` com `output.targets[]` ativo:
-- Executar `/sf-publish $ARGUMENTS Progresso`
-- O `/sf-publish` respeita o `mode` (auto/manual/off) de cada target
-- Se não existe `sfw.config.yml` → pular silenciosamente
-- **Nota**: `tasks.md`, `specs/`, `docs/`, `projetos.yaml` são LOCAL ONLY — nunca publicados
+**Este passo NÃO é opcional**. Tomar decisão baseada em arquivo:
 
-Ver `.github/skills/sf-publish.md`.
+| Detecção | Ação |
+|----------|------|
+| `sfw.config.yml` NÃO existe | Pular silenciosamente. Registrar: "publish: skipped (no sfw.config.yml)" |
+| `sfw.config.yml` existe | **Chamar `/sf-publish $ARGUMENTS Progresso`** — sem condicional. Execute. |
+
+`/sf-publish` respeita `mode` de cada target. Ver `.github/skills/sf-publish/SKILL.md`.
+
+**Nota**: `tasks.md`, `specs/`, `docs/`, `projetos.yaml` são LOCAL ONLY — `/sf-publish` nunca toca neles.
+
+### 8. Saída obrigatória
+
+Antes de terminar, a skill DEVE reportar:
+
+```
+/sf-plan $ARGUMENTS — completo
+
+Artefatos locais:
+  - specs/$ARGUMENTS/tasks.md ({N} tasks em {F} fases, áreas: [{lista}])
+  - workspace/Output/$ARGUMENTS/Progresso.md
+
+Publish:
+  - {target-name}: {CREATED|UPDATED|SKIPPED|CONFLICT|ERROR} — ver .ai/sf-publish-log.md
+  OU
+  - SKIPPED (no sfw.config.yml)
+
+Próximo passo:
+  /sf-dev $ARGUMENTS         ← implementa tudo
+  /sf-dev $ARGUMENTS --fase 1   ← só fase 1
+```
 
 ## Saídas
 - `specs/{nome}/tasks.md` — tabela única