# Experimental: The Living Domain Model

**Status: Lab · optional working hypothesis · expected to change.**
Recommended when a brief must stay useful across repeated work, changing
evidence, multiple consumers, or agent sessions. Evidence includes two public
format simulations and one private live-product field test; independent
team-scale use remains an open question. Feedback is especially useful on
cold-team usability, update rituals, and whether the proposed structure stays
lightweight at scale.

Use this draft when a Domain Context Brief needs to survive past its first
use: repeated work, changing evidence, multiple consumers, and agents that
read it every session.

This is a Lab under the framework's publication and maturity rule. It
synthesizes the
[brief-to-living-model simulation](./evaluations/brief-to-living-domain-model-simulation.md?source=1),
the [OKF format experiment](./evaluations/okf-living-domain-model-experiment.md?source=1),
and a private live-product field test into one directional statement. The
private report remains unpublished; this Lab keeps its relevant findings
generalized. Use the ideas now where they help, while requiring more
independent evidence before making them recommended defaults.

## The Phase-Two Claim

Phase one of Domain Context Modeling answered: *what should a team write
down about the product world?* The brief is that answer, and the private
field test suggests the field set is broadly right — a product that never
used the framework had independently accumulated much of it under pressure.

Phase two answers a different question: **how does written-down meaning
stay true?** A brief is an orientation artifact; it is finished when the
work starts. The living domain model is a stewardship artifact; it is never
finished, and its value comes from being *currently trustworthy* rather
than *originally complete*. Teams are converging on nearby ideas — team
second brains, spec-driven agent development, docs-as-code — but this project
has not yet found a widely adopted practice that owns the durable, versioned
meaning layer humans and agents both maintain and consult. That layer is a
candidate second half of this framework.

## Minimum Viable Living Model

The simulation's original list, extended by the field test. A structured
file can satisfy all of it; no graph database, ontology platform, or custom
tool is required to start.

1. A declared scope and model identity.
2. Versioning and a change log (in a code repo, Git provides both).
3. Authoritative concepts, relationships, rules, and authority boundaries —
   the brief's content, which becomes the model's first revision.
4. Separate layers of truth: reusable meaning, policy assertions, project
   context — **and, for software products, an implementation layer:
   anchors** (see below).
5. Source references, evidence status, effective dates, freshness
   expectations.
6. Provenance marks on individual entries — a lightweight set such as
   `(locked)` / `(observed)` / `(assumed)`, dated where the date matters.
   Agents treat unmarked assumptions as law; the marks are the fix.
7. **A declined ledger**: ideas considered and refused, each with a reason
   and, where known, an unlock condition. Neither authoritative meaning nor
   policy — refused meaning. In practice this is the layer agents need
   most; without it they re-propose declined ideas as helpful suggestions.
8. Explicit applicability reasoning (per the simulation).
9. Stewardship roles and update triggers — within the three-tier authority
   model below.
10. Purpose-specific slices and representation guidance.

## Anchors: The Implementation Layer

The simulation's layers track *why we believe* an assertion (sources,
evidence, dates). A software product needs one more pointer per rule:
*where the rule is made true in the artifact.*

An **anchor** names the single enforcement point for a rule — a shared
predicate, a shared prompt file, a database policy, a validation. A rule
with an anchor is checkable: a reviewer or an agent can verify that the
model and the code still agree, and drift becomes detectable instead of
silent. A rule enforced only by *absence* (nothing in the product does X)
is a **negative anchor** — the weak kind, flagged so review guards it,
because no code change can trip it.

Field evidence: the live product's strongest rules each had exactly one
anchor before the model existed; writing the model consisted partly of naming
them. Product-identifying details remain private. The anchors argument also
settles where the model lives — see Placement.

## Three Authority Tiers

A complete model governs three distinct kinds of actor, and confusing them
is a common failure:

1. **Product authority** — what the product's people, software, and agents
   may do. The brief's Actions, Automation, and Authority field.
2. **Builder authority** — what the humans and agents *building* the
   product may do: who designs vs executes, what "done" and "shipped" mean,
   release and migration ceremony, secret handling. Teams practicing
   agent-assisted development already write this artifact (often named
   `AGENTS.md` or `CLAUDE.md`) without recognizing it as domain authority.
3. **Model stewardship** — who may propose, verify, confirm, lock, unlock,
   or retire entries in the model itself (per the simulation). A workable
   default: agents may propose `(observed)` entries; only accountable
   humans lock, unlock, or retire.

## Placement: The Model Lives With The Code

For a single system, the model belongs in the code repository, and anchors
make the case decisive: anchor links only resolve — and only stay
checkable — in-repo. Three compounding reasons: the maintenance covenant
needs the model and the change in one commit; agents receive the file
without retrieval infrastructure; and meaning changes appear in normal
diffs, so humans review a semantic change the way they review a schema
migration.

