# PRD — Execução Paralela de Agent Teams no TUI

---

## Resumo

O SDD-layer executa tasks das etapas Execution e Review de forma estritamente sequencial. Isso desperdiça tempo quando tasks são independentes entre si — o caso mais comum nessas duas etapas — e o TUI não oferece visibilidade de progresso durante a execução. Esta feature introduz despacho paralelo de agent teams e um painel de acompanhamento em tempo real: lista de agentes, status individual, contador global e exibição isolada de falhas. Os artefatos finais só são gerados após todos os agentes concluírem.

---

## Objetivos

- **O-1**: Despachar múltiplos agent teams em paralelo nas etapas Execution e Review.
- **O-2**: Exibir painel de acompanhamento (lista de agentes, status individual, contador global) sem bloquear o loop de renderização.
- **O-3**: Garantir que os artefatos finais sejam gerados somente após todos os agentes concluírem.
- **O-4**: Isolar falhas por agente — um agente com erro não interrompe os demais.
- **O-5**: Preservar rastreabilidade: cada task deve ter um agente atribuído registrado no artefato de saída.

---

## Não objetivos

- Não paralelizar etapas diferentes entre si (fluxo sequencial de etapas permanece intacto).
- Não alterar o modelo de checkpoints humanos.
- Não implementar throttling de rate limit no MVP.
- Não configurar grau de paralelismo via UI no MVP.
- Não modificar `can_navigate` em `stage.rs`.
- Não paralelizar Idea, PRD, TechSpec, Tasks, Refinement e Memory.

---

## Usuários

**Engenheiro operador (primário)**: usa o sdd-layer diariamente como harness de orquestração no terminal. Valoriza eficiência e rastreabilidade; quer ver o que está acontecendo, identificar falhas rapidamente e ter confiança de que o artefato final só foi gerado quando tudo concluiu.

**Tech lead avaliador (secundário)**: aprova artefatos de Review. Precisa de confiança de que o artefato foi montado com base em todas as tasks, não apenas nas que terminaram primeiro.

---

## Requisitos

### Funcionais

| ID | Requisito |
|----|-----------|
| RF-01 | Despacho paralelo de agents na etapa Execution com base nas tasks aprovadas |
| RF-02 | Despacho paralelo de agents na etapa Review com base nas tasks aprovadas |
| RF-03 | Painel `ParallelRunning` no TUI: lista de AgentSlots, status individual, contador global |
| RF-04 | Status individual por AgentSlot: Aguardando / Em execução / Concluído / Erro |
| RF-05 | Contador global "X de N concluídos" atualizado em tempo real |
| RF-06 | Atualização assíncrona via channel/mpsc sem bloquear loop de renderização |
| RF-07 | Barreira de sincronização: artefato só gerado após todos os slots em estado terminal |
| RF-08 | Exibição isolada de erro por AgentSlot sem alterar os demais |
| RF-09 | Fluxo pós-barreira com erros: opções ao usuário (nenhuma ação automática) |
| RF-10 | Rastreabilidade no artefato final: task → AgentSlot → status final |
| RF-11 | Toda task aprovada recebe exatamente um AgentSlot (sem omissão nem duplicação) |
| RF-12 | Identificação determinística de tasks independentes por ausência de dependência declarada |

### Não-funcionais

| ID | Requisito |
|----|-----------|
| RNF-01 | Interface responsiva durante execução paralela (entrada de teclado sem atraso) |
| RNF-02 | Ausência de race conditions no estado compartilhado (reducer single-thread via channel) |
| RNF-03 | Suporte a ao menos 16 AgentSlots simultâneos sem degradação |
| RNF-04 | Layout legível em terminal de 80 colunas (sem panic) |
| RNF-05 | Encerramento limpo de subprocessos ao cancelar/encerrar (sem processos órfãos) |
| RNF-06 | Artefato determinístico em relação ao conjunto de resultados |
| RNF-07 | Lógica de AgentSlots testável sem terminal (reducers puros) |

### Regras de negócio

| ID | Regra |
|----|-------|
| RN-01 | Paralelismo restrito às etapas Execution e Review |
| RN-02 | Checkpoints humanos são invioláveis |
| RN-03 | Artefato final exige barreira completa (todos os slots em estado terminal) |
| RN-04 | Aceitar resultado parcial é decisão exclusiva do usuário |
| RN-05 | Uma task → um AgentSlot (sem duplicação nem omissão) |
| RN-06 | Falha isolada não cancela demais agentes |
| RN-07 | Rastreabilidade por agente é obrigatória no artefato final |
| RN-08 | Independência de tasks é determinística (baseada em declaração explícita) |

### Estados da tela ParallelRunning

| Estado | Descrição |
|--------|-----------|
| `Dispatching` | Agentes sendo despachados; slots inicializando |
| `Running` | Pelo menos um slot em execução; painel atualiza em tempo real |
| `Barrier` | Todos em estado terminal; aguardando decisão/composição |
| `PartialError` | Barreira atingida com erros; aguarda decisão do usuário |
| `Composing` | Artefato final sendo gerado |
| `Done` | Artefato gerado; TUI avança para Checkpoint |

### Estados de um AgentSlot

