# Refinement - Roadmap de maturidade do sdd-layer

## Rastreabilidade
- Orquestração: `roadmap-de-maturidade-do-sdd-layer-gate-unico-de-release-corrigir-jest-do-bot-modul-960734c3de8d`
- Stage: refinement
- Estado atual: draft para checkpoint humano.
- Artefato anterior: `04-tasks.md`.
- Artefatos aprovados: `02-prd.md`, `03-techspec.md`.
- Context Pack: `.sdd/intelligence/context-packs/roadmap-de-maturidade-do-sdd-layer-gate-unico-de-release-corrigir-jest-do-bot-modul-960734c3de8d/refinement.md`.
- Risco: `medium`; checkpoint humano obrigatório antes de Execution.

## Resumo
O backlog foi refinado em três ondas para evitar uma implementação grande demais em cima de um worktree já amplo. A primeira onda deve estabilizar a base e tornar o gate reproduzível. A segunda fecha integrações GitHub/Jira, rastreabilidade externa, diagramas e maintenance report. A terceira trata modularização e precisão de contratos depois que os checks já estiverem protegendo o projeto.

A Execution deve começar por T-01 e só avançar para tarefas arquiteturais depois de registrar evidência objetiva dos checks atuais.

## Solução proposta
- Executar T-01 como tracer bullet obrigatório: rodar o baseline real, corrigir falhas pequenas e registrar pendências.
- Fechar o bot GitHub/Jest cedo, porque ele é uma superfície nova e historicamente frágil.
- Implementar o gate strict/release como agregação de checks existentes antes de criar abstrações novas.
- Tratar checks advisory como visibilidade, não bloqueio, no primeiro ciclo.
- Endurecer HTTP externo e webhooks antes de considerar GitHub maduro.
- Usar `maintenance report` como leitura rápida de drift, reutilizando `health_report`.
- Adiar extrações de `src/main.rs` e TUI até existir gate confiável.
- Adicionar golden/property tests depois que os contratos de report, link e diagramas estabilizarem.

## Pontos de observação
- O `traceability-map.yaml` registra `tasks` como `recorded`; o `resolve-input` sugeriu `execution`, mas também manteve `refinement` como `required`. A regra do fluxo prevalece: não iniciar Execution antes deste checkpoint.
- O worktree atual tem mudanças amplas em Rust, bot, docs, clients e TUI. Nenhuma task deve reverter ou reorganizar mudanças não relacionadas.
- `execa` já está mockado em testes novos do bot, mas o import direto em `GitHubProvider` continua sendo risco residual de ESM/Jest/CI.
- `block_gate.rs` já contém GitHub App e paginação GitHub; a task de HTTP deve endurecer essa implementação, não recriá-la do zero.
- Workspace execution multi-provider no TUI usa modos de escrita potencialmente perigosos; readiness e trace são pré-requisitos antes de uso real.
- Checks advisory devem começar como `warn/skipped`; virar bloqueante exige decisão futura e evidência de adoção.

## Checklist
- [ ] T-01 executada antes de qualquer refactor amplo.
- [ ] Falhas atuais classificadas como relacionadas ao roadmap, não relacionadas ou bloqueantes.
- [ ] Bot build/test verde antes de declarar GitHub provider maduro.
- [ ] Gate obrigatório chama comandos reais e preserva exit code.
- [ ] Checks advisory não bloqueiam contributor local no primeiro ciclo.
- [ ] HTTP externo tem timeout, redaction e classificação testados.
- [ ] `artifact link` e `diagram doctor` têm testes antes de entrar no gate completo.
- [ ] TUI provider desconhecido falha antes de mutar workspace.
- [ ] Modularizações ocorrem em PRs/fatias pequenas com testes all-features.
- [ ] Golden/property tests validam estrutura, não copy longa.

## Subtasks

