ADR 0100: Project constitution¶

Status: Accepted
Date: 2026-04-26

ADR	Role
0006	related ADR
0009	related ADR
0027	related ADR
0036	related ADR
0079	related ADR
0097	related ADR
0099	related ADR
architecture-policy.md	outside numbered ADR

Summary¶

Project constitution: long-lived principles, invariants, governance.
Order of changes to “foundation”; hub with 0077.

For a short onboarding path in English, see concept overview.

1. Purpose¶

This constitution records Cascade IDE’s long-term principles so day-to-day decisions stay aligned across architecture, product direction, and contribution process.

It is a meta-level ADR: not a feature spec, but a stable agreement on how decisions are made.

2. Mission¶

Build a keyboard-first .NET IDE with a cockpit-style interface where human and agent scenarios share one reliable operational model.

Key goals:

transparent state and observability,
deterministic, testable architectural boundaries,
practical velocity for a small team,
open-source collaboration without losing product direction.

3. Constitutional principles¶

Single source of truth beats convenient duplication.
State projections must have one canonical source; derived views may cache but must not diverge in meaning.
Typed contracts beat ad-hoc glue.
Channels, CCU boundaries, and DataBus events must be explicit and testable.
UI is projection, not business-logic storage.
ViewModels orchestrate; computation and aggregation live in dedicated modules and services.
Strangler beats “big bang” rewrites.
Migration proceeds in vertical slices with guardrails and stepwise stabilization.
Human–agent parity is designed in.
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; evolving it should update that resource and cross-link here if needed, without bloating the constitution.
Open source first, compatible with commercialization.
Architecture and dependency policy must preserve open collaboration and future monetization options.

4. Non-negotiable guardrails¶

No hidden cross-layer bypasses around channel and CCU boundaries.
No untyped event payloads on the IDE domain bus.
No direct UI-framework coupling inside compute units.
No new dependencies without explicit license visibility.
No irreversible architectural shifts without an ADR update.

5. Governance¶

ADR-first for durable decisions.
Any change to boundaries, contracts, or operational principles is recorded in an ADR.
Analyzer and CI checks where feasible.
Repeated architectural violations move from guidance to build-time enforcement.
Living documents with explicit status.
Proposed → Accepted → Implemented cycle is required for project memory.

6. Contribution contract¶

Contributors are expected to:

preserve existing architectural invariants unless changed deliberately via ADR;
prefer additive, reviewable slices over broad unstructured edits;
add tests for changed contracts and boundary regressions.

Maintainers are expected to:

keep guardrails explicit and current;
propose migration paths, not only prohibitions;
align product evolution with these principles.

7. Amendment process¶

This constitution may change only through:

a dedicated amending ADR referencing this document;
explicit rationale for each changed principle and guardrail;
maintainer acceptance with an implementation plan where applicable.

8. Consequences¶

Positive¶

Stable long-term direction during fast iteration.
Less architectural drift in mixed human+agent development.
More predictable onboarding and review.

Negative¶

Extra discipline at the gate for foundation-touching changes.
Some experiments move slower until boundaries are explicit.