<?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-07-18-1-charter-yaml-authoring-authority-and-extractor-retirement/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-07-18-1-charter-yaml-authoring-authority-and-extractor-retirement/</id>
  <title>ADR: charter.yaml is the authoritative structured source; charter.md is a curated companion; retire the prose→triad extractor</title>
  <updated>2026-07-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-07-18-1-charter-yaml-authoring-authority-and-extractor-retirement/"/>
  <summary>`charter.yaml` becomes the authoritative structured charter owning activation state, `charter.md` becomes a curated companion, and the prose-to-triad extractor retires.</summary>
  <content type="html">&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Proposed&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-07-18&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Operator (Stijn Dejongh); assessment by a 4-lens grounding squad + a thesis/antithesis dialectic + a neutral empirical investigation (2026-07-18).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt; epic &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2519&quot;&gt;#2519&lt;/a&gt;; mission &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2773&quot;&gt;#2773&lt;/a&gt; (consolidate-charter-bundle); relates &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2772&quot;&gt;#2772&lt;/a&gt;; aligns with &lt;a href=&quot;/adr/3.x/2026-07-15-1-doctrine-offers-charter-activates-runtime-consumes/&quot;&gt;ADR 2026-07-15-1&lt;/a&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;Charter state is compiled from a hand-authored &lt;code dir=&quot;auto&quot;&gt;charter.md&lt;/code&gt; into four separate on-disk artifacts under &lt;code dir=&quot;auto&quot;&gt;.kittify/charter/&lt;/code&gt;: &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; (the “derived triad”, produced by &lt;code dir=&quot;auto&quot;&gt;sync.py::sync()&lt;/code&gt;), and &lt;code dir=&quot;auto&quot;&gt;references.yaml&lt;/code&gt; (produced by &lt;code dir=&quot;auto&quot;&gt;compiler.py&lt;/code&gt;, and also the ID-parity authority). Mission #2773 consolidates these four into one compiled &lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;While specifying #2773 the operator reopened a deeper question under a &lt;strong&gt;deterministic-first&lt;/strong&gt; philosophy: should &lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt; become the &lt;strong&gt;authoritative structured source&lt;/strong&gt; and &lt;code dir=&quot;auto&quot;&gt;charter.md&lt;/code&gt; a &lt;strong&gt;curated companion&lt;/strong&gt; (rationale write-up), inverting the current “charter.md is the authored source” model?&lt;/p&gt;
