# 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.
