<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/4.x/2026-10-11-2-a-pack-declares-its-level-in-pack-yaml/">
  <id>https://docs.spec-kitty.ai/adr/4.x/2026-10-11-2-a-pack-declares-its-level-in-pack-yaml/</id>
  <title>ADR: a Charter Pack declares its level in pack.yaml</title>
  <updated>2026-10-11T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/4.x/2026-10-11-2-a-pack-declares-its-level-in-pack-yaml/"/>
  <summary>Every Charter Pack declares its level (built-in, org or project) in pack.yaml; loading refuses a pack whose declared level disagrees with where it is configured.</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-10-11&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Stijn Dejongh (owner; ruled on the model and the vocabulary on 2026-10-11).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt; the layout question on
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty-open-packs/pull/32&quot;&gt;spec-kitty-open-packs#32&lt;/a&gt;
(seeding the built-in pack into open-packs for &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/3504&quot;&gt;#3504&lt;/a&gt;).
Related: &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5961&quot;&gt;#5961&lt;/a&gt; and
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5992&quot;&gt;#5992&lt;/a&gt; (pack-tier spelling), &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6048&quot;&gt;#6048&lt;/a&gt; (implementation),
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/6046&quot;&gt;#6046&lt;/a&gt; (&lt;code dir=&quot;auto&quot;&gt;requires_core&lt;/code&gt;, another &lt;code dir=&quot;auto&quot;&gt;pack.yaml&lt;/code&gt; field).&lt;/p&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;A Charter Pack’s level is never declared. It is inferred from how the pack was wired in:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;the built-in pack is the directory &lt;code dir=&quot;auto&quot;&gt;resolve_pack_root(&quot;built-in&quot;)&lt;/code&gt; finds;&lt;/li&gt;
&lt;li&gt;an org pack is a directory listed under &lt;code dir=&quot;auto&quot;&gt;charter_packs.org.packs&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;a project pack is the directory under &lt;code dir=&quot;auto&quot;&gt;.kittify/charter-packs/&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Only the built-in pack has a &lt;code dir=&quot;auto&quot;&gt;pack.yaml&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;PackDescriptor&lt;/code&gt;: &lt;code dir=&quot;auto&quot;&gt;pack_id&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;pack_version&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;parent_pack&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;name&lt;/code&gt;). Org packs such as &lt;code dir=&quot;auto&quot;&gt;qa&lt;/code&gt; are recognised by the files they hold
(&lt;code dir=&quot;auto&quot;&gt;org-charter.yaml&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;drg/fragment.yaml&lt;/code&gt;). The validator infers what to expect from those files.&lt;/p&gt;
&lt;p&gt;That inference broke as soon as packs started living outside the repository that uses them.
Seeding the built-in pack into &lt;code dir=&quot;auto&quot;&gt;spec-kitty-open-packs&lt;/code&gt; (#32) showed it:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;placed under &lt;code dir=&quot;auto&quot;&gt;packs/&lt;/code&gt;, the built-in pack was registered as an org pack by that repository’s CI;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;doctor charter-packs&lt;/code&gt; then failed, because it had no &lt;code dir=&quot;auto&quot;&gt;drg/fragment.yaml&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;it also shadowed the CLI’s own built-in layer.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Nothing in the pack said what it was, so nothing could refuse the mistake.&lt;/p&gt;
&lt;p&gt;The level names themselves have no single owner either. Code spells the built-in level both
&lt;code dir=&quot;auto&quot;&gt;&quot;built-in&quot;&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;&quot;builtin&quot;&lt;/code&gt; (#5961, #5992), and about 93 source files carry the layer literals.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;A pack must say what it is, so a wrong placement is refused by name rather than discovered
by a downstream failure.&lt;/li&gt;
&lt;li&gt;Reuse the vocabulary the product already speaks (config keys, glossary, paths). Do not add
a third one.&lt;/li&gt;
&lt;li&gt;One authority for the level names, which #5961 needs anyway.&lt;/li&gt;
&lt;li&gt;Avoid terms that already mean something else: “root pack” already means a pack with no
&lt;code dir=&quot;auto&quot;&gt;parent_pack&lt;/code&gt;.&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;Field name:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;pack_level&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;pack_tier&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;layer&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Values:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;built-in&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;org&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;project&lt;/code&gt; (A); &lt;code dir=&quot;auto&quot;&gt;core&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;org&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;project&lt;/code&gt; (B);
&lt;code dir=&quot;auto&quot;&gt;base&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;organization&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;project&lt;/code&gt; (C); &lt;code dir=&quot;auto&quot;&gt;root&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;organisational&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;repository&lt;/code&gt;
(the first proposal).&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen: &lt;code dir=&quot;auto&quot;&gt;pack_level&lt;/code&gt; with values &lt;code dir=&quot;auto&quot;&gt;built-in&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;org&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;project&lt;/code&gt;.&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Every Charter Pack has a &lt;code dir=&quot;auto&quot;&gt;pack.yaml&lt;/code&gt;, and it declares &lt;code dir=&quot;auto&quot;&gt;pack_level&lt;/code&gt;.&lt;/strong&gt; It is a required
field of &lt;code dir=&quot;auto&quot;&gt;PackDescriptor&lt;/code&gt; and must be one of &lt;code dir=&quot;auto&quot;&gt;built-in&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;org&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;project&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;pack_id&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;pack_version&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;parent_pack&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;name&lt;/code&gt; are unchanged.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The level names have one authority.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;kernel.pack_tiers&lt;/code&gt; is the single authority for the
three level names; the descriptor reuses its &lt;code dir=&quot;auto&quot;&gt;PackTier&lt;/code&gt; Literal — no second enum is
introduced. Every layer literal, including the former no-hyphen &lt;code dir=&quot;auto&quot;&gt;&quot;builtin&quot;&lt;/code&gt; provenance
spelling (#5961, #5992), derives from it (this mission performs that fold).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Loading refuses a mismatch.&lt;/strong&gt; A pack whose declared &lt;code dir=&quot;auto&quot;&gt;pack_level&lt;/code&gt; disagrees with where it
was configured is refused with &lt;code dir=&quot;auto&quot;&gt;PACK_LEVEL_MISMATCH&lt;/code&gt;, naming the file, the declared level
and the configured one. A &lt;code dir=&quot;auto&quot;&gt;pack.yaml&lt;/code&gt; without the field is refused with
&lt;code dir=&quot;auto&quot;&gt;PACK_LEVEL_MISSING&lt;/code&gt;, after the migration window described below.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The validator branches on the declared level&lt;/strong&gt;, not on the files it finds. For example,
&lt;code dir=&quot;auto&quot;&gt;drg/fragment.yaml&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;org-charter.yaml&lt;/code&gt; are expected of &lt;code dir=&quot;auto&quot;&gt;org&lt;/code&gt; packs, and the sharded
&lt;code dir=&quot;auto&quot;&gt;*.graph.yaml&lt;/code&gt; plus a generated &lt;code dir=&quot;auto&quot;&gt;pack-manifest.yaml&lt;/code&gt; of the &lt;code dir=&quot;auto&quot;&gt;built-in&lt;/code&gt; pack.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Migration.&lt;/strong&gt; An upgrade migration writes &lt;code dir=&quot;auto&quot;&gt;pack.yaml&lt;/code&gt; (minting a &lt;code dir=&quot;auto&quot;&gt;pack_id&lt;/code&gt;) with
&lt;code dir=&quot;auto&quot;&gt;pack_level: project&lt;/code&gt; for an existing project pack. For one release, an org pack without a
&lt;code dir=&quot;auto&quot;&gt;pack.yaml&lt;/code&gt; loads with a deprecation warning that names the file to add. After that it is
refused.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Rejected:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;root&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;organisational&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;repository&lt;/code&gt;.&lt;/strong&gt; “root pack” already means a pack with no
&lt;code dir=&quot;auto&quot;&gt;parent_pack&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;organisational&lt;/code&gt; fails the US-spelling docs gate and disagrees with the
config key &lt;code dir=&quot;auto&quot;&gt;org&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;repository&lt;/code&gt; clashes with &lt;code dir=&quot;auto&quot;&gt;project&lt;/code&gt; and with “repository root checkout”.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;pack_tier&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;layer&lt;/code&gt;.&lt;/strong&gt; “Tier” is overloaded (model tiers, tiered rigour). &lt;code dir=&quot;auto&quot;&gt;layer&lt;/code&gt; is
overloaded by the architectural layer rules.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Values B and C.&lt;/strong&gt; Both rename what config, paths and the glossary already say.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;A mis-placed pack is refused at load with a named code. The open-packs layout question is
settled: &lt;code dir=&quot;auto&quot;&gt;built-in/&lt;/code&gt; can live at &lt;code dir=&quot;auto&quot;&gt;packs/built-in/&lt;/code&gt;, and open-packs CI registers only packs
that declare &lt;code dir=&quot;auto&quot;&gt;org&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;#5961 gets its single owner for the tier spelling.&lt;/li&gt;
&lt;li&gt;The validator’s expectations become explicit per level.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Every org and project pack must gain a &lt;code dir=&quot;auto&quot;&gt;pack.yaml&lt;/code&gt;. That needs a migration for consumer
project packs and a deprecation window for org packs.&lt;/li&gt;
&lt;li&gt;This is a &lt;code dir=&quot;auto&quot;&gt;PackDescriptor&lt;/code&gt; schema change. Bundle it with &lt;code dir=&quot;auto&quot;&gt;requires_core&lt;/code&gt; (#6046) so pack
authors meet one schema bump, not two.&lt;/li&gt;
&lt;li&gt;The open-packs layout fix waits for a core release that ships the field.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;provenance-spelling-fold-retires-nfr-003&quot;&gt;Provenance-spelling fold (retires NFR-003)&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;This mission &lt;strong&gt;retires the NFR-003 provenance-spelling freeze&lt;/strong&gt;. The earlier carve-out
language (in &lt;code dir=&quot;auto&quot;&gt;kernel.pack_tiers&lt;/code&gt;, the pack-tier gate docstring, and the first draft of this
ADR) asserted that the fold had not happened and that two spellings — &lt;code dir=&quot;auto&quot;&gt;&quot;built-in&quot;&lt;/code&gt; (tier
token) and &lt;code dir=&quot;auto&quot;&gt;&quot;builtin&quot;&lt;/code&gt; (provenance/layer/rank) — coexisted. That freeze is lifted: the two
vocabularies become one. Every layer literal now derives from &lt;code dir=&quot;auto&quot;&gt;kernel.pack_tiers&lt;/code&gt;, which
strengthens single-authority rather than weakening it.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Cross-version persisted-value note.&lt;/strong&gt; The fold changes the serialized provenance spelling
from &lt;code dir=&quot;auto&quot;&gt;&quot;builtin&quot;&lt;/code&gt; to &lt;code dir=&quot;auto&quot;&gt;&quot;built-in&quot;&lt;/code&gt;. This is verified safe for the current CLI: no read-back path
compares a loaded value to the string &lt;code dir=&quot;auto&quot;&gt;&quot;builtin&quot;&lt;/code&gt;, regenerated JSON and the dogfood
&lt;code dir=&quot;auto&quot;&gt;pack-manifest.yaml&lt;/code&gt; self-heal on the next write, and nothing persists the old spelling as a
lookup key. The only theoretical edge is an &lt;em&gt;older&lt;/em&gt; CLI reading a new-spelling artifact after
an upgrade; no such mixed-version read path is exercised today, so no data migration ships.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;charter pack validate&lt;/code&gt; refuses a pack without &lt;code dir=&quot;auto&quot;&gt;pack_level&lt;/code&gt; once the window closes, and
refuses one whose level disagrees with its configured position.&lt;/li&gt;
&lt;li&gt;An architectural test pins that every layer literal in &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt; derives from the single
&lt;code dir=&quot;auto&quot;&gt;kernel.pack_tiers&lt;/code&gt; authority (the &lt;code dir=&quot;auto&quot;&gt;PackTier&lt;/code&gt; Literal), not a second enum.&lt;/li&gt;
&lt;li&gt;In open-packs, the built-in pack moves to &lt;code dir=&quot;auto&quot;&gt;packs/built-in/&lt;/code&gt; with &lt;code dir=&quot;auto&quot;&gt;pack_level: built-in&lt;/code&gt;, and
&lt;code dir=&quot;auto&quot;&gt;validate-packs.sh&lt;/code&gt; registers only &lt;code dir=&quot;auto&quot;&gt;pack_level: org&lt;/code&gt; packs.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;amendment-2026-10-11&quot;&gt;Amendment 2026-10-11&lt;/h2&gt;
&lt;p&gt;Decision 3 says loading refuses a level mismatch “where it was configured”. That is
enforced at load time &lt;strong&gt;only for org packs&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;load_org_pack&lt;/code&gt; reads &lt;code dir=&quot;auto&quot;&gt;pack.yaml&lt;/code&gt; through
&lt;code dir=&quot;auto&quot;&gt;load_pack_descriptor&lt;/code&gt; and refuses a declared level other than &lt;code dir=&quot;auto&quot;&gt;org&lt;/code&gt;, and refuses an
unreadable or schema-invalid &lt;code dir=&quot;auto&quot;&gt;pack.yaml&lt;/code&gt;). For the built-in and project positions nothing refuses at load. The mismatch check
lives in the validator (&lt;code dir=&quot;auto&quot;&gt;validate_pack(..., expected_level=...)&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;check_pack_level&lt;/code&gt;), which a position-aware caller must opt into; at the time of this
amendment no production caller (including &lt;code dir=&quot;auto&quot;&gt;charter pack validate&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor charter-packs&lt;/code&gt;) passes &lt;code dir=&quot;auto&quot;&gt;expected_level&lt;/code&gt;, so on a bare path the
mismatch check is skipped fail-closed and only &lt;code dir=&quot;auto&quot;&gt;PACK_LEVEL_MISSING&lt;/code&gt; and the schema
checks run. This amendment records where the check runs today; it adds no load-time
enforcement. Wiring a position into those callers is follow-up work.&lt;/p&gt;</content>
</entry>
