# PRD - Orquestrador Autônomo de Demandas SDD

## Rastreabilidade
- Orquestração: Orquestrador Autônomo de Demandas SDD
- Slug: orquestrador-autônomo-de-demandas-sdd
- Stage: prd
- Estado atual: in_review
- Origem: visão de produto aprovada em `01-idea.md` + classificação de risco (`00-risk-classification.md`, nível high).
- Próximo artefato: Tech Spec em `03-techspec.md`.
- Decisões de escopo (checkpoint humano): MVP = **planejamento primeiro**; integrações = **adapters agora, local como default**; teto de execução = **autocorreção até o verde** (fase futura, registrado como meta/não-objetivo).

## Resumo
Este PRD trava a **Fase 1** do orquestrador autônomo: transformar o `sdd` de harness disparado por humano em um **orquestrador durável dirigido por demanda** que ingere itens de uma **fila**, gera a etapa Idea automaticamente e conduz o **planejamento** (Idea → PRD → Tech Spec → Tasks → Refinamento) sozinho, **pausando nos checkpoints humanos** e retomando ao receber aprovação por **CLI ou Slack**.

A entrega é deliberadamente faseada (`pipeline.html` §08): a Fase 1 escreve **zero código de produto** além do próprio harness e **não toca produção** — risco operacional baixo, valor no dia um. A execução paralela em worktrees e a revisão/correção autônoma já existem como fundação (`parallel.rs`, `execution.rs`) e serão **ligadas em fase seguinte**; aqui elas entram apenas como **estado de handoff** ("pronto para execução") e como design de fronteira, não como autonomia ativa.

As integrações externas (Jira, Confluence, Slack, repo provider) — hoje **não configuradas** (`systems.chat=none`, `work_tracker=markdown`) — entram como **seams de adapter**: o orquestrador funciona 100% com `docs/<slug>/` + CLI como default canônico e operante, e **espelha/linka** para Jira/Confluence/Slack quando o adapter correspondente estiver configurado. Nunca duplica conteúdo entre sistemas; só guarda ponteiros.

## Objetivos
- **O1 — Ingestão por fila**: receber demandas (épico/história/task/bug) numa fila durável e iniciar a orquestração automaticamente, gerando a etapa Idea sem ação humana.
- **O2 — Orquestrador durável**: avançar o planejamento como máquina de estados persistente, que sobrevive a reinício do processo e nunca avança duas vezes a mesma etapa.
- **O3 — Checkpoints com pausa indefinida**: parar em PRD, Tech Spec e Refinamento, persistir o estado, postar o pedido de aprovação e retomar exatamente de onde parou ao receber o sinal.
- **O4 — Aprovação multicanal**: aceitar aprovação/reprovação por **CLI** e por **Slack** (adapter), com a mesma semântica, registrando autor e timestamp.
- **O5 — Espelhamento por tipo de artefato com fallback local**: manter `docs/<slug>/` como fonte canônica e linkar/espelhar para Jira (estado/itens) e Confluence (página/whiteboard) quando configurado, sem duplicar conteúdo.
- **O6 — Rastreabilidade e auditoria**: cada transição, aprovação e link externo registrado no `traceability-map.yaml` e em trilha de auditoria local.
- **O7 — Observabilidade da esteira**: operador lista e acompanha demandas por etapa/estado via CLI e via TUI (visão de esteira).
- **O8 — Compatibilidade e neutralidade**: não quebrar o fluxo manual atual nem a TUI; funcionar em qualquer provider/harness com fallback Markdown.

## Não objetivos
- **NO1 — Execução autônoma ativa**: rodar agentes que escrevem código em worktree de forma autônoma fica para a fase seguinte. Aqui só se produz o **estado de handoff** e o contrato de fronteira. (Meta futura: **autocorreção até o verde** — agentes rodam loops revisão→correção até CI/critérios verdes, humano aprova só o merge final.)
- **NO2 — Revisão/correção autônoma e merge automático**: fora de escopo no MVP; merge continua manual.
- **NO3 — Wiring real validado contra Jira/Confluence/Slack de produção**: o MVP entrega os **seams** e um adapter local/Markdown operante + contratos; a validação contra instâncias reais é fase seguinte (depende de credenciais/MCP).
- **NO4 — Relaxar checkpoints (autonomia plena)**: os portões críticos permanecem obrigatórios; afrouxá-los é o destino, não a largada (§08, Fase 4).
- **NO5 — Whiteboards/diagramas gerados automaticamente no Confluence**: o adapter expõe o ponto de extensão; a geração rica de whiteboard fica para depois do wiring real.
- **NO6 — Multirrepositório / fila distribuída**: o MVP assume um repositório e uma fila local.

