andreaswasita/copilot-agents-dojo/traceability-gate

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

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:

1. All required frontmatter keys present (id, layer, title,

parent_ids, owner, measurable, ratified_by, derivation_skill).

1. id matches filename and starts with the correct layer prefix.
2. layer is in {BR, FR, NFR, SR, IR, TR}.
3. Every parent_ids entry resolves to an existing file in the same

engagement.

1. Every parent's layer is in the Valid parent layers column for

this artifact (see spec/artifact-schema.md §1).

1. measurable: true for NFR/SR/TR.
2. 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

• [ ] bash scripts/verify-traceability.sh requirements/sample exits 0.
• [ ] bash scripts/verify-traceability.sh --strict requirements/sample

exits 1 when at least one artifact has ratified_by: "".

• [ ] bash scripts/gen-rtm.sh requirements/sample writes a

non-empty docs/rtm-sample.md.

• [ ] bash scripts/verify.sh includes the traceability gate in its

output and the run is green.