Project rules that can change safely

Series: Aigile deep dives, paper 03 of 09. Elaborates working paper Section 7. Depends on Paper 02.

Abstract

The constitution is the anchor artifact of the durable layer: the smallest written statement of a project’s binding intent. Because every agent reads it in every session, it has the widest blast radius of any artifact in the system; an error in it is not a mistake but a broadcast. This paper specifies its content model, its amendment process, its semantic versioning, the increment-stamping mechanism that makes it auditable, and its rollback semantics. The governing design principle: law-like process, Git-native mechanics. The constitution must be deliberately hard to change and deliberately possible to change, and must never silently drift or silently freeze.

1. Position in the framework

The constitution is where humans exercise architectural authority (the second form of intent ownership under the core invariant). It is the escalation target of Papers 05’s constitutional drift class, the subject of Paper 08’s gardening, and the source of the mandate under which agents act in Paper 07.

2. The problem in full

Foundational knowledge in software projects has historically lived in one of two bad regimes. In the frozen regime (waterfall baselines, architecture handbooks), the foundation is protected but cannot learn; reality departs from it and the document becomes fiction with a signature. In the wiki regime, the foundation can learn but is unprotected; anyone edits anything, authority is unclear, and load-bearing statements decay alongside trivia. Human teams survived both regimes because senior engineers carried the real constitution in their heads and enforced it in review. Agents remove that safety net: the written constitution is the only constitution an agent has, so the document itself must carry the properties the seniors carried, namely authority, memory of rationale, and the capacity to change deliberately.

Blast radius drives the design. A wrong sentence in a story spec misleads one increment. A wrong sentence in the constitution misleads every agent session everywhere simultaneously, with the confident consistency that makes agent error distinctive. Governance strength must be proportional to blast radius, which is why the constitution gets law-grade process while story specs get one-sitting review.

3. The mechanism

3.1 Content model

The constitution admits five content types, each with an example shape:

1. Constraints: “All service communication is asynchronous except the checkout path.”
2. Invariants: “Monetary amounts are integer cents; floating point money is inadmissible anywhere.”
3. Decisions with rationale: technology and pattern choices in ADR form (context, decision, alternatives rejected, consequences). The rationale is not decoration; it is what lets a future amendment know what it is overturning.
4. Quality bars: test coverage floors, latency budgets, review requirements.
5. Collaboration law: the authority matrix settings (Paper 07), deviation and demo protocols in force, prompt and wording norms that Paper 08 promotes.

Inadmissible: anything derivable from code (R3), tutorials, aspirations without enforcement intent, and any statement nobody would stop the line to defend. The admission test is behavioral: a clause belongs in the constitution only if its violation should pull the andon cord. If violation would be waved through, the clause is culture or preference, not law, and it lives elsewhere or nowhere.

3.2 The amendment process

Amendments are pull requests against the constitution file, carrying a mandatory rationale block: what changes, why, alternatives rejected, what existing material is invalidated. Approval authority follows the matrix: a competent human decides in collaborative setups, supported by AI analysis of the amendment’s impact; in fully agentic setups a lead-architect agent may hold the authority within a human-granted mandate, and the mandate itself, its appointment, scope, and revocation, remains human (Paper 07). Discussion happens on the PR, where it becomes part of the record. The latency budget applies: an amendment decision has a deadline, because a constitution that takes weeks to amend teaches the team to route around it, and routing around the constitution is how the wiki regime returns.

3.3 Semantic versioning

• Patch (x.y.Z): clarification; no existing spec or code is invalidated.
• Minor (x.Y.0): a new constraint or decision; future work is bound, existing work is grandfathered until touched.
• Major (X.0.0): an existing clause is changed or removed such that existing specifications or code become non-conforming.

The version taxonomy is not bureaucratic classification. It is a machine-readable statement of blast radius, and it drives the impact process: a major amendment mechanically triggers the census described next.

3.4 Increment stamping

