# PRD - 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: prd
- Estado atual: draft para checkpoint humano
- Artefato anterior: `01-idea.md`
- Artefatos de base: `00-project-discovery.md`, `00-risk-classification.md`
- Context Pack: `.sdd/intelligence/context-packs/roadmap-de-maturidade-do-sdd-layer-gate-unico-de-release-corrigir-jest-do-bot-modul-960734c3de8d/prd.md`
- Decisões relacionadas: runtime-agnostic core, TUI determinística, DDD incremental e orquestrador autônomo documentados em ADRs históricos do repositório.

## Resumo
Este PRD define um programa incremental para aumentar a maturidade de engenharia do `sdd-layer` sem transformar o roadmap em uma reescrita ampla. O foco é tornar release/readiness mais objetivo, estabilizar o bot TypeScript, reduzir acoplamento em módulos centrais, endurecer integrações Jira/GitHub, ampliar a precisão dos contratos SDD e expor uma visão operacional por área via `sdd maintenance report`.

O produto resultante deve preservar o contrato principal do `sdd-layer`: provider-neutralidade, runtime-agnostic core, artifact store local, traceability map, CLI determinístico, docs e client surfaces geradas. Ferramentas opcionais de segurança/supply-chain entram como evidência advisory quando disponíveis, não como bloqueio implícito em ambientes sem essas dependências.

## Objetivos
- Criar um gate único de release que agregue checks Rust, docs, bot, SDD health e contracts multi-client.
- Corrigir a suíte Jest do bot para rodar verde junto com `tsc`.
- Planejar modularização incremental de `src/main.rs` por domínio de comando, sem quebrar call sites existentes.
- Planejar separação incremental da TUI em estado, provider adapters, rendering, execução, persistência e telemetria.
- Adicionar contrato de resiliência para Jira/GitHub: timeout, retry, rate-limit, redaction e mock-server tests.
- Evoluir a precisão com golden tests de artefatos SDD, corpus de PRD/Tech Spec/Tasks, property tests para slug/rastreabilidade e validação semântica determinística.
- Tornar checks opcionais visíveis no CI e no relatório de manutenção.
- Criar `sdd maintenance report` por área: core Rust, docs, clients, bot, providers, intelligence, workflows e release.

## Não objetivos
- Executar todas as refatorações em uma única task.
- Reescrever o CLI em workspace multi-crate sem Tech Spec e ADR dedicadas.
- Tornar Node, bot, MCP, CodeGraph, browser, `cargo audit`, `cargo deny`, `gitleaks` ou SBOM obrigatórios para o funcionamento básico do CLI.
- Remover suporte a providers/clients existentes.
- Mudar decisões já aceitas sobre runtime-agnostic core e artifact store como fonte local de verdade.
- Aprovar merge, release ou deploy automaticamente.

## Usuários
- Mantenedor do `sdd-layer`, que precisa de veredito objetivo de release.
- Reviewers, que precisam saber qual área falhou e qual evidência é obrigatória ou advisory.
- Agentes de execução SDD, que precisam de tasks fatiadas e validação reproduzível.
- Contribuidores do bot/docs/clients, que precisam de CI cobrindo a superfície que alteraram.
- Operadores de integrações Jira/GitHub, que precisam de erros previsíveis e seguros.

## Requisitos

### RF-01 Gate único de release
O sistema deve oferecer um gate consolidado que execute ou orquestre:

- `cargo fmt --check`
- `cargo clippy --all-targets --all-features -- -D warnings`
- `cargo test --locked --all-features`
- `sdd health --json` ou modo strict definido na Tech Spec
- `sdd clients doctor --strict --json`
- `sdd capabilities doctor --targets all --json`
- `sdd skills doctor --strict --json`
- `sdd workflow validate agentic-sdd-loop --json`
- `npm run build` e `npm test` em `bot/`
- `npm run docs:generate -- --check`, `npm run docs:links` e `npm run build` em `docs-site/`

