feat: uniform findings JSON — the diagnostics convergence (FR-E1, stacked on #112)

[HenryCFnord]

Stacked on #112 (base is that PR's branch — retarget to main after #112 merges; independent of #113). Draft until the base lands.

FR-E1 from the PSI feedback: "stable JSON on all commands, so an orchestrating agent branches on results without parsing prose." The investigation narrowed it to three commands — lint frontmatter, lint requirements, and trace markers — which still answered --format json with an unversioned findings/summary shape inherited from the retired Python reference checkers (path/rule/level instead of file/code/severity, no schema_version). Everything else already speaks the diagnostics contract (ADR-0006 layer 2, ICD Diagnostics).

The change

All three now emit the one documented payload:

{"schema_version": 1, "diagnostics": [
  {"severity": "error", "code": "FM-001", "message": "…", "file": "docs/…", "line": 12}
]}

• Checkers map Finding → shared Diagnostic and emit through diag::emit; the two duplicated oracle-shape emitters are deleted (net −23 lines).
• trace markers folds its findings (errors, with line) and kind warnings (warnings) into diagnostics and keeps tests_files/coverage_by_kind as additive keys.
• Text output and exit codes are byte-identical — only the JSON surface converges.

Process note: the superseded oracle pins

The three commands' JSON tests were oracle-shape pins. The shape they froze retired with its oracle (PR #88), so per the AGENTS.md rule the spec change landed first (REQ-04-01-10-03 on US-04-01-10, the canonical diagnostics story — goals-not-features: no new story), then the pins were rewritten to the new contract in the red commit, keeping their original requirement markers so no requirement loses verified coverage (ratchet stays green). A new cross-command test in tests/cli.rs verifies REQ-04-01-10-03 by driving all three surfaces in one scratch.

Red evidence (verbatim):

findings_surfaces_speak_the_shared_diagnostics_contract ... FAILED
lint_frontmatter_reports_contract_violations_as_json ... FAILED
lint_requirements_reports_authoring_violations_as_json ... FAILED
trace_markers_gates_test_functions_without_a_marker ... FAILED

All four green afterwards; full just ci green before every commit (unpiped log, exit 0).

Breaking change, deliberately

Consumers parsing the old checker JSON (the PSI corpus may) must switch findings→diagnostics, path→file, rule→code, level→severity, and derive counts instead of reading summary. The old shape carried no schema_version to negotiate with — that defect is exactly what this closes. The ICD diagnostics unit documents the converged surface.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Gie4jfrHKCxQktD2UsvH4Q

---

Generated by Claude Code