# Tech Spec - 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: techspec
- Estado atual: draft para checkpoint humano, reexecutado sobre a nova base de código em 2026-07-04.
- Artefato anterior aprovado: `02-prd.md`.
- Artefatos de base: `00-project-discovery.md`, `00-risk-classification.md`, `01-idea.md`.
- Context Pack: `.sdd/intelligence/context-packs/roadmap-de-maturidade-do-sdd-layer-gate-unico-de-release-corrigir-jest-do-bot-modul-960734c3de8d/techspec.md`.
- CodeGraph usado: `ArtifactCommand::Link`, `DiagramCommand`, `DirectAdapter`, `run_cli_workspace_execution_task`, `GitHubProvider`, `github_token`, `fetch_github_last_comment`.
- Diffs inspecionados: `Cargo.toml`, `src/domain/orchestrator/block_gate.rs`, `src/main.rs`, `src/tui/runner.rs`, `bot/src/providers/github.ts`, `bot/src/providers/githubWebhook.ts`, `bot/src/providers/githubWebhookReceiver.ts`, `bot/src/__tests__/githubProvider.test.ts`, `bot/src/__tests__/githubWebhook.test.ts`.
- Skills aplicadas: `orchestration`, `artifact-diagrams`, `ci-release`, `test-strategy`, `security-privacy`, `provider-compatibility`, `checkpoints`, `artifact-schemas`.

## Visão técnica
O roadmap deixa de ser majoritariamente prospectivo porque a nova base já contém parte da implementação: GitHub provider e webhook no bot, suporte GitHub App no `block_gate`, `sdd artifact link`, comandos de diagrama, novas capacidades de workspace execution no TUI e dependências Rust adicionais. A estratégia correta agora é estabilizar, validar e consolidar essas superfícies antes de avançar para modularizações maiores.

Prioridade técnica revisada:

1. fechar o gate único de release usando os comandos reais de Rust, bot, docs, doctors e diagramas;
2. estabilizar o bot GitHub/Jest, tratando `execa` como risco residual mesmo com mock atual;
3. validar GitHub provider, webhook receiver, migration e `block_gate` GitHub App como um contrato único;
4. tornar o TUI multi-provider seguro para execução real de workspace, com readiness, trace e mensagens consistentes;
5. criar `sdd maintenance report` como visão rápida de drift por área;
6. modularizar `src/main.rs` e TUI por extrações pequenas depois do contrato estabilizado;
7. ampliar precisão com golden tests, property tests e corpus determinístico de artefatos SDD.

O princípio permanece: não criar segunda fonte de verdade. O relatório de manutenção deve agregar `health_report`, doctors, CI, bot, docs, diagramas e checks advisory. O release gate deve chamar os comandos reais. A modularização deve mover comportamento existente com testes verdes antes de alterar a superfície pública.

## Arquitetura

### Estado da nova base

| Superfície | Evidência atual | Implicação |
|---|---|---|
| Release/maintenance | `run_ci`, `health_report`, doctors e workflows ainda vivem majoritariamente em `src/main.rs` | gate único deve nascer como orquestração de checks existentes antes de virar módulo profundo |
| Artifact store | `ArtifactCommand::Link` e `add_external_link` registram links externos em `traceability-map.yaml` | maintenance report e release gate devem validar links e rastreabilidade local/externa |
| Diagramas | `DiagramCommand::{Attach, Doctor}` e comandos espelhados por client foram expandidos | gate deve incluir `sdd diagram doctor` quando houver artefatos com companion visual |
| Bot GitHub | `bot/src/providers/github.ts`, webhook, config e migration existem; testes mockam `axios` e `execa` | foco muda de criar provider para estabilizar contrato, ESM/Jest, auth e webhooks |
| Block gate | `block_gate.rs` suporta GitHub, GitHub App, paginação `rel=last` e parsing `GH-123`/URL | falta política HTTP comum com timeout, retry, rate-limit e erro classificado |
| TUI | `DirectAdapter` cobre Codex, Claude, opencode, Cursor, Devin, Trae e Antigravity com workspace execution | falta evidência completa de prontidão, segurança operacional e UX de falha por provider |
| Dependências | `jsonwebtoken = "9.3"` e `reqwest` com `rustls-tls` foram adicionados | release gate deve cobrir lockfile, build all-features e checks advisory de supply chain |

