# Memory - Orquestrador Autônomo de Demandas SDD

## Estado final
Planejamento **e implementação da Fase 1 entregues** (branch `feat/orquestrador-autonomo-demandas`). O orquestrador durável dirigido por demanda está **funcional e testado** (`cargo test` → 328 passed; `clippy -D warnings` limpo): ingestão de fila → planejamento autônomo (Idea→PRD→TechSpec→Tasks→Refinamento) com pausa nos gates → aprovação humana (default-deny, sem auto-aprovação) → artefatos locais + estado durável + auditoria redigida. Runner real ligado opt-in (`--real`); geração via LLM requer provider configurado.

Como rodar:
```
sdd demand --root . enqueue --id X --type story --title "..."
sdd auto   --root . run [--real]      # leva a fila até os gates
sdd demand --root . approve X --gate prd --by <autor>   # exige approvers no sdd.config.yaml
```
Implementado (11/15 + parciais): 003 (demand+queue), 004 (state), 005/006 (engine tick+avanço), 007 (gate notify local), 008 (approval default-deny), 009 (runner real opt-in), 010 (redação), 011 parcial (limites+confinamento+input redigido), 012 (CLI), 013 (auto run+audit), 014 parcial (assinatura Slack), 015 parcial (hygiene). ADR em `06-adr.md`.

Pendente (dependência externa/polish): webhook Slack + adapters Jira/Confluence (014), extração de `runtime::stage_runner` + anti-injeção pleno no prompt (002/011), esteira na TUI (015).

## Rastreabilidade
- Slug: `orquestrador-autonomo-de-demandas-sdd` · Diretório: `docs/orquestrador-autonomo-de-demandas-sdd/`
- Risco: `00-risk-classification.md` — **high** (execução autônoma, integrações externas, infra, cross-layer).
- Idea: `01-idea.md` (approved) · PRD: `02-prd.md` (approved) · Tech Spec v2: `03-techspec.md` (approved) · Tasks: `04-tasks.md` (approved, 15 tasks) · Refinamento: `05-refinement.md` (approved).
- Execução: `06-execution.md` (in_progress, 11/15) · ADR: `06-adr.md` (recorded). Pendente: `07-review.md` (review/merge).
- Revisão de Tech Spec por **Agent Team**: architecture-reviewer + security-reviewer + data-contract-reviewer (achados Críticos/Altos já incorporados na v2 — ver seção "Revisão (Agent Team) — decisões" do techspec).
- Origem: `pipeline.html` (arquitetura de referência, §07 "cola" e §08 "fases").

## Decisões
- **Escopo MVP = planejamento primeiro** (faseado, `pipeline.html` §08). Execução paralela, integrações reais e autonomia plena ficam para fases seguintes.
- **Integrações = adapters plugáveis, local como default operante** (Jira/Confluence/Slack/repo não configurados hoje: `systems.chat=none`).
- **Teto de execução-alvo = autocorreção até o verde** (registrado como meta/não-objetivo; fase futura).
- **Reuso, não reescrita (arch-C1)**: o motor headless de geração **já existe** em `src/tui/runner.rs`; será **extraído** para `runtime::stage_runner` (sink genérico) e compartilhado por TUI e engine — não reimplementado.
- **Camadas (arch-A4)**: motor puro em `domain/orchestrator/`; runner e adapters (efeito de rede) em `runtime/`. Sem top-level novo.
- **Estado durável (data Opção A)**: `.sdd/state/<slug>.json` é a verdade primária (atômico, lock, `schema_version`); o `traceability-map` é cache de display e só recebe estados que `StageStatus::from_yaml` entende — estados ricos (`awaiting_approval`/`ready_for_exec`) **nunca** no campo por-artefato do map.
- **Segurança (barreiras primárias)**: motor não executa nada do provider na Fase 1; motor **não tem caminho que aprove gate** (RN-02); escrita confinada a `docs/<slug>/` e `.sdd/`; demanda tratada como **dado não confiável** (anti-injeção + deny-check); redação ampliada em todos os writers; `approvers` com **default-deny**; assinatura Slack (HMAC + timestamp + replay) **no MVP**.
- **`tick` agendável em vez de daemon**: `auto run` é fino sobre `tick` (puro), preservando neutralidade de harness.

