# Qualidade e observabilidade

Este guia consolida os recursos que tornam o fluxo SDD mensurável, auditável e realista. A meta é eficácia verificável por contrato local, não promessa absoluta de LLM.

## Rastreabilidade

- Origem: evolução do motor autônomo, avaliação determinística e adapters por capacidade.
- Fonte canônica local: `docs/<slug>/traceability-map.yaml`.
- Estado operacional: comandos `sdd eval`, `sdd quality`, `sdd trace`, `sdd auto`, `sdd providers` e logs `.sdd/*.jsonl`.
- Próximo artefato esperado: Execution, Review ou Memory da orquestração em andamento.

## Comandos principais

```bash
sdd providers doctor --json
sdd health --json
sdd context build --name "<ciclo>" --stage execution --json --metadata-only
sdd context build --name "<ciclo>" --stage execution --write
sdd eval stage --name "<ciclo>" --stage techspec --json
sdd eval orchestration --name "<ciclo>" --json
sdd quality report --name "<ciclo>" --json
sdd trace summary --orchestration "<ciclo>" --json
sdd skills doctor --strict
sdd workflow validate agentic-sdd-loop --json
sdd workflow run agentic-sdd-loop --input "<demanda>" --max-iterations 3 --json
sdd workflow status --json
sdd clients sync --targets opencode --dry-run
sdd capabilities doctor --targets opencode
sdd auto run --real --through review
sdd auto run --real --through memory
```

## Avaliação determinística

`sdd eval stage` avalia um stage específico. `sdd eval orchestration` avalia a cobertura completa de uma orquestração. Ambos gravam resultados append-only em `.sdd/evaluations.jsonl`.

Os checks cobrem:

- seções obrigatórias declaradas em `.sdd/schemas/artifact-sections.json`;
- rastreabilidade mínima em artefatos materializados;
- presença ou justificativa de `## Diagramas` em PRD e Tech Spec, aceitando Mermaid, `.excalidraw`, `Não aplicável` ou companions `assets/diagrams/*.html|*.svg`;
- presença de `## Prompts Agent` em Tasks;
- freshness de Context Packs para `techspec`, `execution`, `review` e `memory`;
- existência e estado coerente do `traceability-map.yaml`;
- ponteiros de arquivos locais e links externos quando existirem.

Achados críticos bloqueiam avanço automático. O agente pode propor correção, mas não deve marcar stage como aprovado sem checkpoint humano quando o contrato exigir aprovação.

## Relatório de qualidade

`sdd quality report --name "<ciclo>" --json` agrega sinais de avaliação, rastreabilidade e ferramentas opcionais. O relatório também é persistido como evento `quality_report` em `.sdd/evaluations.jsonl`.

| Ferramenta | Quando usar | Fallback documentado |
|---|---|---|
| CodeGraph | mapa estrutural, impacto, callers/callees | `rg`, `git diff/status` e Context Pack |
| Lexa | grafo semântico quando houver índice | `rg`, `git diff/status` e Context Pack |
| `cargo llvm-cov` ou `cargo tarpaulin` | cobertura Rust | `cargo test` com lacuna registrada |
| `cargo audit` | vulnerabilidades Rust | Dependabot/GitHub Advisory review |
| `cargo deny` | licença, bans e supply chain | revisão manual de dependências/licenças |
| `gitleaks` | secrets no repositório | redaction central + revisão de diff |

Ferramentas ausentes não tornam o projeto inválido por si só. Elas precisam aparecer como fallback explícito no relatório para que a decisão humana saiba o que foi medido e o que ficou como lacuna.

Use `--force` em sync de clients apenas quando a intenção for sobrescrever arquivos gerados do client depois de revisar o plano com `--dry-run`.

## Economia de contexto

