# Automations, hooks e eventos
Automação é a camada que acorda a pipeline, registra evidência e impede ações sem gate.
## Ordem de preferência
1. Evento push: webhook, Channel, callback de CI, Jira, Slack ou PR.
2. Polling temporário: scheduled task quando não há webhook confiável.
3. Hook local: validação determinística sob demanda, chamada pela CLI/CI ou por um harness em modo estrito.
## Hooks locais
| `sdd hook write-guard` | valida edição de código por agents read-only quando executado explicitamente; o fluxo automático padrão não instala esse hook em `PreToolUse` |
| `sdd hook bash-guard` | valida comandos destrutivos, force-push, merge, publish e deploy quando executado explicitamente; `git push` comum e dry-runs são permitidos |
| `sdd hook task-gate` | valida TaskCreated, TaskCompleted e TeammateIdle |
| `sdd hook trace-log` | grava auditoria de tool use |
| `sdd hook subagent-audit` | grava parada de subagents |
| `sdd hook notify` | notifica quando há input/permissão pendente |
Em clients interativos como Claude Code, os arquivos de hooks instalados pela camada SDD deixam os arrays de eventos vazios por padrão para não exigir intervenção humana durante loops automáticos. Para endurecer localmente, chame `sdd hook <nome>` no ponto desejado do harness, CI ou comando de release, em vez de transformar cada tool use do agente em checkpoint.
## Eventos externos recomendados
| Ideia criada | inicia PRD |
| PRD aprovado | inicia Tech Spec |
| Tech Spec aprovada | inicia Tasks |
| Refinement aprovado/dispensado | libera Execution |
| PR aberto | inicia Review |
| CI verde | completa evidência de Review |
| Review aprovado | libera checkpoint de merge |
| Deploy concluído | inicia Memory |
## Observabilidade local
Automations e hooks devem registrar eventos append-only e redigidos:
| `.sdd/events.jsonl` | eventos normalizados de tool use, geração, execução e checkpoints |
| `.sdd/runs.jsonl` | runs de comandos/stages do harness |
| `.sdd/task-gates.jsonl` | decisões de TaskCreated, TaskCompleted e gates de execução |
| `.sdd/subagents.jsonl` | início/fim de subagents e Agent Teams |
| `.sdd/execution-runs.jsonl` | execução task-by-task e evidências |
| `.sdd/evaluations.jsonl` | `sdd eval` e `sdd quality report` |
Eventos de provider precisam preservar `agent`, `selected_model`, `observed_model` quando reportado, `confidence`, uso/custo quando disponível e erro redigido. Não copie tokens, API keys, bearer tokens, passwords ou secrets para logs.
## Execução autônoma
`sdd auto run --real --through review|memory` pode materializar pós-planejamento quando a demanda já passou pelos gates humanos necessários. O motor não aprova merge, release ou deploy.
Estado e lock ficam em `.sdd/state/<slug>.json`. Em falha, o motor deve registrar `EngineStatus::Error`, preencher `last_error`, gravar evento e liberar o lock para não bloquear a demanda indefinidamente.
## Regra de segurança
Ausência de evento não é aprovação. Timeout não é aprovação. Comentário solto não é aprovação. Gate humano exige decisão explícita.