Architecture Decision Records¶

This directory is the canonical ADR corpus for lionagi. It replaces the earlier corpus now preserved at docs/_archive/v0/ (moved there intact, original filenames kept). Every archived record has an explicit disposition — carried forward into a new ADR, merged into one, or retired — recorded in dispositions.yaml in this directory (one row per archived record).

Each ADR follows TEMPLATE.md and is exactly one of two kinds:

• Retrospective — records what the code does today, honestly, including a current-vs-ideal delta table whose rows are phrased to lift directly into issues.
• Aspirational — records a target state that is decided but not yet implemented.

A gap between a retrospective truth and an aspirational target is an issue, never a blurred document.

Kind describes what the document is and never changes as code lands. How much of a decided target has actually shipped is recorded in the separate, mutable Implementation-status header field (see TEMPLATE.md), updated as implementation progresses without a formal amendment.

Status lifecycle¶

An ADR is authored Proposed. The flip to Accepted has an owner and a trigger: the PR that merges the ADR's first dependent implementation also flips its status, and whoever merges that PR owns the flip. When an implementation has already merged while the record still reads Proposed, the correction is an immediate docs follow-up, not a debt to accumulate. Decisions inside one ADR are separable: where only some decision clauses have shipped or one clause is blocked on an external dependency, the status line says so per-clause and Implementation-status names what landed and what remains.

Architecture-quality figures (κ and τ)¶

Several ADRs report two figures in their Consequences sections. κ is a coupling density: directed dependencies divided by n × (n − 1) over the components that ADR's own design diagram names, where a component is a named box and an edge is a direct dependency drawn in that diagram. τ is an estimated fraction of components testable in isolation through their declared seams. Both are the author's structural reading of the recorded design: arithmetically consistent within each ADR, not independently re-derived from source, and not comparable across ADRs whose component maps differ in granularity. Read them as review aids for the specific component map shown, not as corpus-wide measurements.

Numbering¶

Numbers are allocated in per-area blocks so areas can be authored independently without collisions. Unused numbers inside a block are intentional gaps, not missing documents.

ADR-0094 and ADR-0095 are documented numbering exceptions: both retain numbers from the substrates block (0090-0095) despite declaring scheduling-control-plane as their area. They landed in that range before the area mismatch was identified; retaining the numbers avoids collisions with other ADR work and preserves existing inbound references.

ADR-0104 is a documented numbering exception for the same reason: it declares cli-surface but carries a number far outside that block (0062-0067), which was allocated before the per-area scheme was applied to it. It is indexed under cli-surface and keeps its number, so inbound references stay valid.

Numbers 0096-0103 belong to no area block and are reserved but unused: they fall between the end of the block regime (0095) and the start of the sequential regime (0104), and no document will be created to fill them.

From ADR-0104 onward, numbers are in practice allocated sequentially rather than from the area block, and each such record is indexed under the area it declares. This is a description of what the corpus does, not a second scheme competing with the blocks: the blocks still hold for 0001-0095, and every number is unique either way. A record numbered past 0104 carries a "sequential number" note in the index so a reader is not left to reconcile its number against its area block.

Index¶

core-data-model (0001-0005)¶

• ADR-0001 — Element identity and polymorphic serialization envelope
• ADR-0002 — UUID-keyed ordered collection model
• ADR-0003 — In-process Event execution lifecycle
• ADR-0004 — Directed graph structural invariants
• 0005 — unused (intentional gap)

messages-context (0006-0010)¶

• ADR-0006 — Conversational message envelope and ordered history
• ADR-0007 — Canonical turn-request compilation boundary
• ADR-0008 — Pre-turn context- provider execution and attribution
• 0009-0010 — unused (intentional gaps)

actions-tools (0011-0015)¶

• ADR-0011 — Function tool descriptor and Branch registry
• ADR-0012 — Branch action execution and event lifecycle
• ADR-0013 — Built-in tool provider and Branch binding
• 0014-0015 — unused (intentional gaps)
• ADR-0112 — MCP tool registration naming and collision behavior (sequential number; see Numbering)
• ADR-0121 — Authoritative action execution and native agent harness (sequential number; see Numbering)

session-branch (0016-0020)¶

• ADR-0016 — Branch conversation aggregate and attachment boundary
• ADR-0017 — Session membership and coordination boundary
• ADR-0018 — Turn-scoped Branch execution state
• 0019-0020 — unused (intentional gaps)

operations (0021-0026)¶

• ADR-0021 — Branch operation facade and turn-adapter contract
• ADR-0022 — Composed branch operation pipeline
• ADR-0023 — Dependency-aware operation-graph execution kernel
• ADR-0024 — LNDL operate integration adapter
• 0025-0026 — unused (intentional gaps)

service-providers (0027-0032)¶

• ADR-0027 — Model-service facade and endpoint resolution
• ADR-0028 — Validated provider-adapter catalog
• ADR-0029 — Unified request admission, deadline, and resilience policy
• ADR-0030 — Agentic provider-adapter boundary
• 0031-0032 — unused (intentional gaps)

orchestration (0033-0040)¶

• ADR-0033 — Operation-graph orchestration boundary
• ADR-0034 — Domain-engine coordination and autonomy safeguards
• ADR-0035 — Persisted run-completion contract
• ADR-0036 — Casts role palettes as playstyle
• ADR-0037 — Resident engine host and task queue
• ADR-0038 — Escalation tier routing
• 0039-0040 — unused (intentional gaps)
• ADR-0110 — Deterministic manifest fan-out — legs from briefs, no planner (sequential number; see Numbering)
• ADR-0111 — A run records the code it was reasoning about, and can refuse to start (sequential number; see Numbering)
• ADR-0123 — Canonical Run identity and execution projections (sequential number; see Numbering)
• ADR-0124 — Invocation terminal callback cutover (sequential number; see Numbering)

