Ref Roles and Relationship Rules for Ready Primitives

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

Role	Source type	Target type	Meaning
`serves`	`intent`	`premise`	The intent addresses a root product premise
`contains_premise`	`intent`	`premise`	The intent owns a subordinate premise that appears under that intent rather than as a root premise
`requires`	`intent`	`service`	The intent depends on a service to build, prove, run, or monitor the product
`governed_by`	`intent`	`standard`	The intent must obey a standard
`questions`	`question_card`	any primitive	The 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

Situation	Use
Current file is the edge source (`from`)	Compact: `role` + `id`
Edge source is a different primitive	Explicit: `from` + `role` + `to`
Documenting multiple edges with mixed sources	Explicit 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.

​The five approved ref roles

​Canonical primary tree edges

​Inverse edges — do NOT store

​Ref syntax

​Full ref format

​Compact ref format

​When to use explicit vs. compact

​required_services and required_standards fields

​Validation rules for refs

The five approved ref roles

Canonical primary tree edges

Inverse edges — do NOT store

Ref syntax

Full ref format

Compact ref format

When to use explicit vs. compact

`required_services` and `required_standards` fields

Validation rules for refs