### Boundaries propostos

| Área | Direção |
|---|---|
| `src/main.rs` | manter como composition root no curto prazo, extraindo primeiro coletores e comandos de manutenção com testes de CLI |
| `src/commands/*` | extrair por domínio somente quando mover implementação real: `ci`, `maintenance`, `artifacts`, `diagram`, `clients`, `workflow`, `package` |
| `src/domain/maintenance.rs` | modelar áreas, status, duração, evidência, ação recomendada e severidade agregada |
| `src/runtime/http.rs` | centralizar timeout, retry de leitura, redaction, classificação de 401/403/404/429/5xx/timeout |
| `src/domain/orchestrator/block_gate.rs` | consumir a política HTTP comum sem mudar o contrato público de `/bloqueado` |
| `src/tui/*` | separar readiness de adapter, montagem de comando, execução, persistência de relatório e telemetria |
| `bot/src/providers/*` | estabilizar contratos `WorkTrackerProvider` e `RepoProvider`; isolar execução git por adapter testável se o mock de `execa` não for suficiente no Jest/CI |
| `tests/fixtures/golden/*` | versionar corpus mínimo de PRD, Tech Spec, Tasks, traceability map, maintenance report e diagramas |

### Teste de deleção
- `maintenance report` tem valor se a sua remoção espalhar lógica de status por CI, docs, bot e doctors. Se for apenas um wrapper textual, não deve ser criado.
- `artifact link` deve permanecer no core se evitar duplicação manual de Jira/Confluence/GitHub/GitLab no `traceability-map.yaml`.
- `runtime/http.rs` só se justifica se `block_gate`, bot ou futuros adapters reutilizarem timeout/redaction/classificação de forma testável.
- A extração de `commands/*` só tem valor quando reduz `src/main.rs` com comportamento e testes junto, não como pass-through vazio.
- O adapter de shell do bot deve ser criado se o mock atual de `execa` continuar frágil em Jest/ESM ou se o provider precisar de testes de branch/PR sem processo real.

## Stack
- Rust 2021, Clap, Serde, Serde YAML/JSON, Ratatui, Crossterm, Reqwest blocking com `rustls-tls`.
- `jsonwebtoken` para GitHub App JWT no `block_gate`.
- TypeScript CommonJS no bot, Jest + ts-jest, Axios, Execa, servidor HTTP nativo para webhook.
- GitHub Issues/Projects/PRs/Webhooks como provider adicional a Jira/Bitbucket.
- Next/Fumadocs no docs site.
- GitHub Actions como CI principal.

## Estrutura de pastas

```text
src/
  commands/
    artifacts.rs
    ci.rs
    diagram.rs
    maintenance.rs
    clients.rs
    workflow.rs
  domain/
    maintenance.rs
  runtime/
    http.rs
  tui/
    adapters.rs
    execution.rs
    state.rs
    telemetry.rs
bot/src/
  providers/
    contracts.ts
    gitShell.ts
    github.ts
    githubWebhook.ts
    githubWebhookReceiver.ts
  db/migrations/
    002_github_provider.sql
tests/
  fixtures/
    golden/
```

Esses paths são alvos arquiteturais. O Refinement deve escolher a menor sequência executável, preservando o worktree atual e evitando refatorações amplas antes do release gate ficar confiável.

