spec-first-copilot 0.6.0-beta.9 → 0.7.0

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

@@ -1,234 +1,234 @@
-# SourceAdapter — Contrato de Erros
-
-> Classes de erro tipadas que qualquer adapter **deve** lançar em vez de
-> `throw new Error(...)`. As skills (`/sf-load`, `/sf-publish`, `/sf-start`,
-> `/sf-extract`, `/sf-design`, `/sf-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**:
-- `/sf-load`: pode ser scope removido no backend. Loga e pula (não fatal).
-- `/sf-publish`: se título existia no publish-log mas sumiu do backend → o caller
-  DEVE chamar `create` em vez de `update` (fallback implícito).
-- `/sf-start`: 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. `/sf-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`
+# SourceAdapter — Contrato de Erros
+
+> Classes de erro tipadas que qualquer adapter **deve** lançar em vez de
+> `throw new Error(...)`. As skills (`/sf-load`, `/sf-publish`, `/sf-start`,
+> `/sf-extract`, `/sf-design`, `/sf-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**:
+- `/sf-load`: pode ser scope removido no backend. Loga e pula (não fatal).
+- `/sf-publish`: se título existia no publish-log mas sumiu do backend → o caller
+  DEVE chamar `create` em vez de `update` (fallback implícito).
+- `/sf-start`: 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. `/sf-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`