# Refinement — SDD CLI (TUI)

## Resumo

O `sdd tui` é um novo modo interativo do binário existente: um cockpit determinístico no terminal que conduz o fluxo Spec-Driven completo, da concepção à memória, sem depender de agente ou GUI. A TUI lista orquestrações, dispara subcomandos `sdd` como processos filhos, exibe spinners/loaders, renderiza artefatos Markdown inline, conduz checkpoints de aprovação e persiste estado via o mesmo contrato de filesystem que o harness atual. O valor entregue é visibilidade de progresso e fluxo guiado para o engenheiro que vive no terminal — sem regredir nenhum subcomando existente.

## Solução proposta

- **Módulo isolado `src/tui/`** com 11 submódulos (mod, app, stage, orchestration, event, ui, markdown, runner, loader, editor, persist). A entrada no binário é um único braço novo em `Command::Tui` no `run()` de `src/main.rs` — nenhuma função existente é alterada, apenas reusada.
- **Padrão Elm-like** (Model–Update–View) sobre event loop síncrono: `poll(100ms)` → `update` (transição pura) → `render`. Sem tokio; subprocessos em `std::thread` + `mpsc::channel`; o loop principal continua animando o spinner via `try_recv`.
- **Execução de etapas**: `runner.rs` invoca `current_exe()` com args vetorizados (`[stage, "--name", ..., "--root", ...]`), nunca via shell. O contrato de sucesso é exit 0 + artefato já gravado pelo subcomando filho.
- **`write_atomic` (decisão crítica, T-17)**: novo helper `persist.rs` que escreve em `.tmp` no mesmo dir e faz `fs::rename`. As funções `save_artifact` (~:1182) e `write_stage_content` (~:1996) de `src/main.rs` serão refatoradas para usá-lo. Essa é a única mudança no harness e exige suite de não-regressão dedicada antes de qualquer integração com a TUI (T-18 depende de T-17).
- **Checkpoint de aprovação**: a TUI não reimplementa escrita de YAML — invoca `sdd artifact save --state approved --force` como subprocesso, mantendo um único ponto de mutação de estado.
- **Loader com threshold 200ms**: `Loader::arm/disarm/tick`; spinner braille só aparece se `elapsed >= 200ms`, eliminando flash em operações rápidas.
- **Restauração de terminal**: `TerminalGuard` com `Drop` + panic hook garantem `LeaveAlternateScreen` + `disable_raw_mode` em qualquer caminho de saída.
- Detalhe de cada decisão em `03-techspec.md` (Arquitetura, Segurança, Performance, Testes).

## Pontos de observação

- **`write_atomic` não pode quebrar o harness (risco central):** T-17 altera `save_artifact` e `write_stage_content`, compartilhados com todos os subcomandos. Mitigação: `cargo test` completo + testes que invocam `sdd idea --help`/`sdd prd --help` e verificam stdout/stderr/exit idênticos ao baseline antes de avançar para T-18. Nenhuma task posterior começa antes de T-17 verde.
- **Restauração do terminal em panic/erro:** raw mode não restaurado corrompe o shell. Mitigação: `TerminalGuard` com `Drop` + `std::panic::set_hook`. Coberto em T-05; validado com `kill -9` em T-25.
- **Sem shell injection:** todo subprocesso usa `Command::new` com args vetorizados; ideia em linguagem natural é argumento posicional único. Verificar em T-09, T-13, T-16, T-18.
- **Artefatos da TUI não podem quebrar `infer_artifact`/gate:** a TUI reusa `sdd artifact save`, mesmo fluxo do harness. Teste de inferência dedicado em T-24.
- **Loader threshold 200ms:** implementar com `Instant::elapsed` contra `armed_at`, sem `sleep`; testar com tempo mockado.
- **Ciclo `$EDITOR`:** desabilitar raw mode + sair do alternate screen ANTES de abrir o editor e restaurar DEPOIS de fechar; testar exit não-zero do editor.
- **Tamanho do binário:** gate ≤+5MB medido em T-01 com `cargo bloat` antes de tudo; falha bloqueia a feature.
- **Versões pinadas ratatui 0.29 / crossterm 0.28:** `cargo update` controlado; CI compila em cada PR (RT-04).
- **Thread worker:** ao sair (`should_quit`), abandonar o handle (sem join bloqueante); o filho termina naturalmente.

## Checklist

- [ ] **Fase 1 — Fundação:** deps adicionadas, gate de binário verde, esqueleto `src/tui/`, `sdd tui` reconhecido pelo clap, TTY guard, event loop abre/fecha sem panic.
- [ ] **Fase 2 — Componentes + write_atomic:** orchestration, stage machine, loader, markdown, editor e `write_atomic`; não-regressão do harness confirmada.
- [ ] **Fase 3 — UI e Runner:** todas as telas e runner com mpsc; spinner animando durante subcomandos.
- [ ] **Fase 4 — Integração e telas finais:** checkpoint completo, Refinement condicional, ErrorPanel, Summary, telemetria JSONL.
- [ ] **Fase 5 — Validação e release:** `cargo test` zero falhas, matriz de terminais, `time sdd tui < 1s`, `validation-matrix.md`.

## Subtasks

