Architecture Decision Records

This section contains Architecture Decision Records (ADRs) for the Stemix / IDP project.

This content is also available in the GitHub repository.

Format

All decision records use the Markdown Any Decision Records (MADR) format.

Naming Convention

Files follow the pattern NNNN-title-with-dashes.md:

• NNNN: Zero-padded 4-digit sequence number
• title-with-dashes: Lowercase, dash-separated descriptive title

Process

1. Copy the template to a new file with the next sequence number.
2. Fill in all sections. Set status to proposed.
3. Submit a PR referencing the relevant GitHub Issue.
4. After review and approval, update status to accepted.

Decision Intake Framework

Record a decision as an ADR only when it is long-lived, cross-cutting, and expensive to reverse.

Use these gates:

1. Cross-cutting scope: impacts multiple services, stacks, teams, or workflows.
2. Reversal cost: changing later requires broad migration, compatibility updates, or automation changes.
3. Contract surface: defines a boundary or contract (architecture, interfaces, runtime conventions, workflow/governance semantics, security baseline).
4. Longevity: expected to remain valid for multiple quarters.
5. Drift risk: likely to diverge if not codified in one canonical place.

Routing rule: Create an ADR when at least 3 gates are true and one is Gate 2 or Gate 3.

Audience views

• IDP Platform Decisions — user-facing contracts, platform behavior, and cross-stack conformance expectations.
• Internal Engineering Decisions — repository build/orchestration/tooling constraints for maintainers and contributors.

Index

ADR	Title	Status	Date
0001	Intent-Driven Architecture	proposed	2026-03-30
0002	Stack Layout and Make Contract	proposed	2026-03-30
0003	Contract Harness and Runtime Port Contract	proposed	2026-03-30
0004	Implementation Portfolio and Support Tiers	proposed	2026-03-30
0005	Shared Capability Contract and Conformance Profiles	proposed	2026-03-30
0006	Cross-Platform Local Runtime UX Baseline	proposed	2026-03-30
0007	Moon-Required Orchestration and Proto-Enhanced Toolchain Policy	proposed	2026-03-30
0008	Dependency and Tooling Pinning Policy	proposed	2026-03-31
0009	Gherkin as Layer 1 Intent Specification Format	proposed	2026-03-31
0010	Container Build Strategy	proposed	2026-03-31
0011	IETF Health Endpoint Contract	proposed	2026-04-01
0012	Moon Python/uv Toolchain Integration Constraint	accepted	2026-04-01
0013	Optional OAuth Plug-In Architecture	proposed	2026-04-07
0014	MVP Flow Observation Technical Foundations	proposed	2026-04-12
0015	spec-kit Three-Axis Evaluation	proposed	2026-04-22