Use `sdd health --json` como primeira visão de manutenção quando a dúvida for saúde do fluxo, drift ou readiness geral. Ele é read-only e consolida otimização, intelligence health, workflow validate, clients/capabilities/skills doctor e, quando `--name` for informado, quality report da orquestração. O bloco `components.intelligence.repair_command` aponta o reparo explícito (`sdd intelligence repair ...`) para fechar `missing-memory` e `stale-learning`; sinais apenas informativos continuam visíveis sem degradar o status. Em clients MCP, use `sdd_readiness_summary` para transformar esses sinais mais MCP doctor, auto/workflow status e freshness do cache em um veredito `ready | warn | blocked` com próximos comandos recomendados.

Para execução e review, prefira começar por:

```bash
sdd context build --name "<ciclo>" --stage execution --json --metadata-only
```

Esse modo omite o Markdown completo e retorna `handoff.strategy`, `artifact_sources`, `probable_files`, `suggested_tests`, `stale`, `decision_conflicts`, `used_chars` e contadores. Só gere o Context Pack completo quando o handoff apontar conflito, lacuna ou necessidade real de ler trechos dos artefatos. Em loops de execução, use primeiro `handoff.suggested_tests`; comandos amplos ficam como fallback explícito.

## Ergonomia de sessão OpenCode

Os comandos e plugins OpenCode são complementos de qualidade, não fonte canônica:

- `/verify-changes` aplica um fluxo fail-fast antes de review ou handoff.
- `/team-review` executa review adversarial por segurança, arquitetura, testes, performance/release e contratos, em paralelo quando o client permitir.
- `/team-execution` só paraleliza tasks independentes com ownership de arquivos declarado.
- `/security-audit` e `/test-design` carregam rubricas SDD existentes para auditoria e plano de testes.
- `/fast-lane` permite iteração pequena apenas depois de `sdd risk` confirmar baixo risco.
- `sdd-security-scan.ts`, `sdd-verification.ts` e `sdd-parallel-guard.ts` são plugins opt-in; eles bloqueiam arquivos sensíveis ou emitem nudges, mas não formatam nem alteram arquivos automaticamente.

Valide a superfície com:

```bash
sdd clients doctor --strict
sdd capabilities doctor --targets opencode
```

## Motor autônomo

`sdd auto run --real --through review|memory` opera somente demandas em estado adequado para execução. Por padrão, ele não aprova PRD, Tech Spec, Refinement, merge, release ou deploy.

Para uma esteira 100% automática, use `sdd auto run --real --unattended`. Esse modo aceita PRD, Tech Spec e Refinement automaticamente, registra cada decisão em `.sdd/state/<slug>.json` com `channel: automation` e escreve eventos `gate_auto_accept` em `.sdd/orchestrator.jsonl`. Ele continua bloqueando avanço em avaliação crítica, erro de runner ou provider sem modo headless, e não aprova merge, release ou deploy.

O estado durável fica em:

```text
.sdd/state/<slug>.json
```

Esse arquivo registra status do motor, cursor, lock, aprovações, tentativas, tasks, evidências, testes e `last_error`. Em erro, o motor deve persistir `EngineStatus::Error`, registrar `last_error` e liberar o lock para que outro owner não pule a demanda indefinidamente.

## Logs append-only

| Arquivo | Conteúdo |
|---|---|
| `.sdd/events.jsonl` | eventos normalizados de execução, geração e checkpoints |
| `.sdd/runs.jsonl` | runs de stages e comandos do harness |
| `.sdd/execution-runs.jsonl` | execução task-by-task, tentativas, evidências e testes |
| `.sdd/evaluations.jsonl` | avaliações determinísticas e quality reports |
| `.sdd/subagents.jsonl` | auditoria de subagents/teams quando usados |
| `.sdd/task-gates.jsonl` | gates de tasks e decisões associadas |
| `.sdd/orchestrator.jsonl` | eventos do motor autônomo e demanda |
| `.sdd/workflows/<id>.json` | status durável da última execução de workflow |
| `.sdd/workflows.jsonl` | eventos de comandos registrados por workflow |

