The constitution

The constitution is a one-page statement of the project’s binding rules. Because every agent reads it at the start of every session, a wrong sentence in it affects all ongoing work at once, and for that reason this document gets stronger governance than any other artifact in the project.

What goes in

A single test decides admission: would violating this statement justify stopping work? If not, the statement is a preference rather than a rule, and it belongs somewhere else. Here are a few clauses from an order system’s constitution:

C-03  Monetary amounts are integer cents. Floating point money is
      inadmissible anywhere. [v1.0.0]
C-07  Billing entity is the invoice grouping key. [v1.1.0, origin:
      demo finding 2026-03]
C-11  Order ingestion is idempotent. Duplicate submission of an
      order event MUST NOT create duplicate state. [v1.0.0]
C-19  p95 latency budget on order-read paths: 300 ms. [v1.2.0]

Clause C-07 shows the usual way such rules come into being: a demo caught a wrong grouping once, the team decided this should never be guessed again, and the lesson was promoted into law.

How it changes

Changes go through amendments, which are pull requests with a written rationale. A shortened example:

Amendment: adopt event sourcing for the order store
Version: 1.4.2 -> 2.0.0 (major: invalidates the persistence clause)
Reason: cross-region replication requirement from feature 0031.
Rejected alternatives: dual writes (consistency risk under partition);
change-data-capture (adds an operational system for one use case).
Invalidates: C-14 (old persistence clause); nine increments built
under v1.x touch persistence (see census below).

The version numbers follow a simple convention. A patch version clarifies wording. A minor version adds a rule that binds future work. A major version invalidates existing work, and the next section shows why that distinction pays off.

The version stamp

Every slice of work records the constitution version it was built under, as a single line:

Constitution-Version: v1.4.2

This small habit provides three capabilities. The history of any module can be traced to the rules that were in force when it was written, which answers questions like “why does this code predate event sourcing”. After a major change, finding the affected work becomes a query over the stamps rather than an investigation; in the amendment above, the query returned nine increments, of which six were left in place with a note and three were scheduled for migration. And rollback becomes a decision with visible costs: five months later, when someone proposed reverting the amendment after a latency regression, the stamps showed that fourteen increments had been built on it in the meantime. With that number on the table, the team chose a small corrective amendment instead.

It shrinks too

On a regular schedule, the retrospective merges related clauses into broader principles and deletes superseded ones. One such session in the example project took the constitution from 31 clauses to 24, with a note per deletion explaining why nothing enforceable was lost. Without this pruning, the document only grows, and over time it becomes too long for its readers, agents included.

Full treatment: Project rules that can change safely.