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

package/templates/.github/adapters/registry.md

@@ -1,244 +1,244 @@
-# Adapter Registry
-
-> Como o SFW resolve `adapter: "confluence"` no `sfw.config.yml` pra uma
-> instância concreta de `SourceAdapter`.
->
-> Este arquivo é a **especificação** do registry. A implementação real vive
-> no bootstrap do kit (quando for codada — §9.9.P0.2+).
-
----
-
-## Conceito
-
-O usuário declara no manifest:
-
-```yaml
-input:
-  adapter: confluence
-  config:
-    space_key: ST
-    parent_page_id: "360668"
-```
-
-As skills **nunca** veem a string `"confluence"`. Elas recebem uma instância
-que implementa `SourceAdapter` — já configurada, já validada. O registry é
-a ponte entre os dois.
-
----
-
-## Responsabilidades do registry
-
-1. **Descobrir adapters disponíveis** (builtin + futuros plugins)
-2. **Resolver** a string `adapter: X` na classe correta
-3. **Instanciar** o adapter passando o objeto `config` do manifest
-4. **Validar** chamando `adapter.validateConfig(config)` antes de devolver
-5. **Falhar cedo e rápido** se o adapter não existe ou config está errado
-
----
-
-## Adapters built-in no MVP
-
-| Chave no YAML | Classe | Arquivo de runbook | Status MVP |
-|---------------|--------|-------------------|------------|
-| `confluence` | `ConfluenceAdapter` | `.github/adapters/confluence.md` | P0.2 — reuso do validado em testes/barbearia |
-| `filesystem` | `FilesystemAdapter` | `.github/adapters/filesystem.md` | P0.2 — novo, trivial |
-
-**Apenas esses 2 no MVP.** Qualquer outro valor em `adapter:` → `ValidationError`
-no load do manifest.
-
----
-
-## Fluxo de resolução
-
-```
-1. Skill começa (ex: /sf-load)
-2. Carrega sfw.config.yml
-3. Para cada seção que precisa de adapter (input, cada output.target):
-   a. Lê string `adapter: X`
-   b. Consulta registry: registry.get("X")
-      - Se X não existe → ValidationError: "unknown adapter 'X' (available: confluence, filesystem)"
-   c. Instancia: const a = new AdapterClass()
-   d. Valida config: a.validateConfig(target.config)
-      - Se inválido → ValidationError (propaga do adapter)
-   e. Armazena a instância configurada em memória pra reuso durante a skill
-4. Usa as instâncias via interface — nunca chama .name direto no hot path
-```
-
-**Importante**: o registry é consultado **1 vez** por execução de skill.
-Instâncias são cached pela duração da skill. Skills que rodam em sequência
-(`/sf-extract` → `/sf-design`) podem re-instanciar — não há estado compartilhado
-entre execuções (não deveria haver, por contrato).
-
----
-
-## Contrato textual do registry
-
-```typescript
-interface AdapterRegistry {
-  /**
-   * Retorna a classe do adapter (não instancia).
-   * @throws ValidationError se a chave não existir
-   */
-  get(key: string): AdapterClass;
-
-  /**
-   * Lista as chaves disponíveis. Usado em mensagens de erro.
-   */
-  available(): string[];
-
-  /**
-   * Registra um novo adapter. No MVP só é chamado internamente pros 2 builtin.
-   * Plugin system (P2) usaria isso pra carregar adapters externos.
-   */
-  register(key: string, cls: AdapterClass): void;
-}
-
-interface AdapterClass {
-  new(): SourceAdapter;
-  /** Chave que o adapter usa no YAML — deve bater com o que está no registry */
-  readonly adapterName: string;
-}
-```
-
-### Inicialização builtin (pseudo-código)
-
-```typescript
-const registry = new AdapterRegistry();
-registry.register("confluence", ConfluenceAdapter);
-registry.register("filesystem", FilesystemAdapter);
-
-// quando o manifest é carregado:
-function resolveAdapter(section: { adapter: string; config: object }): SourceAdapter {
-  const cls = registry.get(section.adapter);   // throws se não existe
-  const instance = new cls();
-  instance.validateConfig(section.config);     // throws se config errada
-  return instance;
-}
-```
-
----
-
-## Declaração de config requerida (contrato por adapter)
-
-Cada adapter **documenta** (em `.github/adapters/{name}.md`) quais campos
-são obrigatórios e quais são opcionais na seção `config`. O registry não
-valida isso — delega pro `validateConfig` do adapter. Isso evita duplicação
-e mantém a responsabilidade localizada.
-
-**Exemplo — ConfluenceAdapter**:
-| Campo | Obrigatório | Tipo | Descrição |
-|-------|:---:|------|-----------|
-| `space_key` | ✅ | string | ex: `"ST"` |
-| `parent_page_id` | ✅ | string | ID numérico da page pai |
-| `recursive` | — | boolean | default `true` |
-| `include_attachments` | — | boolean | default `true` |
-
-**Exemplo — FilesystemAdapter**:
-| Campo | Obrigatório | Tipo | Descrição |
-|-------|:---:|------|-----------|
-| `root_path` | ✅ | string | path absoluto ou relativo ao projeto |
-| `glob` | — | string | default `**/*.md` |
-| `watch` | — | boolean | default `false` (watch mode é P2) |
-
----
-
-## Ordem de validação no load do manifest
-
-Quando skill chama `loadConfig("sfw.config.yml")`:
-
-1. **Parse YAML.** Erro de sintaxe → `ValidationError` (nem chama registry).
-2. **Valida shape top-level.** Presença de `project`, `naming`, `input`, `output.targets[]`.
-3. **Resolve `input.adapter`** via registry + `validateConfig` do adapter.
-4. **Resolve cada `output.targets[i].adapter`** via registry + `validateConfig`.
-5. **Valida `naming.*`** — templates precisam ser strings não-vazias; placeholders
-   desconhecidos detectados agora (antecipa erro de runtime).
-6. **Valida coerência inter-seções**: ex., `output.targets[i].mode: auto` exige
-   `approval_mechanism` presente quando `publishes` contém PRD/SDD (artefatos
-   com gate de aprovação).
-
-Tudo no load. Se qualquer passo falha, skill para antes de tocar backend.
-
----
-
-## Config de exemplo resolvida
-
-Input YAML:
-```yaml
-project:
-  name: "Barbearia"
-input:
-  adapter: confluence
-  config:
-    space_key: ST
-    parent_page_id: "360668"
-output:
-  targets:
-    - name: confluence-mirror
-      adapter: confluence
-      config:
-        space_key: ST
-        parent_page_id: "294931"
-      publishes: [PRD, TRD, Progresso]
-      mode: auto
-    - name: local-mirror
-      adapter: filesystem
-      config:
-        root_path: "./mirror"
-      publishes: [PRD, TRD, Progresso]
-      mode: auto
-```
-
-Após load:
-```typescript
-const manifest = {
-  project: { name: "Barbearia" },
-  input: <ConfluenceAdapter instance, configured>,
-  outputs: [
-    { name: "confluence-mirror", adapter: <ConfluenceAdapter>, publishes: [...], mode: "auto" },
-    { name: "local-mirror",      adapter: <FilesystemAdapter>,  publishes: [...], mode: "auto" },
-  ],
-};
-```
-
-Skill chama `manifest.input.listChildren(...)` e `manifest.outputs[0].adapter.update(...)`.
-A string `"confluence"` nunca aparece fora do registry.
-
----
-
-## O que NÃO é responsabilidade do registry
-
-- **Credenciais.** Adapter lê `.mcp.json` / env var direto. Registry nem vê.
-- **Retry/backoff.** Cada adapter implementa. Registry devolve instância "crua".
-- **Logging.** Skills logam. Adapter/registry silenciam (exceto em erro).
-- **Connection pooling.** MVP é single-process single-skill. Se virar batch,
-  registry pode cachear. Não agora.
-
----
-
-## Futuro (P2) — Plugin system
-
-Quando aparecer o 3º caso real de backend não-builtin:
-
-1. `sfw.config.yml` ganha seção `plugins:`:
-   ```yaml
-   plugins:
-     - npm:@sfw/notion-adapter@1.2.0
-     - file:./local-adapters/sharepoint.js
-   ```
-2. Bootstrap do kit carrega plugins antes do manifest.
-3. Cada plugin exporta `{ key, class }` e chama `registry.register(...)`.
-4. Interface do adapter fica estável (breaking change vira major version).
-
-**Decisão (2026-04-11)**: não implementar agora. Builtin resolve 95% dos casos
-e prova que a interface está certa. Plugin system vira prioridade quando um
-usuário real pedir.
-
----
-
-## Referências
-
-- Interface: `.github/adapters/interface.md`
-- Erros: `.github/adapters/errors.md`
-- Naming: `.github/adapters/naming.md`
-- Manifest: `sfw.config.yml.example`
-- Roadmap: `planodetarefas.md §9.9.P0.2` (implementação dos builtins)
+# Adapter Registry
+
+> Como o SFW resolve `adapter: "confluence"` no `sfw.config.yml` pra uma
+> instância concreta de `SourceAdapter`.
+>
+> Este arquivo é a **especificação** do registry. A implementação real vive
+> no bootstrap do kit (quando for codada — §9.9.P0.2+).
+
+---
+
+## Conceito
+
+O usuário declara no manifest:
+
+```yaml
+input:
+  adapter: confluence
+  config:
+    space_key: ST
+    parent_page_id: "360668"
+```
+
+As skills **nunca** veem a string `"confluence"`. Elas recebem uma instância
+que implementa `SourceAdapter` — já configurada, já validada. O registry é
+a ponte entre os dois.
+
+---
+
+## Responsabilidades do registry
+
+1. **Descobrir adapters disponíveis** (builtin + futuros plugins)
+2. **Resolver** a string `adapter: X` na classe correta
+3. **Instanciar** o adapter passando o objeto `config` do manifest
+4. **Validar** chamando `adapter.validateConfig(config)` antes de devolver
+5. **Falhar cedo e rápido** se o adapter não existe ou config está errado
+
+---
+
+## Adapters built-in no MVP
+
+| Chave no YAML | Classe | Arquivo de runbook | Status MVP |
+|---------------|--------|-------------------|------------|
+| `confluence` | `ConfluenceAdapter` | `.github/adapters/confluence.md` | P0.2 — reuso do validado em testes/barbearia |
+| `filesystem` | `FilesystemAdapter` | `.github/adapters/filesystem.md` | P0.2 — novo, trivial |
+
+**Apenas esses 2 no MVP.** Qualquer outro valor em `adapter:` → `ValidationError`
+no load do manifest.
+
+---
+
+## Fluxo de resolução
+
+```
+1. Skill começa (ex: /sf-load)
+2. Carrega sfw.config.yml
+3. Para cada seção que precisa de adapter (input, cada output.target):
+   a. Lê string `adapter: X`
+   b. Consulta registry: registry.get("X")
+      - Se X não existe → ValidationError: "unknown adapter 'X' (available: confluence, filesystem)"
+   c. Instancia: const a = new AdapterClass()
+   d. Valida config: a.validateConfig(target.config)
+      - Se inválido → ValidationError (propaga do adapter)
+   e. Armazena a instância configurada em memória pra reuso durante a skill
+4. Usa as instâncias via interface — nunca chama .name direto no hot path
+```
+
+**Importante**: o registry é consultado **1 vez** por execução de skill.
+Instâncias são cached pela duração da skill. Skills que rodam em sequência
+(`/sf-extract` → `/sf-design`) podem re-instanciar — não há estado compartilhado
+entre execuções (não deveria haver, por contrato).
+
+---
+
+## Contrato textual do registry
+
+```typescript
+interface AdapterRegistry {
+  /**
+   * Retorna a classe do adapter (não instancia).
+   * @throws ValidationError se a chave não existir
+   */
+  get(key: string): AdapterClass;
+
+  /**
+   * Lista as chaves disponíveis. Usado em mensagens de erro.
+   */
+  available(): string[];
+
+  /**
+   * Registra um novo adapter. No MVP só é chamado internamente pros 2 builtin.
+   * Plugin system (P2) usaria isso pra carregar adapters externos.
+   */
+  register(key: string, cls: AdapterClass): void;
+}
+
+interface AdapterClass {
+  new(): SourceAdapter;
+  /** Chave que o adapter usa no YAML — deve bater com o que está no registry */
+  readonly adapterName: string;
+}
+```
+
+### Inicialização builtin (pseudo-código)
+
+```typescript
+const registry = new AdapterRegistry();
+registry.register("confluence", ConfluenceAdapter);
+registry.register("filesystem", FilesystemAdapter);
+
+// quando o manifest é carregado:
+function resolveAdapter(section: { adapter: string; config: object }): SourceAdapter {
+  const cls = registry.get(section.adapter);   // throws se não existe
+  const instance = new cls();
+  instance.validateConfig(section.config);     // throws se config errada
+  return instance;
+}
+```
+
+---
+
+## Declaração de config requerida (contrato por adapter)
+
+Cada adapter **documenta** (em `.github/adapters/{name}.md`) quais campos
+são obrigatórios e quais são opcionais na seção `config`. O registry não
+valida isso — delega pro `validateConfig` do adapter. Isso evita duplicação
+e mantém a responsabilidade localizada.
+
+**Exemplo — ConfluenceAdapter**:
+| Campo | Obrigatório | Tipo | Descrição |
+|-------|:---:|------|-----------|
+| `space_key` | ✅ | string | ex: `"ST"` |
+| `parent_page_id` | ✅ | string | ID numérico da page pai |
+| `recursive` | — | boolean | default `true` |
+| `include_attachments` | — | boolean | default `true` |
+
+**Exemplo — FilesystemAdapter**:
+| Campo | Obrigatório | Tipo | Descrição |
+|-------|:---:|------|-----------|
+| `root_path` | ✅ | string | path absoluto ou relativo ao projeto |
+| `glob` | — | string | default `**/*.md` |
+| `watch` | — | boolean | default `false` (watch mode é P2) |
+
+---
+
+## Ordem de validação no load do manifest
+
+Quando skill chama `loadConfig("sfw.config.yml")`:
+
+1. **Parse YAML.** Erro de sintaxe → `ValidationError` (nem chama registry).
+2. **Valida shape top-level.** Presença de `project`, `naming`, `input`, `output.targets[]`.
+3. **Resolve `input.adapter`** via registry + `validateConfig` do adapter.
+4. **Resolve cada `output.targets[i].adapter`** via registry + `validateConfig`.
+5. **Valida `naming.*`** — templates precisam ser strings não-vazias; placeholders
+   desconhecidos detectados agora (antecipa erro de runtime).
+6. **Valida coerência inter-seções**: ex., `output.targets[i].mode: auto` exige
+   `approval_mechanism` presente quando `publishes` contém PRD/TRD (artefatos
+   com gate de aprovação).
+
+Tudo no load. Se qualquer passo falha, skill para antes de tocar backend.
+
+---
+
+## Config de exemplo resolvida
+
+Input YAML:
+```yaml
+project:
+  name: "Barbearia"
+input:
+  adapter: confluence
+  config:
+    space_key: ST
+    parent_page_id: "360668"
+output:
+  targets:
+    - name: confluence-mirror
+      adapter: confluence
+      config:
+        space_key: ST
+        parent_page_id: "294931"
+      publishes: [PRD, TRD, Progresso]
+      mode: auto
+    - name: local-mirror
+      adapter: filesystem
+      config:
+        root_path: "./mirror"
+      publishes: [PRD, TRD, Progresso]
+      mode: auto
+```
+
+Após load:
+```typescript
+const manifest = {
+  project: { name: "Barbearia" },
+  input: <ConfluenceAdapter instance, configured>,
+  outputs: [
+    { name: "confluence-mirror", adapter: <ConfluenceAdapter>, publishes: [...], mode: "auto" },
+    { name: "local-mirror",      adapter: <FilesystemAdapter>,  publishes: [...], mode: "auto" },
+  ],
+};
+```
+
+Skill chama `manifest.input.listChildren(...)` e `manifest.outputs[0].adapter.update(...)`.
+A string `"confluence"` nunca aparece fora do registry.
+
+---
+
+## O que NÃO é responsabilidade do registry
+
+- **Credenciais.** Adapter lê `.mcp.json` / env var direto. Registry nem vê.
+- **Retry/backoff.** Cada adapter implementa. Registry devolve instância "crua".
+- **Logging.** Skills logam. Adapter/registry silenciam (exceto em erro).
+- **Connection pooling.** MVP é single-process single-skill. Se virar batch,
+  registry pode cachear. Não agora.
+
+---
+
+## Futuro (P2) — Plugin system
+
+Quando aparecer o 3º caso real de backend não-builtin:
+
+1. `sfw.config.yml` ganha seção `plugins:`:
+   ```yaml
+   plugins:
+     - npm:@sfw/notion-adapter@1.2.0
+     - file:./local-adapters/sharepoint.js
+   ```
+2. Bootstrap do kit carrega plugins antes do manifest.
+3. Cada plugin exporta `{ key, class }` e chama `registry.register(...)`.
+4. Interface do adapter fica estável (breaking change vira major version).
+
+**Decisão (2026-04-11)**: não implementar agora. Builtin resolve 95% dos casos
+e prova que a interface está certa. Plugin system vira prioridade quando um
+usuário real pedir.
+
+---
+
+## Referências
+
+- Interface: `.github/adapters/interface.md`
+- Erros: `.github/adapters/errors.md`
+- Naming: `.github/adapters/naming.md`
+- Manifest: `sfw.config.yml.example`
+- Roadmap: `planodetarefas.md §9.9.P0.2` (implementação dos builtins)