spec-first-copilot 0.5.0-beta.1 → 0.5.0-beta.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-first-copilot",
-  "version": "0.5.0-beta.1",
+  "version": "0.5.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/adapters/confluence.md

@@ -0,0 +1,273 @@
+# ConfluenceAdapter — Runbook
+
+> Implementação do `SourceAdapter` para Atlassian Confluence via MCP
+> `sooperset/mcp-atlassian` (validado end-to-end em 2026-04-11 —
+> ver `planodetarefas.md §9.9` e napkin "Hard findings do teste E2E").
+>
+> Este arquivo é o **runbook que o agent segue** quando uma skill precisa
+> de uma operação de Confluence. A interface conceitual está em
+> `.github/adapters/interface.md`.
+
+---
+
+## Meta
+
+| Campo | Valor |
+|-------|-------|
+| `name` | `confluence` |
+| MCP provider | `sooperset/mcp-atlassian` via uvx |
+| Credenciais | `.mcp.json` gitignored (hardcoded, `${VAR}` **não funciona**) |
+| Transporte | MCP — tools prefixadas `mcp__atlassian__confluence_*` |
+| Conflict detection | **Client-side obrigatório** (MCP não aceita `expectedVersion`) |
+| Suporta attachments? | ✅ leitura + escrita |
+| Suporta busca? | Fora da interface (skills podem chamar `confluence_search` direto se precisar) |
+
+---
+
+## Config
+
+Passada via `sfw.config.yml > input.config` ou `output.targets[].config`.
+
+| Campo | Obrig. | Tipo | Descrição |
+|-------|:---:|------|-----------|
+| `space_key` | ✅ | string | Ex: `"ST"`. Usado em todas as operações que exigem space. |
+| `parent_page_id` | ✅ | string | ID numérico (como string) da página raiz. Ex: `"360668"`. |
+| `recursive` | — | boolean | Default `true`. Se `false`, `listChildren` não desce. |
+| `include_attachments` | — | boolean | Default `true`. Se `false`, `fetchAttachments` retorna `[]`. |
+
+### `validateConfig`
+
+Lança `ValidationError` se:
+- `space_key` ausente, vazio ou não-string
+- `parent_page_id` ausente, vazio ou não parseável como inteiro
+- `recursive` presente mas não-boolean
+- `include_attachments` presente mas não-boolean
+
+Não valida que `space_key` existe no Confluence — isso acontece no primeiro
+`listChildren` e vira `AuthError` ou `NotFoundError`.
+
+---
+
+## Mapeamento da interface → MCP
+
+### `listChildren(containerId) → Item[]`
+
+**MCP**: `mcp__atlassian__confluence_get_page_children`
+
+**Passos**:
+1. Chamar tool com `parent_id: containerId`, `limit: 100`, `expand: "version"`
+2. Para cada filho retornado, montar `Item`:
+   - `id` = `page.id` (string)
+   - `title` = `page.title`
+   - `version` = `String(page.version.number)`
+   - `type` = `"page"` (Confluence só tem páginas — folders são páginas vazias convencionadas)
+   - `hasChildren` = `page.children_count > 0` (se vier na resposta; senão `true` por default — custo de 1 chamada extra é baixo)
+3. Se retorno paginado (cursor), iterar até esgotar
+4. Retornar array
+
+**Erros**:
+- `404` → `NotFoundError { kind: "container", itemId: containerId }`
+- `401/403` → `AuthError`
+- `5xx`/timeout → `TransportError { retryable: true }`
+
+---
+
+### `fetchContent(itemId) → { content, metadata }`
+
+**MCP**: `mcp__atlassian__confluence_get_page` com `convert_to_markdown: true`
+
+**Passos**:
+1. Chamar tool com `page_id: itemId`, `convert_to_markdown: true`, `include_metadata: true`
+2. Extrair `content` do campo markdown retornado
+3. Montar `metadata`:
+   - `version` = `page.version.number` (inteiro)
+   - `space_key`, `parent_id`, `created_at`, `updated_at`, `author`
+   - `labels` = array das labels da página (usado pelo caller pra checar `sfw-approved`)
+4. Retornar `{ content, metadata }`
+
+**Notas importantes**:
+- Markdown roundtrip **normaliza** (`#` vira `===` no H1, `-` vira `*` em listas).
+  `version.number` é a fonte de verdade pra drift, **não** diff de bytes.
+- `labels` vêm via `confluence_get_labels` **separadamente** se não vierem
+  embutidos na resposta do `get_page`. Chamar só se o caller pediu (lazy).
+
+**Erros**: mesmas regras do `listChildren`.
+
+---
+
+### `fetchAttachments(itemId) → Attachment[]`
+
+**MCP**:
+- `mcp__atlassian__confluence_get_attachments` (lista)
+- `mcp__atlassian__confluence_download_attachment` (bytes, lazy)
+
+**Passos**:
+1. Se `config.include_attachments === false`, retornar `[]` sem chamar MCP.
+2. Chamar `get_attachments` com `page_id: itemId`
+3. Para cada item retornado, montar `Attachment`:
+   - `filename` = `attachment.title`
+   - `size` = `attachment.size` em bytes
+   - `mimeType` = `attachment.mime_type`
+   - `download()` = closure que chama `confluence_download_attachment` com
+     `page_id: itemId, filename: attachment.title` e retorna `Buffer`
+4. Retornar array
+
+**Lazy**: `download()` só dispara quando o caller chama. Listar attachments é
+barato, baixar PDFs pode não ser.
+
+---
+
+### `getVersion(itemId) → string`
+
+**MCP**: `mcp__atlassian__confluence_get_page` com `convert_to_markdown: false`
+
+**Passos**:
+1. Chamar tool com `page_id: itemId`, `include_metadata: true`, `convert_to_markdown: false`
+   (evita o custo de converter body quando só queremos version)
+2. Retornar `String(page.version.number)`
+
+**Nota**: se o MCP oferecer um `confluence_get_page_history` mais barato no
+futuro, trocar. Hoje `get_page` é o caminho mais direto. Custo: ~1 request HTTP.
+
+---
+
+### `create(parentId, title, content) → { itemId, version }`
+
+**MCP**: `mcp__atlassian__confluence_create_page`
+
+**Passos**:
+1. Chamar tool com:
+   - `space_key: config.space_key`
+   - `parent_id: parentId`
+   - `title: title` (já vem formatado pelo naming engine — ex: `"app_barbearia - TRD"`)
+   - `content: content` (markdown — MCP converte pra storage format)
+   - `content_format: "markdown"`
+2. Retornar:
+   - `itemId` = `response.page.id`
+   - `version` = `String(response.page.version.number)` (tipicamente `"1"`)
+
+**Erros específicos**:
+- `BadRequestException: A page already exists with the same TITLE in this space` →
+  `ConflictError { kind: "duplicate_title", itemId: null }`
+  (naming templating com `{scope}` no título deveria impedir isso — se bateu,
+  dois scopes têm o mesmo nome, o user precisa renomear no Input)
+- `parent_id` inválido → `NotFoundError { kind: "container", itemId: parentId }`
+
+---
+
+### `update(itemId, content, expectedVersion) → { version, ok, conflict? }`
+
+**MCP**: `mcp__atlassian__confluence_update_page` (+ `get_page` pra version check)
+
+> **Atenção crítica**: o MCP sooperset **não** aceita `expectedVersion` como
+> parâmetro. Isso significa **zero optimistic locking server-side**. Toda a
+> conflict detection é client-side — responsabilidade deste adapter.
+
+**Passos**:
+1. Chamar `getVersion(itemId)` → `currentVersion`
+   - Se o item sumiu → `NotFoundError`
+2. Comparar `currentVersion !== expectedVersion`:
+   - **Se diverge** → retornar `{ version: currentVersion, ok: false, conflict: true }`
+     (sem chamar `update_page` — não sobrescreve drift)
+3. Se bate, chamar `confluence_update_page` com:
+   - `page_id: itemId`
+   - `title: <mesmo título atual>` (pegar do `get_page` anterior se não vier em cache)
+   - `content: content`
+   - `content_format: "markdown"`
+   - `version_comment: "sfw: auto-publish"` (opcional mas recomendado pra histórico Confluence)
+4. Retornar `{ version: String(response.page.version.number), ok: true }`
+
+**Race window**: há uma pequena janela entre o `getVersion` e o `update_page`
+onde outra pessoa pode ter editado. MVP aceita — o caso é raro e o próximo
+`getVersion`/`update` no ciclo detecta. Se virar dor, documentar como
+limitação conhecida.
+
+**Erros específicos**:
+- `version_drift` detectado no passo 2 → retorno `{ ok: false, conflict: true }`
+  (não lança erro — é caminho normal do contrato)
+- Qualquer outro erro → embrulhar conforme `errors.md`
+
+---
+
+### `attachFile?(itemId, filename, content, mimeType)`
+
+**MCP**: `mcp__atlassian__confluence_upload_attachment` (ou `upload_attachments` batch)
+
+**Passos**:
+1. Chamar tool com `page_id: itemId`, `filename`, `content` (bytes), `mime_type`
+2. Não retorna valor — sucesso é ausência de erro
+
+**Implementação opcional no MVP**: ativar se/quando o `/publish` precisar
+anexar diagramas, planilhas, etc. Por padrão, não chamado.
+
+---
+
+## Constraints descobertos (aprendizado do teste E2E)
+
+1. **Title uniqueness por SPACE inteiro** — não por parent.
+   **Premissa**: 1 space = 1 projeto. Multi-projeto no mesmo space causa
+   colisão se dois scopes tiverem o mesmo nome.
+   **Mitigação**: user nomeia items no Input com nomes únicos; naming
+   templating com `{scope}` no `output_artifact` garante unicidade no Output.
+
+2. **Markdown roundtrip é lossy** — `#` vira `===`, `-` vira `*`, emojis
+   podem normalizar. **Consequência**: nunca usar diff de bytes pra detectar
+   drift. `version.number` é a única fonte de verdade.
+
+3. **`.mcp.json` com `${VAR}` não funciona** no startup do Claude Code.
+   Credenciais precisam estar hardcoded no arquivo (gitignored). Mudanças
+   exigem reiniciar Claude Code — servers MCP só sobem no startup.
+
+4. **`page_id` é chave estável** — renomeação preserva ID, history, children.
+   Skills persistem ID em logs, não título.
+
+5. **`recursive: true` no `get_page_children`** não é suportado pelo MCP
+   atual — adapter precisa fazer recursão manual (loop + stack) quando
+   `config.recursive === true`.
+
+6. **Paginação**: `get_page_children` retorna `limit` default 25. Caller
+   deve iterar via `start` ou cursor pra esgotar filhos — não assumir
+   que primeira página é tudo.
+
+---
+
+## Checklist de pré-requisitos (documentar no bootstrap do kit)
+
+Antes de usar este adapter, usuário precisa:
+
+- [ ] `uvx` instalado (ou `pipx`/`pip`)
+- [ ] `.mcp.json` na raiz do projeto com entrada pro `sooperset/mcp-atlassian`
+      + credenciais hardcoded (NUNCA commitar — está no `.gitignore` do kit)
+- [ ] Token Atlassian com scope de leitura + escrita no space alvo
+- [ ] `space_key` descoberto (ex: via `confluence_search` ou URL do Confluence)
+- [ ] Página raiz do projeto criada (manualmente ou via `/new-project`)
+- [ ] Claude Code reiniciado após qualquer mudança no `.mcp.json`
+
+Bootstrap do kit (§9.9.P0.3) automatiza isso.
+
+---
+
+## Matriz de erros Confluence → tipos do SFW
+
+| Situação Confluence | Tipo lançado | Detalhes |
+|---|---|---|
+| 401 / token inválido | `AuthError` | `hint`: "verifique token em .mcp.json" |
+| 403 / sem permissão | `AuthError` | `hint`: "usuário sem acesso ao space {space_key}" |
+| 404 page_id | `NotFoundError` | `kind: "item"` |
+| 404 parent_id | `NotFoundError` | `kind: "container"` |
+| `BadRequestException` title duplicado | `ConflictError` | `kind: "duplicate_title"` |
+| 5xx Confluence down | `TransportError` | `retryable: true` |
+| MCP server não responde | `TransportError` | `retryable: true`, `hint`: "reinicie Claude Code" |
+| Timeout | `TransportError` | `retryable: true` |
+| Attachment muito grande | `TransportError` | `retryable: false`, `hint`: tamanho máx Confluence |
+
+---
+
+## Referências
+
+- Interface: `.github/adapters/interface.md`
+- Erros: `.github/adapters/errors.md`
+- Naming: `.github/adapters/naming.md`
+- Registry: `.github/adapters/registry.md`
+- Validação E2E: `planodetarefas.md §9.9` + napkin "Estado do Confluence MCP"
+- MCP provider: [sooperset/mcp-atlassian](https://github.com/sooperset/mcp-atlassian)

package/templates/.github/adapters/errors.md

@@ -0,0 +1,234 @@
+# SourceAdapter — Contrato de Erros
+
+> Classes de erro tipadas que qualquer adapter **deve** lançar em vez de
+> `throw new Error(...)`. As skills (`/load`, `/publish`, `/new-project`,
+> `/extract`, `/design`, `/plan`) fazem `catch` tipado e decidem o que fazer.
+>
+> Arquivo é referência conceitual, não runtime. A implementação real vive no
+> adapter específico (`.github/adapters/confluence.md` etc.).
+
+---
+
+## Por que erros tipados
+
+1. **Skills reagem diferente por categoria.** Um `ConflictError` é recuperável
+   (pede ao usuário), um `AuthError` é fatal (para tudo e orienta setup).
+   Genérico obriga a parsear mensagem — frágil.
+2. **Logs ficam úteis.** `.ai/load-log.md` e `.ai/publish-log.md` registram
+   o tipo do erro, não a mensagem livre. Re-execução pode filtrar por tipo.
+3. **Testes ficam honestos.** FilesystemAdapter (mock natural) lança os mesmos
+   tipos — skills testadas contra ele ganham cobertura real.
+
+---
+
+## Hierarquia
+
+```
+SourceAdapterError                  (base — nunca lançado direto)
+├── ValidationError                 (config do sfw.config.yml inválido)
+├── AuthError                       (credenciais inválidas ou ausentes)
+├── NotFoundError                   (itemId / containerId inexistente)
+├── ConflictError                   (version drift, título duplicado)
+├── TransportError                  (rede, MCP down, timeout)
+└── NotImplementedError             (método opcional não implementado)
+```
+
+Todos os erros **devem** carregar:
+- `name` — nome da classe (ex: `"ConflictError"`)
+- `adapter` — nome do adapter que lançou (ex: `"confluence"`)
+- `operation` — método que falhou (ex: `"update"`)
+- `message` — descrição humana
+- `cause` opcional — erro original (MCP, fs, fetch) pra debug
+
+---
+
+## Catálogo completo
+
+### `ValidationError`
+
+**Quando**: `validateConfig(config)` detecta campo ausente, tipo errado, ou
+combinação inválida (ex: `mode: auto` sem `approval_mechanism` quando o target
+requer aprovação).
+
+**Campos extras**:
+- `field` — caminho do campo inválido (ex: `"output.targets[0].publishes"`)
+- `expected` — o que era esperado
+- `got` — o que veio
+
+**Como o caller reage**: para imediatamente. Nunca é recuperável em runtime —
+o usuário precisa arrumar o `sfw.config.yml` e re-rodar.
+
+**Exemplo**:
+```
+ValidationError em confluence.validateConfig:
+  field: input.config.space_key
+  expected: string não-vazio
+  got: undefined
+  message: space_key obrigatório pro ConfluenceAdapter
+```
+
+---
+
+### `AuthError`
+
+**Quando**: backend rejeita credenciais (401, 403, token expirado, MCP retorna
+auth failure). Também lançado se credenciais nem foram encontradas (`.mcp.json`
+ausente, env var não setada).
+
+**Campos extras**:
+- `hint` opcional — pista acionável (ex: `"verifique CONFLUENCE_TOKEN em .mcp.json"`)
+
+**Como o caller reage**: para imediatamente. Mostra `hint` pro usuário. Nunca
+tenta retry — credenciais não se consertam sozinhas.
+
+**Importante**: adapters nunca devem vazar o token no `message` ou `cause`.
+Se o erro original tem o token no URL, o adapter faz sanitize antes de embrulhar.
+
+---
+
+### `NotFoundError`
+
+**Quando**: operação aponta pra um `itemId` / `containerId` que não existe ou
+foi deletado. Inclui: `fetchContent`, `getVersion`, `update`, `listChildren`,
+`fetchAttachments` em um ID inválido.
+
+**Campos extras**:
+- `itemId` — o ID que não foi encontrado
+- `kind` — `"container"` | `"item"` | `"attachment"`
+
+**Como o caller reage**:
+- `/load`: pode ser scope removido no backend. Loga e pula (não fatal).
+- `/publish`: se título existia no publish-log mas sumiu do backend → o caller
+  DEVE chamar `create` em vez de `update` (fallback implícito).
+- `/new-project`: se parent root não existe → fatal (config errada).
+
+---
+
+### `ConflictError`
+
+**Quando**:
+- `create` encontra título duplicado no parent (ou no space, no Confluence).
+- `update` detecta `expectedVersion != version atual` (drift — alguém editou
+  entre o último `getVersion` e o `update`).
+
+**Campos extras**:
+- `expectedVersion` — o que o caller achava que estava lá
+- `actualVersion` — o que o backend tem de fato
+- `itemId` — item que conflitou
+- `kind` — `"duplicate_title"` | `"version_drift"`
+
+**Como o caller reage**:
+- `duplicate_title` (no `create`): normalmente fatal em MVP — skills assumem
+  naming unique via template com `{scope}` no título. Se bateu, dois
+  scopes têm o mesmo nome — o user precisa renomear no Input.
+- `version_drift` (no `update`): **recuperável**. Fluxo:
+  1. `/publish` para a operação atual
+  2. Baixa content remoto via `fetchContent`
+  3. Gera diff local-vs-remoto
+  4. Pergunta ao usuário: **sobrescrever, abortar, ou fazer merge manual**
+  5. Se sobrescrever → novo `update` com `expectedVersion` atualizada
+
+**Nunca retry automático** — drift é sinal de que um humano tocou o artefato
+(aprovação manual, edição pós-review). Requer decisão consciente.
+
+---
+
+### `TransportError`
+
+**Quando**: rede caiu, MCP morreu, timeout, 5xx do backend.
+
+**Campos extras**:
+- `retryable` — `true` se faz sentido tentar de novo (5xx, timeout)
+- `statusCode` opcional — se o backend deu HTTP
+
+**Como o caller reage**:
+- `retryable=true`: retry com backoff (proposta: 3 tentativas, 1s / 3s / 10s).
+  Depois disso, escala pro usuário.
+- `retryable=false`: escala imediato.
+
+**Importante**: distinguir `TransportError` de `AuthError` é crítico — 401 **não**
+é transport, é auth. Adapter precisa classificar antes de embrulhar.
+
+---
+
+### `NotImplementedError`
+
+**Quando**: skill chama método opcional (`attachFile`) num adapter que não
+implementa.
+
+**Como o caller reage**: skill **deve** ter fallback ou skipar feature. Nunca
+é fatal — é esperado em MVP (FilesystemAdapter sem attachments na v0, por ex).
+
+Caller típico:
+```
+try {
+  await adapter.attachFile(id, name, buf, mime);
+} catch (e) {
+  if (e instanceof NotImplementedError) {
+    log("adapter ${adapter.name} não suporta attachments, pulando");
+    return;
+  }
+  throw e;
+}
+```
+
+---
+
+## Quem lança o quê (matriz)
+
+| Método | ValidationError | AuthError | NotFoundError | ConflictError | TransportError | NotImplementedError |
+|--------|:---:|:---:|:---:|:---:|:---:|:---:|
+| `validateConfig` | ✅ | — | — | — | — | — |
+| `listChildren` | — | ✅ | ✅ | — | ✅ | — |
+| `fetchContent` | — | ✅ | ✅ | — | ✅ | — |
+| `fetchAttachments` | — | ✅ | ✅ | — | ✅ | — |
+| `getVersion` | — | ✅ | ✅ | — | ✅ | — |
+| `create` | — | ✅ | ✅¹ | ✅² | ✅ | — |
+| `update` | — | ✅ | ✅ | ✅³ | ✅ | — |
+| `attachFile` | — | ✅ | ✅ | — | ✅ | ✅⁴ |
+
+**Notas**:
+- ¹ `NotFoundError` no `create` quando o `parentId` não existe.
+- ² `ConflictError` no `create` = `kind: "duplicate_title"`.
+- ³ `ConflictError` no `update` = `kind: "version_drift"`.
+- ⁴ `NotImplementedError` apenas em adapters que não suportam attachments.
+
+---
+
+## Padrão de implementação (pseudo-código)
+
+Todo adapter embrulha erros nativos nesses tipos. Exemplo genérico:
+
+```typescript
+async update(itemId, content, expectedVersion) {
+  try {
+    const current = await this.getVersion(itemId);
+    if (current !== expectedVersion) {
+      throw new ConflictError({
+        adapter: this.name,
+        operation: "update",
+        kind: "version_drift",
+        itemId,
+        expectedVersion,
+        actualVersion: current,
+      });
+    }
+    const result = await this.backendUpdate(itemId, content);
+    return { version: result.version, ok: true };
+  } catch (e) {
+    if (e instanceof ConflictError) throw e;
+    if (isNotFound(e))  throw new NotFoundError({ adapter: this.name, operation: "update", itemId, kind: "item", cause: e });
+    if (isAuth(e))      throw new AuthError(    { adapter: this.name, operation: "update", cause: e });
+    if (isTransport(e)) throw new TransportError({ adapter: this.name, operation: "update", retryable: e.status >= 500, cause: e });
+    throw e; // unknown — propaga cru
+  }
+}
+```
+
+---
+
+## Referências
+
+- Interface: `.github/adapters/interface.md`
+- Registry: `.github/adapters/registry.md`
+- Naming: `.github/adapters/naming.md`