Datamodel categorization — five layers (Product / Architecture / SDLC / Work / Planning-meta)
Status: open/accepted
Summary
Section titled “Summary”- Entities are grouped into five layers — Product, Architecture, SDLC, Work, and Planning-meta — each answering a distinct question about the project (Decision).
- Layered framing assigns each entity its purpose by position, so a reader infers role from neighborhood instead of from the type name alone (Why).
- A fifth Planning-meta layer is added beyond the canonical four to house governance artifacts (Decisions, Standards, Principles) that otherwise have no home (Why).
- Each layer reads as a chain — purpose, structure, verification, execution, governance — so the entity roster reveals the system’s shape before any specific type (How to read the layers).
- This ADR fixes only the categorization; per-entity roster, schemas, lifecycles, and adoption order live elsewhere (Out of scope).
- Boundary cases and the “Planning-meta” name itself remain open and are resolved per-entity or by future rename, not pre-committed here (Open questions).
Decision
Section titled “Decision”Entities SDLC tracks are grouped into five layers, each answering a distinct question about the project:
| Layer | Question it answers | Example entity types |
|---|---|---|
| Product | Why we’re building | Product, Driver, Goal |
| Architecture | How the system is structured | Capability, Constraint |
| SDLC | What must be built and verified | Requirement, AcceptanceCriterion |
| Work | How and when work gets done | Milestone, Task |
| Planning-meta | How we reason about the project itself | Decision, Standard, Principle |
Examples above are illustrative; the authoritative roster is D-ORMG-data-model.
This ADR fixes the categorization. The roster of entities per layer
— status, purpose, source — lives in D-ORMG-data-model. Per-entity
schemas and definitions live under plugin/lib/model/entities/<type>/.
Layered framing tells a reader the role of each entity by position. A flat entity list (“Milestone, Task, Capability, Requirement, Standard, Principle, Backlog, …”) forces inference of purpose from the type name. Grouping under explicit layers gives each entity its rationale by neighborhood: an entity in the Product layer answers why are we building this?; one in the SDLC layer answers what must be verified?
Five layers, not four. The canonical Product / Architecture / SDLC / Work split (common in PRD-driven systems) covers substantive work but leaves project-governance artifacts (Decisions, Standards, Principles, planning rosters) homeless. The Planning-meta layer is sdlc-specific and houses those. The stance: if an artifact has a schema and validates, it’s an entity — and Decisions, Standards, Principles all qualify.
How to read the layers
Section titled “How to read the layers”- Product — the purpose chain: why the system exists, what problems it solves, what outcomes it targets.
- Architecture — the structural chain: what the system does and the non-negotiable boundaries that shape how.
- SDLC — the verification chain: requirements that elaborate capabilities, and acceptance criteria that test them.
- Work — the execution chain: time-bound groupings of effort (Milestone) and atomic units of effort (Task).
- Planning-meta — the governance chain: artifacts that record why this and not that (Decision), what rule binds here (Standard), and what value drives judgment (Principle).
A reader navigating the entity roster by layer learns the shape of the system before learning any specific entity type.
Out of scope
Section titled “Out of scope”- Per-entity design. Which entities ship in each layer, their
schemas, and their lifecycles live in D-ORMG-data-model and
each entity’s own
definition.mdunderplugin/lib/model/entities/<type>/. This ADR fixes the categorization; the roster fixes membership. - Adoption order. Milestone-by-milestone sequencing for which
entities ship when lives in
index(milestone order byversion; the roadmap manifest is retired). - Identity convention. See D-0002-entity-identifier-shape.
- Definition contract. See S-0005-entity-definition-contract.
Open questions
Section titled “Open questions”- Boundary cases between layers. Some entities could plausibly sit in two layers (e.g., is Backlog a Work-layer queue of effort or a Planning-meta artifact?). Resolved per-entity in D-ORMG-data-model; this ADR doesn’t pre-commit a position.
- Is “Planning-meta” the right name? “Governance,” “Meta,” and “Process” were considered; Planning-meta won on being descriptive without sounding bureaucratic. Open to renaming if a better candidate surfaces.
- P-0008-harness-agnostic-substrate underwrites why this ADR doesn’t address storage: the categorization is a property of the entities, not of any particular harness’s view of them.
- This ADR supersedes the earlier entity-model design document
(
docs/planning/decisions/entity-model/README.md), which mixed categorization with per-entity design. Per-entity design lives in D-ORMG-data-model (roster) and per-entitydefinition.mdfiles.