# Shared Language

Use this page to keep the repository's ubiquitous language stable.
It is the project-wide glossary for terms that should mean one thing everywhere in design artifacts, code, tests, and reviews.

## Why this exists

Naming inconsistency creates design inconsistency.
When the same concept is called three different things, reviewers and LLMs start inventing distinctions that are not real.
A stable shared language improves design quality, review quality, and implementation consistency.

This file is for **project-wide terms**.
Feature-specific naming choices should also be recorded in the relevant design artifact.

## How to use it

- Add terms that appear across multiple features or modules.
- Prefer short domain definitions over implementation detail.
- Record preferred terms and rejected synonyms.
- Update this file when the team decides one name should win.
- Keep the grammar consistent with the naming rules in `../explanation/naming-for-domain-modeling.md`.

## Core grammar

- **Commands**: imperative intents such as `LoadPackage`
- **Events**: past-tense facts such as `PackageLoaded`
- **States / Objects**: domain nouns such as `LoadingTruck`
- **Workflows**: verb-noun names such as `loadPackage`
- **Policies**: decision-oriented names such as `decideLoadEligibility`

## Project-wide glossary template

| Term | Meaning | Use this, not that | Notes |
| :--- | :--- | :--- | :--- |
| `<PreferredTerm>` | `<Short domain meaning>` | `<PreferredTerm>` not `<RejectedSynonym>` | `<Optional note>` |
| `<PreferredTerm>` | `<Short domain meaning>` | `<PreferredTerm>` not `<RejectedSynonym>` | `<Optional note>` |

## Review questions

- Would a domain expert recognize these terms?
- Are the same concepts named consistently across story, events, model, code, and tests?
- Are we accidentally using programmer words where domain words should exist?
- Have we documented which synonym is preferred when multiple names are plausible?