<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/migrations/relocate-builtin-doctrine-packs/">
  <id>https://docs.spec-kitty.ai/migrations/relocate-builtin-doctrine-packs/</id>
  <title>Migration: Relocate Built-In Doctrine to packs/built-in</title>
  <updated>2026-10-08T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/migrations/relocate-builtin-doctrine-packs/"/>
  <summary>Migration for the built-in doctrine relocation: content moved from src/doctrine into a top-level packs/built-in/ pack root, resolved through a shared pack-root seam.</summary>
  <content type="html">&lt;blockquote&gt;
&lt;p&gt;Migration note: This page documents a migration path or historical transition. It is not the current 3.2 happy path.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;span id=&quot;migration-relocate-built-in-doctrine-to-packsbuilt-in&quot;&gt;&lt;/span&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Superseded; kept as a historical record.&lt;/strong&gt; The charter-pack cutover (#3732) replaced the layout
and commands this page describes, and Spec Kitty no longer reads them. The current path is
&lt;a href=&quot;/migrations/charter-pack-cutover/&quot;&gt;Charter pack cutover&lt;/a&gt;.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;&lt;strong&gt;Mission&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;relocate-builtin-doctrine-packs-01KYT87F&lt;/code&gt;
&lt;strong&gt;Audience&lt;/strong&gt;: downstream org/project doctrine-pack authors, and anyone whose code or docs referenced the built-in doctrine artefacts by their old &lt;code dir=&quot;auto&quot;&gt;src/doctrine/&lt;/code&gt; paths.&lt;/p&gt;
&lt;h2 id=&quot;what-changed&quot;&gt;What changed&lt;/h2&gt;
&lt;p&gt;The &lt;strong&gt;content&lt;/strong&gt; (data files) of the built-in doctrine pack moved out of the
&lt;code dir=&quot;auto&quot;&gt;src/doctrine/&lt;/code&gt; Python package into a new &lt;strong&gt;top-level &lt;code dir=&quot;auto&quot;&gt;packs/built-in/&lt;/code&gt; pack
root&lt;/strong&gt;. Only the shipped artefact data moved — no doctrine &lt;code dir=&quot;auto&quot;&gt;.py&lt;/code&gt; code, schemas,
templates, skills, or the &lt;code dir=&quot;auto&quot;&gt;missions/&lt;/code&gt; tree moved (those still live under
&lt;code dir=&quot;auto&quot;&gt;src/doctrine/&lt;/code&gt;).&lt;/p&gt;
&lt;p&gt;The move is &lt;strong&gt;breaking&lt;/strong&gt; for anything that named the old paths, and it
&lt;strong&gt;flattens&lt;/strong&gt; the layout: the pre-move per-kind home &lt;code dir=&quot;auto&quot;&gt;src/doctrine/&amp;#x3C;kind&gt;/built-in/&lt;/code&gt;
loses its inner &lt;code dir=&quot;auto&quot;&gt;built-in/&lt;/code&gt; segment and becomes &lt;code dir=&quot;auto&quot;&gt;packs/built-in/&amp;#x3C;kind&gt;/&lt;/code&gt;.&lt;/p&gt;



































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Kind of reference&lt;/th&gt;&lt;th&gt;Before (pre-move)&lt;/th&gt;&lt;th&gt;After (this mission)&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;Per-kind built-in content&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/doctrine/&amp;#x3C;kind&gt;/built-in/&amp;#x3C;file&gt;&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;packs/built-in/&amp;#x3C;kind&gt;/&amp;#x3C;file&gt;&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Sharded DRG fragments&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/doctrine/&amp;#x3C;kind&gt;.graph.yaml&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;packs/built-in/&amp;#x3C;kind&gt;.graph.yaml&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Built-in agent profiles&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/doctrine/agent_profiles/built-in/*.agent.yaml&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;packs/built-in/agent_profiles/*.agent.yaml&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Built-in glossary packs&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/doctrine/glossary_packs/built-in/*.glossary-pack.yaml&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;packs/built-in/glossary_packs/*.glossary-pack.yaml&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Doctrine &lt;code dir=&quot;auto&quot;&gt;.py&lt;/code&gt; code, &lt;code dir=&quot;auto&quot;&gt;schemas/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;templates/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;skills/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;missions/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/doctrine/…&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;strong&gt;unchanged&lt;/strong&gt; — still &lt;code dir=&quot;auto&quot;&gt;src/doctrine/…&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h3 id=&quot;the-new-resolution-seam&quot;&gt;The new resolution seam&lt;/h3&gt;
&lt;p&gt;All three tiers (built-in → org → project) now resolve the built-in root
through a single shared seam, &lt;code dir=&quot;auto&quot;&gt;resolve_pack_root(&quot;built-in&quot;)&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;src/doctrine/pack_paths.py&lt;/code&gt;). It fails &lt;strong&gt;closed&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;PackRootNotFound&lt;/code&gt;) rather
than guessing, and discovers the root in three ordered ways:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;an explicit environment override;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;editable checkout&lt;/strong&gt; — the nearest ancestor directory that contains
&lt;code dir=&quot;auto&quot;&gt;packs/built-in/&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;installed wheel&lt;/strong&gt; — &lt;code dir=&quot;auto&quot;&gt;packs/&lt;/code&gt; ships as a site-packages &lt;em&gt;sibling&lt;/em&gt; of the
&lt;code dir=&quot;auto&quot;&gt;doctrine&lt;/code&gt; package, i.e. &lt;code dir=&quot;auto&quot;&gt;files(&quot;doctrine&quot;).parent / &quot;packs&quot; / &quot;built-in&quot;&lt;/code&gt;.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;The DRG seam (&lt;code dir=&quot;auto&quot;&gt;built_in_graph_source()&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;load_built_in_graph()&lt;/code&gt; in
&lt;code dir=&quot;auto&quot;&gt;src/doctrine/drg/loader.py&lt;/code&gt;) now yields the &lt;code dir=&quot;auto&quot;&gt;packs/built-in/&lt;/code&gt; directory
(&lt;code dir=&quot;auto&quot;&gt;source.name == &quot;built-in&quot;&lt;/code&gt;), and the shipped graph loads by merging the
per-kind &lt;code dir=&quot;auto&quot;&gt;*.graph.yaml&lt;/code&gt; fragments it finds there.&lt;/p&gt;
&lt;h3 id=&quot;no-runtime-shim&quot;&gt;No runtime shim&lt;/h3&gt;
&lt;p&gt;There is &lt;strong&gt;no compatibility shim&lt;/strong&gt; for the old &lt;code dir=&quot;auto&quot;&gt;src/doctrine/&amp;#x3C;kind&gt;/built-in&lt;/code&gt;
locations. A reader that still names an old path gets a missing file, not a
silent redirect — the fail-closed resolver is deliberate. Update the reference
(see the table above) rather than relying on a fallback.&lt;/p&gt;
&lt;h3 id=&quot;packaging&quot;&gt;Packaging&lt;/h3&gt;
&lt;p&gt;Both the wheel and the sdist ship the relocated tree:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;wheel&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;[tool.hatch.build.targets.wheel] force-include = { &quot;packs&quot; = &quot;packs&quot; }&lt;/code&gt;
lands &lt;code dir=&quot;auto&quot;&gt;packs/built-in/&amp;#x3C;kind&gt;/…&lt;/code&gt; as a site-packages sibling of &lt;code dir=&quot;auto&quot;&gt;doctrine&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;sdist&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;packs/**&lt;/code&gt; is added to &lt;code dir=&quot;auto&quot;&gt;[tool.hatch.build.targets.sdist]&lt;/code&gt; (the
&lt;code dir=&quot;auto&quot;&gt;src/**&lt;/code&gt; globs never match a top-level &lt;code dir=&quot;auto&quot;&gt;packs/&lt;/code&gt; tree).&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;A &lt;code dir=&quot;auto&quot;&gt;.gitignore&lt;/code&gt; audit confirms no &lt;code dir=&quot;auto&quot;&gt;packs/&lt;/code&gt;- or &lt;code dir=&quot;auto&quot;&gt;built-in/&lt;/code&gt;-shaped pattern
swallows the new tree (&lt;code dir=&quot;auto&quot;&gt;git check-ignore packs/built-in/...&lt;/code&gt; returns “not
ignored”).&lt;/p&gt;
&lt;h2 id=&quot;action-required&quot;&gt;Action required&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Downstream pack authors and integrators:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;If you referenced a built-in artefact by its &lt;code dir=&quot;auto&quot;&gt;src/doctrine/&amp;#x3C;kind&gt;/built-in/…&lt;/code&gt;
path (in code, docs, DRG endpoints, or tooling), repoint it to
&lt;code dir=&quot;auto&quot;&gt;packs/built-in/&amp;#x3C;kind&gt;/…&lt;/code&gt; (drop the inner &lt;code dir=&quot;auto&quot;&gt;built-in/&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;If you resolved the built-in root yourself, switch to
&lt;code dir=&quot;auto&quot;&gt;resolve_pack_root(&quot;built-in&quot;)&lt;/code&gt; rather than reconstructing the path.&lt;/li&gt;
&lt;li&gt;Org and project packs are unaffected in shape — this mission moved &lt;strong&gt;only&lt;/strong&gt;
the built-in tier’s on-disk home. Converging built-in onto the org-pack
loader/schema contract is &lt;strong&gt;Phase 2&lt;/strong&gt; (see Follow-ons).&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;rollback&quot;&gt;Rollback&lt;/h2&gt;
&lt;p&gt;This is a pure relocation of committed content plus a resolver repoint; there
is no data migration and no persisted state to revert. To roll back, revert the
mission’s merge commit — the built-in content returns to &lt;code dir=&quot;auto&quot;&gt;src/doctrine/&amp;#x3C;kind&gt;/built-in/&lt;/code&gt;
and the resolver/loader repoint reverts with it. No downstream cleanup is
required because there is no shim or generated sidecar to unwind.&lt;/p&gt;
&lt;h2 id=&quot;follow-ons&quot;&gt;Follow-ons&lt;/h2&gt;
&lt;p&gt;Two pieces of work are &lt;strong&gt;deliberately deferred&lt;/strong&gt; and must not be treated as
lost:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Phase 1b — relocate the &lt;code dir=&quot;auto&quot;&gt;missions/&lt;/code&gt; tree&lt;/strong&gt;
(&lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/3091&quot;&gt;#3091&lt;/a&gt;). The
&lt;code dir=&quot;auto&quot;&gt;missions/&lt;/code&gt; readers span the kernel layer and use &lt;code dir=&quot;auto&quot;&gt;__file__&lt;/code&gt;-relative idioms
that cannot route through the doctrine-layer resolver without a layering
violation. &lt;strong&gt;First task:&lt;/strong&gt; a cross-layer &lt;code dir=&quot;auto&quot;&gt;missions/&lt;/code&gt;-reader inventory (every
&lt;code dir=&quot;auto&quot;&gt;files(&quot;doctrine*&quot;)&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;__file__&lt;/code&gt;-relative reader that touches &lt;code dir=&quot;auto&quot;&gt;missions/&lt;/code&gt;),
classified as move-or-stay, before any file moves.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Phase 2 — loader/schema convergence.&lt;/strong&gt; Unify built-in onto the org-pack
loader and schema contract and re-architect &lt;code dir=&quot;auto&quot;&gt;merge_three_layers&lt;/code&gt;. This
mission preserved the built-in &lt;em&gt;structure&lt;/em&gt; (a per-kind mirror); it did &lt;strong&gt;not&lt;/strong&gt;
claim built-in’s on-disk shape matches the org/project pack contract.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;notes&quot;&gt;Notes&lt;/h2&gt;
&lt;p&gt;Observations recorded during the closeout for a later agent to action — &lt;strong&gt;out
of scope to fix in this mission&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;CLAUDE.md&lt;/code&gt; “Deferred Items” lists a closed issue.&lt;/strong&gt; The
“Charter Activation and Doctrine Integrity Model → Deferred Items” list still
carries &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/1624&quot;&gt;#1624&lt;/a&gt;
(&lt;code dir=&quot;auto&quot;&gt;_tag_source&lt;/code&gt; provenance sidecar typing), which is &lt;strong&gt;already closed&lt;/strong&gt;. Flag
for a later CLAUDE.md correction.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Migration-hint repoint was cross-cutting.&lt;/strong&gt; The relocation left the
operator-facing DRG-edge migration hint (&lt;code dir=&quot;auto&quot;&gt;build_migration_hint&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;src/doctrine/shared/errors.py&lt;/code&gt;) naming the now-dead &lt;code dir=&quot;auto&quot;&gt;src/doctrine/&amp;#x3C;kind&gt;.graph.yaml&lt;/code&gt;.
It was repointed to &lt;code dir=&quot;auto&quot;&gt;packs/built-in/&amp;#x3C;kind&gt;.graph.yaml&lt;/code&gt; here, along with the
tests that pin its shape (&lt;code dir=&quot;auto&quot;&gt;tests/doctrine/shared/test_errors.py&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;tests/doctrine/test_inline_ref_rejection.py&lt;/code&gt;) — because both the mission’s
own dead-path gate and a sibling test went red on the dead path. &lt;strong&gt;Follow-on:&lt;/strong&gt;
the shape contract at
&lt;code dir=&quot;auto&quot;&gt;kitty-specs/excise-doctrine-curation-and-inline-references-01KP54J6/contracts/validator-rejection-error.schema.json&lt;/code&gt;
is an archived artifact of another mission and was &lt;strong&gt;left untouched&lt;/strong&gt;; its
&lt;code dir=&quot;auto&quot;&gt;pattern&lt;/code&gt;/example still name the old &lt;code dir=&quot;auto&quot;&gt;src/doctrine/…graph.yaml&lt;/code&gt; shape. No test
loads that JSON at runtime (it is documentation only), so nothing is red, but
the contract now lags the emitted hint and should be refreshed by the owning
mission.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Cross-tree markdown links.&lt;/strong&gt; Because &lt;code dir=&quot;auto&quot;&gt;packs/built-in/toolguides/&lt;/code&gt; (moved)
and &lt;code dir=&quot;auto&quot;&gt;src/doctrine/templates/&lt;/code&gt; (stayed) cross-reference each other, several
navigation links are now cross-tree relative paths
(&lt;code dir=&quot;auto&quot;&gt;packs/built-in/…&lt;/code&gt; ↔ &lt;code dir=&quot;auto&quot;&gt;src/doctrine/templates/…&lt;/code&gt;). They resolve and are
guarded by &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_no_dead_doctrine_paths.py&lt;/code&gt; Gate C, but
the split home is a structural smell a future consolidation (Phase 1b/2) may
want to remove.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Toolguide &lt;code dir=&quot;auto&quot;&gt;guide_path:&lt;/code&gt; metadata.&lt;/strong&gt; Several &lt;code dir=&quot;auto&quot;&gt;packs/built-in/toolguides/*.toolguide.yaml&lt;/code&gt;
still carry &lt;code dir=&quot;auto&quot;&gt;guide_path: src/doctrine/toolguides/built-in/&amp;#x3C;FILE&gt;.md&lt;/code&gt; in their
YAML metadata (a data field, not markdown navigation, so outside Gate C’s
&lt;code dir=&quot;auto&quot;&gt;*.md&lt;/code&gt; scope). Confirm the toolguide loader/resolver repoints these to
&lt;code dir=&quot;auto&quot;&gt;packs/built-in/toolguides/&lt;/code&gt; (content-move integrity, not a WP08 test-literal
concern).&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;why-this-happened&quot;&gt;Why this happened&lt;/h2&gt;
&lt;p&gt;See &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/docs/adr/3.x/2026-07-26-2-doctrine-artefact-pack-layout-convention.md&quot;&gt;ADR 2026-07-26-2: Doctrine Artefact Pack Layout Convention&lt;/a&gt;
and the mission spec at
&lt;code dir=&quot;auto&quot;&gt;kitty-specs/relocate-builtin-doctrine-packs-01KYT87F/spec.md&lt;/code&gt; for the full
rationale, the built-in → org → project resolution-seam goal, and why loader
convergence is deferred to Phase 2.&lt;/p&gt;</content>
</entry>
