Terminology
Definitions used normatively throughout this specification.
Product Artifact. An independently addressable unit of product knowledge with a stable immutable ID: an Actor, Journey, Use Case, Business Rule, Domain Term, Bounded Context, Functional Requirement, Quality Requirement or Constraint. Product Changes, Delivery Slices and Product Handoffs also carry IDs but are not part of the current product model.
Current Product Model (Baseline). The set of product artifacts under docs/product/model.
It describes the product as currently defined, including behaviour that is implemented and
accepted. Also called the baseline when a Product Change is validated against it.
Product Graph. The derived directed graph whose nodes are product artifacts and whose typed edges are the canonical relationships declared in artifact frontmatter, together with derived reverse indexes. The graph is always compiled from the canonical files and is never authored.
Product Change. An explicit, versioned delta against the baseline: additions, modifications
and removals, each represented by complete proposed future-state artifacts, plus rationale and open
questions. Stored under docs/product/changes/.
Overlay. The virtual product model obtained by applying a Product Change’s operations to the baseline without modifying baseline files. Validation of a Product Change compiles and validates the overlay.
Delivery Slice. A coherent, implementable, verifiable product increment carved out of an approved Product Change, with explicit requirement coverage and verification declarations.
Product Handoff. A generated, framework-independent contract that packages the product subgraph relevant to one delivery increment — artifact list, digests, source revision, work-item reference — for consumption by a Spec-Driven Development (SDD) framework.
Product Context. The generated human-readable document (product-context.md) accompanying a
Product Handoff. It is non-canonical.
Promotion. The explicit operation that applies an implemented and verified Product Change’s
operations to the baseline and moves the change to changes/completed.
Staleness. The state of a Product Handoff whose referenced artifacts’ content digests no longer match the current canonical content. Staleness is judged per referenced artifact, never by unrelated repository activity.
Canonical / Derived / Generated. Canonical files are authored by humans (possibly assisted by AI) and are the source of truth. Derived or generated files are produced by tooling from canonical files, are reproducible, and MUST NOT be edited by hand.
Managed File. A generated provider-integration file carrying a managed-file header. Managed files are regenerated by the implementation and checked for manual modification. Management covers absence as well as presence: a managed file the current assets and configuration no longer produce is removed, provided its content still matches what was recorded for it.
Provenance. The evidence behind a recovered claim: where the knowledge came from, how strongly that source supports it, and how it was recovered. Provenance is an epistemic property of an artifact’s content, not a record of authorship — Git history remains the record of who changed what and when — and it is set only on artifacts recovered from an existing system. See the Frontmatter reference.
SDD (Spec-Driven Development) framework. A framework such as OpenSpec that owns the specification, design, task and verification workflow for one implementation increment. SDD frameworks consume Product Handoffs; they do not own canonical product semantics.
Structural impact. The set of artifacts reachable from a given artifact through graph edges within a stated direction and depth. Structural impact is deterministic and makes no semantic claim.
Diagnostic. A machine-readable validation finding with severity, stable code, message, source file and, when available, artifact ID, field and target ID.