Skip to content

Context: Charter

Who is this for (2)

Context: Charter

The canonical Terminology-Canon entry for the governing charter term (glossary authority 3 — see .kittify/glossaries/spec_kitty_core.yaml and packs/built-in/glossary_packs/spec-kitty-core.glossary-pack.yaml for authorities 1/2), followed by terms describing the Doctrine domain model and doctrine artifact taxonomy (kept domain vocabulary — the src/charter/offering/ package, artifact kinds, and the DRG are unaffected by the governing-term flip; see mission retire-doctrine-term-01M0JMK9).

charter

DefinitionThe governance document synthesizing a project’s purpose, constraints, team norms, and the body of project-specific governance artifacts (directives, tactics, and styleguides) into a durable reference artifact, produced by the charter interview workflow. This is the canonical governing term (glossary authority 1/2/3: .kittify/glossaries/spec_kitty_core.yaml, the built-in glossary pack, this entry).
ContextDoctrine
Statuscanonical
Applicable to2.x, 3.x
Do NOT use whenThe concept is the .kittify/charter/ directory tree and its files (activation state, DRG cache, synthesis manifest) as a unit — use Charter Bundle. The concept is a distributable bundle of charter components offered to a project — use Charter Pack; everything offered to a project, packs and project layer together, is the Charter offering. The concept is a named, ready-made set of activations a pack ships (default, minimal) — use Activation preset. The concept is what a project has activated (its activated_<kind> keys, activated_kinds and mission_type_activations) — use Active charter. The concept is a single artifact’s own per-project state (the Active-Inactive Charter distinction) — say “an active directive” or “an inactive tactic”: “active” and “inactive” alone describe one artifact, “active charter” names the project’s activated set as a whole, and the .kittify/charter/ tree is never called “active” (ADR 2026-10-06-2 §1). The concept is the src/charter/ Python package (facades, resolver, synthesis, activation engine) — use the src/charter/ package. The concept is the spec-kitty charter ... CLI command group (interview, generate, context, activate, deactivate, pack, …) — use the spec-kitty charter CLI group. Never use bare “doctrine” for any of these senses; the governing term is charter.
Related termsCharter offering, Charter Pack, Activation preset, Active charter, Project layer, Charter Bundle, Charter-Mediated Selection, Charter Facade

Charter offering

DefinitionEverything offered to a project: the Charter Packs it can draw from (the built-in pack and each configured org pack) plus the Project layer. The offer side of the charter; the activation side is the Active charter. Defined in ADR 2026-10-06-2 §1.
ContextCharter
Statuscanonical
Applicable to4.x
Locationsrc/charter/offering/, packs/
Related termsCharter Pack, Project layer, Active charter, Organization Tier
Do NOT use whenThe concept is what the project has activated from the offering — use Active charter. The concept is one distributable bundle — use Charter Pack.

Charter Pack

DefinitionA distributable bundle of charter components (artifacts and their DRG edges) together with optional activation presets shipped as presets/<name>.yaml. An org pack may also enforce activations through required_<kind> lists in its org-charter.yaml. A pack is identified by its charter_pack_id (built-in, an org pack’s configured name, or project); org packs are configured under charter_packs.org.packs in .kittify/config.yaml. Every pack now declares its level in pack.yaml via the pack_level field — one of built-in, org or project (ADR 2026-10-11-2). The level names have one authority, kernel.pack_tiers; the level token and the provenance/layer value now share a single spelling, built-in (the former no-hyphen builtin provenance spelling is folded away). Loading refuses a pack whose declared level disagrees with where it is configured (PACK_LEVEL_MISMATCH). A pack.yaml that omits the field, or an org pack with no pack.yaml, is reported as PACK_LEVEL_MISSING. During the deprecation window of ADR 2026-10-11-2 that is a non-blocking diagnostic: loading warns and uses the configured level, and charter pack validate reports a pack.yaml without the field as an advisory. Once the window closes it becomes a refusal. Validated with spec-kitty charter pack validate, listed with spec-kitty charter pack list.
ContextCharter
Statuscanonical
Applicable to4.x
Locationpacks/built-in/, charter_packs.org.packs[], src/charter/offering/packs/
Related termsCharter offering, Activation preset, Project layer, Activation Registry, Organization Tier
Do NOT use whenThe concept is a named starting set of activations — use Activation preset. The concept is the project’s own activation state — use Active charter. The concept is the .kittify/charter/ tree — use Charter Bundle.

Contract Scenario

DefinitionA Gherkin scenario that is the behavior half of the charter contract: it names pack files, calls one operation of contracts/charter/openapi.yaml and states the answer. Scenarios tagged @contract run in verifyAll; @provisional marks behavior the conformance corpus has yet to decide.
ContextGovernance
Statuscandidate
Applicable to4.x
Locationcontracts/charter/scenarios/ in spec-kitty/spec-kitty-charter (today action_context.feature, errors.feature, packs.feature)
Related termsCharter Pack; Acceptance Scenario (the scenarios under tests/scenarios/charter/) and Conformance Corpus are defined in spec-kitty-charter, not in this glossary yet
Do NOT use whenYou mean the acceptance scenarios under tests/scenarios/charter/, the conformance corpus as a whole, or BDD the practice. Do not write “BDD scenarios”.

Activation preset

