Cross-org / supplier traceability: external-anchor + boundary-coverage MVP

[avrabe]

Problem

Rivet's traceability today is single-organization. As soon as a chain
crosses into a supplier's repo (or a non-rivet ALM tool), the link
goes dangling, coverage looks red, and the auditor cannot
distinguish "we forgot to satisfy this" from "the supplier owns
what's downstream". The user's framing:

Imagine a project involving several hardware and implementations
and spawning from several variations along the way as in-house. At
the same time I might have the topic that some of my components
are also to be used by someone else which might have a different
idea how the fields are mapped or even how this is being tracked
at all. How would we as of today prove an overall status of this
when e.g. saying we start from the top one and would like to get
all the linkage down to the smallest one or possibly have to say
"until here, and then an external provides me this and I can't
further link to their requirements" (think supplier management).

Design doc

Full research note (competitor survey, ISO 26262 / ASPICE pointers,
sphinx-needs / OSLC / ReqIF / AUTOSAR comparison, six-element design
proposal, open questions) lives at
docs/design/cross-org-supplier-traceability.md.

What's missing today

• No notion of "the chain ends here intentionally" — coverage is
  binary.
• No structured external link target (today's target: is a flat
  string).
• No federation handshake for non-rivet suppliers (ReqIF / OSLC /
  PDF deliveries).
• No field-mapping recipe at the artifact-import boundary
  (migrate.rs recipes work between schema versions, not between
  organizations).
• No provenance trail recording who delivered what, when, with
  which hash.

MVP scope (this issue, ~3 weeks)

Smallest version that demonstrates the boundary-coverage semantic
without adding any federation wires:

1. external-anchor artifact type in schemas/common.yaml
   with fields source-of-truth, expected-derived-types,
   received-status, optional contract-reference and
   cited-source (re-uses the typed field shipped in 0.7.0).
2. Three-state coverage in rivet-core/src/coverage.rs:
   classify a chain that terminates at an external-anchor whose
   expected-derived-types covers the missing rule type as
   EXTERNAL_BOUNDARY (not UNCOVERED). CoverageEntry gains
   external_boundary count + ID list.
3. rivet supplier list and rivet supplier check —
   read-only commands that surface anchors and boundary coverage.
4. Doc topic rivet docs supplier explaining the model, with
   a worked example (an OEM with one in-house and one supplier-
   delegated chain).

That alone makes the auditor story honest: "47 satisfied,
6 delegated to acme (boundary), 2 genuinely uncovered."

Phase 2 (separate issue)

• derives-from-external link type with structured target ({ org, contract, doc-id, last-synced, sha256, anchor }).
• cited-source backend for kind: reqif (read-only, sha at
  fetch time).
• rivet supplier pull <anchor-id> for kind: file | reqif,
  caching under .rivet/supplier-cache/<anchor-id>/.
• FederationProvenance block on imported artifacts.

Phase 3 (separate issue)

• Field-mapping recipes in schemas/supplier-mappings/.
• rivet supplier publish (manifest emission for rivet-to-rivet).
• OSLC / Polarion backends for cited-source.
• Variant-aware anchors (when: clause).
• rivet supplier promote <anchor-id> to convert delegated chain
  to first-party.

Open questions for scoping

• Subcommand placement: new top-level rivet supplier (recommended)
  vs extend rivet externals.
• Coverage display: single 100% sum with three colours
  (recommended) vs separate "supplier delegation" panel.
• Anchor lifecycle: never auto-delete; require explicit
  rivet supplier promote.
• Authentication: defer to Phase 2; MVP records source_hash per
  fetch which is the primitive every signing scheme needs.

Related

• Supply chain integration: Sigil attestations + SBOM/AIBOM + Rivet traceability bridge #107 — Supply chain integration (Sigil attestations + SBOM): the
  technical-supply-chain counterpart. This issue is about the
  organizational-supply-chain (OEM / tier-1 / tier-2). Both
  ultimately want signed manifests and provenance, and Phase 2
  could share the signing primitive with Supply chain integration: Sigil attestations + SBOM/AIBOM + Rivet traceability bridge #107.
• Externals: load each external repo's schemas alongside its artifacts #245 — "Externals: load each external repo's schemas alongside
  its artifacts": adjacent. The external-anchor type sidesteps
  the need to load the supplier's schema; we describe what we
  expect them to produce, not their full vocabulary.
• V&V coverage matrix dashboard via rivet coverage (per-commit, per-repo, per-technique) #188 — V&V coverage dashboard: the boundary-coverage state is a
  natural addition to the dashboard and would render as a third
  colour.

Standards / audit anchors

• ISO 26262 Part 8 §5 (Interfaces within distributed development)
  — DIA concept maps to external-anchor.
• ASPICE PAM 4.0 SUP.10 / SUP.8 — change & config across the
  OEM-supplier interface.
• OSLC Configuration Management — Phase 3 wire format candidate.
• ReqIF + Automotive ReqIF Implementation Guide — Phase 2 wire.
• sphinx-needs needs_external_needs — closest open-source prior
  art for "read-only federated needs".

Refs: REQ-020 (cross-repo links), REQ-025 (adapters), FEAT-001
(interop surface). Candidate new requirements:
REQ-NEW-supplier-anchor, REQ-NEW-boundary-coverage.

[avrabe]

Triage: the MVP-scope section has four numbered deliverables but no ## Acceptance Criteria block — the oracle-gated workflow (ref) needs testable bullets it can mechanically check on completion. Suggested lift from the MVP scope:

