<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/changelog/2x/glossary-system/">
  <id>https://docs.spec-kitty.ai/changelog/2x/glossary-system/</id>
  <title>2.x Glossary System</title>
  <updated>2026-06-03T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/changelog/2x/glossary-system/"/>
  <summary>Historical Spec Kitty 2.x archive page for 2.x Glossary System; use Spec Kitty 3.2 docs for current Charter-era workflows.</summary>
  <content type="html">&lt;blockquote&gt;
&lt;p&gt;Archive notice: This page documents historical Spec Kitty behavior and is not the current 3.2 workflow. Start with &lt;a href=&quot;/context/&quot;&gt;Spec Kitty 3.2&lt;/a&gt; for current docs.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;span id=&quot;2x-glossary-system&quot;&gt;&lt;/span&gt;
&lt;p&gt;The glossary keeps terminology consistent across all mission artifacts. Every term that matters to your project — from framework concepts like “lane” and “work package” to domain-specific jargon like “deployment” — lives in the glossary with a precise definition, a scope, and a status. When the runtime detects a term used inconsistently in an artifact, it can flag or block generation until you resolve the inconsistency.&lt;/p&gt;
&lt;p&gt;In 2.x the glossary is a living system: terms are added, curated, promoted, and deprecated over the lifecycle of a project. The system is designed so that agents and humans share the same vocabulary.&lt;/p&gt;
&lt;h2 id=&quot;glossary-structure&quot;&gt;Glossary Structure&lt;/h2&gt;
&lt;p&gt;2.x glossary content is organized by context domain:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;glossary/README.md&lt;/code&gt; — overview and conventions&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;docs/context/*.md&lt;/code&gt; — domain-specific term files&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Current domains include execution, orchestration, governance, identity, doctrine, dossier, lexical, system-events, and technology-foundations.&lt;/p&gt;
&lt;h2 id=&quot;the-4-scopes&quot;&gt;The 4 Scopes&lt;/h2&gt;
&lt;p&gt;Terms are organized into four scopes. When the same surface form exists in multiple scopes, the narrowest scope wins:&lt;/p&gt;






























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th align=&quot;center&quot;&gt;Precedence&lt;/th&gt;&lt;th&gt;Scope&lt;/th&gt;&lt;th&gt;Use For&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td align=&quot;center&quot;&gt;0 (highest)&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;mission_local&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Feature-specific jargon (e.g., “widget” = a specific UI component in this feature)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td align=&quot;center&quot;&gt;1&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;team_domain&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Team or organization conventions (e.g., “sprint” = a 2-week iteration)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td align=&quot;center&quot;&gt;2&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;audience_domain&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Industry or domain standards (e.g., “deployment” in DevOps)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td align=&quot;center&quot;&gt;3 (lowest)&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;spec_kitty_core&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Framework terms like “lane”, “work package”, “mission”&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;If &lt;code dir=&quot;auto&quot;&gt;deployment&lt;/code&gt; is defined in both &lt;code dir=&quot;auto&quot;&gt;team_domain&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;audience_domain&lt;/code&gt;, the &lt;code dir=&quot;auto&quot;&gt;team_domain&lt;/code&gt; definition takes precedence during conflict resolution.&lt;/p&gt;
&lt;h2 id=&quot;term-lifecycle&quot;&gt;Term Lifecycle&lt;/h2&gt;
&lt;p&gt;Every term follows a three-state lifecycle:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;plaintext&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;draft  --&gt;  active  --&gt;  deprecated&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;^                          |&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;+--------------------------+&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;         &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;(re-draft)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;draft&lt;/strong&gt; — newly added or auto-extracted, not yet reviewed by a human&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;active&lt;/strong&gt; — promoted by a human, used in conflict resolution&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;deprecated&lt;/strong&gt; — retired from active resolution but preserved in event history&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;New terms are added as &lt;code dir=&quot;auto&quot;&gt;draft&lt;/code&gt;. Promotion to &lt;code dir=&quot;auto&quot;&gt;active&lt;/code&gt; is controlled by Human-in-Charge governance. Deprecated terms are excluded from conflict resolution but remain in the glossary for audit purposes.&lt;/p&gt;
&lt;h2 id=&quot;strictness-modes&quot;&gt;Strictness Modes&lt;/h2&gt;
&lt;p&gt;The glossary runtime supports three enforcement levels:&lt;/p&gt;





















&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Mode&lt;/th&gt;&lt;th&gt;Behavior&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;off&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Glossary checks are disabled entirely&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;medium&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Only HIGH severity conflicts block generation&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;max&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Any unresolved conflict blocks generation&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;Strictness is configured per-project in &lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt; or via the charter interview. The default is &lt;code dir=&quot;auto&quot;&gt;medium&lt;/code&gt;.&lt;/p&gt;
&lt;h2 id=&quot;conflict-resolution&quot;&gt;Conflict Resolution&lt;/h2&gt;
&lt;p&gt;When the same surface form is defined differently in two scopes, or when an artifact uses a term inconsistently with the glossary, the system records a &lt;strong&gt;conflict&lt;/strong&gt;. Conflicts have an ID, a description of the inconsistency, and a resolution status.&lt;/p&gt;
&lt;p&gt;Resolving a conflict is a human decision: you choose which definition wins, or you update the artifact to match the glossary. Once resolved, the conflict is closed and excluded from future checks.&lt;/p&gt;
&lt;h2 id=&quot;cli-commands&quot;&gt;CLI Commands&lt;/h2&gt;





































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Command&lt;/th&gt;&lt;th&gt;Purpose&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty glossary list&lt;/code&gt;&lt;/td&gt;&lt;td&gt;List all terms across all scopes&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty glossary list --scope &amp;#x3C;scope&gt;&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Filter terms by scope&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty glossary list --status &amp;#x3C;status&gt;&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Filter terms by status (draft, active, deprecated)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty glossary list --json&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Machine-readable JSON output&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty glossary conflicts&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Show all conflict history&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty glossary conflicts --unresolved&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Show only unresolved conflicts&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty glossary resolve &amp;#x3C;conflict-id&gt;&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Resolve a conflict interactively&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h2 id=&quot;runtime-integration&quot;&gt;Runtime Integration&lt;/h2&gt;
&lt;p&gt;Glossary checks are integrated into mission primitive execution via:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/doctrine/missions/glossary_hook.py&lt;/code&gt; — hook that runs during artifact generation&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/doctrine/missions/primitives.py&lt;/code&gt; — primitive execution with glossary context&lt;/li&gt;
&lt;li&gt;Compatibility import path: &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/missions/glossary_hook.py&lt;/code&gt;&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Hook behavior is metadata/config driven with enabled-by-default semantics.&lt;/p&gt;
&lt;p&gt;Doctrine artifacts for glossary curation:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/doctrine/tactics/glossary-curation-interview.tactic.yaml&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/doctrine/styleguides/writing/kitty-glossary-writing.styleguide.yaml&lt;/code&gt;&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;validation-coverage&quot;&gt;Validation Coverage&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;Link/anchor integrity for context docs: &lt;code dir=&quot;auto&quot;&gt;tests/doctrine/test_glossary_link_integrity.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Glossary hook behavior: &lt;code dir=&quot;auto&quot;&gt;tests/doctrine/missions/test_glossary_hook.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Primitive context strictness/enablement behavior: &lt;code dir=&quot;auto&quot;&gt;tests/doctrine/missions/test_primitives.py&lt;/code&gt;&lt;/li&gt;
&lt;/ol&gt;
&lt;hr&gt;
&lt;h2 id=&quot;learn-more&quot;&gt;Learn More&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Step-by-step management&lt;/strong&gt;: &lt;a href=&quot;/guides/how-to/governance/manage-glossary/&quot;&gt;How to Manage the Glossary&lt;/a&gt; — listing terms, resolving conflicts, editing seed files, configuring strictness&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Spec-driven development&lt;/strong&gt;: &lt;a href=&quot;/architecture/spec-driven-development/&quot;&gt;Spec-Driven Development Explained&lt;/a&gt; — how the glossary fits into the broader specification workflow&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;CLI reference&lt;/strong&gt;: &lt;a href=&quot;/api/cli-commands/&quot;&gt;CLI Commands Reference&lt;/a&gt; — complete &lt;code dir=&quot;auto&quot;&gt;glossary&lt;/code&gt; subcommand details&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
