Glossary Conventions
Who is this for (2)
- Stakeholder Persona: System Architect — Read this to know which source wins when terms conflict and which rows a glossary entry must carry.
- Stakeholder Persona: Lead Developer — Read this before adding or changing a term entry under docs/context/, so the entry follows the shared schema.
Canonical authoring conventions for Spec Kitty’s living glossary. The glossary
is a living artifact organized by context domain; the per-domain term
definitions live in this directory (docs/context/*.md) and are indexed from
the Context landing page. This page carries the shared conventions
those context pages follow.
Source of Truth
When terms conflict, use this order:
- Accepted product planning docs (PDR/PRD/ADR)
- This glossary (policy language)
- Runtime contracts and event logs (operational behavior)
Architecture Framing
Spec Kitty uses two complementary layers:
- Policy layer (glossary, specs, ADRs): defines language, intent, and invariants.
- Runtime layer (CLI/events/projections): executes behavior and records what happened.
Use policy docs to answer “what should this mean?” and runtime artifacts to answer “what did the system do?”
Domain Index
The canonical index of glossary context domains and their files lives on the
Context landing page. A context slug is a filename (without
.md) under docs/context/; the Contextive generator extracts terms only from
a page with a ## Context: heading. See
Contextive Glossary Integration for how those slugs
generate the IDE hover glossaries.
Status Lifecycle
candidate -> canonical -> deprecated / superseded
Term Entry Schema
Each glossary term table carries these required rows:
DefinitionContextStatusApplicable to(version scope, for example`1.x`, `2.x`)
Entries may also carry optional rows, used where they add clarity:
Do NOT use when— disambiguation guards that steer a reader to the correct neighboring term when a word is overloadedRelated terms— in-page or cross-page links to neighboring termsNote— any additional contextCanonical term— present when the heading is a legacy alias and a different word is canonical for the sense- term-specific rows such as
Scoping rule,Materialization triggerandPlacement when materialized
Runtime Anchors
src/glossary/src/charter/offering/missions/glossary_hook.pysrc/charter/offering/missions/primitives.pysrc/specify_cli/cli/commands/glossary.py
PDR Alignment Notes
- Scoped glossary model:
spec_kitty_core,team_domain,audience_domain,mission_local - Strictness modes:
off,medium(global default),max - Generation block policy:
mediumblocks only unresolved high-severity semantic conflicts,maxblocks any unresolved conflict,offnever blocks (src/glossary/strictness.py) - History model: append-only glossary evolution events, replayable from canonical logs