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.
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.ymlYAML 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
typeis a valid enum value (premise,intent,standard,service, orquestion_card).
- Directed refs point to existing ids within the product tree.
- Ref roles are approved (
serves,contains_premise,requires,governed_by, orquestions). See Ref Roles.
- 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.ymlrecord.
- Seed and delta flags are non-claimable unless they pass the claim gate.
- Claimable flags carry Completion Proof.
readyflags with a non-emptyblocked_byfield remain non-claimable regardless of other fields.
- Primitive files do not carry implementation lifecycle state. Coding lifecycle belongs on seed and delta flags, not on primitive bodies.
- 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 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 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:- Report exact locations. Every violation message must include the repo-relative file path and the primitive id.
- Do not silently fix semantic errors. Return the error and let the author correct the source record.
- Do not average conflicting documents. If two records claim authority over the same fact, report the conflict.
- 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.