Skip to content
contextlint

GRP-001 Traceability chain

Overview

Section titled “Overview”

Validates that an ID can be traced through multiple document stages in order — for example, requirements → design → test plan. Any ID that fails to appear in a downstream stage is reported as warning. This is a project-scope rule and is evaluated across all documents loaded via include.

The rule collects IDs from the idColumn of the first stage (chain[0]), then walks each subsequent stage, checking that those IDs appear in the stage’s refColumn.

Why it matters

Section titled “Why it matters”

In a flow like requirements → design → test, the minimum consistency requirement is that “every requirement ID is referenced in design, and every ID that appears in design is referenced in test plans”. When files are split, gaps such as adding a requirement but forgetting the design or the test plan are invisible to a human reading documents one by one. This rule detects breaks in the chain mechanically.

Options

Section titled “Options”
FieldTypeRequiredDescription
chainobject[]YesStages that make up the chain (minimum 2). The order is the validation order
idPatternstring—Only values matching this regex are treated as IDs (non-matching values are ignored)

Each stage in chain

Section titled “Each stage in chain”
FieldTypeRequiredDescription
stagestringYesName of the stage (shown in error messages)
filesstringYesGlob of documents at this stage
idColumnstring—Column where IDs are defined at this stage (required for the first stage)
refColumnstring—Column where IDs from the previous stage are referenced (required from the second stage onward)

The first stage uses idColumn; every subsequent stage uses refColumn.

Bad example

Section titled “Bad example”
docs/requirements.md:


| ID      | Name   |
| ------- | ------ |
| REQ-001 | Login  |
| REQ-002 | Logout |


docs/design.md:


| Requirement | Detail        |
| ----------- | ------------- |
| REQ-001     | Design login  |

REQ-002 is not referenced in the Requirement column of docs/design.md, which triggers a violation.

docs/requirements.md
  line 4  warning  REQ-002 defined in docs/requirements.md but not referenced in stage "Design"  GRP-001

After fix

Section titled “After fix”
docs/design.md:


| Requirement | Detail         |
| ----------- | -------------- |
| REQ-001     | Design login   |
| REQ-002     | Design logout  |

Configuration example

Section titled “Configuration example”
{
  "rule": "grp001",
  "options": {
    "chain": [
      { "stage": "Requirements", "files": "**/requirements.md", "idColumn": "ID" },
      { "stage": "Design", "files": "**/design.md", "refColumn": "Requirement" },
      { "stage": "Test", "files": "**/test-plan.md", "refColumn": "Covers" }
    ],
    "idPattern": "^REQ-\\d{3}$"
  }
}

Chains of three or more stages are expressed simply by extending the chain array. Specifying idPattern excludes sample header rows or notation-drift rows from the ID set.

Section titled “Related rules”