> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dotready.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Ref Roles and Relationship Rules for Ready Primitives

> The five approved ref roles for Ready primitives, canonical edge directions, compact vs. explicit syntax, and rules for storing and deriving inverse edges.

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:

```yaml theme={null}
# 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.

<Warning>
  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.
</Warning>

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:

```yaml theme={null}
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:

```yaml theme={null}
refs:
  - role: requires
    id: SV-001
```

<Note>
  In compact format the field is `id`, not `to`. Importers expand `id` to `to` and infer `from` as the current primitive id during parsing.
</Note>

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.

<Note>
  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.
</Note>

## 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](/reference/validator-rules) for the complete list of required checks.