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

status: PROPOSED
task IDs: (none assigned)
source request: 2026-08-13 owner: "create a full spec and plan for all of your recommendations, do not continue to execution yet" — deliverable is documents only; launch is explicit owner-gated.

## Goal

Create the repo-root CONTEXT.md (domain glossary, agent-facing, one-line-per-term) and docs/adr/ with exactly three records: ADR-0001 (shared contracts package — decision from 2026-08-13-arch-shared-contracts-design.md D1/D2/D8), ADR-0008 (glossary in a single root file), ADR-0009 (ADR template). Owner decision: docs only for now — plan registered PROPOSED, not launched.

## Source design

Normative: docs/specs/2026-08-13-arch-domain-glossary-design.md (D1-D6, §3, §4, §6, §8). This plan adds execution order and file pins only; it MUST NOT contradict the spec.

## Context

- No repo-root CONTEXT.md today; modules/systray/CONTEXT.md is the only module-local one (verified at origin/main) — the root file MUST NOT duplicate it, links or one-lines it.
- ADR-0002..0007 files are created by their implementers when the related specs land (shared-contracts, module-deepenings) — NOT by this plan.

## Files

- NEW /CONTEXT.md (repo root, next to CLAUDE.md/AGENTS.md): audience line; architecture vocabulary (module, interface, implementation, depth, seam, adapter, leverage, locality, ≤2 lines each); process map (one line per module: collector, controller, web, systray, fleet, gptbridge, harness, spine, buildbox); domain glossary (alphabetical, definitions-first, examples last); link list to module-local CONTEXT.md files.
- NEW docs/adr/0001-shared-contracts-package.md, docs/adr/0008-repository-glossary.md, docs/adr/0009-adr-records.md per the fixed template (Status, Context, Decision, Consequences, Related).

## Contracts

Per spec §6:

- `test -f CONTEXT.md && grep -c "^audience:" CONTEXT.md` = 1.
- `grep -c "^## " CONTEXT.md` ≥ 2.
- Every module name in the process map exists on disk.
- 0001/0008/0009 files exist and contain the five template headers.
- No history/changelog sections in CONTEXT.md.

## Behavior

Documentation only; no runtime behavior changes. Acceptance is content-level: terms accurate, terse, linked to real modules.

## Out of scope

- Rewriting modules/systray/CONTEXT.md or any module-local doc.
- User-facing docs, README rewrites.
- Enforcing glossary in code (no lint rules).
- ADR files 0002-0007 (created by the other two plans' implementers).
- The already-landed candidates (C1, C2, C6, C14, C20).

## Acceptance criteria

Per spec §6, all of the above contract checks pass; no MISSING lines from the module-existence loop; no History/Changelog/"last updated" lines.

## Preserved WIP

- Worktree /home/user/Projects/overdeck/.worktrees/arch-deepening (branch wt/arch-deepening at 7158544cf = origin/main).
- Review report: /home/user/.cache/agent-tmp/architecture-review-20260813-102418.html (baseline note: 5 candidates already landed at origin/main; do not re-specify).
- docs/plans/INDEX.md registration rows for all three arch plans (PROPOSED).

## Constraints

- Delivery scope is documentation only until the owner lifts it: "do not continue to execution yet" (2026-08-13). MUST NOT launch.
- Terminology: only terms that exist in code or in this delivery's specs. No invented vocabulary.
- Agent-doc-authoring register: audience line first, terse, no prose narrative, normative keywords verbatim.

## Execution steps

1. (Owner gate) Owner approves → plan flips ACTIVE/IDLE with a named worker.
2. Write CONTEXT.md; run the contract checks (audience line, section count, module existence, no history).
3. Create docs/adr/ + the three ADR files; verify the five headers each.
4. Land via .claude/scripts/ship.sh; deploy via packaging/deploy-local.sh.
5. (Optional, owner-visible) Reference CONTEXT.md from AGENTS.md in a later change — out of this delivery's scope, do NOT edit AGENTS.md here.

## Current receipt

2026-08-13: Spec 2026-08-13-arch-domain-glossary-design.md written in worktree, externally reviewed (APPROVE-WITH-FIXES), fixes applied (ADR-0001 + ADR-0008 + ADR-0009 all created by THIS delivery; 0002-0007 by their implementers — contradiction between §3.2 and §8 resolved). Three plans registered PROPOSED in docs/plans/INDEX.md. Nothing created yet, nothing launched.

## Next executable action

Owner approval to launch; then execution step 2. Until then: none.