Architecture decision records¶
This index lists the ADRs that document Loreley's design and implementation decisions. Use it when you need historical context for a subsystem, a configuration choice, or a behavior change that is already reflected in the code.
ADR numbers are unique and chronological. ADR 0029 resolves an earlier duplicate
0022 numbering conflict.
0001-0009¶
- ADR 0001: Incremental repo-state embeddings (diff-based)
- ADR 0002: Repo-state embeddings use canonical commit hashes only
- ADR 0003: Experiment config locking and dispatch (behavior params)
- ADR 0004:
.loreleyignorefor embedding scope - ADR 0005: Remove legacy MAP-Elites embedding flows
- ADR 0006: Auto-start UI API from Streamlit UI entrypoint
- ADR 0007: Vectorized occupied-cell neighbourhood sampling for MAP-Elites
- ADR 0008: Single scheduler per experiment (Postgres advisory lock)
- ADR 0009: Immutable file embedding cache (insert-only)
0010-0019¶
- ADR 0010: Incremental-only repo-state embeddings (after bootstrap)
- ADR 0011: Remove repo-state max-files cap; require interactive startup approval
- ADR 0012: Pin repo-state ignore rules
- ADR 0013: Remove filter_signature and prompt_signature from experiment-scoped caches
- ADR 0014: Experiment-scoped file embedding cache (remove pipeline_signature)
- ADR 0015: Experiment-attached workers and per-experiment task queues
- ADR 0016: Use Typer for the unified Loreley CLI
- ADR 0017: Use Tenacity for OpenAI retry/backoff
- ADR 0018: Remove legacy
script/wrappers - ADR 0019: Use pathspec for pinned gitignore matching
0020-0029¶
- ADR 0020: Split built-in agent backends and extract a shared agent runner
- ADR 0021: Centralize HTTP calls on httpx via an internal client module
- ADR 0022: Reuse UI API client connections via Streamlit resource cache
- ADR 0023: Lock experiment behavior keyset and settings injection
- ADR 0024: Env-only settings; remove experiment settings snapshot
- ADR 0025: Explicit experiment ID; remove derived config identity and legacy snapshots
- ADR 0026: Experiment ID as operational naming namespace
- ADR 0027: Single-tenant DB and instance metadata marker
- ADR 0028: Unify git commit availability and fail-fast best-fitness branch (branch semantics superseded by ADR 0052)
- ADR 0029: Use Pydantic
from_attributesfor UI API response schemas
0030-0039¶
- ADR 0030: DB-only repo-state embeddings and explicit bootstrap
- ADR 0031: Scheduler ingestion fail-soft and backoff
- ADR 0032: Simplify worker prompts; make freeform Markdown the default
- ADR 0033: Remove schema/validation modes; simplify agent outputs
- ADR 0034: Kilocode CLI agent backend
- ADR 0035: Default planning/coding backend is Kilocode
- ADR 0036: Single source of truth for worker commits
- ADR 0037: Sampler lightweight cell/commit sampling (superseded by ADR 0052)
- ADR 0038: Worker planning context batch DB loading
- ADR 0039: PCA epochs and archive rebuild on refit
0040-0049¶
- ADR 0040: Delay MAP-Elites archive until initial PCA fit
- ADR 0041: Split MAP-Elites manager modules
- ADR 0042: Sample ingest INFO logs and gate progress to TTY
- ADR 0043: Cache PCA history matrix for refits
- ADR 0044: Repo-state embeddings must embed all cache misses
- ADR 0045: Config profiles for large-repo campaigns
- ADR 0046: Agent-visible evaluation artifacts
- ADR 0047: Defer failed-candidate lineage semantics
- ADR 0048: Failed-candidate repair pool
- ADR 0049: Campaign program contract