Conformance

A conformance claim MUST identify both the method/spec version and the serialization version. The pair selects the accepted document set and semantic contract. A conforming v0.2 implementation MUST recognise the expanded v1alpha1 schemas and semantics; conformance only to the tagged v0.1 specification does not establish conformance to v0.2.

An implementation MAY additionally record the Git revision of the specification repository content it observed. That revision identifies the observed input state and MUST NOT substitute for either claimed version.

Repository conformance

A repository conforms to Product Definition as Code v0.2 when:

1. Its canonical product definition lives in a git repository, the model repository, under the product root selected by Configuration, with the model/ root and changes/ lifecycle directories defined in this specification. Subdirectories below model/ are non-normative; artifact kinds are discovered from frontmatter type, not paths. See Specification index → Canonical authority and Topologies.
2. Every product artifact satisfies the artifact contracts: valid frontmatter per schema, required body sections, valid lifecycle state.
3. Every ID satisfies the identifier rules and every reference satisfies the relationship vocabulary.
4. Structural validation of the baseline reports no errors. Warnings are permitted.
5. The Product Definition is the accepted product intent on the repository’s canonical branch; semantic evolution happens only through Product Changes, applied by an explicit human-triggered apply and accepted by a reviewed merge. The first Product Definition enters through CHG-INITIAL, the same mechanism as every later change.
6. Every live Product Change satisfies the change contract: valid change.md frontmatter per schema, required body sections, operations consistent with proposed/, and an overlay that validates without errors.
7. Consumer documents outside docs/product/model MAY carry citations to canonical product text; a conforming tool verifies those citations per the citation contract.
8. The canonical product artifacts are files in the model repository. A network service MUST NOT be the source of truth for the Product Definition. See Services over the model.

Clauses 1, 5 and 8 rest on facts a fixture cannot observe: a git repository, a canonical branch, a reviewed merge, and the absence of an external source of truth. They are verified by review of the repository, not by the conformance tests.

Topologies

The model repository MAY be the same repository as the software it defines (co-located topology) or a repository of its own (dedicated topology). Both conform.

When one repository serves the product, co-location SHOULD be the default: the definition, its review history and the software stay on one review surface.

Both topologies use the same product roots, the same artifact contracts, the same validation and the same Product Change lifecycle. A dedicated model repository is not a different kind of repository, only one whose software lives elsewhere.

A model repository holds one Product Definition. Splitting a single Product Definition across repositories is out of scope for v0.2.

Layout	Topology	v0.2
Monorepo: one repository holding the product and its software	co-located	conforms, and is the default
One repository per product, beside the software it defines	co-located	conforms, and is the default
One product spanning several software repositories	dedicated	conforms; each consuming repository carries the pointer below
One Product Definition split across several repositories	neither	out of scope; a model repository holds one Product Definition

The model-repository pointer

In the dedicated topology, a consuming repository SHOULD carry a machine-readable pointer to the model repository, so that a tool or an agent can find the product context instead of being told out of band where it is.

The pointer is a record. It MUST carry:

Field	Presence	Meaning
repository	required	a resolvable git location of the model repository
revision	required	a git revision resolving to exactly one commit
product-root	required	the product root path within the model repository

revision MUST NOT be a branch name. A branch moves, so a pointer to one resolves to different files on different days, which deterministic validation forbids. A repository that follows a branch advances its pointer, which is a reviewable diff.

product-root is required because the product root is configurable, so a consumer MUST NOT assume docs/product.

The pointer MUST be readable as data, without executing code.

The pointer locates the model repository and MUST NOT contain, summarize or restate product artifacts.

A consuming repository carries at most one model-repository pointer in v0.2.

This specification fixes the pointer’s record shape. It does not fix the pointer’s serialization or its location in the consuming repository, exactly as the Citation Contract fixes the citation record and not one of its three forms. Resolution is implementation-defined in v0.2: how an implementation fetches the model repository, caches it, authenticates, and what it reports when the repository is unreachable. PRODUCT070-PRODUCT079 is reserved for model-repository resolution and no code in that band is issued in v0.2.

Services over the model

A network service, whether a database, a wiki, an issue tracker or an API, MUST NOT be the source of truth for a Product Definition.

Services that serve the compiled graph or projections of it, including read APIs, agent-facing servers and dashboards, are permitted and encouraged. They are generated outputs, so they are reproducible from canonical files and never authoritative (Specification index → Canonical authority).

Implementation conformance

An implementation (tooling) conforms when:

1. It validates every mechanically checkable structural rule over repository content deterministically, emitting the diagnostic codes, fields, ordering and exit codes defined in Validation.
2. It compiles the product graph exclusively from canonical files and can always rebuild every derived output.
3. It derives reverse relationships and never requires reciprocal authoring.
4. It computes digests with the mandated LF normalization.
5. It validates a Product Change by compiling and validating its overlay, without modifying any baseline file.
6. It applies a Product Change only under the rules in Product Changes → Apply: approved status (PRODUCT028 otherwise), revalidated overlay, baseline-revision compatibility, computed and reported product diff, --dry-run support, never implicitly, never committing. It MUST NOT treat a successful apply as acceptance.
7. It MUST NOT merge a proposal that fails structural validation (the CI gate); validation of a proposed tree is full structural validation.
8. It MUST NOT merge, auto-approve or self-merge model changes: merging is a human decision.
9. It MUST compute citation statuses deterministically per the citation contract.
10. It discovers and validates the versioned Configuration, uses its product root, and treats warnings as non-fatal unless validation.warnings-as-errors is true.
11. It MUST NOT require a co-located software tree in order to validate a Product Definition (Topologies).
12. It MUST NOT read canonical product artifacts from a network service. It MAY serve them (Services over the model).
13. When it claims population-aware consumer verification for an integration, it enumerates and classifies that provider’s current document population and reports PRODUCT064-PRODUCT066 under the Citation Contract. Implementations that provide no such integration remain conforming.
14. It dispatches schema and semantic validation by the claimed method/spec and serialization version, and recognises Structured Behaviour as an optional Product Artifact in v0.2 v1alpha1, including its schema, canonical relationships, Product Change operations, graph and impact participation, citation target behaviour and the inline-or-reference Requirement verification union.

Violation mapping

Diagnostic mapping applies to mechanically checkable structural rules over repository content. Each such violation maps to a diagnostic in Validation. The conformance fixtures under conformance/cases/ exercise representative mapped violations and assert their codes; uncovered codes remain explicit coverage gaps.

Other normative statements remain conformance criteria without pretending to be deterministic diagnostics. Repository and history-dependent facts, including clauses 1, 5 and 8 of repository conformance and the prohibition on ID reuse, are verified by review. Semantic authoring constraints, such as whether an artifact body contains implementation design, a term definition merely repeats its title, Structured Behaviour clauses restate another canonical carrier, two verification entries express the same behaviour or a consumer omitted a semantic dependency, require human judgement. Obligations on implementation behaviour that a flat repository fixture cannot observe, including never self-merging and reporting an apply product diff, are also verified by review of the implementation and its operation. Naming these review categories does not claim that a review occurred on any particular merge.

Diagnostic codes are stable and are never renumbered or reused. A change to mechanically checkable normative behaviour MUST update the specification, diagnostic table and applicable fixtures together. A change to a review-conformance criterion updates its normative text and review evidence; it does not receive a diagnostic merely to satisfy a universal mapping claim.

Consumer projections remain provider-specific and non-canonical. Conformance tests MUST NOT require OpenSpec, Spec Kit, Kiro, Cucumber or any other named consumer.