agent-roles (0041-0046)¶

• ADR-0041 — Agent specification and Branch construction boundary
• ADR-0042 — Casts pattern catalog and typed role authoring
• ADR-0043 — Per-role configuration resolution
• ADR-0044 — Agent prompt directives and executable permissions
• 0045-0046 — unused (intentional gaps)

hooks (0047-0049)¶

• ADR-0047 — Hook mechanism scopes and canonical ownership
• ADR-0048 — Interoperable external hooks (Claude Code / Codex hook contract)
• 0049 — unused (intentional gap)
• ADR-0120 — Interception, observation, and durable delivery planes (sequential number; see Numbering)

utilities (0050-0054)¶

• ADR-0050 — Foundational utility and typed adaptation strata
• ADR-0051 — LNDL language and operations boundary
• ADR-0052 — Supported validation and testing surfaces
• 0053-0054 — unused (intentional gaps)
• ADR-0119 — Deterministic declaration and configuration substrate (sequential number; see Numbering)

persistence-state (0055-0061)¶

• ADR-0055 — Operational state persistence boundary
• ADR-0056 — StateDB SQLAlchemy Core backend
• ADR-0057 — Operational lifecycle and transition audit
• ADR-0058 — Unified lifecycle transition service
• ADR-0059 — Durable dispatch outbox
• ADR-0060 — Run supervision: generic terminal callback and two-stage orphan detection (superseded by ADR-0095)
• 0061 — unused (intentional gap)
• ADR-0105 — Resumed session lifecycle and terminal notification (sequential number; see Numbering)
• ADR-0109 — A mirrored session's idleness is not its completion (sequential number; see Numbering)
• ADR-0117 — Normalized progression membership and online cutover (sequential number; see Numbering)
• ADR-0118 — Declared entity schema as the single authority for state and studio persistence (sequential number; see Numbering)

cli-surface (0062-0067)¶

• ADR-0062 — CLI command-surface ownership
• ADR-0063 — Project attribution cascade
• ADR-0064 — CLI execution outcome and completion record
• ADR-0065 — Marketplace catalog and directory discovery
• ADR-0066 — li mcp v2 verb surface (discrete core plus one parser-generated dispatch verb)
• 0067 — unused (intentional gap)
• ADR-0104 — li kill reaping of detached-play workers and terminal-notify on kill (sequential number; see Numbering)
• ADR-0106 — The lion machine-result contract, v1 (sequential number; see Numbering)
• ADR-0107 — Conclusive orphan terminal reaping (sequential number; see Numbering)

scheduling-control-plane (0068-0075)¶

• ADR-0068 — Three public orchestration lanes
• ADR-0069 — Reactive flow steering and recovery
• ADR-0070 — Studio scheduling and dispatch delivery
• ADR-0071 — Durable ad-hoc task queue
• ADR-0072 — Unified task admission and lifecycle
• ADR-0073 — Fixed workflow-definition execution
• 0074-0075 — unused (intentional gaps)
• ADR-0108 — Agent-run steering at the turn-end boundary (sequential number; see Numbering)

studio (0076-0085)¶

• ADR-0076 — Studio daemon route registry and local control plane
• ADR-0077 — Studio state and filesystem boundary
• ADR-0078 — Studio application-service boundary
• ADR-0079 — Studio web client architecture and deployment
• ADR-0080 — Studio six-space cockpit information architecture
• ADR-0081 — Studio execution and artifact workspace target
• ADR-0082 — VS Code Studio observability client
• ADR-0083 — Studio operator-command protocol
• 0084-0085 — unused (intentional gaps)
• ADR-0113 — The execution graph as the primary run canvas (sequential number; see Numbering)
• ADR-0116 — Editor client capability expansion; revises ADR-0082 D2 (sequential number; see Numbering)

governance (0086-0089)¶

• ADR-0086 — Local tool controls and session authorization observation
• ADR-0087 — Evidence-backed governed execution
• 0088-0089 — unused (0088 allocated to a substrates record from this gap; see below)
• ADR-0122 — Feature boundaries and optional runtime profiles (sequential number; see Numbering)

substrates (0090-0095)¶

• ADR-0090 — Local sandbox and measured-cell backend seams
• ADR-0091 — Per-worker worktree execution isolation
• ADR-0092 — Minimal Branch and session memory store
• ADR-0093 — External memory adapter fidelity contract
• ADR-0094 — Automated PR-review pipeline over github-poll schedules (area: scheduling-control-plane; numbering exception)
• ADR-0095 — Run-terminal callbacks and orphan recovery (area: scheduling-control-plane; numbering exception; supersedes ADR-0060)
• ADR-0088 — Plugin system (directory-bundle manifest with lazy activation; number from the adjacent free gap — the substrates block is exhausted)

cli-orchestration (sequential numbers only)¶

Ratified 2026-08-11 as the seventeenth area: the CLI orchestration surface — li o flow / li o fanout, playbooks and flow definitions, orchestration guidance packs. It postdates the block regime, so it holds no number block; its records carry sequential numbers (≥0104).

• ADR-0114 — An executable flow definition, and roles whose declared capabilities are real (sequential number; see Numbering)
• ADR-0115 — Orchestration guidance as an enforced pack (sequential number; see Numbering)

Remaining areas land here as their records are accepted.

Status-set literals quoted in these records (terminal sets, valid-status vocabularies) are checked against the lifecycle policy registry in CI (scripts/check_adr_status_sets.py); a registry change that stale-ifies a quoted set fails the docs job.