<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/architecture/06_unified_charter_bundle/">
  <id>https://docs.spec-kitty.ai/architecture/06_unified_charter_bundle/</id>
  <title>06 — Unified Charter Bundle</title>
  <updated>2026-10-21T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/architecture/06_unified_charter_bundle/"/>
  <summary>The unified charter bundle architecture: the canonical manifest, its module and JSON Schema, inverted to a single-file authoritative charter.yaml model (#2773).</summary>
  <content type="html">&lt;span id=&quot;06--unified-charter-bundle&quot;&gt;&lt;/span&gt;
&lt;p&gt;&lt;strong&gt;Status&lt;/strong&gt;: v2.0.0 (introduced by mission &lt;code dir=&quot;auto&quot;&gt;unified-charter-bundle-chokepoint-01KP5Q2G&lt;/code&gt;, WP01,
as v1.0.0; inverted to the single-file model by mission
&lt;code dir=&quot;auto&quot;&gt;consolidate-charter-bundle-01KXSYB9&lt;/code&gt;, IC-02).
&lt;strong&gt;Canonical manifest module&lt;/strong&gt;: &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/src/charter/bundle.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;src/charter/bundle.py&lt;/code&gt;&lt;/a&gt;
&lt;strong&gt;v2.0.0 contracts&lt;/strong&gt;: &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/kitty-specs/consolidate-charter-bundle-01KXSYB9/contracts/charter-yaml-schema.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;charter-yaml-schema.md&lt;/code&gt;&lt;/a&gt;, &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/kitty-specs/consolidate-charter-bundle-01KXSYB9/contracts/manifest-v2.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;manifest-v2.md&lt;/code&gt;&lt;/a&gt;
&lt;strong&gt;v1.0.0 JSON Schema (archived, superseded)&lt;/strong&gt;: &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/kitty-specs/unified-charter-bundle-chokepoint-01KP5Q2G/contracts/bundle-manifest.schema.yaml&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;kitty-specs/unified-charter-bundle-chokepoint-01KP5Q2G/contracts/bundle-manifest.schema.yaml&lt;/code&gt;&lt;/a&gt;&lt;/p&gt;
&lt;h2 id=&quot;purpose&quot;&gt;Purpose&lt;/h2&gt;
&lt;p&gt;Spec Kitty’s governance surface is a small bundle of files rooted at
&lt;code dir=&quot;auto&quot;&gt;.kittify/charter/&lt;/code&gt;. The &lt;strong&gt;unified charter bundle&lt;/strong&gt; contract is a single typed
manifest — &lt;code dir=&quot;auto&quot;&gt;CharterBundleManifest&lt;/code&gt; — that every reader, migration, and CLI
surface consults to know which files the bundle contains and how they relate.&lt;/p&gt;
&lt;p&gt;This file is the narrative source of truth. The Pydantic model in
&lt;code dir=&quot;auto&quot;&gt;src/charter/bundle.py&lt;/code&gt; is the machine-readable authority. The two MUST stay
in sync; changes to either REQUIRE a &lt;code dir=&quot;auto&quot;&gt;SCHEMA_VERSION&lt;/code&gt; bump and an
accompanying migration.&lt;/p&gt;
&lt;h2 id=&quot;v200-scope-a-single-authoritative-file&quot;&gt;v2.0.0 scope: a single authoritative file&lt;/h2&gt;
&lt;p&gt;The v1.0.0 manifest (mission &lt;code dir=&quot;auto&quot;&gt;unified-charter-bundle-chokepoint-01KP5Q2G&lt;/code&gt;)
declared &lt;code dir=&quot;auto&quot;&gt;charter.md&lt;/code&gt; as the sole tracked source and three sync-derived files
(&lt;code dir=&quot;auto&quot;&gt;governance.yaml&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;directives.yaml&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;metadata.yaml&lt;/code&gt;) as its content-hash
input set. Mission &lt;code dir=&quot;auto&quot;&gt;consolidate-charter-bundle-01KXSYB9&lt;/code&gt; &lt;strong&gt;inverted&lt;/strong&gt; that
model: the git-tracked, authorable, structured charter is now
&lt;code dir=&quot;auto&quot;&gt;.kittify/charter/charter.yaml&lt;/code&gt; — a single file nesting &lt;code dir=&quot;auto&quot;&gt;governance&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;directives&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;catalog&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;overrides&lt;/code&gt; (activation, once nested here too,
moved to the activation ledger in 4.0.0rc8; see below). &lt;code dir=&quot;auto&quot;&gt;charter.md&lt;/code&gt; remains
tracked as a curated companion, but nothing is derived from it any more and
it contributes nothing to the content-hash.&lt;/p&gt;

























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Role&lt;/th&gt;&lt;th&gt;Path&lt;/th&gt;&lt;th&gt;Notes&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;tracked&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;.kittify/charter/charter.md&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Curated companion — human-authored, never parsed for policy&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;tracked + content-hash input&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;.kittify/charter/charter.yaml&lt;/code&gt;&lt;/td&gt;&lt;td&gt;The single authoritative structured charter&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;optional tracked + optional content-hash input&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;.kittify/charter/activation.yaml&lt;/code&gt;&lt;/td&gt;&lt;td&gt;The activation ledger (&lt;a href=&quot;/adr/4.x/2026-10-19-1-activation-ledger-persists-deactivation/&quot;&gt;ADR 2026-10-19-1&lt;/a&gt;); present on every project created or upgraded by 4.0.0rc8 or later&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;&lt;strong&gt;The activation ledger is an optional member (4.0.0rc8).&lt;/strong&gt; The manifest
lists it in &lt;code dir=&quot;auto&quot;&gt;optional_tracked_files&lt;/code&gt;, still at &lt;code dir=&quot;auto&quot;&gt;SCHEMA_VERSION&lt;/code&gt; 2.0.0 (an
additive optional field). &lt;code dir=&quot;auto&quot;&gt;bundle validate&lt;/code&gt; reports it as present or absent
and never fails on its absence; &lt;code dir=&quot;auto&quot;&gt;--json&lt;/code&gt; lists it under
&lt;code dir=&quot;auto&quot;&gt;optional_tracked_files&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;expected&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;present&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;missing&lt;/code&gt;). It is hashed,
after the required members, only when the file exists
(&lt;code dir=&quot;auto&quot;&gt;BUNDLE_OPTIONAL_CONTENT_HASH_FILES&lt;/code&gt;), so a project without it keeps a
byte-identical digest while an edit made outside the CLI changes the digest
and reads as stale. The CLI’s activation writers (&lt;code dir=&quot;auto&quot;&gt;charter activate&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;charter deactivate&lt;/code&gt;, presets and the ledger migration) re-stamp the
synthesis manifest’s &lt;code dir=&quot;auto&quot;&gt;bundle_content_hash&lt;/code&gt; after they write.&lt;/p&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;derived_files&lt;/code&gt; is &lt;strong&gt;empty&lt;/strong&gt; in v2.0.0 — nothing under &lt;code dir=&quot;auto&quot;&gt;.kittify/charter/&lt;/code&gt;
is generated-and-gitignored any more. &lt;code dir=&quot;auto&quot;&gt;content_hash_files&lt;/code&gt; is a field
&lt;strong&gt;distinct&lt;/strong&gt; from &lt;code dir=&quot;auto&quot;&gt;derived_files&lt;/code&gt; (it always was; the historic 4-vs-3
file-count mismatch between &lt;code dir=&quot;auto&quot;&gt;BUNDLE_CONTENT_HASH_FILES&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;derived_files&lt;/code&gt;
made that distinction explicit) and holds exactly &lt;code dir=&quot;auto&quot;&gt;[charter.yaml]&lt;/code&gt;.
&lt;code dir=&quot;auto&quot;&gt;gitignore_required_entries&lt;/code&gt; is also empty — there is nothing left that the
bundle requires a project’s &lt;code dir=&quot;auto&quot;&gt;.gitignore&lt;/code&gt; to exclude.&lt;/p&gt;
&lt;p&gt;Full field-level guarantees live in the contracts:
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/kitty-specs/consolidate-charter-bundle-01KXSYB9/contracts/charter-yaml-schema.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;charter-yaml-schema.md&lt;/code&gt;&lt;/a&gt;
(the &lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt; shape) and
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/kitty-specs/consolidate-charter-bundle-01KXSYB9/contracts/manifest-v2.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;manifest-v2.md&lt;/code&gt;&lt;/a&gt;
(the manifest diff from v1.0.0).&lt;/p&gt;
&lt;h3 id=&quot;out-of-manifest-scope&quot;&gt;Out of manifest scope&lt;/h3&gt;
&lt;p&gt;The following files live under &lt;code dir=&quot;auto&quot;&gt;.kittify/charter/&lt;/code&gt; but are &lt;strong&gt;not&lt;/strong&gt; managed
by the manifest. They are produced by separate pipelines with their own
lifecycle and ownership:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;.kittify/charter/context-state.json&lt;/code&gt;&lt;/strong&gt; — runtime state written by
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/src/charter/activation/context.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;src/charter/activation/context.py&lt;/code&gt;&lt;/a&gt; inside
&lt;code dir=&quot;auto&quot;&gt;build_charter_context()&lt;/code&gt;. This is lazy, per-invocation runtime
state; it is not part of any reproducibility contract and is
intentionally absent from the manifest.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;.kittify/charter/interview/answers.yaml&lt;/code&gt;&lt;/strong&gt; — optional companion input
for charter generation, owned by the interview surface.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The &lt;code dir=&quot;auto&quot;&gt;bundle validate&lt;/code&gt; CLI surfaces these as &lt;strong&gt;informational warnings&lt;/strong&gt;
when present, never as failures. Operators can leave them in place, remove
them, or extend their &lt;code dir=&quot;auto&quot;&gt;.gitignore&lt;/code&gt; to match; the manifest does not forbid
them.&lt;/p&gt;
&lt;h2 id=&quot;tracked-vs-content-hash-classification&quot;&gt;Tracked vs. content-hash classification&lt;/h2&gt;
&lt;p&gt;The split exists so tooling can reason about the two classes separately:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Tracked files&lt;/strong&gt; MUST exist on disk, MUST be committed to git, and MUST
appear in &lt;code dir=&quot;auto&quot;&gt;git ls-files&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;charter.md&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt; are both tracked.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Content-hash files&lt;/strong&gt; are the input set for the bundle’s freshness hash —
a strict subset of tracked files (&lt;code dir=&quot;auto&quot;&gt;[charter.yaml]&lt;/code&gt; only). A tracked file
need not be a content-hash input; &lt;code dir=&quot;auto&quot;&gt;charter.md&lt;/code&gt; is the example: tracked
(git must have it) but excluded from the hash (it is not read for policy).&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The manifest asserts the shape of this split via the Pydantic
&lt;code dir=&quot;auto&quot;&gt;_validate&lt;/code&gt; hook: no path may be in both the tracked and derived sets; every
&lt;code dir=&quot;auto&quot;&gt;derivation_sources&lt;/code&gt; key must be a derived path; every value must be a
tracked path. &lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt; lives only in &lt;code dir=&quot;auto&quot;&gt;tracked_files&lt;/code&gt; (and
&lt;code dir=&quot;auto&quot;&gt;content_hash_files&lt;/code&gt;), never in &lt;code dir=&quot;auto&quot;&gt;derived_files&lt;/code&gt; — that disjointness
invariant is unchanged from v1.0.0 and MUST NOT be relaxed; keeping
“authored ≠ generated” meaningful is the point.&lt;/p&gt;
&lt;h2 id=&quot;canonical-root-contract&quot;&gt;Canonical-root contract&lt;/h2&gt;
&lt;p&gt;All readers resolve the canonical project root through a single helper —
&lt;code dir=&quot;auto&quot;&gt;charter.resolution.resolve_canonical_repo_root()&lt;/code&gt; — which correctly maps a
worktree path back to its main-checkout location. See
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/kitty-specs/unified-charter-bundle-chokepoint-01KP5Q2G/contracts/canonical-root-resolver.contract.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;contracts/canonical-root-resolver.contract.md&lt;/code&gt;&lt;/a&gt;
for the full contract (unchanged by the v2.0.0 inversion).&lt;/p&gt;
&lt;h2 id=&quot;config-pointer-resolution&quot;&gt;Config pointer resolution&lt;/h2&gt;
&lt;p&gt;The active &lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt; is located through a single &lt;code dir=&quot;auto&quot;&gt;charter:&lt;/code&gt; pointer in
&lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt; (default &lt;code dir=&quot;auto&quot;&gt;.kittify/charter/charter.yaml&lt;/code&gt;). The
resolver reads the pointer, then loads that file. The pointer may redirect
to a sibling, shared, or cross-project charter — a swap is a one-line config
change. The v2.0.0 inversion moved the flat &lt;code dir=&quot;auto&quot;&gt;activated_*&lt;/code&gt; /
&lt;code dir=&quot;auto&quot;&gt;mission_type_activations&lt;/code&gt; keys from &lt;code dir=&quot;auto&quot;&gt;config.yaml&lt;/code&gt; to &lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt;’s root;
4.0.0rc8 moves them again, to the activation ledger
&lt;code dir=&quot;auto&quot;&gt;.kittify/charter/activation.yaml&lt;/code&gt;, through the &lt;code dir=&quot;auto&quot;&gt;4.0.0rc8_activation_ledger&lt;/code&gt;
upgrade step (or &lt;code dir=&quot;auto&quot;&gt;spec-kitty migrate activation-ledger&lt;/code&gt;).&lt;/p&gt;
&lt;p&gt;Where activation is read from is decided by one resolver,
&lt;code dir=&quot;auto&quot;&gt;kernel.activation_ledger_store.resolve_activation_source&lt;/code&gt;: the activation
ledger when it exists or the project is fresh; the old surface (the pointed
&lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt;, else &lt;code dir=&quot;auto&quot;&gt;config.yaml&lt;/code&gt;) inside the upgrade scope and for an
unmigrated project, whose allow keys are read as before and which refuses
every exclusion until it is upgraded. Activation keys left in &lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt;
or &lt;code dir=&quot;auto&quot;&gt;config.yaml&lt;/code&gt; beside the activation ledger are ignored and reported.&lt;/p&gt;
&lt;p&gt;A &lt;code dir=&quot;auto&quot;&gt;charter:&lt;/code&gt; pointer to a missing or unreadable file fails loud; there is no
fallback to a legacy file.&lt;/p&gt;
&lt;h2 id=&quot;content-hash-semantics&quot;&gt;Content-hash semantics&lt;/h2&gt;
&lt;p&gt;The bundle’s freshness signal is content-hash driven, not sync-driven:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;compute_bundle_content_hash&lt;/code&gt; hashes exactly the files in
&lt;code dir=&quot;auto&quot;&gt;content_hash_files&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt;, declared order), then the optional
&lt;code dir=&quot;auto&quot;&gt;activation.yaml&lt;/code&gt; when it exists, via the unchanged per-file recipe
(BOM-strip/CRLF normalization).&lt;/li&gt;
&lt;li&gt;Write-side stampers (&lt;code dir=&quot;auto&quot;&gt;write_pipeline.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;resynthesize_pipeline.py&lt;/code&gt;) and
the freshness reader (&lt;code dir=&quot;auto&quot;&gt;charter_runtime/freshness/computer.py&lt;/code&gt;) all route
through that single recipe.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;charter.md&lt;/code&gt;’s own SHA-256 hash — the v1.0.0 staleness mechanism compared
against a &lt;code dir=&quot;auto&quot;&gt;charter_hash&lt;/code&gt; field — is retired. A hash of &lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt;
cannot live &lt;em&gt;inside&lt;/em&gt; &lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt; (chicken-egg), so &lt;code dir=&quot;auto&quot;&gt;metadata&lt;/code&gt; carries
no self-referential hash; &lt;code dir=&quot;auto&quot;&gt;metadata.bundle_schema_version&lt;/code&gt; is the only
field &lt;code dir=&quot;auto&quot;&gt;versioning.py&lt;/code&gt; reads from it.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;ensure_charter_bundle_fresh()&lt;/code&gt; is retained for canonical-root resolution and
back-compat call sites (the bundle-migration upgrader, &lt;code dir=&quot;auto&quot;&gt;charter context&lt;/code&gt;), but no
longer performs extraction. The &lt;code dir=&quot;auto&quot;&gt;charter sync&lt;/code&gt; CLI command was removed (#5828).&lt;/p&gt;
&lt;h2 id=&quot;gitignore-policy-must-include-not-exclusive&quot;&gt;Gitignore policy: MUST-INCLUDE, not exclusive&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;gitignore_required_entries&lt;/code&gt; is a &lt;strong&gt;MUST-INCLUDE&lt;/strong&gt; set, currently empty in
v2.0.0 (nothing left under &lt;code dir=&quot;auto&quot;&gt;.kittify/charter/&lt;/code&gt; is required to be ignored).
The &lt;code dir=&quot;auto&quot;&gt;.gitignore&lt;/code&gt; at the project root:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;MUST contain every entry the manifest lists on its own line (none, today).&lt;/li&gt;
&lt;li&gt;MAY carry additional entries, including entries for the out-of-scope
files enumerated above (&lt;code dir=&quot;auto&quot;&gt;context-state.json&lt;/code&gt;, provenance sidecars,
synthesis manifests).&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;bundle validate&lt;/code&gt; only fails when a &lt;strong&gt;required&lt;/strong&gt; entry is missing. It
does not enforce exclusivity and does not warn about additional
&lt;code dir=&quot;auto&quot;&gt;.kittify/charter/*&lt;/code&gt; entries.&lt;/p&gt;
&lt;h2 id=&quot;schema-versioning-policy&quot;&gt;Schema versioning policy&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;CANONICAL_MANIFEST.schema_version&lt;/code&gt; carries an independent semver
(&lt;code dir=&quot;auto&quot;&gt;2.0.0&lt;/code&gt; as of the consolidate-charter-bundle inversion). The manifest
version is &lt;strong&gt;not&lt;/strong&gt; tied to the &lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt; package version.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Major bump&lt;/strong&gt; (e.g. &lt;code dir=&quot;auto&quot;&gt;3.0.0&lt;/code&gt;): breaking change to the manifest shape or
required fields — e.g., adding a required key, renaming an existing
key, removing the tracked/content-hash split. Requires a new migration
module under &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/migrations/&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Minor bump&lt;/strong&gt; (e.g. &lt;code dir=&quot;auto&quot;&gt;2.1.0&lt;/code&gt;): scope expansion or additive optional fields.
Requires a migration that extends the manifest and updates every
reader site simultaneously.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Patch bump&lt;/strong&gt; (e.g. &lt;code dir=&quot;auto&quot;&gt;2.0.1&lt;/code&gt;): narrative or docstring fixes that do not
change the shape or scope. No migration needed.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Future manifest versions ship with their own migration; there is &lt;strong&gt;no
fallback&lt;/strong&gt; for older manifests at runtime (per C-001). A project that
lags a manifest bump must upgrade before it can use the bundle CLI. The
upgrade migration that folds the legacy &lt;code dir=&quot;auto&quot;&gt;governance.yaml&lt;/code&gt; /
&lt;code dir=&quot;auto&quot;&gt;directives.yaml&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;metadata.yaml&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;references.yaml&lt;/code&gt; quartet (plus
&lt;code dir=&quot;auto&quot;&gt;config.yaml&lt;/code&gt;’s &lt;code dir=&quot;auto&quot;&gt;activated_*&lt;/code&gt; keys) into &lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt; and mints the
&lt;code dir=&quot;auto&quot;&gt;charter:&lt;/code&gt; pointer is the v1.0.0 → v2.0.0 migration path.&lt;/p&gt;
&lt;h2 id=&quot;charteryaml-precedence-over-chartermd&quot;&gt;charter.yaml precedence over charter.md&lt;/h2&gt;
&lt;p&gt;The charter has two surfaces with a strict precedence (operator decision, 2026-08-02):&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;.kittify/charter/charter.yaml&lt;/code&gt;&lt;/strong&gt; is the deterministic, schema-guarded &lt;strong&gt;resolution
authority&lt;/strong&gt; — it takes precedence for any resolving decision (governance policy,
presence gates, activated sets).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;.kittify/charter/charter.md&lt;/code&gt;&lt;/strong&gt; is a &lt;strong&gt;secondary&lt;/strong&gt; read point that carries rationale
and prose. It stays human-readable but &lt;strong&gt;never overrides&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt; and is never
the authoritative resolving source.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;When a surface must decide “does a charter exist / what does it say”, resolve from
&lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt; first and treat &lt;code dir=&quot;auto&quot;&gt;charter.md&lt;/code&gt; only as secondary rationale. Route reads
through the charter-layer authority (&lt;code dir=&quot;auto&quot;&gt;charter.bundle&lt;/code&gt; constants + the charter-yaml IO),
not re-derived path joins.&lt;/p&gt;
&lt;h2 id=&quot;the-charter-path-literal-authority-gate&quot;&gt;The charter path-literal authority gate&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_charter_path_literal_authority.py&lt;/code&gt; is an AST census gate: it
finds every hardcoded charter-path literal (&lt;code dir=&quot;auto&quot;&gt;&quot;charter.yaml&quot;&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;&quot;charter.md&quot;&lt;/code&gt; in a
&lt;code dir=&quot;auto&quot;&gt;Path&lt;/code&gt;-construction context) across &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt; and asserts the live-site count equals the
allowlist (plus a census ceiling). Adding one new &lt;code dir=&quot;auto&quot;&gt;repo_root / &quot;charter.yaml&quot;&lt;/code&gt;-style
literal reds it.&lt;/p&gt;
&lt;p&gt;The correct fix is the &lt;strong&gt;drain procedure, not an allowlist add&lt;/strong&gt;: route the path through
the canonical repo-root-relative &lt;code dir=&quot;auto&quot;&gt;charter.bundle.CHARTER_YAML&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;CHARTER_MD&lt;/code&gt; so no new
literal exists (e.g. &lt;code dir=&quot;auto&quot;&gt;if not (repo_root / CHARTER_YAML).exists():&lt;/code&gt;). The allowlist
reserves entries only for sites that genuinely cannot use the repo-root Path — for
example a bundle &lt;em&gt;writer&lt;/em&gt; materializing into a caller-supplied &lt;code dir=&quot;auto&quot;&gt;output_dir&lt;/code&gt;. This gate
runs only in the full architectural battery, so a per-WP subset run will not surface it.&lt;/p&gt;
&lt;h2 id=&quot;related-contracts&quot;&gt;Related contracts&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/kitty-specs/consolidate-charter-bundle-01KXSYB9/contracts/charter-yaml-schema.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;charter-yaml-schema.md&lt;/code&gt;&lt;/a&gt; — the &lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt; structured shape (v2.0.0).&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/kitty-specs/consolidate-charter-bundle-01KXSYB9/contracts/manifest-v2.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;manifest-v2.md&lt;/code&gt;&lt;/a&gt; — the &lt;code dir=&quot;auto&quot;&gt;CharterBundleManifest&lt;/code&gt; v1.0.0 → v2.0.0 diff.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/kitty-specs/consolidate-charter-bundle-01KXSYB9/contracts/migration-contract.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;migration-contract.md&lt;/code&gt;&lt;/a&gt; — the fold migration that retires the legacy quartet.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/kitty-specs/unified-charter-bundle-chokepoint-01KP5Q2G/contracts/bundle-manifest.schema.yaml&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;bundle-manifest.schema.yaml&lt;/code&gt;&lt;/a&gt; — archived v1.0.0 JSON Schema, superseded by the contracts above.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/kitty-specs/unified-charter-bundle-chokepoint-01KP5Q2G/contracts/bundle-validate-cli.contract.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;bundle-validate-cli.contract.md&lt;/code&gt;&lt;/a&gt; — CLI contract for &lt;code dir=&quot;auto&quot;&gt;spec-kitty charter bundle validate&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/kitty-specs/unified-charter-bundle-chokepoint-01KP5Q2G/contracts/canonical-root-resolver.contract.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;canonical-root-resolver.contract.md&lt;/code&gt;&lt;/a&gt; — canonical-root resolution (unchanged by the inversion).&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/kitty-specs/unified-charter-bundle-chokepoint-01KP5Q2G/contracts/chokepoint.contract.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;chokepoint.contract.md&lt;/code&gt;&lt;/a&gt; — reader chokepoint contract.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
