docs(release): explain require: coverage semantics — coverage-rules ≠ every V-level (#612)

[avrabe]

Closes #612 (the docs sliver — the implementation of ready-when + require: coverage already landed in REQ-240 / #641 and was confirmed working on gale).

What

rivet release status under require: coverage (REQ-240, #612) greens when the configured coverage-rules pass — which is not the same thing as "every verification level is present". The ASPICE swe1-has-verification rule ships as "≥ 1 of {sw-verification, unit-verification, sw-integration-verification}" at severity: warning, so a sw-req with just formal + system verification passes the rule and counts as ready even though rivet validate's granular breakdown still lists the per-level gaps as info. Both are internally correct — they answer different questions:

View	Question it answers
rivet release status under require: coverage	Does the schema's swe1-has-verification rule pass? (≥ 1 measure)
rivet validate granular breakdown	Is every declared verification level present? (per-level)

An ASIL-D (or DAL-A, IEC 62304 Class C) project that wants the gate to mean full per-level V-closure should express that in the schema's coverage-rules — split the ≥ 1-of-many rule into per-level rules at severity: error, or author project-specific coverage-rules — rather than reinterpret the command.

Changes

• docs/release-status.md (new, type: reference / status: current) — reference doc for rivet release status, the release: config, and the two readiness knobs. The precision note is the central section: it names the ≥ 1-vs-per-level distinction, gives a concrete before/after table using aspice's built-in rule (mirroring @avrabe's own gale confirmation matrix on docs: clarify require: coverage semantics — coverage-rules satisfied ≠ every V level present #612), and points ASIL-D projects at the schema-tightening options.
• rivet-cli/src/main.rs — the Status command's doc-comment (drives rivet release status --help) now cites REQ-240 / docs: clarify require: coverage semantics — coverage-rules satisfied ≠ every V level present #612, distinguishes the built-in status-only path from ready-when and require: coverage, and points readers at docs/release-status.md for the precision note.

Acceptance criteria (from #612 last comment, 17:37 UTC 2026-07-02)

#	Criterion	How this PR satisfies it
1	docs/release-status.md grows a section explaining require: coverage == "the configured coverage-rules are satisfied", NOT "every verification level is present". Concrete before/after example using an aspice-shaped swe1-has-verification warning-severity ≥ 1 rule.	New file created. "The precision note" section states the semantics exactly. "Concrete example" table below it walks the three-verdict matrix (default / ready-when: [approved] / require: coverage) on eleven aspice-flavoured sw-req artifacts, matching @avrabe's gale confirmation shape.
2	Names the choice an ASIL-D project should make: tighten the coverage-rules (per-level, severity: error) rather than rely on the built-in ≥ 1 warning — otherwise the green can overstate readiness.	"When '≥ 1 measure' isn't strict enough" section presents both concrete options (split the built-in rule; author project-specific per-level rules) and states each with severity: error.
3	rivet release status --help (or rivet.yaml --explain / rivet docs release) points to the new section.	The Status doc-comment in rivet-cli/src/main.rs now lands in --help with the precision note summary and an explicit see docs/release-status.md pointer. Verified live: ./target/release/rivet release status --help prints the pointer.
4	Regression: golden-file test if docs-test harness exists, else manual link check + rivet validate PASS.	No docs/ golden-file harness exists (rivet docs check is the closest — validates frontmatter and reference invariants, not content golden files). PASS on both mechanical gates: rivet validate PASS (450 warnings, unchanged from main), rivet docs check PASS (60 files scanned, 0 violations). Internal links checked by hand: docs/schemas.md, docs/verification.md, REQ-240, and #612 all resolve.
5	Commit trailers: Refs: REQ-XXX (the REQ anchoring the v0.23.0 release-readiness widening), Refs: #612.	Trailers are Refs: REQ-240 (REQ-240 anchors ready-when + require-coverage per the commit 61e297d) and Refs: #612. Exempt from Implements: because this PR is docs-only under CLAUDE.md's docs exempt type; Refs: carries the traceability.
6	Explicitly out of scope (file separately if wanted): any change to the coverage-rule semantics themselves; a new require: full-v-closure (per-level) mode.	Untouched. The doc names both options as schema-tightening choices for the consumer, not as new command modes.

Blog process pre-check

Re-fetched https://pulseengine.eu/blog/ at the start of this run. The blog carries the spec-driven-development / oracle-gated post that's already reflected in rivet's conventions; no team-workflow / branching / PR-flow / testing-conventions post overrides this PR.

Test plan

• rivet validate on the rivet repo — PASS (450 warnings, unchanged from main).
• rivet docs check on the rivet repo — PASS (60 files, 0 violations).
• cargo fmt --all --check — clean.
• cargo clippy -p rivet-cli --release --bins -- -D warnings — clean (the pre-existing MSRV mismatch between clippy.toml and Cargo.toml is untouched by this PR).
• ./target/release/rivet release status --help renders the new doc-comment with the REQ-240 / docs: clarify require: coverage semantics — coverage-rules satisfied ≠ every V level present #612 reference and the docs/release-status.md pointer.
• CI Format / YAML-lint / Docs Check / Clippy gates green on this branch.
• Reviewer smoke-test: read docs/release-status.md top-to-bottom on the assumption you're a new ASIL-D adopter — every design choice (ready-when, require: coverage, the ≥ 1-vs-per-level distinction) should be actionable from the page alone.

Not this PR

• Any change to what require: coverage computes — the command's contract stays exactly as REQ-240 shipped (schema coverage-rule satisfaction, purely additive to verified/accepted/ready-when).
• A require: full-v-closure per-level mode — an ASIL-D project can already reach that meaning by tightening the schema's coverage-rules; the doc names how.
• Repurposing docs: clarify require: coverage semantics — coverage-rules satisfied ≠ every V level present #612 further; the docs sliver was the last remaining item on it.

Commit trailer: Refs: REQ-240, Refs: #612 (docs is an exempt type per CLAUDE.md's commit-traceability section).

---

Generated by Claude Code — issue-triage agent run 2026-07-02.

---

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.

[github-actions]

⚠️ Performance Alert ⚠️

Possible performance regression was detected for benchmark 'Rivet Criterion Benchmarks'.
Benchmark result of this commit is worse than the previous benchmark result exceeding threshold 1.20.

Benchmark suite	Current: 14ce9cc	Previous: c7a59b3	Ratio
store_insert/10000	15859127 ns/iter (± 756215)	13019488 ns/iter (± 389061)	1.22
link_graph_build/10000	38228947 ns/iter (± 2003450)	24716536 ns/iter (± 1658759)	1.55

This comment was automatically generated by workflow using github-action-benchmark.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!