# Handoff - Orquestrador Autônomo de Demandas SDD

> Continuação do plano. Estado em v0.7.0 (branch `feat/orquestrador-autonomo-demandas`).
> Contexto completo nos demais artefatos desta pasta (lista de leitura no fim).

## O que está entregue (Fase 1)
Orquestrador durável dirigido por demanda, **funcional e testado** (`cargo test` → 328; `clippy -D warnings` limpo):
- Fila `.sdd/queue/<id>.json` + estado durável `.sdd/state/<slug>.json` (lock, `schema_version`, Opção A).
- Motor `engine::tick` / `run_until_idle`: ingestão → planejamento (uma etapa por tick) → **pausa nos gates** PRD/TechSpec/Refinamento.
- Aprovação humana `approval::apply_decision` (allowlist `approvers` default-deny; **o motor nunca auto-aprova**).
- Runner real opt-in: `HeadlessRunner` (em `src/main.rs`) envolve `tui::runner::spawn_stage`. `FakeRunner` é o default.
- Notify de gate local + auditoria `.sdd/orchestrator.jsonl` redigida.
- Segurança: `runtime::redaction` (segredos vs `redact_pii`), `runtime::slack::verify_slack_signature` (HMAC-SHA256), limites de entrada, escrita confinada.
- CLI: `sdd demand enqueue/list/status/approve/reject`, `sdd auto tick/run [--real] [--json]`.

## Como rodar
```
sdd demand --root . enqueue --id X --type story --title "..."   # type: epic|story|task|bug
sdd auto   --root . run [--real]                                 # leva a fila até os gates
sdd demand --root . status X
sdd demand --root . approve X --gate prd --by <autor>           # approvers no sdd.config.yaml
```
Config mínima para aprovar (`sdd.config.yaml`):
```yaml
approvers:
  cli: [seu-usuario-ou-git-email]
  slack: []     # user-ids quando o webhook existir
```

## Pendências (ordem sugerida)
1. **SDD-OAD-002 — Extrair `runtime::stage_runner`** de `tui::runner` (sink genérico no lugar de `Sender<StageEvent>`), consumido por TUI **e** engine. Hoje o `HeadlessRunner` (composition root) envolve `spawn_stage` — funciona, mas a extração elimina o acoplamento e habilita (2). Faça **testes de equivalência** da geração da TUI antes/depois (maior risco de regressão — ver ADR).
2. **SDD-OAD-011 (restante) — Anti-injeção no prompt**: em `tui::runner::build_provider_prompt` (ou no runner extraído), envolver os campos da demanda como **dado delimitado/rotulado** + instrução de sistema fixa proibindo comando shell/segredo/release; adicionar **deny-check de conteúdo** (mais relevante na execução). Já feito: descrição entra como input com PII redigida.
3. **SDD-OAD-014 (restante) — Wiring externo**: endpoint de webhook que chama `runtime::slack::verify_slack_signature` → `approval::apply_decision(Channel::Slack)`; mapear user-id Slack → `approvers.slack`. Abstração de adapters + Jira/Confluence (config-gated). Precisa de credenciais/endpoint.
4. **Geração via LLM**: configurar provider (codex/claude/...) + auth; usar `--real`. Sem provider, `--real` cai no harness determinístico (scaffold real).
5. **SDD-OAD-015 (restante) — Esteira na TUI**: estender `tui::orchestration::scan_orchestrations` + render para listar a fila e destacar `awaiting_approval`. Observabilidade já existe via CLI (`sdd demand list`/`auto status`).
6. **Itens adiados (quando consumidos)**: `ProviderSelection.timeouts/retries`; `validate_state(in_progress)`; `update_stage_state` com round-trip serde; bloco `demand:`/links externos no `traceability-map`.

## Invariantes a preservar
- **Opção A**: estados ricos (`awaiting_approval`/`ready_for_exec`/`manual:*`) só no `.sdd/state`; o campo por-artefato do map só recebe `recorded|in_progress|approved|skipped` (senão `StageStatus::from_yaml` → `Unknown` quebra a TUI).
- **Motor nunca aprova gate** (RN-02). Aprovação só por humano (CLI/Slack verificado), allowlist **default-deny**.
- Artefatos sempre no **nome canônico** (`infer_artifact` é filename-first; conteúdo/nome não-canônico evita palavras de `ARTIFACT_HINTS` nos 300 primeiros chars).
- Escrita confinada a `docs/<slug>/` e `.sdd/`; slug validado contra traversal.
- `redact_text` na auditoria (preserva e-mail do autor); `redact_pii` em conteúdo não confiável.

## Mapa de arquivos
- `src/domain/orchestrator/{demand,queue,state,engine,approval}.rs` — núcleo puro/determinístico.
- `src/runtime/{redaction,slack}.rs` — efeitos/segurança.
- `src/main.rs` — comandos `demand`/`auto`, `HeadlessRunner`, `select_runner`, `decide_gate`, `audit_tick`, `emit_gate_requests`, `load_approvers`.
- `tests/cli.rs` — 3 testes de integração (`demand_*`, `auto_run_*`, `auto_tick_real_*`).

## Gate de qualidade (CI = `.github/workflows/sdd-layer.yml`)
```
cargo fmt --check && cargo clippy -- -D warnings && cargo test && cargo build --release && target/release/sdd ci
```

## Leitura recomendada (nesta pasta)
`03-techspec.md` (v2, decisões do Agent Team) · `04-tasks.md` (15 tasks + prompts) · `05-refinement.md` (pacotes/flags) · `06-execution.md` (o que foi feito) · `06-adr.md` (decisões arquiteturais) · `08-memory.md` (memória/handoff resumido).
