---
type: "API"
title: "Charter CLI Reference"
description: "Narrative reference for the core charter interview/generate/sync/synthesize subcommands, verified against live --help output."
status: "stable"
generated:
  by: "process:dockitty-export"
  at: "2026-11-06T00:00:00Z"
---

# 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](/guides/how-to/governance/synthesize-doctrine.md).
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](/api/cli-commands.md#spec-kitty-charter).

---

## spec-kitty charter

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

**Description**: Charter management commands.

| Subcommand | Description |
| --- | --- |
| `interview` | Capture charter interview answers for later generation |
| `generate` | Generate charter bundle from interview answers + doctrine references |
| `context` | Render charter context for a specific workflow action |
| `status` | Display charter sync status plus synthesis/operator state |
| `synthesize` | Validate and promote agent-generated project-local doctrine artifacts |
| `resynthesize` | Regenerate a bounded set of project-local doctrine artifacts (partial resynthesis) |
| `lint` | Detect decay in charter artifacts via graph-native checks |
| `bundle` | Charter bundle validation commands |
| `activate` | Activate 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](/api/cli-commands.md#spec-kitty-charter-activate) |
| `deactivate` | Deactivate a doctrine artifact by kind and ID (FR-005), with optional cascade — see [CLI Command Reference](/api/cli-commands.md#spec-kitty-charter-deactivate) |
| `preflight` | Verify charter-derived state before a governed session begins — see [CLI Command Reference](/api/cli-commands.md#spec-kitty-charter-preflight) |
| `list` | List activated charter artifacts by kind; `--all --json` rows in `available` carry `declared_id` beside the stem-keyed `artifact_id` — see [CLI Command Reference](/api/cli-commands.md#spec-kitty-charter-list) |
| `mission-type` | Mission type commands (activated types only) — see [CLI Command Reference](/api/cli-commands.md#spec-kitty-charter-mission-type) |
| `pack` | Charter pack management commands — see [CLI Command Reference](/api/cli-commands.md#spec-kitty-charter-pack) |
| `org` | Org 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](/api/cli-commands.md#spec-kitty-charter-org) |

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](#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`.

| Flag | Description | Default |
| --- | --- | --- |
| `--mission-type TEXT` | Mission type for charter defaults | `software-dev` |
| `--profile TEXT` | Interview profile: `minimal` or `comprehensive` | `minimal` |
| `--defaults` | Use deterministic defaults without prompts | — |
| `--selected-paradigms TEXT` | Comma-separated paradigm IDs override | — |
| `--selected-directives TEXT` | Comma-separated directive IDs override | — |
| `--available-tools TEXT` | Comma-separated tool IDs override | — |
| `--narrow-activation` | Replace (not append to) activated directives, tactics and paradigms with the selection plus org-required ids; kinds with no selection are untouched | — |
| `--mission-slug TEXT` | Mission slug for decision moment paper trail (optional) | — |
| `--json` | Output 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:

```yaml
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**:
```bash
# 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.

| Flag | Description | Default |
| --- | --- | --- |
| `--mission-type TEXT` | Mission type for template-set defaults | — |
| `--template-set TEXT` | Override charter offering template set (must exist in packaged charter offering missions) | — |
| `--from-interview` / `--no-from-interview` | Load interview answers if present | `--from-interview` |
| `--profile TEXT` | Default profile when no interview is available | `minimal` |
| `--force`, `-f` | Overwrite existing charter bundle | — |
| `--json` | Output JSON | — |

**Examples**:
```bash
# 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](https://github.com/spec-kitty/spec-kitty/issues/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.

| Flag | Description | Default |
| --- | --- | --- |
| `--adapter TEXT` | Adapter to use: `generated` (validates agent-authored YAML under `.kittify/charter/generated/`) or `fixture` (offline/testing only) | `generated` |
| `--dry-run` | Stage and validate artifacts but do not promote to live tree | — |
| `--json` | Output JSON | — |
| `--skip-code-evidence` | Skip code-reading evidence collection | — |
| `--skip-corpus` | Skip best-practice corpus loading | — |
| `--dry-run-evidence` | Print evidence summary and exit without running synthesis | — |

**Examples**:
```bash
# 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`.

| Flag | Description | Default |
| --- | --- | --- |
| `--topic TEXT` | Structured topic selector: `<kind>:<slug>` (project-local), `<drg-urn>` (built-in+project graph), or `<interview-section-label>` | — |
| `--list-topics` | List valid structured topic selectors and exit | — |
| `--adapter TEXT` | Adapter to use (`generated` or `fixture`) | `generated` |
| `--skip-code-evidence` | Skip code-reading evidence collection | — |
| `--skip-corpus` | Skip best-practice corpus loading | — |
| `--json` | Output JSON | — |

**Examples**:
```bash
# 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.

| Flag | Description | Default |
| --- | --- | --- |
| `--json` | Output JSON | — |
| `--provenance` | Include per-artifact provenance details | — |

**Examples**:
```bash
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](#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](#local-shapes-not-the-activation-contract).

| Field | Type | Meaning |
| --- | --- | --- |
| `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 |
| `path` | string | The file actually read, relative to the project when it is inside it |
| `exists` | bool | Whether 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, ...]` \| `null` | Mission-type activations; `null` when the key is absent |
| `activated_kinds` | `[kind, ...]` \| `null` | `null` 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:

```json
"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:

```json
"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).

| Flag | Description | Default |
| --- | --- | --- |
| `--mission TEXT` | Scope lint to a specific mission slug | — |
| `--orphans` | Run only orphan checks | — |
| `--contradictions` | Run only contradiction checks | — |
| `--stale` | Run only staleness checks | — |
| `--json` | Output findings as JSON | — |
| `--severity TEXT` | Minimum severity (`low`/`medium`/`high`/`critical`) | `low` |

**Examples**:
```bash
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.

| Flag | Description | Default |
| --- | --- | --- |
| `--action TEXT` | Workflow action (`specify`, `plan`, `implement`, `review`) | **required** |
| `--mark-loaded` / `--no-mark-loaded` | Persist first-load state | `--mark-loaded` |
| `--json` | Output JSON | — |

**Examples**:
```bash
# 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:

```json
{"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.

| `code` | When it fires |
| --- | --- |
| `UNKNOWN_SELECTION_DROPPED` | A 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_APPLIED` | No activation key is set for paradigms or directives, so the built-in catalog default is the base set. |
| `FALLBACK_APPLIED` | The charter selects no `available_tools` (the runtime tool registry is used) or no `template_set` (the fallback template set is used). |
| `SELECTION_MERGED` | Tools, 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_REFERENCE` | A 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.

| Flag | Description | Default |
| --- | --- | --- |
| `--json` | Emit structured JSON to stdout instead of a human-readable report | — |

**Examples**:
```bash
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](/adr/4.x/2026-10-19-1-activation-ledger-persists-deactivation.md),
glossary: [Activation ledger](/context/charter.md#activation-ledger)). Their flags are in
the generated [CLI Command Reference](/api/cli-commands.md#spec-kitty-charter-activate); this
section describes what they do with the ledger and what they print.

**Where activation is read from.**

| Project state | Reads | Writes |
| --- | --- | --- |
| The activation ledger exists | the activation ledger | the 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 before | allow 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`](#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:

  ```text
  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 <scope>\` … to activate the referenced artifacts` line
  follows only while at least one reference is still not in force: when they are all in
  force, `--cascade` would 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:

```text
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](#error-envelope-and-codes) 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](#presets-and-exclusions)). `--json` with neither a positional
`KIND ARTIFACT_ID` nor `--preset` is a usage error.

**Change report.**

| Field | Type | Meaning |
| --- | --- | --- |
| `schema_version` | `"1.0.0"` | Local schema version of this payload |
| `command` | `"activate"` \| `"deactivate"` | The command that ran |
| `kind` | string | The `KIND` argument as given (operator token) |
| `id` | string | The `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]` \| `null` | `activate --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](#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 |
| `cascade` | object \| `null` | The 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.

| Field | Entries | Meaning |
| --- | --- | --- |
| `source_urn` | string | The cascade source |
| `scope` | `"all"` or `[kind, ...]` | The parsed `--cascade` value |
| `cascaded` | `ArtifactRef` | Activated (or, for `deactivate`, deactivated) by the walk |
| `reinstated` | `ArtifactRef` | Activated with its exclusion cleared (`--include-deactivated`) |
| `failed` | `ArtifactRef` + `message` | This target failed; the command carries on |
| `skipped_out_of_scope` | `ArtifactRef` + `deactivated` (bool) | Outside the scope; `deactivated: true` when the node is itself deactivated and nothing behind it was walked |
| `skipped_deactivated` | `ArtifactRef` + `required_by` (`[urn]`) | `activate`: deactivated, so not activated; `required_by` names the requiring parents (`[]` when reached only through `suggests`) |
| `unreached_behind_deactivated` | `ArtifactRef` | `activate`: reachable only through a deactivated artifact |
| `skipped_kind_filtered` | `ArtifactRef` | A kind that cannot be activated (for example `asset`) |
| `skipped_shared` | `ArtifactRef` + `referenced_by` (urn) | `deactivate`: still referenced by another active artifact |
| `skipped_required` | `ArtifactRef` + `packs` (`[string]`) | `deactivate`: required by these org packs |
| `still_active_unrestricted` | `ArtifactRef` | `deactivate`: 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):

```json
{
  "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`:

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

```json
{"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`.

| Code | Command(s) | Cause | Exit |
| --- | --- | --- | --- |
| `ACTIVE_CHARTER_CONFIG_INVALID` | all three | `charter.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 project | 1 |
| `CHARTER_CONFIG_SHAPE_INVALID` | status | The config shape error of the evidence reader; reachable only after the soundness check passed | 1 |
| `CHARTER_STATUS_FAILED` | status | Repository or task resolution failed, or the charter bundle is not compatible with this CLI | 1 |
| `INTERNAL_ERROR` | status | An unexpected exception; the only message that starts `Unexpected error:` | 1 |
| `ACTIVATION_KIND_UNKNOWN` | activate, deactivate | `KIND` is not an activation kind; the message lists the valid kinds | 1 |
| `CASCADE_SCOPE_INVALID` | activate, deactivate | A bad `--cascade` value | 1 |
| `CHARTER_WRITE_ROOT_INVALID` | activate, deactivate | The command ran where activation cannot be written (a linked worktree) | 1 |
| `DEACTIVATION_REFUSED_REQUIRED` | deactivate | An org pack requires the id; `error.requiring_packs` lists the packs | 1 |
| `ACTIVATION_FAILED` | activate, deactivate | The 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 projection | 1 |
| `RESYNTHESIS_FAILED` | activate, deactivate (`--json`) | The change is recorded, but the catalog refresh after it failed; `error` carries the change report and `detail` | 1 |

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

```json
{"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.

| Code | Level | Meaning |
| --- | --- | --- |
| `ACTIVATION_STORE_ERROR` | error | The activation ledger, or an org pack's required floor, cannot be read |
| `LEGACY_DENY_KEY` | error | A `deactivated_<kind>` key on `charter.yaml` or `config.yaml` of an unmigrated project; never applied |
| `LEGACY_KEYS_PRESENT` | error | An activation key in `charter.yaml` or `config.yaml` beside the activation ledger; ignored |
| `ACTIVATION_UNMIGRATED` | warning | An activation key not moved yet; reads still use the old surface |
| `REQUIRED_OMITTED_BY_ALLOW_LIST` | warning | An explicit allow list leaves out an org-required id, so it is not in force |
| `DENY_UNKNOWN_ID` | warning | An exclusion names an id no layer provides |
| `DENY_REQUIRED_ID` | warning | An exclusion names an org-required id; the required floor wins, so it has no effect |
| `DENY_SELECTED_ID` | warning | `answers.yaml` selects an excluded id; the exclusion wins |
| `UNKNOWN_DENY_KEY` | warning | A `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.

| Key | Code | Entry | Checks |
| --- | --- | --- | --- |
| `body_path_escapes` | `ORG_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_escapes` | `ORG_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).

| Surface | Where the finding appears | What names it |
| --- | --- | --- |
| `spec-kitty charter status` | `org_layer.errors`, and the human organisation-layer section | the same message the doctor writes: the pack, the node or asset, the path |
| `spec-kitty charter org validate` | one error issue per escape, exit 1 | category `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.

```json
{
  "result": "moved",
  "moves": [{"key": "activated_directives", "from": ".kittify/charter/charter.yaml", "to": ".kittify/charter/activation.yaml"}],
  "refusal": null,
  "ledger_record": "written"
}
```

| Field | Values |
| --- | --- |
| `result` | `noop`, `dry_run`, `moved`, `refused` |
| `moves` | `{key, from, to}` per key and file, paths relative to the project |
| `refusal` | `null`, or `{key, files, reason}` with `reason` `divergent` or `legacy_deny_key` |
| `ledger_record` | `written`, 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

- [How Charter Works](/context/charter-overview.md)
- [How to Synthesize and Maintain Doctrine](/guides/how-to/governance/synthesize-doctrine.md)
- [Governance Files Reference](/context/governance-files.md)
- [Activation Preset Usage Journey](/architecture/charter-pack-usage-journey.md) — the `charter
  activate --preset` → `charter generate` two-step and the dispatch safety net (`charter pack` flags: see the
  generated [CLI Command Reference](/api/cli-commands.md#spec-kitty-charter-pack))

## Related

- [Activation Preset Usage Journey: Activate, Generate, and the Dispatch Safety Net](/architecture/charter-pack-usage-journey.md)
- [How Charter Works](/context/charter-overview.md)
- [Governance Files Reference](/context/governance-files.md)
