Trace

Gap Summary

A gap is a workbook-level traceability finding that auditors will flag. Trace now merges generic graph gaps and profile-generated chain gaps into one result set; only hard/error findings count toward --strict.

Gaps don't block output by default. Trace still generates reports when gaps are present. Generic reports group findings into hard and advisory sections; profile-aware reports render one merged list with profile clause references where available. Only hard gaps and profile err findings affect --strict.

Gap conditions

Diagnostics are separate. Parser warnings, schema issues, and broken references still appear in Diagnostics. The Gap Summary only describes workbook traceability structure and audit-readiness findings.

⚠

Requirement with no test-group link

Class: Hard gap

Condition: A requirement declares no test-group references at all.

Risk: The requirement has no verification linkage. Strict mode treats this as a blocking traceability failure.

Fix: Add one or more test groups to the Tests tab and reference them from the requirement's Test Group IDs cell.

⚠

Requirement with only unresolved test-group references

Class: Hard gap

Condition: A requirement declares one or more test-group IDs, but none resolve to a valid TestGroup node.

Risk: The workbook looks traced at first glance, but every declared verification target is broken. This is a strict-mode failure.

Fix: Correct the test-group IDs or add the missing test groups to the Tests tab.

Requirement with no user need

Class: Hard gap

Condition: A requirement has no upstream DERIVES_FROM link to a user need.

Risk: The requirement has no documented rationale or originating need, which auditors typically treat as a blocking traceability gap.

Fix: Add the originating user need and reference it from the requirement row.

Risk with no mitigation requirement

Class: Hard gap

Condition: A risk row does not declare any mitigation requirement at all.

Risk: The risk is structurally unmitigated in the workbook.

Fix: Link the risk to one or more mitigating requirements.

Risk with unresolved mitigation requirement

Class: Hard gap

Condition: A risk declares a mitigation requirement ID, but it does not resolve to an existing requirement.

Risk: The risk appears mitigated, but the mitigation target is broken.

Fix: Correct the requirement ID or add the missing requirement.

ℹ

Advisory graph gaps

Class: Advisory only

Conditions: Trace also reports user needs with no requirements, requirements linked to empty test groups, and test groups with no requirements.

Risk: These do not fail --strict, but they are still valuable audit-prep signals.

↔

Profile-specific chain gaps

Class: Profile-dependent err or warn

Condition: A non-generic profile activates additional chain checks such as Design Input → Design Output continuity, HLR → LLR decomposition, source/configuration-item evidence, or ASIL inheritance.

Examples: iso13485_di_do_chain, do178c_hlr_llr_decomposition, iso26262_asil_inheritance.

Fix: Repair the missing chain under the chosen profile or rerun with --profile generic if you intentionally want the baseline generic graph checks only.

Where gaps appear

Detected gaps are surfaced in four places:

CLI output — a gap count is printed after the run. Non-zero means something needs attention.
Native app summary — the macOS and Windows apps show gap count and warning count after a file loads, before generation.
Report Gap Summary section — the last section of every generated report lists all gaps by type and requirement ID.
Gaps JSON file — when --gaps-json is passed, a machine-readable file is written with full gap and diagnostic detail.

Strict mode and CI

Pass --strict to make the process exit non-zero when hard gaps are detected. Advisory findings are still reported, but they do not fail CI.

rtmify-trace requirements.xlsx --format md --strict

In strict mode the exit code reflects the merged hard-gap count: generic hard gaps plus profile err findings for the selected profile. Advisory generic gaps and profile warn findings do not fail CI.

Combine with --gaps-json to get a machine-readable artifact alongside the exit code:

rtmify-trace requirements.xlsx --format md --strict --gaps-json gaps.json

Gaps JSON

When --gaps-json <path> is passed, Trace writes a structured JSON file at that path. It captures:

—The active top-level profile
—Parser and ingest diagnostics (warnings, errors, and their codes)
—Each gap finding, including severity, kind, primary_id, node_id, and related_id when applicable
—For profile gaps, additional code, profile_rule, and clause fields
—Hard gap count plus warning and error totals

{
  "profile": "medical",
  "diagnostics": [...],
  "gaps": [
    {
      "severity": "err",
      "code": 1202,
      "kind": "design_input_without_design_output",
      "primary_id": "DI-001",
      "node_id": "DI-001",
      "related_id": null,
      "profile_rule": "iso13485_di_do_chain",
      "clause": "ISO 13485 §7.3.4",
      "message": "..."
    }
  ],
  "gap_count": 4,
  "warning_count": 2,
  "error_count": 0
}

This file is intended for downstream tooling — build dashboards, custom reporters, or RTMify Live ingestion. It does not need to be read by humans to understand gaps; the report's Gap Summary section is the human-readable version.