---
type: "ADR"
title: "ADR: charter offering, active charter and activation presets"
description: "A Charter Pack bundles charter components with activation presets applied by charter activate; the doctrine names are cut over with no aliases or shims."
status: "stable"
generated:
  by: "process:dockitty-export"
  at: "2026-10-06T00:00:00Z"
---

**Status:** Accepted

**Date:** 2026-10-06

**Deciders:** Stijn Dejongh (repository owner).

**Technical Story:** [#3732](https://github.com/spec-kitty/spec-kitty/issues/3732) (rename doctrine packs to charter packs), with [#5323](https://github.com/spec-kitty/spec-kitty/issues/5323) and [#4400](https://github.com/spec-kitty/spec-kitty/issues/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](https://github.com/spec-kitty/spec-kitty/issues/5323)). Three activation-promotion callers narrow an absent key with the same file ([#4400](https://github.com/spec-kitty/spec-kitty/issues/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/`:

| 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'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

| 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-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](/adr/4.x/2026-10-19-1-activation-ledger-persists-deactivation.md) 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.
