Report schema

pgdba check always writes pgdba-report.md (human) and pgdba-report.json (machine, agent-consumable) — the JSON is the stable contract:

• Findings carry stable IDs (<duty>.<check> style, e.g. connection.max_connections), severity, verb, plain-language why, cost_of_ignoring, ignore_if, and remediation SQL.
• summary_for_agents — a compact block intended for MCP/LLM consumers: the triage view (duty groups, grade, top actions) in one object.
• trend — when snapshot.json exists (via --state-dir): per-finding baseline / resolved / new / unchanged status and a runs-compared summary.
• config — provenance when a run-config file was used: {"path", "keys", "connection"}; null when no file was used.
• Audit log (apply/migrate runs) — applied / skipped / failed / retrying rows in execution order, with attempt counts.

Finding IDs are stable across runs and formats, so snapshots, deltas, webhooks, and agent consumers can correlate results over time. pgdba why <finding-id> prints the full plain-language explainer for one finding from the last report.

Severity levels

• critical — act now; also the --critical threshold trigger
• warning — schedule a fix
• info — context and hygiene