# Workflows dinâmicos determinísticos
Este documento descreve a DSL YAML e o runner de `sdd workflow`. Workflows são recipes locais para encadear etapas, skills, comandos, avaliações e checkpoints com limites explícitos de iteração.
## Visão geral
Workflows não substituem o fluxo SDD nem checkpoints humanos. Eles oferecem uma forma determinística de declarar loops operacionais como:
- planejamento padrão até o primeiro gate;
- execução seguida de avaliação e review até passar ou atingir limite;
- discovery + hardening de skills/capabilities;
- diagnóstico de bug com reproduzir, alterar, testar e revisar.
Runtime adapters como LangGraph, Rig, Agno, Flue ou outros podem ser adicionados depois, mas o contrato v1 funciona apenas com YAML, artifact store local, `.sdd/*.jsonl` e comandos `sdd`.
## Comandos
```bash
sdd workflow list
sdd workflow list --json
sdd workflow validate standard-sdd
sdd workflow validate templates/workflows/deep-execution-review.yaml --json
sdd workflow run standard-sdd --input "Criar busca por tags" --max-iterations 10 --json
sdd workflow run deep-execution-review --input "Corrigir regressão" --max-iterations 3 --json
sdd workflow status
sdd workflow status deep-execution-review --json
```
Use `sdd workflow --root <path> ...` para operar um projeto instalado fora do diretório atual.
## Localização
O CLI procura workflows em:
1. `templates/workflows/<id>.yaml` do projeto alvo;
2. `templates/workflows/<id>.yaml` da camada SDD;
3. caminho explícito passado como argumento.
Resultados de execução são persistidos em:
```text
.sdd/workflows/<workflow-id>.json
```
Comandos declarados em nodes `command` também registram eventos em `.sdd/workflows.jsonl`.
## DSL v1
Campos de topo:
| Campo | Obrigatório | Uso |
|---|---:|---|
| `version` | sim | Versão da DSL. Deve ser `1`. |
| `id` | sim | Identificador do workflow. |
| `title` | sim | Nome legível. |
| `inputs` | não | Descrição dos inputs esperados. |
| `nodes` | sim | Lista ordenada de passos. |
| `edges` | não | Transições entre nodes. |
| `max_iterations` | condicional | Obrigatório quando houver loop/back-edge. |
IDs de workflow e nodes aceitam letras ASCII, números, `-` e `_`.
## Nodes
Cada node declara `id`, `action` e metadados conforme o tipo.
Actions aceitas:
| Action | Campos esperados | Uso |
|---|---|---|
| `stage` | `stage` | Representa uma etapa SDD como `prd`, `execution` ou `review`. |
| `skill` | `skill` | Aciona uma skill por contrato operacional. |
| `eval` | `stage` opcional | Representa avaliação determinística de artefato/estado. |
| `checkpoint` | `stage` | Pausa aguardando decisão humana. |
| `parallel` | opcional | Reserva para fan-out controlado. |
| `command` | `command` | Registra comando determinístico no trace do workflow. |
| `notify` | opcional | Representa notificação/handoff. |
Exemplo:
```yaml
nodes:
- id: execution
action: stage
stage: execution
description: Execute the current task with fresh evidence.
- id: eval
action: eval
stage: execution
- id: gate
action: checkpoint
stage: prd
```
## Edges e loops
Edges usam `from`, `to` e `condition` opcional.
```yaml
edges:
- from: execution
to: eval
- from: fix
to: execution
condition: retry
```
Regras de validação:
- action desconhecida falha;
- node intermediário sem edge de saída falha;
- edge para node inexistente falha;
- loop/back-edge sem `max_iterations` falha;
- checkpoint com comando contendo `approve` falha;
- checkpoint só aceita `stage` em `prd`, `techspec`, `refinement`, `review` ou `deploy`.
O runner conta iterações quando percorre uma edge de retorno. Ao atingir o limite, retorna `status: "iteration_limit"` e persiste o relatório.
## Checkpoints
Nenhum workflow autoaprova gate humano. Um node `checkpoint` pausa e retorna `status: "awaiting_checkpoint"` com mensagem de gate. A decisão continua sendo feita por comandos explícitos, como:
```bash
sdd demand approve <id> --gate prd --by "<pessoa>"
sdd demand reject <id> --gate prd --reason "<motivo>"
```
Use checkpoints para PRD, Tech Spec, Refinement, Review, merge, release e deploy quando aplicável.
## Workflows embutidos
### `agentic-sdd-loop`
Recipe de entrada para agents e automações. Resolve a entrada, delega o planejamento durável para `standard-sdd`, persiste o status do workflow e pausa no checkpoint de PRD.
```bash
sdd workflow validate agentic-sdd-loop --json
sdd workflow run agentic-sdd-loop --input "Criar busca por tags" --max-iterations 3 --json
```
Depois do checkpoint humano, continue com `sdd demand approve`, `sdd auto run --real`, `sdd auto run --real --through review` ou `sdd auto run --real --through memory`, conforme o gate aprovado e a capacidade do provider/adapter. Para execução 100% automática, chame o motor explicitamente com `sdd auto run --real --unattended`; esse modo autoaceita gates de planejamento como `channel: automation`, não como decisão humana. O guia completo fica em `docs/AGENTIC-SDD-LOOP.md`, e o caminho de uso recomendado aparece em `docs/USAGE.md`.
### `standard-sdd`
Equivalente ao caminho de planejamento do motor autônomo até o primeiro gate. Enfileira a entrada como demanda durável quando `--input` é informado, roda o motor determinístico e para em PRD aguardando aprovação.
```bash
sdd workflow run standard-sdd --input "Criar busca por tags" --max-iterations 10 --json
```
Status esperado até o primeiro gate:
- `produced`: inclui `idea` e `prd`;
- `paused`: inclui o slug da demanda;
- `status`: `awaiting_checkpoint`.
`sdd auto run` permanece compatível. A diferença é que `workflow run standard-sdd` também persiste um relatório em `.sdd/workflows/standard-sdd.json`.
### `deep-execution-review`
Loop de execução, avaliação, review e correção até passar ou atingir `max_iterations`.
```bash
sdd workflow run deep-execution-review --input "Corrigir regressão" --max-iterations 3 --json
```
No runner atual, actions de stage/skill/eval são eventos determinísticos; adapters reais podem ser acoplados depois ao mesmo contrato.
### `discovery-skill-hardening`
Sequência para endurecer contexto de projeto:
1. discovery;
2. `sdd skills recommend --write`;
3. `sdd skills doctor --strict`;
4. `sdd capabilities doctor --targets all`.
Use quando a stack mudar, quando um projeto receber a camada pela primeira vez ou antes de distribuir skills para clientes.
### `bugfix-diagnostic-loop`
Loop de diagnóstico de bug com limite de 3 ciclos:
1. reproduzir;
2. inspecionar impacto;
3. alterar;
4. testar;
5. revisar;
6. voltar para reprodução se falhar.
## Relatório de execução
Formato persistido:
```json
{
"workflow_id": "deep-execution-review",
"status": "iteration_limit",
"iterations": 2,
"events": [
{"node": "execution", "action": "stage", "status": "ok"}
],
"produced": [],
"paused": [],
"ready": [],
"errors": []
}
```
Campos:
| Campo | Uso |
|---|---|
| `workflow_id` | ID executado. |
| `status` | `completed`, `awaiting_checkpoint`, `ready_for_exec`, `iteration_limit` ou `error`. |
| `iterations` | Quantidade de ciclos/retornos percorridos ou ticks do motor para `standard-sdd`. |
| `events` | Eventos de nodes executados pelo runner genérico. |
| `produced` | Artefatos produzidos pelo motor SDD quando aplicável. |
| `paused` | Demandas pausadas em gate humano. |
| `ready` | Demandas prontas para execução. |
| `errors` | Erros redigidos. |
## Workflow customizado mínimo
```yaml
version: 1
id: review-gate
title: Review Gate
inputs:
input: Pull request, diff or release candidate.
nodes:
- id: review
action: stage
stage: review
description: Review diff and evidence.
- id: gate
action: checkpoint
stage: review
description: Pause for human review decision.
edges:
- from: review
to: gate
```
Valide antes de usar:
```bash
sdd workflow validate templates/workflows/review-gate.yaml
```
## Relação com artifact store e observabilidade
Workflows usam o mesmo estado durável do SDD:
- demandas em `.sdd/queue/`;
- estado do motor em `.sdd/state/<slug>.json`;
- relatórios em `.sdd/workflows/<id>.json`;
- eventos append-only em `.sdd/workflows.jsonl`, `.sdd/orchestrator.jsonl`, `.sdd/events.jsonl` e `.sdd/evaluations.jsonl`;
- artefatos em `docs/<slug>/`.
MCP e trace podem consultar esses dados, mas não aprovam gates nem substituem `traceability-map.yaml`.
## Boas práticas
- Declare `max_iterations` sempre que houver qualquer retorno no grafo.
- Use `command` para comandos determinísticos e auditáveis, não para comandos destrutivos.
- Use `checkpoint` em vez de tentar aprovar por comando.
- Mantenha workflows curtos; detalhes longos devem ficar em docs ou skills.
- Rode `sdd workflow validate` em CI para workflows customizados.
- Rode `sdd skills doctor --strict` e `sdd capabilities doctor --targets all` quando workflows dependerem de skills/capabilities novas.