Every increment records the constitution version it was built under, one line of metadata in the PR and the archive. This purchases three capabilities:

• Auditability. “Why does the ingestion module look like this” becomes answerable: built under v2.1, before the event-sourcing amendment. Code archaeology gains a chronology.
• Impact census. After a major amendment, the set of increments built under older versions is a query, not an investigation. Each is dispositioned: migrate, grandfather with a note, or schedule for the next touch.
• Honest rollback. Reverting an amendment does not un-build the code built under it. The stamp trail identifies exactly which increments embody the reverted assumption, so the cost of a constitutional mistake is enumerable rather than diffuse. Rollback in the constitution is therefore a forward operation: a new version that restores prior text, plus a census of what was built in the interim.

3.5 Gardening interface

The constitution grows by amendment and shrinks only by gardening (Paper 08). Each gardening session may consolidate clauses into principles, demote derivable content, delete superseded law, and must leave the version history intact; gardening ships as an ordinary amendment PR, usually minor.

4. Normative protocol

R7 (Andon admission test). A statement enters the constitution only if its violation warrants stopping the line. All admissions occur through the amendment process. R8 (Amendment form). Every amendment is a PR carrying rationale (change, reason, rejected alternatives, invalidations), receives a semantic version, and is decided within the standing latency budget by the authority the matrix assigns. R9 (Stamping). Every increment records its constitution version. Major amendments trigger an impact census over older stamps, and every censused increment receives an explicit disposition. R10 (No silent paths). The constitution is never edited outside the amendment process, never forked informally, and never allowed to accumulate unversioned local exceptions. Discovered violations take the deviation or drift protocols (Paper 05), never quiet correction.

5. Orderly worked example

Orderly’s constitution v1.0 is one page: eleven clauses, including integer-cent money, idempotent ingestion, billing entity as the invoice grouping key, and a 300 ms p95 budget on the order-read path. In month four, a feature needs cross-region replication, and the team proposes event sourcing for the order store. The amendment PR carries the rationale and rejects two alternatives (dual writes; change-data-capture) with reasons. It is major, v2.0.0, because it invalidates the existing persistence clause. The impact census over stamps v1.x returns nine increments touching persistence; six are grandfathered with notes, three are migrated as scheduled stories. Five months later a latency regression is traced to the amendment’s read-model assumption; rollback is proposed and rejected after the census shows fourteen increments now embody event sourcing, and a corrective minor amendment (v2.3.0, read-model caching mandate) is chosen instead, precisely the enumerable-cost decision stamping exists to enable. The rejected rollback and its reasoning are themselves recorded, because the next engineer to feel that regression will otherwise propose it again.

6. Failure modes

• The statute book: growth without gardening until agents drown in context and humans stop reading. Counter: R3, Paper 08 cadence, and tracking Layer 1 line count as a first-class metric.
• The ceremonial constitution: violations observed and waved through. One waved violation reprices every clause to zero; R7 exists to keep un-defended statements out so that defense remains credible.
• The shadow constitution: real constraints living in prompts, chat history, or one architect’s head. Detection: deviations repeatedly resolved by appeal to unwritten rules signal shadow law needing promotion.
• Amendment sludge: decision latency so high the team routes around the process. Counter: the latency budget is itself constitutional law and its breaches are incidents.

7. Metrics

Constitution size over time (stable or shrinking after month three); amendment latency against budget; violations detected per month and their resolution class; census disposition times after major amendments; share of deviations resolved by appeal to unwritten rules (shadow-law indicator, target zero).

8. Open questions

Constitution federation across teams and the shape of inter-constitution contracts; whether clause-level freshness stamps (last defended at increment N) add value or noise; automated impact-census tooling over stamps; the interaction of R9 with regulated traceability regimes, which it appears to satisfy almost by accident.

9. Derivative artifacts

Constitution template with the five content types and admission-test checklist; amendment PR template; playbook chapter on bootstrapping a constitution from an existing codebase; governance one-pager for executive material; tooling requirements for stamping and census queries.