<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/context/glossary-conventions/">
  <id>https://docs.spec-kitty.ai/context/glossary-conventions/</id>
  <title>Glossary Conventions</title>
  <updated>2026-11-13T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/context/glossary-conventions/"/>
  <summary>Authoring conventions for Spec Kitty&apos;s living glossary — source-of-truth precedence, policy/runtime layering, term status lifecycle, per-term entry schema, and runtime anchors.</summary>
  <content type="html">&lt;span id=&quot;glossary-conventions&quot;&gt;&lt;/span&gt;
&lt;p&gt;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 (&lt;code dir=&quot;auto&quot;&gt;docs/context/*.md&lt;/code&gt;) and are indexed from
&lt;a href=&quot;/context/&quot;&gt;the Context landing page&lt;/a&gt;. This page carries the shared conventions
those context pages follow.&lt;/p&gt;
&lt;h2 id=&quot;source-of-truth&quot;&gt;Source of Truth&lt;/h2&gt;
&lt;p&gt;When terms conflict, use this order:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Accepted product planning docs (PDR/PRD/ADR)&lt;/li&gt;
&lt;li&gt;This glossary (policy language)&lt;/li&gt;
&lt;li&gt;Runtime contracts and event logs (operational behavior)&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;architecture-framing&quot;&gt;Architecture Framing&lt;/h2&gt;
&lt;p&gt;Spec Kitty uses two complementary layers:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Policy layer (glossary, specs, ADRs): defines language, intent, and invariants.&lt;/li&gt;
&lt;li&gt;Runtime layer (CLI/events/projections): executes behavior and records what happened.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Use policy docs to answer “what should this mean?” and runtime artifacts to answer “what did the system do?”&lt;/p&gt;
&lt;h2 id=&quot;domain-index&quot;&gt;Domain Index&lt;/h2&gt;
&lt;p&gt;The canonical index of glossary context domains and their files lives on the
&lt;a href=&quot;/context/&quot;&gt;Context landing page&lt;/a&gt;. A context slug is a filename (without
&lt;code dir=&quot;auto&quot;&gt;.md&lt;/code&gt;) under &lt;code dir=&quot;auto&quot;&gt;docs/context/&lt;/code&gt;; the Contextive generator extracts terms only from
a page with a &lt;code dir=&quot;auto&quot;&gt;## Context:&lt;/code&gt; heading. See
&lt;a href=&quot;/context/contextive-glossaries/&quot;&gt;Contextive Glossary Integration&lt;/a&gt; for how those slugs
generate the IDE hover glossaries.&lt;/p&gt;
&lt;h2 id=&quot;status-lifecycle&quot;&gt;Status Lifecycle&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;candidate&lt;/code&gt; -&gt; &lt;code dir=&quot;auto&quot;&gt;canonical&lt;/code&gt; -&gt; &lt;code dir=&quot;auto&quot;&gt;deprecated&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;superseded&lt;/code&gt;&lt;/p&gt;
&lt;h2 id=&quot;term-entry-schema&quot;&gt;Term Entry Schema&lt;/h2&gt;
&lt;p&gt;Each glossary term table carries these required rows:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;Definition&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;Context&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;Status&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;Applicable to&lt;/code&gt; (version scope, for example &lt;code dir=&quot;auto&quot;&gt;`1.x`, `2.x`&lt;/code&gt;)&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Entries may also carry optional rows, used where they add clarity:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;Do NOT use when&lt;/code&gt; — disambiguation guards that steer a reader to the correct neighboring term when a word is overloaded&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;Related terms&lt;/code&gt; — in-page or cross-page links to neighboring terms&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;Note&lt;/code&gt; — any additional context&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;Canonical term&lt;/code&gt; — present when the heading is a legacy alias and a different word is canonical for the sense&lt;/li&gt;
&lt;li&gt;term-specific rows such as &lt;code dir=&quot;auto&quot;&gt;Scoping rule&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;Materialization trigger&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;Placement when materialized&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;runtime-anchors&quot;&gt;Runtime Anchors&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/glossary/&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/charter/offering/missions/glossary_hook.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/charter/offering/missions/primitives.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/glossary.py&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;pdr-alignment-notes&quot;&gt;PDR Alignment Notes&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Scoped glossary model: &lt;code dir=&quot;auto&quot;&gt;spec_kitty_core&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;team_domain&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;audience_domain&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;mission_local&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Strictness modes: &lt;code dir=&quot;auto&quot;&gt;off&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;medium&lt;/code&gt; (global default), &lt;code dir=&quot;auto&quot;&gt;max&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Generation block policy: &lt;code dir=&quot;auto&quot;&gt;medium&lt;/code&gt; blocks only unresolved high-severity semantic conflicts, &lt;code dir=&quot;auto&quot;&gt;max&lt;/code&gt; blocks any unresolved conflict, &lt;code dir=&quot;auto&quot;&gt;off&lt;/code&gt; never blocks (&lt;code dir=&quot;auto&quot;&gt;src/glossary/strictness.py&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;History model: append-only glossary evolution events, replayable from canonical logs&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