## Usuários
- **Operador do `sdd-layer`** (mantenedor): liga/desliga o modo autônomo, define políticas de gate e quem pode aprovar, observa a esteira e intervém. Jornada: `ligar autônomo → ver demandas avançando → receber pedido de aprovação → decidir`.
- **Engenheiro do time**: coloca uma demanda na fila e acompanha até "pronto para execução". Jornada: `enfileirar demanda → acompanhar etapa → aprovar/ajustar nos gates`.
- **PM / Tech Lead**: aprova PRD/Tech Spec/Refinamento sem abrir o terminal, decidindo com evidência (link local + externo). Jornada: `receber card no Slack → abrir artefato → aprovar/reprovar com comentário`.
- **Agentes da pipeline** (Idea→Refinamento): consomem estado durável e contexto/memória para produzir cada artefato de forma consistente.

### Notas de experiência (CLI/TUI)
- **Estados visíveis por demanda**: `na fila`, `planejando (etapa X)`, `aguardando aprovação (gate Y)`, `aprovado`, `reprovado/ajustar`, `pronto para execução`, `pausado/erro`.
- **CLI**: verbos claros — `enqueue`, `status`, `approve`, `reject`, `resume`; saída determinística e `--json` para automação.
- **TUI (esteira)**: coluna por etapa, sinal de cor para gate humano (cor de alerta, como em `pipeline.html`), e foco no item que aguarda decisão.
- **Copy de aprovação**: o pedido (CLI/Slack) sempre mostra *o que decidir*, *origem*, *link do artefato* (local + externo) e *riscos pendentes* — o contrato da skill `checkpoints`.

## Requisitos

### Requisitos funcionais
- **RF-01 — Enfileirar demanda**: o sistema DEVE permitir registrar uma demanda com `id`, `tipo` (épico/história/task/bug), `título`, `descrição` e `origem`, persistida de forma durável.
- **RF-02 — Ingestão dispara Idea**: ao entrar uma demanda nova na fila, o sistema DEVE criar a orquestração (`docs/<slug>/`) e produzir a etapa Idea automaticamente, sem ação humana.
- **RF-03 — Avanço durável do planejamento**: o sistema DEVE avançar Idea → PRD → Tech Spec → Tasks → Refinamento como máquina de estados, persistindo o estado após cada etapa.
- **RF-04 — Pausa nos checkpoints**: o sistema DEVE pausar em PRD, Tech Spec e Refinamento, persistir o estado e postar o pedido de aprovação, sem timeout.
- **RF-05 — Retomada idempotente**: ao receber aprovação, o sistema DEVE retomar exatamente da etapa seguinte; reiniciar o processo NÃO DEVE perder estado nem reexecutar etapa já concluída.
- **RF-06 — Aprovação por CLI**: o sistema DEVE aceitar `approve`/`reject` por CLI, com autor e timestamp, e efeito imediato na máquina de estados.
- **RF-07 — Aprovação por Slack (adapter)**: quando o adapter Slack estiver configurado, o sistema DEVE aceitar a mesma decisão por Slack (botão/comando), com paridade semântica e mesma trilha de auditoria.
- **RF-08 — Espelhamento por adapter com default local**: o sistema DEVE escrever todo artefato em `docs/<slug>/` (canônico) e, quando o adapter estiver configurado, espelhar/linkar em Jira (item/estado) e Confluence (página), guardando apenas o ponteiro no `traceability-map.yaml`.
- **RF-09 — Reprovação reabre etapa**: uma reprovação em um gate DEVE devolver a demanda para ajuste da etapa correspondente, registrando o motivo.
- **RF-10 — Observabilidade da esteira**: o sistema DEVE listar demandas e seus estados/etapas por CLI (`status`, com `--json`) e exibi-las na TUI em formato de esteira.
- **RF-11 — Handoff para execução**: ao aprovar Tasks/Refinamento, a demanda DEVE alcançar o estado "pronto para execução", expondo o contrato consumido pelo fluxo de execução existente (acionado manualmente no MVP).
- **RF-12 — Dedup de demanda**: o sistema NÃO DEVE iniciar duas orquestrações para o mesmo `id` de demanda.

### Requisitos não funcionais
- **RNF-01 — Durabilidade**: o estado da demanda DEVE persistir em disco e ser reconstruível após crash/restart, sem avanço duplicado (operações idempotentes).
- **RNF-02 — Segurança e privacidade**: nenhum segredo DEVE aparecer em artefatos ou logs (reuso de `src/runtime/redaction.rs`); a aprovação DEVE ter autoria verificável e respeitar a política de quem pode aprovar.
- **RNF-03 — Provider/harness-neutro**: o fluxo DEVE funcionar com qualquer provider configurado e degradar para Markdown/CLI quando faltarem tool calling, MCP ou browser.
- **RNF-04 — Compatibilidade**: comandos e TUI existentes DEVEM continuar funcionando; cobertura por `cargo test` para os novos módulos e para a não regressão dos fluxos atuais.
- **RNF-05 — Eficiência do observador**: a fila/observador NÃO DEVE fazer busy-poll; DEVE usar evento/intervalo configurável e concorrência limitada.
- **RNF-06 — Auditoria**: toda transição de estado e decisão de gate DEVE ser registrada em trilha local (jsonl) com timestamp.

