spec-first-copilot 0.7.0 → 0.8.0-beta.2

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

@@ -1,152 +1,152 @@
-
-# /sf-plan $ARGUMENTS
-
-Skill atômica de planejamento. Lê **PRD + TRD + specs/{nome}/** e gera
-`specs/{nome}/tasks.md` (arquivo único) + `workspace/Output/{nome}/Progresso.md`.
-`$ARGUMENTS` = nome do scope (ex: `app_barbearia`, `feat_cadastro_cliente`).
-
-## Agente: Planner (Opus)
-
-Metódico e exaustivo. Cada task auto-contida. Prioriza ordem correta.
-
-## Pré-condições
-
-| # | Validação | Se falhar |
-|---|-----------|-----------|
-| 1 | $ARGUMENTS informado | Parar |
-| 2 | `.context.md` com status `design_done` | Se anterior → "/sf-design primeiro". Se posterior → "Tasks já geradas" |
-| 3 | Se `prd_existe=true`: PRD.md existe e `prd_aprovado=true` | Parar (não deveria passar pelo /sf-design, mas defensivo) |
-| 4 | Se `trd_existe=true`: TRD.md existe e `trd_aprovado=true` | Parar |
-| 5 | `specs/{nome}/{contracts,scenarios}.md` existem (projeções do /sf-design) | Parar → "/sf-design não gerou projeções — re-rode" |
-
-## Passos
-
-### 1. Ler contexto
-
-- `workspace/Output/{nome}/PRD.md` (se prd_existe) + `TRD.md` (se trd_existe) — fontes
-- `specs/{nome}/{brief,contracts,scenarios}.md` (projeções já geradas pelo /sf-design)
-- `projetos.yaml` + `docs/` (architecture, domain, conventions) + `.github/rules.md`
-- Template `.github/templates/specs/tasks.template.md`
-
-### 2. Identificar fases de entrega
-
-Ler **PRD §10 (Fases de Entrega)** — cada fase vira um agrupamento de tasks:
-
-- Fases são sequenciais: Fase 2 depende de Fase 1 concluída
-- Cada fase tem entregável + critério de done
-- O `/sf-dev` pode rodar por fase: `/sf-dev feat_nome --fase 1`
-
-**Se scope não tem PRD** (puro-técnico): toda task vai pra **Fase 1**. Não há
-fases de entrega de produto — é bootstrap/infra em uma leva só.
-
-### 3. Identificar áreas (dinâmicas, vêm do TRD)
-
-Ler `.context.md → areas_tocadas` (populado pelo /sf-design a partir dos GATEs do TRD).
-
-| Seção do TRD | Área |
-|--------------|------|
-| §2 §Área-Backend (GATE=SIM) | BACK |
-| §3 §Área-Frontend (GATE=SIM) | FRONT |
-| §4 §Área-DB (GATE=SIM) | DB |
-| §5 §Área-Infra (GATE=SIM) | INFRA |
-
-Áreas com GATE=NÃO não geram tasks nessa área. Se o scope tem apenas PRD (raríssimo
-caso puro-produto sem TRD): área FRONT derivada de PRD §7 Telas.
-
-**INFRA em first-run** (detectado via `first_run=true` no .context):
-
-```
-- [ ] INFRA-001: Validar ambiente local + setup repos (projetos.yaml)
-- [ ] INFRA-002: Docker-compose dev (só dependências) + Dockerfiles prod
-- [ ] INFRA-003: Hello world — subir stack completa e validar
-```
-
-INFRA-001 sempre a PRIMEIRA; INFRA-003 sempre a ÚLTIMA da Fase 1 (validação).
-
-### 4. Gerar `specs/{nome}/tasks.md` (arquivo único)
-
-Tabela única com coluna `Área` diferenciando:
-
-```markdown
-| ID | Área | Fase | Tam | Título | Repo | Arquivos | Depende de | Ref TRD | Ref CA |
-|----|------|------|-----|--------|------|----------|-----------|---------|--------|
-| DB-001 | DB | 1 | S | Migration clientes | api | src/db/migrations/... | — | TRD §4.1 | — |
-| BACK-001 | BACK | 1 | M | Endpoint POST /clientes | api | src/routes/... | DB-001 | TRD §2.1 | CA-001 |
-```
-
-**Regras** (ver `.github/templates/specs/tasks.template.md` pra detalhes):
-
-- 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 (DB, BACK, FRONT, INFRA, MOBILE...)
-- Tamanhos: S (≤2h), M (≤4h), L (≤2 dias). L → considerar dividir (INVEST: Small)
-- IDs sequenciais por área, nunca reutilizar
-- Dependências cross-area permitidas
-- `Ref TRD`: seção do TRD (ex: `§2.1`, `§4.2`) — obrigatório quando TRD existe
-- `Ref CA`: ID do CA em `specs/{nome}/scenarios.md` ou `—`
-- Ordenar por Fase → Área → ID (visual)
-
-**Tasks L**: preencher bloco "Done When — {TASK-ID}" abaixo da tabela com 3-5
-bullets verificáveis.
-
-### 5. Gerar `workspace/Output/{nome}/Progresso.md` (tracking)
-
-Progresso.md vive em **workspace/Output** (tracking de execução, não spec).
-
-- Resumo Área × Fase com contagem (derivado de `tasks.md`)
-- Ordem de execução com paralelismos
-- Checklist pós-conclusão (já coberto pelo /sf-merge-docs automático no fim do /sf-dev)
-
-**Regra**: status das tasks vive SÓ em Progresso.md. `tasks.md` é o plano imutável.
-
-### 6. Atualizar `.context.md`
-
-```yaml
-status: "plan_done"
-ultima_skill: "/sf-plan"
-atualizado_em: "{{ISO_DATETIME}}"
-```
-
-### 7. Publicar Progresso no backend (se `sfw.config.yml` existe)
-
-Chamar `/sf-publish $ARGUMENTS Progresso`. Respeita `mode` de cada target.
-
-**Nota**: `tasks.md`, `specs/*`, `docs/*`, `projetos.yaml` são **LOCAL ONLY** — `/sf-publish`
-nunca toca neles. Apenas PRD/TRD/Progresso vão pro Confluence.
-
-### 8. Saída obrigatória
-
-```
-/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}: Progresso: {{status}}
-  OU
-  - SKIPPED (no sfw.config.yml)
-
-Próximo passo:
-  /sf-dev $ARGUMENTS              ← implementa tudo
-  /sf-dev $ARGUMENTS --fase 1     ← só a primeira fase (RECOMENDADO)
-```
-
-## Saídas
-
-- `specs/{nome}/tasks.md` — plano (tabela única)
-- `workspace/Output/{nome}/Progresso.md` — tracking
-
-## Rastreabilidade
-
-Cada task gerada deve ter:
-- **Ref TRD** (se TRD existe): seção do TRD que motivou — garante que nada do TRD
-  fica sem task correspondente
-- **Ref CA** (se aplicável): garante que cada CA em `scenarios.md` tem pelo menos
-  1 task que o satisfaz
-
-Validação final antes de terminar:
-- Todo endpoint do TRD §2.1 tem task BACK correspondente? ✓
-- Toda tabela/migration do TRD §4 tem task DB correspondente? ✓
-- Todo CA em `scenarios.md` tem task Ref CA correspondente (ou justificativa de why not)? ✓
+
+# /sf-plan $ARGUMENTS
+
+Skill atômica de planejamento. Lê **PRD + TRD + specs/{nome}/** e gera
+`specs/{nome}/tasks.md` (arquivo único) + `workspace/Output/{nome}/Progresso.md`.
+`$ARGUMENTS` = nome do scope (ex: `app_barbearia`, `feat_cadastro_cliente`).
+
+## Agente: Planner (Opus)
+
+Metódico e exaustivo. Cada task auto-contida. Prioriza ordem correta.
+
+## Pré-condições
+
+| # | Validação | Se falhar |
+|---|-----------|-----------|
+| 1 | $ARGUMENTS informado | Parar |
+| 2 | `.context.md` com status `design_done` | Se anterior → "/sf-design primeiro". Se posterior → "Tasks já geradas" |
+| 3 | Se `prd_existe=true`: PRD.md existe e `prd_aprovado=true` | Parar (não deveria passar pelo /sf-design, mas defensivo) |
+| 4 | Se `trd_existe=true`: TRD.md existe e `trd_aprovado=true` | Parar |
+| 5 | `specs/{nome}/{contracts,scenarios}.md` existem (projeções do /sf-design) | Parar → "/sf-design não gerou projeções — re-rode" |
+
+## Passos
+
+### 1. Ler contexto
+
+- `workspace/Output/{nome}/PRD.md` (se prd_existe) + `TRD.md` (se trd_existe) — fontes
+- `specs/{nome}/{brief,contracts,scenarios}.md` (projeções já geradas pelo /sf-design)
+- `projetos.yaml` + `docs/` (architecture, domain, conventions) + `.github/rules.md`
+- Template `.github/templates/specs/tasks.template.md`
+
+### 2. Identificar fases de entrega
+
+Ler **PRD §10 (Fases de Entrega)** — cada fase vira um agrupamento de tasks:
+
+- Fases são sequenciais: Fase 2 depende de Fase 1 concluída
+- Cada fase tem entregável + critério de done
+- O `/sf-dev` pode rodar por fase: `/sf-dev feat_nome --fase 1`
+
+**Se scope não tem PRD** (puro-técnico): toda task vai pra **Fase 1**. Não há
+fases de entrega de produto — é bootstrap/infra em uma leva só.
+
+### 3. Identificar áreas (dinâmicas, vêm do TRD)
+
+Ler `.context.md → areas_tocadas` (populado pelo /sf-design a partir dos GATEs do TRD).
+
+| Seção do TRD | Área |
+|--------------|------|
+| §2 §Área-Backend (GATE=SIM) | BACK |
+| §3 §Área-Frontend (GATE=SIM) | FRONT |
+| §4 §Área-DB (GATE=SIM) | DB |
+| §5 §Área-Infra (GATE=SIM) | INFRA |
+
+Áreas com GATE=NÃO não geram tasks nessa área. Se o scope tem apenas PRD (raríssimo
+caso puro-produto sem TRD): área FRONT derivada de PRD §7 Telas.
+
+**INFRA em first-run** (detectado via `first_run=true` no .context):
+
+```
+- [ ] INFRA-001: Validar ambiente local + setup repos (projetos.yaml)
+- [ ] INFRA-002: Docker-compose dev (só dependências) + Dockerfiles prod
+- [ ] INFRA-003: Hello world — subir stack completa e validar
+```
+
+INFRA-001 sempre a PRIMEIRA; INFRA-003 sempre a ÚLTIMA da Fase 1 (validação).
+
+### 4. Gerar `specs/{nome}/tasks.md` (arquivo único)
+
+Tabela única com coluna `Área` diferenciando:
+
+```markdown
+| ID | Área | Fase | Tam | Título | Repo | Arquivos | Depende de | Ref TRD | Ref CA |
+|----|------|------|-----|--------|------|----------|-----------|---------|--------|
+| DB-001 | DB | 1 | S | Migration clientes | api | src/db/migrations/... | — | TRD §4.1 | — |
+| BACK-001 | BACK | 1 | M | Endpoint POST /clientes | api | src/routes/... | DB-001 | TRD §2.1 | CA-001 |
+```
+
+**Regras** (ver `.github/templates/specs/tasks.template.md` pra detalhes):
+
+- 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 (DB, BACK, FRONT, INFRA, MOBILE...)
+- Tamanhos: S (≤2h), M (≤4h), L (≤2 dias). L → considerar dividir (INVEST: Small)
+- IDs sequenciais por área, nunca reutilizar
+- Dependências cross-area permitidas
+- `Ref TRD`: seção do TRD (ex: `§2.1`, `§4.2`) — obrigatório quando TRD existe
+- `Ref CA`: ID do CA em `specs/{nome}/scenarios.md` ou `—`
+- Ordenar por Fase → Área → ID (visual)
+
+**Tasks L**: preencher bloco "Done When — {TASK-ID}" abaixo da tabela com 3-5
+bullets verificáveis.
+
+### 5. Gerar `workspace/Output/{nome}/Progresso.md` (tracking)
+
+Progresso.md vive em **workspace/Output** (tracking de execução, não spec).
+
+- Resumo Área × Fase com contagem (derivado de `tasks.md`)
+- Ordem de execução com paralelismos
+- Checklist pós-conclusão (já coberto pelo /sf-merge-docs automático no fim do /sf-dev)
+
+**Regra**: status das tasks vive SÓ em Progresso.md. `tasks.md` é o plano imutável.
+
+### 6. Atualizar `.context.md`
+
+```yaml
+status: "plan_done"
+ultima_skill: "/sf-plan"
+atualizado_em: "{{ISO_DATETIME}}"
+```
+
+### 7. Publicar Progresso no backend (se `sfw.config.yml` existe)
+
+Chamar `/sf-publish $ARGUMENTS Progresso`. Respeita `mode` de cada target.
+
+**Nota**: `tasks.md`, `specs/*`, `docs/*`, `projetos.yaml` são **LOCAL ONLY** — `/sf-publish`
+nunca toca neles. Apenas PRD/TRD/Progresso vão pro Confluence.
+
+### 8. Saída obrigatória
+
+```
+/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}: Progresso: {{status}}
+  OU
+  - SKIPPED (no sfw.config.yml)
+
+Próximo passo:
+  /sf-dev $ARGUMENTS              ← implementa tudo
+  /sf-dev $ARGUMENTS --fase 1     ← só a primeira fase (RECOMENDADO)
+```
+
+## Saídas
+
+- `specs/{nome}/tasks.md` — plano (tabela única)
+- `workspace/Output/{nome}/Progresso.md` — tracking
+
+## Rastreabilidade
+
+Cada task gerada deve ter:
+- **Ref TRD** (se TRD existe): seção do TRD que motivou — garante que nada do TRD
+  fica sem task correspondente
+- **Ref CA** (se aplicável): garante que cada CA em `scenarios.md` tem pelo menos
+  1 task que o satisfaz
+
+Validação final antes de terminar:
+- Todo endpoint do TRD §2.1 tem task BACK correspondente? ✓
+- Toda tabela/migration do TRD §4 tem task DB correspondente? ✓
+- Todo CA em `scenarios.md` tem task Ref CA correspondente (ou justificativa de why not)? ✓

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

@@ -1,144 +1,144 @@
-
-# /sf-publish <nome> <tipo>
-
-Publica um artefato gerado localmente no(s) backend(s) configurado(s) como `output.targets[]` no `sfw.config.yml`.
-
-## Argumentos
-
-- `<nome>` = scope do artefato (ex: `app_barbearia`, `feat_login`)
-- `<tipo>` = tipo do artefato: `PRD` | `TRD` | `Progresso`
-
-## Quando é chamado
-
-Automaticamente pelos commands:
-- `/sf-extract` → publica `PRD` (se `prd_existe=true`) E `TRD` (se `trd_existe=true`)
-- `/sf-plan` → publica `Progresso` no fim
-- `/sf-design` → **não publica** (gera apenas artefatos locais: docs/, specs/, projetos.yaml)
-
-Manualmente: quando o usuário quer re-publicar um artefato após editar local.
-
-## Modo (`mode` no sfw.config.yml)
-
-| Mode | Comportamento |
-|------|---------------|
-| `auto` | Publica sem perguntar (default) |
-| `manual` | Gera artefato local, pergunta "Publicar no {target.name}? (s/n)" |
-| `off` | Ignora o target completamente |
-
-## Pré-condições
-
-| # | Validação | Se falhar |
-|---|-----------|-----------|
-| 1 | `sfw.config.yml` existe | Parar → "Sem sfw.config.yml, publish desabilitado. Artefato local está em workspace/Output/{nome}/{tipo}.md" |
-| 2 | Tipo está na `publishes` do target | Pular target, informar |
-| 3 | Arquivo local existe em `workspace/Output/{nome}/{tipo}.md` (ou .lower) | Parar → "Arquivo não encontrado" |
-
-## Execução
-
-### 1. Carregar configuração
-
-- Ler `sfw.config.yml`
-- Para cada target em `output.targets[]`:
-  - Verificar `mode` (se `off` → pular)
-  - Verificar `publishes` inclui `<tipo>` (se não → pular)
-  - Se `mode: manual` → perguntar ao usuário
-
-### 2. Ler artefato local
-
-Ler `workspace/Output/{nome}/{arquivo}` onde arquivo depende do tipo:
-- `PRD` → `PRD.md`
-- `TRD` → `TRD.md`
-- `Progresso` → `Progresso.md`
-
-### 3. Aplicar naming
-
-Usar templates do `naming` no `sfw.config.yml`:
-- `containerTitle = applyNaming(naming.output_container, {scope: nome})`
-  - Ex: `"out_app_barbearia"`
-- `artifactTitle = applyNaming(naming.output_artifact, {scope: nome, type: tipo})`
-  - Ex: `"app_barbearia - PRD"`
-
-### 4. Para cada target ativo — publicar
-
-**Confluence**:
-
-1. Listar filhos de `target.config.parent_page_id` (Output)
-2. Buscar container pelo `containerTitle`:
-   - **Não existe** → `mcp__atlassian__confluence_create_page` como filho de Output
-   - **Existe** → pegar `container.id`
-3. Listar filhos do container
-4. Buscar artefato pelo `artifactTitle`:
-   - **Não existe** → `mcp__atlassian__confluence_create_page` com `content=markdown local`
-   - **Existe** → precisa atualizar (próximo passo)
-
-### 5. Conflict detection (update)
-
-Se artefato existe no backend:
-
-1. Ler `.ai/publish-log.md` pra pegar a última `version` publicada desse artefato
-2. Chamar `mcp__atlassian__confluence_get_page(page_id=artifact.id)` → pega `currentVersion`
-3. **Se `currentVersion != lastPublishedVersion`** → DRIFT detectado
-   - Alguém editou no Confluence depois do último publish
-   - Mostrar ao usuário:
-     ```
-     CONFLITO: "{artifactTitle}" foi editada no Confluence desde o último publish.
-
-     Última version publicada por nós: {last}
-     Version atual no Confluence: {current}
-
-     Opções:
-       1. Sobrescrever (perde edição manual)
-       2. Abortar (edita local depois)
-       3. Ver diff
-     ```
-   - Esperar decisão
-4. Se sem drift → `mcp__atlassian__confluence_update_page(page_id, content)`
-5. Ler nova `version` retornada
-
-### 6. Registrar em `.ai/publish-log.md`
-
-Formato append-only:
-
-```markdown
-## Publish: {nome} {tipo} — {ISO_DATETIME}
-
-| Target | Container | Artifact ID | Version | Status |
-|--------|-----------|-------------|---------|--------|
-| confluence-mirror | out_app_barbearia (393220) | 393238 | 3 | UPDATED |
-```
-
-Status: `CREATED`, `UPDATED`, `SKIPPED` (se INALTERADO), `CONFLICT` (se drift não resolvido)
-
-### 7. Informar o usuário
-
-```
-Publicado: {nome} {tipo}
-
-  confluence-mirror: app_barbearia - PRD (v3) — UPDATED
-
-Link: https://empresa.atlassian.net/wiki/spaces/ST/pages/393238
-```
-
-## Erros
-
-| Erro | Ação |
-|------|------|
-| `sfw.config.yml` não existe | Skippa todos os targets, só salva local |
-| Target MCP não disponível | Avisar, pular target |
-| Sem permissão de escrita | Avisar, pular target |
-| Conflict não resolvido | Não publicar, salvar como CONFLICT no log |
-| Container Output não existe | Criar automaticamente como filho de `output.parent_page_id` |
-
-## Notas
-
-- O `/sf-publish` é **idempotente** pra content sem mudanças — detecta hash igual e marca `SKIPPED`
-- `naming.output_container` e `naming.output_artifact` são aplicados em TODOS os targets
-- Cada target pode ter `publishes: []` diferente (permite segmentar: Confluence recebe 4 artefatos, filesystem recebe todos)
-- `.ai/publish-log.md` é essencial pro conflict detection funcionar
-- Nunca publica tasks.md, docs/, specs/, projetos.yaml — esses são LOCAL ONLY
-
-## Referências
-
-- Adapter interface: `.github/adapters/interface.md`
-- Confluence adapter: `.github/adapters/confluence.md`
-- Naming engine: `.github/adapters/naming.md`
+
+# /sf-publish <nome> <tipo>
+
+Publica um artefato gerado localmente no(s) backend(s) configurado(s) como `output.targets[]` no `sfw.config.yml`.
+
+## Argumentos
+
+- `<nome>` = scope do artefato (ex: `app_barbearia`, `feat_login`)
+- `<tipo>` = tipo do artefato: `PRD` | `TRD` | `Progresso`
+
+## Quando é chamado
+
+Automaticamente pelos commands:
+- `/sf-extract` → publica `PRD` (se `prd_existe=true`) E `TRD` (se `trd_existe=true`)
+- `/sf-plan` → publica `Progresso` no fim
+- `/sf-design` → **não publica** (gera apenas artefatos locais: docs/, specs/, projetos.yaml)
+
+Manualmente: quando o usuário quer re-publicar um artefato após editar local.
+
+## Modo (`mode` no sfw.config.yml)
+
+| Mode | Comportamento |
+|------|---------------|
+| `auto` | Publica sem perguntar (default) |
+| `manual` | Gera artefato local, pergunta "Publicar no {target.name}? (s/n)" |
+| `off` | Ignora o target completamente |
+
+## Pré-condições
+
+| # | Validação | Se falhar |
+|---|-----------|-----------|
+| 1 | `sfw.config.yml` existe | Parar → "Sem sfw.config.yml, publish desabilitado. Artefato local está em workspace/Output/{nome}/{tipo}.md" |
+| 2 | Tipo está na `publishes` do target | Pular target, informar |
+| 3 | Arquivo local existe em `workspace/Output/{nome}/{tipo}.md` (ou .lower) | Parar → "Arquivo não encontrado" |
+
+## Execução
+
+### 1. Carregar configuração
+
+- Ler `sfw.config.yml`
+- Para cada target em `output.targets[]`:
+  - Verificar `mode` (se `off` → pular)
+  - Verificar `publishes` inclui `<tipo>` (se não → pular)
+  - Se `mode: manual` → perguntar ao usuário
+
+### 2. Ler artefato local
+
+Ler `workspace/Output/{nome}/{arquivo}` onde arquivo depende do tipo:
+- `PRD` → `PRD.md`
+- `TRD` → `TRD.md`
+- `Progresso` → `Progresso.md`
+
+### 3. Aplicar naming
+
+Usar templates do `naming` no `sfw.config.yml`:
+- `containerTitle = applyNaming(naming.output_container, {scope: nome})`
+  - Ex: `"out_app_barbearia"`
+- `artifactTitle = applyNaming(naming.output_artifact, {scope: nome, type: tipo})`
+  - Ex: `"app_barbearia - PRD"`
+
+### 4. Para cada target ativo — publicar
+
+**Confluence**:
+
+1. Listar filhos de `target.config.parent_page_id` (Output)
+2. Buscar container pelo `containerTitle`:
+   - **Não existe** → `mcp__atlassian__confluence_create_page` como filho de Output
+   - **Existe** → pegar `container.id`
+3. Listar filhos do container
+4. Buscar artefato pelo `artifactTitle`:
+   - **Não existe** → `mcp__atlassian__confluence_create_page` com `content=markdown local`
+   - **Existe** → precisa atualizar (próximo passo)
+
+### 5. Conflict detection (update)
+
+Se artefato existe no backend:
+
+1. Ler `.ai/publish-log.md` pra pegar a última `version` publicada desse artefato
+2. Chamar `mcp__atlassian__confluence_get_page(page_id=artifact.id)` → pega `currentVersion`
+3. **Se `currentVersion != lastPublishedVersion`** → DRIFT detectado
+   - Alguém editou no Confluence depois do último publish
+   - Mostrar ao usuário:
+     ```
+     CONFLITO: "{artifactTitle}" foi editada no Confluence desde o último publish.
+
+     Última version publicada por nós: {last}
+     Version atual no Confluence: {current}
+
+     Opções:
+       1. Sobrescrever (perde edição manual)
+       2. Abortar (edita local depois)
+       3. Ver diff
+     ```
+   - Esperar decisão
+4. Se sem drift → `mcp__atlassian__confluence_update_page(page_id, content)`
+5. Ler nova `version` retornada
+
+### 6. Registrar em `.ai/publish-log.md`
+
+Formato append-only:
+
+```markdown
+## Publish: {nome} {tipo} — {ISO_DATETIME}
+
+| Target | Container | Artifact ID | Version | Status |
+|--------|-----------|-------------|---------|--------|
+| confluence-mirror | out_app_barbearia (393220) | 393238 | 3 | UPDATED |
+```
+
+Status: `CREATED`, `UPDATED`, `SKIPPED` (se INALTERADO), `CONFLICT` (se drift não resolvido)
+
+### 7. Informar o usuário
+
+```
+Publicado: {nome} {tipo}
+
+  confluence-mirror: app_barbearia - PRD (v3) — UPDATED
+
+Link: https://empresa.atlassian.net/wiki/spaces/ST/pages/393238
+```
+
+## Erros
+
+| Erro | Ação |
+|------|------|
+| `sfw.config.yml` não existe | Skippa todos os targets, só salva local |
+| Target MCP não disponível | Avisar, pular target |
+| Sem permissão de escrita | Avisar, pular target |
+| Conflict não resolvido | Não publicar, salvar como CONFLICT no log |
+| Container Output não existe | Criar automaticamente como filho de `output.parent_page_id` |
+
+## Notas
+
+- O `/sf-publish` é **idempotente** pra content sem mudanças — detecta hash igual e marca `SKIPPED`
+- `naming.output_container` e `naming.output_artifact` são aplicados em TODOS os targets
+- Cada target pode ter `publishes: []` diferente (permite segmentar: Confluence recebe 4 artefatos, filesystem recebe todos)
+- `.ai/publish-log.md` é essencial pro conflict detection funcionar
+- Nunca publica tasks.md, docs/, specs/, projetos.yaml — esses são LOCAL ONLY
+
+## Referências
+
+- Adapter interface: `.github/adapters/interface.md`
+- Confluence adapter: `.github/adapters/confluence.md`
+- Naming engine: `.github/adapters/naming.md`