# Glossary Integration — Design Spec

**Date:** 2026-05-31
**Status:** Draft — awaiting user spec review
**Authors:** orchestrator + Claude

## Goal

Give consuming projects a single, canonical place that pins
nomenclature so terminology does not drift over time, and so that
LLM-driven work reuses the established term for a concept instead of
coining a fresh synonym each session. The glossary is **guidance,
not enforcement**: it becomes standing reading for every skill and
agent, but no tool scans artefacts for forbidden synonyms.

The plugin stays mechanics-only. This cycle adds:

1. an optional profile slot `paths.glossary`,
2. a convention doc that owns the glossary format and the write
   discipline,
3. standing-reading wiring so a set `paths.glossary` is read by
   every role automatically,
4. a boss write-rule (record reality, never invent),
5. a dogfooded `docs/glossary.md` in this repo proving the format
   on the plugin's own vocabulary.

## Architecture

The glossary rides the **existing standing-reading mechanism**
rather than introducing a new delivery path. One optional path slot
carries the whole feature:

- `paths.glossary` (optional). **If set, the file it points to is
  automatically standing reading for every agent** — no separate
  `standing_reading.always` entry is required. If unset, the whole
  feature is a documented no-op, exactly matching the plugin's
  existing "missing optional slot = silent skip" contract.

Semantics ("set ⇒ standing reading for all roles") live in
`docs/profile-schema.md` next to the slot, so the wiring is
single-sourced and a project cannot set the path yet forget to make
it read.

The format and the write discipline live in a new
`docs/glossary-convention.md`, following the established
`docs/`-doc pattern (`pipeline.md`, `profile-schema.md`). Skills and
`boss` cross-reference it rather than restating it.

## Concrete code shapes

### 1. The delivered `docs/glossary.md` (dogfood — primary artefact)

This is the actual file the feature produces, shown on the plugin's
own vocabulary. Per-term blocks (not a table) so boss-appended
entries produce clean line-wise diffs.

```markdown
# Glossary

Canonical nomenclature for this project. Use the **canonical term**;
never use a term under **Avoid**. If you need a concept that is not
listed here, reuse the closest existing term — do not silently coin
a new one. New entries are added only to record nomenclature already
in consistent use; see `docs/glossary-convention.md`.

---

### cycle
**Avoid:** release, epic, round, sprint
One round in the pipeline graph (design → plan → execute → review →
close). Not the top-level container — that is a *milestone*.

### milestone
**Avoid:** epic, phase, big-ticket
A tracker container spanning potentially many cycles; closes only
when its promised work is complete and functional. A cycle close is
never a milestone close.

### iteration
**Avoid:** sprint, story, step
The default sub-unit of a cycle; one pass through the inner loop. A
project may rename it via `vocabulary.subcycle`.

### drift
**Avoid:** divergence, rot, skew
Accumulated mismatch between the codebase and its design ledger.
Surfaced by the architect agent at audit, not by any synonym check.

### hard-gate
**Avoid:** checkpoint, barrier, blocker
A pipeline point that forbids downstream work until an artefact
exists and is approved (e.g. an approved spec before any plan).
```

### 2. The profile slot (worked author example)

What a consuming project writes — one line opts the whole project
in:

```yaml
# <project>/.claude/dev-cycle-profile.yml
paths:
  spec_dir: docs/specs
  plan_dir: docs/plans
  glossary: docs/glossary.md   # optional — if set, every agent reads
                               # it as standing reading
  code_roots: [src]
```

### 3. The boss write-rule (lives in `docs/glossary-convention.md`)

`boss/SKILL.md` carries only a cross-reference pointer; the rule
text itself is single-sourced here:

```markdown
## Extending the glossary (user + boss only)

The user may edit the glossary at any time. In a `/boss` session the
orchestrator may extend it autonomously — but only to **record
reality, never to invent**:

- A term already used consistently across shipped artefacts but not
  yet listed → add it, with its known synonyms under **Avoid**.
- A drift the orchestrator just resolved (two terms for one concept)
  → record the winner as the canonical entry, the loser under
  **Avoid**.

The orchestrator never coins a brand-new term into the glossary: a
term earns its entry by already being in consistent use. All other
skills and agents are read-only consumers of the glossary.
```

### Implementation shape (secondary — before → after)

**`templates/project-profile.yml`**, `paths:` block:

```yaml
# before
paths:
  spec_dir: docs/specs
  plan_dir: docs/plans
  # design_ledger: design/INDEX.md       # optional
  code_roots: [src]

# after
paths:
  spec_dir: docs/specs
  plan_dir: docs/plans
  # glossary: docs/glossary.md           # optional — if set, read as
                                         # standing reading by every role
  # design_ledger: design/INDEX.md       # optional
  code_roots: [src]
```

**`docs/profile-schema.md`**, `paths` section: add a `glossary`
entry documenting the slot AND the "set ⇒ standing reading for all
roles" semantics, and a no-op-when-unset note.

**`docs/agent-template.md`** and **`docs/pipeline.md`**: where
standing reading is described, add one sentence: a set
`paths.glossary` is part of every role's standing reading.

**`boss/SKILL.md`**: add a short pointer (in the process/loop and a
cross-reference entry) to `docs/glossary-convention.md` for the
record-reality write-rule. No rule text duplicated.

## Components

- **`docs/glossary.md`** (new) — dogfooded glossary for the plugin's
  own vocabulary; the lived proof of the format.
- **`docs/glossary-convention.md`** (new) — single source for the
  format (three fields: canonical term, Avoid synonyms, ≤2-sentence
  definition), the standing-reading obligation, and the boss
  record-reality write-rule.
- **`paths.glossary` slot** — in `templates/project-profile.yml`
  (commented) and `docs/profile-schema.md` (documented).
- **Standing-reading wiring** — one sentence each in
  `docs/agent-template.md` and `docs/pipeline.md`.
- **`boss/SKILL.md`** — cross-reference pointer to the convention.

## Data flow

Author/consume:

1. A project sets `paths.glossary: docs/glossary.md` and writes the
   file using the convention's three-field block format.
2. Every dispatched skill/agent, per the standing-reading contract,
   reads the glossary alongside `CLAUDE.md` and the git-log entries.
3. When producing prose or naming a concept, the role uses the
   canonical term and avoids the listed synonyms.

Extend (boss):

1. In `/boss`, when the orchestrator observes a term already in
   consistent use but unlisted, or has just resolved a two-term
   drift, it appends/edits one block per the convention.
2. The edit is an ordinary working-tree change committed under the
   only-orchestrator-commits rule; no separate gate.

Unset:

- No `paths.glossary` ⇒ standing reading omits it, the convention
  doc is inert reference, boss has nothing to extend. Documented
  no-op.

## Error handling

- **Slot set but file missing:** a role that cannot read the
  glossary treats it as it treats any missing standing-reading
  source — notes the gap, proceeds; this is a profile error for the
  project to fix, not a plugin failure.
- **Boss tempted to invent:** guarded by the convention's
  red-flag/rationalisation framing ("a term earns its entry by
  already being in use"); mirrors the existing boss anti-invention
  discipline.
- **Convention vs. glossary drift:** the convention owns format and
  rule; `docs/glossary.md` is an instance. The dogfood file is
  expected to conform and serves as the conformance example.

## Testing strategy

This is a docs/profile cycle with no executable surface; the plugin
has no test runner (`commands.test` is empty for this repo). The
acceptance evidence is therefore the concrete artefacts above plus
two manual conformance checks:

1. **Dogfood conformance:** every block in `docs/glossary.md` has
   exactly the three fields the convention mandates (canonical term
   heading, **Avoid:** line, ≤2-sentence definition).
2. **No-op proof:** the wording added to `profile-schema.md`,
   `agent-template.md`, and `pipeline.md` states the unset-slot case
   so a profile without `glossary` provably skips the feature.

No fenced block in this spec targets a configured `spec_validation`
parser (this repo declares none); the parse-every-block gate is a
documented no-op here.

## Acceptance criteria

- `paths.glossary` documented in `docs/profile-schema.md` (slot +
  "set ⇒ standing reading" semantics + unset no-op) and present
  commented in `templates/project-profile.yml`.
- `docs/glossary-convention.md` exists and owns: the three-field
  format, the standing-reading obligation, and the boss
  record-reality write-rule (with the never-invent guard).
- `docs/agent-template.md` and `docs/pipeline.md` each state that a
  set `paths.glossary` is standing reading for every role.
- `boss/SKILL.md` cross-references the convention for the write-rule
  without duplicating its text.
- `docs/glossary.md` exists, dogfoods the plugin vocabulary, and
  every entry conforms to the three-field format.
- With no `paths.glossary` set, the feature is a provable no-op.