Skip to content

Charter CLI Reference

Note: Examples use uv run spec-kitty ..., which is the source-checkout invocation. If Spec Kitty is installed on your PATH, the same flags work with spec-kitty ....

This page gives a narrative, example-driven walkthrough of the core charter interview/generate/sync/synthesize workflow subcommands. For a task-oriented walkthrough, see How to Synthesize and Maintain Doctrine. For the complete spec-kitty charter subcommand surface — including activate/deactivate (doctrine artifact activation, FR-004/FR-005), preflight, list, mission-type, and pack — see the exhaustive, generated spec-kitty charter section of the CLI Command Reference.


spec-kitty charter

Synopsis: spec-kitty charter [OPTIONS] COMMAND [ARGS]...

Description: Charter management commands.

SubcommandDescription
interviewCapture charter interview answers for later generation
generateGenerate charter bundle from interview answers + doctrine references
contextRender charter context for a specific workflow action
statusDisplay charter sync status plus synthesis/operator state
synthesizeValidate and promote agent-generated project-local doctrine artifacts
resynthesizeRegenerate a bounded set of project-local doctrine artifacts (partial resynthesis)
lintDetect decay in charter artifacts via graph-native checks
bundleCharter bundle validation commands
activateActivate a doctrine artifact by kind and ID (FR-004), with optional cascade; --only replaces the kind’s list with the selection plus org-required ids — see CLI Command Reference
deactivateDeactivate a doctrine artifact by kind and ID (FR-005), with optional cascade — see CLI Command Reference
preflightVerify charter-derived state before a governed session begins — see CLI Command Reference
listList activated charter artifacts by kind; --all --json rows in available carry declared_id beside the stem-keyed artifact_id — see CLI Command Reference
mission-typeMission type commands (activated types only) — see CLI Command Reference
packCharter pack management commands — see CLI Command Reference
orgOrg Charter Pack authoring and project registration: init, validate, and add/remove, which register a pack with the project without hand-editing charter_packs.org.packs in .kittify/config.yaml — see CLI Command Reference

The rows from activate down to pack were added by the Charter Activation Engine; org covers Charter Pack authoring and registration (init, validate, add, remove). This page does not carry their full flag reference (kept in the canonical, --help-generated CLI Command Reference to avoid duplicated, driftable copies) — only interview/generate/context/status/synthesize/ resynthesize/lint/bundle validate get the narrative treatment below. What activate, deactivate and list do with the activation ledger, and what they print, is in Activation and the activation ledger.


spec-kitty charter interview

Synopsis: spec-kitty charter interview [OPTIONS]

Description: Capture charter interview answers for later generation. Saves answers to .kittify/charter/interview/answers.yaml.

FlagDescriptionDefault
--mission-type TEXTMission type for charter defaultssoftware-dev
--profile TEXTInterview profile: minimal or comprehensiveminimal
--defaultsUse deterministic defaults without prompts—
--selected-paradigms TEXTComma-separated paradigm IDs override—
--selected-directives TEXTComma-separated directive IDs override—
--available-tools TEXTComma-separated tool IDs override—
--narrow-activationReplace (not append to) activated directives, tactics and paradigms with the selection plus org-required ids; kinds with no selection are untouched—
--mission-slug TEXTMission slug for decision moment paper trail (optional)—
--jsonOutput JSON (adds languages, languages_source: stored, confirmed, detected or none, languages_notice: a human-readable notice when the list was detected and stored, else null, and narrowed: see below)—

--json narrowed: an object that maps an activation key (for example activated_directives) to the list of ids that stopped being in force because --narrow-activation replaced that key with the selection plus the org-required ids. Only keys that lost at least one id appear. It is {} when --narrow-activation is not given or nothing was narrowed. Without --json the same information prints as No longer in force (N) for <key>: ....