| ID | Origem | Subtask refinada | Estimativa | Dependências | Observações |
|---|---|---|---:|---|---|
| ST-01 | T-01 | Rodar baseline completo possível e registrar matriz pass/warn/fail/skipped | 1.0h | — | Não corrigir ainda; primeiro obter evidência limpa |
| ST-02 | T-01 | Corrigir falhas pequenas de fmt/clippy/test/docs diretamente ligadas ao roadmap | 2.0h | ST-01 | Se abrir refactor amplo, parar e registrar pendência |
| ST-03 | T-04 | Rodar bot build/test e estabilizar mock/adapter de `execa` | 2.0h | ST-01 | Criar `GitShell` somente se mock direto falhar no CI/local |
| ST-04 | T-05 | Completar testes negativos de webhook receiver e validar config/migration GitHub | 1.5h | ST-03 | Sem chamada real ao GitHub |
| ST-05 | T-02 | Implementar modo strict/release inicial em `sdd ci` ou comando equivalente | 3.0h | ST-01, ST-02 | Preferir estender superfície existente |
| ST-06 | T-03 | Adicionar advisory checks com `skipped/warn` e docs | 1.5h | ST-05 | Não bloquear por ferramenta ausente |
| ST-07 | T-06 | Extrair política HTTP testável e aplicar no `block_gate` | 3.0h | ST-01 | Cobrir 401/403/404/429/5xx/timeout |
| ST-08 | T-08 | Cobrir `artifact link` e `diagram doctor` em testes/report/gate quando aplicável | 2.0h | ST-05 | Validar drift de surfaces espelhadas |
| ST-09 | T-07 | Implementar `sdd maintenance report --json` e Markdown | 3.0h | ST-05, ST-08 | Reutilizar `health_report` |
| ST-10 | T-09 | Endurecer readiness/trace de TUI workspace adapters | 2.5h | ST-01 | Provider desconhecido não escreve workspace |
| ST-11 | T-10 | Extrair primeira fatia de `src/main.rs` após gate mínimo | 2.5h | ST-05 | Priorizar artifact ou diagram |
| ST-12 | T-11 | Extrair primeira fatia do TUI após readiness estabilizado | 2.5h | ST-10 | Sem redesenho visual |
| ST-13 | T-12 | Criar corpus golden/property mínimo para artefatos e rastreabilidade | 2.5h | ST-08, ST-09 | Estrutura > copy textual |

### Ondas de entrega
- Onda 1 - Estabilização e gate mínimo: ST-01 a ST-06.
- Onda 2 - Integrações e observabilidade: ST-07 a ST-10.
- Onda 3 - Modularização e precisão: ST-11 a ST-13.

## Definition of Done
- Refinement aprovado explicitamente antes de Execution.
- T-01/ST-01 produz evidência real antes de qualquer mudança maior.
- Cada subtask concluída registra comandos executados, arquivos alterados e riscos restantes.
- Gate strict/release cobre Rust, SDD doctors, bot e docs com contrato reproduzível.
- Advisory checks ficam visíveis sem bloquear por ausência de ferramenta.
- GitHub provider, webhook e `block_gate` têm cobertura de happy path e erros principais.
- TUI multi-provider só escreve workspace quando provider tem adapter explícito e readiness suficiente.
- Modularizações preservam comportamento público e passam all-features.
- Golden/property tests cobrem contratos estruturais de artefatos e rastreabilidade.

## Flags e configurações
- `GITHUB_TOKEN` e `GH_TOKEN`: tokens aceitos para provider/block gate GitHub.
- `github.auth.token_env`: env customizável no config do bot.
- `github.auth.app_id`, `github.auth.installation_id`, `github.auth.private_key_env`, `github.auth.private_key_path`: GitHub App auth.
- `GITHUB_WEBHOOK_SECRET`: segredo padrão do webhook receiver.
- `SDD_GITHUB_WEBHOOK_PORT`: porta opcional do webhook receiver.
- Checks advisory dependem de ferramentas locais: `cargo-audit`, `cargo-deny`, `gitleaks`, `npm audit` e gerador de SBOM escolhido.
- Nenhuma flag deve permitir autoaprovação humana de PRD, Tech Spec ou Refinement; automação deve ser registrada como canal separado quando existir.
