# Domain glossary — repo-root CONTEXT.md and architecture decision records

audience: AI coding agents first.

- Status: Draft
- Source: architecture-review-20260813-102418.html candidate C7; the review found no repo-root CONTEXT.md and no docs/adr/ — every agent session must rediscover the domain by reading code.
- Scope: CONTEXT.md at repo root, docs/adr/
- Delivery scope: ends after reviewed design + implementation plan documents are written. MUST NOT launch, MUST NOT implement (owner instruction 2026-08-13: "do not continue to execution yet")
- Last updated: 2026-08-13

## 1. Outcome

- Repo-root CONTEXT.md exists: the domain glossary for overdeck. One file, terse, agent-facing first.
- docs/adr/ exists with the first decision record: ADR-0001 (shared contracts package, decided by 2026-08-13-arch-shared-contracts-design.md D1/D2/D8).
- An agent that reads CONTEXT.md can name the domain correctly: module, interface, depth, seam, adapter, leverage, locality — plus the overdeck vocabulary (collector, controller, systray, fleet, seat, wrapper, harness, factory, gate, buildbox, kanboard, incident, dispatch, mutation store, status projection, brief, resolution, offload, admission).

## 2. Decisions

- D1: Single repo-root CONTEXT.md. modules/systray/CONTEXT.md already exists as the module-local precedent — root file MUST NOT duplicate module content; it links or summarizes in one line per module.
- D2: Vocabulary definitions are terse (≤2 lines each), alphabetical, definitions-first, examples last. Audience line first: "audience: AI coding agents first." — same register as every agent-facing doc in this repo (see AGENTS.md, CLAUDE.md symlink).
- D3: CONTEXT.md is a glossary and module map, NOT a changelog, NOT a narrative. MUST NOT contain history sections, "last updated by" logs, or prose paragraphs longer than 3 lines.
- D4: docs/adr/ holds architecture decision records only — decisions with consequences and alternatives considered. MUST NOT hold implementation notes or task lists (those belong in docs/plans/).
- D5: ADR template: Status, Context, Decision, Consequences, Related. First ADR is 0001-shared-contracts-package.md recording the shared-contracts spec's D1/D2/D8 (package pattern, dependence direction, no-zod rule).
- D6: Doc structure (owner decision 2026-08-13): glossary is one of three specs — shared-contracts, module-deepenings, domain-glossary. This spec is the smallest and can land last; it merely records what the other two decided.

## 3. Architecture

### 3.1 CONTEXT.md — location and shape

- Path: /CONTEXT.md (repo root, next to CLAUDE.md/AGENTS.md).
- Sections: (1) audience line; (2) architecture vocabulary — module, interface, implementation, depth (deep/shallow), seam, adapter, leverage, locality — each defined in the review's sense, e.g. "seam — the one place where a process boundary is crossed"; (3) process map — one line each: collector (incidents, actions, activity), controller (leases, transitions, admission), web (deck-ui, design system), systray (router, indicator), fleet (engine, transports), gptbridge (seats, conversations), harness (factory), spine, buildbox; (4) domain glossary — alphabetical overdeck terms with one-line definitions; (5) link list to module-local CONTEXT.md (modules/systray/CONTEXT.md today; add as they appear).
- MUST NOT invent terms: only terms that exist in code or in the specs of this delivery.

### 3.2 docs/adr/ — shape

- Path: docs/adr/0001-shared-contracts-package.md.
- Content: the decision "overdeck keeps wire contracts in a workspace package (@overdeck/incident-contract, pattern of @overdeck/activity-contract)"; Context = the three mirrors and their resync cost (web incident-types.ts 113 lines with the "Mirrored rather than imported" comment; provider.ts Parameters<> gymnastics; controller verb list drift — delivery-feature-reconcile already diverged); Decision = D1/D2/D8 of the shared-contracts spec; Consequences = one source of truth, build coupling confined to a private package; Related = 2026-08-13-arch-shared-contracts-design.md.
- Future ADRs: ADR-0002 (single dispatch state vocabulary), ADR-0003 (offload verbs single-sourced), ADR-0004..0007 (module-deepenings decisions) — files are created by their implementers when the related spec lands. THIS delivery creates the directory and exactly three ADR files: ADR-0001 (shared-contracts D1/D2/D8) and ADR-0008 + ADR-0009 (this spec's own decisions, below).

## 4. Behavior

- No runtime behavior changes: CONTEXT.md and docs/adr/ are documentation only.
- Acceptance is content-level: terms are accurate, terse, and link to real modules.

## 5. Error handling

- None: documentation delivery. The only failure mode is content drift — mitigated by D3 (no history sections) and by the glossary being referenced from AGENTS.md once the owner approves.

## 6. Testing

- `test -f CONTEXT.md && grep -c "^audience:" CONTEXT.md` = 1.
- `grep -c "^## " CONTEXT.md` ≥ 2 (vocabulary + domain glossary sections).
- Every module name in the process map exists: `grep -oE "modules/[a-z-]+" CONTEXT.md | sort -u | while read m; do test -d "$m" || echo "MISSING $m"; done` = empty.
- `test -f docs/adr/0001-shared-contracts-package.md` and it contains Status, Context, Decision, Consequences, Related headers.
- No history sections: `grep -nE "History|Changelog|last updated" CONTEXT.md` = empty.

## 7. Out of scope

- Rewriting modules/systray/CONTEXT.md or any module-local doc.
- User-facing documentation, README rewrites.
- Enforcing the glossary in code (no lint rules in this delivery).
- The five already-landed candidates (C1, C2, C6, C14, C20) — document, never re-specify.

## 8. Architecture Decisions

- ADR-0008: repository glossary lives in a single root CONTEXT.md, module-local docs remain supplements (D1).
- ADR-0009: architecture decisions live in docs/adr/ with a fixed template (D4, D5).