DefinitionA named set of activations that a Charter Pack ships (presets/<name>.yaml: per-kind activated_<kind> keys, activated_kinds, mission_type_activations), applied with spec-kitty charter activate [--pack <pack>] --preset <name>. Applying a preset replaces every activation key it governs; changing a customized key needs --force. The applied preset name is not stored. The built-in pack ships default (no per-kind restriction, so every built-in artifact is in force, plus the built-in mission types) and minimal (a small curated baseline).
ContextCharter
Statuscanonical
Applicable to4.x
Locationpacks/built-in/presets/, <pack>/presets/
Related termsCharter Pack, Active charter, activated_<kind>
Do NOT use whenThe concept is a context-scoped activation entry — use Activation Registry. The concept is a single artifact’s state (“an active directive”). The concept is the project’s activation state after a preset was applied — use Active charter.

Active charter

DefinitionWhat a project has activated: its activated_<kind> keys, activated_kinds and mission_type_activations (plus the deactivated_<kind> exclusions), held in the Activation ledger .kittify/charter/activation.yaml (ADR 2026-10-19-1); list it with spec-kitty charter list --json. The activation side of the charter, resolved by PackContext.from_config and served by ActiveCharterService; an invalid shape fails with ACTIVE_CHARTER_CONFIG_INVALID. The “active” guard (ADR 2026-10-06-2 §1): “active” and “inactive” alone still describe one artifact (“an active directive”); “active charter” names the project’s activated set as a whole; the .kittify/charter/ tree is never called “active”.
ContextCharter
Statuscanonical
Applicable to4.x
Location.kittify/charter/activation.yaml, src/charter/activation/
Related termsactivated_<kind>, Activation preset, Charter offering, Charter-Mediated Selection
Do NOT use whenThe concept is what is offered rather than activated — use Charter offering. The concept is the materialized .kittify/charter/ tree — use Charter Bundle. The concept is a ready-made set of activations — use Activation preset.

Activation ledger

DefinitionThe git-tracked file .kittify/charter/activation.yaml, the single authority for what a project has activated. It holds activated_kinds, mission_type_activations, the three-state activated_<plural> allow state (absent = the kind’s effective_when_absent default, [] = nothing, a list = that set) and the deactivated_<plural> deny-lists (Exclusion); an empty deny-list is omitted. The effective set of a kind is its allow state minus its Effective deny; a deny entry never subtracts a Required floor id. Read and written only through charter.activation.activation_ledger; spec-kitty doctor charter-packs reports any other surface that disagrees. spec-kitty init writes it; spec-kitty upgrade (step 4.0.0rc8_activation_ledger) or spec-kitty migrate activation-ledger moves an older project’s keys into it. Until then such a project is read from its old surface (allow keys only) and refuses every deactivation. Defined in ADR 2026-10-19-1.
ContextCharter
Statuscanonical
Applicable to4.x
Location.kittify/charter/activation.yaml, src/charter/activation/
Related termsActive charter, Exclusion, Effective deny, Required floor, activated_<kind>
Do NOT use whenThe concept is the applied-migration record (.kittify/migration-ledger.jsonl, which says which upgrade migrations have run) — use the Migration Ledger (ADR 2026-10-17-1). The concept is the record of Decision Moments (decisions/) — use the decision ledger. The concept is the append-only per-Mission status-lane history (status.events.jsonl) — use the status event log. The concept is the set of artifacts a project has activated, as a whole — use Active charter; the ledger is the file that stores it.

Exclusion

DefinitionAn artifact id a user explicitly deactivated, stored in the Activation ledger as a deactivated_<plural> entry (a deny-list entry). It survives every later command, upgrade, interview and regeneration. Only an explicit choice removes it: charter activate <kind> <id> (including --only), a cascade with --include-deactivated, or charter activate --preset X --force. Ids dropped by --only narrowing are not excluded.
ContextCharter
Statuscanonical
Applicable to4.x
Location.kittify/charter/activation.yaml
Related termsActivation ledger, Effective deny, Required floor
Do NOT use whenThe concept is an artifact that is simply absent from an activated_<kind> list — that is “not in the allow state”, not an exclusion. The concept is an out-of-scope skip in a cascade — say “skipped (out of scope)”. The concept is the deny-list after the Required floor is taken out — use Effective deny.

Effective deny

DefinitionThe deny-list that actually subtracts: the ledger’s Exclusions resolved in identity space (stem, declared id and DRG URN all match), minus the Required floor. D* = resolve_deny(D) - R. A stale exclusion for a required id is therefore inert, and doctor reports it.
ContextCharter
Statuscanonical
Applicable to4.x
Locationsrc/charter/activation/, PackContext.denied
Related termsExclusion, Required floor, Activation ledger
Do NOT use whenThe concept is the raw deactivated_<plural> list as written in the file — use Exclusion. The concept is the final set of artifacts in force — say “effective set” (allow state minus effective deny).

Required floor

DefinitionThe union of required_<plural> over every declared org pack and each pack’s extends: chain, with each id attributed to the pack(s) requiring it. Precedence never decides membership. Required artifacts cannot be deactivated (charter deactivate refuses and names the pack) and are never subtracted by an Exclusion. Read strictly: an unreadable declared pack or a broken extends: chain is an error, never an empty floor.
ContextCharter
Statuscanonical
Applicable to4.x
Locationorg-charter.yaml (required_<plural>), src/charter/activation/org_pack_discovery.py
Related termsEffective deny, Exclusion, Charter Pack
Do NOT use whenThe concept is the project charter’s own top-level required_directives list, which is not an org-pack requirement. The concept is a kind’s default while its allow key is absent (effective_when_absent) — say “absent default”.

