> ## 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.

# Required and Warning Validator Rules for Ready Trees

> All required and warning-level validation checks that a conforming Ready product-tree importer or docs compiler must apply before accepting source truth.

A product-tree importer should fail loudly when source truth is ambiguous. Silent fixes, averaged conflicting documents, and promoted open flags introduce errors that propagate through every compiled view, work package, and agent brief that depends on the tree. Validators that report exact file paths and ids make broken records easy to find and correct.

<Note>
  Two categories of checks exist: **required checks** that cause an import to fail, and **warning checks** that emit a warning but allow the import to continue. Treat warnings as signals that a primitive may be incomplete or misleading even though it is technically valid.
</Note>

## Required checks

The following conditions must all be true for an import to succeed. A validator that encounters any of these violations must report the exact file path and id before halting.

**Source record format**

* Every primitive source record is a `.ready.yml` YAML document.
* Every primitive source record has `schema: readyroom/primitive/v1`.
* Every primitive source record has `kind: primitive`.
* Every primitive source record has a stable `id`.
* No two records share the same `id`.
* Primitive `type` is a valid enum value (`premise`, `intent`, `standard`, `service`, or `question_card`).

**Relationships**

* Directed refs point to existing ids within the product tree.
* Ref roles are approved (`serves`, `contains_premise`, `requires`, `governed_by`, or `questions`). See [Ref Roles](/reference/ref-roles).

**Index and generated output integrity**

* Generated indexes do not carry independent primitive truth. An index file must not be the canonical source for any field that belongs in a `.ready.yml` record.

**Flags and coding claims**

* Seed and delta flags are non-claimable unless they pass the claim gate.
* Claimable flags carry Completion Proof.
* `ready` flags with a non-empty `blocked_by` field remain non-claimable regardless of other fields.

**Lifecycle separation**

* Primitive files do not carry implementation lifecycle state. Coding lifecycle belongs on seed and delta flags, not on primitive bodies.

**Content placement**

* Project-specific governance docs are stored under `ready/governance/`, not artifact directories.
* Project-agnostic Ready resources and templates are referenced from the Ready standard package or an explicitly vendored copy, not artifact directories.

**Artifact integrity**

* Artifact ids are unique within their artifact family (for example, no two `SA-*` ids exist across all samples in the same stage).
* Sensitive content, source excerpts, diffs, raw logs, and secrets are absent from all artifact files.
* Large artifacts use storage paths or external refs instead of inline payloads.

<Warning>
  A validator must not silently fix semantic errors, average conflicting documents, or promote open flags into the coding workflow. Report the violation and stop.
</Warning>

## Warning checks

The following conditions do not cause an import to fail, but they indicate that a primitive may be incomplete or low confidence. Emit a warning with the file path and id for each violation.

| Warning                                                             | Meaning                                                                                                     |
| ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Primitive body is too large to review comfortably                   | The record should be split or its bulky content moved to an artifact                                        |
| Premise confidence is low without a discovery flag or question card | A low-confidence premise needs evidence anchored in a discovery flag or an open question card               |
| Intent lacks failure behavior                                       | The `failure_behavior` field in `fields` is absent or empty                                                 |
| Intent lacks required services or standards                         | The intent has no `requires` or `governed_by` refs and no `required_services` / `required_standards` fields |
| Quality-bearing intent lacks an Operating Envelope                  | An intent whose behavior can vary materially after release should define an Operating Envelope in `fields`  |
| Service readiness is unknown without a blocker                      | A service with no readiness field and no blocking flag may be silently incomplete                           |
| Product-shaping ambiguity appears only in prose                     | Ambiguity that should become a `question_card` primitive is buried in prose instead                         |

## Importer behavior rules

Follow these rules when implementing a Ready product-tree importer or docs compiler:

1. **Report exact locations.** Every violation message must include the repo-relative file path and the primitive id.
2. **Do not silently fix semantic errors.** Return the error and let the author correct the source record.
3. **Do not average conflicting documents.** If two records claim authority over the same fact, report the conflict.
4. **Do not promote open flags.** A seed or delta flag that has not passed the claim gate must never be treated as a completed claim.

<Tip>
  Run the validator in CI on every pull request that touches the `ready/` directory. This catches id conflicts, broken refs, and misplaced content before they reach any compiled view or agent brief.
</Tip>