Traceability Gate
The single governance gate for the TOGAF red thread: no artifact at
layer N+1 may persist unless it carries a verified link to a parent at
layer N. The skill does NOT elicit requirements and does NOT derive
new ones; its only job is to refuse to let unlinked artifacts live.
When to Use
- Before any pull request that touches
requirements/** or any skill
that emits artifacts under it.
- Before promoting a curator-proposed skill from
optional-skills/ to
skills/ — learned skills must pass the same gate as live delivery.
- During Phase B → C and Phase C → D transitions, to prove the cascade
is intact before architecture commits to a design.
- After every batch run of
derive-nfr-from-driver or
derive-security-from-risk.
- NOT as a substitute for elicitation — the gate verifies linkage,
not quality of requirements. A bad requirement linked to a bad
parent still passes the gate.
Prerequisites
- The engagement directory exists at
requirements/<engagement>/.
spec/artifact-schema.md defines the frontmatter contract.
scripts/verify-traceability.sh is executable.
The gate is allowed to be called against an empty engagement
directory — it reports zero artifacts and exits 0. That is the seed
state, not a failure.
How to Run
# Full traceability check for one engagement
bash scripts/verify-traceability.sh requirements/<engagement>
# CI / strict mode — warnings (e.g. unratified) become failures
bash scripts/verify-traceability.sh --strict requirements/<engagement>
# Generate the RTM as a byproduct of the gate
bash scripts/gen-rtm.sh requirements/<engagement>
# Roll the gate into the dojo-wide gate
bash scripts/verify.sh # invokes run_traceability_checks
Quick Reference
| Action |
Tool |
Notes |
| Run gate locally |
bash scripts/verify-traceability.sh requirements/<engagement> |
Exit 0 = lineage intact. |
| Run gate strict |
bash scripts/verify-traceability.sh --strict … |
CI default. |
| Regenerate RTM |
bash scripts/gen-rtm.sh requirements/<engagement> |
Writes docs/rtm-<engagement>.md. |
| Full dojo gate |
bash scripts/verify.sh |
Includes the traceability check. |
Procedure
Step 1: Walk
The gate walks every *.md under requirements/<engagement>/{BR,FR,NFR,SR,IR,TR}/
and parses YAML frontmatter only. The body is ignored — humans read
the body, the machine reads the schema.
Step 2: Validate
For each artifact:
- All required frontmatter keys present (
id, layer, title,
parent_ids, owner, measurable, ratified_by,
derivation_skill).
id matches filename and starts with the correct layer prefix.
layer is in {BR, FR, NFR, SR, IR, TR}.
- Every
parent_ids entry resolves to an existing file in the same
engagement.
- Every parent's
layer is in the Valid parent layers column for
this artifact (see spec/artifact-schema.md §1).
measurable: true for NFR/SR/TR.
- No cycles in the parent graph.
Step 3: Decide
- Any rule failure → gate fails (exit 1). The artifact cannot
persist. The agent must fix the link or delete the artifact.
ratified_by empty → warning by default, failure in --strict.
CI runs --strict; the local loop does not, so iteration is fast.
- Zero artifacts → exit 0 with a note. Empty is a valid seed state.
Step 4: Publish
If the gate passes, regenerate the RTM. The RTM is never edited by
hand — it is always a function of the artifact graph.
bash scripts/gen-rtm.sh requirements/<engagement>
Pitfalls
- DO NOT treat the gate as a style check. It is the precondition
for an artifact existing; downgrading a failure to a warning
collapses the whole framework.
- DO NOT add a
# skip-traceability escape hatch. Every escape
hatch becomes the default within a quarter.
- DO NOT parent a
TR straight to a BR because "it's obvious"
— the layers exist so the agent cannot quietly skip them.
- DO NOT ratify an artifact from inside the agent to make the gate
green. Ratification is a human signal; faking it is the worst
failure mode this whole framework exists to prevent.
Verification
1---
2name: traceability-gate
3description: Enforces parent-link lineage across requirement layers.
4tier: core
5category: discipline
6created_by: human
7platforms: [windows, macos, linux]
8tags: [traceability, governance, togaf, gate]
9author: Andreas Wasita (@andreaswasita)
10metadata:
11 source: https://skillmd.com/skills/gabrielmoreira/traceability-gate
12---
13
14# Traceability Gate
15
16The single governance gate for the TOGAF red thread: no artifact at
17layer N+1 may persist unless it carries a verified link to a parent at
18layer N. The skill does NOT elicit requirements and does NOT derive
19new ones; its only job is to refuse to let unlinked artifacts live.
20
21## When to Use
22
23- Before any pull request that touches `requirements/**` or any skill
24 that emits artifacts under it.
25- Before promoting a curator-proposed skill from `optional-skills/` to
26 `skills/` — learned skills must pass the same gate as live delivery.
27- During Phase B → C and Phase C → D transitions, to prove the cascade
28 is intact before architecture commits to a design.
29- After every batch run of `derive-nfr-from-driver` or
30 `derive-security-from-risk`.
31- **NOT** as a substitute for elicitation — the gate verifies linkage,
32 not quality of requirements. A bad requirement linked to a bad
33 parent still passes the gate.
34
35## Prerequisites
36
37- The engagement directory exists at `requirements/<engagement>/`.
38- `spec/artifact-schema.md` defines the frontmatter contract.
39- `scripts/verify-traceability.sh` is executable.
40
41The gate is allowed to be called against an empty engagement
42directory — it reports zero artifacts and exits 0. That is the seed
43state, not a failure.
44
45## How to Run
46
47```bash
48# Full traceability check for one engagement
49bash scripts/verify-traceability.sh requirements/<engagement>
50
51# CI / strict mode — warnings (e.g. unratified) become failures
52bash scripts/verify-traceability.sh --strict requirements/<engagement>
53
54# Generate the RTM as a byproduct of the gate
55bash scripts/gen-rtm.sh requirements/<engagement>
56
57# Roll the gate into the dojo-wide gate
58bash scripts/verify.sh # invokes run_traceability_checks
59```
60
61## Quick Reference
62
63| Action | Tool | Notes |
64|---|---|---|
65| Run gate locally | `bash scripts/verify-traceability.sh requirements/<engagement>` | Exit 0 = lineage intact. |
66| Run gate strict | `bash scripts/verify-traceability.sh --strict …` | CI default. |
67| Regenerate RTM | `bash scripts/gen-rtm.sh requirements/<engagement>` | Writes `docs/rtm-<engagement>.md`. |
68| Full dojo gate | `bash scripts/verify.sh` | Includes the traceability check. |
69
70## Procedure
71
72### Step 1: Walk
73
74The gate walks every `*.md` under `requirements/<engagement>/{BR,FR,NFR,SR,IR,TR}/`
75and parses YAML frontmatter only. The body is ignored — humans read
76the body, the machine reads the schema.
77
78### Step 2: Validate
79
80For each artifact:
81
821. All required frontmatter keys present (`id`, `layer`, `title`,
83 `parent_ids`, `owner`, `measurable`, `ratified_by`,
84 `derivation_skill`).
852. `id` matches filename and starts with the correct layer prefix.
863. `layer` is in `{BR, FR, NFR, SR, IR, TR}`.
874. Every `parent_ids` entry resolves to an existing file in the same
88 engagement.
895. Every parent's `layer` is in the **Valid parent layers** column for
90 this artifact (see `spec/artifact-schema.md` §1).
916. `measurable: true` for `NFR`/`SR`/`TR`.
927. No cycles in the parent graph.
93
94### Step 3: Decide
95
96- Any rule failure → **gate fails** (exit 1). The artifact cannot
97 persist. The agent must fix the link or delete the artifact.
98- `ratified_by` empty → warning by default, failure in `--strict`.
99 CI runs `--strict`; the local loop does not, so iteration is fast.
100- Zero artifacts → exit 0 with a note. Empty is a valid seed state.
101
102### Step 4: Publish
103
104If the gate passes, regenerate the RTM. The RTM is never edited by
105hand — it is always a function of the artifact graph.
106
107```bash
108bash scripts/gen-rtm.sh requirements/<engagement>
109```
110
111## Pitfalls
112
113- **DO NOT** treat the gate as a style check. It is the precondition
114 for an artifact existing; downgrading a failure to a warning
115 collapses the whole framework.
116- **DO NOT** add a `# skip-traceability` escape hatch. Every escape
117 hatch becomes the default within a quarter.
118- **DO NOT** parent a `TR` straight to a `BR` because "it's obvious"
119 — the layers exist so the agent cannot quietly skip them.
120- **DO NOT** ratify an artifact from inside the agent to make the gate
121 green. Ratification is a human signal; faking it is the worst
122 failure mode this whole framework exists to prevent.
123
124## Verification
125
126- [ ] `bash scripts/verify-traceability.sh requirements/sample` exits 0.
127- [ ] `bash scripts/verify-traceability.sh --strict requirements/sample`
128 exits 1 when at least one artifact has `ratified_by: ""`.
129- [ ] `bash scripts/gen-rtm.sh requirements/sample` writes a
130 non-empty `docs/rtm-sample.md`.
131- [ ] `bash scripts/verify.sh` includes the traceability gate in its
132 output and the run is green.