### RF-02 Bot Jest verde
O bot deve rodar `npm test` sem falha de ESM/CommonJS, preservando `npm run build`. A solução pode mockar `execa`, ajustar Jest para ESM ou isolar execução shell atrás de adapter testável, desde que mantenha testes determinísticos.

### RF-03 Modularização de `src/main.rs`
A Tech Spec deve propor uma extração incremental por domínio, com módulos prováveis como `commands/clients`, `commands/workflow`, `commands/providers`, `commands/package`, `commands/ci` e `commands/artifacts`. O `main.rs` pode permanecer composition root, mas deve perder responsabilidades de implementação que já têm fronteira estável.

### RF-04 Modularização da TUI
A Tech Spec deve propor cortes seguros para `src/tui/`, separando estado, provider adapters, rendering, execução, persistência e telemetria. A navegação e os testes existentes devem continuar funcionando durante a migração.

### RF-05 Resiliência Jira/GitHub
Chamadas a Jira/GitHub devem ter timeout explícito, classificação de erro, retry limitado quando seguro, tratamento de rate-limit e redaction em bodies/logs. Testes devem cobrir sucesso, 401/403, 404, 429, 5xx, timeout e body com possível segredo.

### RF-06 Precisão de contratos SDD
O projeto deve adicionar cobertura para regressões de artefatos e rastreabilidade:

- golden tests para PRD, Tech Spec, Tasks, traceability map e reports;
- corpus mínimo de artefatos bons/ruins;
- property tests ou testes gerativos leves para slug, normalização de stage e referências de arquivo;
- validação semântica determinística para seções críticas quando possível.

### RF-07 Checks opcionais visíveis
`cargo audit`, `cargo deny`, `gitleaks`, `npm audit` e SBOM devem aparecer como checks advisory quando disponíveis. Quando ausentes, o output deve registrar `skipped` com ação recomendada, sem quebrar o caminho básico de contributor.

### RF-08 `sdd maintenance report`
O CLI deve expor relatório por área com status, evidências, warnings, riscos e próximos comandos. Áreas mínimas: core Rust, docs, clients, bot, providers, intelligence, workflows e release.

## Critérios de aceite
```gherkin
Funcionalidade: Gate único de release do sdd-layer

  Cenário: Release gate passa quando todas as superfícies obrigatórias estão saudáveis
    Dado que o core Rust, o bot, o docs-site e os doctors SDD estão verdes
    Quando eu executo o gate único de release
    Então o comando finaliza com status de sucesso
    E o relatório lista cada check obrigatório com status "pass"
    E o relatório lista checks opcionais disponíveis como "pass" ou "warn"

  Cenário: Falha obrigatória bloqueia o release
    Dado que `npm test` em `bot/` falha
    Quando eu executo o gate único de release
    Então o comando finaliza com status de falha
    E o relatório indica a área "bot"
    E o relatório preserva o comando que falhou e o próximo passo recomendado

Funcionalidade: Testes do bot compatíveis com dependências ESM

  Cenário: Jest executa provider GitHub sem erro de parsing de execa
    Dado que o bot possui testes para GitHub provider
    Quando eu executo `npm test` em `bot/`
    Então a suíte termina verde
    E nenhum teste falha com "Cannot use import statement outside a module"

Funcionalidade: Modularização incremental do CLI e TUI

  Cenário: Extração preserva comportamento público
    Dado que uma fatia de `src/main.rs` ou `src/tui/runner.rs` foi movida para novo módulo
    Quando eu executo os testes Rust all-features e os doctors SDD
    Então os comandos públicos existentes continuam passando
    E não há mudança não documentada no formato dos artefatos ou outputs JSON

Funcionalidade: Integrações Jira/GitHub resilientes

  Cenário: Rate limit de GitHub é reportado com segurança
    Dado que a API GitHub retorna 429 com body contendo texto sensível
    Quando o gate de bloqueio consulta o último comentário
    Então o erro é classificado como rate-limit
    E o body persistido ou exibido está redigido
    E a operação não fica bloqueada indefinidamente

Funcionalidade: Maintenance report por área

  Cenário: Relatório mostra saúde agregada do projeto
    Dado que há checks obrigatórios, opcionais e intelligence warnings
    Quando eu executo `sdd maintenance report`
    Então vejo áreas para core Rust, docs, clients, bot, providers, intelligence, workflows e release
    E cada área tem status, evidências e próximos comandos
```

