> ## Documentation Index
> Fetch the complete documentation index at: https://gump.top/sdlc-harness-docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Requirements traceability

> Connect requirements, user stories, acceptance criteria, features, and verification items.

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

```text theme={null}
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.

```json theme={null}
{
  "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

```bash theme={null}
npx @caesarlo/sdlc-harness traceability
```

[See the `traceability` command →](/sdlc-harness-docs/reference/command-repository#traceability)

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`.

<Tip>
  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.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.