# Contratos de artefato
Os schemas em `.sdd/schemas/artifact-sections.json` definem as seções mínimas de cada artefato. Eles não substituem julgamento técnico; servem para impedir que a pipeline avance com documentos incompletos.
## Validação
```bash
sdd validate-artifact prd caminho/para/prd.md
sdd validate-artifact techspec caminho/para/techspec.md
sdd validate-artifact review caminho/para/review.md
sdd eval stage --name "<orquestracao>" --stage techspec --json
sdd eval orchestration --name "<orquestracao>" --json
sdd quality report --name "<orquestracao>" --json
sdd workflow status --json
```
`validate-artifact` valida o arquivo isolado. `sdd eval stage` e `sdd eval orchestration` validam o artefato dentro do ciclo, usando `docs/<slug>/traceability-map.yaml`, Context Packs e estado da orquestração. `sdd quality report` agrega sinais de avaliação e ferramentas opcionais. Resultados são persistidos em `.sdd/evaluations.jsonl`.
## Persistência local
Quando Jira/Confluence/etc. não forem a fonte canônica, salve os artefatos da orquestração em `docs/<slug-da-orquestracao>/`:
```bash
sdd init "<nome-da-orquestracao>"
sdd artifact save "<nome-da-orquestracao>" prd --file caminho/para/prd.md --state approved
```
O arquivo `traceability-map.yaml` do diretório local registra o estado das etapas e os links externos quando existirem.
## Gates de avanço
O avanço automático deve parar quando a avaliação retornar erro crítico. O agente pode corrigir artefatos e reavaliar, mas checkpoints humanos continuam obrigatórios para PRD, Tech Spec, Refinement quando aplicável, Review/merge e deploy.
Os checks determinísticos cobrem:
- seções obrigatórias do schema;
- `Rastreabilidade` com origem, estado, owner/evidências e próximo artefato;
- `## Diagramas` em PRD/Tech Spec ou justificativa de `Não aplicável`;
- `## Prompts Agent` em Tasks;
- freshness de Context Packs em Tech Spec, Execution, Review e Memory;
- coerência do `traceability-map.yaml` com arquivos locais.
Workflows em `templates/workflows/*.yaml` podem produzir ou pausar artefatos, mas não alteram o contrato de seções obrigatórias. Use `sdd workflow validate <id>` para validar a recipe e `sdd eval`/`sdd validate-artifact` para validar o conteúdo produzido.
## Seção obrigatória em todos os artefatos principais
```md
## Rastreabilidade
- Origem:
- Estado atual:
- Dono humano:
- Evidências:
- Próximo artefato:
```
## PRD
Precisa conter problema, objetivos, não objetivos, usuários, requisitos, critérios de aceite, métricas e riscos.
## Tech Spec
Precisa conter arquitetura, contratos, dados, segurança, performance, observabilidade, testes, riscos e plano.
## Tasks
Cada task precisa ter origem, critérios de aceite, Definition of Done e dependências.
Tasks também precisam conter `## Prompts Agent` com prompts standalone, provider-neutral, suficientes para execução sem memória da conversa. Inclua objetivo, escopo, arquivos prováveis, constraints, passos, validação, DoD e formato do relatório final.
## Refinement
Consolida o backlog em plano executável: solução, pontos de observação, checklist, subtasks, DoD e flags/configurações.
## Review
Precisa trazer escopo revisado, evidências, achados, testes e veredito.
## Memory
Compacta estado final, links, decisões, padrões úteis, comandos, pendências e contexto para o próximo agente.
## Evidências mínimas por artefato
| Artefato | Evidência esperada |
|---|---|
| PRD | decisão humana, critérios de aceite, riscos e métricas |
| Tech Spec | decisões técnicas, contratos, diagramas e plano de testes |
| Tasks | backlog executável, prompts agent e ordem sugerida |
| Execution | arquivos alterados, comandos/testes, decisões e erros relevantes |
| ADR | decisão arquitetural detectada ou marcada, alternativas e consequências |
| Review | diff revisado, testes, achados por severidade e veredito |
| Memory | links finais, decisões, padrões e pendências |