<?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-18-1-monorepo-charter-scope/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-05-18-1-monorepo-charter-scope/</id>
  <title>ADR-8: Monorepo charter scope via `CharterScope` abstraction</title>
  <updated>2026-05-18T00: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-18-1-monorepo-charter-scope/"/>
  <summary>Introduces CharterScope to resolve the nearest enclosing configured scope in a monorepo, while single-project behaviour stays byte-identical to the prior path.</summary>
  <content type="html">&lt;h2 id=&quot;context&quot;&gt;Context&lt;/h2&gt;
&lt;p&gt;Slice F lifts spec-kitty’s governance surface beyond a single repository.
Axis 1 (org-tier doctrine, WP04–WP08) lets organisations layer doctrine on top
of the shipped catalog. Axis 2 — the subject of this ADR — addresses the
operator request from issue #522: monorepos that ship multiple deployable
packages each want their &lt;strong&gt;own&lt;/strong&gt; charter, scoped by the filesystem location of
the mission rather than by the repository root.&lt;/p&gt;
&lt;p&gt;Concretely:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;A monorepo &lt;code dir=&quot;auto&quot;&gt;myorg-platform/&lt;/code&gt; contains &lt;code dir=&quot;auto&quot;&gt;packages/auth/&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;packages/web/&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;The auth team owns &lt;code dir=&quot;auto&quot;&gt;packages/auth/.kittify/charter/charter.md&lt;/code&gt; describing
their security posture, language standards, and review policy.&lt;/li&gt;
&lt;li&gt;The web team owns &lt;code dir=&quot;auto&quot;&gt;packages/web/.kittify/charter/charter.md&lt;/code&gt; describing
their frontend conventions.&lt;/li&gt;
&lt;li&gt;When a developer runs &lt;code dir=&quot;auto&quot;&gt;spec-kitty implement WP01&lt;/code&gt; from inside
&lt;code dir=&quot;auto&quot;&gt;packages/auth/some/deep/dir/&lt;/code&gt;, the prompt must surface the &lt;strong&gt;auth&lt;/strong&gt;
charter, not the platform root.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Before WP09, &lt;code dir=&quot;auto&quot;&gt;build_charter_context(repo_root, ...)&lt;/code&gt; read the charter only
from &lt;code dir=&quot;auto&quot;&gt;repo_root / .kittify / charter / charter.md&lt;/code&gt;. Monorepo teams could
work around this with &lt;code dir=&quot;auto&quot;&gt;cd packages/auth &amp;#x26;&amp;#x26; spec-kitty implement WP01&lt;/code&gt; (which
made &lt;code dir=&quot;auto&quot;&gt;packages/auth&lt;/code&gt; look like the root), but that fights every other
mechanism in the system (mission discovery, status events, worktrees) which
all consult the &lt;strong&gt;actual&lt;/strong&gt; git root.&lt;/p&gt;
&lt;p&gt;We need a first-class abstraction for “which charter applies to this
filesystem path”, with a hard &lt;strong&gt;byte-stability&lt;/strong&gt; guarantee for single-project
repositories — the 23 governance-contract fixtures locked by NFR-001 must
not change a single byte.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;p&gt;Introduce a new abstraction at the charter layer: &lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;CharterScope&lt;/code&gt;&lt;/strong&gt;, modelled
as a frozen dataclass living in &lt;code dir=&quot;auto&quot;&gt;src/charter/scope.py&lt;/code&gt;. It has exactly two
constructors and a small failure-mode surface:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;CharterScope.default(repo_root)&lt;/code&gt; — single-project constructor.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;root = repo_root&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;name = None&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;config_source = &quot;repo_root_default&quot;&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Behaviour is &lt;strong&gt;byte-identical to today&lt;/strong&gt; (NFR-001 binding).&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;CharterScope.resolve(repo_root, feature_dir)&lt;/code&gt; — monorepo-aware resolver.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;If &lt;code dir=&quot;auto&quot;&gt;repo_root/.kittify/config.yaml&lt;/code&gt; is absent OR its &lt;code dir=&quot;auto&quot;&gt;charter_scopes:&lt;/code&gt;
key is empty/missing, return &lt;code dir=&quot;auto&quot;&gt;CharterScope.default(repo_root)&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Otherwise, walk the configured scopes and return the &lt;strong&gt;nearest enclosing
ancestor&lt;/strong&gt; of &lt;code dir=&quot;auto&quot;&gt;feature_dir&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Raise &lt;code dir=&quot;auto&quot;&gt;CharterScopeConflict&lt;/code&gt; if two configured scopes have incompatible
nesting depths (one is an ancestor of another and the feature_dir is
under the deeper one — both scopes claim it).&lt;/li&gt;
&lt;li&gt;Raise &lt;code dir=&quot;auto&quot;&gt;CharterScopeNotFound&lt;/code&gt; if &lt;code dir=&quot;auto&quot;&gt;feature_dir&lt;/code&gt; is not under any
configured scope.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;The operator-facing configuration shape lives in &lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt;:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;yaml&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;charter_scopes&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;- &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;root&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;packages/auth&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;name&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;auth&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;- &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;root&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;packages/web&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;name&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;web&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;It is opt-in. Repositories that omit &lt;code dir=&quot;auto&quot;&gt;charter_scopes:&lt;/code&gt; get exactly the
behaviour they have today.&lt;/p&gt;
&lt;p&gt;To thread the resolver through the rendering pipeline without disturbing
&lt;code dir=&quot;auto&quot;&gt;build_charter_context&lt;/code&gt;’s signature (WP07’s ownership boundary), we ship a
new thin wrapper module &lt;code dir=&quot;auto&quot;&gt;src/charter/scope_router.py&lt;/code&gt; exposing:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;python&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;def&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;build_with_scope&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;(&lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;repo_root&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: Path, &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;feature_dir&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: Path, &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;**kwargs&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;)&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; -&gt; CharterContextResult:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&quot;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;Resolve the scope, then delegate to build_charter_context.&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&quot;&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;scope &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; CharterScope.&lt;/span&gt;&lt;span style=&quot;--0:#B2CCD6;--1:#096E72&quot;&gt;resolve&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;(&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;repo_root&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;,&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt; feature_dir&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;return&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#B2CCD6;--1:#096E72&quot;&gt;build_charter_context&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;(&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;scope.root&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;,&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt; feature_dir&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;,&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;**&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;kwargs&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;For single-project repos, &lt;code dir=&quot;auto&quot;&gt;scope.root == repo_root&lt;/code&gt; and the wrapper is a
no-op pass-through. For monorepos, the wrapper redirects to the
package-scoped charter root.&lt;/p&gt;
&lt;p&gt;The Pydantic model &lt;code dir=&quot;auto&quot;&gt;CharterScopeConfig&lt;/code&gt; (plus the inner &lt;code dir=&quot;auto&quot;&gt;_CharterScopeEntry&lt;/code&gt;)
ships alongside in the same module. It validates the YAML payload at config
load time, rejecting empty &lt;code dir=&quot;auto&quot;&gt;root&lt;/code&gt; fields and surfacing structural errors with
a stable error shape. This satisfies the FR-140 round-trip case
&lt;code dir=&quot;auto&quot;&gt;charter.scope.CharterScopeConfig&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;contracts/charter-scope-resolution.md&lt;/code&gt;.&lt;/p&gt;
&lt;hr&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;&lt;strong&gt;Per-package charter scoping unblocked&lt;/strong&gt; for monorepo operators (issue
#522). Auth and web teams own their own &lt;code dir=&quot;auto&quot;&gt;charter.md&lt;/code&gt; and the prompt
renderer surfaces the right one based on &lt;code dir=&quot;auto&quot;&gt;feature_dir&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Zero impact on single-project repos&lt;/strong&gt; — NFR-001 binding. The 23
&lt;code dir=&quot;auto&quot;&gt;test_wp_prompt_governance_contract.py&lt;/code&gt; fixtures pass unchanged because
&lt;code dir=&quot;auto&quot;&gt;CharterScope.default(repo_root)&lt;/code&gt; produces byte-identical output.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Layer-rule clean&lt;/strong&gt; (NFR-003). &lt;code dir=&quot;auto&quot;&gt;scope.py&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;scope_router.py&lt;/code&gt; live in
the charter layer and do not import from &lt;code dir=&quot;auto&quot;&gt;specify_cli.*&lt;/code&gt;. The
prompt-builder wiring (WP11) reverses the dependency direction:
&lt;code dir=&quot;auto&quot;&gt;specify_cli.next.prompt_builder&lt;/code&gt; calls into &lt;code dir=&quot;auto&quot;&gt;charter.scope_router&lt;/code&gt;, not
the other way around.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Ownership clean.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;context.py&lt;/code&gt; (owned by WP07) is untouched.
&lt;code dir=&quot;auto&quot;&gt;scope_router.py&lt;/code&gt; is a new module owned by WP09. No cross-WP file
conflicts.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Round-trip gate strengthened&lt;/strong&gt; (FR-140). The
&lt;code dir=&quot;auto&quot;&gt;charter.scope.CharterScopeConfig&lt;/code&gt; round-trip case flips from &lt;code dir=&quot;auto&quot;&gt;SKIPPED&lt;/code&gt; to
&lt;code dir=&quot;auto&quot;&gt;PASSED&lt;/code&gt;, removing one entry from the deferred-skips ledger.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;negative&quot;&gt;Negative&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Operators must learn a new config key.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;charter_scopes:&lt;/code&gt; is documented
in &lt;code dir=&quot;auto&quot;&gt;docs/explanation/charter-scope.md&lt;/code&gt; (follow-up) and in the contract
file. The single-project default behaviour means existing operators see
nothing new until they choose to opt in.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Modest read-time cost.&lt;/strong&gt; Every &lt;code dir=&quot;auto&quot;&gt;build_with_scope&lt;/code&gt; call reads
&lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt;. Single-project repos pay one extra &lt;code dir=&quot;auto&quot;&gt;stat&lt;/code&gt; per
prompt build (the file is absent and &lt;code dir=&quot;auto&quot;&gt;Path.exists()&lt;/code&gt; returns quickly).
NFR-002 caps prompt-build latency regression at 20%; if measurement shows
perceptible regression a module-level cache keyed by &lt;code dir=&quot;auto&quot;&gt;repo_root&lt;/code&gt; is a
drop-in mitigation (deferred until measured).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Two ways to reach the same place.&lt;/strong&gt; Existing callers of
&lt;code dir=&quot;auto&quot;&gt;build_charter_context(repo_root, ...)&lt;/code&gt; continue to work and continue to
use the repo-root charter; only callers migrated to &lt;code dir=&quot;auto&quot;&gt;build_with_scope&lt;/code&gt;
get monorepo support. This is intentional — the migration is
call-site-by-call-site rather than a forced cutover.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;neutral&quot;&gt;Neutral&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;CharterScope&lt;/code&gt; is a frozen dataclass, not a Pydantic model.&lt;/strong&gt; The
validated configuration shape (&lt;code dir=&quot;auto&quot;&gt;CharterScopeConfig&lt;/code&gt;) is the Pydantic
surface; the resolved runtime value is a small immutable record. This
matches the data-model conventions in §4 of the data-model.md.&lt;/li&gt;
&lt;/ul&gt;
&lt;hr&gt;
&lt;h2 id=&quot;alternatives-considered&quot;&gt;Alternatives Considered&lt;/h2&gt;
&lt;h3 id=&quot;a-repo-root-only-forever-the-status-quo&quot;&gt;A. Repo-root only forever (the status quo)&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Rejected.&lt;/strong&gt; Issue #522 is a real operator pain point and the
“&lt;code dir=&quot;auto&quot;&gt;cd packages/auth&lt;/code&gt;” workaround breaks every other mechanism that uses the
true git root.&lt;/p&gt;
&lt;h3 id=&quot;b-per-mission-charter_root-frontmatter-field&quot;&gt;B. Per-mission &lt;code dir=&quot;auto&quot;&gt;charter_root:&lt;/code&gt; frontmatter field&lt;/h3&gt;
&lt;p&gt;The mission’s &lt;code dir=&quot;auto&quot;&gt;spec.md&lt;/code&gt; would declare its charter root explicitly:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;yaml&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;charter_root&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;packages/auth&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;Rejected.&lt;/strong&gt; Pushes the choice into per-mission metadata, which means every
new mission requires the operator to remember to set the field. Easy to
forget; hard to validate; reproduces the “I forgot to set the canonical
attribute” failure mode the org-DRG work was trying to solve.&lt;/p&gt;
&lt;h3 id=&quot;c-auto-discovery-of-kittifycharter-directories&quot;&gt;C. Auto-discovery of &lt;code dir=&quot;auto&quot;&gt;.kittify/charter/&lt;/code&gt; directories&lt;/h3&gt;
&lt;p&gt;Walk the tree upward from &lt;code dir=&quot;auto&quot;&gt;feature_dir&lt;/code&gt;, return the first ancestor that
contains a &lt;code dir=&quot;auto&quot;&gt;.kittify/charter/&lt;/code&gt; directory.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Rejected.&lt;/strong&gt; Two problems:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Ambiguity surface.&lt;/strong&gt; A repo might contain &lt;code dir=&quot;auto&quot;&gt;.kittify/charter/&lt;/code&gt;
directories used for documentation, examples, fixtures, or vendored
third-party packages. Auto-discovery would pick those up silently.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No name.&lt;/strong&gt; The auto-discovered scope has no human-meaningful identifier
to surface in prompts, catalog-miss warnings, or diagnostics. The
operator-facing &lt;code dir=&quot;auto&quot;&gt;name:&lt;/code&gt; field becomes important the moment we have more
than one charter — it shows up in &lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor&lt;/code&gt;, in
&lt;code dir=&quot;auto&quot;&gt;CatalogMissEvent.extra[&quot;scope&quot;]&lt;/code&gt;, and in error messages.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;d-modify-build_charter_contexts-signature-directly&quot;&gt;D. Modify &lt;code dir=&quot;auto&quot;&gt;build_charter_context&lt;/code&gt;’s signature directly&lt;/h3&gt;
&lt;p&gt;Add &lt;code dir=&quot;auto&quot;&gt;scope: CharterScope | None = None&lt;/code&gt; as a kwarg.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Rejected for this mission.&lt;/strong&gt; Would force WP07 and WP09 to share file
ownership on &lt;code dir=&quot;auto&quot;&gt;src/charter/context.py&lt;/code&gt;, creating the kind of cross-WP
serialisation point we explicitly designed lanes to avoid. The
&lt;code dir=&quot;auto&quot;&gt;scope_router.py&lt;/code&gt; wrapper achieves the same effect from outside, leaves
&lt;code dir=&quot;auto&quot;&gt;context.py&lt;/code&gt; untouched, and gives us a clean place to add scope-aware
features (caching, telemetry, fallback warnings) without further mutating
the rendering core.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;related-decisions&quot;&gt;Related Decisions&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;[ADR Phase 2 of Slice F]: org-tier doctrine pack
(axis 1, WP04–WP08). Charter scoping (axis 2) and org-tier doctrine
(axis 1) are orthogonal and compose: a monorepo’s per-package charter
can layer an org-tier doctrine pack the same way a single-project
charter does.&lt;/li&gt;
&lt;li&gt;C-007 (binding &lt;code dir=&quot;auto&quot;&gt;__all__&lt;/code&gt; declarations) — both new modules expose
&lt;code dir=&quot;auto&quot;&gt;__all__&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;C-011 (ATDD-first per WP) — WP09 lands its failing tests as the first
commit, the model and wrapper turn them GREEN.&lt;/li&gt;
&lt;li&gt;FR-140 round-trip frontmatter convention — &lt;code dir=&quot;auto&quot;&gt;CharterScopeConfig&lt;/code&gt; joins
the round-trip-validated Pydantic surfaces.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;out-of-scope&quot;&gt;Out of Scope&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Charter caching&lt;/strong&gt; (deferred until NFR-002 measurement shows it
matters).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty charter scope list/show&lt;/code&gt; CLI surfaces&lt;/strong&gt; (deferred to a
follow-up; the runtime resolver is the primary deliverable).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Scope-aware glossary contexts.&lt;/strong&gt; Glossary contexts already have their
own scope mechanism; monorepo-aware glossary scoping is its own design
conversation.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Cross-scope dependency resolution.&lt;/strong&gt; If a &lt;code dir=&quot;auto&quot;&gt;packages/auth&lt;/code&gt; mission
needs to consult the &lt;code dir=&quot;auto&quot;&gt;packages/platform&lt;/code&gt; charter, the operator either
declares the dependency explicitly or runs the mission from the
platform scope. No automatic multi-scope merge in this iteration.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
