---
name: checkpoints
description: Operar checkpoints humanos no pipeline Spec-Driven Development. Use ao definir, revisar ou executar gates de aprovação após PRD, após Tech Spec, após Refinement quando houver risco relevante, antes de merge/deploy, ou quando for necessário pausar um workflow durável aguardando decisão humana.
---

# Checkpoints SDD

## Objetivo

Transformar um ponto de parada em uma decisão verificável. Um checkpoint não é um resumo de progresso; é um pacote curto com artefato, evidência, riscos e consequência da decisão.

## Gates obrigatórios

Pare e peça aprovação explícita nestes pontos:

- PRD aprovado: confirma que o produto certo será construído.
- Tech Spec aprovada: confirma arquitetura, riscos e plano.
- Merge aprovado: confirma testes, review e aderência aos critérios.
- Deploy aprovado: confirma evidências de CI e plano de rollback.

Use Refinement como gate opcional quando houver múltiplas tasks, estimativas relevantes, flags, remote configs, migração, dados sensíveis ou dependência externa.

## Pacote de decisão

Antes de pedir aprovação, monte um pacote com:

- Resumo da decisão: o que será aprovado, rejeitado ou ajustado.
- Delta desde a origem: o que mudou em relação ao artefato anterior.
- Critério para aprovar: qual evidência torna a decisão segura o bastante.
- Evidências por tipo: artefato, testes, CI, diff, screenshot, diagrama, contrato, log ou link externo.
- Riscos pendentes: impacto, probabilidade, owner e mitigação.
- Consequência da decisão: o que acontece se aprovar, pedir ajustes ou rejeitar.

Use complementos quando aumentarem clareza:

- `output-quality`: para compactar o pacote em formato decisão-primeiro.
- `provider-compatibility`: quando a aprovação depender de capacidade que nem todo provider/client tem.
- `artifact-diagrams`: quando fluxo, arquitetura, estados ou dependências forem difíceis de entender só em texto.
- `design-flow`, `experience-design`, `frontend-design` e `visual-review`: quando o checkpoint envolver UI, UX, CLI/TUI ou experiência de usuário.
- `release-readiness`: antes de merge, deploy, rollout ou rollback.

## Protocolo

Ao chegar a um checkpoint:

1. Publique o artefato e o resumo da decisão.
2. Liste evidências objetivas por tipo: links, testes, screenshots, diagramas, logs, riscos e pendências.
3. Declare o critério mínimo para aprovação.
4. Peça uma decisão explícita: aprovar, pedir ajustes ou rejeitar.
5. Se houver ajustes, retorne à mesma etapa com o feedback.
6. Depois de aprovação explícita, salve o artefato aprovado em `docs/<slug-da-orquestracao>/` quando não houver fonte externa canônica.
7. Só avance depois de aprovação explícita e evidência salva.

Valide artefatos materializados com `sdd validate-artifact <tipo> <arquivo.md>`. No repo da camada, o schema vive em `schemas/artifact-sections.json`; em projetos instalados, normalmente vive em `.sdd/schemas/artifact-sections.json`.

## Formato de pedido

```md
## Checkpoint — <nome da etapa>
**Resumo:** <decisão em uma frase>
**Artefato:** <link/id>
**Arquivo local:** docs/<slug-da-orquestracao>/<arquivo-da-etapa>.md
**Origem:** <artefato anterior>
**Decisão necessária:** aprovar | pedir ajustes | rejeitar
**Critério para aprovar:** <evidência mínima>
**Evidências:** <links para spec, tasks, CI, review, screenshots, diagramas, logs>
**Riscos pendentes:** <nenhum | lista curta com owner>
**Se aprovado:** <próxima etapa>
**Se ajustes:** <para onde o feedback volta>
```

## Regras

- Nunca trate ausência de resposta como aprovação.
- Nunca permita que o mesmo agente que escreveu o critério seja a única validação do critério.
- Checkpoint não é status report; é decisão com evidência.
- Não peça aprovação com evidência genérica como "revisei o arquivo"; cite comando, arquivo, linha, screenshot, PR, CI ou artefato.
- Não avance com `approved` se o arquivo local ainda não foi salvo ou se o link externo canônico não existe.
- Para workflows duráveis, persista estado antes de notificar o humano.