| Estado | Símbolo | Cor |
|--------|---------|-----|
| Aguardando | `○` | Neutro |
| Em execução | spinner | Acento primário |
| Concluído | `✓` | Verde |
| Erro | `✗` | Vermelho |

---

## Critérios de aceite

```gherkin
Funcionalidade: Despacho paralelo de agentes na etapa Execution

  Cenário: Tasks independentes são despachadas em paralelo
    Dado que estou na tela StageBoard com Execution selecionada
    E o artefato 04-tasks.md contém 4 tasks sem dependência entre si
    Quando inicio a execução da etapa
    Então o TUI exibe o painel ParallelRunning com 4 AgentSlots
    E todos os 4 slots iniciam execução sem aguardar o anterior
    E o contador exibe "0 de 4 concluídos"

  Cenário: Painel atualiza sem bloquear a interface
    Dado que o painel ParallelRunning está ativo com agentes em execução
    Quando um agente conclui sua task
    Então o status desse slot muda para "Concluído" imediatamente
    E o contador global é incrementado
    E a entrada de teclado continua respondendo

  Cenário: Barreira impede geração de artefato antes do término
    Dado que 3 de 4 agentes concluíram
    Então o artefato 06-execution.md ainda não é gerado
    E o painel exibe "3 de 4 concluídos"

  Cenário: Artefato gerado após todos os agentes concluírem
    Dado que todos os 4 AgentSlots estão em "Concluído"
    Quando a barreira é liberada
    Então o sistema compõe o artefato 06-execution.md
    E o artefato inclui rastreabilidade por task e agente
    E o TUI avança para Checkpoint

Funcionalidade: Tratamento isolado de falhas

  Cenário: Falha em um agente não cancela os demais
    Dado que o AgentSlot de "T-03" entra em estado de erro
    Então os demais 3 slots continuam em execução
    E o TUI não exibe mensagem de cancelamento global

  Cenário: Barreira com erros apresenta opções ao usuário
    Dado que todos os slots atingiram estado terminal com pelo menos um em Erro
    Então o TUI exibe: "Retentar falhos", "Aceitar resultado parcial", "Cancelar etapa"
    E nenhuma ação ocorre automaticamente

  Cenário: Aceitar resultado parcial registra tasks não concluídas
    Dado que 1 slot está em Erro e 3 em Concluído
    Quando o usuário escolhe "Aceitar resultado parcial"
    Então o artefato inclui seção explícita com a task não concluída e motivo do erro

Funcionalidade: Mesmo comportamento na etapa Review

  Cenário: Tasks de Review são despachadas em paralelo
    Dado que inicio a etapa Review com tasks de revisão independentes
    Então o TUI exibe ParallelRunning com um AgentSlot por task

  Cenário: Artefato 07-review.md gerado após barreira completa
    Dado que todos os AgentSlots da Review estão em estado terminal
    Então o sistema compõe o artefato 07-review.md com rastreabilidade por agente

Funcionalidade: Responsividade e resiliência

  Cenário: Interface não trava com 8 agentes ativos
    Dado que 8 AgentSlots estão em execução simultânea
    Quando pressiono qualquer tecla de navegação válida
    Então a ação é processada sem atraso perceptível

  Cenário: Encerramento limpo ao cancelar etapa
    Dado que o painel ParallelRunning está ativo com agentes em execução
    Quando o usuário cancela a etapa
    Então todos os subprocessos são encerrados sem processos órfãos
```

---

## Métricas

| Métrica | Referência | Meta |
|---------|-----------|------|
| Tempo de Execution com N tasks independentes | Sequencial: N × T_médio | Paralelo: próximo de T_máx |
| Tempo de Review com N tasks independentes | Sequencial: N × T_médio | Paralelo: próximo de T_máx |
| Tasks com agente atribuído | 100% das tasks aprovadas | Manter 100% |
| Falhas mascaradas (erro não reportado) | 0 tolerado | 0 |
| Panic em TUI durante execução paralela | 0 tolerado | 0 |
| Artefatos sem rastreabilidade de agente | 0 tolerado | 0 |

---

## Riscos

| ID | Risco | Probabilidade | Impacto | Mitigação |
|----|-------|--------------|---------|-----------|
| RP-01 | Race condition no estado compartilhado | Média | Alto | Eventos via channel; reducer single-thread |
| RP-02 | Artefatos conflitantes de agentes paralelos | Média | Alto | Protocolo de composição definido na TechSpec |
| RP-03 | Rate limiting de providers sem throttle | Alta | Médio | Risco aceito no MVP; monitorar via telemetria |
| RP-04 | Processos órfãos em encerramento abrupto | Baixa | Médio | Cleanup no Drop / signal handler |
| RP-05 | Usuário não entende resultado parcial | Média | Alto | Copy clara; seção de aviso explícita no artefato |

---

## Rastreabilidade

- Slug: `tui-team-agents-execution-review`
- Origem: `docs/tui-team-agents-execution-review/01-idea.md`
- Caminho: `docs/tui-team-agents-execution-review/02-prd.md`
- Próximo: `docs/tui-team-agents-execution-review/03-techspec.md`
- Módulos impactados: `src/tui/app.rs`, `src/tui/runner.rs`, `src/tui/stage.rs`, `src/tui/ui.rs`, `src/tui/mod.rs`