## Dados
- `maintenance report` é derivado e reconstruível.
- O report deve expor área, status, severidade, comando, duração, resumo, evidência e ação recomendada.
- Estados mínimos: `pass`, `warn`, `fail`, `skipped`.
- `traceability-map.yaml` segue como fonte local para artefatos e deve aceitar `external_links.<system>[]` gerados por `sdd artifact link`.
- A migration `002_github_provider.sql` deve ser tratada como contrato de compatibilidade do bot e coberta por testes de repositório/config.
- Golden tests devem evitar snapshot de texto integral quando a copy puder mudar; priorizar estrutura, campos, status e links.

## Contratos

### Release gate
- Contrato mínimo: um comando local reproduzível que execute `fmt`, `clippy`, testes Rust all-features, health strict, doctors, docs build e bot build/test.
- Opção inicial recomendada: estender `sdd ci` com modo strict/release e publicar a sequência documentada no CI.
- Opção evolutiva: `sdd release gate --json`, se o Refinement confirmar que um comando separado melhora ergonomia e adoção.
- Falhas obrigatórias retornam exit code diferente de zero; advisory aparece como `warn` sem bloquear no primeiro ciclo.

### Maintenance report
- Novo comando proposto: `sdd maintenance report`.
- Saídas: Markdown por padrão e `--json` para CI/agentes.
- Escopo por área: `core Rust`, `docs`, `clients`, `bot`, `providers`, `intelligence`, `workflows`, `release`, `diagrams`.
- Deve reutilizar `health_report` e não duplicar cálculo já existente.
- Pode aceitar `--name <orchestration>` para anexar rastreabilidade, quality report e diagram doctor da orquestração.

### Artifact link
- `sdd artifact link <name> <system> --url ...` deve aceitar sistemas controlados: `jira`, `confluence`, `bitbucket`, `github`, `gitlab`.
- Cada link deve registrar `url`, `recorded_at` e, quando presente, `kind`, `id`, `title`, `stage`.
- O comando deve preservar YAML existente e falhar com mensagem clara quando `traceability-map.yaml` estiver inválido.
- O report deve sinalizar link externo ausente apenas quando a política do projeto exigir aquele provider.

### Diagramas
- `sdd diagram attach` continua adicionando companion visual à seção `## Diagramas`.
- `sdd diagram doctor --name <slug>` deve entrar no checklist quando IDEA, PRD ou Tech Spec referenciam assets visuais.
- Comandos espelhados de clients devem ser tratados como derivados do contrato canônico; drift deve ser detectável por doctor.

### Bot GitHub
- `GitHubProvider` implementa `WorkTrackerProvider` e `RepoProvider`.
- IDs aceitos: `GH-123`, `owner/repo#123`, `https://github.com/owner/repo/issues/123`.
- Autenticação aceita token, env token e GitHub App.
- Webhook receiver deve validar `x-hub-signature-256`, limitar payload e despachar eventos relevantes sem vazar payload sensível.
- O import direto de `execa` permanece risco de testabilidade. Se Jest/CI continuar instável, criar interface `GitShell`:

```ts
export interface GitShell {
  run(command: string, args: string[], options: { cwd: string }): Promise<{ stdout: string }>
}
```

### HTTP externo
- Criar política comum para Jira/GitHub:
  - timeout default: 10s;
  - retry apenas para leitura em timeout, 5xx e 429;
  - sem retry para 401, 403 e 404;
  - `retry-after` preservado quando disponível;
  - body sempre redigido e truncado;
  - erro classificado por código estável.

## Fluxos técnicos

### Gate de release
1. Desenvolvedor ou CI chama o gate único.
2. O gate executa checks obrigatórios em ordem previsível.
3. Checks advisory rodam quando ferramentas estão disponíveis.
4. Resultado agregado informa `pass`, `warn` ou `fail`.
5. Em `fail`, a saída deve apontar comando, área, causa e próxima ação.

### GitHub block gate
1. CLI carrega `.sdd/bot/sdd-bot.config.yaml`.
2. Se `integrations.work_tracker` for `github` ou o ID for parseável como GitHub, usa bloco GitHub.
3. Resolve token por config, env ou GitHub App.
4. Busca a última página de comentários via `rel=last`.
5. Bloqueia somente se o último comentário normalizado for `/bloqueado`.
6. Falhas de auth/rate-limit/timeouts devem ser classificadas e redigidas.