Project layer

DefinitionThe project’s own charter components, under the one flat root .kittify/charter-packs/ (charter_pack_id project). It is part of the Charter offering, ships no presets, and is listed by spec-kitty charter pack list as the project row. spec-kitty charter synthesize writes here.
ContextCharter
Statuscanonical
Applicable to4.x
Location.kittify/charter-packs/
Related termsCharter offering, Charter Pack, Three-layer DRG
Do NOT use whenThe concept is the materialized charter output — use Charter Bundle. The concept is an org pack checked into the repository — use Charter Pack.

Charter Bundle

DefinitionThe materialized .kittify/charter/ tree as a unit: charter.md, the synthesis manifest, the DRG cache and provenance. Produced by spec-kitty charter generate and spec-kitty charter synthesize; validated by spec-kitty charter bundle validate.
ContextCharter
Statuscanonical
Applicable to4.x
Location.kittify/charter/
Related termscharter, Active charter, Project layer
Do NOT use whenThe concept is the project’s activation state — use Active charter; never call the bundle “active”. The concept is the project’s own authored components — use Project layer.

Doctrine Domain

DefinitionThe domain model that structures reusable governance knowledge in Spec Kitty. It organizes behavior and constraints into composable artifacts (paradigms, directives, tactics, templates, styleguides, and toolguides).
ContextDoctrine
Statuscanonical
Applicable to1.x, 2.x
Locationsrc/charter/offering/
Related termsParadigm, Directive, Tactic, Template Set, Styleguide, Toolguide, Governance

Guideline

DefinitionA high-level doctrine rule expressing non-negotiable or strongly preferred governance behavior. Guidelines sit at the highest precedence and bound what project-level charter may customize.
ContextDoctrine
Statuscanonical
Applicable to1.x, 2.x
LocationPrecedence concept in governance model (no dedicated guidelines/ directory in the current src/charter/offering/ tree)
Related termsDirective, Active charter, Precedence Hierarchy

Paradigm

DefinitionA worldview-level framing for how work is approached in a domain. Paradigms influence selection and interpretation of directives and tactics but are not executable step recipes themselves.
ContextDoctrine
Statuscanonical
Applicable to1.x, 2.x
Locationpacks/built-in/paradigms/
Related termsDirective, Tactic, Active charter

Directive

DefinitionA constraint-oriented governance rule that applies across flows or phases. Directives encode required or advisory expectations and can reference lower-level tactics for execution.
ContextDoctrine
Statuscanonical
Applicable to1.x, 2.x
Locationpacks/built-in/directives/
Related termsParadigm, Tactic, Schema (Doctrine Artifact)

Tactic

DefinitionA reusable behavioral execution pattern that defines how work is performed. Tactics are operational and agent-consumable, and can be selected by directives and mission context.
ContextDoctrine
Statuscanonical
Applicable to1.x, 2.x
Locationpacks/built-in/tactics/
Related termsDirective, Template Set, Toolguide

Procedure

DefinitionA reusable doctrine subworkflow that a step contract may delegate to for part of a mission action. Procedures are structured playbooks, not tracked missions and not runtime sessions.
ContextDoctrine
Statuscanonical
Applicable to1.x, 2.x
Locationpacks/built-in/procedures/ and related doctrine procedure models
Related termsTactic, Directive, Mission Action, step contract

Template Set

DefinitionA structured set of doctrine templates that shape output artifacts and interaction contracts for mission actions and procedures. Template sets allow consistent behavior across mission types while remaining configurable through charter selections.
ContextDoctrine
Statuscanonical
Applicable to1.x, 2.x
Locationsrc/charter/offering/templates/sets/
Related termsProcedure, Tactic, Active charter

Styleguide

DefinitionA doctrine artifact defining cross-cutting quality and consistency conventions (for example coding, documentation, or testing style) that apply across missions and templates.
ContextDoctrine
Statuscanonical
Applicable to1.x, 2.x
Locationpacks/built-in/styleguides/
Related termsToolguide, Schema (Doctrine Artifact), Active charter

Toolguide

DefinitionA doctrine artifact defining tool-specific operational guidance, syntax, and constraints (for example PowerShell usage conventions) used by agents and contributors during execution.
ContextDoctrine
Statuscanonical
Applicable to1.x, 2.x
Locationpacks/built-in/toolguides/
Related termsStyleguide, Tactic, Execution

Schema (Doctrine Artifact)

DefinitionA machine-validated contract that defines allowed structure and fields for doctrine artifacts. Used in CI/tests to fail fast when invalid doctrine files are introduced.
ContextDoctrine
Statuscanonical
Applicable to1.x, 2.x
Locationsrc/charter/offering/schemas/
Related termsDirective, Tactic, Styleguide, Toolguide

Import Candidate

DefinitionA pull-based curation record for an external doctrine idea. Captures source provenance, target classification, adaptation notes, and adoption status before canonization.
ContextDoctrine
Statuscanonical
Applicable to1.x, 2.x
Locationsrc/charter/offering/import_candidates/
Related termsDirective, Tactic, Schema (Doctrine Artifact), ADR (Architectural Decision Record)

