Files

T

Brummel 59c2f4bb6b audit(glossary): close cycle — glossary is SoT for nomenclature

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>

2026-05-31 14:46:14 +02:00

2.6 KiB

Raw Blame History

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:

a level-3 heading naming the canonical term to use;
an Avoid: line listing known synonyms that must NOT be used;
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.

2.6 KiB Raw Blame History