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

package/templates/.github/adapters/filesystem.md

@@ -0,0 +1,353 @@
+# FilesystemAdapter — Runbook
+
+> Implementação do `SourceAdapter` para diretórios em disco.
+>
+> Serve **dois propósitos**:
+>
+> 1. **Backend real** — times offline, diretório compartilhado em NAS,
+>    workflow 100% local sem Confluence/Notion.
+> 2. **Mock natural pra testes E2E** — configurar `sfw.config.yml` apontando
+>    pra pasta de fixtures e o pipeline rodar inteiro sem mocks manuais.
+>    Ganho colateral citado em §9.9 (napkin): "Zero lib de mock, zero stub".
+>
+> Contrato conceitual: `.github/adapters/interface.md`.
+
+---
+
+## Meta
+
+| Campo | Valor |
+|-------|-------|
+| `name` | `filesystem` |
+| Transporte | Node.js `fs` (ou equivalente na runtime) |
+| Credenciais | Nenhuma — permissões do processo |
+| Conflict detection | Hash-based (sha256 do conteúdo) |
+| Suporta attachments? | ✅ via subpasta `attachments/` por convenção |
+| Suporta busca? | Fora da interface |
+
+---
+
+## Config
+
+Passada via `sfw.config.yml > input.config` ou `output.targets[].config`.
+
+| Campo | Obrig. | Tipo | Descrição |
+|-------|:---:|------|-----------|
+| `root_path` | ✅ | string | Path absoluto ou relativo à raiz do projeto. Ex: `"./mirror"`, `"/srv/shared/sfw"`. |
+| `glob` | — | string | Pattern de arquivos que contam como "content". Default `"**/*.md"`. |
+| `create_if_missing` | — | boolean | Default `true`. Se `false` e `root_path` não existe → `ValidationError`. |
+| `follow_symlinks` | — | boolean | Default `false`. Segurança: evita escape da root via symlinks. |
+
+### `validateConfig`
+
+Lança `ValidationError` se:
+- `root_path` ausente, vazio ou não-string
+- `root_path` não existe e `create_if_missing === false`
+- `glob` presente mas não-string
+- `follow_symlinks` presente mas não-boolean
+
+Resolve `root_path` pra absoluto e armazena (evita ambiguidade entre
+operações subsequentes).
+
+---
+
+## Conceitos
+
+### IDs
+
+`id` de qualquer item é o **path relativo a `root_path`**, sempre com
+separador `/` normalizado. Ex:
+- `root_path = "./mirror"`
+- Arquivo em `./mirror/workspace/Input/app_barbearia/brief.md`
+- `id = "workspace/Input/app_barbearia/brief.md"`
+
+**Por que relativo**: logs ficam portáveis entre máquinas. Dev em Mac e
+CI em Linux podem compartilhar `.ai/publish-log.md` sem precisar reescrever.
+
+### Version = sha256
+
+`getVersion` retorna `sha256(content)` hexadecimal, sem prefixo. Sempre
+calculado sob demanda — nunca cacheado.
+
+**Por que sha256**: detecta qualquer mudança de byte, inclusive alterações
+de whitespace. É o equivalente honesto do `version.number` do Confluence
+quando não há um contador monotônico disponível.
+
+**Trade-off aceito**: mesmo conteúdo em dois arquivos tem a mesma version —
+isso é OK porque `id` (path) é que identifica o item, não version.
+
+### Container vs item
+
+| Estrutura filesystem | `type` do Item |
+|---|---|
+| Diretório qualquer | `folder` |
+| Arquivo que bate com `glob` | `file` |
+| Arquivo que NÃO bate com `glob` | ignorado (não aparece em `listChildren`) |
+| Symlink (se `follow_symlinks: false`) | ignorado |
+
+Não há `"page"` no filesystem — só `folder` e `file`.
+
+### Attachments por convenção
+
+`fetchAttachments(itemId)` procura uma subpasta `attachments/` **irmã** do
+item. Exemplo:
+
+```
+workspace/Input/app_barbearia/
+├── brief.md                 ← item
+└── attachments/             ← lidos como attachments de brief.md
+    ├── diagrama.png
+    └── modelagem.sql
+```
+
+**Regra**: attachments são compartilhados por todos os itens do mesmo
+diretório. Se dois arquivos estão na mesma pasta, ambos "enxergam" os mesmos
+attachments. Simplifica o mental model ("tudo junto na pasta").
+
+---
+
+## Mapeamento da interface → filesystem
+
+### `listChildren(containerId) → Item[]`
+
+**Passos**:
+1. Resolver path: `fullPath = path.join(root_path, containerId)`
+2. Validar que `fullPath` está dentro de `root_path` (prevenção de traversal):
+   - Se `path.relative(root_path, fullPath)` começa com `..` → `ValidationError`
+3. Chamar `fs.readdir(fullPath, { withFileTypes: true })`
+4. Para cada entry:
+   - Ignorar nomes iniciando com `.` (`.git`, `.DS_Store`, etc.)
+   - Ignorar `attachments/` (reservado)
+   - Ignorar symlinks se `follow_symlinks === false`
+   - Ignorar arquivos que não batem com `glob` E que não são diretórios
+5. Montar `Item` pra cada entry válida:
+   - `id` = path relativo normalizado (`/` como separador)
+   - `title` = `entry.name`
+   - `version` = sha256 do conteúdo (arquivo) ou `"dir"` (diretório)
+   - `type` = `"folder"` se dir, `"file"` se arquivo
+   - `hasChildren` = `true` se dir, `false` se file
+6. Retornar array ordenado alfabeticamente por `title`
+
+**Erros**:
+- Path fora da root → `ValidationError`
+- Diretório não existe → `NotFoundError { kind: "container", itemId: containerId }`
+- Sem permissão de leitura → `AuthError { hint: "sem permissão de leitura em {path}" }`
+- EIO/ENOSPC/etc → `TransportError { retryable: false }`
+
+---
+
+### `fetchContent(itemId) → { content, metadata }`
+
+**Passos**:
+1. Resolver path (mesma validação anti-traversal)
+2. `stat` no path:
+   - Se diretório → `ValidationError` (`fetchContent` só funciona em file)
+   - Se não existe → `NotFoundError { kind: "item" }`
+3. `fs.readFile(fullPath, "utf-8")` → `content`
+4. Montar `metadata`:
+   - `version` = sha256(content) hex
+   - `size` = bytes
+   - `mtime` = ISO string do `stat.mtime`
+   - `ctime` = ISO string do `stat.ctime`
+   - `absolute_path` = `fullPath` (útil pra debug)
+5. Retornar `{ content, metadata }`
+
+**Nota**: arquivos não-UTF-8 (binários) deveriam estar em `attachments/`,
+não em `content`. Se o glob pegou um binário por engano, aceitar e deixar o
+caller lidar — não é responsabilidade do adapter filtrar.
+
+---
+
+### `fetchAttachments(itemId) → Attachment[]`
+
+**Passos**:
+1. Resolver path do item
+2. Calcular path da subpasta attachments:
+   - `attachDir = path.join(path.dirname(fullPath), "attachments")`
+3. Se `attachDir` não existe → retornar `[]` (não é erro)
+4. `fs.readdir(attachDir, { withFileTypes: true })`
+5. Pra cada arquivo (ignorar subdirs e hidden):
+   - `stat` pra pegar `size`
+   - Detectar `mimeType` por extensão (mapa simples: `.png → image/png`,
+     `.pdf → application/pdf`, `.sql → text/x-sql`, fallback `application/octet-stream`)
+   - `download()` = closure que chama `fs.readFile(path, null)` → `Buffer`
+6. Retornar array
+
+---
+
+### `getVersion(itemId) → string`
+
+**Passos**:
+1. Resolver path, validar existe e é arquivo
+2. Ler conteúdo (`fs.readFile`)
+3. Retornar `sha256(content)` hex lowercase
+
+**Trade-off**: lê o arquivo inteiro pra calcular hash. Pra MVP é aceitável —
+arquivos de spec/doc são pequenos (KB). Se precisar otimizar, substituir por
+`mtime` em nanosegundos (menos honesto mas mais barato).
+
+---
+
+### `create(parentId, title, content) → { itemId, version }`
+
+**Passos**:
+1. Resolver `parentDir = path.join(root_path, parentId)`, validar anti-traversal
+2. Garantir que `parentDir` existe — se não e `create_if_missing`, criar via `mkdirp`
+3. `fullPath = path.join(parentDir, title)`
+4. Se arquivo já existe → `ConflictError { kind: "duplicate_title", itemId: <novo id relativo> }`
+5. `fs.writeFile(fullPath, content, "utf-8")`
+6. Calcular `version = sha256(content)`
+7. Retornar `{ itemId: <relative path>, version }`
+
+**Convenção sobre `title`**: o caller já aplica `naming.output_artifact`
+(ex: `"app_barbearia - TRD"`). O adapter **adiciona extensão `.md`** se o
+title não já tiver uma — filesystem exige extensão, Confluence não. Esta é a
+assimetria principal entre os 2 adapters.
+
+Exemplo: `title = "app_barbearia - TRD"` → arquivo `app_barbearia - TRD.md`.
+
+---
+
+### `update(itemId, content, expectedVersion) → { version, ok, conflict? }`
+
+**Passos**:
+1. Resolver path, validar existe
+2. Chamar `getVersion(itemId)` → `currentVersion` (sha256 do conteúdo atual)
+3. Se `currentVersion !== expectedVersion`:
+   - Retornar `{ version: currentVersion, ok: false, conflict: true }`
+4. `fs.writeFile(fullPath, content, "utf-8")`
+5. `newVersion = sha256(content)`
+6. Retornar `{ version: newVersion, ok: true }`
+
+**Race window**: igual ao Confluence — pequena janela entre `getVersion` e
+`writeFile`. MVP aceita. Se virar dor, usar `proper-lockfile` ou flock.
+
+---
+
+### `attachFile(itemId, filename, content, mimeType)`
+
+**Passos**:
+1. Resolver path do item, achar diretório pai
+2. `attachDir = path.join(dirname, "attachments")`
+3. `mkdirp(attachDir)` se não existe
+4. `fs.writeFile(path.join(attachDir, filename), content)` (bytes)
+5. `mimeType` é ignorado (filesystem deriva da extensão; metadata não persiste)
+
+**Implementação opcional no MVP** — FilesystemAdapter pode deixar como
+`NotImplementedError` se o caller nunca chamar. Facilita ter-a versão
+inicial.
+
+---
+
+## Casos de uso
+
+### 1. Backend real — time offline
+
+```yaml
+input:
+  adapter: filesystem
+  config:
+    root_path: "./workspace/Input"
+  cache:
+    local_dir: "./workspace/Input"   # input já está local — cache é no-op
+    log: ".ai/load-log.md"
+    incremental: true
+
+output:
+  targets:
+    - name: local
+      adapter: filesystem
+      config:
+        root_path: "./workspace/Output"
+      publishes: [PRD, TRD, SDD, Progresso]
+      mode: auto
+      conflict_detection: hash
+      approval_mechanism: none
+```
+
+PM edita arquivos direto em `workspace/Input/`. `/load` vira basicamente
+no-op (ou apenas copia pra pasta canônica se `root_path` for diferente).
+`/publish` escreve em `workspace/Output/`. Aprovação é off-band (Git PR,
+review manual no arquivo, etc.).
+
+### 2. Mock natural pra testes E2E
+
+```yaml
+input:
+  adapter: filesystem
+  config:
+    root_path: "./tests/fixtures/barbearia/Input"
+
+output:
+  targets:
+    - name: assert
+      adapter: filesystem
+      config:
+        root_path: "./tests/fixtures/barbearia/actual_output"
+      publishes: [PRD, TRD, SDD, Progresso]
+      mode: auto
+```
+
+Teste:
+1. Copia `fixtures/expected_output` pra local
+2. Roda pipeline com este `sfw.config.yml`
+3. `diff fixtures/expected_output fixtures/actual_output` — qualquer
+   divergência = teste falhou
+4. Nenhuma lib de mock envolvida
+
+---
+
+## Segurança — path traversal
+
+**Toda** operação que recebe `id` ou `parentId` do caller DEVE validar:
+
+```typescript
+const resolved = path.resolve(root_path, untrustedId);
+const relative = path.relative(root_path, resolved);
+if (relative.startsWith("..") || path.isAbsolute(relative)) {
+  throw new ValidationError({
+    field: "itemId",
+    message: `path escapa root_path: ${untrustedId}`,
+  });
+}
+```
+
+Sem isso, um adapter malicioso ou config errada pode ler/escrever em
+`/etc/passwd`, `~/.ssh/`, etc.
+
+---
+
+## Matriz de erros fs → tipos do SFW
+
+| errno Node.js | Tipo lançado | Detalhes |
+|---|---|---|
+| `ENOENT` | `NotFoundError` | `kind: "item"` ou `"container"` conforme contexto |
+| `EACCES` / `EPERM` | `AuthError` | `hint`: path sem permissão |
+| `EEXIST` (em `create`) | `ConflictError` | `kind: "duplicate_title"` |
+| `ENOTDIR` (esperava dir, achou arquivo) | `ValidationError` | |
+| `EISDIR` (esperava arquivo, achou dir) | `ValidationError` | |
+| `EIO`, `ENOSPC` | `TransportError` | `retryable: false` |
+| `EMFILE` (too many open files) | `TransportError` | `retryable: true` |
+| Path fora de `root_path` | `ValidationError` | ver seção de segurança acima |
+
+---
+
+## O que NÃO está implementado no MVP
+
+- **Watch mode** (`fs.watch` + eventos) — P2. Caller re-roda `/load` manual.
+- **Locking** (`proper-lockfile`, flock) — P2. Race window aceita.
+- **Compression** — nada. Arquivos crus.
+- **Git integration** — não lê `git status` / `git log`. Se quiser
+  versionamento Git, é outro adapter (`GitAdapter`, P2+).
+- **Binary content em `fetchContent`** — caller deveria usar attachments.
+  Adapter aceita binário mas quebra `sha256` de forma desagradável.
+
+---
+
+## Referências
+
+- Interface: `.github/adapters/interface.md`
+- Erros: `.github/adapters/errors.md`
+- Naming: `.github/adapters/naming.md`
+- Registry: `.github/adapters/registry.md`
+- ConfluenceAdapter (comparação): `.github/adapters/confluence.md`

