# Adapters
Adapters traduzem a pipeline SDD para ferramentas específicas sem mudar o fluxo.
## Regra
O fluxo permanece igual. O adapter só define:
- dono do conteúdo;
- dono do estado;
- identificador canônico;
- evento de entrada;
- evento de saída;
- fallback;
- observabilidade.
## Adapters disponíveis
| Adapter | Arquivo | Uso |
|---|---|---|
| Atlassian | `.sdd/adapters/atlassian.yaml` | Jira, Confluence, Bitbucket, Pipelines, Slack |
| GitHub | `.sdd/adapters/github.yaml` | GitHub Issues, Projects v2, PRs, Actions, Markdown |
| GitLab | `.sdd/adapters/gitlab.yaml` | GitLab Issues, MRs, CI |
| Linear + Notion | `.sdd/adapters/linear-notion.yaml` | Linear para estado, Notion para docs |
| Markdown-only | `.sdd/adapters/markdown-only.yaml` | Repos simples sem suite de produto |
Mesmo com adapters externos, mantenha `docs/<slug-da-orquestracao>/` como fallback mínimo quando `artifact_store.enabled=true`.
## Como escolher
Configure em `sdd.config.yaml`:
```yaml
systems:
work_tracker: github-issues
docs: markdown
repo: github
ci: github-actions
chat: none
```
Depois use `/sdd discover` para confirmar se o adapter reflete a realidade do projeto.
### GitHub completo
Para GitHub, configure `systems.work_tracker: github-issues`, `systems.repo: github` e `systems.ci: github-actions`. O adapter usa:
- Issues e comentários/labels como estado operacional.
- Projects v2 via GraphQL para board/status quando configurado.
- Pull Requests e Actions para Execution/Review.
- `docs/<slug>/traceability-map.yaml` como fonte local e lista `external_links.github` para ponteiros tipados.
Autenticação recomendada: GitHub App com `app_id`, `installation_id` e private key por env/path secreto. Para desenvolvimento interno, use `github.auth.token_env: GITHUB_TOKEN` ou `GH_TOKEN`.
Projects v2 exige duas chamadas: adicionar o item ao projeto e depois atualizar campos. O provider GitHub usa timeout explícito, retry conservador e tratamento de `429`; ajuste `github.request_timeout_ms`, `github.max_attempts` e `github.retry_base_delay_ms` quando o ambiente exigir. O bot expõe receiver HTTP opcional para webhooks GitHub (`webhook.enabled`/`SDD_GITHUB_WEBHOOK_PORT`) com raw body e validação `X-Hub-Signature-256`; eventos de Projects v2 continuam best-effort/public-preview, com fallback por polling ou checkpoint manual.
## Matriz esperada
Ao planejar uma integração, entregue:
| Etapa | Artefato | Sistema dono | Entrada | Saída | Aprovação | Fallback | Observabilidade |
|---|---|---|---|---|---|---|---|
Não use comentário livre como estado. Não duplique PRD/Tech Spec entre sistemas. Grave ponteiros canônicos e mantenha o arquivo local quando a integração externa ainda não estiver confiável.
## Arquivos de adapter
Cada arquivo em `.sdd/adapters/*.yaml` tem:
- `artifacts`: dono de conteúdo, dono de estado e ID canônico por etapa.
- `events`: eventos que acordam a próxima etapa.
- `fallbacks`: caminho quando a ferramenta não emite evento confiável.
- `traceability`: como links externos entram no mapa local.
Durante `/sdd discover`, confira se o adapter selecionado em `sdd.config.yaml` bate com a realidade do projeto.