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

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

@@ -1,301 +1,301 @@
-# SourceAdapter — Interface
-
-> Contrato que **todo adapter** (Confluence, Filesystem, Notion, JIRA, …) deve
-> implementar. As skills `/sf-load`, `/sf-publish`, `/sf-start` **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 /sf-load e /sf-start
-  // ------------------------------------------------------------------
-
-  /**
-   * 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 /sf-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 /sf-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 /sf-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ê
-
-```
-/sf-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)
-
-/sf-publish (chamado por /sf-extract, /sf-design, /sf-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 - PRD"
-  ├── 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`
+# SourceAdapter — Interface
+
+> Contrato que **todo adapter** (Confluence, Filesystem, Notion, JIRA, …) deve
+> implementar. As skills `/sf-load`, `/sf-publish`, `/sf-start` **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 /sf-load e /sf-start
+  // ------------------------------------------------------------------
+
+  /**
+   * 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 /sf-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 /sf-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 /sf-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ê
+
+```
+/sf-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)
+
+/sf-publish (chamado por /sf-extract, /sf-design, /sf-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 - PRD"
+  ├── 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`