Specification by Example (Paradigm)

DefinitionA paradigm that builds shared understanding of behavior through concrete, business-readable examples which become the canonical source of truth for requirements, acceptance checks, and living documentation.
ContextDoctrine
Statuscanonical
Applicable to1.x, 2.x
Locationpacks/built-in/paradigms/specification-by-example.paradigm.yaml
Related termsParadigm, Living Documentation Sync (Directive), Usage Examples Sync (Tactic), Example Mapping Workshop (Procedure)

Living Documentation Sync (Directive)

DefinitionDirective DIRECTIVE_037. Requires behavior-describing artifacts to evolve together: when observable behavior changes, the canonical examples, acceptance checks, narrative specs, user docs, glossary entries, code-level docs, and architecture records are updated in the same change.
ContextDoctrine
Statuscanonical
Applicable to1.x, 2.x
Locationpacks/built-in/directives/037-living-documentation-sync.directive.yaml
Related termsDirective, Specification by Example (Paradigm), Usage Examples Sync (Tactic)

Usage Examples Sync (Tactic)

DefinitionTactic usage-examples-sync. The step-by-step pattern for keeping canonical usage examples, acceptance checks, and the artifacts that quote them aligned during a behavior change.
ContextDoctrine
Statuscanonical
Applicable to1.x, 2.x
Locationpacks/built-in/tactics/communication/usage-examples-sync.tactic.yaml
Related termsTactic, Living Documentation Sync (Directive), Example Mapping Workshop (Procedure)

Example Mapping Workshop (Procedure)

DefinitionProcedure example-mapping-workshop. Turns a behavior request into concrete rules, canonical examples, and open questions that stakeholders and implementers share as the current source of truth for the behavior.
ContextDoctrine
Statuscanonical
Applicable to1.x, 2.x
Locationpacks/built-in/procedures/example-mapping-workshop.procedure.yaml
Related termsProcedure, Specification by Example (Paradigm), Living Documentation Sync (Directive), Usage Examples Sync (Tactic)

Charter-Mediated Selection

DefinitionArchitectural pattern in which the project / org charter is the sole authority that decides which doctrine artifacts apply to a given mission run. Doctrine is the knowledge store; charter is the selector; runtime asks charter for the activated set rather than reaching into doctrine directly. Enforced via the runtime → charter → doctrine boundary. This framing is correct at the architectural level; the MECHANISM by which the charter’s activation decision is actually resolved today is activated_<kind> — not selected_<kind> alone. selected_<kind> is the authoring record of what an interview/pack once selected; activated_<kind> is what PackContext.from_config resolves via the INV-2 two-file pointer chase.
ContextDoctrine
Statuscanonical
Applicable to2.x
Related termsGlobal Selection, Context-Scoped Selection, Charter Facade, Charter Pack, activated_<kind>

Global Selection

DefinitionSelection mode in which the charter declares an artifact should be active for every WP prompt regardless of action or mission type. Expressed via selected_<kind>: [<id>, ...] on the project charter or required_<kind>: [<id>, ...] on the org charter. Example: “this project always uses the python-conventions styleguide.” Declaring is not the same as activating: whether a declared entry is actually delivered depends on the resolved activated_<kind> set (PackContext) — selected_<kind>/required_<kind> are additive/unioned onto the activated_<kind>-derived base at the surfaces that resolve activation today (e.g. resolve_project_governance), not an independent activation source in their own right.
ContextDoctrine
Statuscanonical
Applicable to2.x
Related termsContext-Scoped Selection, Charter-Mediated Selection, activated_<kind>

Context-Scoped Selection

DefinitionSelection mode in which the charter declares an artifact is active only for a specific Activation Context (mission_type × action). Surfaces in the prompt as a fetch command paired with a “when you , run …” conditional. Example: “when writing a code comment in a software-dev mission, fetch the caveman styleguide.” Implemented via the Activation Registry.
ContextDoctrine
Statuscanonical
Applicable to2.x
Related termsActivation Registry, Activation Context, Global Selection

Activation Registry

DefinitionCharter-level list of (activation_context, charter_pack_id, artifact_id) tuples expressing which charter artifacts activate in which contexts (charter_pack_id names the Charter Pack). Lives on the charter (not on the artifact) so different projects can activate the same shared artifact in different contexts without forking it. Both project charter and org charter may declare entries; org-declared entries propagate to consumers via the standard org-charter pre-fill.
ContextDoctrine
Statuscanonical
Applicable to2.x
Related termsActivation Context, Context-Scoped Selection, Charter Pack
Do NOT use whenThe concept is a named set of activations a pack ships and charter activate --preset applies — use Activation preset. The concept is the project’s activated set as a whole — use Active charter.

Activation Context

DefinitionThe key that scopes a context-scoped activation. A two-field shape — mission_type (one of software-dev, documentation, research, plan, or generic) and action (one of specify, plan, tasks, implement, review, merge, accept, plus charter verbs). The wildcard generic matches any value in its slot. Resolved during charter-context build by matching the current mission’s meta.json mission_type and the in-flight CLI action against registered entries.
ContextDoctrine
Statuscanonical
Applicable to2.x
Related termsActivation Registry, Mission-Type Profile

Trigger Registry

