feat(check): add rivet check docs oracle with --format json + --strict (#540)

[avrabe]

What

A new dedicated rivet check docs oracle that enumerates every candidate path the doc scanner considered and tags each loaded / skipped (<reason>) / excluded (<glob>). Default output is human text; --format json emits the canonical {oracle, entries, total, by_status} envelope; --strict exits non-zero when any entry is skipped (excluded allowlist matches do not trip strict — explicit opt-in).

How the kill-criterion is met

Fixed when rivet check docs … enumerates every candidate path … tags each loaded / skipped (<reason>) / excluded (allowlist), supports --format json, exits non-zero under --strict when any candidate is skipped.

• Enumerate: new rivet_core::document::scan_documents(dir, exclude) -> Vec<ScannedDoc> returns per-path detail. The existing load_documents_with_report is unchanged (other call sites — serve, validate — keep their byte-identical stderr-warning behavior).
• Per-path reason: each ScannedDoc carries status: Loaded | Skipped(reason) | Excluded(pattern); the reason for Skipped is verbatim what the scanner would have printed ("no YAML frontmatter" or the serde parse-error message).
• --format json: canonical envelope, snake-case, deterministic ordering.
• --strict: exits 1 on any Skipped. Excluded files don't trip it.

Tests

rivet-cli/tests/docs_check.rs (new): four fixture cases (loaded / no-frontmatter / missing-id frontmatter / excluded-by-glob), both --strict branches (skipped → exit 1; same files excluded → exit 0), and the human-text shape.

cargo fmt, cargo clippy --all-targets -- -D warnings, cargo test -p rivet-core -p rivet-cli, and rivet validate on the rivet repo itself are all clean.

Dogfood against the gale skip cases

The maintainer's verification target is gale's three live skips (mcuboot-coverage-analysis.md, release-plan.md, wasm-module-distribution.md). Those files don't live in this repo, but the mechanism is verified against synthetic fixtures with the same three failure modes (no-frontmatter, missing-id frontmatter, excluded-by-glob). On gale, rivet check docs --format json should show each of the three with its current reason and --strict should exit non-zero until they're fixed or excluded — exactly the issue's contract.

Draft note (process)

Opened as draft because https://pulseengine.eu/blog/ is returning HTTP 503 right now (same expired-TLS / site-infra symptom that's been on every recent triage thread — #420, #422, #431, #436, #456, #468, #479, #482, #488, #490, #500, #508, #509, #516, #522, #523, #530, #532, #538, #540), so the routine that opened this PR could not consult the authoritative process guidance the maintainer requires before opening a PR. The technical work and the kill-criterion are complete; please move out of draft once the blog is reachable and a quick process check passes (or if the local AGENTS.md guidance is sufficient — cargo fmt / cargo clippy --all-targets -D warnings / cargo test -p rivet-core -p rivet-cli / rivet validate are all clean, and the Implements: / Refs: trailers per CLAUDE.md are on the commit).

Closes #540.

---

Generated by Claude Code

[github-actions]

📐 Rivet artifact delta

No artifact changes in this PR. Code-only changes (renderer, CLI wiring, tests) don't touch the artifact graph.

[codecov]

Codecov Report

❌ Patch coverage is 0% with 55 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
rivet-core/src/document.rs	0.00%	55 Missing ⚠️

📢 Thoughts on this report? Let us know!

[avrabe]

Dogfood on gale's real docs/ — kill-criterion met on the live case (not just synthetic fixtures)

Built this branch (1feb9963) and ran rivet check docs against gale's actual docs/. All three clauses pass on the real files the issue was filed about:

rivet check docs (text) — exit 0:

skipped: docs/mcuboot-coverage-analysis.md: no YAML frontmatter
skipped: docs/release-plan.md: Schema error: document frontmatter: missing field `id`
skipped: docs/wasm-module-distribution.md: no YAML frontmatter

Total: 3 (loaded: 0, skipped: 3, excluded: 0)

rivet check docs --strict → exit 1 (non-zero with skips present — the CI gate works).

rivet check docs --format json → canonical envelope, each entry path/status/reason correct:

{ "oracle": "docs",
  "entries": [
    {"path":"docs/mcuboot-coverage-analysis.md","status":"skipped","reason":"no YAML frontmatter"},
    {"path":"docs/release-plan.md","status":"skipped","reason":"Schema error: document frontmatter: missing field `id`"},
    {"path":"docs/wasm-module-distribution.md","status":"skipped","reason":"no YAML frontmatter"} ],
  "total": 3, "by_status": {"loaded":0,"skipped":3,"excluded":0} }

So the three skip reasons render identically to what rivet validate's warning stream emits — confirms scan_documents matches load_documents_with_report on the real tree, and the JSON is directly assertable by an agent. This is exactly the queryable doc-visibility oracle the issue asked for; LGTM from the consumer side.

(Bonus, separately from this PR: gale now has a one-shot way to decide the standing skip — give those three docs valid frontmatter to make them trace-visible, or add them to docs[].exclude. That's a gale-side call, tracked on our end.)

No blocker from me — whenever the blog-503 process gate clears, this closes #540 cleanly.