# ADR — TUI determinística do `sdd` (SDD CLI)

## Rastreabilidade
- Orquestração: `criar-um-cli-poderoso-...-sdd-cli`
- Stage: adr
- Estado atual: draft
- Origem principal: `06-execution.md`

## Status
- Estado: Aceito
- Data da decisão: 2026-06-06
- Dono técnico: Allan Alexandre
- Escopo: novo subcomando `sdd tui` e módulo `src/tui/`; refatoração de persistência compartilhada em `src/main.rs`.

## Contexto
O `sdd` operava só como harness invocado por agentes externos (Claude Code, Codex). Não havia forma de conduzir o fluxo SDD interativamente no terminal sem um agente. O requisito (PRD) pediu uma TUI estilo opencode, usável standalone, com loaders e checkpoints. O binário é Rust com clap; não havia crate de TUI nem runtime async; a persistência de artefatos usava `fs::write` direto (não atômico).

## Problema
Como entregar uma experiência interativa de terminal para todo o fluxo SDD **sem** acoplar o binário a um provider de IA (custo, rede, duplicação de prompts) e **sem** regredir os subcomandos existentes nem o contrato dos artefatos?

## Decisão
Construir uma TUI **determinística, sem IA e sem rede**, num módulo isolado `src/tui/`, ativada por `sdd tui`. Ela orquestra o estado do fluxo, navegação, loaders, checkpoints, viewer Markdown e persistência, **delegando a geração de conteúdo aos subcomandos `sdd` existentes executados como processos filhos** (`std::process::Command` + `std::thread` + `mpsc`, sem shell). A mutação do `traceability-map.yaml` é feita exclusivamente reusando `sdd artifact save` (um único ponto de escrita). Stack: `ratatui 0.29` + `crossterm 0.28`, **sem tokio**. Como parte da decisão, introduziu-se `write_atomic` (write-then-rename) e migraram-se `save_artifact`/`write_stage_content` para ele, corrigindo a atomicidade tanto para a TUI quanto para o harness.

## Alternativas consideradas
| Alternativa | Benefícios | Custos/Riscos | Motivo para aceitar ou rejeitar |
|---|---|---|---|
| Provider de IA via HTTP no binário (reqwest+tokio, prompts embarcados) | TUI 100% standalone, gera conteúdo sozinha | Duplica prompts dos subagents; +deps pesadas; rede/credenciais; risco de divergência de qualidade | Rejeitada: alto acoplamento e custo; fora do princípio do harness |
| Delegar a um CLI agente local (`claude`/`opencode`) como subprocesso | Reusa subagents existentes | Exige agente instalado; não é standalone real | Rejeitada para o MVP |
| **Cockpit determinístico (escolhida)** | Sem IA/rede; binário leve; zero regressão por construção; contrato idêntico ao harness | Streaming de IA fora do escopo | **Aceita** |

## Consequências
- Positivas: binário leve (delta de tamanho negativo após `strip`); subcomandos intactos; contrato de artefatos preservado; `write_atomic` beneficia o harness inteiro.
- Negativas: a TUI não gera conteúdo por si só (depende dos subcomandos/agente externo para preencher artefatos).
- Trade-offs aceitos: sem streaming de tokens; checkpoints intermediários sempre manuais no MVP.
- Dívidas técnicas assumidas: validação manual de terminais (T-25) pendente; `tui.auto_approve_stages` adiado.

## Impactos e riscos
- Código e arquitetura: módulo isolado + 1 braço novo no dispatch; nenhuma função existente alterada exceto a migração para `write_atomic`.
- Dados, contratos ou APIs: nenhum novo; `traceability-map.yaml` mutado só via `sdd artifact save`.
- Segurança e privacidade: subprocessos sempre com args vetorizados (sem shell injection); `$EDITOR` como programa com path separado; sem rede; telemetria local com redaction.
- Performance e capacidade: abertura instantânea (sem init pesado); loader com threshold 200ms; thread por etapa via mpsc.
- Observabilidade e suporte: eventos em `.sdd/tui-events.jsonl` via `log_jsonl` reusado.

## Plano de adoção
Documentar `sdd tui` no README/help; concluir a matriz de validação manual de terminais (T-25) antes do release; manter CI compilando para travar versões de `ratatui`/`crossterm`.

## Plano de reversão
Remover o braço `Command::Tui` e o módulo `src/tui/` reverte a TUI sem afetar o harness. A migração `write_atomic` é independente e pode ser mantida (corrige um bug pré-existente) ou revertida isoladamente. Sinais para reversão: regressão de contrato de artefatos ou corrupção de terminal não mitigável.

## Evidências
- Execução: `06-execution.md`
- Testes/CI: `cargo test` 62 passando; `cargo build`/`cargo fmt --check` limpos; gate de binário ≤5MB (delta −0.11MB); não-regressão de subcomandos (exit 0); degradação sem TTY (exit 1).
- PR/commits/diff: (a preencher no merge)
- Review: `07-review.md` quando existir

## Histórico de revisão
| Data | Autor | Alteração | Motivo |
|---|---|---|---|
| 2026-06-06 | Allan Alexandre | Criação da ADR | Pós-execução da TUI |
