Skip to content

The Constitution

Provisioned as a constitution: a small inviolable foundation + everything else explicitly tunable on top.

New here? This page is the map of how CompassAlpha is organized: a few rules that never change, a few that protect you, and a lot of dials you set to fit your own project. Read it once and you'll know where everything else in the docs lives.

CompassAlpha is structured constitutionally — like a written constitution for a polity. There's a small set of inviolable principles (axioms), a set of protective rules (guardrails), and then a wide surface of decisions you make for your specific project (tunables and toggles).

The four-layer constitutional model

The four-layer constitutional model — Axioms (bedrock) · Guardrails · Tunables · Toggles

Higher layers DERIVE from lower layers. Toggles bundle tunables. Tunables operate on top of guardrails. Guardrails defend the axioms. The axioms are the bedrock.

When you adopt CompassAlpha, you accept the axioms unchanged, you accept the guardrails as protection, and you make decisions on tunables + toggles for your specific project.


Layer 1: The 8 Axioms (INVARIANT)

These rules cannot be modified without forking the framework. They define what CompassAlpha is.

“Cannot be modified” is about the rules — not how much you adopt at once

Accepting the axioms unchanged does not mean converting your whole estate on day one. Adoption is incremental and per-unit: you bring one project, module, or team under CompassAlpha at a time — that's the whole point of the adoption ladder and the brownfield parallel-track, where governed and not-yet-governed units run side by side. The axioms govern each unit you bring in, whenever you bring it in — and different teams can sit on different rungs at the same time, indefinitely. What you can't do is keep a unit under CompassAlpha while quietly watering down a rule for that unit — that part is what would require forking. Immutable rules, incremental rollout.

# Axiom One-line essence Detail
1 Tier grammar Mentor-1 / Mentor-2 / Doer per axis →
2 Firewall Confined, not banished. Mentors track only their granularity. →
3 Persistence law Flush before disclose. State on disk + at origin BEFORE discussed. →
4 Hard labour rule Mentors never touch substrate. Doer is the only labour tier. →
5 Bus protocol Inbox-in-destination-folder. Sender writes, founder pings, recipient pulls. →
6 Provenance law Cite by substrate. Never trust institutional memory unverified. →
7 Git foundations GIT_INDEX_FILE + worktree + commit-tree per session. →
8 Amendment protocol Discoveries flow up, ratified truth flows down. The constitution learns at a council-run train. →

Each axiom defends against one or more of the four pathologies. If you try to weaken any axiom, you'll re-introduce the pathology it was preventing.

What 'invariant' means in practice

If you find yourself wanting to violate an axiom for short-term gain, stop. The axiom exists because that shortcut has been tried before and the consequence was costly. The framework's value is exactly in these constraints. If your project genuinely needs to violate an axiom, you're using the wrong framework — fork it or adopt a different one.


Layer 2: Guardrails (PROTECTIVE)

These are the failure modes the framework defends against, with documented recovery patterns when failures occur anyway.

Guardrail Defends against Detail
Pollution containment Context bleed across tiers →
Hallucination defense AI institutional-memory false-positives →
Stale snapshot detection Firewall leak (snapshot ≈ live) →
Failure modes catalog 6 known classes + recovery →
Brief completeness Improvisation by Doers on incomplete briefs →
Single-live-writer Cross-session clobber on shared state →
Minimal-sufficient bus Bus bloat / context overload across tiers →
Retrieval discipline Retrieval (RAG) re-introducing pollution / stale / ungrounded context →
Disaster reconciliation State divergence after an unclean shutdown / crash →

Guardrails are NOT independent of axioms — they DERIVE from axioms. The single-live-writer guardrail derives from the firewall axiom. Stale snapshot detection derives from the firewall + persistence axioms.


Layer 3: Tunables (CONFIGURABLE)

The customization surface. Every tunable has a default, a range, and a documented trade-off.