## Métricas
- Tempo do gate obrigatório em ambiente local após build cache quente.
- Número de áreas cobertas pelo `maintenance report`.
- Percentual de checks obrigatórios incorporados ao CI.
- Redução de falhas não diagnosticadas em bot/Jest.
- Quantidade de golden/property tests cobrindo artefatos e traceability.
- Número de linhas removidas de `src/main.rs`, `src/tui/runner.rs`, `src/tui/app.rs` e `src/tui/ui.rs` sem perda de comportamento.

## Riscos
- Refactor amplo demais pode conflitar com mudanças locais já em andamento.
- Gate único pode ficar lento e ser ignorado se não separar obrigatório de advisory.
- Checks opcionais podem virar falso bloqueio se ferramentas não estiverem instaladas.
- Modularização da TUI pode quebrar fluxo interativo difícil de cobrir apenas por unit tests.
- Retry mal calibrado em Jira/GitHub pode mascarar erro de autenticação ou piorar rate-limit.
- Golden tests frágeis podem travar evolução legítima dos textos se não focarem contrato.

## Dependências
- `00-project-discovery.md` e Risk calibrado desta orquestração.
- ADRs existentes sobre runtime-agnostic core, TUI determinística, DDD incremental e orquestrador autônomo.
- CodeGraph disponível para mapear impacto antes de refactors.
- CI GitHub Actions atual.
- Package scripts em `bot/package.json` e `docs-site/package.json`.

## Escopo do MVP
O MVP deve entregar as fundações em fatias seguras:

1. Gate único documentado e executável localmente, com CI alinhado.
2. Jest do bot corrigido.
3. `sdd maintenance report` inicial lendo checks existentes, sem inventar nova fonte de verdade.
4. Contrato de resiliência Jira/GitHub com timeout e testes principais.
5. Primeira extração pequena de `src/main.rs` ou TUI, escolhida pela Tech Spec por menor risco.

## Diagramas
```mermaid
flowchart LR
  A["Developer / CI"] --> B["Release gate"]
  B --> C["Core Rust"]
  B --> D["Docs site"]
  B --> E["Bot"]
  B --> F["SDD contracts"]
  B --> G["Optional advisory checks"]
  C --> H["Maintenance report"]
  D --> H
  E --> H
  F --> H
  G --> H
  H --> I["Checkpoint de release"]
```

```mermaid
flowchart TD
  A["Tech Spec"] --> B["Escolher fatias de menor risco"]
  B --> C["Bot/Jest"]
  B --> D["Release gate"]
  B --> E["Maintenance report"]
  B --> F["Provider resilience"]
  B --> G["Modularização incremental"]
  C --> H["Tasks"]
  D --> H
  E --> H
  F --> H
  G --> H
  H --> I["Refinement obrigatório"]
  I --> J["Execution task-by-task"]
```

## Compatibilidade de provider
- Provider/modelo exigido: nenhum.
- Capacidades opcionais usadas: CodeGraph para impacto, CI para validação, mock server para testes de integração.
- Fallback quando ausente: `rg`, leitura focada, testes unitários e artifact store local.
- Evidência persistida: artefatos em `docs/<slug>/`, reports JSON/Markdown e comandos executados.
- Risco residual: diferenças de ambiente podem afetar checks opcionais; devem ser advisory até a Tech Spec definir política de bloqueio.

## Decisão necessária
Este PRD precisa de aprovação humana antes de avançar para Tech Spec. A decisão esperada é aprovar, ajustar escopo ou fatiar o MVP antes de qualquer implementação.