For multiple systems, split along authority, not convenience: **each
self-contained system owns the model for its own meaning context**, in its
own repo. The only centralized artifact is the **context map** — a thin
document naming the contexts, their owners, and the translations between
them ("what Billing calls an *account* is what Identity calls an
*organization*"). One central domain document for all systems is the
anti-pattern: it violates system self-containment and goes stale fastest,
because no team's ritual touches it. Rule of thumb: *the model lives with
the authority to change it; only the translations between authorities live
centrally.*

## Form: One File First, Then A Graduation Path

Do not prescribe a wiki by default. Structure should expand the way the
brief does — only when the domain demands it:

```text
one file with sections
-> one file per meaning context
-> concept-per-file bundle (the OKF experiment's form)
```

Split when a trigger fires, not before:

- two owners repeatedly edit-contend over one file
- diffs mix unrelated meaning changes (concept-level diffs were a measured
  strength of the bundle form)
- the file outgrows what a consumer should load whole

The trade both experiments measured: **the single file is token-efficient
and consistency-cheap; the bundle is navigation-cheap and
collaboration-cheap.** The triggers mark where the trade flips. At bundle
scale, two obligations activate: a small validation contract (the OKF
experiment showed distributed files drift without one — its validator
caught a superseded source with a still-confirmed dependent) and a root
index, which at multi-context scale grows into the context map.

For consumers, the efficient shape at every scale is the same: **a small
always-loaded index plus load-on-demand leaves.** The unit that matters is
not file count but *what must be loaded to answer a typical question* —
design shards so a typical task costs one index and one or two leaves.
Three independently evolved systems converge on this shape: agent memory
systems (index file plus one-fact-per-file), the private field test's docs
ladder (state map, then targeted retrieval by feature name), and the OKF
bundle (root index, layer indexes, concept pages).

A practical bonus: the sharded form — Markdown files, links, indexes — is
natively an Obsidian vault, and every stage of the graduation path renders
in the same ordinary tools. The human reading surface never breaks as the
model grows. The standing principle: authoritative Markdown, *generated* views
for humans, never parallel-maintained editions — an exported copy in
another tool instantly becomes a competing source of truth.

## Keeping It Alive: The Covenant

A model nobody must read is dead in a month, and a stale model is worse
than none — an agent will believe it. The covenant has two halves, and the
write half must ride an existing ritual rather than requiring a new habit:

- **Write path:** the model updates in the same commit as any change that
  alters a concept, rule, term, or authority line. If the team has a ship
  checklist, this is one added line on it.
- **Read path:** the model (or its relevant slice) is consulted at named
  moments — before writing user-facing copy (the language register),
  before touching prompts or agent instructions (rules and anchors),
  before changing schema (concepts and states), and during review of any
  of the above.

Review rides the existing pull-request ritual: a diff to the model is a
semantic migration and gets reviewed like one.

## Slices Before Slice Generation

The OKF experiment showed a derived slice can be validated but not yet
reliably generated. The field-tested intermediate pattern is available
now: **compiled slices with a drift doctrine.** A prompt, agent
instruction, or spec section is compiled by hand from the model, marked as
derived from it, and the team names divergence between model and compiled
slice as a correctness bug — a reviewable bug class, not a vague risk.
The private field test ran this pattern in production before the framework had
words for it: one shared prompt file fed two execution paths, with divergence
treated as a correctness bug.

## Adoption Paths

**An individual or solo builder**: retro-cast first —
gather the rules, terms, and refusals the project has already accumulated
into one file, following the Core Brief fields plus the declined ledger
and anchors. Then establish it as authoritative: commit it, add it to the
agent-instructions read-first list, add the covenant line to the ship ritual, and
*deduplicate* — the model becomes the home of doctrine and other docs link
to it, or the team has created a second source of truth.

**A team**: start from a completed brief; appoint the steward tier; wire
the covenant into the PR template; introduce provenance marks and the
declined ledger in the first month (they are the cheapest high-value
pieces); let structure graduate on triggers.

**Agents**: read the index always and slices on demand; obey provenance
marks (an `(assumed)` entry is a question, not a law); propose `(observed)`
updates through the normal change process; never lock, unlock, or retire.
An agent that consumes the model is also its best drift detector — checking
anchors is a mechanical task agents are suited to.

## Proposed Brief Edits (Phase-One Continuity)

Small v0.x changes to the current brief that fell out of the field test,
listed here until deliberately made:

1. Provenance marks as a line-level convention, with a one-line legend.
2. Declined-decision stems in field 1: `We considered and declined…
   because… It stays declined until…`
3. Builder-authority stems in the Actions/Authority fields: `Builder
   agents may… must not… "Done" means…`
4. An explicit note that the sentence stems are the questionnaire, not the
   document: stems elicit, headings structure, and stems should not
   survive into the maintained artifact.

## Open Questions

- Typed relationships: can they be declared once, machine-readably,
  without making concept pages unpleasant to author? (Carried from the
  OKF experiment; still the main structural weakness.)
- Slice generation: can a profile-aware tool regenerate a bounded slice
  deterministically from the model?
- Cold-team usability: every current evidence artifact was produced by
  authors saturated in their own context. Can a team that did not write
  the model navigate and correct it? (The retro-cast eval lane, run on
  products the evaluator did not build, is the cheapest probe.)
- Token economics at scale: measure what a typical task actually loads at
  each graduation stage, rather than asserting it.
- The context map: does it need its own minimal format, or is a table of
  contexts, owners, and translations enough?

---

*Drafted July 17, 2026 from public simulations and a private live-product
field test. Published as a Lab so use can confirm, change, or retire it.*