<?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-03-25-1-glossary-type-ownership/">
  <id>https://docs.spec-kitty.ai/adr/2.x/2026-03-25-1-glossary-type-ownership/</id>
  <title>ADR: Glossary Primitive Type Ownership and the Kernel Package</title>
  <updated>2026-03-25T00: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-03-25-1-glossary-type-ownership/"/>
  <summary>Relocates stdlib-only glossary value types into the kernel package so doctrine stops importing from specify_cli and the container dependency direction holds.</summary>
  <content type="html">&lt;h2 id=&quot;context&quot;&gt;Context&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;src/doctrine/missions/primitives.py&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;src/doctrine/missions/glossary_hook.py&lt;/code&gt; imported
types from &lt;code dir=&quot;auto&quot;&gt;specify_cli.glossary.*&lt;/code&gt; at module level, violating the stated architectural rule
that &lt;code dir=&quot;auto&quot;&gt;doctrine&lt;/code&gt; has no dependency on &lt;code dir=&quot;auto&quot;&gt;specify_cli&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;The types involved were pure value objects with no external dependencies:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;Strictness&lt;/code&gt; — enforcement level enum&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;ExtractedTerm&lt;/code&gt; — term extracted from input text&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;SemanticConflict&lt;/code&gt; + nested types (&lt;code dir=&quot;auto&quot;&gt;TermSurface&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;ConflictType&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;Severity&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;SenseRef&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;ScopeRef&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;GlossaryScope&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;These were defined in &lt;code dir=&quot;auto&quot;&gt;specify_cli.glossary.*&lt;/code&gt; for historical reasons, but their nature
(stdlib-only, zero external dependencies) makes them candidates for the lowest layer.&lt;/p&gt;
&lt;p&gt;A &lt;code dir=&quot;auto&quot;&gt;src/kernel/&lt;/code&gt; package had already been introduced to hold &lt;code dir=&quot;auto&quot;&gt;atomic.py&lt;/code&gt; — a write utility
shared by all three higher-level packages. Its declared contract is:&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;kernel  &amp;#x3C;-  doctrine&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 style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;kernel  &amp;#x3C;-  charter&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 style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;kernel  &amp;#x3C;-  specify_cli&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;hr&gt;
&lt;h2 id=&quot;options-considered&quot;&gt;Options Considered&lt;/h2&gt;

























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Option&lt;/th&gt;&lt;th&gt;Location&lt;/th&gt;&lt;th&gt;Verdict&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;A&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/doctrine/shared/glossary_types.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Doctrine becomes the owner; specify_cli imports from doctrine. Establishes the right direction but places glossary contracts in a domain-specific package.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;B&lt;/td&gt;&lt;td&gt;Accept the dependency; add specify_cli to doctrine/pyproject.toml&lt;/td&gt;&lt;td&gt;Abandons the standalone-doctrine goal. Rejected.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;C&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/kernel/glossary_types.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Zero-dependency types belong in the zero-dependency layer. All three higher packages import from kernel.&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;hr&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Option C: move to &lt;code dir=&quot;auto&quot;&gt;src/kernel/glossary_types.py&lt;/code&gt;.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;The types are stdlib-only value objects with no domain-specific behavior. They are not
“doctrine primitives” — they are shared primitive types used by the glossary subsystem across
all containers. The kernel is the designated home for exactly this category of artifact.&lt;/p&gt;
&lt;p&gt;For &lt;code dir=&quot;auto&quot;&gt;glossary_hook.py&lt;/code&gt;: &lt;code dir=&quot;auto&quot;&gt;GlossaryAwarePrimitiveRunner&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;read_glossary_check_metadata&lt;/code&gt;
orchestrate &lt;code dir=&quot;auto&quot;&gt;specify_cli&lt;/code&gt;’s full glossary pipeline and cannot move to kernel or doctrine
without inverting the ownership of the entire pipeline. The import is deferred to call time
(lazy import inside the function body). &lt;code dir=&quot;auto&quot;&gt;Strictness&lt;/code&gt; now imports from &lt;code dir=&quot;auto&quot;&gt;kernel.glossary_types&lt;/code&gt;.
This is the only sanctioned lazy cross-boundary import in the codebase.&lt;/p&gt;
&lt;p&gt;Backward compatibility is preserved via re-exports:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;doctrine.shared&lt;/code&gt; re-exports all types from &lt;code dir=&quot;auto&quot;&gt;kernel.glossary_types&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;specify_cli.glossary.{strictness,extraction,models,scope,checkpoint}&lt;/code&gt; re-export their
respective types from &lt;code dir=&quot;auto&quot;&gt;kernel.glossary_types&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;No existing call sites require changes.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;h3 id=&quot;dependency-graph-after&quot;&gt;Dependency graph (after)&lt;/h3&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;kernel (stdlib only)&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;+-- doctrine (no dependency on specify_cli)&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;|     doctrine.shared re-exports kernel.glossary_types&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;|     doctrine.missions.primitives imports from kernel.glossary_types&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;|     doctrine.missions.glossary_hook: kernel for Strictness; lazy import for specify_cli&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;+-- charter (no dependency on specify_cli at module level)&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;+-- specify_cli&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;specify_cli.glossary.* re-exports from kernel.glossary_types&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;All existing import paths continue to work unchanged&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h3 id=&quot;class-identity&quot;&gt;Class identity&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;from specify_cli.glossary.strictness import Strictness&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;from doctrine.shared import Strictness&lt;/code&gt;, and
&lt;code dir=&quot;auto&quot;&gt;from kernel.glossary_types import Strictness&lt;/code&gt;
all return the same class object. &lt;code dir=&quot;auto&quot;&gt;isinstance&lt;/code&gt; checks across package boundaries work.&lt;/p&gt;
&lt;h3 id=&quot;isolation-test&quot;&gt;Isolation test&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;tests/doctrine/test_isolation.py&lt;/code&gt; verifies that &lt;code dir=&quot;auto&quot;&gt;doctrine.missions.primitives&lt;/code&gt; can be
imported with only &lt;code dir=&quot;auto&quot;&gt;doctrine&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;kernel&lt;/code&gt; on &lt;code dir=&quot;auto&quot;&gt;PYTHONPATH&lt;/code&gt; — &lt;code dir=&quot;auto&quot;&gt;specify_cli&lt;/code&gt; absent.&lt;/p&gt;
&lt;h3 id=&quot;kernel-package-purpose-expanded&quot;&gt;kernel package purpose (expanded)&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;src/kernel/&lt;/code&gt; now contains two modules:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;atomic.py&lt;/code&gt; — atomic file-write utility&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;glossary_types.py&lt;/code&gt; — shared glossary primitive types&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Future zero-dependency shared utilities and value types belong here rather than being
duplicated across or imported between higher-level packages.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;related&quot;&gt;Related&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;PR #305 review finding C1&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;docs/development/pr305-review-resolution-plan.md&lt;/code&gt; — Track 2&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/kernel/__init__.py&lt;/code&gt; — package declaration&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/kernel/glossary_types.py&lt;/code&gt; — canonical type definitions&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