### TUI workspace execution
1. TUI recebe provider selecionado e task.
2. `DirectAdapter` identifica comando, label, login command e modo de permissão.
3. Antes de executar, readiness valida binário/configuração mínima.
4. Execução grava trace, provenance, uso estimado, contexto e relatório da task.
5. Provider desconhecido falha antes de mutar workspace.

## Estados e eventos
- `recorded`: artefato gerado e validado, ainda sem aprovação humana.
- `approved`: somente após checkpoint humano explícito.
- `skipped`: apenas para etapa opcional quando risco permitir.
- `pass/warn/fail/skipped`: status de áreas do maintenance report.
- `started/succeeded/failed/error`: eventos de execução de task no TUI.
- Eventos derivados devem passar por redaction antes de `.sdd/events.jsonl`, `.sdd/task-gates.jsonl` ou reports.

## Autenticação e autorização
- Não alterar o modelo global de auth da camada SDD.
- GitHub aceita `GITHUB_TOKEN`, `GH_TOKEN`, `github.auth.token`, `github.auth.token_env` ou GitHub App.
- GitHub App private key pode vir de config, env ou path, mas nunca deve aparecer em log, erro, golden fixture ou report.
- Webhook exige segredo via env e assinatura HMAC SHA-256.
- Workspace execution por provider deve ser explícita; provider desconhecido não pode cair em shell genérico.

## Validação e erros
- Todo artefato desta orquestração deve passar por `sdd validate-artifact`.
- Erros obrigatórios do release gate retornam exit code != 0.
- Ferramenta ausente em advisory retorna `skipped`.
- Ferramenta ausente em check obrigatório retorna `fail`.
- Rate-limit externo deve ser `rate_limited` e incluir `retry-after` quando disponível.
- Payloads externos e stderr de providers devem ser truncados/redigidos em saídas persistidas.

## Observabilidade
- `sdd health --json` já agrega optimization, intelligence, workflow, clients, capabilities, skills e quality; `maintenance report` deve reutilizar esse shape e acrescentar bot, docs, release, diagrams e advisory.
- TUI workspace execution deve manter `AgentProvenance`, `ModelProvenance`, uso estimado, duração e contexto por task.
- `artifact link` deve tornar rastreabilidade externa auditável sem duplicar conteúdo.
- Webhook receiver deve logar ativação, falhas de configuração e tipo de evento, mas não payload completo.

## Segurança
- Tokens de Jira/GitHub não podem aparecer em erro, log, report, snapshot ou golden fixture.
- Private keys de GitHub App devem ser redigidas mesmo em falhas de parsing.
- Webhook deve rejeitar assinatura inválida antes de parsear/acionar efeitos.
- Checks opcionais visíveis: `cargo audit`, `cargo deny`, `gitleaks`, `npm audit` e SBOM em modo advisory inicial.
- Comandos de workspace-write em TUI precisam ser explicitamente rastreados porque podem mutar arquivos.

## Performance
- `maintenance report` deve ter modo rápido, reaproveitando dados existentes e evitando builds caros por padrão.
- `release gate` pode ser mais lento, mas deve mostrar duração por área.
- HTTP externo deve ter timeout para evitar travas indefinidas.
- Bot tests e docs build devem rodar no gate completo, não no report rápido padrão.
- Golden/property tests devem ser pequenos e determinísticos.

## Testes