DefinitionCanonical frozenset of agent-action tokens (e.g. write_comment, write_docstring, rename_identifier, add_dependency) the prompt builder knows how to emit “when you , …” stanzas for. It is REGISTERED_TRIGGERS in src/charter/activation/activations.py: the ten ALLOWED_ACTIONS tokens plus four fine-grained ones (write_comment, write_docstring, rename_identifier, add_dependency). An Activation Registry entry’s action must be a member or a wildcard (any, generic). No test checks the triggers: values on shipped doctrine artifacts against it today: the architectural test that did, test_trigger_registry_coverage.py, was removed in #3285 (2026-08-12). Mission B’s WP05 populated the initial set.
ContextDoctrine
Statuscanonical
Applicable to2.x
Related termsActivation Context, Activation Registry

Charter Facade

DefinitionA src/charter/<facade>.py module that re-exports (or thinly wraps) a doctrine surface so runtime callers can consume it as from charter.<facade> import X instead of from doctrine.<x> import X. Examples: charter.profiles, charter.mission_steps, charter.drg, charter.primitives, charter.resolution, charter.versioning. The set of facades is the runtime → charter → doctrine boundary’s public surface.
ContextDoctrine
Statuscanonical
Applicable to2.x
Related termsCharter-Mediated Selection

Mission-Type Profile

DefinitionShipped governance profile per mission type (software-dev, documentation, research, plan) at packs/built-in/missions/<type>/governance-profile.yaml. Declares default selections and default activations for that mission type. The charter resolver reads meta.json mission_type, picks the matching profile, and unions its declarations into the project + org selections. No software-dev-default fallback for non-software missions — the resolver hard-fails if a mission’s mission_type has no matching profile and the project has not declared its own.
ContextDoctrine
Statuscanonical
Applicable to2.x
Related termsActivation Context, Global Selection

selected_<kind> / required_<kind>

DefinitionThe field-naming convention for Global Selection entries. On the project charter (GovernanceCharterConfig), each artifact kind gets a selected_<kind>: [<id>, ...] field — selected_directives, selected_styleguides, selected_toolguides, selected_paradigms, selected_tactics, selected_procedures, selected_agent_profiles, selected_mission_step_contracts. On the org charter (OrgCharterPolicy), the mirror is required_<kind>: [<id>, ...]. apply_org_charter_to_interview unions the org required_<kind> into the project selected_<kind> non-destructively. The architectural test test_artifact_selection_completeness.py enforces parity — every ActiveCharterService artifact kind has both a selected_* and a required_* field. These fields are the CHARTER-AUTHORED record of a selection, not an independent activation source: they are unioned as an additive project-local layer over the resolved activated_<kind> base (PackContext.from_config) at the surfaces that resolve activation today (e.g. _resolve_directive_base in resolver.py).
ContextDoctrine
Statuscanonical
Applicable to2.x
Related termsGlobal Selection, Charter-Mediated Selection, activated_<kind>

activated_<kind>

DefinitionThe three-state per-kind activation allow state for a doctrine artifact kind (activated_paradigms, activated_directives, activated_tactics, activated_styleguides, activated_toolguides, activated_procedures, activated_agent_profiles, activated_mission_step_contracts, activated_glossary_packs, activated_anti_patterns, activated_skills: one key per activatable ArtifactKind). Since 4.0.0rc8 it lives in the Activation ledger .kittify/charter/activation.yaml, beside the kind’s deactivated_<kind> Exclusions, and PackContext.from_config reads it through charter.activation.activation_ledger. A project that has not run spec-kitty upgrade since then still has the keys in .kittify/config.yaml, or in the charter.yaml its charter: pointer names, and is read from there (allow keys only) until it is upgraded. Three states per kind, applied independently: an ABSENT key resolves to None (“all built-ins available”); an explicit empty list ([]) is an explicit opt-out (nothing of that kind activated); a non-empty list is the explicit activated set. This is the field the compiler (compile_charter) and — after mission spdd-reasons-activation-split-brain-01M1K6VN — is_spdd_reasons_active, _load_action_doctrine_bundle, and resolve_project_governance all resolve activation from: the actual mechanism behind Charter-Mediated Selection, distinct from the charter-authored selected_<kind> / required_<kind> declaration surface.
ContextDoctrine
Statuscanonical
Applicable to2.x, 4.x
Related termsActivation ledger, Exclusion, Charter-Mediated Selection, Global Selection, selected_<kind> / required_<kind>

Three-layer DRG

DefinitionThe three-tier Doctrine Relationship Graph composed of: (1) the shipped built-in layer (the per-kind *.graph.yaml fragments under packs/built-in/), (2) zero or more org-tier extension fragments (drg/fragment.yaml inside each configured org pack), and (3) optional project-tier annotations declared in the project charter. Each tier is additive; org and project tiers may only extend or annotate shipped nodes — they cannot remove or reclassify them. Resolved at runtime by charter.drg.merge_three_layers.
ContextDoctrine
Statuscanonical
Applicable to2.x
Related termsCharter Pack, Organization Tier, Charter-Mediated Selection

Tension — in_tension_with (DRG Relation)

