Marking a sw-req 'implemented' + verified requires the full ASPICE design chain — no direct test→sw-req link, and the completeness error doesn't guide you there

[avrabe]

What I was doing

On a downstream project (pulseengine/synth, rivet 0.13.3, aspice schema), I shipped a batch of features and wanted to mark the corresponding sw-req artifacts implemented and keep rivet validate green — e.g. SL-TR-003 "Relocation emission for import BL instructions" (now actually implemented + tested).

What I used

• rivet validate / rivet check (the completeness diagnostics)
• read the existing sw-verification artifacts + the verifies-link error to reverse-engineer the required shape

The friction (in order I hit it)

1. Flipping status: planned → implemented on a sw-req is easy, but then validate reports
   SL-TR-003 (sw-req, status: implemented) — missing: unit-verification, sw-integration-verification.
   This tells me what's missing but not how to satisfy it, and crucially not that it can't be satisfied directly.

2. You cannot link a verification to a sw-req. I authored a unit-verification and a sw-integration-verification with verifies: SL-TR-003, pointing at the real cargo test cases. validate rejected both:

   • unit-verification verifies allowed targets: [sw-detail-design]
   • sw-integration-verification verifies allowed targets: [sw-arch-component, sw-detail-design]
     So to mark ONE sw-req verified, the ASPICE chain sw-req → sw-arch-component → sw-detail-design → {unit,integration}-verification must ALL exist. There is no shortcut for "this requirement is implemented and here are the tests that cover it."

3. The completeness error and the link-target error don't reference each other. The "missing: unit-verification, sw-integration-verification" message never mentions that you first need sw-arch-component/sw-detail-design intermediate artifacts. I only discovered the required layering by trying the direct link and reading the rejection.

4. Schema drift adds noise: the project's sw-req artifacts carry a crate: field that the aspice sw-req schema doesn't declare → 37+ INFO: field 'crate' is not defined in schema diagnostics on every validate, drowning the actionable errors. (Either the schema should allow a crate/component field on sw-req, or there should be an easy per-project field extension.)

What finally helped

The verifies-link target-type rejection is what actually revealed the intended layered model — it's the only message that names sw-detail-design/sw-arch-component. Everything else (the completeness "missing X-verification" list) pointed me at the wrong fix (author a verification linking to the req).

Suggestions

• Make the completeness diagnostic for an implemented sw-req name the chain: "needs a sw-detail-design (satisfies SL-TR-003) verified by a unit-verification, and a sw-arch-component verified by a sw-integration-verification." A one-line "how to satisfy" in the error would have saved the whole detour.
• Consider a rivet implement <id> (or rivet scaffold-verification <id>) that stubs the minimal sw-arch-component + sw-detail-design + verification artifacts wired with the correct link types, so marking shipped work as implemented is a guided step rather than reverse-engineering link target-types.
• Provide a docs page: "minimal artifact chain to mark a sw-req verified" with a copy-pasteable example.
• Make undeclared-field handling per-project-easy (the crate: case): a documented way to extend a built-in schema type with project fields without forking the schema.

Environment: rivet 0.13.3 (b55a9c6f), aspice + common + stpa schemas, project pulseengine/synth.

[avrabe]

Picked this up in the triage pass but holding off on implementation — the Suggestions section is multi-track (better completeness diagnostic; new rivet implement/rivet scaffold-verification command; docs page; per-project field extension for crate:) and the "one PR per issue, keep PRs focused" rule means I should pick exactly one direction.

Could you reframe as an explicit Acceptance Criteria section so the triage agent can pick this up automatically? Format I look for:

## Acceptance Criteria

- [ ] `rivet validate` completeness diagnostic for sw-req with status: implemented names the layered chain (`sw-arch-component (...) -> sw-detail-design (...) -> {unit,integration}-verification (...)`) in the error body, including which links connect each step
- [ ] Regression test: a sw-req without the chain produces a diagnostic whose body contains the four artifact type names above
- [ ] `cargo test -p rivet-core` passes, `rivet validate` on the rivet repo still PASS

The bulleted, testable statements let the agent know unambiguously when it's done. Items that are clearly aspirational (e.g. a brand-new rivet implement command, a new docs topic) are easier to file as their own issues — each one then becomes its own focused PR.

(Triage signal — this issue is high-value but blocked on scope clarification, not on engineering effort.)

---

Generated by Claude Code

[avrabe]

Triaged — this is a valid, high-signal UX report, and it lands on the exact theme we're prioritizing for v0.15.0: the gate must say how to satisfy it, not just what's missing. Assessment of each point:

1. "missing: unit-verification, sw-integration-verification" doesn't say you can't link them directly — confirmed friction. The completeness diagnostic names the terminal artifacts but not the required chain (sw-req → sw-arch-component → sw-detail-design → {unit,integration}-verification). This is exactly what REQ-124 (diagnostic remediation) does for link-target-type/broken-link etc. — but the traceability/completeness rules key on a dynamic rule.id, which I deliberately deferred in the first REQ-124 pass. Your report is the case that justifies finishing it. Filing as REQ-132: completeness diagnostics for an implemented req emit a "how to satisfy" line naming the intermediate chain.

2. The verifies-link rejection is what actually taught you the model — noted, and telling: the only useful message was an unrelated one. That's precisely the "errors should teach" gap REQ-124/REQ-125 (--explain) close.