| Requisito | Testes |
|---|---|
| RF-01 | integração CLI do gate/release ou `sdd ci` strict; CI executando a mesma sequência local |
| RF-02 | `bot/src/__tests__/githubProvider.test.ts` verde com `axios` e `execa` mockados; fallback para `GitShell` se ESM continuar frágil |
| RF-03 | testes Rust existentes após extrações; `cargo test --locked --all-features` |
| RF-04 | testes de TUI para `DirectAdapter`, readiness, comandos workspace-write e provider desconhecido |
| RF-05 | testes de `block_gate` GitHub para parse, paginação `rel=last`, auth ausente e política HTTP com timeout/rate-limit |
| RF-06 | golden tests de report, traceability map, artefatos SDD e diagramas |
| RF-07 | property tests leves para slug, stage, path, external links e parsing de IDs |
| RF-08 | `sdd artifact link` preservando YAML e rejeitando sistema desconhecido |
| RF-09 | `sdd diagram doctor` cobrindo skill instalada, assets, allowlist de stage e comandos espelhados |
| RF-10 | webhook receiver validando assinatura, payload máximo, JSON inválido e dispatch de eventos |

Comandos esperados no gate completo:

```bash
cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --locked --all-features
sdd health --strict --json
sdd workflow validate agentic-sdd-loop --json
sdd clients doctor --strict --json
sdd capabilities doctor --targets all --json
sdd skills doctor --strict --json
sdd diagram doctor --name roadmap-de-maturidade-do-sdd-layer-gate-unico-de-release-corrigir-jest-do-bot-modul-960734c3de8d
cd bot && npm run build && npm test
cd docs-site && npm run docs:generate -- --check && npm run docs:links && npm run build
```

Checks advisory iniciais:

```bash
cargo audit
cargo deny check
gitleaks detect
cd bot && npm audit
```

## Riscos
- O worktree atual tem mudanças amplas em 58 arquivos; tasks devem preservar esse contexto e evitar reverter alterações não relacionadas.
- GitHub provider, webhook, config e migration formam um contrato multi-superfície; validar só um arquivo pode dar falso positivo.
- `execa` está mockado nos testes novos, mas ainda é import direto no provider; Jest/ESM pode continuar sendo ponto frágil no CI.
- `block_gate` adiciona GitHub App e nova dependência criptográfica; precisa de teste all-features e revisão de redaction.
- Workspace execution multi-provider pode executar comandos perigosos; readiness e trace precisam ser tratados como contrato, não copy de UI.
- `artifact link` muta YAML de rastreabilidade; precisa preservar comentários/ordem quando possível ou documentar limitação.
- Golden tests podem congelar texto demais; focar em estrutura e campos críticos.

## Decisões arquiteturais
- A nova base deve ser estabilizada antes de uma modularização ampla.
- `health_report` continua base do futuro `maintenance report`.
- `artifact link` entra como contrato de rastreabilidade, não como documentação auxiliar.
- Diagramas entram no gate quando a orquestração usa companion visual ou comando `diagram doctor`.
- Checks de segurança começam advisory para aumentar visibilidade sem bloquear a adoção inicial.
- O bot deve manter GitHub e Jira por interfaces de provider, com branch/PR e webhooks cobertos por testes.
- `main.rs` permanece composition root até uma ADR justificar a extração completa de comandos.

## Plano de implementação

### Fase 1 - Estabilização da nova base
- Rodar e corrigir `cargo fmt`, `clippy all-targets all-features`, `cargo test --locked --all-features`.
- Rodar e corrigir `bot npm run build` e `npm test`, incluindo os testes GitHub/webhook/config.
- Validar docs e doctors existentes.
- Registrar status real em um handoff curto antes de novas extrações.

### Fase 2 - Gate único de release
- Documentar e automatizar o bundle obrigatório.
- Incluir bot, docs, health strict, clients/capabilities/skills/workflow doctors e diagram doctor quando aplicável.
- Expor JSON agregado ou estender `sdd ci` com modo strict/release.
- Tornar advisory visível sem bloquear.

### Fase 3 - GitHub/provider hardening
- Validar config, migration, provider GitHub, webhook receiver e `block_gate` como contrato único.
- Introduzir política HTTP comum com timeout, retry de leitura e erro classificado.
- Decidir se `GitShell` é necessário ou se o mock atual de `execa` é suficiente e estável no CI.

