Understanding Charter: Synthesis, DRG, and Governed Context
Who is this for (1)
- Stakeholder Persona: Lead Developer — Written for the Lead Developer reader.
This document explains the Charter synthesis model and the DRG-backed context system. For a practical walkthrough, see How Charter Works. For step-by-step how-to instructions, see How to Synthesize and Maintain Doctrine.
What the charter bundle is
The charter bundle is the machine-readable synthesis of your charter.md governance document.
It is not a simple copy of the prose — it is a structured set of YAML artifacts that the runtime
can traverse, merge, and inject as context for specific workflow actions.
The core bundle lives in .kittify/charter/ and consists of:
governance.yaml— testing, quality, performance, branch, and doctrine-selection configdirectives.yaml— extracted directive list with IDs, descriptions, and severitymetadata.yaml— bundle metadata: charter hash, last-sync timestamp, provenance
references.yaml, context-state.json, synthesis manifests, and provenance sidecars are also
Charter-era files, but they are outside the narrow CharterBundleManifest v1.0.0 core scope.
Why is the bundle needed rather than raw prose? Because the runtime context injection requires a
structured artifact. When spec-kitty next prepares a prompt for the implement action, it
needs to select the directives that apply specifically to implement (not to specify or
review). A flat prose document cannot serve that purpose efficiently. The bundle provides the
structure for action-scoped context injection.
How synthesis works
The synthesis pipeline has four logical phases:
-
Parse:
charter synthesizereadscharter.mdand the interview answers. It also reads any agent-generated YAML from.kittify/charter/generated/(artifacts the LLM harness has written). -
DRG edge computation: The synthesizer constructs the Directive Relationship Graph (DRG) by resolving typed relationships between actions, directives, tactics, procedures, profiles, templates, and glossary terms.
-
Directive resolution: With the DRG computed, the synthesizer determines which artifacts need to be generated or updated. Artifacts whose provenance points to unchanged inputs are left intact (this is what makes
charter resynthesize --topic <selector>work — only affected artifacts are regenerated). -
Promote artifacts: The synthesizer writes resolved artifacts to
.kittify/charter-packs/(project-local doctrine) and records synthesis state under.kittify/charter/. The--dry-runflag stops after validation, before promotion.
The authoritative file throughout is always charter.md. The synthesizer reads it; it does not
write to it. Doctrine artifacts are outputs, not inputs.
DRG edge computation
The Directive Relationship Graph (DRG) is a directed graph with typed nodes such as actions, directives, tactics, procedures, profiles, templates, and glossary terms. Edges use these relations:
scope: action-to-artifact scopingrequires: hard dependencies between artifactssuggests: softer recommendations traversed to a bounded depthvocabulary: links from resolved artifacts to glossary scope/term contextinstantiates,replaces,delegates_to: additional graph relations used by specific doctrine surfaces
When the runtime prepares context for a specific mission action (e.g., implement), it traverses
the DRG from the action’s entry node. It follows scope edges first, then transitive requires
edges, bounded-depth suggests edges, and one-hop vocabulary edges from the resolved nodes.
That keeps implementation prompts focused on implementation-relevant doctrine instead of
specification-phase concerns.
The DRG is not stored as a standalone file that you can inspect directly. It is computed by the synthesizer and manifests as the structured content of the bundle artifacts.
Mission-type governance grains
Per-mission-type governance also resolves through the charter layer, keyed off the
mission_type recorded in a mission’s meta.json — never inferred from
template_set and never defaulted to software-dev. It is authored at two grains
that the resolver unions and de-dupes: an action-grain source
(missions/<type>/actions/<action>/index.yaml, which generates the DRG scope
edges described above) and a type-grain source
(missions/<type>/governance-profile.yaml), which is also the project-override
target. A full explanation of that seam — the reserved slots for templates and
gates, the per-type override, and the leak-closure invariant — lives in
Mission-Type Resolution.
Bootstrap vs compact context
The DRG traversal for a given action can produce large payloads for complex governance structures. Two modes handle this:
Bootstrap mode: On the first load for an action (or after a fresh synthesis), the full relevant DRG subgraph is injected into the governed profile invocation. The agent sees all applicable directives, tactics, and glossary terms for its current action, plus the full doctrine library references.
Compact-context mode: When the DRG context payload exceeds the size threshold for inclusion, the runtime falls back to compact-context mode. In this mode, the agent receives only the resolved paradigm list, directive list, and tool list — without the full doctrine library text. This is a known limitation (see issue #787 in the project issue tracker; check that issue for current resolution status). Do not assume full-context behavior unconditionally on large governance layers.
First-load state is tracked per action in .kittify/charter/context-state.json. Each action
(specify, plan, implement, review) has an independent first-load timestamp.
Why the authoritative vs generated distinction matters
Charter governance is built on a strict read/write boundary:
- Authoritative policy source:
.kittify/charter/charter.md— human-edited, the source of truth for project governance policy. - Derived config and runtime state:
governance.yaml,directives.yaml,metadata.yaml,references.yaml,context-state.json, synthesis manifests, and provenance sidecars — owned by their respective CLI commands. - Project layer:
.kittify/charter-packs/— promoted bycharter synthesizeand read alongside the built-in Charter Pack. - Agent-generated synthesis input:
.kittify/charter/generated/— written by the harness and validated bycharter synthesize.
If you edit a derived file (for example, add a directive to governance.yaml directly), the edit
can be lost on the next charter generate run because those files are
re-derived from charter.md. There is no merge step for derived config.
charter status detects drift between charter.md and the bundle hash. charter lint detects
decay within the DRG (orphaned artifacts, contradictions, staleness). Both tools exist precisely
because the authoritative/generated boundary creates a risk of divergence if synthesis is not run
after charter edits.
Known limitations
-
Compact-context mode (issue #787): Large governance layers may trigger compact-context fallback, causing agents to receive summarized rather than full doctrine context. The workaround is to reduce governance scope or break the project into smaller governance domains.
-
Fresh-project synthesis: On a project where
.kittify/charter/generated/is missing or empty (no agent-generated artifacts),charter synthesizeproduces only the minimal artifact set (directory marker and PROVENANCE.md). The runtime falls back to the built-in Charter Pack until a full synthesis run with agent-generated content completes. -
Synthesis requires
charter.md:charter synthesizewill exit non-zero ifcharter.mddoes not exist. Runcharter interviewandcharter generatefirst.
The shipped-graph orphan residual (current state)
An orphan is a DRG node with no inbound and no outbound edge. Some orphans are intentional — a deliberately authored artifact with no single natural referent, or a structural node that is resolved by lookup rather than by traversal. Doctrine forbids deleting such an artifact or manufacturing an edge to zero the metric (D-C2 / C-003): every orphan is either wired to a real referent or recorded here.
This section is the live, current-state record. It is bound to the measurement by
test_documented_residual_matches_measured_shipped_orphans in
tests/specify_cli/cli/commands/test_doctrine_regenerate_graph.py: the URNs in the block below must
equal the shipped graph’s orphans exactly, so an unrecorded new orphan, or a recorded one that has
since been wired, fails a test rather than passing as prose drift.
How to recompute it — never copy the list from prose:
from charter.offering.drg.loader import load_built_in_graph
g = load_built_in_graph()incident = {u for e in g.edges for u in (e.source, e.target)}orphans = sorted({n.urn for n in g.nodes} - incident)print(len(orphans))print(*orphans, sep="\n") # the membership the block below must equalCurrent state:
mission_step_contract:documentation/acceptmission_step_contract:documentation/auditmission_step_contract:documentation/designmission_step_contract:documentation/discovermission_step_contract:documentation/generatemission_step_contract:documentation/publishmission_step_contract:documentation/validatemission_step_contract:plan/planmission_step_contract:plan/researchmission_step_contract:plan/reviewmission_step_contract:plan/specifymission_step_contract:research/gatheringmission_step_contract:research/methodologymission_step_contract:research/outputmission_step_contract:research/scopingmission_step_contract:research/synthesismission_step_contract:software-dev/implementmission_step_contract:software-dev/planmission_step_contract:software-dev/reviewmission_step_contract:software-dev/specifymission_step_contract:software-dev/tasksglossary_pack:spec-kitty-coreagent_profile:human-in-chargestyleguide:deployable-skill-authoringtoolguide:powershell-syntax
Why each group is residual
| Group | Count | Disposition |
|---|---|---|
mission_step_contract:<mission>/<action> | 21 | Edge-less by construction. The step-contract fragment ships edges: []; the activation engine resolves a contract by URN lookup on the (mission_type, action) join, never by traversal. Deleting or edging them to shrink the metric is what D-C2 / C-003 forbid. The 21 are the 17 shipped by doctrine-controlled-transition-gates (7 documentation + 5 research + 5 software-dev) plus the 4 plan/* contracts vendored by #6379. Membership is pinned as _EDGELESS_BY_CONSTRUCTION. |
glossary_pack:spec-kitty-core | 1 | Awaiting references. The pack node ships with zero outbound references; its enforcement fields stay inert until a follow-up mission gives it a real referent. Inventing one now would be a guessed edge. Pinned in _AWAITING_REFERENCES. |
agent_profile:human-in-charge | 1 | Runtime-assignment sentinel. Signalled by assigning a work package to a human at runtime, never by a static doctrine edge. |
styleguide:deployable-skill-authoring | 1 | Direct-activation-only. Reached by charter activate styleguide deployable-skill-authoring; no defensible source artifact exists to carry an inbound edge (a guessed one is refused, C-003). Pinned in _DIRECT_ACTIVATION_ONLY. |
toolguide:powershell-syntax | 1 | Runtime tooling. Real PowerShell-authoring content consumed by agents at runtime; no built-in artifact cites it. Admitted by PR #2936. |
Ceiling history
There is no numeric ceiling any more: the membership block above, checked for equality against the measured shipped orphans, is the only guard (a ceiling could not see a shrink or a silent raise). The history of the retired ceiling, so the old numbers are never bare:
| Ceiling | Cause |
|---|---|
| 14 | Post-WP05 curated baseline (9 Fowler tactics wired, 12 orphans wired). |
| 18 -> 14 | A stopgap raise for 8 structural mission-type nodes, reverted once mission-type-drg-edges (#2677) emitted the mission_type -> action edges. |
| 29 | doctrine-controlled-transition-gates (epic #2535 half A) shipped 17 edge-less step contracts. |
| 30 | PR #2936 promoted toolguide:powershell-syntax from a dead file to a live, edge-less node. |
| 30 -> 21 | Ratcheted after both #3007 residuals were retired/wired and six other artifacts were wired; a ceiling cannot see a shrink, so it was ratcheted rather than left with nine points of silent slack. |
| 22 -> 21 | charter-delivery-finish-context-degod (#3064) relocated asset:common-charter-scaffold-minimal to charter-pack status, removing the node. |
| 21 -> 25 | The built-in pin bump of PR #6379 vendored the plan mission’s four step contracts (#6432), which are edge-less by construction like the other 17. No edge was wired; packs/built-in/ was untouched. Recorded by mission charter-synthesis-graph-and-languages-01M59RZ5, and the live record above was added under #6513 so the raise has a writable home. |
Where the older records live
kitty-specs/mission-lifecycle-dispatch-drg-closeout-01KV0S99/drg-orphan-residual.mdis the canonical historical record (WP05, #1923). It sits underkitty-specs/, an immutable archive root (tests/architectural/test_archive_root_byte_identical.py), so it is frozen: cite it for the curation narrative of its date, never edit it, and do not read its last ceiling (29 -> 30 over 17 step contracts) as current state._INTENTIONAL_ORPHANS/_SHIPPED_ORPHANSintests/charter_offering/drg/migration/test_extractor_projection.pyare the pure-extractor frame membership pins. This page records the shipped frame (load_built_in_graph()), which is the frame the membership guard measures; the two differ only by_ORPHANS_RESOLVED_BY_OVERLAY, so neither may be “corrected” against the other.tests/charter_offering/drg/test_reachability.pypins the companion reachability measure (action-unreachable vs profile-delivered), which is a different question from incidence: a node can be edge-incident and still unreachable from any action.