<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/3.x/2026-07-21-2-glossary-first-order-doctrine-artefact/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-07-21-2-glossary-first-order-doctrine-artefact/</id>
  <title>ADR: promote the glossary to a first-order doctrine artefact (GLOSSARY_PACK kind), retire the runtime glossary, and deliver terminology enforcement as an executable ASSET gate</title>
  <updated>2026-07-21T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/3.x/2026-07-21-2-glossary-first-order-doctrine-artefact/"/>
  <summary>The glossary is promoted to a charter-activatable `GLOSSARY_PACK` artefact kind, the runtime glossary retires, and terminology enforcement ships as an executable ASSET gate.</summary>
  <content type="html">&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Accepted&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-07-21&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Operator (Stijn Dejongh); assessment by a 4-lens pre-spec research squad
(2026-07-21, branch &lt;code dir=&quot;auto&quot;&gt;research/glossary-doctrine-artefact&lt;/code&gt;).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt; epics &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/1629&quot;&gt;#1629&lt;/a&gt;
(glossary coherence slice) / &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2535&quot;&gt;#2535&lt;/a&gt;
(doctrine-controlled transition gates); tickets
&lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/1418&quot;&gt;#1418&lt;/a&gt; (glossary as first-order
artifact — keystone), &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2727&quot;&gt;#2727&lt;/a&gt; (retire
runtime &lt;code dir=&quot;auto&quot;&gt;src/glossary/&lt;/code&gt;), &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2822&quot;&gt;#2822&lt;/a&gt;
(alias/banned-synonym governance), &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2830&quot;&gt;#2830&lt;/a&gt;
(retire the casing ratchet), &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2823&quot;&gt;#2823&lt;/a&gt;
(stale CLAUDE.md kind table), &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2599&quot;&gt;#2599&lt;/a&gt;
(executable ASSET-kind gate handlers). Program plan:
&lt;a href=&quot;../../plans/glossary-doctrine-overhaul-program.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;docs/plans/glossary-doctrine-overhaul-program.md&lt;/code&gt;&lt;/a&gt;.
Aligns with &lt;a href=&quot;/adr/3.x/2026-05-16-1-doctrine-layer-merge-semantics/&quot;&gt;ADR 2026-05-16-1&lt;/a&gt;.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Spec Kitty carries &lt;strong&gt;two&lt;/strong&gt; glossary subsystems that are drifting apart. The &lt;strong&gt;runtime
glossary&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;src/glossary/&lt;/code&gt;, ~6,379 LOC / 22 modules) is a dynamic observation/extraction/
resolution pipeline seeded from &lt;code dir=&quot;auto&quot;&gt;.kittify/glossaries/&amp;#x3C;scope&gt;.yaml&lt;/code&gt;. In parallel, #1418 designs
a &lt;strong&gt;static, distributable doctrine glossary&lt;/strong&gt; (a first-order artefact) and explicitly names the
runtime package as the thing it supersedes. Maintaining both is a standing tax; meanwhile the
runtime pipeline’s enforcement role has already lapsed.&lt;/p&gt;
&lt;p&gt;A 4-lens pre-spec research squad established the ground truth:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;#1418 is a draft architecture doc, not a spec; the pack half is fully greenfield.&lt;/strong&gt; The
&lt;em&gt;term&lt;/em&gt; half exists (&lt;code dir=&quot;auto&quot;&gt;NodeKind.GLOSSARY&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;Relation.VOCABULARY&lt;/code&gt;, the runtime &lt;code dir=&quot;auto&quot;&gt;glossary:&amp;#x3C;hash&gt;&lt;/code&gt;
DRG bridge). &lt;code dir=&quot;auto&quot;&gt;ArtifactKind.GLOSSARY_PACK&lt;/code&gt; does not exist; &lt;code dir=&quot;auto&quot;&gt;src/doctrine/glossaries/&lt;/code&gt; does not
exist.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The runtime glossary’s dynamic pipeline is provably dead&lt;/strong&gt; (~2,220 LOC never invoked; the
runner is never registered). All seven consumer surfaces named in #2727 are inert or cosmetic.
The package retains exactly &lt;strong&gt;two&lt;/strong&gt; pieces of live authority: the 104 curated canonical
definitions in &lt;code dir=&quot;auto&quot;&gt;spec_kitty_core.yaml&lt;/code&gt;, and an &lt;em&gt;unlisted 8th consumer&lt;/em&gt;,
&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_glossary_canonical_terms.py&lt;/code&gt;, which imports
&lt;code dir=&quot;auto&quot;&gt;glossary.scope.load_seed_file&lt;/code&gt; and is the live CI casing gate.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;#1418’s design contradicts #2727 as written.&lt;/strong&gt; #1418 proposes an ACL
(&lt;code dir=&quot;auto&quot;&gt;pack_seed_loader.py&lt;/code&gt;) that seeds the pack &lt;em&gt;into&lt;/em&gt; &lt;code dir=&quot;auto&quot;&gt;src/glossary/&lt;/code&gt; — the very package #2727
deletes.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Terminology enforcement is two disjoint hardcoded gates today:&lt;/strong&gt;
&lt;code dir=&quot;auto&quot;&gt;test_no_legacy_terminology.py&lt;/code&gt; (a 2-term git-grep denylist) and the casing gate above.
&lt;code dir=&quot;auto&quot;&gt;GlossarySeedTerm.synonyms_to_avoid&lt;/code&gt; already exists in the schema (3 terms populate it) but is
dropped at runtime and consumed by nothing — the metadata rail is present but unwired.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The executable ASSET-kind gate (#2599) is a security-sensitive greenfield subsystem&lt;/strong&gt; — it
executes pack-supplied code (RCE-equivalent surface) and its trust model is binding.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Single canonical authority&lt;/strong&gt; (charter governing principle) — one owning source for
terminology; collapse the two subsystems onto the doctrine artefact.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Glossary &amp;#x26; terminology adherence&lt;/strong&gt; (charter governing principle) — enforcement must be
data-driven from the canonical source, not hardcoded in disjoint tests.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Executable doctrine as a strategic enabler&lt;/strong&gt; — an executable ASSET rail lets
repository-specific logic (glossary/contextive parsing; repo-local step guards) move out of
the shared runtime and into shipped doctrine bundles. Glossary enforcement is its first
consumer, not its only one.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Readable, reviewable PRs&lt;/strong&gt; (DIRECTIVE_046) — keystone-first decomposition over one
unreviewable mega-diff.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Do not ship an RCE surface&lt;/strong&gt; while still deferring hardening that does not yet apply.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Option 1 (chosen)&lt;/strong&gt; — Build &lt;code dir=&quot;auto&quot;&gt;GLOSSARY_PACK&lt;/code&gt; as a first-order charter-activatable kind;
migrate the 104 terms onto it; deliver enforcement as an executable ASSET gate; retire the
runtime package. Sequenced four-mission program &lt;strong&gt;A → D → B → C&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 2&lt;/strong&gt; — Follow #1418 literally: keep &lt;code dir=&quot;auto&quot;&gt;src/glossary/&lt;/code&gt; and seed the pack into it via the
proposed ACL. &lt;em&gt;Rejected&lt;/em&gt; — the runtime is dead, this perpetuates the dual subsystem, and it
directly contradicts #2727.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 3&lt;/strong&gt; — Defer the ASSET gate; ship enforcement only as a data-driven Python
architectural test. &lt;em&gt;Rejected by the operator&lt;/em&gt; — the ASSET kind is a strategic enabler beyond
glossary and is wanted in-program.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 4&lt;/strong&gt; — One mega-mission covering all six tickets. &lt;em&gt;Rejected&lt;/em&gt; — unreviewable diff; the
keystone cannot stabilise before its dependents build on it.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;Chosen: &lt;strong&gt;Option 1.&lt;/strong&gt; Four decisions bind the program:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;GLOSSARY_PACK&lt;/code&gt; becomes a first-order, charter-activatable &lt;code dir=&quot;auto&quot;&gt;ArtifactKind&lt;/code&gt;&lt;/strong&gt; — it joins the
8-kind charter-activatable universe, &lt;strong&gt;not&lt;/strong&gt; the &lt;code dir=&quot;auto&quot;&gt;{template, asset}&lt;/code&gt; exclusion set. Copy the
&lt;code dir=&quot;auto&quot;&gt;directive&lt;/code&gt; kind’s wiring. The pack URN is &lt;code dir=&quot;auto&quot;&gt;glossary_pack:&lt;/code&gt; (underscore) — the DRG URN regex
and the &lt;code dir=&quot;auto&quot;&gt;prefix == kind.value&lt;/code&gt; assertion (&lt;code dir=&quot;auto&quot;&gt;src/doctrine/drg/models.py:19,117-121&lt;/code&gt;) reject the
hyphenated form; hyphen is the operator token only. A “resolves as a loaded node” test guards
the silent-invisibility trap (packs load but stay invisible unless the extractor emits them
and a &lt;code dir=&quot;auto&quot;&gt;*.graph.yaml&lt;/code&gt; fragment ships).&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Reconcile #1418 ↔ #2727 by not seeding into the dying runtime.&lt;/strong&gt; #1418’s proposed
seed-into-runtime ACL is dropped/inverted. Instead: migrate the 104 curated terms into the
built-in &lt;code dir=&quot;auto&quot;&gt;spec-kitty-core&lt;/code&gt; pack; repoint the casing gate at the pack loader (the single hard
dependency); then retire &lt;code dir=&quot;auto&quot;&gt;src/glossary/&lt;/code&gt;.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Terminology enforcement is delivered as a built-in executable ASSET gate&lt;/strong&gt; consuming the
pack’s &lt;code dir=&quot;auto&quot;&gt;aliases&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;banned_synonyms&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;synonyms_to_avoid&lt;/code&gt;, folding in the 2-term legacy
denylist. The 200 baselined casing violations are swept and the ratchet deleted (#2830); the
stale CLAUDE.md kind table is corrected (#2823).&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;The executable ASSET trust model is phased on provenance.&lt;/strong&gt; A &lt;em&gt;built-in&lt;/em&gt; asset is Spec
Kitty’s own shipped code, so executing it is the same trust level as the rest of the CLI; the
RCE-surface concern applies only to &lt;em&gt;non-built-in&lt;/em&gt; provenance. Phase 1 (this program) ships
with the cheap, load-bearing guards — &lt;code dir=&quot;auto&quot;&gt;review.allow_executable_gate_assets&lt;/code&gt; opt-in
&lt;strong&gt;default-OFF&lt;/strong&gt;, per-invocation &lt;strong&gt;timeout&lt;/strong&gt;, &lt;strong&gt;fail-OPEN&lt;/strong&gt;, &lt;strong&gt;structured-verdict-or-warn&lt;/strong&gt; —
and hard-restricts provenance to &lt;code dir=&quot;auto&quot;&gt;built-in&lt;/code&gt;. The expensive hardening (full sandboxed runner,
interpreter allowlist / no-shell) is deferred to the increment that first enables org-pack /
third-party asset execution, because that is the only point at which it becomes load-bearing.
The provenance gate and the default-off flag are &lt;strong&gt;not&lt;/strong&gt; deferred.&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;program-sequence&quot;&gt;Program sequence&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;A&lt;/strong&gt; (build &lt;code dir=&quot;auto&quot;&gt;GLOSSARY_PACK&lt;/code&gt; kind + migrate 104 terms, #1418, keystone) → &lt;strong&gt;D&lt;/strong&gt; (executable
ASSET-kind gate, #2599, depends on A + #2535 steps 1–4) → &lt;strong&gt;B&lt;/strong&gt; (enforcement shipped as a
built-in ASSET gate + casing/CLAUDE.md cleanup, #2822/#2830/#2823, depends on A + D) → &lt;strong&gt;C&lt;/strong&gt;
(retire runtime &lt;code dir=&quot;auto&quot;&gt;src/glossary/&lt;/code&gt;, #2727, depends on A + B). Recommended order is A → D → B → C so
enforcement ships directly in its target form; a fallback lets B ship interim Python enforcement
if D slips, re-homed onto the asset rail later.&lt;/p&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Positive&lt;/strong&gt; — one canonical terminology authority; ~6,379 LOC of dead machinery removed; a
reusable executable-doctrine rail; enforcement data-driven from the pack rather than hardcoded.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Negative / risk&lt;/strong&gt; — the ASSET gate is security-sensitive greenfield and depends on #2535
steps 1–4 landing; three mirrored kind-lists (&lt;code dir=&quot;auto&quot;&gt;pack_context._BUILTIN_ARTIFACT_KINDS&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;activations._ALLOWED_KINDS&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;org_pack_loader._ORG_DRG_CANONICAL_KINDS&lt;/code&gt;) are drift-guarded to
move in lockstep; the &lt;code dir=&quot;auto&quot;&gt;spec-kitty glossary&lt;/code&gt; CLI + dashboard handler are user-facing contracts
requiring a deprecation path, not a silent delete.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Boundaries&lt;/strong&gt; — NOT #2653 (prose-only), and the doctrine-side tests
(&lt;code dir=&quot;auto&quot;&gt;test_glossary_link_integrity&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;test_glossary_node_kind&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;scripts.docs.glossary_linker&lt;/code&gt;)
are left untouched.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;related-adrs&quot;&gt;Related ADRs&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/adr/3.x/2026-07-22-1-gate-binding-content-vs-relationship/&quot;&gt;2026-07-22-1-gate-binding-content-vs-relationship.md&lt;/a&gt;
— the reuse/attach counterpart of this promote decision: same content-vs-relationship
rule, opposite outcome. That ADR reuses the existing &lt;code dir=&quot;auto&quot;&gt;mission_step_contract&lt;/code&gt; kind for
gate bindings (a relationship/configuration on an existing artefact) rather than
promoting a new &lt;code dir=&quot;auto&quot;&gt;gate&lt;/code&gt; kind, because a gate binding — unlike this glossary pack — has no
files, repository, or provenance of its own.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
