<?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-1-doctrine-artifact-governance-model/">
  <id>https://docs.spec-kitty.ai/adr/2.x/2026-02-23-1-doctrine-artifact-governance-model/</id>
  <title>Doctrine Artifact Governance 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-1-doctrine-artifact-governance-model/"/>
  <summary>Stores directives, tactics, styleguides, and mission assets as typed schema-validated repository artifacts, and compiles charter bundles from them, not from prose.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;2.x introduces a doctrine layer that did not previously have an explicit ADR. We now have:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Typed doctrine artifacts under &lt;code dir=&quot;auto&quot;&gt;src/doctrine/&lt;/code&gt; (directives, tactics, styleguides, toolguides, schemas, mission assets).&lt;/li&gt;
&lt;li&gt;A charter generation flow built from interview answers plus doctrine catalog selection.&lt;/li&gt;
&lt;li&gt;Runtime/template loading paths that resolve packaged doctrine mission assets as canonical defaults.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Without an ADR, these choices are hard to evaluate and easy to accidentally regress.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;Make doctrine behavior auditable and deterministic.&lt;/li&gt;
&lt;li&gt;Keep governance artifacts local-first and repository-native.&lt;/li&gt;
&lt;li&gt;Enforce schema-level quality gates for doctrine artifacts.&lt;/li&gt;
&lt;li&gt;Ensure charter generation references explicit doctrine selections.&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 doctrine behavior implicit in templates and command handlers.&lt;/li&gt;
&lt;li&gt;Store doctrine as typed, schema-validated repository artifacts and compile charter bundles from them (chosen).&lt;/li&gt;
&lt;li&gt;Move doctrine selection/generation to an external service.&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; Store doctrine as typed, schema-validated repository artifacts and compile charter bundles from them.&lt;/p&gt;
&lt;h3 id=&quot;decision-details&quot;&gt;Decision Details&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;Doctrine artifacts are first-class files under &lt;code dir=&quot;auto&quot;&gt;src/doctrine/&lt;/code&gt; with schema contracts in &lt;code dir=&quot;auto&quot;&gt;src/doctrine/schemas/&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Charter generation compiles interview inputs plus doctrine selections into &lt;code dir=&quot;auto&quot;&gt;.kittify/charter/&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;charter.md&lt;/code&gt;, references, library files).&lt;/li&gt;
&lt;li&gt;Runtime default mission/template assets resolve from doctrine package assets (&lt;code dir=&quot;auto&quot;&gt;src/doctrine/missions/...&lt;/code&gt;) when project and global overrides are absent.&lt;/li&gt;
&lt;li&gt;Doctrine integrity is tested with fixture schema tests and in-repo artifact compliance tests.&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;Governance behavior is explicit, versioned, and reviewable.&lt;/li&gt;
&lt;li&gt;Charter output is reproducible from interview + doctrine selection state.&lt;/li&gt;
&lt;li&gt;Doctrine changes are testable in CI before user-facing execution.&lt;/li&gt;
&lt;/ol&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ol&gt;
&lt;li&gt;Additional schema and test maintenance burden for doctrine artifacts.&lt;/li&gt;
&lt;li&gt;More files and concepts for contributors to understand.&lt;/li&gt;
&lt;/ol&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ol&gt;
&lt;li&gt;Existing command UX is preserved while implementation becomes doctrine-backed.&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;Doctrine artifacts validate against schemas.&lt;/li&gt;
&lt;li&gt;Cross-artifact references resolve (for example directive &lt;code dir=&quot;auto&quot;&gt;tactic_refs&lt;/code&gt;, tactic references, toolguide paths).&lt;/li&gt;
&lt;li&gt;Charter generation produces deterministic bundles from the same inputs.&lt;/li&gt;
&lt;li&gt;Runtime/template resolution selects doctrine package defaults when higher-precedence tiers are absent.&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;src/doctrine/schemas/*.schema.yaml&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/doctrine/directives/test-first.directive.yaml&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/doctrine/tactics/*.tactic.yaml&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/doctrine/styleguides/**/*.styleguide.yaml&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/doctrine/toolguides/*.toolguide.yaml&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/charter/compiler.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/charter.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/runtime/home.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/runtime/resolver.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/doctrine/test_schema_validation.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/doctrine/test_artifact_compliance.py&lt;/code&gt;&lt;/li&gt;
&lt;/ol&gt;</content>
</entry>
