Skip to main content
Refs are directed semantic edges between primitives. You store them in the refs array of a .ready.yml file. Each ref records a role, a source primitive (from), and a target primitive (to). Tools that compile product views, validate the tree, and traverse the primitive graph all depend on these edges being stored in the correct canonical direction.

​
The five approved ref roles

RoleSource typeTarget typeMeaning
servesintentpremiseThe intent addresses a root product premise
contains_premiseintentpremiseThe intent owns a subordinate premise that appears under that intent rather than as a root premise
requiresintentserviceThe intent depends on a service to build, prove, run, or monitor the product
governed_byintentstandardThe intent must obey a standard
questionsquestion_cardany primitiveThe question card is about the target primitive

​
Canonical primary tree edges

Store one directed edge for each relationship. The canonical direction always runs from the more specific primitive to the more foundational one: 
# intent → premise
refs:
  - from: I-001
    role: serves
    to: P-001

# intent → subordinate premise
refs:
  - from: I-002
    role: contains_premise
    to: P-002

# intent → service
refs:
  - from: I-001
    role: requires
    to: SV-001

# intent → standard
refs:
  - from: I-001
    role: governed_by
    to: ST-001

# question card → any primitive
refs:
  - from: QC-001
    role: questions
    to: I-003

​
Inverse edges — do NOT store

Do not store inverse edges such as premise --serves--> intent, service --serves--> intent, or standard --serves--> intent. Reader views derive inverse labels automatically from the one canonical edge you store.
Storing both the canonical edge and its inverse creates two competing sources of truth for the same relationship. Validators will flag duplicate or conflicting edges. Store the canonical direction only.
For example, if you have stored intent I-001 --serves--> premise P-001, a compiled view of P-001 can automatically show “served by: I-001” without any additional edge in the tree.

​
Ref syntax

​
Full ref format

Use the full format when the edge source is a different primitive than the file you are editing, or when you want the direction to be unambiguous at a glance: 
refs:
  - from: I-001
    role: serves
    to: P-001

​
Compact ref format

Use compact refs when the current primitive is the edge source. The from field is inferred as the id of the current file: 
refs:
  - role: requires
    id: SV-001
In compact format the field is id, not to. Importers expand id to to and infer from as the current primitive id during parsing.
Use compact refs only for outgoing edges from the current primitive. If you need to store an edge whose source is another primitive — for example, when back-filling a relationship discovered during review — write the explicit from and to so the canonical direction is unambiguous.

​
When to use explicit vs. compact

SituationUse
Current file is the edge source (from)Compact: role + id
Edge source is a different primitiveExplicit: from + role + to
Documenting multiple edges with mixed sourcesExplicit for all, for clarity

​
required_services and required_standards fields

Some intent templates include required_services and required_standards as named fields inside fields. These are reader aids — they make compiled summaries easier to scan. They do not replace canonical refs entries.
You must still write matching refs entries with role: requires and role: governed_by for every service and standard listed in required_services and required_standards. Validators and graph-traversal tools follow the refs array, not the prose fields.

​
Validation rules for refs

  • Directed refs must point to existing ids within the product tree. A ref to a non-existent id causes an import failure.
  • Ref roles must be one of the five approved values. Any other role value causes an import failure.
  • Compact refs are expanded during import. If expansion produces an ambiguous from, the validator reports an error.
See Validator Rules for the complete list of required checks.