### Regras de negócio
- **RN-01 — Refinamento obrigatório**: por risco `external_dependency`, o Refinamento NÃO pode ser pulado nesta feature.
- **RN-02 — Autoria separada (Três Amigos)**: humanos aprovam o comportamento a montante dos gates; o agente implementa a jusante. O agente nunca aprova o próprio checkpoint.
- **RN-03 — Não duplicar entre sistemas**: conteúdo vive em um sistema; os demais apenas referenciam por link.
- **RN-04 — Ordem fixa**: nenhuma etapa é pulada nem reordenada; a única opcionalidade (Refinamento) está suspensa por RN-01.
- **RN-05 — Pausa sem timeout**: um gate aguarda indefinidamente; nunca expira nem auto-aprova.

## Critérios de aceite
Notação combinada (`pipeline.html` §02): a regra EARS afirma; o Gherkin prova.

```gherkin
Funcionalidade: Ingestão da fila dispara a Idea
  Cenário: Demanda nova inicia a orquestração automaticamente
    Dado que o modo autônomo está ligado
    E que a fila está vazia
    Quando uma demanda "DEM-1" do tipo "história" entra na fila
    Então o sistema cria "docs/<slug-de-dem-1>/"
    E gera a etapa Idea sem ação humana
    E registra o estado "planejando (idea)" no traceability-map

  Cenário: Demanda duplicada não cria segunda orquestração
    Dado que a demanda "DEM-1" já está em orquestração
    Quando "DEM-1" entra na fila novamente
    Então nenhuma nova orquestração é criada
    E o evento é registrado como ignorado por dedup
```

```gherkin
Funcionalidade: Checkpoint durável com pausa e retomada
  Cenário: Pausa no gate do PRD
    Dado que a demanda "DEM-1" concluiu o PRD
    Quando o orquestrador alcança o checkpoint do PRD
    Então o estado é persistido como "aguardando aprovação (prd)"
    E um pedido de aprovação é postado com link local e (se configurado) externo
    E nenhuma etapa seguinte é executada

  Cenário: Retomada sobrevive a reinício do processo
    Dado que "DEM-1" está "aguardando aprovação (prd)"
    E que o processo do orquestrador foi reiniciado
    Quando uma aprovação de PRD chega por CLI
    Então o orquestrador retoma na etapa Tech Spec
    E não reexecuta o PRD
    E a aprovação fica registrada com autor e timestamp
```

```gherkin
Funcionalidade: Aprovação multicanal com paridade
  Cenário: Aprovar pelo Slack tem o mesmo efeito que pelo CLI
    Dado que o adapter Slack está configurado
    E que "DEM-1" está "aguardando aprovação (techspec)"
    Quando um aprovador autorizado aprova pelo Slack
    Então o orquestrador avança para Tasks
    E a trilha de auditoria registra canal "slack", autor e timestamp

  Cenário: Reprovação devolve a etapa para ajuste
    Dado que "DEM-1" está "aguardando aprovação (prd)"
    Quando o aprovador reprova com o motivo "escopo amplo demais"
    Então o estado volta para "planejando (prd) - ajustar"
    E o motivo fica registrado no traceability-map
```

```gherkin
Funcionalidade: Espelhamento com fonte canônica local
  Cenário: Sem adapter externo, o local é a fonte de verdade
    Dado que nenhum adapter externo está configurado
    Quando o PRD de "DEM-1" é aprovado
    Então o artefato existe em "docs/<slug>/02-prd.md"
    E o traceability-map marca prd como approved
    E nenhum sistema externo é exigido

  Cenário: Com adapter, espelha por link sem duplicar
    Dado que os adapters Jira e Confluence estão configurados
    Quando o PRD de "DEM-1" é aprovado
    Então a página do PRD é criada/atualizada no Confluence
    E o item correspondente no Jira aponta para ela por link
    E o traceability-map guarda os ponteiros externos
    E o conteúdo não é duplicado entre os sistemas
```

