---
title: "Architecture Decision Records (ADRs)"
---
import RepoFile from '../../../../components/RepoFile.astro'

**Status**: Open — Phase 1, no confirmation needed (requires Developer Reference setup first)

## Problem

No ADR directory exists. Design context lives only in PR descriptions (not committed) and tool-specific spec files (not browsable). Three foundational decisions need documentation so future contributors (human and AI) understand why the current architecture exists.

## Three priority ADRs

**ADR-001: Single-crate vs workspace**
`docs/src/content/docs/internal/decisions/001-single-crate.mdx`
Decision: stay single-crate while LOC < 150K and no external library consumers. Evidence: starship and fd-find stay single-crate at similar/larger scale. Trigger for workspace: LOC > 150K, or `jackin-core` types needed by external tooling.

**ADR-002: Rust 1.95.0 toolchain + 1.94 MSRV**
`docs/src/content/docs/internal/decisions/002-toolchain.mdx`
Decision: pin to 1.95.0 in mise.toml and CI; declare 1.94 as MSRV in Cargo.toml. Documents the `dtolnay/rust-toolchain` SHA encoding convention and `edition = "2024"` floor (≥ 1.85).

**ADR-003: ratatui selection**
`docs/src/content/docs/internal/decisions/003-ratatui.mdx`
Decision: use ratatui for all TUI rendering. Documents the tui-rs → ratatui fork history, why ratatui is the correct successor (actively maintained, tui-rs abandoned), and the version currently in use.

## ADR frontmatter format

```yaml
---
title: "ADR-NNN: Title"
status: accepted   # proposed | accepted | superseded | deprecated
date: YYYY-MM-DD
---
```

## Steps

1. Ensure Developer Reference setup is done (directory exists).
2. Create the three ADR MDX files with Context, Decision, and Consequences sections.
3. Keep each ADR to 1–2 pages — decisions, not dissertations.
