This directory captures architectural and design decisions using lightweight ADRs (Architecture Decision Records). Every time we make a non-obvious choice, we record the context, options considered, and reasoning.
Each decision is a numbered markdown file: NNNN-short-title.md
Template:
# NNNN: Title
**Date:** YYYY-MM-DD
**Status:** accepted | superseded by NNNN | deprecated
**Phase:** which milestone/phase prompted this
## Context
What situation are we in? What problem or question arose?
## Options
What alternatives did we consider?
## Decision
What did we choose and why?
## Consequences
What follows from this decision? Trade-offs accepted.
| # | Decision | Date | Status |
|---|---|---|---|
| 0000 | Why Intent exists | 2025-02-12 | accepted |
| 0001 | Rust as compilation target | 2025-02-12 | accepted |
| 0002 | Go toolchain for compiler | 2025-02-12 | accepted |
| 0003 | Runtime assertions over static proofs | 2025-02-12 | accepted |
| 0004 | Separate linter from checker | 2025-02-12 | accepted |
| 0005 | While loops before for loops | 2025-02-12 | accepted |
| 0006 | Print as built-in function | 2025-02-12 | accepted |
| 0007 | Arrays before enums | 2025-02-12 | accepted |
| 0008 | Intermediate representation | 2026-02-16 | accepted |
| 0009 | Multi-target code generation | 2026-02-16 | accepted |
| 0010 | Attractor as driving example | 2026-02-20 | accepted |
| 0011 | Conservative String cloning for Rust ownership | 2026-02-20 | accepted |
| 0012 | Method self-mutability analysis | 2026-02-20 | accepted |
| 0013 | String standard library | 2026-02-20 | accepted |
| 0014 | Remove legacy codegen package | 2026-02-20 | accepted |
| 0015 | Array<String> on entity fields | 2026-02-23 | accepted |
| 0016 | Map<K,V> type | 2026-02-23 | accepted |
| 0017 | Error handling patterns in Attractor examples | 2026-02-24 | accepted |
| 0018 | Trait system (static dispatch) | 2026-02-24 | accepted |
| 0019 | I/O standard library | 2026-02-27 | accepted |
| 0020 | HTTP, JSON, and event builtins | 2026-02-27 | accepted |
| 0021 | Phase 9 completion (lint rules, HandlerRegistry, Map key rejection, json_path) | 2026-03-20 | accepted |
| 0022 | Rust codegen mutability analysis | 2026-03-20 | accepted |
| 0023 | Closures and first-class functions | 2026-03-20 | accepted |
| 0024 | JavaScript multi-file codegen fix | 2026-03-20 | accepted |
| 0025 | User-defined generics design | 2026-03-20 | accepted |
| 0026 | Concurrency and async design | 2026-03-20 | accepted (revised in Phase 14) |
| 0027 | Package management design | 2026-03-20 | accepted; revised by ADR 0039 (MVS replaces constraint solver) |
| 0028 | Rust FFI / crate imports | 2026-05-28 | accepted |
| 0029 | In-language testing framework | 2026-05-29 | accepted |
| 0030 | Cross-package test visibility | 2026-05-30 | accepted |
| 0031 | @target_specific annotation for tests |
2026-05-30 | accepted; implemented in 4dacd6c |
| 0032 | LSP v1 surface | 2026-05-30 | accepted; revised five times (Phase 19, Phase 20, Phase 21, Phase 25, Phase 26); see ADR for commit ranges |
| 0033 | --strip-contracts flag and contract strip policy |
2026-05-31 | accepted; revised same day (dropped redundant --release flag); PRD pending |
| 0034 | Per-contract source positions in verify results | 2026-05-31 | accepted (PRD pending) |
| 0035 | LSP textDocument/references scope and semantics | 2026-05-31 | accepted (PRD pending) |
| 0036 | Entity and method auto-test emission for --target intent |
2026-05-31 | accepted (PRD pending) |
| 0037 | Multi-param iteration in --target intent test generation |
2026-06-01 | accepted (PRD pending) |
| 0038 | Retire the legacy Rust testgen path |
2026-06-02 | accepted |
| 0039 | Package registry — git-based + MVS | 2026-06-03 | accepted (PRD pending) |
| 0040 | Self-hosted formatter strategy | 2026-06-03 | accepted (strategic; per-phase ADRs follow) |
| 0041 | String indexing and Char type |
2026-06-03 | accepted (Phase 31 shipped 2026-06-03) |