DefinitionA symmetric, non-transitive Three-layer DRG relation marking two co-valid, co-activatable artifacts that compete on the same decision. Stored as a single canonical edge (lexicographically-smaller URN as source) and queryable from either endpoint; it does not imply that either side is deprecated, superseded, or wrong — both remain valid rules until an operator deactivates one side or activates a reconciler (Reconciliation). Canonical source: RELATION_DESCRIPTIONS[Relation.IN_TENSION_WITH] in src/charter/offering/drg/models.py; human-readable mirror and worked examples in docs/architecture/doctrine-relationships.md (“Tension vocabulary”). Retired from the external contract (2026-10-19): the spec-kitty-charter contract 1.0 Relation enum carries impacts and drops in_tension_with; use impacts (a signed, authored relation; tension is impacts < 0, ADR 2026-07-26-3). Core’s seam maps an in_tension_with edge to a negative impacts until core’s edge migration (B2) removes the relation from the DRG (spec-kitty-charter ADR-0009 and ADR-0014).
ContextDoctrine
Statusdeprecated
Applicable to3.x
Related termsReconciliation, Rejection, Three-layer DRG

Reconciliation — reconciles_tension (DRG Relation)

DefinitionA directional Three-layer DRG relation linking an active reconciliation artifact to one side of a declared Tension pair. A tension pair is treated as resolved only when an active artifact carries this edge to both sides of the pair — an edge to just one side leaves the pair half-reconciled and still flagged. It is authored explicitly and is never inferred from an in_tension_with edge. Canonical source: RELATION_DESCRIPTIONS[Relation.RECONCILES_TENSION] in src/charter/offering/drg/models.py; human-readable mirror in docs/architecture/doctrine-relationships.md (“Tension vocabulary”).
ContextDoctrine
Statuscanonical
Applicable to3.x
Related termsTension, Rejection, Three-layer DRG

Rejection — rejects (DRG Relation)

DefinitionA directional Three-layer DRG relation from a good artifact to a marked anti-pattern or smell node (NodeKind.ANTI_PATTERN), expressing rejection of a named bad practice. It is distinct from Tension — the target is not a competing equal, it is a bad practice — and from replaces/supersession, since the target was never a valid rule to begin with. Canonical source: RELATION_DESCRIPTIONS[Relation.REJECTS] in src/charter/offering/drg/models.py; human-readable mirror in docs/architecture/doctrine-relationships.md (“Tension vocabulary”).
ContextDoctrine
Statuscanonical
Applicable to3.x
Related termsTension, Reconciliation, Three-layer DRG

Hard Dependency — requires (DRG Relation)

DefinitionA directional Three-layer DRG relation marking a mandatory prerequisite: the source artifact cannot be meaningfully resolved without the target also being present and considered. Governance-context resolution for a mission-step action walks requires edges transitively (no hop limit) once it has collected the action’s scoped artifacts, and the charter activation cascade follows the same edge to pull in artifacts that must also be active. It is the most heavily used relation in the built-in graph. Canonical source: RELATION_DESCRIPTIONS[Relation.REQUIRES] in src/charter/offering/drg/models.py.
ContextDoctrine
Statuscanonical
Applicable to2.x, 3.x
Related termsSoft Recommendation, Governance Scope, Three-layer DRG

Soft Recommendation — suggests (DRG Relation)

DefinitionA directional Three-layer DRG relation pointing at content that is relevant but optional. Unlike Hard Dependency, which is walked transitively with no depth limit, governance-context resolution only follows suggests edges a bounded number of hops, and the charter activation cascade treats a suggests target as something an operator may accept or decline. It is emitted more often than any other relation in the built-in graph, but that volume is incidental — the depth-bounded walk, not the count, is what separates it from requires. Canonical source: RELATION_DESCRIPTIONS[Relation.SUGGESTS] in src/charter/offering/drg/models.py.
ContextDoctrine
Statuscanonical
Applicable to2.x, 3.x
Related termsHard Dependency, Three-layer DRG

Workflow Application — applies (DRG Relation)

DefinitionA directional Three-layer DRG relation from an agent profile to the concrete procedure or tactic it executes as its operating workflow. The built-in graph contains zero applies edges and authoring one into the shipped tree is refused by tests/architectural/test_no_authored_applies_edge.py: nothing traverses applies — not governance-context resolution, not the charter cascade, not the reference walk — so an authored edge names a relationship no reader follows. Use requires when the profile must actually reach the artifact. The relation itself is not retired, but project-tier synthesis no longer emits it for tactics: a synthesized tactic is linked from its directive with suggests, and legacy tactic applies edges are replaced on re-synthesis. Distinct from Governance Scope: applies names what a profile does, scope names what an action is governed by; the two edge-roles are never interchangeable even though both link an actor-adjacent node to guidance content. Canonical source: RELATION_DESCRIPTIONS[Relation.APPLIES] in src/charter/offering/drg/models.py.
ContextDoctrine
Statuscanonical
Applicable to2.x, 3.x
Related termsGovernance Scope, Three-layer DRG

Governance Scope — scope (DRG Relation)

DefinitionA directional Three-layer DRG relation from a mission-step action node to the directives and tactics that govern performing that action. It is the entry point of governance-context resolution: the resolver first walks scope edges from the action node, then expands through Hard Dependency and Soft Recommendation edges from what it found. It is one of the most heavily emitted relations tied to action nodes in the built-in graph. Distinct from Workflow Application — see that entry for the contrast. Canonical source: RELATION_DESCRIPTIONS[Relation.SCOPE] in src/charter/offering/drg/models.py.
ContextDoctrine
Statuscanonical
Applicable to2.x, 3.x
Related termsWorkflow Application, Hard Dependency, Soft Recommendation, Three-layer DRG

