# Execution — SDD CLI (TUI)

## Tarefa

Implementar, numa única execução, o conjunto completo de itens (T-01..T-25) da TUI determinística do binário `sdd`: módulo `src/tui/`, subcomando `sdd tui`, refatoração compartilhada `write_atomic`, testes automatizados e evidências de DoD. Escopo conforme os artefatos de planejamento aprovados (ver Rastreabilidade).

## Resumo da implementação

Foi adicionado um módulo isolado `src/tui/` (11 submódulos) e uma única variante `Command::Tui` no dispatch de `src/main.rs`, sem alterar nenhum braço existente. A TUI é um cockpit determinístico (padrão Elm-like Model–Update–View) sobre `crossterm`/`ratatui`, sem IA e sem rede: conduz estado, navegação por etapas, loaders, checkpoints, viewer Markdown e persistência, delegando a geração de conteúdo aos subcomandos `sdd` existentes executados como processos filhos.

Pontos implementados por task:
- **T-01** deps `ratatui 0.29` + `crossterm 0.28`, `dev-dependencies` (TestBackend) e `[profile.release] strip = true`.
- **T-02/T-03** esqueleto `src/tui/`, `mod tui;`, `Command::Tui(TuiArgs)` + dispatch `tui::run`.
- **T-04** detecção de TTY/`TERM=dumb` com helper puro `tty_ready` (testável) — degrada com exit 1.
- **T-05** `TerminalGuard` RAII + `panic` hook restaurando o terminal.
- **T-06** modelo de estado (`App`/`Screen`/`Stage`) e event loop `poll(100ms)` → `update` → `render`.
- **T-07** `orchestration.rs`: scan de `docs/` + parse do `traceability-map.yaml` (ausente/ inválido → `unknown`).
- **T-08/T-09** tela de orquestrações e criação via `sdd init` (subprocesso, args vetorizados).
- **T-10/T-11** máquina de estados `can_navigate` (bloqueio de etapas obrigatórias; Refinement opcional) e StageBoard.
- **T-12** `Loader` com threshold de 200ms (sem flash).
- **T-13** `runner.rs`: execução de etapa em `std::thread` + `mpsc`, `current_exe()`, `stdin: null`, sem shell.
- **T-14/T-15** parser Markdown subset → `ratatui::text::Text` + Viewer com scroll (parse uma única vez).
- **T-16** `editor.rs`: ciclo suspender/restaurar `$EDITOR` (fallback `vi`), path como argumento separado.
- **T-17** `persist::write_atomic` (write-then-rename) e refatoração de `save_artifact` e `write_stage_content` em `src/main.rs` para usá-lo.
- **T-18** Checkpoint (Aprovar/Regenerar/Editar) persistindo via `sdd artifact save` (subprocesso) — único ponto de mutação do traceability-map.
- **T-19** Refinement condicional (executar/pular → `state=skipped`).
- **T-20** Painel de erro (stderr, "tentar novamente"/"editar config"), sem sobrescrever artefato aprovado.
- **T-21** Ajuda contextual `?`. **T-22** Resumo final pós-Memory. **T-23** Telemetria `.sdd/tui-events.jsonl` via `log_jsonl` reusado.
- **T-24** testes unit + render (TestBackend) + não-regressão.

## Arquivos alterados

Criados:
- `src/tui/mod.rs` — entrada, TTY guard, RAII, event loop, telemetria.
- `src/tui/app.rs` — estado e reducers.
- `src/tui/stage.rs` — `Stage`/`StageStatus`/`can_navigate`.
- `src/tui/orchestration.rs` — scan + parse do traceability-map.
- `src/tui/event.rs` — `Action` + mapeamento de teclas.
- `src/tui/ui.rs` — render de todas as telas.
- `src/tui/markdown.rs` — parser do subset Markdown.
- `src/tui/runner.rs` — subprocessos de etapa (thread+mpsc) e `sdd init`.
- `src/tui/loader.rs` — spinner com threshold.
- `src/tui/editor.rs` — ciclo `$EDITOR`.
- `src/tui/persist.rs` — `write_atomic` + `save_stage_state`.

Modificados:
- `Cargo.toml` — deps `ratatui`/`crossterm`, dev-dep `ratatui`, `[profile.release] strip = true`.
- `src/main.rs` — `mod tui;`; `Command::Tui` + dispatch; `now_public()` e `log_jsonl` `pub(crate)`; `save_artifact` e `write_stage_content` usando `write_atomic`.

## Testes e evidências

- `cargo build` — **0 erros, 0 warnings**.
- `cargo fmt --check` — **limpo**.
- `cargo test` — **62 testes passando** (2 suites). Cobre: navegação/bloqueio (`stage`), parse do traceability-map e estados (`orchestration`), markdown subset (`markdown`), threshold do loader (`loader`), `write_atomic` incl. tmp órfão e parent ausente (`persist`), runner sem shell + entrega via canal (`runner`), reducers do app, render de todas as telas em 40/80/120 cols (`ui`), e degradação de TTY (`mod::tty_ready`).
- **Gate de binário (T-01):** release stripped = 3.958.784 bytes vs baseline 4.076.432 → **delta −0.11 MB** (≤ 5 MB OK).
- **Não-regressão (CA-RNF05):** `sdd {idea,prd,techspec,tasks,refinement,execution,review,memory,artifact} --help` → exit 0 inalterados; `sdd tui --help` reconhecido.
- **Degradação sem TTY (CA-RF11):** `sdd tui` com stdout redirecionado → mensagem clara no stderr + **exit 1**, sem entrar em raw mode.

## Riscos e pendências

- **T-25 (validação manual de terminais) PENDENTE:** a matriz interativa (iTerm2, Terminal.app, alacritty, kitty, tmux), o ciclo `$EDITOR` ao vivo, o `kill -9` durante etapa e o benchmark `time sdd tui` exigem um TTY real e não puderam ser executados neste ambiente headless. Deve ser feito antes do merge/release como gate.
- **Auto-aprovação de checkpoints** (`tui.auto_approve_stages`) ficou fora do MVP por decisão de grooming; todos os checkpoints são manuais.
- **Streaming de tokens** permanece fora do escopo (sem IA embarcada); loaders cobrem operações de filesystem/subcomando.

## Rastreabilidade

| Campo | Valor |
|---|---|
| Backlog de origem | `04-tasks.md` (T-01..T-25) e `05-refinement.md` |
| Tech Spec | `03-techspec.md` |
| Risco | `00-risk-classification.md` — medium (external_dependency) |
| Próximo artefato | `06-adr.md` (decisão arquitetural) e `07-review.md` (revisão) |
| Orquestração | `criar-um-cli-poderoso-...-sdd-cli` |
