<?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-05-24-3-shipped-to-built-in-cutover/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-05-24-3-shipped-to-built-in-cutover/</id>
  <title>ADR: `shipped` → `built-in` Vocabulary Cutover for Doctrine Layer Label</title>
  <updated>2026-05-24T00: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-05-24-3-shipped-to-built-in-cutover/"/>
  <summary>Renames the doctrine layer label from shipped to built-in across identifiers, messages, and CLI JSON output in one breaking cutover with no deprecation window.</summary>
  <content type="html">&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/adr/3.x/2026-05-16-1-doctrine-layer-merge-semantics/&quot;&gt;ADR 2026-05-16-1 — Doctrine Layer Merge Semantics&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/adr/3.x/2026-05-24-2-pack-augmentation-vocabulary/&quot;&gt;ADR 2026-05-24-2 — Pack Augmentation Vocabulary&lt;/a&gt;
&lt;strong&gt;Cross-references&lt;/strong&gt;:&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/adr/3.x/2026-05-24-1-charter-freshness-ux-contract/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;2026-05-24-1-charter-freshness-ux-contract.md&lt;/code&gt;&lt;/a&gt; (sibling — consumes the renamed &lt;code dir=&quot;auto&quot;&gt;built-in&lt;/code&gt; label in its freshness banners and preflight output)&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;context&quot;&gt;Context&lt;/h2&gt;
&lt;p&gt;The doctrine layer system has three layers stacked from least- to most-specific:
&lt;code dir=&quot;auto&quot;&gt;built-in → org → project&lt;/code&gt;. The runtime resolves an artifact by reading the
lowest-precedence layer first and overlaying higher-precedence layers on top
of it (per the field-level merge ratified in &lt;code dir=&quot;auto&quot;&gt;2026-05-16-1&lt;/code&gt;).&lt;/p&gt;
&lt;p&gt;On disk, the lowest layer has always been called &lt;code dir=&quot;auto&quot;&gt;built-in/&lt;/code&gt; — there are
&lt;code dir=&quot;auto&quot;&gt;built-in/&lt;/code&gt; directories under every artifact kind (&lt;code dir=&quot;auto&quot;&gt;tactics/built-in/&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;paradigms/built-in/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;agent_profiles/built-in/&lt;/code&gt;, etc.). But in code,
the same layer is referred to inconsistently:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Python identifiers in &lt;code dir=&quot;auto&quot;&gt;src/doctrine/base.py&lt;/code&gt; say &lt;code dir=&quot;auto&quot;&gt;_shipped_dir&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;_load_shipped_items&lt;/code&gt;, and parameter names like &lt;code dir=&quot;auto&quot;&gt;shipped&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Docstrings say &lt;code dir=&quot;auto&quot;&gt;&quot;shipped → org → project&quot;&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Log lines say &lt;code dir=&quot;auto&quot;&gt;Skipping invalid shipped {kind}&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;CLI JSON surfaces (&lt;code dir=&quot;auto&quot;&gt;spec-kitty agent profile list --json&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;spec-kitty charter status --json&lt;/code&gt;) emit &lt;code dir=&quot;auto&quot;&gt;&quot;shipped&quot;&lt;/code&gt; as the layer label.&lt;/li&gt;
&lt;li&gt;Test fixtures and assertions across &lt;code dir=&quot;auto&quot;&gt;tests/&lt;/code&gt; bake the literal &lt;code dir=&quot;auto&quot;&gt;&quot;shipped&quot;&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Docs and CHANGELOG entries refer to the layer as &lt;code dir=&quot;auto&quot;&gt;shipped&lt;/code&gt; in some
places and &lt;code dir=&quot;auto&quot;&gt;built-in&lt;/code&gt; in others.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The on-disk vocabulary is canonical (it is what operators see when they
&lt;code dir=&quot;auto&quot;&gt;ls&lt;/code&gt; the doctrine tree), but the in-code vocabulary lags. This asymmetry
hurts readability, makes greps misleading, and confuses pack authors who
read a &lt;code dir=&quot;auto&quot;&gt;built-in/&lt;/code&gt; directory and then see &lt;code dir=&quot;auto&quot;&gt;&quot;shipped&quot;&lt;/code&gt; echoed in &lt;code dir=&quot;auto&quot;&gt;--json&lt;/code&gt;
output.&lt;/p&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;2026-05-24-2&lt;/code&gt; added two declarative pack-augmentation fields
(&lt;code dir=&quot;auto&quot;&gt;overrides&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;enhances&lt;/code&gt;) whose target &lt;em&gt;is&lt;/em&gt; the built-in layer. The new
fields are authored in pack YAML against &lt;code dir=&quot;auto&quot;&gt;built-in&lt;/code&gt; IDs while the runtime
internally still calls that layer &lt;code dir=&quot;auto&quot;&gt;shipped&lt;/code&gt;. Resolving the vocabulary
asymmetry now — at the same time pack augmentation lands — keeps the
mental model coherent for pack authors.&lt;/p&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;p&gt;Perform a &lt;strong&gt;straight cutover&lt;/strong&gt; of the layer label from &lt;code dir=&quot;auto&quot;&gt;shipped&lt;/code&gt; to
&lt;code dir=&quot;auto&quot;&gt;built-in&lt;/code&gt; across all &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt; source surfaces:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Python identifiers (functions, methods, parameters, local variables).&lt;/li&gt;
&lt;li&gt;Docstrings and inline comments.&lt;/li&gt;
&lt;li&gt;Log / advisory / warning message strings.&lt;/li&gt;
&lt;li&gt;CLI JSON output values (&lt;code dir=&quot;auto&quot;&gt;spec-kitty agent profile list --json&lt;/code&gt; source label,
&lt;code dir=&quot;auto&quot;&gt;_warn_project_override&lt;/code&gt; log payload).&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;The on-disk layout (&lt;code dir=&quot;auto&quot;&gt;built-in/&lt;/code&gt; directories) already uses the target term and
is unchanged.&lt;/p&gt;
&lt;p&gt;The cutover is performed without a deprecation window. The CHANGELOG entry
(authored in WP09 of this mission) flags this as a &lt;strong&gt;breaking change&lt;/strong&gt; for any
external tooling that pattern-matches the string &lt;code dir=&quot;auto&quot;&gt;&quot;shipped&quot;&lt;/code&gt; in CLI JSON
output. An architectural regression test (FR-016, authored in WP08) asserts
zero occurrences of the literal &lt;code dir=&quot;auto&quot;&gt;&quot;shipped&quot;&lt;/code&gt; as a layer label in &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;tests/&lt;/code&gt;, preventing regression.&lt;/p&gt;
&lt;h2 id=&quot;alternatives-considered&quot;&gt;Alternatives Considered&lt;/h2&gt;
&lt;h3 id=&quot;a-dual-emit-deprecation-period-rejected&quot;&gt;A. Dual-emit deprecation period (rejected)&lt;/h3&gt;
&lt;p&gt;The runtime could emit &lt;em&gt;both&lt;/em&gt; &lt;code dir=&quot;auto&quot;&gt;&quot;shipped&quot;&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;&quot;built-in&quot;&lt;/code&gt; for one or more
minor versions, signalling deprecation of &lt;code dir=&quot;auto&quot;&gt;&quot;shipped&quot;&lt;/code&gt; and removing it in a
later version. This was rejected because:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The doctrine pack vocabulary is internal-facing: it is consumed by
&lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt; operators reading CLI output, not by long-lived external
pipelines with deployment lag.&lt;/li&gt;
&lt;li&gt;Dual-emit doubles the surface that tests must cover and creates a
permanent gravitational pull back toward &lt;code dir=&quot;auto&quot;&gt;&quot;shipped&quot;&lt;/code&gt; (engineers reading
dual-emit code will copy the wrong half).&lt;/li&gt;
&lt;li&gt;The asymmetry is a documented bug (&lt;code dir=&quot;auto&quot;&gt;built-in/&lt;/code&gt; on disk vs &lt;code dir=&quot;auto&quot;&gt;shipped&lt;/code&gt; in
code), not a feature. Deprecating one half encodes the bug into the
contract.&lt;/li&gt;
&lt;li&gt;Per R-3 in &lt;code dir=&quot;auto&quot;&gt;research.md&lt;/code&gt;: the surface area is small enough that a
straight cutover plus CHANGELOG warning is cheaper than a deprecation
cycle.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;b-postpone-until-a-major-release-rejected&quot;&gt;B. Postpone until a major release (rejected)&lt;/h3&gt;
&lt;p&gt;The cutover could ride alongside a future 4.0 boundary change. Rejected
because:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The vocabulary mismatch confuses pack authors &lt;em&gt;today&lt;/em&gt;, especially in
combination with &lt;code dir=&quot;auto&quot;&gt;2026-05-24-2&lt;/code&gt;’s new &lt;code dir=&quot;auto&quot;&gt;overrides&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;enhances&lt;/code&gt; fields.&lt;/li&gt;
&lt;li&gt;Postponement only enlarges the surface that has to be edited later.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;h3 id=&quot;positive&quot;&gt;Positive&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;The in-code vocabulary matches the on-disk layout. &lt;code dir=&quot;auto&quot;&gt;grep -r built-in src/&lt;/code&gt; returns coherent results.&lt;/li&gt;
&lt;li&gt;Log lines, advisory text, and JSON output use the same word a pack
author sees when they &lt;code dir=&quot;auto&quot;&gt;ls built-in/&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;The pack augmentation vocabulary from &lt;code dir=&quot;auto&quot;&gt;2026-05-24-2&lt;/code&gt; lands against
consistent terminology (pack YAML authors &lt;code dir=&quot;auto&quot;&gt;enhances: &amp;#x3C;id&gt;&lt;/code&gt; targets the
&lt;code dir=&quot;auto&quot;&gt;built-in&lt;/code&gt; layer; the runtime now says so in every surface).&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;negative&quot;&gt;Negative&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Breaking change for any external tooling that pattern-matches
&lt;code dir=&quot;auto&quot;&gt;&quot;shipped&quot;&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent profile list --json&lt;/code&gt; or
&lt;code dir=&quot;auto&quot;&gt;spec-kitty charter status --json&lt;/code&gt; output. Documented in CHANGELOG
under the next release.&lt;/li&gt;
&lt;li&gt;A large mechanical edit touches many files. Mitigated by:
&lt;ul&gt;
&lt;li&gt;Authoritative &lt;code dir=&quot;auto&quot;&gt;occurrence_map.yaml&lt;/code&gt; classifying every rename target.&lt;/li&gt;
&lt;li&gt;Bulk-edit gate enforcing per-commit trace to a classification row.&lt;/li&gt;
&lt;li&gt;FR-016 architectural regression test (WP08) preventing reintroduction.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;Cross-cutting test failures land in WP07 and are intentionally left
for WP08 to fix in bulk (per the per-WP scoping in the mission tasks).
This is not a regression; it is the planned wave boundary.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;neutral&quot;&gt;Neutral&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;The word &lt;code dir=&quot;auto&quot;&gt;&quot;shipped&quot;&lt;/code&gt; remains acceptable in unrelated English contexts
(e.g. &lt;code dir=&quot;auto&quot;&gt;&quot;the v3.2 release shipped on 2026-05-12&quot;&lt;/code&gt;). Only its use as a
doctrine layer label is in scope. The &lt;code dir=&quot;auto&quot;&gt;occurrence_map.yaml&lt;/code&gt; codifies
this distinction.&lt;/li&gt;
&lt;li&gt;Historical text (ADR &lt;code dir=&quot;auto&quot;&gt;2026-05-16-1&lt;/code&gt;, CHANGELOG entries before this
mission merges, frozen kitty-spec snapshots) is preserved as-is. The
&lt;code dir=&quot;auto&quot;&gt;historical_preservation&lt;/code&gt; section of &lt;code dir=&quot;auto&quot;&gt;occurrence_map.yaml&lt;/code&gt; lists the
paths that MUST NOT be edited.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;cross-references&quot;&gt;Cross-references&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/adr/3.x/2026-05-16-1-doctrine-layer-merge-semantics/&quot;&gt;ADR 2026-05-16-1 — Doctrine Layer Merge Semantics&lt;/a&gt;
ratified the field-level merge. This ADR aligns the vocabulary of that
merge contract with the on-disk layout.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/adr/3.x/2026-05-24-2-pack-augmentation-vocabulary/&quot;&gt;ADR 2026-05-24-2 — Pack Augmentation Vocabulary&lt;/a&gt;
introduced &lt;code dir=&quot;auto&quot;&gt;overrides&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;enhances&lt;/code&gt; declarative fields whose target is
the built-in layer. This ADR ensures that target is named consistently
across code, logs, and CLI output.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;kitty-specs/charter-ux-and-org-pack-vocabulary-01KSAF14/occurrence_map.yaml&lt;/code&gt;
is the authoritative per-file classification for the rename.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;kitty-specs/charter-ux-and-org-pack-vocabulary-01KSAF14/research.md&lt;/code&gt; R-3
records the decision rationale for straight cutover over dual-emit.&lt;/li&gt;
&lt;li&gt;WP08 authors &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_no_shipped_layer_label.py&lt;/code&gt;
(FR-016) to operationalise this ADR on every CI run.&lt;/li&gt;
&lt;li&gt;WP09 authors the CHANGELOG breaking-change entry.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
