Skip to content

Migration: Charter Pack Cutover

Who is this for (1)

Issue: #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). 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; the full list of renamed names is in Saved scripts below.

Operators

Upgrade a project

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

Terminal window
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 keySummary prefixWhat it meansWhat you do
movedMovedA file moved from .kittify/doctrine/ to .kittify/charter-packs/.Commit it.
rewrittenRewroteA config key or path reference was renamed (file and key named).Commit it.
resetResetAn 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_reviewKept for reviewA 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_minimalMatches preset minimal, keptA list equals the released minimal preset; it stays.Nothing, or apply a preset (see Choosing a starting point).
skills_removedRemoved skillAn installed copy of a removed skill was deleted.Nothing; the new skill is installed.
skills_keptKept edited skill copyYou 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.
errorserror linesThe 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). spec-kitty upgrade moves them in its 4.0.0rc8_activation_ledger step; spec-kitty migrate activation-ledger runs only that step:

Terminal window
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:

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):

    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:

    Terminal window
    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:

    Terminal window
    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.

Terminal window
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).

    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:

    Terminal window
    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

OldNewNotes
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-checkspec-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 validatespec-kitty charter fetch / new / validate / org init / org validate
spec-kitty doctrine mission-type listspec-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-skillspec-kitty doctor tool-surfaces --kind charter-skillKind 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

OldNew
spk-doctrine-charter, spec-kitty-charter-doctrine, spec-kitty-constitution-doctrinespk-charter-governance
spk-doctrine-glossary, spec-kitty-glossary-contextspk-charter-glossary
spk-doctrine-profile-load, ad-hoc-profile-loadspk-charter-profile-load
spk-doctrine-spdd-reasons, spec-kitty-spdd-reasonsspk-charter-spdd-reasons
spk-doctrine-bulk-edit, spec-kitty-bulk-edit-classificationspk-practice-bulk-edit
spk-doctrine-semantic-compressionspk-practice-semantic-compression
spk-doctrine-show-mespk-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

OldNew
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.yamlgovernance.charter.*; top-level charter:
tracker.doctrinetracker.ownership
top-level doctrine: in .kittify/charter/interview/answers.yamlcharter:
doctrine_pack_id in activations entriescharter_pack_id
.kittify/doctrine/.kittify/charter-packs/
.kittify/doctrine/replaceable-builtins.yaml.kittify/charter-packs/replaceable-builtins.yaml

Error codes

OldNewRaised when
CHARTER_PACK_CONFIG_INVALIDACTIVE_CHARTER_CONFIG_INVALIDThe active charter config has an invalid shape (also a governance.doctrine key left in charter.yaml).
—LEGACY_CHARTER_STATEThe project still has the old layout.
DefaultCharterPackMissingErrorDEFAULT_PRESET_MISSINGThe built-in default preset is missing during init, charter generate or upgrade provisioning.
—PACK_NOT_FOUND, PRESET_NOT_FOUNDcharter activate --preset or charter pack path names an unknown pack or preset.
—PRESET_ID_UNRESOLVED, PRESET_INVALIDA preset names an id that resolves nowhere, or the preset file is malformed.
—PRESET_WOULD_OVERWRITEA preset would change a customized key and --force was not given.
—RESYNTHESIS_FAILEDcharter activate --preset … --json wrote the preset but the follow-up recompile failed; run spec-kitty charter synthesize.
generic “extra field” errorRETIRED_PACK_FIELDA 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.

OldNew
CharterPackManagerActiveCharterManager
CharterPackConfigErrorActiveCharterConfigError
DefaultCharterPackMissingErrorDefaultPresetMissingError
DoctrineServiceCharterOfferingService (offering) or ActiveCharterService (activation-aware)
DoctrineCatalog, load_doctrine_catalogOfferingCatalog, load_offering_catalog
DoctrineSelectionConfigGovernanceCharterConfig
resolve_doctrine_rootresolve_offering_root
build_activation_aware_doctrine_servicebuild_active_charter_service
keyword doctrine_service= on compile_charter and related functionscharter_service=
BaseDoctrineRepositoryBaseArtifactRepository
DoctrineLayerCollisionWarning, DoctrineArtifactLoadError, DoctrineResolutionCycleErrorArtifactLayerCollisionWarning, ArtifactLoadError, ArtifactResolutionCycleError
OrgDoctrineSourceOrgCharterPackSource
specify_cli.doctrinecharter.offering.packs, charter.activation and specify_cli.charter_packs
doctrine_service_builder, action_doctrine_bundle, kernel.doctrine_root, specify_cli.doctrine_synthesizeractive_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.