&lt;p&gt;The proposal was assessed and de-risked. The key findings:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Three surfaces are conflated by the phrase “what is active”.&lt;/strong&gt; (A) the &lt;em&gt;activation ledger&lt;/em&gt; — &lt;code dir=&quot;auto&quot;&gt;config.yaml activated_*&lt;/code&gt;; (B) the &lt;em&gt;compiled resolving bundle&lt;/em&gt; — the four files → &lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt;; (C) &lt;em&gt;human prose&lt;/em&gt; — &lt;code dir=&quot;auto&quot;&gt;charter.md&lt;/code&gt;. #2773 consolidates B; the inversion targets C.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;answers.yaml&lt;/code&gt; is provenance-only&lt;/strong&gt; (operator-binding): a creation-time record of &lt;em&gt;why/when/who&lt;/em&gt;, with &lt;strong&gt;zero&lt;/strong&gt; runtime/behavioural impact by design. Reading &lt;code dir=&quot;auto&quot;&gt;answers.yaml selected_*&lt;/code&gt; for behaviour is a bug. Therefore &lt;code dir=&quot;auto&quot;&gt;config.yaml activated_*&lt;/code&gt; is the &lt;strong&gt;sole&lt;/strong&gt; activation authority; the #2519 “disjoint activation ledgers” concern is largely a mislabel.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;charter.md&lt;/code&gt; is currently dual-owned&lt;/strong&gt; — hand-authored prose AND regenerated from an interview template by &lt;code dir=&quot;auto&quot;&gt;compiler.py:421&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;charter_path.write_text(compiled.markdown)&lt;/code&gt;), reachable via &lt;code dir=&quot;auto&quot;&gt;charter generate --force&lt;/code&gt;. That single writer is the #2772 clobber (a 1237-line curated-prose destruction was observed live).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The “AI/hybrid extractor” is a phantom.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;extractor.py:807 extract_with_ai&lt;/code&gt; returns &lt;code dir=&quot;auto&quot;&gt;{}&lt;/code&gt; and has zero callers; the prose→triad extraction is 100% deterministic regex/keyword scraping. The &lt;code dir=&quot;auto&quot;&gt;extraction_mode: &quot;hybrid&quot;&lt;/code&gt; label is cosmetic.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Prose is display-only for governance.&lt;/strong&gt; A neutral trace of every &lt;code dir=&quot;auto&quot;&gt;charter.md&lt;/code&gt;-content reader found all governance/directive reads flow into &lt;strong&gt;agent-facing display text&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;context.py:274 _extract_policy_summary&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;context.py:1023/2754/2784 render_critical_section_bodies&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;compact.py:138&lt;/code&gt;), not decisions. Runtime governance/directive loaders (&lt;code dir=&quot;auto&quot;&gt;sync.py:307/356&lt;/code&gt;) read the &lt;strong&gt;triad YAML&lt;/strong&gt;, not prose. The one behavioral prose read — doctrine language-scoping (&lt;code dir=&quot;auto&quot;&gt;language_scope.py:101-103&lt;/code&gt;) — is orthogonal: its authoritative source is &lt;code dir=&quot;auto&quot;&gt;references.yaml&lt;/code&gt; (structured, from the interview), with &lt;code dir=&quot;auto&quot;&gt;charter.md&lt;/code&gt; only a degraded tier-3 fallback; it is not produced by the scraper and not part of the triad.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Consequence of the findings:&lt;/strong&gt; seeding &lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt; from the existing triad is a &lt;strong&gt;deterministic, lossless yaml→yaml fold&lt;/strong&gt; (the same migration #2773 already commits to). The inversion’s cost is therefore &lt;em&gt;not&lt;/em&gt; a data-migration hazard — it is (a) a governance/authoring-UX structural change and (b) a schema-shape decision that is expensive to reverse under the bundle-manifest schema contract (a version bump + migration).&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Deterministic-first&lt;/strong&gt; — the authoritative “what is active / what governance applies” state should be structured and deterministically read, not scraped from prose.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Single canonical authority&lt;/strong&gt; (charter governing principle) — one owning source per surface; eliminate the dual-owned &lt;code dir=&quot;auto&quot;&gt;charter.md&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Kill the split/drift/stopgap churn&lt;/strong&gt; — epic #2519’s purpose. Shipping a &lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt; schema we already know we will re-cut for the inversion would recreate exactly that churn.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Cut the schema once&lt;/strong&gt; — the bundle-manifest schema/migration is the only expensive-to-reverse artifact; deciding its end-state shape now avoids a second bump on the same brand-new file.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Eliminate the #2772 clobber&lt;/strong&gt; at its single write site.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Preserve&lt;/strong&gt; the #2732 content-identity machinery and the C-001 layer boundary (&lt;code dir=&quot;auto&quot;&gt;src/charter/&lt;/code&gt; must not import &lt;code dir=&quot;auto&quot;&gt;specify_cli&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;Option X — ADR now + reshape #2773 to be authoring-ready; stage the deletion.&lt;/strong&gt; (chosen)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option Y — ADR-first, then shape #2773 from the outcome.&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option Z — keep #2773 bounded (derived-from-prose), do the inversion later as a wholly separate mission.&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option (b) — charter.md becomes fully generated from rationale fields embedded in charter.yaml.&lt;/strong&gt; (rejected)&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: X&lt;/strong&gt;, because the only expensive-to-reverse artifact is the &lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt; schema, and the empirical trace removed the “lossy migration” blocker — so we commit the full end-state in one coherent mission, delivered on a single branch and PRed as a consistent whole (sequenced tidy-first within the mission rather than split across PRs).&lt;/p&gt;
&lt;p&gt;The end-state this ADR pins:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt; is the project charter&lt;/strong&gt; — the authoritative structured source for the project’s active doctrine: governance knobs, directive declarations, the resolving/artifact-ID catalog, &lt;strong&gt;the project activation state and overrides&lt;/strong&gt;. It is pack-shaped (same &lt;strong&gt;flat&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;activated_kinds&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;mission_type_activations&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;activated_*&lt;/code&gt; root-key vocabulary as &lt;code dir=&quot;auto&quot;&gt;src/charter/packs/default.yaml&lt;/code&gt;). This mission relocates a &lt;strong&gt;single flat activation surface&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;default.yaml&lt;/code&gt; supplies the absent-key fallback/seed); the multi-tier org⊆team⊆repo charter &lt;em&gt;accumulation&lt;/em&gt; is the target model but is &lt;strong&gt;forward-intent&lt;/strong&gt; — the current &lt;code dir=&quot;auto&quot;&gt;pack_roots&lt;/code&gt; overlay applies to artifact definitions, not activation tiers — and is fenced OUT with the rest of the ADR 2026-07-15-1 restructure.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt; OWNS activation.&lt;/strong&gt; The project activation state (&lt;code dir=&quot;auto&quot;&gt;activated_*&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;activated_kinds&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;mission_type_activations&lt;/code&gt;) &lt;strong&gt;relocates out of &lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt; into &lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt;&lt;/strong&gt;; the activation engine (&lt;code dir=&quot;auto&quot;&gt;commit_plan&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;merge_defaults&lt;/code&gt;) and &lt;code dir=&quot;auto&quot;&gt;PackContext.from_config&lt;/code&gt; are re-pointed to write/read &lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;config.yaml&lt;/code&gt; retains only non-doctrine config (agents, tooling). &lt;code dir=&quot;auto&quot;&gt;answers.yaml&lt;/code&gt; stays provenance-only. &lt;strong&gt;Fenced OUT of this mission:&lt;/strong&gt; the broader ADR 2026-07-15-1 restructure (runtime activation-gating; first-class DRG nodes for &lt;code dir=&quot;auto&quot;&gt;mission_type&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;gate&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;asset&lt;/code&gt;) — this mission advances only the activation-surface/ownership axis. Local-only/personal doctrine is assumed to activate via the same pack-shaped mechanism (the local-override mechanism itself is a separately-tracked gap).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;charter.md&lt;/code&gt; is a hand-authored curated companion&lt;/strong&gt; — the human “why”. It is &lt;strong&gt;never a resolving input&lt;/strong&gt; and &lt;strong&gt;never clobbered&lt;/strong&gt; by any generate/compile path.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The prose→triad regex extractor (&lt;code dir=&quot;auto&quot;&gt;extractor.py&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;SECTION_MAPPING&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;sync()&lt;/code&gt; backward scrape) is retired&lt;/strong&gt; — governance/directive structure is authored/held structurally, not scraped from prose.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Delivery is one coherent mission on a single branch, PRed as a whole&lt;/strong&gt;, sequenced tidy-first: (i) build &lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt; with first-class &lt;em&gt;authorable&lt;/em&gt; fields + fold the clobber guard; (ii) seed it deterministically from the triad and re-point resolving/parity/freshness consumers; (iii) re-point the display prose-consumers and retire the prose→triad extractor + &lt;code dir=&quot;auto&quot;&gt;sync()&lt;/code&gt; backward scrape; (iv) &lt;code dir=&quot;auto&quot;&gt;charter.md&lt;/code&gt; becomes a pure hand-authored companion the derive path never writes. No intermediate PR ships a half-inverted state.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;This aligns with ADR 2026-07-15-1 (“Doctrine offers, charter activates, runtime consumes”) on the activation axis (activation stays in the charter/config layer, routed via the default charter) and adds the orthogonal &lt;strong&gt;authoring-direction&lt;/strong&gt; decision that ADR did not cover.&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 canonical structured authoring source; the dual-owned &lt;code dir=&quot;auto&quot;&gt;charter.md&lt;/code&gt; smell and the #2772 clobber are eliminated.&lt;/li&gt;
&lt;li&gt;Deterministic-first resolving/governance with no brittle prose scraper.&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt; schema is cut once (no second C-004 bump), honoring #2519’s anti-churn goal.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;charter.md&lt;/code&gt; becomes freely curatable rationale that no tool overwrites.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;The mission widens materially — it now carries the full inversion (schema design + clobber guard + C-001 flip + extractor retirement + display-consumer re-pointing) &lt;strong&gt;plus relocating the activation state and re-pointing the activation engine (&lt;code dir=&quot;auto&quot;&gt;commit_plan&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;merge_defaults&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;PackContext.from_config&lt;/code&gt;)&lt;/strong&gt; in one branch/PR. Expect a large WP count and review surface; the activation-engine change is the biggest new blast radius.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt; is &lt;strong&gt;git-tracked&lt;/strong&gt; (an authoring surface); its derived &lt;code dir=&quot;auto&quot;&gt;catalog&lt;/code&gt; section produces honest tracked diffs when activation changes — acceptable, and detected by the freshness signal.&lt;/li&gt;
&lt;li&gt;The governance authoring UX shifts from prose to structured fields — a real change delivered within the mission, needing docs + operator guidance in the same PR.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;The doctrine language-scoping tier-3 &lt;code dir=&quot;auto&quot;&gt;charter.md&lt;/code&gt; fallback (&lt;code dir=&quot;auto&quot;&gt;language_scope.py:103&lt;/code&gt;) is orthogonal; it is &lt;strong&gt;folded into this mission&lt;/strong&gt; as FR-009/IC-08 (migrated off &lt;code dir=&quot;auto&quot;&gt;charter.md&lt;/code&gt; prose to the structured catalog &lt;code dir=&quot;auto&quot;&gt;languages&lt;/code&gt;), so &lt;code dir=&quot;auto&quot;&gt;charter.md&lt;/code&gt; is behaviorally inert by mission end.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;#2772&lt;/code&gt; is folded (the guard) / superseded (the derive path stops writing &lt;code dir=&quot;auto&quot;&gt;charter.md&lt;/code&gt; once the extractor retires).&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;amendment-2026-07-19-2800-landing-pass&quot;&gt;Amendment (2026-07-19, #2800 landing pass)&lt;/h4&gt;
&lt;p&gt;The original outcome — the &lt;em&gt;compiler&lt;/em&gt; (&lt;code dir=&quot;auto&quot;&gt;write_compiled_charter&lt;/code&gt;) never writes &lt;code dir=&quot;auto&quot;&gt;charter.md&lt;/code&gt; — is preserved. But “generate never writes charter.md &lt;strong&gt;at all&lt;/strong&gt;” left a fresh project with no companion and no signal that one should exist (and stranded the FR-009 golden-path affordance). Refined: the &lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;charter generate&lt;/code&gt; command&lt;/strong&gt; now seeds a minimal starter &lt;code dir=&quot;auto&quot;&gt;charter.md&lt;/code&gt; &lt;strong&gt;only when the file is absent&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;_seed_charter_md_companion_if_absent&lt;/code&gt;). This is &lt;em&gt;create-if-absent&lt;/em&gt; — an existing curated &lt;code dir=&quot;auto&quot;&gt;charter.md&lt;/code&gt; is left byte-for-byte untouched, so the never-clobber invariant (#2772 / IC-03, pinned by &lt;code dir=&quot;auto&quot;&gt;test_generate_force_preserves_curated_charter_prose_2772&lt;/code&gt;) is fully preserved, and the companion is discoverable. &lt;code dir=&quot;auto&quot;&gt;charter.md&lt;/code&gt; remains display-only and never a resolving input.&lt;/p&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;#2773 ships &lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt; with authorable governance/directive/catalog fields; its migration is a deterministic idempotent yaml→yaml fold (second run reports 0 changes).&lt;/li&gt;
&lt;li&gt;No &lt;code dir=&quot;auto&quot;&gt;charter generate&lt;/code&gt;/compile path writes &lt;code dir=&quot;auto&quot;&gt;charter.md&lt;/code&gt; without an explicit guard; a regression test pins that curated prose survives a refresh.&lt;/li&gt;
&lt;li&gt;By mission end (same PR): &lt;code dir=&quot;auto&quot;&gt;extractor.py&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;SECTION_MAPPING&lt;/code&gt; is deleted; governance/directive loaders read &lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt;; a grep shows no runtime governance decision reads &lt;code dir=&quot;auto&quot;&gt;charter.md&lt;/code&gt; prose.&lt;/li&gt;
&lt;li&gt;Activation is relocated: &lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt; no longer carries &lt;code dir=&quot;auto&quot;&gt;activated_*&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;commit_plan&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;merge_defaults&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;PackContext.from_config&lt;/code&gt; read/write &lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt; overlays &lt;code dir=&quot;auto&quot;&gt;default.yaml&lt;/code&gt; (layer-0); the activation-parity/DRG-filter behavior is preserved (existing activation tests green).&lt;/li&gt;
&lt;li&gt;Confidence: &lt;strong&gt;high&lt;/strong&gt; on the losslessness/determinism facts (traced to &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt; lines); &lt;strong&gt;medium&lt;/strong&gt; on authoring-UX ergonomics, which the fast-follow will validate with real operator authoring.&lt;/li&gt;
&lt;/ul&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;option-x--adr--reshape-2773-to-carry-the-full-inversion-in-one-branchpr&quot;&gt;Option X — ADR + reshape #2773 to carry the full inversion in one branch/PR&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; cuts the schema once; delivers the operator’s direction as a consistent, reviewable whole (no half-inverted intermediate state ships); de-risked by the empirical trace; eliminates the clobber at its single site; fully folds #2772.
&lt;strong&gt;Cons:&lt;/strong&gt; materially widens the mission (more WPs, larger PR); commits to the inversion direction within a single review surface.&lt;/p&gt;
&lt;h3 id=&quot;option-y--adr-first-then-shape-2773&quot;&gt;Option Y — ADR-first, then shape #2773&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; fullest end-state pinned before any schema is cut; safest for a structural-boundary change.
&lt;strong&gt;Cons:&lt;/strong&gt; stalls a ready P2 consolidation; the empirical trace already de-risked the decision, so the extra gate buys little.&lt;/p&gt;
&lt;h3 id=&quot;option-z--keep-2773-bounded-invert-separately&quot;&gt;Option Z — keep #2773 bounded; invert separately&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; minimal #2773 now.
&lt;strong&gt;Cons:&lt;/strong&gt; near-certain second schema re-cut + migration on the same brand-new file — the exact split/drift/stopgap churn #2519 exists to end. Rejected as self-defeating for the epic.&lt;/p&gt;
&lt;h3 id=&quot;option-b--chartermd-fully-generated-from-charteryaml-rationale-fields&quot;&gt;Option (b) — charter.md fully generated from charter.yaml rationale fields&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; single-source/deterministic on paper.
&lt;strong&gt;Cons:&lt;/strong&gt; curated rationale (~30 KB, ~7× the structured extract) is not derivable from structured data; authoring rich prose inside YAML block scalars is diff-hostile and fragile; makes the #2772 clobber the &lt;em&gt;normal&lt;/em&gt; path. Rejected — the viable model is a hand-authored companion, not a generated one.&lt;/p&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Assessment + dialectic + empirical resolution: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/consolidate-charter-bundle-01KXSYB9/research/charter-authority-inversion-assessment.md&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Mission spec: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/consolidate-charter-bundle-01KXSYB9/spec.md&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Related: ADR 2026-07-15-1 (activation axis); #2772 (charter.md non-destructive refresh); epic #2519.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;amendment-2026-10-19-decision-2-is-superseded-for-activation-keys&quot;&gt;Amendment 2026-10-19: Decision 2 is superseded for activation keys&lt;/h2&gt;
&lt;p&gt;&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; supersedes &lt;strong&gt;Decision 2 only&lt;/strong&gt; (“&lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt; OWNS activation”). The activation keys (&lt;code dir=&quot;auto&quot;&gt;activated_kinds&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;mission_type_activations&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;activated_&amp;#x3C;plural&gt;&lt;/code&gt;) and the new &lt;code dir=&quot;auto&quot;&gt;deactivated_&amp;#x3C;plural&gt;&lt;/code&gt; deny-lists now live in &lt;code dir=&quot;auto&quot;&gt;.kittify/charter/activation.yaml&lt;/code&gt;, not in &lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt;. A migration moves existing keys. The rest of this ADR stands: &lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt; stays the authoritative structured charter for everything else, &lt;code dir=&quot;auto&quot;&gt;charter.md&lt;/code&gt; stays a curated companion, and the prose-to-triad extractor stays retired. &lt;code dir=&quot;auto&quot;&gt;answers.yaml&lt;/code&gt; is still provenance only.&lt;/p&gt;</content>
</entry>
