Writing an Architecture Constitution: LEO's Approach to Preventing Drift

In most software projects, architectural intent exists in the minds of the original designers and degrades over time as new contributors add features without understanding the original constraints. LEO explicitly addressed this by writing a formal Architecture Constitution stored in backend/docs/.

The Constitution comprised 14 numbered documents:

The Constitution established these non-negotiable rules (examples):

From ARCHITECTURE_PRINCIPLES.md:

• "No component outside the Provider Platform may have any knowledge of specific AI models"
• "The OS infrastructure is complete. Future development must focus on extending behavior using existing infrastructure"
• "Every new feature must reuse existing infrastructure"

From ENGINEERING_RULES.md:

• "Never create a new Scheduler / Memory Manager / Event Bus / Runtime / Provider Layer / Queue / Execution Engine unless an ADR explicitly approves it"
• "Layers must only depend on the layer immediately below them"
• "Code must never reference specific AI models or vendors outside Provider implementation classes"
• "All inter-subsystem communication must occur via the Interconnect"

From ARCHITECTURE_GUARDIAN.md:

• 7 mandatory questions before any code is written
• "If the answer indicates duplication, violation of layer boundaries, or redundant subsystems: STOP. Redesign."

The Constitution was written and documents exist in the repository. The Architecture Guardian subsystem was built to enforce constraints programmatically at runtime. The Phase 28 violation report was generated by applying Constitution rules to the actual codebase.

The gap between the Constitution's intent and the actual codebase state (281 violations) suggests the Constitution was aspirational in Phase 28. Whether this represents the system "not yet conforming" or "never conforming" is not established.

• backend/docs/ — 14 Constitution documents (confirmed in directory listing)
• docs/01_ARCHITECTURE_PRINCIPLES.md — 7 principles text
• docs/05_ENGINEERING_RULES.md — 5 engineering laws text
• docs/10_ARCHITECTURE_GUARDIAN.md — 7 mandatory questions
• docs/09_DECISION_RECORDS.md — ADR template and 4 historical ADRs
• phase_28_x_2_violation_report.md — evidence of enforcement gap

Established: The Architecture Constitution exists as 14 documents. It defines layer rules, component ownership, forbidden patterns, and mandatory decision records. 4 ADRs were recorded.

Likely: The Constitution was written during or after the OS infrastructure phases (26-27) to formalize the architecture that had been built. The 281-violation report was generated against code that predated (or was developed in parallel with) the Constitution.

Unknown: Whether the Constitution was referenced during feature development or served primarily as retrospective documentation.

The Constitution documents appear stable. They describe the target architecture state, not the achieved state.

Writing an Architecture Constitution is valuable independent of its enforcement state. It forces explicit articulation of: what the system is, what it is not, what the rules are, and who owns what. Even if the codebase does not fully conform, the Constitution serves as the target state for any migration effort.

The 7-question pre-code checklist in ARCHITECTURE_GUARDIAN.md is the most actionable tool — if engineers actually answer those questions before writing code, many of the 281 violations would be prevented.

Architecture governance requires three layers: (1) documented principles (the Constitution), (2) automated enforcement (static analysis, CI gates), and (3) cultural adoption (engineers reading and applying the principles). Any single layer alone is insufficient for long-term architectural integrity.

• backend/docs/ (all 14 documents)
• docs/09_DECISION_RECORDS.md (ADR records)
• docs/10_ARCHITECTURE_GUARDIAN.md