Every entity ships a complete definition surface

Status: open/draft

Summary

• Every entity directory ships a fixed surface — schema.ts (the Zod frontmatter schema AND the markdown-contract body grammar, exported together), body-template.eta, definition.md, plus the optional obsidian-index.yaml — and is discoverable by its type: directory name, registration in the entity schema registry, and a D-ORMG-data-model entry.

Rule

Every entity directory under solutions/ontological/lib/model/entities/<type>/ ships:

Artifact	Required	Purpose
schema.ts	yes	The entity’s full two-plane contract. Exports the Zod frontmatter schema (a CommonFrontmatter.extend({ … }).strict() declaring required fields, enums, and .default()s, registered in _registry.ts) AND the markdown-contract Contract (that same Zod schema as the frontmatter plane, plus the body grammar — required/optional H2 sections and content leaves), registered in _contracts.ts. Validation and docs both derive from it.
body-template.eta	yes	Eta body template for new instances. Body-only — no frontmatter block. Where an entity’s body shape varies by a routing key (a task’s kind:), this file ships the floor — the sections every instance carries — and the per-kind shape comes from the routed process’s registration, never from a second template here.
definition.md	yes	Human reference: Purpose, Identifier, Frontmatter, Body shape, Lifecycle, Relationships, Operations, Position in model, Summary.
obsidian-index.yaml	optional	Obsidian Bases view template, materialized into a consuming project by /sdlc:setup --obsidian.
ops/<op>.ts	optional	defineOp descriptor modules (D-0007-deterministic-op-substrate).

Plus discoverability:

• The directory name is the type:; instances carry it in frontmatter.
• The entity appears in D-ORMG-data-model.

Variant body grammars

One type: has one frontmatter schema and one body-template file. Where the body shape varies by a routing key, the contract declares it in two parts:

• the common floor — the H2 sections every instance of the type: carries — declared required in the entity’s markdown-contract body plane and rendered by body-template.eta;
• a variant overlay — the per-kind sections — resolved at authoring and validation time from the routed process’s readiness contract, not enumerated in schema.ts.

The frontmatter plane stays single and strict: one Zod schema per type:, .strict(), no per-kind branching. Only the body plane varies.

Worked case: sdlc task create --kind renders the routed process’s shape over the floor template (D-VSLI-distributed-work-runner-architecture), so a kind: research task and a kind: implementation task share the floor and differ below it. Spec depth is a property of the routed process; the entity contract owns only what every instance shares.

See D-0004-entity-definition-architecture for the architecture this rule presupposes — common-denominator frontmatter, file shapes, the Obsidian Bases template, the operations contract, and discovery.

Why

A uniform surface keeps the model self-describing: adding an entity is a known shape, and the framework reads every entity the same way. Without it each entity grows its own glue, drift starts on day one, and the model becomes a collection of exceptions.

How to apply

Follow the surface in D-0004-entity-definition-architecture. New entities satisfy it on day one; all shipped types satisfy it — the former backlog / task gap closed with the authoring pipeline (T-87GH-new-scripts-derive-schema-bound-values), which synthesizes frontmatter from the entity’s Zod schema and renders body-template.eta, validating both before write; capability / driver / product shipped conformant on day one (2026-06-04).

Deterministic checks

Tool	Checks
sdlc entities validate (the per-type markdown-contract contract)	Frontmatter AND body conformance for any instance in one pass — resolves the per-type contract from _contracts.ts and emits markdown-contract findings.
solutions/ontological/lib/model/authoring.ts (authorEntity)	Born-valid: synthesized frontmatter and the rendered body are validated against the entity contract before any write.
/project-check → check_entities.ts	Field-name and status enum references in prose match the Zod schema (projected to JSON in memory); body templates are body-only (no frontmatter block).
/project-check → check_entity_bases.ts	Every obsidian-index.yaml parses as a valid Obsidian Bases document (via the entities validate --flavor base path).
solutions/ontological/lib/model/entity.ts	Projection over the surface, shared by the validator, scaffolder, and dispatcher; validateFrontmatter routes through the per-type contract’s frontmatter plane.

Remaining surface-drift checks — four-artifact presence, Operations table presence, Surface declarations match reality — land with T-0001 and the registry drift checks (T-0014). The validators are authoritative; this Standard points at them rather than narrating what a tool can decide.

Anti-examples

• schema.ts but no body-template.eta: no scaffolded starting point.
• A schema.ts whose contract declares no body grammar: body shape is prose-only; the validator can’t catch drift.
• Multiple per-entity reference docs where one definition.md would consolidate: discovery cost grows and the H2 set drifts across docs.
• Frontmatter the validator doesn’t recognize (“we’ll add it later”): drift starts on day one.
• New entity missing from D-ORMG-data-model: not discoverable.

Notes

• Architecture concerns — common-denominator frontmatter, the Obsidian Bases template, operations contract, discovery, the entity.ts projection — live in D-0004-entity-definition-architecture; this Standard does not duplicate them.
• The body grammar is defined in each entity’s schema.ts as its markdown-contract contract (the body plane alongside the Zod frontmatter plane), validated through _contracts.ts.
• A readiness contract is a process artifact, not an entity artifact. The implementation process’s implementation-ready.md belongs to that process’s registration and travels with it. Do not add it — or any future per-kind contract — to the required-artifact table above. That table is the universal surface every type: ships; putting a per-kind contract in it would re-universalize the exact gate D-VSLI-distributed-work-runner-architecture demotes to one process’s private business.

---

← Back to Standards