title: Recorded design decisions
description: Every architecture decision record in the repository, with the status each file carries, generated at build time.
url: https://legalquants.github.io/lq-ai/reference/adr-index/
checked-against: 671eab0d (2026-10-25)
status: draft
kind: explanation
sources: docs/site/reference/adr-index.intro.md, docs/adr

Every architecture decision record in `docs/adr/`, with the status each file
carries today. The table below is read from the directory at build time, not
hand-maintained, so it can't fall behind whatever files actually exist there.

**An accepted record describes an agreed direction — not necessarily what's
built yet.** Read a decision alongside the actual code and tests to see
which parts of it are available now; "Accepted" means the project has
committed to that direction, not that every part of it has shipped.

**A status can lag behind the code, and this index doesn't correct for
that.** The Status column is rendered exactly as the file states it,
including a record that still reads "Proposed" on a decision everyone
already treats as settled, or that mentions work as deferred after the
deferred part has since landed. When the status word and what you observe
in the running system disagree, the code is the more current answer; a
stale status is worth fixing in the ADR file itself, not worked around here.

<!-- table: records key=2 -->
| ADR | Decision | Status | Note |
|---|---|---|---|
| 0001 | [OpenWebUI fork pin and refresh strategy](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0001-openwebui-fork-pin.md) | Accepted | (2026-05-07) |
| 0002 | [Backend (FastAPI) owns authentication](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0002-backend-owned-auth.md) | Accepted | (2026-05-07) |
| 0003 | [Error handling: parallel `lq_ai.errors` packages with an OpenAPI-defined contract](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0003-error-handling.md) | Accepted | (2026-05-08) |
| 0004 | [Skill loader lives in the backend (`api/`), not the gateway](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0004-skill-loader-locus.md) | Accepted | (2026-05-08); extended by [ADR 0012 — DB-backed user skills](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0012-db-backed-user-skills.md) (2026-05-10) for the user/team-scope shadow layer |
| 0005 | [File-storage soft-delete and MinIO key scheme](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0005-file-storage-soft-delete-and-key-scheme.md) | Accepted |  |
| 0006 | [Document pipeline architecture](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0006-document-pipeline-architecture.md) | Accepted |  |
| 0007 | [Skill prompt assembly: gateway↔backend auth, templating, and request surface](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0007-skill-prompt-assembly.md) | Accepted | (2026-05-08) |
| 0008 | [Embedding model selection and OpenAI provider adapter](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0008-embedding-model-and-openai-adapter.md) | Accepted | (2026-05-08) |
| 0009 | [LQ.AI web shell co-exists alongside the OpenWebUI shell (does not replace it)](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0009-web-lq-ai-shell-coexistence.md) | Accepted | (2026-05-08) |
| 0010 | [Gateway config hot-reload + admin write API](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0010-gateway-config-hot-reload.md) | Accepted |  |
| 0011 | [Transparency-first model selection posture](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0011-transparency-first-model-selection.md) | Accepted |  |
| 0012 | [DB-backed user skills (amends ADR 0004)](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0012-db-backed-user-skills.md) | Accepted | (2026-05-10) |
| 0013 | [Autonomous Layer design influences (M4 / LQVern)](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0013-autonomous-layer-design-influences.md) | Proposed |  |
| 0014 | [Gateway egress boundary for tool / data-source providers](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0014-gateway-egress-boundary-for-tool-providers.md) | Accepted | (2026-06-19) |
| 0015 | [Governed tool-calling model (closed-intent posture extended, not abandoned)](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0015-governed-tool-calling-model.md) | Accepted | (2026-06-19) |
| 0016 | [Transparency and governance invariants (the engineering posture, made enforceable)](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0016-transparency-and-governance-invariants.md) | Proposed |  |
| 0017 | [DOCX ingest via Pandoc (canonical text) with an OOXML comment fallback](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0017-docx-ingest-via-pandoc.md) | Accepted | (2026-06-23) — maintainer approved the Pandoc dependency and the redline policy; implementation lands in a separate build PR per the [mini-PRD](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/contribute/mini-prds/docx-ingest-support.md). |
| 0018 | [The Citation Ledger & fiduciary-grade output](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0018-citation-ledger-and-fiduciary-grade-output.md) | Accepted | (2026-06-24) — maintainer-accepted; Phase 1 implementation PRs (P1-A1+) carry security review per CODEOWNERS (new content store derived from egress; citation/audit surface) |
| 0019 | [Transparent validity/treatment layer (WS-G)](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0019-transparent-validity-treatment-layer.md) | Accepted | (2026-06-26) — maintainer-accepted. Implementation PRs (WS-G PR1+) carry **security review** per CODEOWNERS (new gateway egress operation; citation/audit surface). |
| 0020 | [Governed agentic legal-matter sessions (WS-D)](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0020-governed-agentic-legal-matter-sessions.md) | Accepted | (2026-06-28) — maintainer-accepted. Implementation PRs (WS-D PR1+) carry **security review** per CODEOWNERS (the autonomous governance chokepoint; the citation/audit/ledger surface in PR2). |
| 0021 | [Content-source registry & free-source expansion (WS-E)](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0021-content-source-registry-and-free-source-expansion.md) | Accepted | (2026-06-29) — maintainer-accepted (PR #241; the four design forks settled with the maintainer 2026-06-29). Implementation PRs (WS-E PR1+) carry **security review** per CODEOWNERS (the `gateway/**` egress boundary, the `api/app/autonomous/**` governance chokepoint, and a new external-egress surface). |
| 0022 | [Committee governance document and public meeting records](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0022-committee-governance-and-meeting-records.md) | Accepted | (2026-07-26) — committee-accepted at the weekly call |
| 0023 | [uv-managed lockfiles for gateway/ and api/](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0023-uv-lockfiles-gateway-api.md) | Accepted | (2026-07-27) |
| 0024 | [Routing expansion contributions (new jurisdictions and practice areas)](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0024-jurisdiction-and-practice-area-expansion.md) | Accepted | (2026-08-09) — committee-accepted at the weekly call. |
| 0025 | [Release versioning policy and release-pipeline ordering](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0025-release-versioning-and-pipeline-ordering.md) | Accepted | (2026-08-09) — committee-accepted at the weekly call. |
| 0026 | [Document-ingestion parsing: remove the dead Docling integration; defer pluggable ingestion (DE-387)](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0026-document-ingestion-parser-and-docling.md) | Accepted | (2026-08-23) — committee-accepted at the weekly call |
| 0027 | [Request budgets and timeouts: sane defaults, per-request tuning, operator escape hatches](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0027-request-budgets-and-timeouts.md) | Accepted | (2026-09-20) — committee-ratified at the weekly call |
| 0028 | [Documentation-site generator and hosting: Astro Starlight on GitHub Pages](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0028-documentation-site-generator-and-hosting.md) | Accepted | (2026-09-20) — committee-ratified at the weekly call |
| 0029 | [Definition of 1.0](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0029-definition-of-1.0.md) | Accepted | (2026-10-04) — committee-ratified at the weekly call (drafted |
| 0030 | [Pacing 1.0: date preconditions, the January checkpoint, and named trains](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0030-pacing-1.0-preconditions-and-named-trains.md) | Accepted | (2026-10-04) — committee-ratified at the weekly call. The milestone |
| 0031 | [Headless / API-only use: acknowledged, not supported](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0031-headless-api-only-use.md) | Accepted | (2026-10-04) — committee-ratified at the weekly call |
| 0032 | [The Word add-in 1.0 slice: scope, the DE-287 collision, and document-representation sequencing](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0032-word-add-in-1.0-slice.md) | Accepted | (2026-10-04) — committee-ratified at the weekly call |
| 0033 | [Document-pipeline honesty, the OCR un-deferral, and a local embedding path](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0033-document-pipeline-honesty-and-ocr.md) | Accepted | (2026-10-04) — committee-ratified at the weekly call |
| 0034 | [Review capacity: the trusted-reviewer rung, maintainer promotion, the attorney pool, and an honest review SLA](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0034-review-capacity-and-reviewer-roles.md) | Accepted | (2026-10-04) — committee-ratified at the weekly call. Decision 5 was |
| 0035 | [Governed orchestration on the autonomous executor](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0035-governed-orchestration-run-tree.md) | Accepted | (2026-09-20) — committee-ratified at the weekly call. |
| 0036 | [Bundled object store: replace archived MinIO with RustFS; keep the api S3-generic](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0036-bundled-object-store-rustfs.md) | Accepted | (2026-09-20) — committee-ratified at the weekly call |
| 0037 | [Deployment migrations: a journal for stack state, first used by the object-store swap](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0037-deployment-migrations-framework.md) | Accepted | (2026-09-20) — committee-ratified alongside ADR 0036 |
| 0038 | [Governed runs in chat: an orchestrator model](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0038-governed-runs-in-chat.md) | Proposed | (2026-09-23; rewritten 2026-10-06; rewritten again 2026-10-09, after |
| 0040 | [Tabular bulk operations (redline report + column memo)](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0040-tabular-bulk-operations.md) | Accepted | (2026-10-04) — approved at the committee meeting with the maintainer's review amendments. Hou Fu confirmed the approval and inclusion of those amendments on 2026-10-10. Implementation acceptance and security review remain separate from this architectural approval. |
| 0041 | [Community skill catalog served from the local submodule](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0041-community-skill-catalog-source.md) | Proposed | (2026-07-25) — authored in-PR with roadmap item 3.8 (DE-263, community skill installer admin UI); reviewable at PR time. New admin endpoints carry **security review** per the auth-touching-surface rule in CLAUDE.md / CODEOWNERS. |
| 0042 | [Matter access and central policy administration](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0042-matter-scoped-access-control.md) | Proposed | — maintainer-authorised replacement implementation for PR #536; |
| 0043 | [`lq` design-system primitives for the LQ.AI shell](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0043-lq-design-system-primitives.md) | Accepted | (2026-10-18) |
| 0044 | [Workspace events, Today View, and read-only email triage](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/adr/0044-workspace-events-today-email.md) | Accepted | (2026-10-18) — committee adoption of the ADR text and staged scope. |

Each row links the ADR file at the commit this page was checked against, so the status you read here is the status that file carried at that commit. Statuses are rendered exactly as the file states them — an ADR that says "Proposed" is listed as Proposed even where the decision is being followed, because the file is the record.

## Next

- [Reference](/lq-ai/reference/) — the rest of the generated material.
- [Release versioning](/lq-ai/reference/versioning/) — ADR 0025 in full.
- [Governance](/lq-ai/trust/governance/) — who decides, and how a decision is recorded.