## Padrões úteis
- **Gate de artefato (`sdd hook artifact-gate`)**: `infer_artifact` é **filename-first** via `CANONICAL_ARTIFACT_FILES` (`src/main.rs:108`); só cai na heurística por conteúdo (primeiros 300 chars + filename vs `ARTIFACT_HINTS`) para nomes **não-canônicos**. Por isso o nome da orquestração evitou "backlog" (colide com hint `tasks`) e arquivos não-canônicos (ex.: `00-risk-classification.md`) devem manter os 300 primeiros chars sem palavras de hint. O motor deve gravar sempre no nome canônico.
- **`sdd artifact save` recusa sobrescrever** artefato existente; para reaprovar um arquivo já no store, copie para um caminho temporário e use `--force` (`cp x /tmp/y && sdd artifact save "<nome>" <stage> --file /tmp/y --state approved --force`).
- **Âncoras de reuso reais** (validadas pelo Agent Team): `tui::stage::{can_navigate,current_stage}` (`stage.rs:143/172`), `tui::orchestration::parse_index` (`orchestration.rs:78`, ignora chaves desconhecidas), `tui::persist::write_atomic`, `domain::providers` (`stage_models`/`stage_efforts`; `timeouts/retries` precisam ser propagados a `ProviderSelection`), `runtime::redaction::redact_text` (cobertura **estreita** hoje — expandir), `tui::runner::{DirectAdapter,build_provider_prompt,collect_artifact_context}`.
- **Helpers a extrair (privados hoje)**: `update_stage_state` (`main.rs:~1199`, string-replace → trocar por serde round-trip), `required_sections()` (`main.rs:~1406`), `validate_state` (`main.rs:~1326`, aceitar `in_progress`).
- **Guardrails**: `sdd hook bash-guard` bloqueia `git push|merge|reset --hard|clean`, `gh pr merge`, deploys — **defesa-em-profundidade** (pode não interceptar comandos de provider headless que não seja o Claude Code).

## Testes e comandos
- Gates de CI (`sdd.config.yaml` quality): `cargo test`, `cargo clippy -- -D warnings`, `cargo check`, `cargo build --release`.
- Validação de artefato: `sdd validate-artifact <tipo> <arquivo.md>` (usado em todos os artefatos desta orquestração — todos `valid`).
- Estratégia de testes planejada: unitários puros (queue/state/engine/approval/slug/redação por formato), integração com `FakeRunner` (ciclo completo + restart no meio), equivalência de refactor do runner, segurança (injeção, não-vazamento por formato, anti-spoof Slack, path traversal, não auto-aprovação), provider real `#[ignore]` gated.

## Pendências
- **Execução das 15 tasks** (`04-tasks.md`), ordem dos pacotes WP1→WP6; começar pelos refactors habilitantes (SDD-OAD-001 e 002) — base de tudo e maior risco de regressão (testar equivalência do runner antes de plugar o engine).
- **ADR** após a execução para "orquestrador durável" e "extração do runner" (`sdd adr`).
- **Fases seguintes** (fora do MVP): execução autônoma em worktrees + autocorreção até o verde; wiring real de Jira/Confluence/Slack; relaxar checkpoints (autonomia plena).
- **Fix de fundo do `infer_artifact`** (detecção filename-first) está sendo tratado em **sessão separada** (chip iniciado pelo usuário) — confirmar antes da execução.

## Contexto para o próximo agente
1. Leia, nesta ordem: `03-techspec.md` (v2, com as decisões do Agent Team), `04-tasks.md` (prompts standalone por task) e `05-refinement.md` (pacotes + flags).
2. Comece pelo **WP1 / SDD-OAD-001** (helpers in-process) e **SDD-OAD-002** (extrair `runtime::stage_runner`) — são as fundações; sem elas tudo duplica.
3. Invariantes inegociáveis: **Opção A** (não gravar estado rico no map por-artefato), **motor nunca aprova gate**, **`autonomous.enabled` off por default**, escrita **confinada** a `docs/<slug>/` e `.sdd/`, **nome canônico** nos artefatos gerados.
4. Use **Agent Team** na execução (risco high: `cross_layer`/`security_sensitive`/`data_contract`) e na revisão; pare nos checkpoints de **merge** (e **deploy/ativação** antes de ligar o modo autônomo em repo real).
5. Risco maior da execução: regressão na extração do runner — proteja com testes de equivalência da TUI antes de conectar o engine.
