# 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.