```gherkin
Funcionalidade: Segurança e compatibilidade
  Cenário: Nenhum segredo vaza para artefatos ou logs
    Dado um valor sensível presente no ambiente
    Quando qualquer artefato ou log é gerado
    Então o valor sensível aparece redigido
    E nunca em texto claro

  Cenário: Fluxo manual existente segue funcionando
    Dado o modo autônomo desligado
    Quando um humano roda as etapas pela CLI/TUI como hoje
    Então o comportamento é idêntico ao atual
    E os testes de não regressão passam
```

## Métricas
- **Time-to-Idea**: tempo entre a demanda entrar na fila e a Idea ficar pronta (meta: minutos, sem humano).
- **% de demandas que chegam ao gate do PRD sem toque humano**: meta alta (autonomia de planejamento até o primeiro gate).
- **Taxa de retomada bem-sucedida após restart**: meta 100% (durabilidade).
- **Incidentes de vazamento de segredo**: meta 0.
- **Regressões no fluxo manual**: meta 0 (suíte verde).
- **Latência de decisão no gate** (postagem → decisão): observada para calibrar canais (CLI vs Slack).
- **Cobertura de testes** dos novos módulos (fila, máquina de estados, adapters): meta alta, com casos de idempotência e dedup.

## Riscos
- **Avanço duplicado / corrida de estado** → mitigar com escrita idempotente, lock por demanda e transições atômicas (verificado por teste).
- **Perda de estado em crash** → persistência após cada transição + reconstrução na inicialização (critério de aceite de retomada).
- **Vazamento de segredo nos artefatos/logs** → redação obrigatória reusando `runtime/redaction.rs`; teste de não vazamento.
- **Autoria de aprovação forjada** → política de aprovadores + autoria registrada; Slack adapter valida identidade.
- **Acoplamento prematuro às integrações** → seams de adapter com default local; nada do núcleo depende de Jira/Confluence/Slack estar de pé.
- **Busy-poll do observador degradando a máquina** → observador por evento/intervalo com concorrência limitada (RNF-05).
- **Regressão no fluxo manual/TUI** (brownfield) → Agent Team em Tech Spec/Execução/Revisão e suíte de não regressão.
- **Escopo escorregar para execução autônoma** → NO1/NO2 explícitos; handoff é só estado + contrato no MVP.

## Diagramas

Marcador canônico: ```mermaid. Esta seção versiona o ciclo de vida durável, a sequência de ingestão e a anatomia do checkpoint para auditoria do PRD.

### Ciclo de vida durável de uma demanda
```mermaid
stateDiagram-v2
    [*] --> NaFila: enqueue(demanda)
    NaFila --> PlanejandoIdea: ingestão automática
    PlanejandoIdea --> PlanejandoPRD
    PlanejandoPRD --> GatePRD: checkpoint
    GatePRD --> PlanejandoTechSpec: aprovado (CLI/Slack)
    GatePRD --> PlanejandoPRD: reprovado (ajustar)
    PlanejandoTechSpec --> GateTechSpec: checkpoint
    GateTechSpec --> PlanejandoTasks: aprovado
    GateTechSpec --> PlanejandoTechSpec: reprovado
    PlanejandoTasks --> PlanejandoRefinamento
    PlanejandoRefinamento --> GateRefinamento: checkpoint (obrigatório)
    GateRefinamento --> ProntoParaExecucao: aprovado
    GateRefinamento --> PlanejandoRefinamento: reprovado
    ProntoParaExecucao --> [*]: handoff (execução = fase futura)
    note right of GatePRD
      Pausa indefinida.
      Estado persistido.
      Sem timeout.
    end note
```

### Ingestão → Idea (sequência)
```mermaid
sequenceDiagram
    participant Fonte as Fonte da demanda (CLI/Jira/webhook)
    participant Fila as Fila durável
    participant Orq as Orquestrador durável
    participant Store as docs/<slug>/ (canônico)
    participant Ext as Adapters (Jira/Confluence) [se configurado]
    Fonte->>Fila: enqueue(demanda)
    Fila->>Orq: evento "nova demanda"
    Orq->>Orq: dedup por id
    Orq->>Store: cria orquestração + Idea
    Orq->>Ext: cria/linka item (opcional)
    Orq->>Fila: marca "planejando (idea)"
```

### Anatomia do checkpoint (pausa/retomada)
```mermaid
flowchart LR
    A[Etapa concluída] --> B[Persiste estado em docs/&lt;slug&gt;]
    B --> C[Posta pedido: o quê + origem + link + riscos]
    C --> D{Aguarda sinal}
    D -- CLI approve --> E[Retoma na próxima etapa]
    D -- Slack approve --> E
    D -- reject --> F[Reabre etapa para ajuste]
    D -- (nada) --> D
```

> Excalidraw editável (mapa de adapters e fronteiras) fica para a Tech Spec, salvo em `docs/orquestrador-autonomo-de-demandas-sdd/assets/` se a colaboração visual ajudar.
