Skip to content

ADR: charter offering, active charter and activation presets

Status: Accepted

Date: 2026-10-06

Deciders: Stijn Dejongh (repository owner).

Technical Story: #3732 (rename doctrine packs to charter packs), with #5323 and #4400.

Reader: a maintainer or agent executing the #3732 rename, or changing pack loading, charter activation, the charter / doctrine CLI groups, or the shipped spk-* skills.


Context and Problem Statement

PR #3791 settled two words for the rename of “doctrine pack”: Charter Pack for the offered collection, and Pack Default Charter for the older meaning of “charter pack”. Classifying every occurrence at b327f5bb showed that this was not enough to rename safely:

  • “charter pack” has three meanings in the code, not two. The config key charter_packs.org.packs and the directory .kittify/charter-packs/ already mean the offered collection. spec-kitty charter pack list|path|apply, src/charter/activation/packs/{default,minimal}.yaml and the 3.2.0rc35_default_charter_pack migration mean a ready-made activation set. CharterPackManager, CharterPackConfigError and the error code CHARTER_PACK_CONFIG_INVALID mean a project’s own activation state. The contract had no word for the third meaning.
  • The CLI name was taken twice over. Retiring spec-kitty doctrine sends doctrine pack validate|assemble to charter pack, which already holds the activation-set commands.
  • The “default charter pack” is a drifted copy. default.yaml says it lists every built-in artifact id; it lists about 200, and at b327f5bb it missed 91 shipped artifacts across seven kinds (matching each file by YAML id or filename stem; a stricter match finds about 100). Nothing regenerates it or compares it to packs/built-in/. The rc35 upgrade migration and charter pack apply default write it into .kittify/config.yaml, where a present activated_<kind> key is an allowlist, so those projects silently lose every newer built-in (#5323). Three activation-promotion callers narrow an absent key with the same file (#4400).
  • The presets are not part of any pack. They are registered in a hard-coded BUILTIN_PACKS map in specify_cli and live outside packs/built-in/; the pack descriptor does not know them. Packs are going to ship from the spec-kitty public-packs sidecar repository, where a code-registered preset cannot exist.
  • The spk-doctrine-* skill family mixes two things. Four skills are charter governance (charter, glossary, profile loading, the REASONS canvas); three are working practices unrelated to the charter (bulk-edit classification, semantic compression, show-me visuals). An older spec-kitty-* name layer still ships beside them and often holds the real content.
  • Earlier renames left compatibility layers with no end date. The spec-kitty doctrine group, the doctrine.* config keys and the .kittify/doctrine/ read root each warn once and keep working, with no removal milestone, so in practice they are permanent.

docs/context/charter.md cites ADR 2026-08-22-2 (§74, §76–77) for the earlier definitions, but that ADR is not in the repository. This ADR therefore states the vocabulary in full rather than amending it.

Decision

1. The model: charter offering and active charter

The charter has two sides, matching the existing package split src/charter/offering/ and src/charter/activation/:

TermMeaningReplaces
Charter offeringEverything that is offered to a project: the Charter Packs it can draw from.“doctrine” as the name of the offer-side tier
Charter PackA distributable bundle of interconnected charter components (artifacts and their DRG edges) together with a set of activation presets. An org pack may also enforce activations (required_<kind> in org-charter.yaml).“doctrine pack”
Activation presetA named set of activations that a Charter Pack ships, applied to a project by activating it.“Pack Default Charter”, and the old meaning of “charter pack”
Active charterWhat a project has activated: its activated_<kind> keys and mission_type_activations.the third meaning of “charter pack” (CharterPackManager, CHARTER_PACK_CONFIG_INVALID)
Charter BundleUnchanged: the materialised .kittify/charter/ tree.—

“Active” and “inactive” still describe a single artefact’s state (“an active directive”). The glossary guard that “active” never describes bundle state is amended: active charter names the project’s activated set as a whole.

2. Applying a preset is an activation

spec-kitty charter activate --pack <pack> --preset <preset>

--pack defaults to built-in. The built-in pack ships two presets:

  • default: every built-in artifact, plus the built-in mission types. It is expressed as no per-kind restriction (the per-kind keys stay absent, which already means “all built-ins”), never as a list of ids, so it cannot drift from the shipped inventory.
  • minimal: the curated small baseline (today’s minimal.yaml).

Skipping charter activation during spec-kitty init is the same as charter activate --pack built-in --preset default. Today’s fresh init already behaves this way for artifact kinds: it writes only mission_type_activations and leaves the per-kind keys absent. It reads that mission-type list from src/charter/activation/packs/default.yaml and fails closed when the file is missing (provision_default_mission_type_activations, DefaultCharterPackMissingError); that read moves with the preset, to the built-in pack’s default preset.

3. Presets are pack data

A preset lives inside its pack, next to the pack’s components, and is discovered from the pack, for the built-in pack and for any fetched or org pack alike. There is no code registry of presets. src/charter/activation/packs/ and BUILTIN_PACKS are removed. The pack descriptor field accompanies_doctrine_pack, which described a separate pack accompanying a doctrine pack, is retired: a pack carries its own presets.

4. The CLI

BeforeAfter
charter pack apply <name>charter activate --pack <pack> --preset <preset>
charter pack list (presets only)charter pack list: packs and the presets each one ships
charter pack path <name>charter pack path <pack>
doctrine pack validate, doctrine pack assemblecharter pack validate, charter pack assemble
charter pack consistency-checka top-level charter subcommand; it checks the active charter, not a pack
doctrine regenerate-graph, doctrine asseta home under spec-kitty charter
doctrine mission-type listalready replaced by charter mission-type list --include-inactive; removed with the group
spec-kitty doctrine groupremoved once its last command has moved

charter pack holds operations on Charter Packs (the offering). Activation operations, presets included, stay on charter activate and charter deactivate.

5. Skills

BeforeAfter
spk-doctrine-charterspk-charter-governance
spk-doctrine-glossaryspk-charter-glossary
spk-doctrine-profile-loadspk-charter-profile-load
spk-doctrine-spdd-reasonsspk-charter-spdd-reasons
spk-doctrine-bulk-editspk-practice-bulk-edit
spk-doctrine-semantic-compressionspk-practice-semantic-compression
spk-doctrine-show-mespk-practice-show-me

spk-practice-* is a new family for working practices that apply in any mission. The older spec-kitty-* skills (spec-kitty-charter-doctrine, spec-kitty-glossary-context, spec-kitty-bulk-edit-classification, spec-kitty-spdd-reasons, ad-hoc-profile-load, and the rest of that layer) are folded into the spk-* skill they back and deleted. Each skill ends with one name.

6. Names that stay

  • The doctrine-daphne agent profile keeps its id and name. It is a known persona already in use; “doctrine” there is part of a name, not the retired tier.
  • “Doctrine” as the governance content itself (the substance of a directive or tactic) stays where it is written as content.
  • DIRECTIVE_039 (named for a person) and every historical record (kitty-specs/, released changelog sections, ADRs, dated reports, the archive) are unchanged.

7. Full cutover: no aliases, no shims

Earlier renames kept the old names working for backwards compatibility. The result is a mixed bag of naming and code structures: agents and human contributors meet two names for one thing, and users’ harnesses contradict themselves because one surface uses the old name while another uses the new one. This rename therefore does not repeat that approach. The old names are removed, not deprecated:

  • No alias commands, alias skills or redirecting stubs. An old command name fails as an unknown command.
  • The existing compatibility layers are removed: the deprecated spec-kitty doctrine group (after its commands move), the read-side fallbacks for the doctrine.org.packs and governance.doctrine.* config keys, and the .kittify/doctrine/ read-root fallback.
  • Persisted project state is rewritten once, not shimmed (confirmed by the deciders: a one-time migration is not a compatibility layer). An upgrade migration rewrites legacy config keys and moves .kittify/doctrine/ to .kittify/charter-packs/ during spec-kitty upgrade. The same migration replaces a project’s activated_<kind> lists that equal the drifted default.yaml contents with the default preset’s meaning (key absent), so projects stop losing newer built-ins. After the migration there is no read-side compatibility. A project that has not been upgraded gets an error naming spec-kitty upgrade.

Consequences

Good:

  • One meaning per word on every surface: CLI, config, code, skills, docs.
  • The default preset cannot drift, because it lists nothing.
  • Presets work for packs fetched from the public-packs sidecar repository, not only for the built-in one.
  • Fixes #5323 and #4400 by construction instead of by re-listing ids.
  • Removes four permanent compatibility layers instead of adding more.

Bad:

  • A breaking release for anyone who scripts charter pack apply, spec-kitty doctrine … or a renamed skill. The changelog carries a Before/After table, and the generated agent command and skill copies are regenerated in the same change.
  • A project that skips spec-kitty upgrade stops at the first command, with an error naming the fix.

Neutral:

  • The src/specify_cli/doctrine/ module path and internal Doctrine* identifiers are renamed as internal refactors under the same occurrence map; they are not consumer contracts.

Execution

The rename runs as the #3732 governed mission. Its occurrence map is the classification ledger from the 2026-10-06 run (posted on #3732); this ADR is the naming contract the map binds to.

Amendment 2026-10-06: rulings from the mission specification

The #3732 mission specification (kitty-specs/charter-pack-cutover-01M491G6/spec.md) surfaced ten further questions after its adversarial review. The deciders ruled on them the same day:

  1. doctrine_pack_id is renamed to charter_pack_id. The upgrade migration rewrites project state; the org-charter.yaml schema version is bumped and validation names the field to change in an org pack.
  2. Packs that still carry accompanies_doctrine_pack are rejected with an error naming the field to delete. The public-packs sidecar repository receives a pull request. A validation message that names a replacement is not a compatibility layer.
  3. A removed command fails with the plain unknown-command error. No hint, stub or hidden group; the changelog and the migration runbook carry the message.
  4. The organisation_packs legacy key is removed and migrated with the other legacy keys.
  5. Compatibility residue unrelated to the doctrine vocabulary (for example the charter sync no-op) is out of scope and tracked separately.
  6. Applying a preset over customised activation lists is refused without --force, with the per-key difference printed. The applied preset name is not persisted.
  7. §5 is narrowed for this mission: only the older skills that back the renamed spk-* skills (spec-kitty-charter-doctrine, spec-kitty-glossary-context, spec-kitty-bulk-edit-classification, spec-kitty-spdd-reasons, ad-hoc-profile-load) are folded and deleted. The rest of the spec-kitty-* layer follows in a separate mission.
  8. charter pack consistency-check becomes spec-kitty charter consistency-check, not charter check, to stay clear of validate, lint and bundle validate.
  9. src/specify_cli/doctrine/ is split by meaning, not renamed. It holds code only (no charter content). Pack model and tooling (descriptor, manifest, built-in manifest, lineage, validator, assembler) move to src/charter/offering/packs/; org charter composition (org_charter, org_charter_loader, config) moves to src/charter/activation/; the fetch and scaffold adapters (sources/, snapshot, template_render/) move to src/specify_cli/charter_packs/. Layer-root and org-chain resolution moves into charter, and the architectural boundary exemption for the old package is deleted rather than carried over.
  10. The cutover ships as one mission and one pull request, because a cutover without compatibility layers cannot ship half.

The “Neutral” consequence above (“the src/specify_cli/doctrine/ module path … renamed as internal refactors”) is superseded by ruling 9.

Amendment 2026-10-19: synthesized tactics and activation lists

The charter-governance-resolution Mission (#6404-#6408) settled four points about how activation lists treat synthesized tactics. They refine the activation model above without changing the absent-key default.

  1. Synthesized “how we apply” tactics are reach-only (operator decision 2026-10-18, #6404). A tactic that synthesis created and linked from its directive with directive --suggests--> tactic is never a traversal root. It is delivered only while its directive is active, even when it appears in an explicit activated_tactics list. Hand-authored tactics and org-required tactics stay roots.
  2. Synthesis appends, and never creates the key. charter synthesize and charter resynthesize append the tactic ids a run creates to a present activated_tactics list. They never create the key, so absent-key semantics are unchanged.
  3. An operator’s removal sticks (operator decision 2026-10-19). A tactic the operator removed from activated_tactics is not silently re-added. Synthesis appends a tactic only the first time it creates it, and records every tactic it has created in .kittify/charter/synthesized-tactics.yaml, also when the key is absent. A later run that regenerates the tactic, after a --prune or a deleted manifest, does not append it again. A removed tactic is also not delivered through its directive. Only the operator brings it back (charter activate tactic <id>). Org-required (enforced) tactics stay in force regardless. If the record cannot be read, synthesis appends nothing and warns.
  4. Narrowing is opt-in. charter activate --only and charter interview --narrow-activation (#6408) set a kind’s list to the selection plus org-required ids. The absent-key default and the preserve-don’t-narrow rule are unchanged.
  5. Reach-only and removal-sticks cover synthesized styleguides (operator decision 2026-10-19, #6442). The testing_philosophy, quality_gates and documentation_policy interview sections source their styleguide from a fixed directive (DIRECTIVE_034, DIRECTIVE_030 and DIRECTIVE_037). Synthesis links it with directive --suggests--> styleguide, only when that directive is in the run’s DRG snapshot. Such a styleguide follows points 1 to 3 above: it is never a traversal root, it is delivered only while its directive is in force (also with an explicit activated_styleguides list or an absent key), it is appended to an explicit activated_styleguides list only the first time it is created, and an absent key stays absent. Unsourced styleguides (language_scope, hand-authored) keep today’s activation semantics, and org-required styleguides stay roots. The record is now the per-kind .kittify/charter/synthesized-artifacts.yaml (created_tactics, created_styleguides). It also reads the unreleased tactic-only .kittify/charter/synthesized-tactics.yaml, which is never written again. If either record cannot be read, synthesis appends nothing for any kind and warns. A source-side styleguide --applies--> X overlay edge on a synthesized styleguide is legacy: reconcile strips and reports it. Styleguides that already sit in the synthesis manifest are not appended on the first recording run (they were not created for the first time by it), so they stay as delivered today.

Amendment 2026-10-19: presets and synthesis under the activation ledger

ADR 2026-10-19-1 refines how presets and synthesis treat a deactivated artifact. The absent-key default is unchanged.

  1. A preset without --force never touches deny keys. A denied id the preset lists stays subtracted, and the preset warns and names it.
  2. charter activate --preset X --force clears exclusions for the ids the preset lists, and the output names them. It is one of the four explicit choices that may change a deny-list.
  3. Synthesis never re-adds a denied tactic or styleguide, also on first creation. This adds to rulings 3 and 5 of Amendment 2026-10-19 above.
  4. The created-artifacts record stays and is not an activation surface. .kittify/charter/synthesized-artifacts.yaml (and the legacy synthesized-tactics.yaml it still reads) records what synthesis created. It does not say what is in force, and the ledger does not read it.