Brummel
59c2f4bb6b
Cycle-close tidy for the glossary-integration cycle (fc0e1d0..HEAD). Architect drift review (sole gate — repo ships no .claude/dev-cycle-profile.yml, so commands.regression is empty and the regression step is a documented no-op): - [medium] FIXED. docs/glossary.md Avoid-lists `release`/`epic` while profile-schema.md § vocabulary offered the same words as example slot renamings — opposite verdicts on the same words in two in-repo docs, with neither stating its scope, reading as contradiction. Resolution (per the user's steer: the glossary is the new source of truth for nomenclature): state that authority once, where the glossary's role is owned. glossary-convention.md now declares the set glossary the SoT for a project's nomenclature and that its canonical entry + Avoid list win over any colliding vocabulary example; profile-schema.md's vocabulary note defers to it with a pointer rather than restating the rule, keeping the single-sourcing the architect flagged as clean. The glossary itself is unchanged — it is the SoT and was already correct. - [low] CARRY-ON. glossary-convention.md mandates an `**Avoid:** —` line for synonym-free terms, but no dogfood entry in glossary.md exercises that arm (all five terms have real synonyms). Accepted as low-severity documented debt: the rule is unambiguous prose, and coining a synonym-free term solely to exercise a formatting arm would be gold-plating. Revisit if a genuinely synonym-free canonical term enters the dogfood. What holds: wiring semantics single-sourced at the paths.glossary row; convention/instance split clean; boss named as the only autonomous glossary writer; all six spec acceptance criteria landed. Cycle is drift-clean. Not a milestone close (no milestone fieldtest run; see docs/pipeline.md § Milestone-close gate). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
67 lines
2.6 KiB
Markdown
67 lines
2.6 KiB
Markdown
# Glossary convention
|
|
|
|
A project's glossary pins canonical 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. This file owns the format, the reading obligation, and the
|
|
write discipline; an individual project's glossary is an instance of
|
|
this convention.
|
|
|
|
## Where it lives
|
|
|
|
A project opts in by setting `paths.glossary` in its
|
|
`.claude/dev-cycle-profile.yml` (see `profile-schema.md` § `paths`).
|
|
When the slot is set, the file it names is standing reading for every
|
|
role — no separate `standing_reading.always` entry is required. When
|
|
the slot is unset, the whole feature is a documented no-op.
|
|
|
|
A set glossary is the source of truth for the project's nomenclature.
|
|
Where any other document names a concept differently — including the
|
|
example renamings in `profile-schema.md` § `vocabulary` — the
|
|
glossary's canonical entry, and its **Avoid** list, win. A
|
|
`vocabulary.*` slot only sets which term the glossary then pins as
|
|
canonical; it does not override the glossary.
|
|
|
|
## Format
|
|
|
|
The glossary is a flat list of per-term blocks (not a table), so an
|
|
appended entry produces a clean line-wise diff. Each block has exactly
|
|
three fields:
|
|
|
|
1. a level-3 heading naming the **canonical term** to use;
|
|
2. an **Avoid:** line listing known synonyms that must NOT be used;
|
|
3. a definition of at most two sentences.
|
|
|
|
```
|
|
### canonical-term
|
|
**Avoid:** synonym-one, synonym-two
|
|
A definition of at most two sentences.
|
|
```
|
|
|
|
A term with no known synonyms still carries an `**Avoid:** —` line so
|
|
every block has the same three-field shape.
|
|
|
|
## Reading obligation
|
|
|
|
Every skill and agent reads the glossary as part of its standing
|
|
reading and, when producing prose or naming a concept, uses the
|
|
canonical term and avoids the listed synonyms. If a concept is not
|
|
listed, reuse the closest existing term — do not silently coin a new
|
|
one.
|
|
|
|
## 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.
|