Trace Links & the Suspect Cycle¶
Audience: authors who build and maintain traceability.
A trace item becomes traceable when you link it — to another item, or to a document. Links are how coverage is counted, how the chains are walked, and how a change upstream tells everyone downstream to look again. This chapter covers the link vocabulary, where you author links, why a link on a released document is refused, and the suspect cycle that keeps traceability honest across change.
1. The link vocabulary — and when to use which¶
Links are typed. The type carries the meaning, so pick the one that states the true relationship. The Trace links card (on the document detail) offers them with a one-line hint; each also has a readable inverse used in the reverse direction.
| Link type | Reads as | Inverse | Use it when… |
|---|---|---|---|
| Verifies | This document or item proves the target is met. | Verified by | a test/verification proves a requirement or a control holds. |
| Satisfies | This design realizes the target requirement. | Satisfied by | a software requirement realizes a stakeholder requirement. |
| Derives from | This item decomposes the higher-level target. | Derived into | a lower-level requirement is decomposed from a higher-level one. |
| References | Informational reference without trace semantics. | Referenced by | you are pointing at something for context, with no coverage claim. |
| Mitigates | This control reduces the target risk. | mitigated by | a risk control reduces a risk. |
| Implemented by | The target requirement item — or an implementing document (SOP/WI) — realizes this control. | implements | a control is realized by a requirement, or by a procedure/work instruction. |
| Validates | This validation proves the right thing — validate a user need (e.g. a Validation Plan that validates a user need). | Validated by | a validation activity (or a whole Validation Plan/Report) confirms a user need — the validation axis (§6). |
| Complies with | This requirement or design element satisfies a regulatory principle — comply with a GSPR / essential-principle clause. | Complied with by | a requirement or design element conforms to a GSPR / essential-principle clause (§6). |
Two points worth internalising:
VerifiesandSatisfiesare different coverage kinds, on purpose. A software requirement is verified by test evidence; a stakeholder requirement is satisfied by software requirements. Both count as coverage, but they are counted separately so each reads correctly (see traceability-workspace §2).- The Trace links card is the ONE home for every claim (ADR-0085). All trace claims —
Verifies,Satisfies,Derives from,Mitigates,Implemented by— are authored here, at whichever granularity fits: a keyed item or a whole document. The neighbouring References card is now plainly a reference list —References(and the auto "from text" links) are its only type, its type picker is gone, and it never carries a coverage claim. If a stale client somehow POSTs a claim to the references endpoint the server refuses it (HTTP 400) with a message pointing you back here. - A claim can target a whole document — not only a keyed item. "This verification plan verifies
the whole SRS", "this design satisfies that specification", a control implemented by an SOP/WI:
for
Verifies/Satisfies/Derives from/Implemented bythe Add-link dialog offers a target-mode toggle — A keyed item or A whole document — so you point at whichever is true. (An Implemented by document is the classic case: a control that is information for safety — a label, a manual warning — or organizational — a procedure, a training — is realized by an SOP/WI, not a product requirement. Forcing every control to name a requirement would fabricate one that does not exist; a document target counts as implemented.)
2. Where you author links¶
From the Trace links card. On the document detail, Trace links lists the links to and from the document's items (and document-level links). Add link opens a dialog: pick the Source item (or (the document) for a document-level link such as Verifies), the Link type, the Target scope, and then the target — either a Target item (search by key or text) or, for a claim that accepts one (Verifies / Satisfies / Derives from / Implemented by), a whole Target document via the A keyed item / A whole document toggle. Cross-scope targets are supported (you pick the target scope); a target in a scope you cannot see shows only its key, marked Cross-scope.
A document that defines no items can still carry document-level links: "This document defines no items, but document-level links (e.g. Verifies) can still be authored — use 'Add link'."
From the gap flags. The risk and requirement views flag what is missing and offer to close the gap in place, so you do not have to hunt for the right card:
- Add mitigation… — on a risk with no control: pick a control and the Mitigates link is created on that control's document.
- Add verification… — on a control not yet verified: pick the verifying document and the Verifies link is created on that document's draft.
Each remedy tells you exactly where the link will be written and what to do if that document has no draft ("This document has no draft — you will need to revise it first to add the link.").
3. Links are draft structure — why a released link is refused¶
Adding or removing a link is a structure change, and structure changes are draft-only: the source document must currently have a version in Draft. The card states this — "Links are draft metadata — editable here while this version is a draft." — and a gap you cannot close in place tells you why: "No draft — close this gap via a revision."
This is enforced by the server, not just hidden in the UI. If you attempt to add or remove a link against a document with no draft (for example, directly via the API), the server refuses with HTTP 409 Conflict and a message naming the remedy: revise the document first. The reasoning is a core LQMS principle — released trace evidence must not erode in place. The proper vehicle for changing what a released document traces is a revision, which goes through review like any other change. (A 409, not a 403: you are allowed to edit trace structure; the document is simply in the wrong state.)
4. The suspect cycle¶
Traceability is only trustworthy if a change upstream forces a fresh look downstream. That is the suspect mechanism:
- When a new released version of a defining document changes an item's content (its hash differs) — or removes the key entirely — every inbound link to that item is flagged Suspect.
- A suspect link says, in effect: "the thing you attested to has changed; look again." The card shows "The target item changed since this link was reviewed. Review and clear to re-attest." If the target is gone, it says "The target item no longer exists. Remove this link."
Clearing a suspect flag is a deliberate re-attestation, not an automatic reset. You use Review & clear, and LQMS records it — "Suspect flag cleared — re-attested to the current content." You are on record as having reviewed the link against the new target content.
Re-attesting is deliberately available on a released document. Unlike adding or removing a link (§3), clearing a suspect flag is an attestation act, not a structure change — so it is state-independent and always audited. If a released requirement's upstream moves, you must be able to re-attest the affected links without being forced into a pointless revision. This is the deliberate asymmetry: structure changes need a draft; attestations do not.
Suspect state is surfaced everywhere a link appears — on the cards, in the requirements registry ("One or more requirement links touching this key are suspect — review them on the document."), and per hop in the requirement chains and risk views, so you can see exactly where a path is interrupted.
5. Planned vs. verified — what a Verifies link means (ADR-0088)¶
A Verifies link records a designation: authored from a verification plan it says "this is
where verification of the target is designated" — an appointment. The execution evidence (the run,
the signed result) is a released report. These are different things, and LQMS now distinguishes
them in every derived view — the roadmap item from earlier releases has shipped.
The class is derived, not a new authoring step. An inbound Verifies link classifies as:
- verified — its source document's type carries the verification evidence flag (an
installation-wide property of the document TYPE, administered in Admin › Document types; a project's
configuration screen shows it but cannot change it, because one value governs how
Verifieslinks read in every project) and the source version is Released. A released report of an evidence-type document is the recorded event. - planned — every other
Verifieslink: a plan-type source, or an evidence-type source that is not yet released (a draft report is not evidence).
Where you see it:
- Requirement coverage splits the evidence chips — planned ×N / verified ×N (satisfied is
unchanged). The covered verdict itself is unchanged (any inbound
VerifiesorSatisfies). - Requirement chains show each evidence chip's class and, for a verified one, its release date
(
QMS-DEV-VER-011 · v4 · verified 2026-07-19vs… · planned). A chain that is satisfied and fully designated but whose evidence is all planned carries the amber Planned only flag — the honest intermediate between Satisfied, unverified and clean — and the header counts it. - Risk traceability renders a planned-class verification as planned, never as a green verified;
the control not verified gap still fires only on zero
Verifieslinks.
So keep linking the released report where you mean executed evidence, and set the verification evidence type flag on your genuine report types — a planned-only chain then reads honestly as "the verification is designated but not yet run", which is exactly the audit question the split answers. (Freshness — "verified within N days" — is deliberately not a rule yet; it is registered for a future recurring-obligation decision.)
6. Validation & regulatory links (Stage C, ADR-0084)¶
Stage C adds two link types — and gives the existing Satisfies link a new source — so the
validation and regulatory axes are traceable end to end. All three are authored on the Trace links
card like every other claim (§2), at item level or document level.
Validates— "This validation proves the right thing — validate a user need (e.g. a Validation Plan that validates a user need)." Its inverse is Validated by. Author it from a validation case, or document-level from a whole Validation Plan / Validation Report, onto a user need. This is the validation axis — "did we build the right thing?" — distinct fromVerifies("does it meet the written requirement?"). LikeVerifies, aValidateslink carries a planned-vs-verified class (§5, ADR-0088): it reads as validated when its source is a released document of a verification-evidence type, and planned otherwise. The Validation matrix reads exactly this (see traceability-workspace §7).Complies with— "This requirement or design element satisfies a regulatory principle — comply with a GSPR / essential-principle clause." Its inverse is Complied with by. Author it from a requirement or a design element onto a regulatory reference. It is the spine of the GSPR conformity view (see traceability-workspace §8).Satisfiesnow accepts a design element as its source. The V-model's "how satisfies what" — a design elementSatisfiesa requirement — is now first-class, alongside the existing software-requirement-satisfies-stakeholder-requirement use. The Design realization panel of the Validation matrix surfaces it.
Suspect behaves the same as for every claim (§4): when a Validates target user need or a
Complies with target clause changes content, the link goes Suspect and must be re-attested on
its source document.
Governing decisions: ADR-0077 §5 (item links + suspect semantics + deliberate clearing), ADR-0078 (type-agnostic link vocabulary), ADR-0079 (mitigates / implemented-by, incl. document targets for organizational & information-for-safety controls), ADR-0081 (draft-only structure changes, server-enforced; 409 on a released source; clearSuspect stays state-independent), ADR-0084 (Stage C — the validates & complies-with edges; design-element as a satisfies source), ADR-0086 (the chain view that surfaces suspect per hop), ADR-0088 (planned-vs-verified evidence classes, applied to the validates link too). Classification: conventions.md "Lifecycle gating of affordances" (structure change vs attestation act).