Glossary Vocabulary — vocabulary (DRG Relation)

DefinitionA directional Three-layer DRG relation from a resolved doctrine artifact to a glossary-scope node, meant to surface which glossary sections are relevant once governance context has been resolved for an action. The traversal step exists and is exercised by tests, but no built-in or org-pack artifact currently emits a vocabulary edge — treat it as intended-but-dormant rather than actively exercised. Canonical source: RELATION_DESCRIPTIONS[Relation.VOCABULARY] in src/charter/offering/drg/models.py.
ContextDoctrine
Statuscanonical
Applicable to2.x, 3.x
Related termsGovernance Scope, Three-layer DRG

Template Instantiation — instantiates (DRG Relation)

DefinitionA directional Three-layer DRG relation from a mission-step action node to the template it produces as its concrete output. It appears only between action and template nodes in the built-in graph, in modest numbers, and is distinct from Governance Scope: scope links an action to content it must follow, instantiates links it to content it produces. Canonical source: RELATION_DESCRIPTIONS[Relation.INSTANTIATES] in src/charter/offering/drg/models.py.
ContextDoctrine
Statuscanonical
Applicable to2.x, 3.x
Related termsGovernance Scope, Three-layer DRG

Supersession — replaces (DRG Relation)

DefinitionA directional Three-layer DRG relation asserting that the source artifact fully supersedes the target, which stops applying once the source is active. It is retained for backward compatibility with older, hand-authored fragments; no built-in artifact emits it today, since current practice either deactivates the superseded artifact directly or, for pack overlays, expresses supersession through Overlay Override. Distinct from Tension, which never implies either side is deprecated or wrong. Canonical source: RELATION_DESCRIPTIONS[Relation.REPLACES] in src/charter/offering/drg/models.py.
ContextDoctrine
Statuscanonical
Applicable to2.x, 3.x
Related termsOverlay Override, Tension, Three-layer DRG

Delegation — delegates_to (DRG Relation)

DefinitionA directional Three-layer DRG relation expressing a runtime handoff: one agent profile hands work to another at execution time. It is kept deliberately separate from Lineage so a static “derives from” relationship never gets conflated with a live work handoff. No built-in artifact emits a delegates_to edge today — delegation is currently expressed in profile collaboration.handoff_to prose rather than as a graph edge, so treat this relation as intended-but-dormant. Canonical source: RELATION_DESCRIPTIONS[Relation.DELEGATES_TO] in src/charter/offering/drg/models.py.
ContextDoctrine
Statuscanonical
Applicable to2.x, 3.x
Related termsLineage, Three-layer DRG

Lineage — specializes_from (DRG Relation)

DefinitionA directional, static Three-layer DRG relation: a profile or artifact derives from a parent, narrowing or extending it. In the built-in graph this appears only between agent_profile nodes (e.g. a language-specialist implementer profile specializing from the generic implementer profile), and is resolved through AgentProfileRepository.resolve_profile graph traversal at composition time. Deliberately distinct from Delegation so inheritance never leaks into runtime handoff traversal. Canonical source: RELATION_DESCRIPTIONS[Relation.SPECIALIZES_FROM] in src/charter/offering/drg/models.py.
ContextDoctrine
Statuscanonical
Applicable to2.x, 3.x
Related termsDelegation, Three-layer DRG

Overlay Enhancement — enhances (DRG Relation)

DefinitionA directional org-pack overlay relation: a pack artifact field-merges additional content into a built-in artifact, preserving the built-in’s existing action sequence and step I/O rather than discarding them. No built-in artifact emits this edge — by design, enhances only ever originates from an org- or project-tier pack fragment layered on top of a shipped artifact, never between two built-in nodes. Distinct from Overlay Override, which replaces rather than merges. Canonical source: RELATION_DESCRIPTIONS[Relation.ENHANCES] in src/charter/offering/drg/models.py.
ContextDoctrine
Statuscanonical
Applicable to2.x, 3.x
Related termsOverlay Override, Three-layer DRG, Organization Tier

Overlay Override — overrides (DRG Relation)

DefinitionA directional org-pack overlay relation: a pack artifact declares a full replacement of a built-in artifact’s content rather than a field-merge. Like Overlay Enhancement, no built-in artifact emits this edge by design — it only ever originates from an org- or project-tier overlay. Silently dropping steps or stripping step input/output when applying an overrides edge is rejected rather than tolerated. Canonical source: RELATION_DESCRIPTIONS[Relation.OVERRIDES] in src/charter/offering/drg/models.py.
ContextDoctrine
Statuscanonical
Applicable to2.x, 3.x
Related termsOverlay Enhancement, Three-layer DRG, Organization Tier

Refinement — refines (DRG Relation)

DefinitionA directional Three-layer DRG relation: an artifact narrows or sharpens the applicability or meaning of a parent or built-in target without replacing it. It is a first-class, traversable relation in its own right — never a stand-in for Workflow Application or Lineage. No built-in artifact currently emits a refines edge, so treat it as intended-but-dormant; an earlier version of the org-to-DRG bridge silently downgraded authored refines edges to applies, but that lossy downgrade has since been removed. Canonical source: RELATION_DESCRIPTIONS[Relation.REFINES] in src/charter/offering/drg/models.py.
ContextDoctrine
Statuscanonical
Applicable to2.x, 3.x
Related termsWorkflow Application, Lineage, Three-layer DRG