| #   | Subtask | Est. (h) | Fase |
|-----|---------|----------|------|
| T-01 | Deps ratatui/crossterm + gate de binário | 1.0 | 1 |
| T-02 | Esqueleto `src/tui/` (11 submódulos) | 0.5 | 1 |
| T-03 | `Command::Tui` no enum + braço em `run()` | 0.5 | 1 |
| T-04 | Detecção de TTY e degradação | 1.0 | 1 |
| T-05 | TerminalGuard RAII + panic hook | 1.0 | 1 |
| T-06 | `App`/`Screen`/`Stage` e event loop | 2.0 | 1 |
| T-07 | `orchestration.rs`: scan + parse YAML | 1.5 | 2 |
| T-08 | OrchestrationList + atalhos | 1.5 | 3 |
| T-09 | NewOrchestration: input + `sdd init` | 1.5 | 3 |
| T-10 | `stage.rs`: máquina de estados + bloqueio | 1.5 | 2 |
| T-11 | StageBoard: painel de progresso | 1.5 | 3 |
| T-12 | `loader.rs`: spinner threshold 200ms | 1.0 | 2 |
| T-13 | `runner.rs`: thread + mpsc + captura | 2.0 | 3 |
| T-14 | `markdown.rs`: parser subset → Text | 2.0 | 2 |
| T-15 | Viewer com scroll | 1.5 | 3 |
| T-16 | `editor.rs`: suspender/restaurar `$EDITOR` | 1.5 | 2 |
| T-17 | `write_atomic` + refator harness (crítico) | 2.0 | 2 |
| T-18 | Checkpoint: Aprovar/Regenerar/Editar | 2.0 | 3 |
| T-19 | Refinement condicional: skip/run | 1.0 | 4 |
| T-20 | Painel de erro e recuperação | 1.0 | 3 |
| T-21 | Ajuda contextual `?` | 1.0 | 4 |
| T-22 | Resumo final pós-Memory | 1.0 | 4 |
| T-23 | Telemetria `.sdd/tui-events.jsonl` | 1.0 | 4 |
| T-24 | Testes unit + render + não-regressão | 3.0 | 5 |
| T-25 | Validação manual + benchmark (gate) | 2.0 | 5 |

**Total estimado:** ~36 h

## Definition of Done

- [ ] `cargo build --release` sem warnings; binário stripped; delta ≤+5MB (`cargo bloat`).
- [ ] `cargo test` completo verde, incl. não-regressão de `save_artifact`/`write_stage_content` após T-17.
- [ ] `sdd tui --help` ok; `sdd idea --help`/`sdd prd --help` com stdout/stderr/exit idênticos ao baseline (CA-RNF05).
- [ ] Fluxo completo Idea → Memory executável via `sdd tui`, com artefatos em `docs/<slug>/` e `traceability-map.yaml` atualizado.
- [ ] Checkpoint registra `state: approved` + `approved_at` (CA-RF09); skip de Refinement registra `state: skipped`.
- [ ] Degradação sem TTY: exit 1, mensagem no stderr, sem raw mode (CA-RF11).
- [ ] Spinner não aparece em <200ms; aparece em ≥200ms (CA-RF05).
- [ ] Nenhum subprocesso usa `sh -c`; args vetorizados (revisão em T-09/T-13/T-16/T-18).
- [ ] Artefatos passam no gate com tipo correto (teste de inferência T-24).
- [ ] Matriz de terminais validada (iTerm2/Terminal.app/alacritty/kitty/tmux): zero panic, resize, `$EDITOR`, `kill -9` restaura.
- [ ] `time sdd tui < 1s` (RNF-01); `validation-matrix.md` commitada.
- [ ] `tui_error` não loga stderr bruto com segredos (redaction).

## Flags e configurações

Não há feature flag de runtime nem remote config — a TUI é ativada exclusivamente por `sdd tui` (entrada estática no binário). Não há rollout gradual: a mudança é aditiva e sem toque nos paths existentes do harness, exceto o refactor atômico de T-17 (transparente externamente).

- **`--root <path>`:** flag opcional de `TuiArgs`; default `.`.
- **`$EDITOR`:** lida em runtime por `editor.rs`; fallback `vi`. Documentar no help/README.
- **`TERM` / TTY:** `TERM=dumb` ou ausência de TTY ativam degradação automática (RF-11).
- **`sdd.config.yaml` — auto-aprovação de checkpoints intermediários:** decisão de grooming = **manter todos os checkpoints manuais no MVP** (default seguro). A chave `tui.auto_approve_stages` fica como evolução futura, NÃO implementada agora — evita ambiguidade no fluxo de aprovação.
- Sem env vars novas, sem secrets, sem feature flags de infraestrutura.

## Rastreabilidade

| Campo | Valor |
|---|---|
| Backlog de origem | `04-tasks.md` — T-01..T-25, 5 fases, dependências, CA Gherkin |
| Tech Spec | `03-techspec.md` — Arquitetura, Segurança, Performance, Riscos RT-01..RT-08 |
| PRD | `02-prd.md` — RF-01..RF-15, RNF-01..RNF-08 |
| Risco | `00-risk-classification.md` — medium (external_dependency) |
| Próximo artefato | `06-execution.md` (execução única de todas as tasks) |
| Orquestração | `criar-um-cli-poderoso-...-sdd-cli` |
