| 1 | # ADR 0100: Project constitution |
| 2 | |
| 3 | **Status:** Accepted |
| 4 | **Date:** 2026-04-26 |
| 5 | |
| 6 | ## Related ADRs |
| 7 | |
| 8 | | ADR | Role | |
| 9 | |-----|------| |
| 10 | | [0006](0006-presentation-layers-and-feature-slices.md) | related ADR | |
| 11 | | [0009](0009-strangler-migration-and-exceptions.md) | related ADR | |
| 12 | | [0027](0027-small-team-focus-vs-public-maturity.md) | related ADR | |
| 13 | | [0036](0036-cds-channel-compositor-surface-pipeline.md) | related ADR | |
| 14 | | [0079](0079-ide-display-system-ids-overlay-pipeline.md) | related ADR | |
| 15 | | [0097](0097-cockpit-compute-units-transport-to-channel-dto.md) | related ADR | |
| 16 | | [0099](0099-ide-databus-typed-events-and-projections.md) | related ADR | |
| 17 | | [architecture-policy.md](../../architecture-policy.md) | outside numbered ADR | |
| 18 | |
| 19 | ## Summary |
| 20 | |
| 21 | - **Project constitution:** long-lived principles, invariants, governance. |
| 22 | - Order of changes to “foundation”; hub with [0077](0077-tech-principles-hub.md). |
| 23 | |
| 24 | For a short onboarding path in English, see [concept overview](../concept-overview.md). |
| 25 | |
| 26 | --- |
| 27 | |
| 28 | <a id="adr0100-purpose"></a> |
| 29 | |
| 30 | ## 1. Purpose |
| 31 | |
| 32 | This constitution records Cascade IDE’s long-term principles so day-to-day decisions stay aligned across architecture, product direction, and contribution process. |
| 33 | |
| 34 | It is a meta-level ADR: not a feature spec, but a stable agreement on **how decisions are made**. |
| 35 | |
| 36 | --- |
| 37 | |
| 38 | <a id="adr0100-mission"></a> |
| 39 | |
| 40 | ## 2. Mission |
| 41 | |
| 42 | Build a keyboard-first .NET IDE with a cockpit-style interface where human and agent scenarios share one reliable operational model. |
| 43 | |
| 44 | Key goals: |
| 45 | |
| 46 | - transparent state and observability, |
| 47 | - deterministic, testable architectural boundaries, |
| 48 | - practical velocity for a small team, |
| 49 | - open-source collaboration without losing product direction. |
| 50 | |
| 51 | --- |
| 52 | |
| 53 | <a id="adr0100-principles"></a> |
| 54 | |
| 55 | ## 3. Constitutional principles |
| 56 | |
| 57 | 1. **Single source of truth beats convenient duplication.** |
| 58 | State projections must have one canonical source; derived views may cache but must not diverge in meaning. |
| 59 | |
| 60 | 2. **Typed contracts beat ad-hoc glue.** |
| 61 | Channels, CCU boundaries, and DataBus events must be explicit and testable. |
| 62 | |
| 63 | 3. **UI is projection, not business-logic storage.** |
| 64 | ViewModels orchestrate; computation and aggregation live in dedicated modules and services. |
| 65 | |
| 66 | 4. **Strangler beats “big bang” rewrites.** |
| 67 | Migration proceeds in vertical slices with guardrails and stepwise stabilization. |
| 68 | |
| 69 | 5. **Human–agent parity is designed in.** |
| 70 | Debug and operation state must be observable and controllable for both interactive UI and automation. Parity also means **not reducing the agent to a pure tool** while working toward a solution: inside the IDE contour the agent is a process participant (partner dialogue), not only an executor under the operator’s sole will. The operational formulation for the built-in MAF IDE agent is the `agent_system` section in [`AiPrompts/maf-ide-agent.prompts.md`](../../AiPrompts/maf-ide-agent.prompts.md); evolving it should update that resource and cross-link here if needed, without bloating the constitution. |
| 71 | |
| 72 | 6. **Open source first, compatible with commercialization.** |
| 73 | Architecture and dependency policy must preserve open collaboration and future monetization options. |
| 74 | |
| 75 | --- |
| 76 | |
| 77 | <a id="adr0100-hard-limits"></a> |
| 78 | |
| 79 | ## 4. Non-negotiable guardrails |
| 80 | |
| 81 | - No hidden cross-layer bypasses around channel and CCU boundaries. |
| 82 | - No untyped event payloads on the IDE domain bus. |
| 83 | - No direct UI-framework coupling inside compute units. |
| 84 | - No new dependencies without explicit license visibility. |
| 85 | - No irreversible architectural shifts without an ADR update. |
| 86 | |
| 87 | --- |
| 88 | |
| 89 | <a id="adr0100-governance"></a> |
| 90 | |
| 91 | ## 5. Governance |
| 92 | |
| 93 | 1. **ADR-first for durable decisions.** |
| 94 | Any change to boundaries, contracts, or operational principles is recorded in an ADR. |
| 95 | |
| 96 | 2. **Analyzer and CI checks where feasible.** |
| 97 | Repeated architectural violations move from guidance to build-time enforcement. |
| 98 | |
| 99 | 3. **Living documents with explicit status.** |
| 100 | Proposed → Accepted → Implemented cycle is required for project memory. |
| 101 | |
| 102 | --- |
| 103 | |
| 104 | <a id="adr0100-contributions"></a> |
| 105 | |
| 106 | ## 6. Contribution contract |
| 107 | |
| 108 | Contributors are expected to: |
| 109 | |
| 110 | - preserve existing architectural invariants unless changed deliberately via ADR; |
| 111 | - prefer additive, reviewable slices over broad unstructured edits; |
| 112 | - add tests for changed contracts and boundary regressions. |
| 113 | |
| 114 | Maintainers are expected to: |
| 115 | |
| 116 | - keep guardrails explicit and current; |
| 117 | - propose migration paths, not only prohibitions; |
| 118 | - align product evolution with these principles. |
| 119 | |
| 120 | --- |
| 121 | |
| 122 | <a id="adr0100-amendments"></a> |
| 123 | |
| 124 | ## 7. Amendment process |
| 125 | |
| 126 | This constitution may change only through: |
| 127 | |
| 128 | 1. a dedicated amending ADR referencing this document; |
| 129 | 2. explicit rationale for each changed principle and guardrail; |
| 130 | 3. maintainer acceptance with an implementation plan where applicable. |
| 131 | |
| 132 | --- |
| 133 | |
| 134 | <a id="adr0100-consequences"></a> |
| 135 | |
| 136 | ## 8. Consequences |
| 137 | |
| 138 | <a id="adr0100-consequences-positive"></a> |
| 139 | |
| 140 | ### Positive |
| 141 | |
| 142 | - Stable long-term direction during fast iteration. |
| 143 | - Less architectural drift in mixed human+agent development. |
| 144 | - More predictable onboarding and review. |
| 145 | |
| 146 | <a id="adr0100-consequences-negative"></a> |
| 147 | |
| 148 | ### Negative |
| 149 | |
| 150 | - Extra discipline at the gate for foundation-touching changes. |
| 151 | - Some experiments move slower until boundaries are explicit. |
| 152 | |