The five primary axes in tension (no combination optimizes all):

  • ⏱ SPEED — wall-clock to deliverable
  • 🧠 INTELLIGENCE — depth, correctness, coverage
  • 💰 COST — tokens + founder cognitive load + maintenance
  • ⚠ RISK — pollution, hallucination, drift, replay
  • 📐 PREDICTABILITY — cycle/scope estimability

A conservative profile biases toward intelligence + low-risk (LAYGO — Learn As You Go, meaning each step is taken in sequence and the next one starts only once the last is understood — concurrency, pure RELAY, fresh-per-slice, xhigh effort, strict provenance). Other project profiles want other bias points.

Tunable categories:


Layer 4: Toggles (LIVE)

Toggles are tunables seen from the timing perspective: when can each one flip?

  • Runtime toggles — flip mid-cycle (rare; usually escalation-class) → →
  • Cycle toggles — flip at cycle boundaries → →
  • Project-lifecycle toggles — flip only at project-wide seams → →
  • Operating presets — named bundles of toggles (Conservative · Throughput · Risk-averse · ...) → →

How the layers compose

A worked example: a conservative profile biased toward intelligence + low-risk.

How the four layers compose — AXIOMS and GUARDRAILS are an invariant foundation (the same every project); TUNABLES and TOGGLES are the configurable top a project sets, shown here as a Conservative profile

An invariant foundation, a configurable top. The bottom two layers (axioms, guardrails) are the same for every project; the top two (tunables, toggles) are the profile a project chooses — here, Conservative. Swap the profile and the foundation is untouched. The same values, written out:

LAYER 1 (axioms):     all 8 axioms in force (always — invariant)
LAYER 2 (guardrails): all 9 guardrails active (always — derived from axioms)
LAYER 3 (tunables):
                      concurrency = LAYGO
                      context_patterns = {fresh-per-slice doer, verbose digests, liberal memory}
                      ai_model = top-tier all tiers
                      lanes_enabled = {Doctrine Cycle, Phase 3, Polish, Surgical}
                      ...
LAYER 4 (toggles):    operating_preset = Conservative
                      (this bundles the LAYER 3 settings above)
                      rotation_cadence = "2-4 weeks preventive"
                      ...

Same axioms, same guardrails. Different project = different tunables + toggles. The constitution stays; the customization changes.


The doctrine substrate: Charter, Compasses, and Axis annexes

Team federation — one Charter at the top, distributed teams inheriting it, Git as the glue

Team federation: a single Charter at the top, inherited by distributed teams wherever they sit, with Git as the glue that binds them into one coherent codebase — the essence of GitAI. Click to open full size.

The four layers above describe the framework. A specific federation's doctrine — the living constitution it actually governs by — is organized as a single hierarchy with one source of truth:

  • One federation Charter. Each federation has exactly one Charter — its constitution. It is not split per team or per component; that single document is what every tier and every human cohort is bound to.
  • Components are Compasses. Each component of the project gets its own Compass (the 60K/30K/10K deliverable, plus any variants) under the one Charter. "A charter per component" means, in practice, a per-component Compass governed by the single Charter — not a separate constitution per component.
  • Axes are annexes. Each declared axis — build, doctrine, and any DECOUPLED Day-2 axis (ops, QA, audit) — registers as an annex under the same Charter: its declaration plus any axis-specific invariants and primitives. An axis never gets a competing charter.

This single-source-of-truth shape is what makes cross-team codebase coherence possible: one canonical place defines each concept, so there is no room for divergent or duplicated implementations of the same thing. It is also what lets a federation scale physically across many human teams (cohorts) without the codebase drifting — every team builds its segment under the one Charter.

What each doctrine artifact controls — and loosens

The three named artifacts under the Charter each sit at a deliberate altitude, and each declares what it locks down versus what it leaves open:

Artifact Where it sits Controls (locks down) Loosens (leaves open) Why it's there
Invariants Charter · federation-wide the rules that must hold everywhere, always — the non-negotiables nothing — invariants are not tunable define what can never break across the whole federation; the bedrock of coherence
Primitives Charter · shared contracts the one canonical definition of each shared concept (types, operations, vocabulary) every component reuses a component's internal use of a primitive; new primitives may be proposed prevent divergent re-implementations of the same concept — the mechanism of cross-team coherence
Compass under the Charter · one per component a single component's own doctrine (60K ideology · 30K mechanics · 10K schema) per-component design latitude within the Charter localize component-specific doctrine while staying bound to the one Charter

This is the constitutional spirit applied to the doctrine itself: Invariants are maximally controlled, Primitives lock the shared contracts yet stay extensible, and Compasses are the loosened, per-component surface — tight at the center, flexible at the edges.

Charter, Compasses and axis annexes — and the GO-UP-BUMP / sub-bump ladder

Version bumps: GO-UP-BUMP vs sub-bump

Two bump levels keep the hierarchy honest:

Bump Scope When
GO-UP-BUMP the federation Charter (charter-v<n+1>) a doctrine cycle closes and re-locks — cross-cutting / charter-level change
sub-bump (GO-SUB-BUMP) a single Compass / entity (sub-v<n+1>-<entity>) one component's doctrine is amended within a cycle

A cohort team releases only against the current chartered Compass; any cross-cutting change must flow through a GO-UP-BUMP, never an ad-hoc release. That discipline is what prevents "someone had an idea and shipped" from fracturing a multi-team codebase.

For a worked walkthrough of several teams each owning a component under one Charter — including how the founder/relay avoids becoming a bottleneck and how teams sit on different adoption rungs at once — see Multi-team federation.


The "provisioned as a constitution" property

The founder's framing: "toggles with every possible detail provisioned as a constitution."

What this means concretely:

  • Every detail is explicitly named. Nothing implicit. Tunables are catalogued (LAYER 3). Toggles are catalogued (LAYER 4). Invariants are catalogued (LAYER 1).
  • Every detail has a default. New adopters can be functional without making every decision; the Conservative preset's defaults work for most cases.
  • Every detail is documented. The reasoning behind each default is recorded. Trade-offs are explicit.
  • Every detail is auditable. A new team member can trace any decision to its layer.
  • Every detail respects the layer hierarchy. Tunables defer to guardrails defer to axioms. No upper layer overrides a lower one.

This is what makes CompassAlpha constitutional rather than ad-hoc.


Reading the constitution

A practical order:

  1. Now: skim this page (you're here)
  2. Next 30 minutes: read all 8 axioms (→)
  3. Next hour: read all 9 guardrails (→)
  4. Next 2-3 hours: skim the tunables (don't memorize) (→)
  5. As needed: refer to toggles when you need a specific switch (→)

You don't need to memorize tunables and toggles — those are reference material. You DO need to internalize the axioms and guardrails — those govern every interaction.


Versioning the constitution

The constitution evolves. Like real-world constitutions, it has amendment cycles — but unlike real-world constitutions, the procedure is itself documented.

  • Axioms: changed only by forking the framework (rare; if ever)
  • Guardrails: changed by community consensus + reference-implementation validation
  • Tunables: extended frequently; existing tunables are stable
  • Toggles: extended in lockstep with tunables

A reference federation's doctrine cycle (e.g. Charter v0.4 → v0.5) informs and validates the framework's own evolution — it does not amend the axioms, which still change only by forking. Each cycle is documented in the Changelog.


Remember this

  • CompassAlpha is built like a constitution: a tiny set of rules that never change (the axioms), a set that protects you (the guardrails), and a wide surface of dials you set for your own project (tunables and toggles).
  • The layers stack downward: toggles bundle tunables, tunables sit on guardrails, and guardrails defend the axioms. Higher layers can't override lower ones.
  • You only need to internalize the axioms and guardrails. Tunables and toggles are reference material — look them up when you need them.
  • Every federation governs by one Charter as its single source of truth; each component gets a Compass under it, so teams can spread out without the codebase drifting apart. For the bigger picture of how the pieces fit, see the mental model.

Next: Codebase coherence →