Selection promotion: the captured decisions, directives and paradigms are appended to their activated_<kind> lists when those lists are present. An absent key is never filled (#6685): while it is absent, every available artifact of that kind is in force, so writing a list would only turn “nothing chosen yet” into an activation that charter synthesize reads as one (it would demand a companion tactic per directive and skip the fresh-project seed). The run names each key it left absent, and names any selected id you deactivated separately — the interview never clears a deny list, so that id stays out of force (kept deactivated: directive <id>). --narrow-activation is the way to keep activation narrow and write an explicit list.

The interview decides per kind, not per id: it never checks whether the effective set could be resolved, because every selected id was resolved against the catalogue and a kind whose absent key puts everything in force already has them in force. (charter activate differs: when it cannot resolve the effective set it cannot prove the id is in force, so it writes a list.) A kind whose absent key puts only the org-required set in force, such as skill, is written.

Every selected id is resolved through the same layer-aware authority charter context reads (the project pack, the org packs and the built-in pack), and spec-kitty upgrade’s 4.0.0rc8_promote_interview_selections step uses that same resolver, so an org-pack selection promotes to the same stem from either writer. An id no layer knows is reported (Could not resolve selected <kind> id '<id>'; skipped.) and is not promoted.

Project languages (languages in .kittify/config.yaml): before the questions, the interview detects the repository’s languages (manifests and source counts) and proposes them. You confirm or edit the list, primary language first, and it is stored as a top-level list of catalog tokens:

languages:
- python
- typescript

The key is a plain top-level languages list because charter: (the charter.yaml pointer) and charter_packs: are taken. Other keys and comments in config.yaml are preserved.

  • Precedence. When the key is set it is the single list for both synthesis evidence (languages, with the first entry as the primary language, and no source-count walk) and doctrine scoping (infer_repo_languages, ahead of the compiled catalog.languages and the interview free text; synthesis also makes it the language_scope, one styleguide per language). File detection and free-text parsing apply only when the key is absent.
  • Families. Prefer members (kotlin): a jvm-tagged artifact still matches [kotlin] because families are expanded at match time. A family on its own (jvm, what a declared “Gradle” or “Maven” resolves to) is accepted too and matches jvm-tagged artifacts only.
  • Validation. An entry that is neither a catalog language nor a family (jvm) is refused when written (ValueError; the interview exits 1 and writes nothing). On read it is dropped with a warning; if valid entries remain they alone are used, and if none remain (or the list is empty or not a list) the key reads as absent and detection applies. Answer none to leave the key unset.
  • Re-running. A later interactive interview shows the stored list as the default.
  • Detection rule (20%). A manifest alone only nominates a candidate for the primary language; it never lists a language by itself (a tooling-only package.json in a Python repository does not add javascript). The primary language is always listed; a secondary language is detected only when it holds at least 20% of the counted source files. One rule applies everywhere detection runs: the interview proposal, synthesis evidence and infer_repo_languages.
  • The language step never prompts under --defaults or SPEC_KITTY_NON_INTERACTIVE=1 (or no TTY). Only the language step is non-interactive: without --defaults, the remaining interview questions still prompt. When the key is absent, that step stores the detected list. It never overwrites a stored list. The stored list is detected, not confirmed, so the interview says so: text output prints a Notice naming the stored list, that it was detected and how to change it (edit languages: in .kittify/config.yaml, or re-run spec-kitty charter interview interactively); --json carries languages, languages_source: "detected" and languages_notice.
  • Stored with the answers. The languages are written to config.yaml together with the interview answers, after they are saved. An interview that aborts or fails before that stores neither; a failure to store the languages exits non-zero with the error. If the languages write fails after the answers are saved, the command exits non-zero and re-running is safe.
  • Typos. An interactive answer that is not a catalog list is asked again (up to three attempts), then the interview fails without writing.
  • Compiled catalog. When the key is set, the compiled catalog.languages stamp, and therefore the bundle hash, follows it.

Examples:

Terminal window
# Interactive minimal interview
uv run spec-kitty charter interview
# Non-interactive with defaults
uv run spec-kitty charter interview --profile minimal --defaults --json
# Comprehensive profile
uv run spec-kitty charter interview --profile comprehensive

spec-kitty charter generate

Synopsis: spec-kitty charter generate [OPTIONS]

Description: Refresh charter.yaml’s catalog and metadata sections from interview answers + doctrine references, through the shared load→mutate-owned-section→round-trip-save helper — the governance/directives/activation/overrides sections are preserved byte-for-byte (they are bootstrapped from a legacy triad only the first time charter.yaml is created; every later run leaves them untouched). generate never writes charter.md — it is a curated companion, not a compilation target. On success in a git working tree, the generated charter commit inputs are auto-staged for the follow-up spec-kitty safe-commit step. Requires a git working tree — exits non-zero outside git repos with a git init remediation message. With --from-interview, missing interview answers fail closed; use --no-from-interview to opt into defaults.

FlagDescriptionDefault
--mission-type TEXTMission type for template-set defaults—
--template-set TEXTOverride charter offering template set (must exist in packaged charter offering missions)—
--from-interview / --no-from-interviewLoad interview answers if present--from-interview
--profile TEXTDefault profile when no interview is availableminimal
--force, -fOverwrite existing charter bundle—
--jsonOutput JSON—

Examples:

Terminal window
# Generate from interview answers
uv run spec-kitty charter generate --from-interview --json
# Force regenerate
uv run spec-kitty charter generate --from-interview --force --json
# Override template set
uv run spec-kitty charter generate --from-interview --template-set documentation-default

spec-kitty charter synthesize

Synopsis: spec-kitty charter synthesize [OPTIONS]

Description: Validate and promote agent-generated project-local doctrine artifacts. Reads the charter interview answers, resolves synthesis targets from the DRG + doctrine, and writes all artifacts to .kittify/charter-packs/.

On a fresh project where .kittify/charter/generated/ is missing or empty, this command materializes the minimal artifact set (directory marker and PROVENANCE.md) without running the full adapter pipeline. The runtime falls back to the built-in Charter Pack until a full synthesis run completes.

Synthesis links each synthesized “how we apply” tactic from its directive with a directive --suggests--> tactic edge. It links the styleguide built from a testing, quality-gates or documentation answer the same way, from DIRECTIVE_034, DIRECTIVE_030 and DIRECTIVE_037 (only when that directive is in the graph). Such a tactic or styleguide is reach-only: it is delivered only while its directive is active, even when listed in activated_tactics or activated_styleguides (for styleguides this includes software-dev implement and review). language_scope styleguides have no source directive and keep their existing activation. When the matching activated_* list is present, synthesis appends an id the first time it creates that artifact; it never creates the key. An artifact you remove from the list stays removed: synthesis records every tactic and styleguide it has created in .kittify/charter/synthesized-artifacts.yaml (created_tactics, created_styleguides) and never appends one again, even when a later run regenerates it. A legacy synthesized-tactics.yaml is still read and never written. Bring an artifact back with spec-kitty charter activate tactic <id> or activate styleguide <id>. Re-synthesis replaces legacy applies edges only on the tactics and styleguides the run regenerates and reports the replacement; the others keep the edge until a run regenerates them.

If the record (or the legacy synthesized-tactics.yaml) cannot be read, synthesis appends nothing to any activation list and warns that the file is unreadable. Restore it from version control (git checkout -- <path>, or from an earlier commit) or repair its YAML by hand, keeping every listed id. Do not delete it: synthesis would forget which artifacts it created and add back ones you removed.

One writing synthesis run holds the worktree’s synthesis lock at a time. A second synthesize or resynthesize waits about 10 seconds, then refuses with CHARTER_SYNTHESIS_LOCK_HELD and writes nothing; retry once the other run finishes. --dry-run, --dry-run-evidence and --list-topics take no lock.

charter activate, charter deactivate, charter activate --preset and the activation-ledger migration write under the same lock, and hold it across the whole read-modify-write (#6719). A deactivation that lands while a synthesis run is appending is therefore serialized instead of lost, and the migration’s manifest stamp cannot drop an entry the run just wrote. While another run holds the lock, these commands wait about 10 seconds, then exit 1 with CHARTER_SYNTHESIS_LOCK_HELD, name the lock file and write nothing. Before #6719 they saved their change unlocked and skipped the re-stamp with a warning; that unlocked save was the race. charter interview keeps promoting its selections best-effort: a lock it cannot get is reported as a skipped promotion, not a failure.

The always-synthesized directive is named project-intent-directive; synthesis converges a legacy mission-type-scope-directive first, and spec-kitty upgrade does the same through the 4.0.0rc8_project_intent_directive_rename migration.

The code evidence carries languages, the primary language first, next to primary_language. The primary language is always listed; another language is listed only when it holds at least 20% of the counted sources, and a manifest alone only nominates a candidate. The key is additive in the --json evidence of charter status and charter synthesize --dry-run. It enters the evidence hash only when the list holds more than one language. A configured languages: list (see charter interview) replaces the observed list.

FlagDescriptionDefault
--adapter TEXTAdapter to use: generated (validates agent-authored YAML under .kittify/charter/generated/) or fixture (offline/testing only)generated
--dry-runStage and validate artifacts but do not promote to live tree—
--jsonOutput JSON—
--skip-code-evidenceSkip code-reading evidence collection—
--skip-corpusSkip best-practice corpus loading—
--dry-run-evidencePrint evidence summary and exit without running synthesis—

Examples:

Terminal window
# Validate + promote generated artifacts
uv run spec-kitty charter synthesize
# Dry-run (preview without promoting)
uv run spec-kitty charter synthesize --dry-run
# Use fixture adapter (offline/testing)
uv run spec-kitty charter synthesize --adapter fixture

spec-kitty charter resynthesize

Synopsis: spec-kitty charter resynthesize [OPTIONS]

Description: Regenerate a bounded set of project-local doctrine artifacts (partial resynthesis). Uses a structured selector to identify the target set. Unrelated artifacts are never touched.

Selector forms:

  • directive:PROJECT_001 — regenerate a specific project directive
  • tactic:how-we-apply-directive-003 — regenerate one tactic
  • directive:DIRECTIVE_003 — regenerate every artifact whose provenance references the built-in DIRECTIVE_003 URN
  • testing-philosophy — regenerate all artifacts from that interview section

Resynthesis follows the synthesize rules above: the suggests edge, appended tactic and styleguide ids, the synthesis lock (CHARTER_SYNTHESIS_LOCK_HELD) and legacy applies edges replaced on the artifacts it regenerates.

A directive the project authored itself has nothing to regenerate: the command reports that and exits 0, and you amend the directive by editing its file. A target with the id of a directive synthesis did not create, of an activated org directive or of shipped doctrine is refused, and so is a project agent profile that reuses a shipped profile-id.

FlagDescriptionDefault
--topic TEXTStructured topic selector: <kind>:<slug> (project-local), <drg-urn> (built-in+project graph), or <interview-section-label>—
--list-topicsList valid structured topic selectors and exit—
--adapter TEXTAdapter to use (generated or fixture)generated
--skip-code-evidenceSkip code-reading evidence collection—
--skip-corpusSkip best-practice corpus loading—
--jsonOutput JSON—

Examples:

Terminal window
# Resynthesize a single tactic
uv run spec-kitty charter resynthesize --topic tactic:how-we-apply-directive-003
# Resynthesize all artifacts referencing a built-in directive
uv run spec-kitty charter resynthesize --topic directive:DIRECTIVE_003
# List valid topic selectors
uv run spec-kitty charter resynthesize --list-topics

spec-kitty charter status

Synopsis: spec-kitty charter status [OPTIONS]

Description: Display charter sync status plus synthesis/operator state.

FlagDescriptionDefault
--jsonOutput JSON—
--provenanceInclude per-artifact provenance details—

Examples:

Terminal window
uv run spec-kitty charter status
uv run spec-kitty charter status --json
uv run spec-kitty charter status --provenance

Refusals. charter status first checks that .kittify/charter/charter.yaml is sound. An unparseable, non-mapping or empty file is refused with ACTIVE_CHARTER_CONFIG_INVALID and its remedy, exit 1, before the bundle check, so a list-rooted file no longer reports a bundle schema version problem. A charter: pointer in .kittify/config.yaml that names a missing file is refused the same way, with the remedy for that case: point the key at an existing file or remove it, or re-run spec-kitty charter generate --from-interview. charter status writes nothing, so its refusal text leaves out the “Nothing was written.” line the synthesis commands print for the same check. Every refusal prints Error (<CODE>): <message>; with --json it prints the error envelope instead. See Error envelope and codes for the codes.

JSON output. The success payload keeps its keys (result: "success", charter_sync, synthesis, org_layer, governance_references, freshness) and adds an activation block. The block appears only under --json; the text output does not render it. The success payload has no ok key; only the error envelope does.

The activation block

The block is a local shape (schema_version 1.0.0), not the spec-kitty-charter activation contract; see Local shapes, not the activation contract.

FieldTypeMeaning
schema_version"1.0.0"Local schema version of this block
source"ledger" | "legacy"Where activation was read: the activation ledger, or the old keys of an unmigrated project
pathstringThe file actually read, relative to the project when it is inside it
existsboolWhether the activation ledger file exists
selected{<plural>: [id, ...] | null}One key per activatable kind. null: the kind has no allow list (see below). []: an allow list that is present and empty
deactivated{<plural>: [id, ...]}The exclusions; a kind appears only when it has at least one
mission_types[id, ...] | nullMission-type activations; null when the key is absent
activated_kinds[kind, ...] | nullnull when the key is absent
required[{kind, id, in_force, packs}]The org-required floor, sorted by kind, then id
required_error{code, message}Present only when an org pack’s org-charter.yaml is malformed (unparseable, not a mapping, a required_<plural> that is not a list of ids). required then holds what could still be read

What a null (absent key) puts in force in core today:

  • selected.<plural>: every artifact of that kind, except skills, where only the org packs’ required skills (plus built-in defaults, none today) are in force.
  • mission_types: no mission type, the same as [].
  • activated_kinds: every kind.

Each required row:

  • kind is the operator token (directive, agent-profile, glossary-pack, asset, …).
  • It covers every kind an org pack can require, including a kind that is not activated (asset). An id of such a kind is always in_force: true, since no allow list can leave it out. Ids are normalized to their stored (file-stem) spelling.
  • in_force reflects core’s current rule: it is false when the kind has an explicit allow list that leaves the id out, because core keeps such an id out of force (doctor charter-packs reports it as REQUIRED_OMITTED_BY_ALLOW_LIST). An exclusion never removes an org-required id, so a deactivated required id is still in_force: true. Under the activation contract’s read-time floor (spec-kitty-charter ADR-0020 D7) a required id is in force whatever the document says, so in_force is expected to become always true.
  • packs names the requiring org packs, without repeats.

Example:

"activation": {
"schema_version": "1.0.0",
"source": "ledger",
"path": ".kittify/charter/activation.yaml",
"exists": true,
"selected": {
"directives": [
"003-decision-documentation-requirement"
],
"tactics": null,
"styleguides": null,
"toolguides": null,
"paradigms": null,
"procedures": null,
"agent_profiles": null,
"mission_step_contracts": null,
"glossary_packs": null,
"anti_patterns": null,
"skills": null
},
"deactivated": {
"tactics": [
"premortem-risk-identification"
]
},
"mission_types": [
"software-dev"
],
"activated_kinds": null,
"required": [
{
"kind": "directive",
"id": "001-architectural-integrity-standard",
"in_force": false,
"packs": [
"acme"
]
}
]
}

Here the directives allow list leaves out 001-architectural-integrity-standard, which org pack acme requires, so that id is not in force.

When the activation state cannot be read, the block degrades to its error form and charter status still succeeds, exit 0, with every other section:

"activation": {"schema_version": "1.0.0", "error": {"code": "ACTIVE_CHARTER_CONFIG_INVALID", "message": "..."}}

The error.code is ACTIVE_CHARTER_CONFIG_INVALID (or another internal-consistency code) when the activation state is unsound, for example an activation ledger with an unknown key, and ACTIVATION_STATE_UNREADABLE when the file cannot be read at all (a permission error, for example).


spec-kitty charter lint

Synopsis: spec-kitty charter lint [OPTIONS]

Description: Detect decay in charter artifacts via graph-native checks. Checks for orphaned artifacts, contradictions between directives, and staleness (provenance points to a deleted or superseded built-in directive).

FlagDescriptionDefault
--mission TEXTScope lint to a specific mission slug—
--orphansRun only orphan checks—
--contradictionsRun only contradiction checks—
--staleRun only staleness checks—
--jsonOutput findings as JSON—
--severity TEXTMinimum severity (low/medium/high/critical)low

Examples:

Terminal window
uv run spec-kitty charter lint
uv run spec-kitty charter lint --severity high
uv run spec-kitty charter lint --orphans --json
uv run spec-kitty charter lint --mission my-feature-slug

spec-kitty charter context

Synopsis: spec-kitty charter context [OPTIONS]

Description: Render charter context for a specific workflow action. This is a runtime/debug command for inspecting what governance context an agent would receive. It is not part of the synthesis pipeline.

FlagDescriptionDefault
--action TEXTWorkflow action (specify, plan, implement, review)required
--mark-loaded / --no-mark-loadedPersist first-load state--mark-loaded
--jsonOutput JSON—

Examples:

Terminal window
# Render context for the implement action
uv run spec-kitty charter context --action implement --json
# Render without persisting first-load state (for debugging)
uv run spec-kitty charter context --action specify --no-mark-loaded --json

--json diagnostics (schema 1.4.0). context_schema_version is 1.4.0. The payload carries a top-level diagnostics list, always present ([] when the resolution has nothing to report or fails). Most projects get informational entries (SELECTION_MERGED, FALLBACK_APPLIED, CATALOG_DEFAULT_APPLIED); only UNKNOWN_SELECTION_DROPPED points at a likely mistake. A code may appear more than once. Each entry is an object with exactly two keys:

{"code": "UNKNOWN_SELECTION_DROPPED", "message": "Unknown selected directive 'NOPE_999' dropped: ..."}

Match on code; message is human text and may be reworded without notice. code is one of this closed set. Adding a code is a contract change that bumps the minor version of context_schema_version; a defensive consumer still treats a code it does not recognise as informational.

codeWhen it fires
UNKNOWN_SELECTION_DROPPEDA selected directive or paradigm exists in no layer (built-in, org packs, .kittify/charter-packs/) and was dropped. spec-kitty agent status doctor warns on it and reports the project unhealthy (exit 1).
CATALOG_DEFAULT_APPLIEDNo activation key is set for paradigms or directives, so the built-in catalog default is the base set.
FALLBACK_APPLIEDThe charter selects no available_tools (the runtime tool registry is used) or no template_set (the fallback template set is used).
SELECTION_MERGEDTools, directives or paradigms selected in charter.yaml, or project-local directives, were unioned onto the base set (including the “already present; none added” case).
UNRESOLVED_REFERENCEA reference followed during profile-aware governance resolution resolves to nothing. Part of the closed set, but charter context does not produce it.

The key is additive; consumers that ignore unknown keys are unaffected. Per-code detail: src/charter/activation/ERROR_CODES.md.

--json project_charter.present semantics (authority-of-record). project_charter.present / project_charter.path key on the compiled charter.yaml — the authority-of-record — not on the display-only charter.md. This is intentional and deliberately narrower than “the charter renders”: a project that has a charter.md but has never compiled reports present: false (the charter_md_present / charter_md_path keys expose the display file separately). The human charter context renderer, by contrast, still renders when either file exists — so do not “align” the JSON present to the renderer’s OR-gate; that would re-introduce the charter.md read dependency this surface deliberately retired. External --json consumers should treat charter.yaml as the presence authority.


spec-kitty charter bundle validate

Synopsis: spec-kitty charter bundle validate [OPTIONS]

Description: Validate the charter bundle against CharterBundleManifest v2.0.0. Verifies that both tracked files (charter.md, charter.yaml) are present and correctly structured.

FlagDescriptionDefault
--jsonEmit structured JSON to stdout instead of a human-readable report—

Examples:

Terminal window
uv run spec-kitty charter bundle validate
uv run spec-kitty charter bundle validate --json

Activation and the activation ledger

charter activate, charter deactivate and charter list read and write the activation ledger, .kittify/charter/activation.yaml (ADR 2026-10-19-1, glossary: Activation ledger). Their flags are in the generated CLI Command Reference; this section describes what they do with the ledger and what they print.

Where activation is read from.

Project stateReadsWrites
The activation ledger existsthe activation ledgerthe activation ledger
Fresh (no activation keys anywhere, no activation ledger)the activation ledger (absent keys)the activation ledger; the first write creates it
Unmigrated (activation keys in charter.yaml or config.yaml, no activation ledger)the old allow keys, as beforeallow keys on the old surface; every exclusion is refused

Every activation write here is one read-modify-write under the run-wide synthesis lock, so it serializes with charter synthesize and charter resynthesize; a held lock is a CHARTER_SYNTHESIS_LOCK_HELD refusal with nothing written (see the synthesis-lock rules above).

spec-kitty init writes the activation ledger, so a new project is never unmigrated. spec-kitty upgrade, or the narrow spec-kitty migrate activation-ledger, moves an unmigrated project’s keys. On an unmigrated project, a deactivated_<kind> key written into charter.yaml or config.yaml by hand is never applied. Each command warns about it, spec-kitty doctor charter-packs reports it as LEGACY_DENY_KEY, and the move refuses it. A save of the old surface leaves such a key where it is. Once the activation ledger exists, activation keys found in charter.yaml or config.yaml are ignored with one warning per command and reported as LEGACY_KEYS_PRESENT.

charter deactivate

  • Records an exclusion: the id goes into deactivated_<kind> in the activation ledger and leaves a present activated_<kind> list. This works when the kind has no allow list too (“absent = all”).

  • Refuses, exit 1, writing nothing, when an org pack requires the id. The message names the requiring pack (as 'base' (via 'overlay') when the requirement is inherited through extends:) and the required_<kind> policy: Cannot deactivate directive '<id>': required by org pack 'acme' (required_directives). Nothing was recorded.

  • Refuses, exit 1, writing nothing, on an unmigrated project, before any write and before the required-floor read. A cascade is refused as a whole, so no child is unselected either:

    Refused: activation keys <keys> in <files> have not been moved to
    .kittify/charter/activation.yaml, and a deactivation (deactivated_<kind>) is recorded
    only there. Run `spec-kitty upgrade` (or `spec-kitty migrate activation-ledger`) to move
    them, then retry. Nothing was written.

    A mission-type deactivation records no exclusion and still runs there.

  • An exclusion stays with its artifact when the project-intent directive is renamed (#6443, #6565): spec-kitty upgrade, charter synthesize and charter resynthesize move a NNN-mission-type-scope-directive exclusion to NNN-project-intent-directive in the same write as the allow list, so you do not need to deactivate it again. Only the legacy stem is moved; an entry you spelled as a declared id (DIRECTIVE_003) is untouched, because ids are not renamed.

  • With --cascade, only the named id gets an exclusion. Exclusively referenced children leave their allow list (Cascade-deactivated: kind/id), a child an org pack requires is skipped (Cascade: kind/id: skipped (required by <pack>)), and under a kind with no allow list a child stays in force: Cascade: kind/id: still active (no allow-list; only <id> excluded).

charter activate

  • Clears the artifact’s own exclusion and adds it to a present allow list. --only does the same and narrows the list; ids dropped by narrowing get no exclusion.

  • An absent allow list is never filled (#6685). While activated_<kind> is absent, every available artifact of that kind is in force, so activating one of them changes nothing: the command reports the artifact as activated, writes no list, and says that a list would freeze the kind (Kind 'directive' keeps no explicit activation set, …). Use charter activate <kind> <id> --only to write a list. A kind whose absent key puts only its org-required ids in force (skill) and mission-type still write their list, because there writing nothing would lose the activation. One consequence: --cascade deactivation removes a child only from a kind that has a written list; with none, it reports the child as still active (no allow-list; …) — use charter deactivate <kind> <id> to record an exclusion (#6873).

  • Accepts the file stem or the declared id (024-locality-of-change or DIRECTIVE_024); the allow list keeps one stem spelling per artifact.

  • A mission type is a cascade source: charter activate mission-type <id> --cascade all walks the artifacts the mission type references.

  • The cascade stops at a deactivated artifact. It is reported, and nothing reachable only through it is activated. --include-deactivated (in its own Cascade options help panel, only with --cascade) walks through, activates those artifacts and clears their exclusions.

  • Without --cascade, every referenced artifact the run leaves alone is named, which can be long for a mission type. Two cases, and the report says which is which (#6742):

    • Already in force — the project’s activation state admits it (its kind has no activated_<kind> list, that list already names it, or an org pack requires it). It reads Note: referenced kind/id is already in force (<reason>); not added by this command., where <reason> is no explicit list or listed in activated_<plural>.
    • Not in force — the kind has an explicit list that omits it. It reads Warning: referenced kind/id was not activated (no --cascade).

    A deactivated reference is always a warning, whatever its kind’s list says: Warning: referenced kind/id is deactivated and was not activated.

    The Hint: Re-run with \—cascade ` … to activate the referenced artifactsline follows only while at least one reference is still not in force: when they are all in force,—cascadewould change nothing. The verdict is taken from the state the command leaves behind, so—only` narrowing still reports the references it dropped.

Cascade output, one line per node:

Skipped (out of scope): kind/id
Skipped (out of scope): kind/id (deactivated; nothing behind it was walked)
Skipped, deactivated: kind/id
Skipped, deactivated: kind/id (required by <urn> — the parent no longer has this requirement)
Unreached (behind a deactivated artifact): kind/id
Hint: Run with --include-deactivated to activate these and clear their exclusions.

The Hint line follows when any node was skipped as deactivated or left unreached. With --include-deactivated, each target whose exclusion the walk cleared is reported as Reinstated: kind/id (exclusion cleared).

charter activate / charter deactivate with --json

The positional forms, charter activate KIND ARTIFACT_ID --json and charter deactivate KIND ARTIFACT_ID --json, print exactly one JSON document on stdout: the change report on success, the error envelope on a refusal. The change report is built from the same value the text output prints, so the two never disagree. charter activate --preset <name> --json keeps its own payload (Presets and exclusions). --json with neither a positional KIND ARTIFACT_ID nor --preset is a usage error.

Change report.

FieldTypeMeaning
schema_version"1.0.0"Local schema version of this payload
command"activate" | "deactivate"The command that ran
kindstringThe KIND argument as given (operator token)
idstringThe ARTIFACT_ID argument as given
changed[string]What the direct write activated or deactivated, as the Activated: / Deactivated: lines name it
now_listed[string]activate --only: the kind’s list as written, as the Now listed for <kind> (N): ... line names it; [] otherwise
no_longer_in_force[string] | nullactivate --only: the ids the narrowed list dropped. null when that cannot be determined (the effective set could not be resolved; a warning says why and the text footer reads No longer in force: unknown). [] without --only
warnings[string]Every warning the run printed, in print order (see below)
notices[string]The lines the steps after the change printed (see After the change), in print order
referenced_not_cascaded[ArtifactRef]Without --cascade: the referenced artifacts the Warning: referenced ... lines name — the ones that are not in force; [] with --cascade
referenced_already_in_force[ArtifactRef]Without --cascade: the referenced artifacts the Note: referenced ... is already in force lines name — the ones the project’s activation state already admits; [] with --cascade
referenced_kind_filtered[ArtifactRef]Without --cascade: the referenced artifacts of a kind that cannot be activated, which the Not cascaded: ... lines name; [] with --cascade, where cascade.skipped_kind_filtered carries them
cascadeobject | nullThe cascade report; null without --cascade

An ArtifactRef is {"kind", "id", "urn"}: kind is the operator token (directive, agent-profile, …), id the stored (file-stem) spelling written to the activation files, and urn the DRG URN (<kind>:<declared id>), or null when it does not resolve.

warnings order: for activate mission-type, the in-flight step-removal warnings come first, because they print before the change; then the project registration and activation manager’s warnings, such as the warning that an explicit skill list freezes the org packs’ required skills (for deactivate, also the mission-step default warning of a named agent profile); then the tension findings of activate; then the advisory warnings of cascaded artifacts.

referenced_not_cascaded lists the artifacts that are not in force: the ones that were skipped and those that are deactivated. referenced_already_in_force lists the ones the project’s activation state already admits, so --cascade has nothing to do for them. An artifact appears in at most one of the two lists. Referenced artifacts of a kind that cannot be activated (an asset or a template, for example) are in referenced_kind_filtered instead.

Cascade report (cascade, with --cascade). Each artifact a cascade line names appears in exactly one list, in the order the text output prints it.

FieldEntriesMeaning
source_urnstringThe cascade source
scope"all" or [kind, ...]The parsed --cascade value
cascadedArtifactRefActivated (or, for deactivate, deactivated) by the walk
reinstatedArtifactRefActivated with its exclusion cleared (--include-deactivated)
failedArtifactRef + messageThis target failed; the command carries on
skipped_out_of_scopeArtifactRef + deactivated (bool)Outside the scope; deactivated: true when the node is itself deactivated and nothing behind it was walked
skipped_deactivatedArtifactRef + required_by ([urn])activate: deactivated, so not activated; required_by names the requiring parents ([] when reached only through suggests)
unreached_behind_deactivatedArtifactRefactivate: reachable only through a deactivated artifact
skipped_kind_filteredArtifactRefA kind that cannot be activated (for example asset)
skipped_sharedArtifactRef + referenced_by (urn)deactivate: still referenced by another active artifact
skipped_requiredArtifactRef + packs ([string])deactivate: required by these org packs
still_active_unrestrictedArtifactRefdeactivate: a child of a kind with no allow list, which stays in force

Example, charter activate directive p-dir --no-compile --json (no --cascade; the ids are those of the test fixture project):

{
"schema_version": "1.0.0",
"command": "activate",
"kind": "directive",
"id": "p-dir",
"changed": [
"p-dir"
],
"now_listed": [],
"no_longer_in_force": [],
"warnings": [],
"notices": [
"Catalog not recompiled (--no-compile): catalog.references may go stale until the next `charter generate` or `charter activate --resynthesize`."
],
"referenced_not_cascaded": [],
"referenced_already_in_force": [
{
"kind": "procedure",
"id": "g-proc",
"urn": "procedure:PROCEDURE_G"
},
{
"kind": "styleguide",
"id": "s-style",
"urn": "styleguide:STYLEGUIDE_S"
},
{
"kind": "tactic",
"id": "c-tac",
"urn": "tactic:TACTIC_C"
}
],
"referenced_kind_filtered": [
{
"kind": "asset",
"id": "a-asset",
"urn": "asset:ASSET_A"
}
],
"cascade": null
}

With --cascade all the same three artifacts land in cascade.cascaded, referenced_not_cascaded, referenced_already_in_force and referenced_kind_filtered are [], and the asset the directive references is in cascade.skipped_kind_filtered.

Read the two lists together: referenced_already_in_force is the set --cascade would have found nothing to do for, referenced_not_cascaded the set it would have activated.

Example, charter deactivate directive p1-dir --cascade all --no-compile --json:

{
"schema_version": "1.0.0",
"command": "deactivate",
"kind": "directive",
"id": "p1-dir",
"changed": [
"p1-dir"
],
"now_listed": [],
"no_longer_in_force": [],
"warnings": [],
"notices": [
"Catalog not recompiled (--no-compile): catalog.references may go stale until the next `charter generate` or `charter activate --resynthesize`."
],
"referenced_not_cascaded": [],
"referenced_kind_filtered": [],
"cascade": {
"source_urn": "directive:DIRECTIVE_P1",
"scope": "all",
"cascaded": [
{
"kind": "tactic",
"id": "x-tac",
"urn": "tactic:TACTIC_X"
}
],
"reinstated": [],
"failed": [],
"skipped_out_of_scope": [],
"skipped_deactivated": [],
"unreached_behind_deactivated": [],
"skipped_kind_filtered": [
{
"kind": "asset",
"id": "a-asset",
"urn": "asset:ASSET_A"
}
],
"skipped_shared": [
{
"kind": "tactic",
"id": "t-tac",
"urn": "tactic:TACTIC_T",
"referenced_by": "directive:DIRECTIVE_P2"
}
],
"skipped_required": [
{
"kind": "tactic",
"id": "r-tac",
"urn": "tactic:TACTIC_R",
"packs": [
"acme"
]
}
],
"still_active_unrestricted": [
{
"kind": "styleguide",
"id": "s-style",
"urn": "styleguide:STYLEGUIDE_S"
}
]
}
}

After the change

The catalog refresh and, for a skill, the pack-skill projection run after the change is recorded. Under --json, what they print becomes notices: one entry per non-empty line, with styling removed. That covers the --no-compile notice, a recompile that degraded to a notice (Catalog not recompiled: every activated 'directive' reference is unresolvable ...), and the Skill file synced / Skill file preserved lines and skill warnings. A failure there is reported as a coded error whose error object also carries every field of the change report (schema_version, command, kind, id, changed, notices, …) and detail, the failed step’s own output, exit 1: RESYNTHESIS_FAILED for the catalog refresh, ACTIVATION_FAILED for the pack-skill projection. The change itself stays recorded.

Error envelope and codes

charter status, charter activate (positional form) and charter deactivate report a refusal as Error (<CODE>): <message> in text mode. Under --json they print one error envelope:

{"ok": false, "error": {"code": "ACTIVE_CHARTER_CONFIG_INVALID", "message": "..."}}

Only the error envelope carries ok, and it is always false. A success payload has no ok: charter status keeps result: "success", and the activate/deactivate change report has neither. Detect an error by the presence of ok (or error), not by reading ok from every payload.

The message carries the remedy where there is one. Some codes add fields to error (below). The exit code is the one the same invocation has without --json.

CodeCommand(s)CauseExit
ACTIVE_CHARTER_CONFIG_INVALIDall threecharter.yaml, the activation state or the pack configuration is unsound, or the charter: pointer of .kittify/config.yaml names a missing file; also deactivate of an artifact on an unmigrated project1
CHARTER_CONFIG_SHAPE_INVALIDstatusThe config shape error of the evidence reader; reachable only after the soundness check passed1
CHARTER_STATUS_FAILEDstatusRepository or task resolution failed, or the charter bundle is not compatible with this CLI1
INTERNAL_ERRORstatusAn unexpected exception; the only message that starts Unexpected error:1
ACTIVATION_KIND_UNKNOWNactivate, deactivateKIND is not an activation kind; the message lists the valid kinds1
CASCADE_SCOPE_INVALIDactivate, deactivateA bad --cascade value1
CHARTER_WRITE_ROOT_INVALIDactivate, deactivateThe command ran where activation cannot be written (a linked worktree)1
DEACTIVATION_REFUSED_REQUIREDdeactivateAn org pack requires the id; error.requiring_packs lists the packs1
ACTIVATION_FAILEDactivate, deactivateThe activation engine or DRG load failed (an unknown artifact id, for example); on activate, a declared org pack that was never fetched (run spec-kitty charter fetch); under --json also a failed pack-skill projection1
RESYNTHESIS_FAILEDactivate, deactivate (--json)The change is recorded, but the catalog refresh after it failed; error carries the change report and detail1

charter status can also pass through, unchanged, any other internal-consistency code an underlying reader raises. Treat a code that is not listed here as an error all the same.

ACTIVATION_STATE_UNREADABLE is not a refusal of the command: it appears only as the error.code of the charter status activation block, which degrades while status succeeds (exit 0).

A refusal writes nothing, except RESYNTHESIS_FAILED and the pack-skill ACTIVATION_FAILED, which come after the change was recorded.

Edge cases:

  • A .kittify/config.yaml that is not a mapping is refused by the soundness check as ACTIVE_CHARTER_CONFIG_INVALID. CHARTER_CONFIG_SHAPE_INVALID appears only after that check passed.
  • A malformed charter_packs registry in .kittify/config.yaml is refused by both verbs as ACTIVE_CHARTER_CONFIG_INVALID (#6772): the org pack registry cannot be read, so the pack configuration is unsound. A declared org pack that was never fetched stays a distinct ACTIVATION_FAILED refusal on activate, with the spec-kitty charter fetch remedy in the message.

Usage errors (flag misuse such as --include-deactivated without --cascade) stay Click usage errors: exit 2, printed as usage text, not JSON.

Before this change, charter status --json reported an error as {"result": "error", "success": false, "error": "<message>"}. Consumers that read success or a string error must instead detect the envelope by its ok key and read error.code / error.message. A dangling charter: pointer used to let charter status exit 0; it is now refused with ACTIVE_CHARTER_CONFIG_INVALID.

Local shapes, not the activation contract

The charter status activation block, the activate/deactivate change report, the error envelope and the codes above are local to the Spec Kitty CLI, with schema_version 1.0.0. They are not the spec-kitty-charter activation contract. Mapping them onto that contract (its field names, revision and refusal codes) is held under epic #6518 (#6520, #6521, #6524).

That mapping is semantic, not a rename. The contract (spec-kitty-charter ADR-0020) omits an absent key where these shapes print null, and null is not a contract value. Each absent key keeps its meaning across the mapping: in the contract, absent missionTypes means no mission type, absent activatedKinds every kind, and an absent selected.<kind> the kind’s default. Some local fields have no contract counterpart, and some contract fields (revision, requiredBy as {packId, via}) have no local one yet.

Presets and exclusions

charter activate --preset <name> never clears an exclusion by itself. Without --force, a deactivated id the preset lists is left out of the written list, stays excluded and is reported (Kept deactivated). --force has two effects: it overwrites customized keys, and it clears the exclusion of every deactivated id the preset lists, writing the id into the list (Cleared exclusion). --json adds one key for each case, present only when it is not empty:

{"pack": "built-in", "preset": "minimal", "written": {"activated_directives": ["..."]}, "removed": [],
"target_file": ".../.kittify/charter/activation.yaml",
"kept_deactivated": {"activated_directives": ["024-locality-of-change"]}}

With --force the same run reports "cleared_exclusions": {"deactivated_directives": ["024-locality-of-change"]} instead: kept_deactivated is keyed by the allow key, cleared_exclusions by the deny key.

charter list --json

Four additions to the existing payload:

  • every row of kinds carries deactivated: the kind’s exclusions, sorted ([] when none), and null for mission-type, which has no exclusions;

  • a top-level required_not_in_force appears when an explicit allow list leaves out an org-required id: {"<plural>": [{"id": "<id>", "packs": ["<pack>"]}]}. Core keeps such an id out of force; doctor reports it as REQUIRED_OMITTED_BY_ALLOW_LIST;

  • a top-level required_in_force appears when a kind has no allow list and an org pack requires ids of that kind: {"<plural>": [{"id": "<id>", "packs": ["<pack>"]}]}. Those ids are in force, the same set doctor charter-packs reports with source: org-required. The human table names each one in the Activated cell as <id> — in force: required by '<pack>'.

  • a top-level required_floor_unreadable (["<plural>"]) appears when an org pack’s required floor cannot be read for a kind with no allow list. The listing still succeeds; the table adds the hint “org required floor unreadable — run spec-kitty doctor charter-packs” under that kind.

The human table gains a Deactivated column only when something is deactivated.

Activation ledger findings in spec-kitty doctor charter-packs

--json carries org_drg.activation_ledger = {"errors": [...], "warnings": [...]}. Each finding is {"code", "file", "key", "ids", "message"}, and its message ends with the remedy. An error also lands in org_drg.errors and makes the report unhealthy (exit 1); warnings do not.

CodeLevelMeaning
ACTIVATION_STORE_ERRORerrorThe activation ledger, or an org pack’s required floor, cannot be read
LEGACY_DENY_KEYerrorA deactivated_<kind> key on charter.yaml or config.yaml of an unmigrated project; never applied
LEGACY_KEYS_PRESENTerrorAn activation key in charter.yaml or config.yaml beside the activation ledger; ignored
ACTIVATION_UNMIGRATEDwarningAn activation key not moved yet; reads still use the old surface
REQUIRED_OMITTED_BY_ALLOW_LISTwarningAn explicit allow list leaves out an org-required id, so it is not in force
DENY_UNKNOWN_IDwarningAn exclusion names an id no layer provides
DENY_REQUIRED_IDwarningAn exclusion names an org-required id; the required floor wins, so it has no effect
DENY_SELECTED_IDwarninganswers.yaml selects an excluded id; the exclusion wins
UNKNOWN_DENY_KEYwarningA deactivated_<kind> key for a kind this CLI does not know; kept and ignored

Path escapes in spec-kitty doctor charter-packs

--json always carries two lists under org_drg, each empty when nothing escapes. A path counts as escaping when it is absolute, has a .. part, resolves outside its root (a symlink), or cannot be resolved at all. No target file is opened or read.

KeyCodeEntryChecks
body_path_escapesORG_FRAGMENT_BODY_PATH_ESCAPE{"code", "pack", "node", "kind", "body_path", "reason"}the body_path of each node an org pack declares in drg/fragment.yaml, against the pack root
asset_path_escapesORG_ASSET_PATH_ESCAPE{"code", "pack", "asset", "path", "reason"}the path of each org asset sidecar (assets/*.asset.yaml), against the pack’s assets/ directory

Each escape also lands in org_drg.errors as a message that names the pack, the node or asset and the path, and the report is unhealthy (exit 1). reason is free text; branch on code. If a check cannot run, org_drg.errors says so and its list stays empty. The human output has a fragment body_path escapes: line and an asset path escapes: line in the organisation-layer section. Nodes found from artifact files (for example directives/*.directive.yaml) are not in these lists, and an asset sidecar that does not parse is skipped here; spec-kitty charter pack validate checks both. A sidecar file that lives outside the pack’s assets/ directory (for example through a symlink), and every asset of a pack whose assets/ directory itself resolves outside the pack, are reported as ORG_ASSET_PATH_ESCAPE.

The same rule on charter status and charter org validate

Since #6733 the other two surfaces that report on an org pack also report a fragment body_path or an asset that leaves the pack. charter status reports these findings but still exits 0; the other two exit 1. A pack skill’s body_path is refused when the skill is activated and isn’t reported on these surfaces (#7299).

SurfaceWhere the finding appearsWhat names it
spec-kitty charter statusorg_layer.errors, and the human organisation-layer sectionthe same message the doctor writes: the pack, the node or asset, the path
spec-kitty charter org validateone error issue per escape, exit 1category body_path_escape for a fragment node, asset_path_escape for an asset sidecar; artifact_id is the node or asset id, file is the file that declares it

charter status adds no JSON key: the finding rides the existing org_layer.errors array, the channel it already uses for a dangling edge endpoint. If a containment check cannot run, the array says so (org-layer body_path check failed: ...) rather than reading as “no escapes”.

All three commands write the same sentence for a fragment body_path, an asset path and an assets/ directory outside the pack. charter org validate checks a pack directory rather than a registered pack, so it names the pack by its directory name, while doctor charter-packs and charter status use the name from .kittify/config.yaml. The validator also reports every asset of a pack whose assets/ directory itself resolves outside the pack, as the doctor does.

spec-kitty migrate activation-ledger

Runs only the move of the 4.0.0rc8_activation_ledger upgrade step: the activation keys leave the pointed charter.yaml (or config.yaml, and any leftover config.yaml copy) for the activation ledger, verbatim, and the synthesis manifest is re-stamped. It refuses, exit 1, writing nothing, when two copies of a key disagree or a legacy file holds a deactivated_<kind> key. A re-run reports nothing to do. It records the step in the Migration Ledger only when .kittify/migration-ledger.jsonl already exists.

{
"result": "moved",
"moves": [{"key": "activated_directives", "from": ".kittify/charter/charter.yaml", "to": ".kittify/charter/activation.yaml"}],
"refusal": null,
"ledger_record": "written"
}
FieldValues
resultnoop, dry_run, moved, refused
moves{key, from, to} per key and file, paths relative to the project
refusalnull, or {key, files, reason} with reason divergent or legacy_deny_key
ledger_recordwritten, or not_recorded (dry run, refusal, or no .kittify/migration-ledger.jsonl)

A failure to read the project prints {"ok": false, "error": {"code": ..., "message": ...}} with code NO_PROJECT_ROOT or ACTIVATION_LEDGER_MIGRATION_FAILED, exit 1.

charter.activation.api

charter.activation.api is the public entry point to the activation layer for code outside charter. It now also exports ActivationLedger, load_activation_ledger, resolve_ledger_source, refuse_unmigrated_deny_write, DenyListChoice, DenyListWriteRefused, ActiveCharterConfigError, deny_delta, plan_ledger_migration, apply_ledger_migration, LedgerMigrationPlan, LedgerMove, LedgerMigrationRefusal, LedgerMigrationRefused, ledger_findings, LedgerFinding, LedgerFindings, required_not_in_force and RequiredOmission.


See Also