---
type: "Architecture"
title: "Understanding the Org Layer of the Charter Offering"
description: "How the three-layer charter offering resolves built-in, org, and project artifacts, how provenance tracking works, and how org charter policy composes with the project charter."
status: "stable"
generated:
  by: "process:dockitty-export"
  at: "2026-10-19T00:00:00Z"
---

# Understanding the Org Layer of the Charter Offering

Spec Kitty resolves governance doctrine through the three layers of the **charter offering**:
the **built-in** Charter Pack shipped with the CLI, an optional **org** layer of Charter Packs
fetched from one or more remote sources, and the **project layer** maintained in the
repository's own `.kittify/charter-packs/`. This document
explains the model, the resolution rules, the provenance tags you will see in tooling
output, and the architectural boundary that keeps the three layers cleanly separated.

For step-by-step instructions on producing a pack, see [How to create an org Charter
Pack](/guides/how-to/governance/create-an-org-doctrine-pack.md). For migration guidance from a local
overlay, see [Migrating shared doctrine to the org layer](/migrations/doctrine-local-overlay-to-org-layer.md).

---

## The three-layer model

```
┌────────────────────────────────────────────────────────────┐
│  Project layer:   .kittify/charter-packs/                  │  ← highest precedence
│  (project-local artifacts and exceptions)                  │
├────────────────────────────────────────────────────────────┤
│  Org layer:       configured packs (e.g. ~/.kittify/org/*) │
│  (company-wide directives, profiles, tactics)              │
├────────────────────────────────────────────────────────────┤
│  Built-in layer:  shipped with the spec-kitty package      │  ← lowest precedence
│  (sane defaults for every spec-kitty project)              │
└────────────────────────────────────────────────────────────┘
```

Each layer is a structured set of YAML artifacts — directives, tactics, styleguides,
toolguides, paradigms, procedures, agent profiles, mission step contracts, and DRG
graph extensions. Layers share the same schemas. Their only difference is **where they
live** and **how they are produced**.

| Layer | Source | Owned by | Activation |
|-------|--------|----------|------------|
| Built-in | spec-kitty package | CLI maintainers | Always active |
| Org | Remote pack(s) declared in `.kittify/config.yaml` | Org governance teams | Opt-in per project |
| Project | `.kittify/charter-packs/` in the repository | Project maintainers | Always active when present |

The org layer is **purely additive**. Projects that do not declare an org pack are
unaffected by this feature — the built-in plus project model continues to work exactly
as it did before.

---

## Why the org layer exists

Before the org layer, an organisation that wanted to share governance across many
projects had two unattractive options:

1. **Fork the CLI** to embed company-specific directives into the built-in layer.
2. **Copy/paste** governance artifacts into every project's `.kittify/charter-packs/`.

Both approaches drift over time. Fork maintenance is painful; copy/paste means each
project carries a stale snapshot of the policy.

The org layer solves this by giving organisations a versioned, PR-governed,
independently-released home for their doctrine that any number of projects can consume
without per-project bookkeeping. A security team can ship `security-v2.1.0`, an
architecture team can ship `architecture-v1.4.0`, and a project consumes both by
listing them in its config.

---

## Precedence and resolution

When resolution traverses the three layers, it walks them in order — built-in first,
then each configured org pack in declaration order, finally project — and applies
**full-replace semantics on ID collision**.

> **Full-replace means**: if an artifact ID exists in a higher-precedence layer, that
> artifact entirely replaces the lower-precedence one. There is no field-level merging
> across layers. The higher-layer artifact stands or falls on its own.

### Within the org layer

If you configure multiple org packs, declaration order determines precedence within
the org layer. The **last entry has the highest precedence** — the convention is
"later wins."

```yaml
charter_packs:
  org:
    packs:
      - name: architecture     # lower precedence
        local_path: ~/.kittify/org/architecture/
      - name: security         # higher precedence (declared later)
        local_path: ~/.kittify/org/security/
```

If both packs define `acme-001-secret-handling`, the `security` pack's version wins.

The same rule holds for every dependency-graph (DRG) node an org pack declares in
`drg/fragment.yaml`, whether or not the node also exists in the built-in pack: the
later-declared pack's node replaces the earlier pack's. A relationship (edge) both
packs declare is kept once, with the later pack's provenance and `reason`. Each
replacement is logged as a warning naming both packs. When the merge also refuses
the packs for another reason, the replacement is listed among the reported conflicts
as a `node_override` whose `conflicting_layers` names the overridden pack first.
Edges are additive: replacing a node does not remove the edges an earlier pack
declared from it. (Before 4.0.0rc8 the first-declared pack's node won for a node the
built-in pack does not ship; see the changelog.)

### Across layers

