Terms describing the Doctrine domain model and doctrine artifact taxonomy.
Doctrine Domain
Definition
The 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).
A 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.
Context
Doctrine
Status
canonical
Applicable to
1.x, 2.x
Location
Precedence concept in governance model (no dedicated src/doctrine/guidelines/ directory in current tree)
A 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.
A constraint-oriented governance rule that applies across flows or phases. Directives encode required or advisory expectations and can reference lower-level tactics for execution.
A 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.
A 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.
Context
Doctrine
Status
canonical
Applicable to
1.x, 2.x
Location
src/doctrine/procedures/ and related doctrine procedure models
A 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.
A doctrine artifact defining cross-cutting quality and consistency conventions (for example coding, documentation, or testing style) that apply across missions and templates.
A doctrine artifact defining tool-specific operational guidance, syntax, and constraints (for example PowerShell usage conventions) used by agents and contributors during execution.
A 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.
A pull-based curation record for an external doctrine idea. Captures source provenance, target classification, adaptation notes, and adoption status before canonization.
The project-level selection layer that activates and narrows doctrine assets (for example selected paradigms, directives, agent profiles, available tools, and template set) without changing doctrine source artifacts.
The registry of all available paradigms, directives, template sets, and tools that the HiC can select from when building their charter. The charter compiler validates selections against this catalog.
A 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.
Directive 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.
Tactic 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.
Procedure 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.
Architectural 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.
Selection mode in which the charter declares an artifact is always 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."
Selection 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.
Charter-level list of (activation_context, doctrine_pack_id, artifact_id) tuples expressing which doctrine artifacts activate in which contexts. 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.
The 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.
A versioned, distributable bundle of doctrine artefacts (glossary terms, tactics, directives, agent profiles, styleguides, and toolguides) that can be installed into a project to govern its development practices. Packs are identified by a stable Doctrine Pack ID and registered in .kittify/config.yaml under doctrine.org.packs. The spec-kitty built-in pack is the base layer; project-layer overrides live at .kittify/doctrine/.
The stable identifier of a doctrine pack (declared in the pack's manifest or in .kittify/config.yamldoctrine.org.packs[].name). Used as the second tuple element in the Activation Registry to disambiguate when multiple packs ship artifacts with the same id. Special values: project (the project-layer pack at .kittify/doctrine/), built-in (the spec-kitty bundled pack).
Canonical 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. Any triggers: value declared on a shipped doctrine artifact must be a member of this set; the architectural test test_trigger_registry_coverage.py enforces no dead triggers. Mission B's WP05 populates the initial set.
A 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.
Shipped governance profile per mission type (software-dev, documentation, research, plan) at src/doctrine/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.
The field-naming convention for Global Selection entries. On the project charter (DoctrineSelectionConfig), 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 DoctrineService artifact kind has both a selected_* and a required_* field.
The three-tier Doctrine Relationship Graph composed of: (1) the shipped built-in layer (src/doctrine/drg/shipped.json), (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.
The middle layer of the three-layer DRG model, contributed by one or more configured org doctrine packs. Each pack ships an org-charter.yaml (governance policies and required artifact selections) and an optional drg/fragment.yaml (DRG extension nodes and edges). Organisation-tier content propagates to all consumer projects via apply_org_charter_to_interview and the standard charter pre-fill path.
A resolution context (charter.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 feature directory. 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).
A 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.
The 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.jsonworkflow_id field to record which sequence drove a given mission run. Org packs must not reuse shipped workflow IDs without explicit override semantics.
A snapshot of a quality metric (failure count, symbol count, dead-module count) recorded in tests/architectural/ratchet-baseline-*.md and enforced by the corresponding architectural gate. 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.
A dead-module or dead-symbol violation that has been explicitly classified as category 7 ("deferred — grandfathered") in the remediation tracking spreadsheet. 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.
A 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.
A 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 doctrine and by the test_no_dead_symbols.py gate when the referencing code reaches into the doctrine catalog.
The 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 uses __all__ as the canonical public surface; symbols absent from __all__ are not counted as dead even if unreferenced, and symbols present in __all__ but never imported externally are flagged as candidates for removal.