fix(docs): make bridge-schema coverage rules discoverable (#895)

[avrabe]

Closes #895 — slice 1 (bridge-schema rule definitions are discoverable). Slice 2 (local-vs-external denominator distinction in coverage) is left for a follow-up PR, per the AC's explicit two-slice cut.

What changed

• rivet docs schema/<bridge> for the seven built-in bridges. Registered schema/eu-ai-act-aspice.bridge, schema/eu-ai-act-stpa.bridge, schema/iso-8800-stpa.bridge, schema/safety-case-eu-ai-act.bridge, schema/safety-case-stpa.bridge, schema/sotif-stpa.bridge, and schema/stpa-dev.bridge as DocTopic entries served by the embedded bridge YAML — the same shape non-bridge schema topics already ship, so the rule's source-type / required-link / target-types / severity are reachable via rivet docs.
• New Bridges category in rivet docs --list grouping the seven above plus a schema/bridges overview topic that names each bridge, its extends list, and how to read a failing coverage row.
• Inline remediation on failing rivet coverage rows. For each row whose percentage is neither 100.0% nor n/a, the text output now prints a <rule> needs: <link> ← [<target-types>] continuation line (→ for forward links, ← for backlinks). The line repeats the rule name so a plain rivet coverage 2>&1 | grep <rule> returns both the tally and the fix — exactly the case the issue describes for constraint-has-requirement. Empty-scope (0/0) and 100% rows are skipped; remediation isn't the question there. JSON output is unchanged.

Sample against the rivet repo itself:

  constraint-has-requirement     system-constraint          55       58    94.8%
    constraint-has-requirement needs: constraint-satisfies ← [requirement]
  controller-constraint-has-requirement controller-constraint  62      67    92.5%
    controller-constraint-has-requirement needs: constraint-satisfies ← [requirement]

Acceptance criteria — slice 1

• rivet docs schema/safety-case-stpa.bridge and rivet docs schema/stpa-dev.bridge (plus the other five bridges) print the same shape as rivet docs schema/dev — per rule, name + source-type + required-link + target-types + severity + description. The content is the raw bridge YAML, so every field the rule carries is exposed verbatim.
• The bridge schemas appear in rivet docs --list under a new Bridges group, so a user chasing a constraint-has-requirement failure can walk from the topic list to a bridge without knowing the bridge filename in advance. schema/bridges is the entry point that maps failing rule names back to their bridge.
• rivet coverage text output renders each failing (non-100%) rule with its required-link + target-types inline (default-on, since the AC's regression test uses plain rivet coverage). Empty-scope and 100% rows are exempt.
• Regression: rivet coverage 2>&1 | grep constraint-has-requirement on the rivet repo now returns both the tally row and the constraint-has-requirement needs: constraint-satisfies ← [requirement] line (see snippet above). Covered by an integration test.
• cargo test --workspace green (196 rivet-cli integration tests pass; workspace runs clean; a background workspace run is confirming the full slice).
• cargo fmt --all -- --check and cargo clippy --all-targets -- -D warnings clean.
• rivet validate PASS on this repo (779 warnings, unchanged from main).

Out of scope (per the AC, filed separately)

• Slice 2 — local vs. external subject denominators in coverage, --local-only, and the 3-state extension for cross-repo subjects. That's a coverage-semantics change, not a docs-discoverability one, and the AC explicitly cuts it into its own PR.
• The unmodelled-rules: modelled-as: <sibling-rule> extension (REQ-320 territory, not this issue).

Tests

• docs::bridge_topic_tests::every_embedded_bridge_has_a_docs_topic — pins the topic set to rivet_core::embedded::BRIDGE_SCHEMAS so a new bridge cannot ship without a discoverable topic. This is the invariant that would have caught the original bug at CI time.
• docs::bridge_topic_tests::bridge_topic_slug_registry_matches_topics, bridge_topics_are_categorized_as_bridges, bridge_topic_content_carries_the_coverage_rule_shape — pin the category, slug pattern, and payload shape.
• docs_list_groups_bridges, docs_show_bridge_topic — integration tests that hit the real binary.
• coverage_text_prints_required_link_for_failing_rules — integration test on the rivet repo itself. Finds a failing row, asserts a <rule> needs: line follows it, and separately grep-pins the requirement-coverage case as a specific regression anchor.

🤖 Generated with Claude Code

https://claude.ai/code/session_01E9RwnfmhwjDB8wPhuq9Prd

---

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.

[avrabe]

CI status on 1215a37: the Kani Proofs check failed. Standing down on it and not pushing a fix.

Grounds: this PR's diff touches rivet-cli/src/docs.rs, rivet-cli/src/main.rs, and rivet-cli/tests/cli_commands.rs only — no proof code. Kani Proofs is the check tracked in #839 ("Kani Proofs fails ~58% with exit 143 and has never passed on a push to main"), filed against the exact failure signature. The check run's output text is empty (annotation-only failure), consistent with the SIGTERM / needrestart pattern named there. Not re-running: #839 makes clear a re-run would not confirm anything a first run doesn't. No ported fix exists yet — #839 is still open.

Every other CI signal is either green or still in progress; I'll come back on those events. Watching until this PR is done.

---

Generated by Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!