What M21 is trying to prove
A software project can be easier to understand and safer to change when its structure is captured in a small set of living artifacts:
Data models define meaning
Each concern owns enforceable domain concepts, fields, relationships, states, and structural constraints.
Interfaces define the surface
Semantic operations make inputs, outputs, failures, effects, and events explicit without choosing a language.
Specs describe intent
The architectural contract explains ownership, dependencies, non-goals, invariants, and decisions.
Features demonstrate behavior
Gherkin scenarios provide executable examples of interfaces and evidence-backed guarantees.
Dependencies are explicit
A module should not just depend on another module; it should say which capabilities it relies on.
Tests close the loop
Passing scenarios make the spec executable instead of aspirational.
Why this matters
Modern codebases often fail quietly. The code may still run, but the architecture becomes implicit, onboarding becomes oral tradition, tests drift from intent, and changes become risky because nobody can see the contracts between parts.
M21 aims to make those contracts durable. A maintainer should be able to identify each concern's owned data, semantic interfaces, promises, dependencies, tested behavior, risky relationships, and safe change boundaries.
Principles
Understandable by default
The primary audience is a human maintainer. Specs should be readable without knowing the implementation language or file layout.
Contracts over vibes
A graph edge is more valuable when it says why the relationship exists.
Living documentation
Models, interfaces, specs, features, test results, and the graph should reinforce each other instead of drifting apart.
Professional software hygiene
Clean boundaries, explicit responsibilities, reproducible tests, and visible risk help teams keep leverage over time.
The long-term direction
- Define each concern's enforceable data model.
- Define semantic interfaces over those models.
- Capture architectural intent and demonstrate behavior with executable scenarios.
- Validate references, export schemas, and visualize relationships and risks.
- Evolve model → interfaces → spec → features → implementation in order.
The experiment succeeds if M21 helps builders move faster without making the system harder to understand later.
Read the source version in VISION.md.