<?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-08-16-3-spec-kitty-internal-is-a-public-org-pack-not-force-shipped/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-08-16-3-spec-kitty-internal-is-a-public-org-pack-not-force-shipped/</id>
  <title>ADR: spec-kitty-internal Is One Public Org Pack, Consumed via the Org Tier, Never Force-Shipped</title>
  <updated>2026-08-16T00: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-08-16-3-spec-kitty-internal-is-a-public-org-pack-not-force-shipped/"/>
  <summary>The internal maintainer pack is one public artifact (open-packs catalog #16), consumed as an org-tier pack and kept out of the core wheel — not secret, just not shipped.</summary>
  <content type="html">&lt;h2 id=&quot;spec-kitty-internal-is-one-public-org-pack-consumed-via-the-org-tier-never-force-shipped&quot;&gt;spec-kitty-internal Is One Public Org Pack, Consumed via the Org Tier, Never Force-Shipped&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Filename:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;2026-08-16-3-spec-kitty-internal-is-a-public-org-pack-not-force-shipped.md&lt;/code&gt;&lt;/p&gt;
&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-08-16&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Maintainer&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt; Internal doctrine-pack initiative. The open-packs catalog proposal already scopes &lt;code dir=&quot;auto&quot;&gt;spec-kitty-internal&lt;/code&gt; as base pack #16 (public, “so contributors and downstream teams can adopt or study it”), grounded in core #2196. A repo-local &lt;code dir=&quot;auto&quot;&gt;packs/internal/&lt;/code&gt; first step was built on branch &lt;code dir=&quot;auto&quot;&gt;feat/internal-pack&lt;/code&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 wants an &lt;strong&gt;internal&lt;/strong&gt; doctrine pack + org charter that governs how the
core team works on the project itself (PR-landing, tracker processing, keeping main
honest, the internal glossary), stated as “&lt;strong&gt;not shipped to our consumers&lt;/strong&gt;” — yet
also “&lt;strong&gt;built in the open&lt;/strong&gt;” as “an example for our user-base.” Read literally these
pull in opposite directions: private vs. public.&lt;/p&gt;
&lt;p&gt;Separately, the open-packs catalog already scopes a pack for exactly this slot —
&lt;code dir=&quot;auto&quot;&gt;spec-kitty-internal&lt;/code&gt; (base pack #16), framed as &lt;strong&gt;public and studyable&lt;/strong&gt;. Building a
second, private pack would &lt;strong&gt;duplicate&lt;/strong&gt; #16 and its &lt;code dir=&quot;auto&quot;&gt;org-charter.yaml&lt;/code&gt;, and force a
policy for what is secret vs. public.&lt;/p&gt;
&lt;p&gt;We must decide whether &lt;code dir=&quot;auto&quot;&gt;spk-internal&lt;/code&gt; is a distinct private artifact or the same
public pack #16, and what “not shipped to consumers” actually constrains.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Avoid duplicating catalog pack #16 and its charter.&lt;/li&gt;
&lt;li&gt;Reconcile “build in the open” with “not shipped to consumers”.&lt;/li&gt;
&lt;li&gt;Keep the public built-in product context clean — maintainer doctrine must not flood
every consumer’s LLM session.&lt;/li&gt;
&lt;li&gt;Reuse the already-built org-tier consumption path (no new plumbing).&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;A — Distinct private pack:&lt;/strong&gt; a maintainer-only pack that never appears in the public
catalog.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;B — One public org pack, not force-shipped (chosen):&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;spk-internal&lt;/code&gt; &lt;strong&gt;is&lt;/strong&gt; catalog
pack #16 — authored in the open in open-packs (studyable), consumed by SK-Inc projects
as an &lt;strong&gt;org-tier&lt;/strong&gt; pack via &lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt;, and &lt;strong&gt;never force-included&lt;/strong&gt; in the
core consumer wheel. “Not shipped” == not in the wheel; &lt;strong&gt;not&lt;/strong&gt; == secret.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;C — Ship it like built-in:&lt;/strong&gt; force-include the internal pack in the wheel alongside
&lt;code dir=&quot;auto&quot;&gt;packs/built-in/&lt;/code&gt;.&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 option: “B — One public org pack, not force-shipped.”&lt;/strong&gt; There is one artifact,
not two: the open-packs catalog pack #16 &lt;code dir=&quot;auto&quot;&gt;spec-kitty-internal&lt;/code&gt;. It is developed publicly
(anyone may study or adopt it), and SK-Inc projects consume it as an &lt;strong&gt;org-tier&lt;/strong&gt; pack —
the merged org-pack loader, &lt;code dir=&quot;auto&quot;&gt;subdir:&lt;/code&gt; support, and &lt;code dir=&quot;auto&quot;&gt;${ENV}&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;~&lt;/code&gt; indirection already make
this a config entry, not new code. It is deliberately &lt;strong&gt;excluded from the core wheel&lt;/strong&gt;:
&lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt;’s &lt;code dir=&quot;auto&quot;&gt;force-include&lt;/code&gt; and sdist globs are scoped to &lt;code dir=&quot;auto&quot;&gt;packs/built-in/&lt;/code&gt; so a
consumer’s default install never inherits maintainer doctrine, keeping their context clean.
This precisely reconciles “built in the open” (public source) with “not shipped to
consumers” (absent from the distributed artifact).&lt;/p&gt;
&lt;p&gt;The repo-local &lt;code dir=&quot;auto&quot;&gt;packs/internal/&lt;/code&gt; created as the first step is a &lt;strong&gt;transitional staging
location&lt;/strong&gt; inside the core repo; its permanent home is the open-packs catalog (per the
companion ADR &lt;code dir=&quot;auto&quot;&gt;2026-08-16-2&lt;/code&gt;, which makes open-packs the source of truth for pack content).&lt;/p&gt;
&lt;p&gt;Option A is rejected (duplicates #16, needs a secrecy policy for no real benefit — the
content is not sensitive, only context-noisy). Option C is rejected (pollutes every
consumer’s default context with maintainer-only doctrine — the exact problem the pack
system exists to solve).&lt;/p&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;One artifact, one &lt;code dir=&quot;auto&quot;&gt;org-charter.yaml&lt;/code&gt;; no duplication.&lt;/li&gt;
&lt;li&gt;Consumers keep a clean default context; SK-Inc projects opt in explicitly.&lt;/li&gt;
&lt;li&gt;Reuses the org tier — a config entry, not new plumbing.&lt;/li&gt;
&lt;li&gt;The pack is public and studyable, serving as the worked example for the user base.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;“Not shipped” is enforced only by the packaging-scope guard; a future whole-tree
&lt;code dir=&quot;auto&quot;&gt;force-include&lt;/code&gt; regression would re-leak it. Mitigated by
&lt;code dir=&quot;auto&quot;&gt;tests/cross_cutting/packaging/test_packaging_safety.py&lt;/code&gt; (tightened to &lt;code dir=&quot;auto&quot;&gt;packs/built-in/&lt;/code&gt;
with an explicit “internal must not ship” assertion).&lt;/li&gt;
&lt;li&gt;SK-Inc projects must each register the org pack (via &lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt;, or a seeded
&lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt; default) — there is no auto-broadcast to “all projects” today.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;The internal pack’s content overlaps maintainer doctrine already in built-in; the pack
&lt;strong&gt;references&lt;/strong&gt; those via DRG edges rather than re-authoring them.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;Success = (1) exactly one &lt;code dir=&quot;auto&quot;&gt;spec-kitty-internal&lt;/code&gt; pack exists (open-packs #16); (2) it never
appears in a released wheel (guard test green; a real wheel build shows 0 &lt;code dir=&quot;auto&quot;&gt;packs/internal/&lt;/code&gt;
files while &lt;code dir=&quot;auto&quot;&gt;packs/built-in/&lt;/code&gt; ships fully — verified for the first-step scaffold); (3)
SK-Inc projects load it as a healthy org layer (&lt;code dir=&quot;auto&quot;&gt;doctor doctrine&lt;/code&gt; reports it with resolved
edges, no dangling/collisions — verified for the first-step scaffold).&lt;/p&gt;
&lt;h2 id=&quot;pros-and-cons-of-the-options&quot;&gt;Pros and Cons of the Options&lt;/h2&gt;
&lt;h3 id=&quot;a--distinct-private-pack&quot;&gt;A — Distinct private pack&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; Clean secrecy story.
&lt;strong&gt;Cons:&lt;/strong&gt; Duplicates #16 + its charter; needs a private-vs-public policy; no real benefit
since the content is not sensitive.&lt;/p&gt;
&lt;h3 id=&quot;b--one-public-org-pack-not-force-shipped&quot;&gt;B — One public org pack, not force-shipped&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; No duplication; clean consumer context; reuses org tier; public/studyable.
&lt;strong&gt;Cons:&lt;/strong&gt; Non-shipment relies on a packaging guard; no auto-broadcast to all SK-Inc projects.&lt;/p&gt;
&lt;h3 id=&quot;c--ship-it-like-built-in&quot;&gt;C — Ship it like built-in&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; Auto-present everywhere.
&lt;strong&gt;Cons:&lt;/strong&gt; Floods every consumer’s context with maintainer-only doctrine — defeats the pack
system’s purpose.&lt;/p&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;First step: &lt;code dir=&quot;auto&quot;&gt;packs/internal/&lt;/code&gt; scaffold on branch &lt;code dir=&quot;auto&quot;&gt;feat/internal-pack&lt;/code&gt; (glossary_pack +
&lt;code dir=&quot;auto&quot;&gt;landing-contributor-prs&lt;/code&gt; procedure + &lt;code dir=&quot;auto&quot;&gt;drg/fragment.yaml&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;org-charter.yaml&lt;/code&gt;), packaging
scoped to &lt;code dir=&quot;auto&quot;&gt;packs/built-in&lt;/code&gt;, guard test tightened.&lt;/li&gt;
&lt;li&gt;Companion decision (source of truth + re-vendor): &lt;code dir=&quot;auto&quot;&gt;2026-08-16-2-open-packs-is-source-of-truth-for-built-in-doctrine.md&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Catalog: &lt;code dir=&quot;auto&quot;&gt;spec-kitty-open-packs/docs/packs/catalog-proposal.md&lt;/code&gt; (pack #16).&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;amendment-2026-10-19--cross-reference-6451&quot;&gt;Amendment (2026-10-19 — cross-reference, #6451)&lt;/h2&gt;
&lt;p&gt;No decision change. &lt;code dir=&quot;auto&quot;&gt;packs/internal/&lt;/code&gt; is now pinned and fetched like &lt;code dir=&quot;auto&quot;&gt;packs/built-in/&lt;/code&gt;: its
source lives in &lt;code dir=&quot;auto&quot;&gt;spec-kitty-open-packs&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;packs/internal&lt;/code&gt;), core holds only
&lt;code dir=&quot;auto&quot;&gt;packs/internal.source.yaml&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;make sync-packs&lt;/code&gt; places the tree. It is still never
shipped: the wheel and sdist exclude it and &lt;code dir=&quot;auto&quot;&gt;tests/cross_cutting/packaging/test_packaging_safety.py&lt;/code&gt;
is extended to cover the fetched tree and the &lt;code dir=&quot;auto&quot;&gt;source.yaml&lt;/code&gt; pins. See the 2026-10-19 amendment to
&lt;code dir=&quot;auto&quot;&gt;2026-08-16-2-open-packs-is-source-of-truth-for-built-in-doctrine.md&lt;/code&gt;.&lt;/p&gt;</content>
</entry>