package/templates/.github/adapters/interface.md

@@ -0,0 +1,301 @@
+# SourceAdapter — Interface
+
+> Contrato que **todo adapter** (Confluence, Filesystem, Notion, JIRA, …) deve
+> implementar. As skills `/load`, `/publish`, `/new-project` **nunca** falam com
+> backends direto — elas falam com essa interface.
+>
+> Este arquivo é **especificação**, não código executável. A implementação real
+> vive em `.github/adapters/confluence.md`, `.github/adapters/filesystem.md`, etc.
+> (arquivos de runbook que o agent segue, no mesmo estilo das skills).
+
+---
+
+## Princípio
+
+> **SFW é sobre processo, não sobre ferramenta.**
+> O pipeline é backend-agnóstico. Times que usam Confluence, Notion, SharePoint,
+> JIRA ou filesystem local plugam um adapter e o resto continua idêntico.
+
+---
+
+## Interface TypeScript (referência)
+
+```typescript
+/**
+ * SourceAdapter — contrato de qualquer backend de I/O usado pelo SFW.
+ *
+ * Todos os métodos são assíncronos (um adapter pode ser rede, disco, MCP).
+ * Erros são tipados — ver .github/adapters/errors.md.
+ */
+interface SourceAdapter {
+  /**
+   * Identificador textual do adapter (ex: "confluence", "filesystem").
+   * Usado pelo registry pra resolver a string em sfw.config.yml.
+   */
+  readonly name: string;
+
+  /**
+   * Valida o objeto de config passado pelo sfw.config.yml.
+   * Chamado 1x no load do manifest, antes de qualquer operação.
+   * Lança ValidationError se config estiver incompleto/incoerente.
+   */
+  validateConfig(config: object): void;
+
+  // ------------------------------------------------------------------
+  // LEITURA — usado por /load e /new-project
+  // ------------------------------------------------------------------
+
+  /**
+   * Lista filhos diretos de um container.
+   *
+   * @param containerId id opaco do container (page, folder, etc.)
+   *                    O formato é adapter-specific — confluence usa page_id
+   *                    numeric, filesystem usa path absoluto ou relativo.
+   * @returns array ordenado (ordem do backend; não há garantia alfabética)
+   */
+  listChildren(containerId: string): Promise<Item[]>;
+
+  /**
+   * Baixa o conteúdo de um item em formato normalizado.
+   *
+   * @returns content em markdown (adapter converte se necessário)
+   *          + metadata livre do backend (pode ser útil pros skills)
+   *
+   * Importante: o adapter é responsável por normalizar pra markdown.
+   * ConfluenceAdapter converte storage format → markdown.
+   * FilesystemAdapter lê .md direto; .txt/.sql/.html também retornam
+   * como markdown (texto cru embrulhado em code fence).
+   */
+  fetchContent(itemId: string): Promise<{
+    content: string;
+    metadata: Record<string, unknown>;
+  }>;
+
+  /**
+   * Lista os attachments de um item (imagens, PDFs, planilhas, etc.).
+   * Retorna metadata + função download() lazy — não baixa bytes a menos
+   * que o skill chame .download() explicitamente.
+   */
+  fetchAttachments(itemId: string): Promise<Attachment[]>;
+
+  /**
+   * Lê a versão atual do item (sem baixar o conteúdo inteiro).
+   * Usado pra conflict detection proativo e pra detectar drift.
+   *
+   * Cada adapter decide o que é "version":
+   *   - Confluence: integer monotônico (ex: "7")
+   *   - Filesystem: sha256 do conteúdo
+   *   - Git: commit hash
+   *
+   * A interface só exige que strings possam ser comparadas por igualdade.
+   */
+  getVersion(itemId: string): Promise<string>;
+
+  // ------------------------------------------------------------------
+  // ESCRITA — usado por /publish
+  // ------------------------------------------------------------------
+
+  /**
+   * Cria um novo item sob um parent.
+   *
+   * @throws ConflictError se já existe item com o mesmo título no parent
+   *                       (ou no espaço, no caso do Confluence — title uniqueness
+   *                       é responsabilidade do caller via naming templates)
+   * @returns itemId do novo item + version inicial
+   */
+  create(
+    parentId: string,
+    title: string,
+    content: string,
+  ): Promise<{ itemId: string; version: string }>;
+
+  /**
+   * Atualiza conteúdo de um item existente com conflict detection.
+   *
+   * @param expectedVersion versão que o caller acredita estar lá.
+   *                        Se o adapter não suporta optimistic lock server-side
+   *                        (ex: Confluence MCP atual), ele faz check client-side:
+   *                        1. chama getVersion(itemId)
+   *                        2. se != expectedVersion → retorna { ok: false, conflict: true }
+   *                        3. caso contrário, faz o update
+   * @returns ok=true + nova version, ou ok=false + conflict=true (drift detectado)
+   *
+   * Nunca sobrescreve cegamente — o caller DEVE tratar conflict=true
+   * (re-lendo, fazendo merge, pedindo confirmação, etc.).
+   */
+  update(
+    itemId: string,
+    content: string,
+    expectedVersion: string,
+  ): Promise<{ version: string; ok: boolean; conflict?: boolean }>;
+
+  /**
+   * Anexa um arquivo binário a um item.
+   * Opcional — adapters que não suportam attachments lançam NotImplementedError.
+   */
+  attachFile?(
+    itemId: string,
+    filename: string,
+    content: Buffer,
+    mimeType: string,
+  ): Promise<void>;
+}
+```
+
+---
+
+## Tipos auxiliares
+
+```typescript
+/**
+ * Representa qualquer "nó" na hierarquia do backend.
+ * Um Item pode ser uma page do Confluence, um arquivo do filesystem,
+ * uma issue do JIRA, uma doc do Notion, etc.
+ */
+interface Item {
+  /**
+   * ID opaco, adapter-specific. Nunca é interpretado pelas skills.
+   * O caller usa como chave em logs e em chamadas subsequentes.
+   */
+  id: string;
+
+  /**
+   * Título exibido ao usuário. Para filesystem = nome do arquivo.
+   * Para Confluence = page title.
+   */
+  title: string;
+
+  /**
+   * Versão atual. Mesma semântica do getVersion().
+   */
+  version: string;
+
+  /**
+   * Tipo estrutural. Permite ao /load decidir se desce recursivamente
+   * (page/folder) ou se baixa conteúdo (file).
+   */
+  type: "page" | "folder" | "file";
+
+  /**
+   * true se o item pode ter filhos (otimização pra /load não chamar
+   * listChildren desnecessariamente em nós folha).
+   */
+  hasChildren: boolean;
+}
+
+/**
+ * Metadata de attachment. download() é lazy — só baixa bytes quando chamado.
+ */
+interface Attachment {
+  filename: string;
+  size: number;           // bytes
+  mimeType: string;       // ex: "image/png", "application/pdf"
+  download(): Promise<Buffer>;
+}
+```
+
+---
+
+## Semântica de version — tabela por adapter
+
+| Adapter | Fonte de version | Exemplo | Monotônico? | Conflict detection |
+|---------|------------------|---------|-------------|--------------------|
+| **Confluence** | `version.number` da page | `"7"` | Sim (inteiro++) | Client-side (MCP não aceita `expectedVersion`) |
+| **Filesystem** | `sha256(content)` | `"a3f5…"` | Não (conteúdo-based) | Re-leitura + compare |
+| **Notion** | `last_edited_time` | `"2026-04-11T14:20:00Z"` | Sim (timestamp) | Client-side |
+| **Git** | `commit hash` onde o arquivo foi tocado | `"9fc3d2e"` | Não (DAG) | `git diff` vs HEAD |
+
+**Regra**: a interface só garante **igualdade**. Skills não fazem aritmética em
+version. Se um adapter quer ordenação (rollback, histórico), expõe em
+`metadata` via `fetchContent`.
+
+---
+
+## Contrato de comportamento (regras invioláveis)
+
+Qualquer adapter **DEVE** garantir:
+
+1. **`update` nunca sobrescreve sem conflict check.**
+   Mesmo backends que não suportam optimistic lock server-side precisam
+   fazer `getVersion` antes do write. É melhor falhar com `conflict: true`
+   do que perder dados do usuário.
+
+2. **IDs são opacos pro pipeline.**
+   O adapter escolhe o formato (page_id numérico, path string, UUID, etc.).
+   Skills persistem o ID em `.ai/load-log.md` / `.ai/publish-log.md` e
+   repassam como string — nunca parseiam.
+
+3. **Content é sempre markdown na saída e na entrada.**
+   Se o backend armazena em outro formato (Confluence storage, Notion blocks),
+   o adapter converte nos 2 sentidos. A normalização é lossy — `getVersion`
+   é a fonte de verdade pra drift, não diff de bytes do markdown.
+
+4. **Erros são tipados.**
+   Nada de `throw new Error("deu ruim")` — usar as classes de
+   `.github/adapters/errors.md`. Skills decidem como reagir via `catch` tipado.
+
+5. **Sem estado global.**
+   Adapter é instanciado com config do manifest e não compartilha estado
+   entre instâncias. Dois projetos rodando lado a lado devem poder usar
+   2 instâncias do mesmo adapter com configs diferentes.
+
+6. **Operações idempotentes quando possível.**
+   `create` com o mesmo título no mesmo parent → `ConflictError` (não cria
+   duplicata). `update` com o mesmo content → ok, nova version igual ou
+   adapter detecta no-op.
+
+---
+
+## Fluxo típico — quem chama o quê
+
+```
+/load {scope}
+  ├── listChildren(input.parent_page_id)        ← lista items no Input
+  ├── busca item por nome == {scope}            ← match exato com o arg da skill
+  ├── listChildren(scope.id)                    ← desce no scope (filhos)
+  ├── fetchContent(scope.id)                    ← conteúdo da página-mãe/arquivo
+  ├── fetchContent(child.id) para cada filho
+  ├── fetchAttachments(scope.id)                ← se include_attachments=true
+  └── (escreve em workspace/Input/{scope}/ localmente)
+
+/publish (chamado por /extract, /design, /plan)
+  ├── applyNaming(output_container, {scope})    ← ex: "out_app_barbearia"
+  ├── listChildren(output.parent_page_id)       ← acha container existente por título
+  ├── se container não existe:
+  │     └── create(output.parent_page_id, containerTitle, seed) → container criado
+  ├── applyNaming(output_artifact, {scope, type}) ← ex: "app_barbearia - TRD"
+  ├── listChildren(container.id)                ← busca artefato por título
+  ├── se artefato não existe:
+  │     └── create(container.id, artifactTitle, content) → log version
+  └── se artefato existe:
+        ├── getVersion(itemId)                  ← lê version atual
+        ├── comparar com publish-log (drift check)
+        ├── se drift → ConflictError pro usuário
+        └── update(itemId, content, expectedVersion) → log nova version
+```
+
+---
+
+## O que NÃO está nesta interface (intencional)
+
+- **Busca full-text.** Se o backend suporta, skills chamam via metadata/config
+  específica do adapter, não pela interface. Aumentaria a superfície sem ganho
+  pro MVP.
+- **Permissions/ACL.** Adapter assume que as credenciais já têm acesso.
+  `AuthError` é o único sinal de permissão negada.
+- **Watching/live updates.** Pull model é suficiente. Push viria depois se
+  houver caso real.
+- **Transactions.** Nenhum backend suportado tem transactions entre itens.
+  Skills são projetadas pra serem idempotentes e re-executáveis.
+- **Attachments bidirecionais no MVP.** `attachFile` é opcional. Só Confluence
+  implementa no MVP. FilesystemAdapter pode implementar trivialmente.
+
+---
+
+## Referências
+
+- Registry + resolução: `.github/adapters/registry.md`
+- Templating de nomes: `.github/adapters/naming.md`
+- Contrato de erros: `.github/adapters/errors.md`
+- Schema do manifest: `sfw.config.yml.example` (raiz do projeto)
+- Decisão arquitetural: `planodetarefas.md §9.9`