Organization Tier

DefinitionThe middle layer of the three-layer DRG model, contributed by one or more org Charter Packs configured under charter_packs.org.packs in .kittify/config.yaml. Each pack ships an org-charter.yaml (governance policies and required artifact selections) and an optional drg/fragment.yaml (DRG extension nodes and edges). Organization-tier content propagates to all consumer projects via apply_org_charter_to_interview and the standard charter pre-fill path.
ContextDoctrine
Statuscanonical
Applicable to2.x
AliasOrganisation Tier (UK spelling, legacy)
Related termsThree-layer DRG, Charter Pack, Active charter

CharterScope

DefinitionA resolution context (charter.activation.scope::CharterScope) that maps a filesystem path to the appropriate charter when multiple charters coexist in a monorepo. Single-project repositories use CharterScope.default(repo_root) which returns the root-scoped charter. Monorepos with multiple sub-project charters configure charter_scopes: in .kittify/config.yaml; CharterScope.resolve(repo_root, feature_dir) then finds the nearest-enclosing charter for any given Mission directory (feature_dir). The resolved scope.root is forwarded to build_charter_context (or via build_with_scope) so the correct per-package charter governs prompt generation. See ADR-8 (docs/adr/3.x/2026-05-18-1-monorepo-charter-scope.md).
ContextDoctrine
Statuscanonical
Applicable to2.x
Related termsThree-layer DRG, Charter-Mediated Selection, Workflow Sequence

Workflow Sequence

DefinitionA named, ordered list of mission-action steps with declared entry conditions, exit conditions, and optional per-step runtime hooks. Stored as a WorkflowSequence Pydantic model in spec-kitty next’s internal runtime schema registry. Org packs may contribute custom workflow sequences that extend or override the shipped set when activated via the Activation Registry.
ContextDoctrine
Statuscanonical
Applicable to2.x
Related termsActivation Registry, Mission-Type Profile, Procedure

Workflow ID

DefinitionThe stable, kebab-case identifier of a Workflow Sequence (e.g. software-dev-default). Used as the lookup key in the workflow schema registry and in the meta.json workflow_id field to record which sequence drove a given mission run. Org packs must not reuse shipped workflow IDs without explicit override semantics.
ContextDoctrine
Statuscanonical
Applicable to2.x
Related termsWorkflow Sequence, Mission-Type Profile

Ratchet Baseline

DefinitionA snapshot of a quality metric (failure count, symbol count, dead-module count) recorded in tests/architectural/_baselines.yaml and enforced by the corresponding architectural gate (tests/architectural/test_ratchet_baselines.py). A ratchet baseline only moves in the decreasing direction during normal development; any increase fails CI. Org packs may declare additional ratchet metrics via governance policies, but cannot lower an existing shipped baseline.
ContextDoctrine
Statuscanonical
Applicable to2.x
Related termsThree-layer DRG, Organization Tier

Cat-7 Grandfathered Orphan

DefinitionA dead-module or dead-symbol violation that has been explicitly classified as category 7 (“deferred — grandfathered”): listed in _CATEGORY_7_GRANDFATHERED_ORPHANS in tests/architectural/test_no_dead_modules.py. Cat-7 items are excluded from the active failure count tracked by the ratchet baseline but must not be added to the allowlist via side-effect imports (the C2 anti-pattern). Each cat-7 record must carry a deferral reason and a target WP for cleanup.
ContextDoctrine
Statuscanonical
Applicable to2.x
Related termsRatchet Baseline, Symbol-level Dead Code, Catalog Miss

Symbol-level Dead Code

DefinitionA public symbol (function, class, constant) exported by a module but not referenced by any other module or test in the codebase, as detected by tests/architectural/test_no_dead_symbols.py. Distinguished from module-level dead code (an entire module with no importers). Symbol-level findings are reported per-file and contribute to the dead-symbol ratchet baseline.
ContextDoctrine
Statuscanonical
Applicable to2.x
Related termsRatchet Baseline, Cat-7 Grandfathered Orphan, __all__ Declaration Convention

Catalog Miss

DefinitionA doctrine artifact ID referenced by a charter selection (e.g. selected_directives: [foo]) that does not resolve to any known artifact in the shipped pack, any configured org pack, or the project-layer doctrine tree. Catalog misses are reported as errors by spec-kitty doctor charter-packs and by the test_no_dead_symbols.py gate when the referencing code reaches into the doctrine catalog.
ContextDoctrine
Statuscanonical
Applicable to2.x
Related termsCharter offering, Active charter, Organization Tier

__all__ Declaration Convention

DefinitionThe project convention that every Python module with a public API must declare an __all__ list enumerating its exported symbols. The test_no_dead_symbols.py architectural gate scans the union of a module’s __all__ members and every public (non-underscore) module-level def, class and assignment (#470). A public name outside __all__ that is used inside its own module is not dead; an __all__ member used only inside its own module still is, because __all__ claims a cross-module export.
ContextDoctrine
Statuscanonical
Applicable to2.x
Related termsSymbol-level Dead Code, Ratchet Baseline