Todos os logs devem passar por redaction antes de persistir comandos, erros, stdout/stderr ou payloads de provider.

## Proveniência de agent e modelo

`agent` é o client/adapter efetivamente invocado pelo harness. Valores canônicos incluem `codex`, `claude-code`, `opencode`, `cursor-agent`, `devin`, `trae-agent`, `antigravity`, `sdd-harness` e `unsupported-workspace-execution`.

Para modelo:

- `selected_model`: modelo resolvido pelo SDD e enviado ao adapter.
- `observed_model`: modelo reportado pelo provider/CLI em metadata estruturada confiável.
- `confidence: "unreported"`: usado quando o provider não expõe metadata real.

Não trate `selected_model` como fato observado. Quando o provider só retorna texto, registre o modelo selecionado e deixe o observado vazio/não reportado.

Para uso de tokens e tempo de geração, trate contagens/timestamps reais como telemetria estruturada do adapter, não como segredo. Quando o provider/CLI reportar uso confiável, propague `SDD_USAGE_INPUT_TOKENS`, `SDD_USAGE_CACHED_INPUT_TOKENS`, `SDD_USAGE_OUTPUT_TOKENS`, `SDD_USAGE_REASONING_OUTPUT_TOKENS` e `SDD_USAGE_TOTAL_TOKENS` ao chamar `sdd <stage>` ou `sdd artifact save`; os artefatos gravam `Tokens source: provider-reported`. Para período real da geração, propague `SDD_GENERATION_STARTED_AT`, `SDD_GENERATION_EXECUTION_STARTED_AT`, `SDD_GENERATION_FINISHED_AT`, `SDD_GENERATION_DURATION_MS`, `SDD_GENERATION_REASONING_DURATION_MS` e `SDD_GENERATION_EXECUTION_DURATION_MS`; os artefatos gravam `Tempo source: provider-reported`. Sem telemetria real, o CLI grava estimativas/tempo local com source explícito.

## Adapters por capacidade

| Adapter | Geração de artefatos | Execução com escrita |
|---|---|---|
| Codex | `codex exec --json` | `codex exec --sandbox workspace-write` |
| Claude Code | `claude --print` | `claude --permission-mode acceptEdits` |
| opencode | `opencode run` | `opencode run --dangerously-skip-permissions` |
| Cursor Agent | `cursor agent --print` | `cursor agent --force` |
| Devin | `devin --print` | `devin --permission-mode dangerous` |
| Trae Agent | `trae-cli run` em diretório temporário | `trae-cli run --working-dir <root>` |
| Antigravity | `agy --prompt` | `agy --dangerously-skip-permissions` |

Provider sem adapter de escrita deve falhar explicitamente antes de executar o client. O evento de falha precisa preservar agent, modelo selecionado, modelo observado quando existir, comando tentado e motivo.

## Checklist de release

Antes de considerar uma orquestração pronta para merge/release:

```bash
cargo build --release
target/release/sdd mcp config --targets all --force
sdd ci --strict-release --name "<ciclo>"
sdd maintenance report --name "<ciclo>"
```

O gate strict/release executa Rust fmt/clippy/test all-features, `sdd health --strict`, workflow/clients/capabilities/skills doctors, bot build/test, docs generate/links/build e advisory checks. Gere antes as configs MCP locais quando estiver em checkout limpo/CI, porque `.mcp.json` e `.cursor/mcp.json` têm paths absolutos e continuam ignorados pelo Git. O `maintenance report` é a visão rápida por área: ele reaproveita health/doctors rápidos, mas marca core Rust, bot, docs, release e advisory como `skipped` quando apenas detecta a superfície e não executa os comandos caros.

Use checks opcionais quando disponíveis:

```bash
cargo llvm-cov
cargo audit
cargo deny check
gitleaks detect
npm audit --audit-level=high
npm sbom --sbom-format=cyclonedx
```

Se qualquer check opcional estiver ausente, registre o fallback usado no Review ou no Quality Report.
