Suspect propagation and impact analysis
When a released artefact changes, every downstream artefact that depended on it must be independently re-checked. Suspect propagation is the mechanism that flags those downstream items automatically — a signal that human review is required, not a validation error.
An artefact with an unresolved suspect state cannot appear in a released baseline.
When suspects are created
Suspect propagation is triggered when any of the following happen to an artefact that is released or part of an approved or released baseline:
| Trigger | Description |
|---|---|
artefact.revised | Content of a released artefact changes |
artefact.status_changed | A released artefact is obsoleted |
relationship.deleted | A relationship that provided traceability is removed |
Changes to draft or reviewed artefacts do not create suspects — they may create validation issues, but not suspect states. The point of suspect propagation is to protect artefacts that have already been formally released.
Which relationships propagate suspects
Not every relationship type propagates. Only relationships that imply a downstream dependency — “if the upstream changes, I might need to change too” — are eligible.
Propagation-eligible types:
| Type | Meaning |
|---|---|
allocates_to | If the requirement changes, the component allocation may be invalid |
satisfies | If the source requirement changes, the satisfying artefact may need revision |
derives_from | If the parent requirement changes, the derived requirement may be invalid |
implements | If the requirement or design changes, the implementation may be invalid |
verifies | If the verified artefact changes, the verification result may be invalid |
produces_result_for | If the test case changes, the test result is suspect |
depends_on | If the depended-on component changes, the dependent component may be affected |
constrains | If the constraint changes, the constrained component is suspect |
protects | If the fault scope changes, the safeguard may be insufficient |
assumes | If the assumption context changes, the downstream is suspect |
Informational types that do not propagate: references, interacts_via, guarantees, mitigates, traces_to. These are reviewed case-by-case rather than automatically.
The propagation algorithm
Suspect propagation runs as a breadth-first traversal of the propagation graph starting from the trigger artefact. For each downstream artefact reached, the tool creates a SuspectState record with the trigger, the propagation depth, and the path from the trigger to the suspect.
- Depth limit — configurable per project; default is 10 hops. If the limit is reached, a warning-level audit event is emitted noting the truncated chain.
- Only active items are traversed — soft-deleted artefacts and relationships are excluded.
- No circular suspects — the trigger artefact itself is never marked suspect from its own change.
- Idempotent — if an open suspect state already exists from the same trigger, a duplicate is not created.
Clearing a suspect state
A suspect must be cleared by a human decision — implicitly or explicitly. There are three clearing methods:
| Method | Meaning | Who can apply it |
|---|---|---|
reviewed_and_accepted | Human review confirmed the suspect artefact remains valid despite the upstream change | Any authorized project member |
re_verified | A new verification run produced a passing result after the upstream change | Quality Engineer or User |
not_applicable | The upstream change does not affect this artefact’s scope; rationale provided | Project Lead |
Clearing a suspect state requires:
cleared_by— the user performing the clearanceclearing_method— one of the values aboveclearing_evidence_refs— at least one supporting reference (except forreviewed_and_accepted, where the audit event itself is the evidence)
Automatic clearing
The tool clears a suspect automatically when:
- A new revision of the suspect artefact is created after the trigger revision — the author has implicitly reviewed the upstream change by producing new content.
- The trigger artefact is rolled back by an admin to its pre-change revision.
- The suspect artefact is soft-deleted (obsolete). A deleted artefact cannot remain suspect.
Automatic clearing is recorded with clearing_method = "system_auto" and cleared_by = "system".
Cascade clearing (or lack of it)
Clearing a suspect does not cascade to downstream suspects that were propagated from the same trigger through the now-cleared artefact. Each artefact’s suspect state must be independently reviewed and cleared.
The reason is deliberate: the downstream artefact may have additional reasons to be suspect, or the reviewer of that artefact may reach a different determination than the upstream reviewer.
Impact analysis
Impact analysis is a user-initiated, on-demand analysis of the potential scope of impact — before a change is made. It uses the same propagation graph as suspect propagation, but does not create any suspect states.
curl -X POST http://localhost/api/v1/projects/<project-id>/impact \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-token>" \
-d '{"artefact_id": "<artefact-id>"}'The result categorizes affected artefacts by:
- Impact severity — direct (depth 1) vs indirect (depth > 1)
- Artefact type distribution
- Baseline membership — artefacts in active baselines are the highest priority
- Verification coverage — whether the affected artefact has associated test results
Impact analysis also lists artefacts that are affected through non-propagating relationships, marked as affected_informational, so reviewers see the full picture even though those relationships wouldn’t auto-flag suspects.
Interaction with the release gate
- A baseline cannot be released if any in-scope artefact has an open
SuspectState(enforced by ruleRULE-081). - If a suspect exists on an artefact that was excluded from the baseline scope via a not-applicable tailoring decision, it does not block that baseline.
- The baseline snapshot records the count of open suspect states at creation time, even for non-blocking cases, for audit purposes.
Related
- Release baselines — how open suspects and stale gates block release
- Managing artifacts — the relationship types that form the propagation graph
- Authorization — who can update released artefacts and clear suspects