## Acceptance Criteria

- [ ] `external-anchor` artifact type added to `schemas/common.yaml` with fields `source-of-truth`, `expected-derived-types`, `received-status`, optional `contract-reference`, optional `cited-source`; `rivet validate` clean and round-trips via `rivet show`
- [ ] `rivet-core/src/coverage.rs` classifies a chain terminating at an `external-anchor` whose `expected-derived-types` covers the missing rule type as `EXTERNAL_BOUNDARY` (not `UNCOVERED`); `CoverageEntry` gains an `external_boundary` count and an ID list
- [ ] An `external-anchor` whose `expected-derived-types` does **not** cover the missing rule type still classifies as `UNCOVERED` (boundary delegation must be opted into per type)
- [ ] `rivet supplier list` (text + JSON) enumerates anchors, source-of-truth, expected-derived-types, received-status
- [ ] `rivet supplier check` reports per-chain status (satisfied / boundary-delegated / uncovered) and exits 0 unless `--strict` is set, in which case it exits 1 on uncovered
- [ ] `rivet docs supplier` topic with the OEM-with-one-in-house-and-one-supplier-delegated-chain worked example; `rivet docs check` clean
- [ ] Tests: coverage three-state golden test, anchor-without-coverage-type still UNCOVERED, supplier-list/check golden tests in text and JSON
- [ ] Commit trailers `Implements: REQ-010` (schema), `Implements: REQ-007` (CLI), `Refs: FEAT-001`

Open questions in the body that affect AC shape:

1. Subcommand placement — rivet supplier (recommended) vs extend rivet externals. Need to lock this before AC referencing the verb is binding.
2. Phase scope — the body lists Phase 2 and Phase 3 as separate issues; please confirm those are NOT part of this issue's AC so the scope stays bounded.

Once the placement question is answered and the AC lands in the body, this is a clean ~3-week implementation issue.

---

Generated by Claude Code — issue-triage agent run 2026-05-01.

---

Generated by Claude Code

[avrabe]

User decision: extend , broaden the framing

Per maintainer feedback (1 May): the new commands should live under rivet externals rather than a new rivet supplier tree. Reason: "supplier is not clear as the nature could be always something I won't further follow or can't" — the boundary case is broader than supplier relationships.

The MVP is boundary semantics, not specifically supplier integration. Examples that all map to the same shape:

• An external supplier owning the downstream chain
• An archived/sunset upstream we no longer track
• A third-party spec we cite but don't own
• A regulator-published doc with version history

All have the property: "the chain stops here; externally owned; we may or may not be able to follow further."

Updates to the design

• The proposed external-anchor artifact type stays.
• The proposed 3-state coverage (SATISFIED / EXTERNAL_BOUNDARY / UNCOVERED) stays.
• CLI commands move under rivet externals:
  • rivet externals anchor list — show all external-anchor artifacts
  • rivet externals anchor pull <uri> — pull-mode federation (Phase 2)
  • rivet externals coverage — boundary-aware coverage report
• The doc docs/design/cross-org-supplier-traceability.md should be renamed to docs/design/external-boundary-traceability.md to reflect the broader framing.

[avrabe]

Triage follow-up: the open scoping question from the 2026-05-01 triage comment was answered later that day in the maintainer reply — rivet externals placement, broader "external boundary" framing rather than supplier-specific.

The remaining blocker for an autonomous implementation run is purely editorial: the revised AC needs to land in the issue body so the oracle-gated workflow can pick it up. Suggested lift, reflecting the maintainer decision:

## Acceptance Criteria

- [ ] `external-anchor` artifact type added to `schemas/common.yaml` with fields `source-of-truth`, `expected-derived-types`, `received-status`, optional `contract-reference`, optional `cited-source`; `rivet validate` clean and round-trips via `rivet show`
- [ ] `rivet-core/src/coverage.rs` classifies a chain terminating at an `external-anchor` whose `expected-derived-types` covers the missing rule type as `EXTERNAL_BOUNDARY` (not `UNCOVERED`); `CoverageEntry` gains an `external_boundary` count and an ID list
- [ ] An `external-anchor` whose `expected-derived-types` does **not** cover the missing rule type still classifies as `UNCOVERED` (boundary delegation must be opted into per type)
- [ ] `rivet externals anchor list` (text + JSON) enumerates anchors, source-of-truth, expected-derived-types, received-status
- [ ] `rivet externals coverage` reports per-chain status (satisfied / external-boundary / uncovered) and exits 0 unless `--strict` is set, in which case it exits 1 on uncovered
- [ ] `rivet docs externals` topic gains a "boundary traceability" section with the OEM-with-one-in-house-and-one-externally-owned-chain worked example; `rivet docs check` clean
- [ ] Design doc renamed to `docs/design/external-boundary-traceability.md`
- [ ] Tests: coverage three-state golden test, anchor-without-coverage-type still UNCOVERED, externals-list/coverage golden tests in text and JSON
- [ ] Commit trailers `Implements: REQ-010` (schema), `Implements: REQ-007` (CLI), `Refs: FEAT-001`

Phase 2 / Phase 3 scope (federation pull, OSLC/Polarion backends, mappings, promote) stays explicitly out of this issue's AC, per the body.

Once these bullets land in the body, this becomes a clean implementation pickup.

---

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

---

Generated by Claude Code