---
type: "Migration"
title: "Migration: Charter Pack Cutover"
description: "Runbook for the charter pack cutover (#3732): run spec-kitty upgrade once, handle LEGACY_CHARTER_STATE and lanes in flight, update packs, and rewrite saved scripts."
status: "stable"
generated:
  by: "process:dockitty-export"
  at: "2026-10-21T00:00:00Z"
---

# Migration: Charter Pack Cutover

**Issue**: [#3732](https://github.com/spec-kitty/spec-kitty/issues/3732)
**Ships in**: spec-kitty-cli 4.0.0rc6
**Audience**: operators who run `spec-kitty` in a project, authors of org Charter Packs, and anyone with saved scripts or CI jobs that call `spec-kitty`.

## What changed

Spec Kitty now uses one name for each idea ([ADR 2026-10-06-1](/adr/4.x/2026-10-06-2-charter-offering-active-charter-and-activation-presets.md)).
A **Charter Pack** is a bundle of charter components that a project can draw from; the packs plus the project's own layer form the **charter offering**.
An **activation preset** is a named set of activations that a pack ships, applied with `spec-kitty charter activate --preset <name>`.
The **active charter** is what your project has activated (`activated_<kind>` keys, `activated_kinds`, `mission_type_activations`).
The older "doctrine" names are removed, not deprecated: the `spec-kitty doctrine` command group, the `doctrine.*` and `organisation_packs` config keys, the `.kittify/doctrine/` directory, the `spk-doctrine-*` skills and their older `spec-kitty-*` twins.
There are no aliases. An old command fails as an unknown command (exit 2), and an old project layout stops every command until you run `spec-kitty upgrade` once.
The glossary entries are in [docs/context/charter.md](/context/charter.md); the full list of renamed names is in [Saved scripts](#saved-scripts) below.

## Operators

### Upgrade a project

Run these from the repository root checkout, on the branch you integrate into:

```bash
spec-kitty upgrade --dry-run     # preview: every line starts with "Would ..."
spec-kitty upgrade               # apply
git status                       # review the moves and rewrites
git add -A && git commit -m "chore: spec-kitty charter pack cutover"
```

The cutover migration runs before every other pending migration, so the later migrations read the new layout.
It is a plain filesystem move plus key rewrites: uncommitted edits under `.kittify/doctrine/` are carried over to `.kittify/charter-packs/` as they are.
Commit the result so teammates and lanes receive it.
A second `spec-kitty upgrade` changes nothing.
If a teammate pulls an older branch that brings the old layout back, `spec-kitty upgrade` selects the cutover again and migrates it again.

### Read the upgrade summary

The summary groups every line of the cutover. `spec-kitty upgrade --json` carries the same lists under `migration_reports.charter_pack_cutover`.

| Report key | Summary prefix | What it means | What you do |
|---|---|---|---|
| `moved` | `Moved` | A file moved from `.kittify/doctrine/` to `.kittify/charter-packs/`. | Commit it. |
| `rewritten` | `Rewrote` | A config key or path reference was renamed (file and key named). | Commit it. |
| `reset` | `Reset` | An activation key was removed because it was a stale copy of an old default list, the old 8-kind gate, the old `minimal` kind gate, or an `[]` written by an earlier upgrade. The kind is now unrestricted (or limited to what your org packs require). | Check the restore hint (below) if you meant to keep it. |
| `kept_for_review` | `Kept for review` | A customized list, or an entry the migration could not convert, was left as it is. | Read the line and edit the file by hand if needed. |
| `matches_minimal` | `Matches preset minimal, kept` | A list equals the released `minimal` preset; it stays. | Nothing, or apply a preset (see [Choosing a starting point](#choosing-a-starting-point)). |
| `skills_removed` | `Removed skill` | An installed copy of a removed skill was deleted. | Nothing; the new skill is installed. |
| `skills_kept` | `Kept edited skill copy` | You edited an installed copy of a removed skill. It is kept, dropped from `.kittify/skills-manifest.json` and is now yours: later upgrades leave it alone. | Delete it when you no longer need it. |
| `errors` | error lines | The run refused (a path collision or a locked file). Nothing in the refused step was written. | Fix the named path and run `spec-kitty upgrade` again. |

### Keys that were reset

Reset lines are there because older releases wrote lists that silently hid every newer built-in artifact. After the reset the key is absent, which means "all built-ins of this kind are in force" (or, where an org pack requires artifacts, only those).

- **A deliberate `[]` was reset.** A per-kind `activated_<kind>: []` cannot be told apart from the empty lists an earlier upgrade wrote, so the cutover removes it and prints a hint naming the file and the key, for example: `To switch the kind off again, set activated_tactics: [] in .kittify/config.yaml.` Put the `[]` back if you meant it. The reset runs only on the first application, so a later `[]` you write stays.
- **The `minimal` kind gate is gone.** Projects that applied the old `minimal` preset carried `activated_kinds: [directives, tactics]`, which switched every other kind off. The new `minimal` preset has no kind gate, so the cutover removes it and says so. To gate kinds again, set `activated_kinds` yourself.
- **A list that matches an old default list** was reset; a list you customized was kept and reported for review.

### Refusals during the upgrade

- **Collision.** When `.kittify/doctrine/` and `.kittify/charter-packs/` both hold the same path with different content, the upgrade refuses and lists every colliding path. Nothing is written. Keep the copy you want under `.kittify/charter-packs/`, delete the other, and run `spec-kitty upgrade` again.
- **Locked file (Windows).** A file held open by an editor or another process stops the move and is named. Close it and run `spec-kitty upgrade` again; the run finishes the remaining moves.

### The activation ledger move (4.0.0rc8)

From 4.0.0rc8 the activation keys (`activated_<kind>`, `activated_kinds`, `mission_type_activations`) live in one file, the activation ledger `.kittify/charter/activation.yaml`, beside the `deactivated_<kind>` exclusions that `charter deactivate` records ([ADR 2026-10-19-1](/adr/4.x/2026-10-19-1-activation-ledger-persists-deactivation.md)).
`spec-kitty upgrade` moves them in its `4.0.0rc8_activation_ledger` step; `spec-kitty migrate activation-ledger` runs only that step:

```bash
spec-kitty migrate activation-ledger --dry-run   # lists each move: key, from-file -> to-file
spec-kitty migrate activation-ledger             # moves them and re-stamps the synthesis manifest
git add .kittify/charter/ .kittify/config.yaml && git commit -m "chore: move activation keys to the activation ledger"
```

- **Until you move them**, every command still reads the old keys as before, `spec-kitty doctor charter-packs` warns `ACTIVATION_UNMIGRATED`, and `charter deactivate` refuses (exit 1, nothing written), naming `spec-kitty upgrade`.
- **Two copies disagree.** When the `charter.yaml` your `charter:` pointer names and a leftover copy in `config.yaml` hold different values for a key, or only the copy holds it, the move names the key and both files, exits 1 and writes nothing. Keep the value you want in the pointed `charter.yaml`, delete the copy from `config.yaml`, and run the command again.
- **A hand-written `deactivated_<kind>` key** in `charter.yaml` or `config.yaml` was never applied; the move refuses it the same way (`LEGACY_DENY_KEY` in doctor). Delete the key, run the move, then record the exclusion with `spec-kitty charter deactivate <kind> <id>`.
- **Interrupted run.** The move writes the activation ledger first, then strips `charter.yaml`, then `config.yaml`. Run the same command again: it strips the keys that equal the activation ledger and finishes. A second run reports nothing to do.
- **The Migration Ledger record.** `migrate activation-ledger` records the step as applied only when `.kittify/migration-ledger.jsonl` already exists (`ledger_record: written`); otherwise it records nothing (`not_recorded`), and a later `spec-kitty upgrade` selects the step, finds nothing to move and skips it.
- **Do not downgrade.** An older CLI does not read the activation ledger: it treats every kind as unrestricted and ignores every deactivation. Activation keys it, or a branch from before the move, writes back into `charter.yaml` or `config.yaml` are ignored with a warning and reported as `LEGACY_KEYS_PRESENT`; after merging such a branch, run `spec-kitty migrate activation-ledger`.

### `LEGACY_CHARTER_STATE`: the project is not migrated yet

Every command refuses a project (or the checkout you are in) that still has the old layout, with exit 1:

```text
Error (LEGACY_CHARTER_STATE): This project uses the retired doctrine layout (<first finding>).
Run `spec-kitty upgrade` to migrate it.
See docs/migrations/charter-pack-cutover.md.
```

In a lane worktree the message adds: upgrade the repository root and merge the target into this lane (do not rebase).

With `--json`, the refusal is one JSON object on stdout instead, with the same exit code 1: `{"ok": false, "error": {"code": "LEGACY_CHARTER_STATE", "message": "..."}}`. The message is the text above without the `Error (LEGACY_CHARTER_STATE):` prefix.

These still run on an unmigrated project, so you can always reach the fix: `spec-kitty upgrade`, `spec-kitty init`, `--version`, `--help`, the git merge drivers (`spec-kitty merge-driver-*`) and the hook entry points (`spec-kitty live-work hook`, `session-start`, `session-stop`, `commit-guard-hook`).
The findings are: the `.kittify/doctrine/` directory, a `governance.yaml` with the old selection key, or one of the old keys in `.kittify/config.yaml` (`doctrine.org`, `organisation_packs`, `governance.doctrine`, `tracker.doctrine`).

### Config that the upgrade does not rewrite

- **`charter_packs.org.local_path` (single-pack form).** Only the named list form is read. Move the fields into one entry of `charter_packs.org.packs[]` with a `name` (not `default`, which is the preset name):

  ```yaml
  charter_packs:
    org:
      packs:
        - name: acme
          local_path: ../acme-charter-pack
  ```

  The old `doctrine.org` single-pack form is rewritten for you: the entry is named after the `local_path` directory (or `org`).
- **`organisation_packs` entries that are not local paths** are kept and reported for review. Declare them under `charter_packs.org.packs[]` with their source fields.
- **Org packs outside the project that use the nested layout** `<pack>/doctrine/<kind>/<layer>/` are no longer read; nor is a repository-root `doctrine/` directory used as the project layer. The upgrade cannot convert files it does not own. `spec-kitty doctor charter-packs` names each one; the pack maintainer moves the artifacts to the flat layout `<pack>/<kind>/`.
- **Agent prompts that still say `/ad-hoc-profile-load`.** Projects that took the 3.2.0rc35 profile hand-off migration have that text in `.kittify/missions/software-dev/command-templates/implement.md` and `review.md`, `.kittify/overrides/missions/software-dev/templates/task-prompt-template.md`, and `.agents/skills/spec-kitty-implement/SKILL.md` and `spec-kitty-review/SKILL.md`. The migration does not run twice, so replace the old skill name yourself: <!-- tool-surface: ignore -->

  ```bash
  grep -rln "ad-hoc-profile-load" .kittify .agents
  # in each file: /ad-hoc-profile-load -> /spk-charter-profile-load
  ```

## Missions in flight

The upgrade skips lane and coordination worktrees. A lane created before the upgrade still carries the old layout, so commands run inside it refuse with `LEGACY_CHARTER_STATE`. Pick one of these:

1. **Upgrade, then merge into each lane.** Upgrade and commit in the repository root checkout (above). Then, in each lane worktree, **merge** the upgraded target branch:

   ```bash
   cd .worktrees/<mission-slug>-lane-<id>
   git merge <target-branch>
   ```

   **Do not rebase the lane.** A rebase rewrites the lane commits, so the lane no longer contains the commit recorded when its work package was approved, and `spec-kitty consolidate` refuses with `APPROVAL_STAMP_NOT_ON_LANE`. A merge keeps the approved commits.
2. **Finish first.** Consolidate the Mission with the release you started it on, then upgrade.

## Choosing a starting point

A preset replaces the activation keys it governs. It refuses to overwrite a key you customized unless you pass `--force`, and prints the per-key difference.

```bash
spec-kitty charter pack list                         # packs and the presets each ships
spec-kitty charter activate --preset default         # every built-in artifact, plus the built-in mission types
spec-kitty charter activate --preset minimal         # a small curated baseline
spec-kitty charter activate --preset minimal --force # overwrite customized keys
spec-kitty charter activate --pack acme --preset team-default   # a preset of an org pack
spec-kitty charter pack path built-in --preset minimal          # print the preset file
```

A fresh `spec-kitty init` already behaves like the `default` preset. The applied preset name is not stored: the result is ordinary activation keys you can edit.

## Pack authors

Update each org Charter Pack you maintain:

1. **`pack.yaml`**: delete `accompanies_doctrine_pack`. A pack that still has it is rejected with `RETIRED_PACK_FIELD`; presets now ship inside the pack.
2. **`org-charter.yaml`**: in every `activations` entry, rename `doctrine_pack_id` to `charter_pack_id` (the old field is rejected with `RETIRED_PACK_FIELD`, whatever the schema version), and set `schema_version: 2`. Version 1 files still load; `spec-kitty charter org init` writes version 2.
3. **Presets** (optional): add `presets/<name>.yaml`. The file name is the preset name (lowercase letters, digits and hyphens).

   ```yaml
   name: team-default
   description: The Acme baseline.
   mission_type_activations: [software-dev]
   activated_directives: [ACME-001]
   # activated_<kind> for directives, tactics, styleguides, toolguides, paradigms,
   # procedures, agent_profiles, mission_step_contracts, anti_patterns.
   # Absent key: unrestricted. []: none of that kind.
   # activated_kinds: optional kind gate; it must include every kind you list ids for.
   ```

   No context-scoped entries. Every id must resolve in the built-in pack, the org pack chain or the project layer. `spec-kitty charter org init` scaffolds `presets/starter.yaml`.
4. **Validate and regenerate**:

   ```bash
   spec-kitty charter pack validate ./my-pack      # also validates presets/
   spec-kitty charter org validate ./my-pack
   spec-kitty charter pack regenerate-graph        # built-in pack maintainers
   ```

5. **Flatten nested layouts**: move `<pack>/doctrine/<kind>/<layer>/` artifacts to `<pack>/<kind>/`.
6. **Replace retired command and skill names** in your procedures, READMEs and skills (see the tables below).

## Saved scripts

Every old spelling exits 2 as an unknown command. Replace it with the new one.

### Commands

| Old | New | Notes |
|---|---|---|
| `spec-kitty charter pack apply <name> [--force]` | `spec-kitty charter activate [--pack <pack>] --preset <name> [--force]` | `--pack` defaults to `built-in`. |
| `spec-kitty charter pack list` (preset rows) | `spec-kitty charter pack list [--json]` | One row per pack with its presets. |
| `spec-kitty charter pack path <preset>` | `spec-kitty charter pack path <pack> [--preset <preset>]` | |
| `spec-kitty charter pack consistency-check` | `spec-kitty charter consistency-check` | `--json` key `missing_from_doctrine` is now `missing_from_offering`. |
| `spec-kitty doctrine pack validate <dir>` | `spec-kitty charter pack validate <dir>` | |
| `spec-kitty doctrine pack assemble …` | `spec-kitty charter pack assemble …` | |
| `spec-kitty doctrine regenerate-graph [--check]` | `spec-kitty charter pack regenerate-graph [--check]` | |
| `spec-kitty doctrine asset list` / `asset path <id>` | `spec-kitty charter pack asset list` / `asset path <id>` | |
| `spec-kitty doctrine fetch` / `new` / `validate` / `org init` / `org validate` | `spec-kitty charter fetch` / `new` / `validate` / `org init` / `org validate` | |
| `spec-kitty doctrine mission-type list` | `spec-kitty charter mission-type list --include-inactive` | |
| `spec-kitty doctor doctrine [--json]` | `spec-kitty doctor charter-packs [--json]` | JSON keys unchanged. |
| `spec-kitty tracker bind --doctrine-mode <m>` | `spec-kitty tracker bind --ownership-mode <m>` | The `doctrine_mode` JSON key is gone; read `ownership_mode`. |
| `spec-kitty doctor tool-surfaces --kind doctrine-skill` | `spec-kitty doctor tool-surfaces --kind charter-skill` | Kind value `charter_skill`; surface ids contain `.charter_skill.`. |

`spec-kitty charter pack list --json` now prints `{"packs": [{"name", "tier", "root", "presets": [{"name", "description", "path"}]}]}`.

### Skills

| Old | New |
|---|---|
| `spk-doctrine-charter`, `spec-kitty-charter-doctrine`, `spec-kitty-constitution-doctrine` | `spk-charter-governance` |
| `spk-doctrine-glossary`, `spec-kitty-glossary-context` | `spk-charter-glossary` |
| `spk-doctrine-profile-load`, `ad-hoc-profile-load` | `spk-charter-profile-load` |
| `spk-doctrine-spdd-reasons`, `spec-kitty-spdd-reasons` | `spk-charter-spdd-reasons` |
| `spk-doctrine-bulk-edit`, `spec-kitty-bulk-edit-classification` | `spk-practice-bulk-edit` |
| `spk-doctrine-semantic-compression` | `spk-practice-semantic-compression` |
| `spk-doctrine-show-me` | `spk-practice-show-me` |

The upgrade removes the old copies from the project skill roots, and the global skill sync removes them from the user-global roots.

### Config keys and paths

| Old | New |
|---|---|
| `doctrine.org.packs[]`, `doctrine.org.{local_path,subdir,source_type,url,ref}`, `organisation_packs[]` | `charter_packs.org.packs[]` |
| `governance.doctrine.*` (`config.yaml`, `charter.yaml`); top-level `doctrine:` in `governance.yaml` | `governance.charter.*`; top-level `charter:` |
| `tracker.doctrine` | `tracker.ownership` |
| top-level `doctrine:` in `.kittify/charter/interview/answers.yaml` | `charter:` |
| `doctrine_pack_id` in `activations` entries | `charter_pack_id` |
| `.kittify/doctrine/` | `.kittify/charter-packs/` |
| `.kittify/doctrine/replaceable-builtins.yaml` | `.kittify/charter-packs/replaceable-builtins.yaml` |

### Error codes

| Old | New | Raised when |
|---|---|---|
| `CHARTER_PACK_CONFIG_INVALID` | `ACTIVE_CHARTER_CONFIG_INVALID` | The active charter config has an invalid shape (also a `governance.doctrine` key left in `charter.yaml`). |
| — | `LEGACY_CHARTER_STATE` | The project still has the old layout. |
| `DefaultCharterPackMissingError` | `DEFAULT_PRESET_MISSING` | The built-in `default` preset is missing during `init`, `charter generate` or upgrade provisioning. |
| — | `PACK_NOT_FOUND`, `PRESET_NOT_FOUND` | `charter activate --preset` or `charter pack path` names an unknown pack or preset. |
| — | `PRESET_ID_UNRESOLVED`, `PRESET_INVALID` | A preset names an id that resolves nowhere, or the preset file is malformed. |
| — | `PRESET_WOULD_OVERWRITE` | A preset would change a customized key and `--force` was not given. |
| — | `RESYNTHESIS_FAILED` | `charter activate --preset … --json` wrote the preset but the follow-up recompile failed; run `spec-kitty charter synthesize`. |
| generic "extra field" error | `RETIRED_PACK_FIELD` | A pack file still has `accompanies_doctrine_pack` or `doctrine_pack_id`. |

Text mode prints coded errors as `Error (<CODE>): <message>`; `--json` mode prints a JSON error object and exits 1.

### Python callers

These Python names changed, with no re-export alias. Update imports if you use Spec Kitty as a library.

| Old | New |
|---|---|
| `CharterPackManager` | `ActiveCharterManager` |
| `CharterPackConfigError` | `ActiveCharterConfigError` |
| `DefaultCharterPackMissingError` | `DefaultPresetMissingError` |
| `DoctrineService` | `CharterOfferingService` (offering) or `ActiveCharterService` (activation-aware) |
| `DoctrineCatalog`, `load_doctrine_catalog` | `OfferingCatalog`, `load_offering_catalog` |
| `DoctrineSelectionConfig` | `GovernanceCharterConfig` |
| `resolve_doctrine_root` | `resolve_offering_root` |
| `build_activation_aware_doctrine_service` | `build_active_charter_service` |
| keyword `doctrine_service=` on `compile_charter` and related functions | `charter_service=` |
| `BaseDoctrineRepository` | `BaseArtifactRepository` |
| `DoctrineLayerCollisionWarning`, `DoctrineArtifactLoadError`, `DoctrineResolutionCycleError` | `ArtifactLayerCollisionWarning`, `ArtifactLoadError`, `ArtifactResolutionCycleError` |
| `OrgDoctrineSource` | `OrgCharterPackSource` |
| `specify_cli.doctrine` | `charter.offering.packs`, `charter.activation` and `specify_cli.charter_packs` |
| `doctrine_service_builder`, `action_doctrine_bundle`, `kernel.doctrine_root`, `specify_cli.doctrine_synthesizer` | `active_charter_service_builder`, `action_governance_bundle`, `kernel.charter_pack_paths`, `specify_cli.charter_pack_synthesizer` |

Removed outright: the `charter.activation.default_pack` module, `BUILTIN_PACKS`, `MissingDoctrinePackError`, `LegacyDoctrineRootWarning`, `LegacyTrackerOwnershipKeyWarning` and `apply_legacy_governance_selection_key_compat`.

## Related

- [ADR: charter offering, active charter and activation presets](/adr/4.x/2026-10-06-2-charter-offering-active-charter-and-activation-presets.md)
- [Changelog](/changelog/CHANGELOG.md)
- [Context: Charter](/context/charter.md)
- [Migrating Shared Doctrine to the Org Layer](/migrations/doctrine-local-overlay-to-org-layer.md)
- [Migration: Relocate Built-In Doctrine to packs/built-in](/migrations/relocate-builtin-doctrine-packs.md)

## Audience

- [Stakeholder Persona: Project Owner](/context/audience/external/project-owner.md) - Written for the Project Owner reader.