### Fase 4 - Maintenance report
- Criar modelo de área/status.
- Reutilizar `health_report`.
- Adicionar coletores bot/docs/release/diagrams/advisory.
- Expor Markdown e JSON com testes de contrato.

### Fase 5 - Modularização incremental
- Extrair primeiro `commands/artifacts` ou `commands/diagram`, pois a nova base já tocou essas superfícies.
- Extrair depois `commands/ci` ou `commands/maintenance`.
- Separar TUI em readiness/adapters/execution/telemetry com testes por fatia.

### Fase 6 - Precisão de contratos
- Adicionar corpus golden mínimo de artefatos SDD.
- Adicionar property tests para slug, stage, external links e parsing de IDs.
- Criar avaliação semântica determinística para PRD/Tech Spec/Tasks sem depender de provider.

## Diagramas
**Pergunta respondida:** como a nova base muda o roadmap de maturidade sem quebrar rastreabilidade, provider-neutralidade e gates humanos.
**Fonte:** PRD aprovado, Context Pack, CodeGraph e diffs locais de 2026-07-04.
**Escopo:** release gate, maintenance report, bot GitHub, webhooks, block gate, artifact links, diagramas, TUI workspace execution e modularização incremental.
**Limitações:** a implementação ainda depende de Tasks, Refinement obrigatório e Execution; não há companion Excalidraw/HTML nesta etapa.

### Arquitetura alvo revisada

```mermaid
flowchart TD
  CLI["src/main.rs / Clap"] --> ART["artifact link"]
  CLI --> DIA["diagram attach/doctor"]
  CLI --> CI["release gate / sdd ci strict"]
  CLI --> MNT["maintenance report"]
  MNT --> HEALTH["health_report existente"]
  MNT --> BOT["bot build/test e GitHub provider"]
  MNT --> DOCS["docs-site build/links"]
  MNT --> DRIFT["clients/skills/capabilities/workflows"]
  MNT --> ADV["audit/deny/gitleaks/npm audit/SBOM"]
  ART --> TRACE["traceability-map.yaml"]
  DIA --> TRACE
  BOT --> GITHUB["GitHub Issues/Projects/PR/Webhooks"]
  BLOCK["block_gate.rs"] --> HTTP["runtime http policy"]
  BLOCK --> GITHUB
  TUI["TUI runner"] --> ADAPTERS["DirectAdapter workspace-write"]
  ADAPTERS --> TRACE_EXEC["trace/provenance/report da task"]
```

### Sequência do gate completo

```mermaid
sequenceDiagram
  participant Dev as Developer ou CI
  participant CLI as sdd
  participant R as Rust
  participant H as Health e doctors
  participant B as Bot
  participant D as Docs e diagramas
  participant A as Advisory
  Dev->>CLI: sdd ci --strict-release ou sdd release gate
  CLI->>R: fmt, clippy, cargo test all-features
  CLI->>H: health strict, workflow, clients, capabilities, skills
  CLI->>B: npm run build, npm test
  CLI->>D: docs generate, links, build, diagram doctor
  CLI->>A: audit/deny/gitleaks/npm audit/SBOM quando disponíveis
  A-->>CLI: warn/skipped/pass
  D-->>CLI: pass/fail
  B-->>CLI: pass/fail
  H-->>CLI: pass/fail
  R-->>CLI: pass/fail
  CLI-->>Dev: status agregado com ações recomendadas
```

### Política externa Jira/GitHub

```mermaid
stateDiagram-v2
  [*] --> Request
  Request --> Success: 2xx
  Request --> AuthError: 401/403
  Request --> NotFound: 404
  Request --> RateLimited: 429
  Request --> Retriable: timeout/5xx leitura
  Retriable --> Request: retry limitado
  Retriable --> Failed: limite excedido
  AuthError --> Failed
  NotFound --> Failed
  RateLimited --> Failed
  Success --> [*]
  Failed --> [*]
```