3. rivet implement <id> / scaffold-verification <id> — strong idea. Filing as REQ-133: a guided command that stubs the minimal sw-arch-component + sw-detail-design + verification artifacts wired with the correct link types, so marking shipped work implemented is guided, not reverse-engineered.

4. crate: field noise (37+ INFO per validate) — confirmed real and separately annoying (drowns actionable diagnostics). Filing as REQ-134: a documented, per-project way to extend a built-in schema type with extra fields without forking the schema (build on the existing schema extends mechanism). Until then, rivet validate severity filtering would help — also noted.

All four are being planned as rivet artifacts (dogfooding). #132 + #133 are the highest-value and I'll pick them up after the in-flight v0.15.0 fixes. Will link the REQs/PRs here as they land.

(Environment note for cross-ref: the required-backlink false-positive you may also have seen on safety schemas is a separate confirmed bug — #349, fixed in #351.)

[avrabe]

Hit this again working synth's traceability after the gale cross-LTO arc shipped. Sharing what I used and what finally helped, per the workflow.

Context: wanted to mark shipped requirements implemented and keep rivet validate green.

What was hard / confusing:

• rivet validate reported FAIL (35 errors) and a big "Lifecycle coverage gaps" list, which looked like flipping anything to implemented would make it worse. It doesn't — but that wasn't obvious from the validate output alone.
• For sw-reqs, marking implemented surfaces "missing sw-integration-verification, unit-verification", but neither type can target a sw-req: unit-verification.verifies -> [sw-detail-design] and sw-integration-verification.verifies -> [sw-arch-component, sw-detail-design]. So closing a sw-req's coverage needs the full chain sw-req → sw-arch-component → sw-detail-design → 2 verifications. This is the original Marking a sw-req 'implemented' + verified requires the full ASPICE design chain — no direct test→sw-req link, and the completeness error doesn't guide you there #350 friction.

What finally helped:

1. rivet schema show sys-integration-verification / ... sys-verification — revealed these can target a system-req directly (verifies -> [system-arch-component, system-req]). So at the system tier the friction disappears: one sys-integration-verification closes the coverage. The asymmetry between the sys tier (direct) and sw tier (chain-only) is the key thing that wasn't obvious.
2. rivet check gaps-json + grouping diagnostics by severity — showed all 35 errors were broken-link to unsynced externals, and every status/coverage concern was warning/info. That de-risked the flips: I could prove the edits live entirely in the info tier and can't change the error count.

Suggestion: could rivet validate's coverage-gap output annotate severity inline (these are info/warning, not errors) and, for a sw-req gap, name the chain needed rather than listing verification types that can't actually target it? The current message points at unit-verification/sw-integration-verification as if they could verify the sw-req directly, which sends you down a dead end.

Tooling: rivet 0.13.3 (release/v0.14.0).

[avrabe]

Partial progress relevant here: rivet validate --explain <ID> shipped in #372 — it shows, for an artifact, which traceability rules apply and what's missing (e.g. needs an incoming 'satisfies' from one of [design-decision, feature]), which is the start of the 'name the chain' ask. The full ASPICE-chain naming (sw-req → sw-arch-component → sw-detail-design → verification) is still tracked as REQ-132, and the guided scaffold as REQ-133. But for 'why is this not yet implemented/covered?', --explain now answers it directly from the CLI.

[avrabe]

Triaged all four points against current main:

Suggestions 1 & 3 (the completeness error doesn't say how to satisfy it / doesn't reference the link rule) → fixed in #394 (REQ-147). The required-backlink coverage diagnostic now appends the link type + allowed source types inline — "… — needs an incoming verifies link from one of [sw-verification, unit-verification, sw-integration-verification]" — and the Lifecycle coverage gaps summary points at rivet validate --explain <ID>, which already lists each rule's satisfied/MISSING state with the exact incoming link + source types. No reverse-engineering from a link-target rejection needed.

Root cause of the "detour" — a real schema inconsistency I found while verifying: the aspice coverage rule swe1-has-verification advertises from-types: [sw-verification, unit-verification, sw-integration-verification], but the link-target rules only let sw-verification verifies→sw-req (unit-verification verifies sw-detail-design; sw-integration-verification verifies arch/detail-design). So two of the three advertised satisfiers can never form that backlink — exactly why your direct unit-verification → sw-req link was rejected. Filed REQ-148 for a generic coverage-rule-consistency meta-check to catch "advertises an unsatisfiable satisfier" in any schema.

Suggestion 4 (crate: undeclared-field noise drowning errors): rivet validate --min-severity warning (shipped in REQ-137) now hides the INFO-level "field not defined" lines so the actionable errors stand out; for a permanent fix, a local schema that extends: aspice and adds the crate field to sw-req declares it without forking. (If you'd like, I can add a docs recipe for the extend-a-built-in-type pattern.)

Suggestion 2 (no direct test→sw-req; rivet scaffold-verification <id>): this is ASPICE/schema intent — whether sw-reqs are verified directly (SWE.6 sw-verification) vs only through the design chain, and whether to generate the intermediate sw-arch-component/sw-detail-design stubs. That's a maintainer/compliance-semantics decision (related to #355 Findings 1-2), so I've left it for the maintainer rather than bake an interpretation into a command.