<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/2.x/2026-02-23-2-living-glossary-context-and-curation-model/">
  <id>https://docs.spec-kitty.ai/adr/2.x/2026-02-23-2-living-glossary-context-and-curation-model/</id>
  <title>Living Glossary Context and Curation Model</title>
  <updated>2026-02-23T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/2.x/2026-02-23-2-living-glossary-context-and-curation-model/"/>
  <summary>Puts term ownership in domain contexts, curation rules in doctrine, and enforcement in a runtime hook, so terminology drift is caught while the work happens.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Glossary behavior in 2.x now spans three layers:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Domain context definitions under &lt;code dir=&quot;auto&quot;&gt;glossary/contexts/&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Curation tactics/styleguides in doctrine (including HiC terminology and candidate promotion rules).&lt;/li&gt;
&lt;li&gt;Runtime execution hook integration (&lt;code dir=&quot;auto&quot;&gt;execute_with_glossary&lt;/code&gt;) for mission primitives.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;This architecture existed in code and tests but lacked a dedicated ADR describing the model and invariants.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;Preserve consistent domain semantics across AI-assisted workflows.&lt;/li&gt;
&lt;li&gt;Keep glossary scope composable by domain context.&lt;/li&gt;
&lt;li&gt;Tie curation quality to explicit doctrine artifacts.&lt;/li&gt;
&lt;li&gt;Make glossary checks opt-in by metadata but enabled-by-default for safety.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;Keep a single monolithic glossary document with no context partitioning.&lt;/li&gt;
&lt;li&gt;Adopt context-owned living glossary with doctrine-guided curation and runtime hook integration (chosen).&lt;/li&gt;
&lt;li&gt;Defer glossary governance to external, non-repository tooling.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option:&lt;/strong&gt; Adopt context-owned living glossary with doctrine-guided curation and runtime hook integration.&lt;/p&gt;
&lt;h3 id=&quot;decision-details&quot;&gt;Decision Details&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;Glossary terms are organized by bounded context files under &lt;code dir=&quot;auto&quot;&gt;glossary/contexts/&lt;/code&gt; (for example &lt;code dir=&quot;auto&quot;&gt;dossier&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;lexical&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;system-events&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;technology-foundations&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;New terminology enters as &lt;code dir=&quot;auto&quot;&gt;candidate&lt;/code&gt;; promotion authority remains with the Human-in-Charge.&lt;/li&gt;
&lt;li&gt;Curation process is codified as a doctrine tactic plus writing styleguide (&lt;code dir=&quot;auto&quot;&gt;glossary-curation-interview&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;kitty-glossary-writing&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;Mission primitive execution can pass through glossary middleware via &lt;code dir=&quot;auto&quot;&gt;execute_with_glossary&lt;/code&gt;; metadata/config determine enablement and strictness.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ol&gt;
&lt;li&gt;Terminology governance is explicit, context-scoped, and testable.&lt;/li&gt;
&lt;li&gt;Definition quality is reinforced by reusable doctrine artifacts.&lt;/li&gt;
&lt;li&gt;Runtime checks align generated outputs with glossary semantics.&lt;/li&gt;
&lt;/ol&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ol&gt;
&lt;li&gt;More governance files to maintain when terminology evolves.&lt;/li&gt;
&lt;li&gt;Cross-context linking introduces additional link-integrity risk without tests.&lt;/li&gt;
&lt;/ol&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ol&gt;
&lt;li&gt;Existing mission execution contracts remain intact, with glossary checks layered on top.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h2&gt;
&lt;p&gt;This decision is validated when:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Glossary context links and anchors resolve.&lt;/li&gt;
&lt;li&gt;Doctrine curation artifacts validate and resolve references.&lt;/li&gt;
&lt;li&gt;Primitive glossary hook behavior honors metadata/config precedence.&lt;/li&gt;
&lt;li&gt;New context additions can be introduced without breaking existing references.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;p&gt;Implementation references:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;glossary/README.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;glossary/contexts/*.md&lt;/code&gt;&lt;/li&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;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/doctrine/missions/glossary_hook.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/doctrine/missions/primitives.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/missions/glossary_hook.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/doctrine/missions/test_glossary_hook.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/doctrine/missions/test_primitives.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/doctrine/test_glossary_link_integrity.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/doctrine/test_tactic_compliance.py&lt;/code&gt;&lt;/li&gt;
&lt;/ol&gt;</content>
</entry>
