spec-first-copilot 0.7.0-beta.1 → 0.7.0

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

@@ -1,353 +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 - PRD"`). 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 - PRD"` → arquivo `app_barbearia - PRD.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, Progresso]
-      mode: auto
-      conflict_detection: hash
-      approval_mechanism: none
-```
-
-PM edita arquivos direto em `workspace/Input/`. `/sf-load` vira basicamente
-no-op (ou apenas copia pra pasta canônica se `root_path` for diferente).
-`/sf-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, 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 `/sf-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`
+# 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 - PRD"`). 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 - PRD"` → arquivo `app_barbearia - PRD.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, Progresso]
+      mode: auto
+      conflict_detection: hash
+      approval_mechanism: none
+```
+
+PM edita arquivos direto em `workspace/Input/`. `/sf-load` vira basicamente
+no-op (ou apenas copia pra pasta canônica se `root_path` for diferente).
+`/sf-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, 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 `/sf-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`