The charter schema defines what a valid Gator charter looks like: the structure that validators, tests and other models can rely on, in any governed repository.

What the schema covers

Version charter-schema-v1 is the official local schema, codified from working Gator charters. It is stable enough for local validator implementations, cross-model consistency checks, external experiments that use Gator charters, and research that compares charter quality across repositories.

It covers the charter file structure, the function-entry structure, the INDEX.md dispatch table, and the minimum structure of the cross-cutting charter. It does not define how a model discovers module boundaries, how tripwires are found, or how the first charter set is formed. That is the Charter formation process, in this Docs list.

Design principleMeaning
Structural, not qualitativeThe schema checks shape and minimum expectations, not whether a charter is insightful.
Stable enough for toolingExternal validators and experiments can rely on the basic format.
Flexible notationBoth ASCII (<- / ->) and Unicode (← / →) arrows are accepted.
Skeleton-friendlyA thin but structurally valid charter is still a charter.

The charter file

Charter files live in .gator/charters/. _template.md and README.md are excluded from validation.

Anatomy of a charter file A charter file shown line by line, with each line's enforcement level. Error, meaning required: the "# Charter:" title, the "Covers" line (exempt for the cross-cutting charter), "## Owns", "## Does Not Own", and a "---" separator before function entries. Function entries are optional; inside each, the File line and a description are Warn, and access patterns, callers, callees and tripwires are optional. "## Before Changing This Module" and "## Connections" are Warn when function entries exist. # Charter: [Name] ERROR First line of the file **Covers**: `path/to/files` ERROR Exempt for the cross-cutting charter ## Owns ERROR What this module is responsible for ## Does Not Own ERROR What belongs elsewhere --- ERROR Required before any function entries ### function_name(args) OPTIONAL Zero or more function entries File: path/to/file.py WARN Recommended [Description] WARN At least one plain line @reads / @writes OPTIONAL Access patterns ← callers → callees OPTIONAL Also accepts <- and -> ! tripwire OPTIONAL Non-obvious behaviour ## Before Changing This Module WARN When function entries exist ## Connections WARN When function entries exist
Figure 1 — a charter file, line by line. ERROR blocks validation; WARN is reported but does not block; OPTIONAL is not required.

Section rules

SectionEnforcementNotes
# Charter: [Name]ErrorFirst line of the file
**Covers**:ErrorExempt for cross-cutting charters
## OwnsErrorMust exist
## Does Not OwnErrorMust exist
--- separatorErrorAt least one, before any function entries
## Before Changing This ModuleWarnRecommended when function entries exist
## ConnectionsWarnRecommended when function entries exist

Function entries

Each function entry starts with ### inside a charter file.

ElementEnforcementFormat
HeadingError### name(args) or free-form after ### . Disambiguate duplicate names with [filename.ext] when needed.
File lineWarnA File: line is recommended
DescriptionWarnAt least one non-annotation line after the heading
Access patternsOptional@reads:, @writes:, Models:, Filesystem:, Session R:, Session W:
CallersOptional← or <- prefix
CalleesOptional→ or -> prefix
TripwiresOptional! prefix

INDEX.md

Every .gator/charters/ directory should have an INDEX.md: the dispatch table that tells a model which charters to read before it changes a given path.

ElementRequiredFormat
TitleYes# Charter Index
Cross-cutting pointerNoAn “always read first” line pointing to cross-cutting.md
Dispatch tableYesA Markdown table that maps code paths to charter files

The cross-cutting charter

If a cross-cutting charter exists, it holds the multi-module invariants: the rules that break during a refactor because the relationship between modules was violated.

ElementRequiredFormat
At least one TRIPWIRE or Pattern sectionYes## TRIPWIRE: or ## Pattern: heading
## OwnsYesThe multi-module invariants in scope
## Does Not OwnYesModule-specific logic, which belongs in the module charters

Severity model

SeverityMeaningExit code
ErrorSchema violation: a required element is missing or malformedCauses exit 1
WarnSuspicious but not broken: an optional-but-recommended element is missingNo effect
InfoSuggestion: the entry is sparse but validNo effect

See also charters/README.md for notation, philosophy and anti-patterns, and charters/_template.md for a blank charter.