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.

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.

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)

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)

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)

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)

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)

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
• 0066-0067 — unused (intentional gaps)

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)

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)

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)

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
• ADR-0095 — Run-terminal callbacks and orphan recovery (supersedes ADR-0060)
• ADR-0088 — Plugin system (directory-bundle manifest with lazy activation; number from the adjacent free gap — the substrates block is exhausted)

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.