No reverse-link view from get/list: verifying 'is this requirement implemented?' needs req→satisfying-tests→run-commands, only reachable via raw YAML

[avrabe]

Follow-up to #353 (same task class — bulk planned/draft → implemented — but on spar, rivet 0.13.3 (b55a9c6f release/v0.14.0)). #353 covers modify/validate ergonomics; this is one distinct gap not covered there: you can't see an artifact's incoming links from the per-artifact commands, which makes evidence-gated status promotion harder than it should be.

The task that exposed it

To promote a requirement to implemented with evidence (not just because a link exists), I wanted, per requirement: the tests that satisfies it → their run commands → run them → promote only if green. Walking that chain from the CLI turned out to be the hard part.

What was hard

In this schema the satisfies edges live on the verification/feature artifacts and point at the requirement. So from the requirement's own view there's nothing to see:

• rivet get REQ-MIGRATION-001 --format json → "links": []. The links array is outbound-only; there is no incoming/reverse view. Inspecting the requirement tells you nothing about what verifies it.
• rivet list --type requirement --format json → collapses links to an integer count ("links": 3), not the link objects — so it's not usable to inspect the graph programmatically either.

Net: the single most common traceability question — "what verifies X?" — is unanswerable from the two commands an agent naturally reaches for when inspecting X.

What finally helped

rivet matrix with --direction backward has the reverse edges:

rivet matrix --from requirement --to feature --link satisfies --direction backward --format json
# rows: [{ "source_id": "REQ-MODEL-002", "targets": ["TEST-WORKSPACE","TEST-HIR-DEF"] }, ...]

This is the right primitive, but (a) it wasn't discoverable from get/list, and (b) it returns only target IDs — to get the executable evidence I still had to load verification.yaml and read each test's fields.steps[].run myself. So the end-to-end walk req → tests → commands still required hand-parsing the source YAML; matrix got me one hop, not the payload.

Asks (agent ergonomics)

1. Show incoming links in rivet get <ID> (text + --format json), e.g. an incoming_links: [{type, source}] array, or a --reverse/--incoming flag. Inspecting one artifact should reveal both what it links to and what links to it.
2. rivet list --format json should emit the real links array, not a count (matches a point implied in Friction marking requirements implemented in a real project (rivet 0.13.3): silent file-skip, validate baseline noise, loop-modify no-op #353's agent-ergonomics asks).
3. (nice-to-have) let matrix/get optionally inline the target's fields (or at least method + run steps) so an agent can reach the runnable evidence without re-parsing source YAML.

Outcome on spar (for context)

Used the matrix-reverse + YAML-parse workaround to map 30 non-implemented requirements to their satisfying tests, ran the suites (cargo test across 9 crates, --no-fail-fast, exit 0 / all green), and promoted 25 planned → implemented (held back 3 with only Kani/Lean verification I couldn't run locally + 2 deliberately-partial). rivet validate held at FAIL (190 errors, 160 warnings, **0 broken cross-refs**) before and after — no structural regression.

Happy to share the spar reverse-mapping script if useful.

[avrabe]

Valid and already on the roadmap — this is REQ-128 (rivet list --orphans + a structural backlink view surfacing LinkGraph::backlinks_to). The #349 reporter independently asked for the same thing ('rivet get should show inbound backlinks' / 'rivet why'), and it pairs with REQ-125 (validate/coverage --explain). Three independent reports now converge on backlink-visibility as the top DX gap — bumping its priority accordingly. Tracked.

[avrabe]

Valid and high-value — verified the gap (get JSON links was outbound-only; list JSON collapsed links to an integer). Implemented your asks #1 and #2 in #364:

• Ask Add ASPICE 4.0, ReqIF, OSLC, WASM, and CI pipelines #1 — incoming links in rivet get <ID>: new incoming_links array in JSON ({type, source, inverse} — type is the source's forward link type, inverse its schema inverse) and an Incoming: section in text. Verified on rivet's own repo: rivet get REQ-004 --format json now returns 56 incoming links (verified-by <- FEAT-134 (verifies), etc.). Built on the existing LinkGraph::backlinks_to, so it's deterministic and free.
• Ask Add document system and improve graph visualization #2 — list --format json emits the real links array: done, and made consistent with get (objects {type, target} rather than a count; the count is recoverable as .links | length).

So rivet get REQ-MIGRATION-001 --format json | jq .incoming_links now answers "what satisfies/verifies this?" directly — no more matrix --direction backward + YAML hand-parsing for the first hop.

• Ask feat: AADL integration — schema, adapter, WASM rendering, architecture dogfood #3 (inline the target's fields/run steps) is the remaining nice-to-have — that's the second hop (req → tests → run commands). It's a bigger surface (and a mild footgun to inline arbitrary fields by default), so I've left it for a follow-up under REQ-128; a get --depth 1-style inline or letting bundle carry the verification steps is the likely shape. Your matrix-reverse + parse script is exactly the workaround feat(get,list): expose incoming links (what links to an artifact) (#358) #364 removes for hop 1 — would still be glad to see it for the hop-2 design.

Regression test get_json_includes_incoming_links added. Tracked as REQ-128.

[avrabe]

Asks #1 (incoming links in get) and #2 (list emits the links array) are resolved by #364 (merged). Ask #3 (inline the target's run-steps for the second hop) remains as a tracked follow-up under REQ-128. Closing the headline; #3 lives on in the roadmap.