Requirement Traceability is the bridge from the domain model to the system requirements it realizes. Every concept in the metamodel carries an implicit satisfies list — zero or more system requirement identifiers — and every bounded context or organization that loads requirements from a file carries a requirements-source pointer. Together they make the provenance of a domain model explicit, navigable, and auditable: for any element, why does it exist; for any requirement, how is it realized.

The satisfies attribute

Every concept in the metamodel — entity, aggregate, value type, operation, command, query, event (of any subtype), state machine, invariant, reaction, agreement, reconciliation, escalation chain, domain service, application service, infrastructure service, interface, module — carries a satisfies list. The list contains zero or more system requirement identifiers (e.g., REQ-ORD-001, REQ-RIDE-020).

The attribute is implicit across the whole metamodel. It is never redeclared per concept — it is always available.

Example:

entity Order {
  satisfies [REQ-ORD-002, REQ-ORD-007]
  ...
}

When Traceability is Required

The rule is binary, and it hinges on input.

• If system requirements are provided as input and each requirement has an identifier, the domain model MUST include satisfies references on every element that realizes a requirement. A domain model element without satisfies when requirements exist is either an orphan (no requirement justifies it) or a traceability gap (the link was omitted). Both cases must be made explicit.
• If no system requirements are provided, satisfies is left empty on all elements. The domain model remains valid — traceability is additive, not blocking. Do not invent requirement identifiers to fill the list.

See the system requirements reference for how requirements are defined and identified in the upstream layer.

How it Works

The satisfies attribute is a list of requirement identifiers. Each identifier references a requirement defined in the system requirement layer. The reference is a string match — no structural link, just the identifier. The tooling resolves the string against the requirements file declared by requirements-source.

The relationship is many-to-many:

• A single domain model element may satisfy multiple requirements.
• A single requirement may be satisfied by multiple domain model elements.

requirements-source

When requirements come from a file, the domain model must declare a requirements-source attribute at the organization or bounded context level. The value is a relative path (relative to the .domain file’s location) that points to the requirements file.

The name mirrors prd-source on a requirement set — each layer’s upstream pointer is named after what it points to, not after where it lives. A domain file points at requirements (hence requirements-source); a requirements file points at the PRD (hence prd-source). The asymmetry in the names is deliberate.

Why it matters:

• The path makes satisfies identifiers resolvable. An agent or tool can follow the link, read the requirements, and perform coverage or drift analysis without guessing which requirements the identifiers refer to.
• Multiple requirements-source declarations are allowed when requirements span several files.
• Without requirements-source, satisfies identifiers are unanchored strings — they carry no provenance, and no tool can verify them.

Example:

organization Acme {
  requirements-source "specs/order-requirements.sysreq"
  requirements-source "specs/payment-requirements.sysreq"

  context OrderContext { ... }
  context PaymentContext { ... }
}

Traceability by Concept Type

The metamodel expects different satisfaction roles for different concept types. The role tells the modeler — and any agent building a domain model — which kind of link to record. The table below maps each domain concept to its typical satisfaction role:

The role is not a separate attribute — it is simply the kind of coverage a concept provides. An entity structures data; an invariant enforces a rule; a reconciliation reconciles cross-aggregate truths. Keeping roles in mind helps the modeler spot a missing link: if a requirement says “the system must reject X”, the concept that satisfies it is an invariant or a precondition, not an entity.

Bidirectional Traceability

Traceability runs in two directions, and both matter:

• Top-down (requirement → domain). From a requirement identifier, find all domain elements whose satisfies list contains that identifier. Answers: how is this requirement realized?
• Bottom-up (domain → requirement). From a domain element, read its satisfies list. Answers: why does this element exist? which business obligation justifies it?

Both queries must be computable. The requirements-source attribute makes the top-down direction possible: without it, there is no file to scan against the satisfies identifiers.

Orphan vs. Unsatisfied

Two failure modes of traceability, and they are not the same:

• Orphan. A domain element with an empty satisfies list when requirements are available. The element exists, but no requirement justifies it. An orphan is either over-engineering (build too much) or a missing requirement (build the right thing for the wrong reason). Either way, it is a signal that something should be questioned.
• Unsatisfied. A requirement whose identifier appears in no domain element’s satisfies list. The domain model has a gap: an obligation has been declared upstream and not realized downstream. Unsatisfied requirements block coverage goals and must be flagged.

Both are detectable by automated tools once requirements-source is resolvable. Both are cheap to fix when caught early and expensive when caught late.

Agent Instruction Summary

When building or updating a domain model, an agent (human or automated) should follow this five-step procedure:

1. Check if system requirements are provided. Look for a .sysreq file, a requirements section, or any input containing EARS statements with identifiers.
2. If requirements come from a file, add a requirements-source declaration at the bounded context or organization level with the relative path. This is mandatory — it is the provenance link that makes satisfies identifiers resolvable.
3. If requirements exist, for every domain model element created or modified, determine which requirement(s) it realizes and populate the satisfies list with the corresponding identifier(s). Do not leave satisfies empty unless the element genuinely satisfies no requirement — and in that case, question whether the element should exist.
4. If no requirements exist, leave satisfies empty and omit requirements-source. Do not invent requirement identifiers.
5. After building the model, verify coverage: every must and should requirement should appear in at least one element’s satisfies list. Flag any unsatisfied requirement as a gap. Flag any orphan as a candidate for removal or for a missing requirement.

Example:

organization Acme {
  requirements-source "specs/order-requirements.sysreq"

  context OrderContext {
    entity Order {
      satisfies [REQ-ORD-002, REQ-ORD-007]
      ...
    }

    invariant positiveQuantity {
      satisfies [REQ-ORD-001]
      scope: aggregate Order
      predicate: forAll(line in order.lines, line.quantity > 0)
      enforcement: rejection
    }

    command PlaceOrder {
      satisfies [REQ-ORD-002]
      id: CommandId
      customer: CustomerId
      lines: LineItem[]
      targets Order
      triggers Order.place
    }

    reaction notifyOnStockout {
      satisfies [REQ-ORD-004]
      triggered by: InventoryDepleted
      effect: command CancelPromotion(product)
    }
  }
}

Every concept carries its satisfies list; the bounded context declares its requirements-source. Any tool can now resolve REQ-ORD-001 upward from positiveQuantity, or resolve REQ-ORD-004 downward to find notifyOnStockout. The model is traceable end-to-end.