Project beats org. Org beats built-in. The project layer is always free to override
an org artifact for legitimate exceptions. When a project artifact has the same ID as
a higher layer (org or built-in), `spec-kitty charter lint` surfaces an advisory so
the team can confirm the override is intentional.

#### Activation tokens: a file name beats a declared ID

An activation token (an entry of an `activated_<kind>` list in
`.kittify/charter/activation.yaml`) is matched against file names (stems) first,
across every layer, and only then against declared IDs. So a file named `foo` in
any layer wins over another artifact that declares `id: foo`, regardless of which
layer is higher: a project file `DIRECTIVE_024.directive.yaml` that declares
`id: DIRECTIVE_901` takes the token `DIRECTIVE_024`, and the built-in directive that
declares `id: DIRECTIVE_024` is not admitted by it. The reverse holds too: a
lower-layer file name beats a higher-layer declared ID. Layer order decides between
two artifacts with the same ID, not between a file name and a declared ID.

When two layers' files share a file name but declare different IDs, writers refuse
the colliding ID (its file name would select the other artifact); rename the org or
project file (a built-in file cannot be renamed).

This behaviour is pinned by
`tests/charter/activation/test_stem_first_gating_6459.py` and
`tests/charter/activation/test_identity_index.py::test_lookup_is_stem_first_across_layers_then_declared_id`
(#6459).

#### Field-level merge, not artifact-level full replace

When a higher layer declares an artifact ID that already exists in a lower layer,
the higher layer **takes ownership** of the resolved artifact: its `provenance`
becomes that layer. But the merge is **field-level**, not artifact-level full
replace:

- Fields **present** in the higher layer's YAML replace same-named fields in
  the lower layer.
- Fields **absent** from the higher layer fall through to the lower layer's value.

So an org override file that contains only `id`, `title`, and `enforcement`
inherits everything else (intent, scope, examples, …) from the built-in
definition. This keeps override YAML short and focused on what actually
changes. The trade-off is that operators must understand which fields are
inherited and which are overridden.

#### Collision warnings (`ArtifactLayerCollisionWarning`)

Because field-merge is silent by default, the resolver emits a
`ArtifactLayerCollisionWarning` whenever a higher layer shadows a lower-layer
artifact. The warning text records the artifact ID, the higher and lower
layers, and how many fields were replaced vs inherited:

```
Artifact override: directive DIRECTIVE_018 from project shadowed builtin
(3 field(s) replaced; 9 field(s) inherited).
```

These warnings are categorized as `ArtifactLayerCollisionWarning` (a
`UserWarning` subclass), so operators who maintain heavy overrides can
filter them via standard Python `warnings` machinery if desired.

#### Auditing collisions via `spec-kitty doctor charter-packs`

To audit the full set of override collisions across the resolved charter
offering without parsing warning streams, run:

```bash
spec-kitty doctor charter-packs
```

The output includes a `Collisions` section that lists every shadowed
artifact (kind, ID, higher layer, lower layer, field counts), or reports
`none — every artifact resolves from a single layer.` when no overrides
are in play. The same data is available as a `collisions` array under
`--json`.

See [ADR 2026-05-16-1](https://github.com/spec-kitty/spec-kitty/blob/main/docs/adr/3.x/2026-05-16-1-doctrine-layer-merge-semantics.md)
for the rationale behind this design.

---

## Per-mission-type governance override

The same three-layer overlay stack is what carries **per-mission-type governance
customisation** — the charter "activate and customise" step for a mission type.

A project override for a mission type's governance lives at:

```
.kittify/charter-packs/mission_types/<type>/governance-profile.yaml
```

Because it sits under `.kittify/charter-packs/`, it is an ordinary **project-layer**
artifact resolved through the existing `charter/offering/base.py` overlay loader, giving it
the same three behaviours as every other overlaid artifact:

- **Builtin → org → project ordering.** The shipped mission-type governance is the
  builtin layer; an org pack may layer on top; the project override wins last.
- **Field-level merge.** Fields present in the override replace same-named fields;
  absent fields fall through from the lower layer — so an override that adjusts a
  single selection need not restate the whole profile.
- **`ArtifactLayerCollisionWarning`.** The resolver emits the same collision
  warning when the override shadows a lower layer, and `spec-kitty doctor charter-packs`
  audits it alongside every other override.

Reusing the overlay stack is deliberate — it avoids duplicating the layer-merge
contract — but it is **not zero-cost plumbing**. The `base.py` overlay loader keys
project artifacts on an `id` field and skips files that lack one, whereas
`governance-profile.yaml` keys on `mission_type`. Wiring the profile onto the stack
therefore requires an adapter: either giving `MissionTypeProfile` an `id` and a
`BaseArtifactRepository` subclass, or a small explicit field-merge in the resolver.
That adapter is owned, tested work — not a free ride. Modulo that adapter, per-type
governance layering reuses rather than reinvents the merge contract in
[ADR 2026-05-16-1](https://github.com/spec-kitty/spec-kitty/blob/main/docs/adr/3.x/2026-05-16-1-doctrine-layer-merge-semantics.md).
Mission-type governance itself resolves through a single charter-mediated seam
keyed off `meta.json`; this override is the project-tier customisation layer of
that seam. For the whole resolution model — the two governance grains, the reserved
slots for templates and gates, and the leak-closure invariant — see
[Mission-Type Resolution](/architecture/mission-type-resolution.md) and
[ADR 2026-07-14-2](https://github.com/spec-kitty/spec-kitty/blob/main/docs/adr/3.x/2026-07-14-2-doctrine-to-core-mission-type-resolution-unification.md).

## DRG composition

The doctrine reference graph (DRG) is the typed graph that the runtime traverses to
select context for a given action. Each layer can contribute graph **fragments**, and
they merge additively:

- Built-in DRG nodes and edges are always present.
- Org packs contribute additional nodes and edges via `drg/*.graph.yaml` fragments.
- Project DRG fragments compose on top.

DRG fragments from the org layer are **additive only** — they may add new nodes and
new edges, but they must not remove or modify nodes from a lower layer. `spec-kitty
charter pack validate` enforces this and rejects packs whose DRG references dangle
or whose extensions try to delete built-in graph state.

This rule is what keeps the three-layer composition safe: org packs cannot
silently weaken the built-in graph, and projects cannot accidentally weaken org
graph state without a visible override.

---

## Source attribution (provenance)

Every artifact and DRG node carries a `source` tag once it is resolved:

| Tag | Meaning |
|-----|---------|
| `builtin` | Shipped with the CLI |
| `org` | Loaded from a configured org pack |
| `project` | Loaded from `.kittify/charter-packs/` in the repository |

Provenance shows up in two places you can inspect directly:

```bash
# Per-action charter context (shows which artifacts apply)
uv run spec-kitty charter context --action implement --json
```

```bash
# Pack inventory (shows what is installed and where it came from)
uv run spec-kitty doctor charter-packs --json
```

When you see an artifact tagged `source: org`, it tells you the artifact resolved
from one of the packs in your `charter_packs.org.packs` config — not from the project
overlay or the built-in defaults. That signal is what lets a team lead audit "is our
security directive actually live in this project?" without having to grep file trees.

---

## Org charter composition

In addition to artifacts and DRG fragments, an org pack may include an
`org-charter.yaml` at its root. This is a small, structured policy document that
composes with the project charter at interview time.

The `org-charter.yaml` schema has three meaningful fields:

| Field | Purpose |
|-------|---------|
| `interview_defaults` | Pre-fill answers for the project charter interview. The user can still override during the interview. |
| `required_directives` | Directive IDs that the project charter is expected to honour. Surfaced as advisories during lint. |
| `governance_policies` | Free-form policy entries (e.g. minimum test coverage). Advisory-only in this release. |

The merge across multiple packs follows the same "later wins" rule as artifacts:

- `interview_defaults`: dict update; later packs overwrite earlier values.
- `required_directives`: union, preserving first-seen order.
- `governance_policies`: concatenated and deduplicated by `(field, value)`, keeping
  the last occurrence.

Empty packs (no `org-charter.yaml`) contribute no policy — they carry artifacts only.

> **Enforcement note**: In this release, `enforcement` values on
> `governance_policies` are read but treated uniformly as advisory. Only the literal
> string `"advisory"` is honoured today; other values parse and surface as advisories.
> Future releases may add stronger enforcement modes; pack authors should write
> `enforcement: advisory` explicitly to remain forward-compatible.

---

## The fetch model

Org packs are not resolved over the network at runtime. The `charter fetch` command
downloads or refreshes a **local snapshot** under each pack's configured `local_path`,
and every subsequent resolution reads from that snapshot.

This shape was chosen deliberately:

- **CI/CD safety**: pipelines do not depend on remote availability or auth.
- **Determinism**: a project produces the same context on every machine that has
  fetched the same ref.
- **Auditability**: the on-disk snapshot is the record of "what governance ran here."

`charter fetch` is an explicit install/update step, not a background operation. If
your org publishes a new ref, you re-run `charter fetch` (or your IT system does)
to pick it up. This is the same shape as `npm install` or `pip install` — fetch is
the install step; resolution is offline.

For git-managed packs, the local path is a normal working tree of the git clone
(`.git/` present). For HTTPS bundles and HTTP APIs, the snapshot is an atomic
replace of the directory with a `pack-manifest.yaml` recording the fetched version.

---

## Architectural boundary

The org layer respects a strict layer rule:

```
kernel  ←  charter  ←  specify_cli
```

The `charter` package implements DRG composition (`load_validated_graph`) and accepts
an explicit `org_root` argument when present. It must not import from
`specify_cli`. The config-aware resolution — reading `.kittify/config.yaml`
and turning it into a list of pack paths — lives in
`charter.offering.drg.org_pack_config.resolve_org_roots`.

To preserve the boundary, `charter.activation._drg_helpers._resolve_org_root()` is an **inert
stub** that always returns `None`. Real callers resolve the path
themselves and pass it explicitly. This pattern is documented in the source and
enforced by `tests/architectural/test_layer_rules.py` so that no future change can
silently introduce a circular dependency.

If you encounter `_resolve_org_root` in the codebase and wonder why it is empty:
that is the intentional design. The real logic lives in `resolve_org_roots`.

---

## Breaking change (mission B): missing packs hard-fail

Prior to mission `charter-mediated-doctrine-selection-01KRTZCA`, an org pack
configured in `.kittify/config.yaml` whose `local_path` did not exist on disk was
silently skipped — resolution would degrade to the built-in + project layers
without surfacing the misconfiguration. This made stale pack entries and typoed
paths invisible until a missing artifact tripped a downstream lookup.

As of this mission (FR-015), missing packs cause `spec-kitty charter context` and
every downstream command (including `spec-kitty next`) to fail loudly with a
message naming the pack and the missing path:

```
Org pack 'very-serious-developers' configured at
'/home/alice/.kittify/org/very-serious-developers' not found. Either fetch the pack
(`spec-kitty charter fetch --pack <name>`) or remove the entry from `.kittify/config.yaml`.
```

The diagnostic is intentionally actionable — operators are given two concrete
remediation steps, and the error is raised by `OrgPackMissingError`
(`src/charter/offering/drg/org_pack_loader.py`) so callers can catch and report it
in their own UIs.

**Migration**

1. Run `spec-kitty doctor charter-packs` to enumerate configured packs and their
   on-disk status.
2. For each missing pack, either:
   - `spec-kitty charter fetch --pack <name>` to populate the snapshot, or
   - Remove the entry from `.kittify/config.yaml` under `charter_packs.org.packs`.
3. Re-run `spec-kitty doctor charter-packs` to confirm a clean state before the next
   `charter context` build.

This behaviour is non-negotiable: silent fallback risked teams unknowingly
running without the governance their charter assumed. There is no opt-out flag.

---

## Frequently asked questions

**Can I have multiple org layers?**
Yes — list any number of packs in `charter_packs.org.packs`. Within the org layer,
declaration order determines precedence (later wins).

**Can a project override an org artifact?**
Yes. The project layer always wins. Use the override when you have a genuine
project-level exception; `charter lint` will surface an advisory so the
override remains visible.

**What if the org snapshot is missing on disk?**
As of mission `charter-mediated-doctrine-selection-01KRTZCA` (FR-015), this is a
**hard error**. Earlier releases silently fell back to built-in + project; that
behaviour was hiding misconfigured packs and stale paths. See the breaking-change
section below for the migration path. `spec-kitty doctor charter-packs` reports every
configured pack and flags any that are missing.

**Is it safe to gitignore the snapshot directory?**
Yes — and that is the recommended pattern. `charter fetch` is the install step;
treating the snapshot as cache rather than source-controlled artifacts keeps the
repository small and ensures all consumers pull the same way.

**Does the org layer change how the built-in Charter Pack is loaded?**
No. The built-in layer is unchanged. The org layer composes on top.

**Where do I see which layer an artifact came from?**
`uv run spec-kitty charter context --action <action> --json` lists every resolved
artifact with its `source` tag. `uv run spec-kitty doctor charter-packs --json` lists
installed pack contents.

---

## See also

- [How to create an org Charter Pack](/guides/how-to/governance/create-an-org-doctrine-pack.md)
- [Migrating shared doctrine to the org layer](/migrations/doctrine-local-overlay-to-org-layer.md)
- [How to set up project governance](/guides/how-to/governance/setup-governance.md)
- [Understanding Charter: Synthesis, DRG, and Governed Context](/architecture/charter-synthesis-drg.md)
- [Mission-Type Resolution](/architecture/mission-type-resolution.md)

## Related

- [Understanding Charter: Synthesis, DRG, and Governed Context](/architecture/charter-synthesis-drg.md)
- [Mission-Type Resolution — the doctrine → charter → core seam](/architecture/mission-type-resolution.md)
- [Migrating Shared Doctrine to the Org Layer](/migrations/doctrine-local-overlay-to-org-layer.md)

## Audience

- [Stakeholder Persona: Lead Developer](/context/audience/internal/lead-developer.md) - Written for the Lead Developer reader.
