<?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-5-operator-config-env-expansion-seam/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-08-16-5-operator-config-env-expansion-seam/</id>
  <title>Operator configuration resolves through one kernel env-expansion seam; committed provenance stores tokens</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-5-operator-config-env-expansion-seam/"/>
  <summary>One kernel ${VAR} expander plus a two-tier .kitty.env seed the process env; committed provenance stores SPEC_KITTY_* tokens, never resolved paths.</summary>
  <content type="html">&lt;span id=&quot;operator-configuration-resolves-through-one-kernel-env-expansion-seam-committed-provenance-stores-tokens&quot;&gt;&lt;/span&gt;
&lt;p&gt;&lt;strong&gt;Filename:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;2026-08-16-5-operator-config-env-expansion-seam.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; Stijn Dejongh (operator); design squad (architect-alphonso design + paula-patterns adversarial review)&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt; Epic #3493 (children #3494 portable provenance, #3495 &lt;code dir=&quot;auto&quot;&gt;.kitty.env&lt;/code&gt;); mission &lt;code dir=&quot;auto&quot;&gt;operator-config-ergonomics-01M04YK8&lt;/code&gt;; related #3047, #3381, #2519, #3251, #3022&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;Three operator-facing config frictions shared one root cause: the CLI resolved environment
and directory state through roughly 88 scattered &lt;code dir=&quot;auto&quot;&gt;os.environ.get&lt;/code&gt; reads with no single
authority, and it committed machine-specific absolute paths into governance files.&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Charter/doctrine catalog &lt;code dir=&quot;auto&quot;&gt;source_path&lt;/code&gt; was emitted as an absolute machine path (the
&lt;code dir=&quot;auto&quot;&gt;_trim_source_path&lt;/code&gt; normalizer keyed on the dead &lt;code dir=&quot;auto&quot;&gt;src/doctrine/&lt;/code&gt; marker after built-in
doctrine moved to &lt;code dir=&quot;auto&quot;&gt;packs/built-in/&lt;/code&gt;). Repo-relative was &lt;em&gt;already&lt;/em&gt; not install-mode
invariant — an installed wheel emits &lt;code dir=&quot;auto&quot;&gt;site-packages/...&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Opting into hosted SaaS sync required hand-exporting &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_ENABLE_SAAS_SYNC&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_SAAS_URL&lt;/code&gt;, and tokens on every shell — there was no config-file home.&lt;/li&gt;
&lt;li&gt;There was no smooth way to consume rc/internal builds (see the companion
&lt;a href=&quot;/adr/3.x/2026-08-16-4-rc-release-channel/&quot;&gt;rc release-channel ADR&lt;/a&gt;).&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;We needed one coherent resolution seam that makes committed provenance portable across all
install modes, gives operators a single file for their knobs, and does so without violating
the kernel’s layering floor or the DR-1 single-read invariant.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Committed governance files must be byte-identical across editable checkout, installed
wheel, and future externally-extracted packs (#3022).&lt;/li&gt;
&lt;li&gt;Operators must configure path/sync/beta knobs once, not per shell.&lt;/li&gt;
&lt;li&gt;DR-1: exactly one env read per var at the kernel floor; no second resolver.&lt;/li&gt;
&lt;li&gt;Layering: &lt;code dir=&quot;auto&quot;&gt;kernel ← doctrine ← charter ← specify_cli&lt;/code&gt;; kernel may gain no upward imports.&lt;/li&gt;
&lt;li&gt;Preserve the deliberate dual-root split &lt;code dir=&quot;auto&quot;&gt;.kittify&lt;/code&gt; (assets) vs &lt;code dir=&quot;auto&quot;&gt;.spec-kitty&lt;/code&gt; (state).&lt;/li&gt;
&lt;li&gt;Secrets must never be committed, slurped into agent context, or printed.&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.&lt;/strong&gt; Repo-relative provenance only; no env-file (narrow bug fix).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;B.&lt;/strong&gt; Env-templated provenance (&lt;code dir=&quot;auto&quot;&gt;${SPEC_KITTY_PACKS_ROOT}/...&lt;/code&gt;) with NO central expander.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;C. (chosen)&lt;/strong&gt; One kernel &lt;code dir=&quot;auto&quot;&gt;${VAR}&lt;/code&gt; expander + token provenance + a two-tier &lt;code dir=&quot;auto&quot;&gt;.kitty.env&lt;/code&gt;
(located via the existing &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_HOME&lt;/code&gt;) seeded into &lt;code dir=&quot;auto&quot;&gt;os.environ&lt;/code&gt; by a pre-import shim.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;D.&lt;/strong&gt; Introduce a new &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_CONFIG_HOME&lt;/code&gt; locator var for the env-file.&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: “C”&lt;/strong&gt;, because it is the only option that makes committed provenance
invariant across all install modes while retiring the scattered-read problem behind one
authority, and it reuses the token-preservation pattern the codebase had already proved for
org-pack &lt;code dir=&quot;auto&quot;&gt;local_path&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;Concretely, as shipped:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Committed provenance stores the token&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;${SPEC_KITTY_PACKS_ROOT}/built-in/...&lt;/code&gt;, never a
resolved path. &lt;code dir=&quot;auto&quot;&gt;.kitty.env&lt;/code&gt; may set &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_PACKS_ROOT&lt;/code&gt; as a per-machine &lt;em&gt;resolution&lt;/em&gt;
override; because provenance stores the symbol, the machine path is never baked in. The
emit side runs through one shared path→token normalizer consumed by both carriers — the
charter catalog source (&lt;code dir=&quot;auto&quot;&gt;src/charter/compiler.py&lt;/code&gt;) and the agent-profile manifest source
(&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/tool_surface/profiles/projection.py&lt;/code&gt;) — so the two emit sites cannot
drift. An idempotent heal migration
(&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/migrations/m_3_2_7_heal_provenance_paths.py&lt;/code&gt;) rewrites existing
absolute paths in already-committed &lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;agent_profiles_manifest.json&lt;/code&gt;, and a
doctor sibling (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/_provenance_doctor.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;doctor provenance&lt;/code&gt;)
flags any leak with a heal hint.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;One expander at the kernel floor&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;src/kernel/env_expand.py&lt;/code&gt;): &lt;code dir=&quot;auto&quot;&gt;expand_env_template(raw, *, inject_defaults)&lt;/code&gt; — fail-loud for resolution fields, default-inject for
provenance/config fields. &lt;code dir=&quot;auto&quot;&gt;get_packs_root_default()&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/kernel/paths.py&lt;/code&gt;) =
&lt;code dir=&quot;auto&quot;&gt;get_built_in_pack_root().parent&lt;/code&gt; (the token names the parent; the resolver returns the
&lt;code dir=&quot;auto&quot;&gt;built-in&lt;/code&gt; child). &lt;code dir=&quot;auto&quot;&gt;doctrine.drg.org_pack_config&lt;/code&gt; delegates the pure transform and
detection primitives (not the raising composition), preserving its own
&lt;code dir=&quot;auto&quot;&gt;OrgPackEnvVarUnsetError&lt;/code&gt; exception type.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;.kitty.env&lt;/code&gt; is the one home&lt;/strong&gt; for path (excl. &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_HOME&lt;/code&gt;) / sync / beta knobs.
Two tiers: user-global &lt;code dir=&quot;auto&quot;&gt;${SPEC_KITTY_HOME}/.kitty.env&lt;/code&gt; (the state root — &lt;code dir=&quot;auto&quot;&gt;.spec-kitty&lt;/code&gt; on
POSIX, &lt;code dir=&quot;auto&quot;&gt;%LOCALAPPDATA%\spec-kitty&lt;/code&gt; on Windows) overridden by &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;repo&gt;/.kittify/.kitty.env&lt;/code&gt;.
&lt;code dir=&quot;auto&quot;&gt;config.yaml&lt;/code&gt; carries one expansion &lt;code dir=&quot;auto&quot;&gt;env_file: ${SPEC_KITTY_HOME}/.kitty.env&lt;/code&gt;, resolved
once at bootstrap via a targeted top-level-key scan (not a full YAML/model load, so it
cannot collide with &lt;code dir=&quot;auto&quot;&gt;org_pack_config.PackRegistry&lt;/code&gt;’s &lt;code dir=&quot;auto&quot;&gt;extra=&quot;forbid&quot;&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;doctrine.org&lt;/code&gt;
section). &lt;strong&gt;Reusing &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_HOME&lt;/code&gt; as the locator&lt;/strong&gt; (option D rejected) avoids an
invented var and any bootstrap circularity, since the env file never &lt;em&gt;sets&lt;/em&gt; &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_HOME&lt;/code&gt;
— a line defining it inside the file is dropped with a &lt;code dir=&quot;auto&quot;&gt;UserWarning&lt;/code&gt; (locator-recursion
guard).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Loaded by a pre-import shim&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/bootstrap/env_file.py&lt;/code&gt;, invoked as the
very first statements of &lt;code dir=&quot;auto&quot;&gt;specify_cli/__init__.py&lt;/code&gt; — before that module’s own
&lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_TEST_MODE&lt;/code&gt; read), &lt;code dir=&quot;auto&quot;&gt;os.environ.setdefault&lt;/code&gt; so real env always wins. Tiers are
merged &lt;code dir=&quot;auto&quot;&gt;{**home, **repo}&lt;/code&gt; first, then exactly one &lt;code dir=&quot;auto&quot;&gt;setdefault&lt;/code&gt; pass — real-env &gt;
per-repo &gt; home. The loader is stdlib + &lt;code dir=&quot;auto&quot;&gt;kernel&lt;/code&gt; only, no &lt;code dir=&quot;auto&quot;&gt;specify_cli.core&lt;/code&gt; import, kept
off the startup critical path (NFR-001).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fail policy&lt;/strong&gt;: an absent &lt;code dir=&quot;auto&quot;&gt;.kitty.env&lt;/code&gt; warns and continues (the default state for almost
every project); a present-but-unreadable file fails loud, naming the path, because it
gates auth. A malformed &lt;code dir=&quot;auto&quot;&gt;KEY=VALUE&lt;/code&gt; line is skipped with a debug log.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Provisioning&lt;/strong&gt;: an idempotent migration
(&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/migrations/m_3_2_8_provision_kitty_env.py&lt;/code&gt;) creates the per-repo
scaffold, registers the &lt;code dir=&quot;auto&quot;&gt;env_file&lt;/code&gt; pointer, and adds &lt;code dir=&quot;auto&quot;&gt;.gitignore&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;.claudeignore&lt;/code&gt; rules —
seeding only values already set in the environment/legacy config, &lt;strong&gt;never&lt;/strong&gt;
&lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_PACKS_ROOT&lt;/code&gt; (it would silently flip the &lt;code dir=&quot;auto&quot;&gt;kernel/paths.py&lt;/code&gt; TEMPLATE_ROOT
presence gate), and never a secret &lt;em&gt;value&lt;/em&gt; (secret-shaped vars are emitted as a commented,
blank template line). A doctor sibling
(&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/_env_file_doctor.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;doctor env-file&lt;/code&gt;) reports presence,
tier, and ignore coverage — values never printed for anything off the fail-closed
printable-var allowlist (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/core/secret_redaction.py&lt;/code&gt;).&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;Committed charter/manifest provenance is identical across editable/wheel/extracted layouts;
a regression test forbids any absolute pack path in committed artifacts, including the
&lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_PACKS_ROOT=&amp;#x3C;abs&gt;&lt;/code&gt;-exported re-bake case.&lt;/li&gt;
&lt;li&gt;Operators configure once; the ~88 downstream reads work unchanged against the seeded env.&lt;/li&gt;
&lt;li&gt;One expansion authority; kernel keeps DR-1 and gains no upward imports.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Provenance tokens are less human-legible in committed YAML than a literal path (accepted:
provenance is metadata; matches the existing org-pack convention).&lt;/li&gt;
&lt;li&gt;An always-set &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_PACKS_ROOT&lt;/code&gt; flips the &lt;code dir=&quot;auto&quot;&gt;kernel/paths.py&lt;/code&gt; TEMPLATE_ROOT presence
gate — documented and regression-tested; the provision migration categorically excludes
seeding it for exactly this reason.&lt;/li&gt;
&lt;li&gt;Mixing secrets and portable knobs in one file forces the whole file to be treated as secret
(mitigated: fully gitignored + &lt;code dir=&quot;auto&quot;&gt;.claudeignore&lt;/code&gt;d + a redaction allowlist).&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;A pre-import shim is a new, tiny startup surface; kept stdlib-only for the TAB-completion
performance budget.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;Success signals, all met at ship time: (1) a portable-provenance regression test stays green
across editable and wheel installs; (2) &lt;code dir=&quot;auto&quot;&gt;spec-kitty sync opt-in&lt;/code&gt; works after a single
&lt;code dir=&quot;auto&quot;&gt;.kitty.env&lt;/code&gt; edit with no shell exports; (3) &lt;code dir=&quot;auto&quot;&gt;doctor env-file&lt;/code&gt; reports env-file health and
never prints token values; (4) architectural tests confirm the kernel has no upward import and
the home-owner pins are undisturbed.&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-repo-relative-provenance-no-env-file&quot;&gt;A. Repo-relative provenance, no env-file&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; smallest change. &lt;strong&gt;Cons:&lt;/strong&gt; not install-mode invariant (wheel → site-packages
absolute); breaks under #3022; does nothing for SaaS opt-in ergonomics.&lt;/p&gt;
&lt;h3 id=&quot;b-env-templated-provenance-no-expander&quot;&gt;B. Env-templated provenance, no expander&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; portable string. &lt;strong&gt;Cons:&lt;/strong&gt; nothing expands these fields without the expander — the
token renders literally and is unresolvable; strictly worse than a concrete path absent the
expander.&lt;/p&gt;
&lt;h3 id=&quot;c-kernel-expander--token-provenance--two-tier-kittyenv-chosen&quot;&gt;C. Kernel expander + token provenance + two-tier &lt;code dir=&quot;auto&quot;&gt;.kitty.env&lt;/code&gt; (chosen)&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; install-mode invariant; one authority; reuses a proven pattern; solves all three
frictions coherently. &lt;strong&gt;Cons:&lt;/strong&gt; more moving parts (expander, shim, two migrations); token
legibility.&lt;/p&gt;
&lt;h3 id=&quot;d-new-spec_kitty_config_home-locator-var&quot;&gt;D. New &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_CONFIG_HOME&lt;/code&gt; locator var&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; explicit config-home. &lt;strong&gt;Cons:&lt;/strong&gt; invents a var that collides conceptually with
&lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_HOME&lt;/code&gt;; adds a bootstrap circularity surface. Rejected in favour of reusing HOME.&lt;/p&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Design source: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/operator-config-ergonomics-01M04YK8/design-record.md&lt;/code&gt; +
&lt;code dir=&quot;auto&quot;&gt;spec.md&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;plan.md&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;research.md&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Companion: &lt;a href=&quot;/adr/3.x/2026-08-16-4-rc-release-channel/&quot;&gt;ADR: Default-off rc release channel&lt;/a&gt;
(T3 / #3496), scoped against the rc-cadence producer half in #3047.&lt;/li&gt;
&lt;li&gt;Architecture: &lt;a href=&quot;/context/team-kitty/&quot;&gt;Team Kitty&lt;/a&gt;; the end-to-end hosted-sync flow
this seam underpinned was removed in #6164 (code preserved in &lt;code dir=&quot;auto&quot;&gt;spec-kitty/event-router&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;Cross-refs: #3251 (PACKS_ROOT fail-closed), #3381 (auto-run migration lesson), #2519.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
