Task: Generate DOMAIN.md — Authoritative Domain Layer

Task: Generate DOMAIN.md — Authoritative Domain Layer

Objective

Produce a DOMAIN.md that serves as the single source of truth for the system's domain layer at the concept level, independent of technology and UI. It merges what older guidance split as GLOSSARY + DOMAIN_MODEL: in Agent-Driven Development those two are always read together, so they live in one file. DOMAIN.md fixes the ubiquitous language (every term, one canonical definition), enumerates bounded contexts and their integration patterns, models entities/aggregates/value objects, names domain events (meaning only — wire schemas live in INTERFACES.md), lists domain services, and indexes every invariant with a stable INV-NN ID. An agent reading this document alone can speak the domain precisely — using the right terms, knowing which aggregate owns which invariant, and knowing which events exist and what they mean — without guessing or drifting from the vocabulary.

DOMAIN.md is the most-read artifact downstream in the ADD workflow (/architecture, every IA skill, /interfaces, /data, /behavior, /security, every per-unit /SPEC.md reads it). The bounded contexts enumerated in this document also define the area catalog used by units/<area>/u<NN>/. Treat every decision in this document as a commitment that propagates everywhere.

Inputs

1. PROPOSAL.md (required) — principles, scope, initial glossary. Seeds the ubiquitous language and bounds the domain.
2. USE_CASES.md (required) — actors and use cases with stable UC-NN IDs. Every entity and aggregate in this document must trace back to at least one use case. Use-case-specific terminology feeds the glossary.
3. Existing DOMAIN.md (auto-discovered — only if refining) — read fully and preserve every INV-NN and EVT-name already assigned. Never renumber stable IDs.
4. Reference material on the domain (optional) — industry vocabulary, regulations, standard models (e.g., the Push and Fetch terms in Git; the Order / Cart / Line Item vocabulary in e-commerce). Use to anchor terms to familiar meanings when available; override only with explicit rationale.

Read set size: 2 required inputs + up to 2 optional. Read them fully — truncated reads cause silent term drift.

Workflow

Domain modelling proceeds in seven phases: term harvest, glossary, bounded contexts and map, structural model (entities → aggregates → value objects), events and services, invariants index, and validation. Phases are sequential — later phases depend on earlier decisions — but revisit earlier phases if a later one reveals a missing term or a contradiction.

Phase 1: Term Harvest

Read PROPOSAL.md and USE_CASES.md end-to-end. Collect every domain noun, verb, and adjective into a working list. Separate three kinds of terms:

• Domain terms — Repository, Push, Commit, Access Control List, Tenant, Order, Cart. These belong in the glossary.
• Technical terms — HTTP request, JSON payload, SQL table, gRPC stub. These do NOT belong here. Flag them for architecture / interfaces / data.
• UI terms — dashboard, settings page, login button. These do NOT belong here. Flag them for IA skills.

If PROPOSAL.md ships with an initial glossary, treat it as an authoritative starting point — but expand, refine, and add missing terms from USE_CASES.md. The output's glossary must cover every domain term used anywhere in the system's artifacts, not just those the proposal listed.

For each harvested term, note every synonym encountered across the inputs (e.g., "repo" vs "repository", "user" vs "account" vs "principal"). You will pick one canonical form per term in Phase 2 and list the others as forbidden synonyms.

Phase 2: Glossary (Ubiquitous Language)

Pick one canonical form per term and define it in § 1 Glossary. Every entry has term, definition (one–two sentences), category (entity / value-object / aggregate / event / service / external / relationship), the document section where the term is formally modelled, and — critically — a (not: X) list of forbidden synonyms.