Skip to main content
Vexa is governed by written, enforced law — not convention. Three documents, each governing a different noun; two operational protocols bookending the contribution loop; a set of surfaces where humans and agents meet the system; and one amendment mechanism through which the law itself evolves. This page is the map.

​
The trinity

AGENTS.md is deliberately the thinnest: it owns no law of its own — it binds a session to the other two and adds only session mechanics (worktree isolation, the expect→verdict loop, the claim heartbeat).

​
The two protocols

Each phase of the delivery loop has an operational protocol — an agent-runnable prompt, not prose about process:
  • PREPARE — signal → spec. Turns one queue item (a raw report, an incident, a failure mode) into a prepared issue: code-grounded, harnessed, carrying an acceptance table that guarantees merge.
  • TAKE — PR → verdict. Triages a delivered PR against its issue’s declared floor: bundle before diff, row-by-row in the issue’s own numbering, the floor never moved, the plan-bug rule owned on our side.
The prepared issue is the hinge between them: the output of PREPARE and the input of a contributor’s work — a PRD whose acceptance table is a merge promise.

​
Surfaces and actors — one pass around the loop

​
Who enforces what

  • The P-book: machines. The CI gate suite (28 gates) — red or it didn’t happen. The live map of principle → gate is Architecture compliance, generated, never hand-edited.
  • The D-book: process. The state-label machine (exactly one state: per issue), acceptance floors, value signing. The enforcement map — including the honestly-marked TO-BUILD rows (the value-signed status check, the label bot) — is the enforcement map.
  • The actor contract: visibility. No gate checks the expect→verdict loop — the human reading the ledger is the gate.
  • Contributor rights: declaration + DCO + attributable corporate authorization. Individuals make one conscious choice and encounter no CLA; employer-controlled work waits for a private receipt bound to the current PR head.

​
How the law itself changes

No principle is edited casually. The amendment loop:
surprise → root-cause with a human → learning → ADR on lane:contract (human-reviewed) → new principle in the P-book or D-book → new gate that enforces it.
The case law lives in docs/adr/ — decision records the constitutions cite by number. Machine models keep both books executable: the P-book’s is architecture.calm.json (FINOS CALM, drift-gated); the D-book’s is the roadmap board itself.

​
The one idea underneath

Agents made code cheap. The scarce input is verified truth about delivered value — so every mechanism above exists to route human attention to the one thing only humans can give: “I ran it, and I witness the value.” Validation is credited as authorship’s equal, invalidation is a first-class result, and nothing merges on anyone’s say-so alone — including ours.