Requirements traceability - SDLC Harness

The traceability matrix uses stable in-repository references to answer two questions: which feature implements each requirement, and which check verifies each acceptance criterion.

Reference chain

FR/NFR requirement → user story → acceptance criterion → feature → verification

A feature’s source_refs can reference a requirement directly or an acceptance criterion in a user story. Each verification’s source_refs should point to the acceptance criteria it actually verifies.

{
  "id": "M1-AUTH-001",
  "source_refs": [
    "docs/product/requirements.md#FR-1",
    "docs/product/user-stories.md#US-1.AC-1"
  ],
  "verification": [
    {
      "type": "automated",
      "command": "npm test -- auth",
      "expected": "Valid credentials create a session",
      "source_refs": ["docs/product/user-stories.md#US-1.AC-1"]
    }
  ]
}

View the matrix

npx @caesarlo/sdlc-harness traceability

See the traceability command → The command outputs the matrix and gaps as JSON and returns a nonzero exit code when the matrix is incomplete. status also includes a traceability summary.

Common gaps

Field	Meaning	Fix
`uncoveredRequirements`	No feature covers the requirement	Add the corresponding FR/NFR reference to a feature
`orphanStories`	The user story is not linked to a requirement	Reference an FR/NFR in the story
`orphanFeatures`	The feature is not linked to a requirement or acceptance criterion	Add feature `source_refs`
`uncoveredAcceptanceCriteria`	No feature covers the acceptance criterion	Add the AC to the responsible feature’s `source_refs`
`unverifiedAcceptanceCriteria`	No verification covers the AC	Add the AC reference to the precise verification item
`unknownReferences`	A reference cannot be resolved	Correct the in-repository path or anchor ID

Traceability checks are deferred while template scope placeholders have not been decomposed. After real requirements and features exist, gaps become [traceability] errors in validate.

Each verification should reference only the acceptance criteria it actually demonstrates. Do not attach every AC to one broad command just to make the matrix green.