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.packsand the directory.kittify/charter-packs/already mean the offered collection.spec-kitty charter pack list|path|apply,src/charter/activation/packs/{default,minimal}.yamland the3.2.0rc35_default_charter_packmigration mean a ready-made activation set.CharterPackManager,CharterPackConfigErrorand the error codeCHARTER_PACK_CONFIG_INVALIDmean 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 doctrinesendsdoctrine pack validate|assembletocharter pack, which already holds the activation-set commands. - The “default charter pack” is a drifted copy.
default.yamlsays it lists every built-in artifact id; it lists about 200, and atb327f5bbit missed 91 shipped artifacts across seven kinds (matching each file by YAMLidor filename stem; a stricter match finds about 100). Nothing regenerates it or compares it topacks/built-in/. The rc35 upgrade migration andcharter pack apply defaultwrite it into.kittify/config.yaml, where a presentactivated_<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_PACKSmap inspecify_cliand live outsidepacks/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 olderspec-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 doctrinegroup, thedoctrine.*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/:
| Term | Meaning | Replaces |
|---|---|---|
| Charter offering | Everything that is offered to a project: the Charter Packs it can draw from. | “doctrine” as the name of the offer-side tier |
| Charter Pack | A 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 preset | A 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 charter | What a project has activated: its activated_<kind> keys and mission_type_activations. | the third meaning of “charter pack” (CharterPackManager, CHARTER_PACK_CONFIG_INVALID) |
| Charter Bundle | Unchanged: 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’sminimal.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
| Before | After |
|---|---|
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 assemble | charter pack validate, charter pack assemble |
charter pack consistency-check | a top-level charter subcommand; it checks the active charter, not a pack |
doctrine regenerate-graph, doctrine asset | a home under spec-kitty charter |
doctrine mission-type list | already replaced by charter mission-type list --include-inactive; removed with the group |
spec-kitty doctrine group | removed 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
| Before | After |
|---|---|
spk-doctrine-charter | spk-charter-governance |
spk-doctrine-glossary | spk-charter-glossary |
spk-doctrine-profile-load | spk-charter-profile-load |
spk-doctrine-spdd-reasons | spk-charter-spdd-reasons |
spk-doctrine-bulk-edit | spk-practice-bulk-edit |
spk-doctrine-semantic-compression | spk-practice-semantic-compression |
spk-doctrine-show-me | spk-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-daphneagent 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 doctrinegroup (after its commands move), the read-side fallbacks for thedoctrine.org.packsandgovernance.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/duringspec-kitty upgrade. The same migration replaces a project’sactivated_<kind>lists that equal the drifteddefault.yamlcontents with thedefaultpreset’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 namingspec-kitty upgrade.
Consequences
Good:
- One meaning per word on every surface: CLI, config, code, skills, docs.
- The
defaultpreset 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 upgradestops at the first command, with an error naming the fix.
Neutral:
- The
src/specify_cli/doctrine/module path and internalDoctrine*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:
doctrine_pack_idis renamed tocharter_pack_id. The upgrade migration rewrites project state; theorg-charter.yamlschema version is bumped and validation names the field to change in an org pack.- Packs that still carry
accompanies_doctrine_packare 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. - 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.
- The
organisation_packslegacy key is removed and migrated with the other legacy keys. - Compatibility residue unrelated to the doctrine vocabulary (for example the
charter syncno-op) is out of scope and tracked separately. - Applying a preset over customised activation lists is refused without
--force, with the per-key difference printed. The applied preset name is not persisted. - §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 thespec-kitty-*layer follows in a separate mission. charter pack consistency-checkbecomesspec-kitty charter consistency-check, notcharter check, to stay clear ofvalidate,lintandbundle validate.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 tosrc/charter/offering/packs/; org charter composition (org_charter,org_charter_loader,config) moves tosrc/charter/activation/; the fetch and scaffold adapters (sources/,snapshot,template_render/) move tosrc/specify_cli/charter_packs/. Layer-root and org-chain resolution moves intocharter, and the architectural boundary exemption for the old package is deleted rather than carried over.- 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.
- 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--> tacticis never a traversal root. It is delivered only while its directive is active, even when it appears in an explicitactivated_tacticslist. Hand-authored tactics and org-required tactics stay roots. - Synthesis appends, and never creates the key.
charter synthesizeandcharter resynthesizeappend the tactic ids a run creates to a presentactivated_tacticslist. They never create the key, so absent-key semantics are unchanged. - An operator’s removal sticks (operator decision 2026-10-19). A tactic the operator removed from
activated_tacticsis 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--pruneor 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. - Narrowing is opt-in.
charter activate --onlyandcharter 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. - Reach-only and removal-sticks cover synthesized styleguides (operator decision 2026-10-19, #6442). The
testing_philosophy,quality_gatesanddocumentation_policyinterview sections source their styleguide from a fixed directive (DIRECTIVE_034, DIRECTIVE_030 and DIRECTIVE_037). Synthesis links it withdirective --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 explicitactivated_styleguideslist or an absent key), it is appended to an explicitactivated_styleguideslist 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-sidestyleguide --applies--> Xoverlay 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.
- A preset without
--forcenever touches deny keys. A denied id the preset lists stays subtracted, and the preset warns and names it. charter activate --preset X --forceclears 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.- 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.
- The created-artifacts record stays and is not an activation surface.
.kittify/charter/synthesized-artifacts.yaml(and the legacysynthesized-tactics.yamlit still reads) records what synthesis created. It does not say what is in force, and the ledger does not read it.