#192 docs+tests: define a shared JSON-output contract across the CLI's JSON commands

[Anonymous]

Originally created by: fu351

What

Doberman now has (or will shortly have) four independent --json/--jsonl CLI additions: scan --json (#178), doctor --json (#179), log --jsonl (#180), and policy-history --json (#190) — each independently restates the same contract in its own acceptance criteria ("emit exactly one valid JSON document/line on stdout, no Rich table or heading text mixed in, preserve redaction, deterministic ordering") and each PR will hand-roll its own "parse stdout with json, assert it's clean" test logic. Add (a) a "JSON output conventions" section to docs/CLI.md (#185) that states this contract once — flag naming (--json for a document vs --jsonl for one-object-per-line), the redaction guarantee, and the determinism guarantee — and (b) one shared pytest helper in tests/conftest.py (e.g. assert_json_stdout(result, jsonl=False)) that asserts "stdout is exactly one/N valid JSON value(s) and nothing else," for the four commands' tests to import instead of re-implementing the same parse-and-assert logic.

Difficulty: level-5

Requires reading all four sibling issues/PRs carefully enough to state one contract that's actually true of each (a JSON array and a JSON-Lines stream are genuinely different shapes — the helper must handle both without hiding that difference), without changing any of the four commands' behaviour.

Safety constraints (do not weaken these)

• The shared helper only asserts shape (valid JSON, nothing extraneous on stdout) — it must never replace or weaken any command's own redaction assertions (e.g. [#180]'s "a synthetic secret never appears in JSONL output"). Each command's test keeps its own redaction check.

Starting files

• docs/CLI.md — from issue [#185]; add a "JSON output conventions" section.
• tests/conftest.py — add the shared assertion helper here.
• src/doberman/cli/main.py — scan, doctor, log, policy_history commands, as their JSON flags land.

Acceptance criteria

• [ ] docs/CLI.md documents the shared JSON-output contract in one place (flag naming, array vs JSON-Lines, redaction, determinism).
• [ ] tests/conftest.py gains one reusable assert_json_stdout-style helper covering both the single-document and JSON-Lines cases.
• [ ] Existing tests for any already-merged JSON command (scan --json, doctor --json, log --jsonl, policy-history --json) may optionally be updated to use the shared helper, but this issue does not require rewriting PRs that already merged with their own equivalent assertions.
• [ ] Existing behaviour unchanged (no test weakened, no output format broken)
• [ ] ruff check . && ruff format --check . and lint-imports pass
• [ ] pytest passes

How to validate

pytest tests/ -k "json" -v

Out of scope

• Do not add a --json/--jsonl flag to any command yourself — this issue only documents and provides a shared test helper for flags added by #178/#179/#180/#190.
• Do not change any of those four commands' output shape.

Notes for contributors

New here? Start with CONTRIBUTING.md. Issues are labelled level-1 (docs only) through level-10 (new subsystem) — pick one at your level and climb. Comment to claim an issue before starting.

[Anonymous]

Ticket changed by: fu351

• status: open --> closed