Skip to main content
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.
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.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.
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.
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 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.

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