v0.4.0 — M4 release: the Autonomous Layer (opt-in)

v0.4.0 — M4 release: the Autonomous Layer (opt-in), platform operability, and a docs/Learn honesty sweep

Status: DRAFT for the v0.4.0 tag. Attorney legal-substance walk-through cleared (gate 1).
Branch ↔ main reconciliation is done (merge d336c66; origin/main is now an ancestor)
and api + gateway __version__ are bumped to 0.4.0. All post-merge gates pass. What
remains is the merge to main + the annotated v0.4.0 tag — see "Release readiness" below.

Milestone 4 turns LQ.AI from an assistant you drive into one that can also run on its own — but
only when you opt in, and only inside hard brakes. The layer is off by default; nothing runs
autonomously until an operator turns it on per-user in Settings. Every autonomous run is bounded by
a cost cap, an external halt + idle watchdog, and per-phase tool limits, and emits an inspectable
receipt. This release also ships the operability surfaces that make the layer discoverable and
self-explanatory, and a thorough reconciliation of the docs and Learn content to what the code
actually does.

---

Headline — the Autonomous Layer (M4)

A new Autonomous area (opt-in, off by default; enabled per-user in Settings → Autonomous).

What it runs

• Schedules — a chosen skill or playbook on a cron cadence, optionally scoped to a knowledge
  base and/or matter, with a per-run cost cap.
• Watches — a run triggered when a document is attached to a chosen knowledge base.
• Run now — a one-off, on-demand run of a skill/playbook so you can see the result (and its
  receipt) before arming a schedule or watch.

How it runs — a LangGraph phase machine (intake → analysis → drafting → ethics review →
delivery) that performs real in-loop agentic work through the same guarded chokepoint as the rest
of the platform: every tool call (retrieve / run-skill / run-playbook) passes through
guarded_tool_call with audit + OpenTelemetry spans, and a tolerant structured-output parser that
completes honestly rather than crashing on malformed model output.

Safety brakes (all live, all leave a receipt)

• R4 — cost cap. Per-trigger max_cost_usd (default $5, configurable via
  autonomous_default_max_cost_usd); a run that would overspend is halted with
  terminal_reason = cost_cap_reached. Live-verified during fresh-install acceptance.
• R5 — external halt + idle watchdog. A run can be halted from the UI; a cron watchdog moves an
  idle run running → paused → halted over two idle ticks.
• R6 — per-phase tool limits. Each phase is bounded in how many guarded calls it may make.

Where results land

• Sessions — every run with its chronological, inspectable receipt.
• Memory — per-user curated memory (keep / edit / dismiss / delete); only kept items are
  injected.
• Precedents — a precedent board (propose_precedent), with promote-to-Matter.
• Proposals — project-context proposals (accept / reject).
• Notifications — in-app notification rail with an unread badge; best-effort email
  dispatch (SMTP transport, timeout-bounded — in-app is the source of truth).

Opt-in enforcement — mutate endpoints are gated on the per-user autonomous_enabled flag
(read + halt stay open so you can always inspect and stop); schedule/watch spawn paths skip
opted-out users.

---

Platform operability (Phase 1 of the platform-cohesion build, design §4)

Made the (off-by-default) layer discoverable and honest about its own scope:

• §4.1 Home discoverability signpost — an Autonomous card on Home for all users; links a
  not-yet-enabled user straight to the opt-in (Settings → Autonomous), or to the Autonomous
  area when already on. Resolves the chicken-and-egg where the tab was hidden until enabled and
  nothing pointed to the toggle.
• §4.2 Configure / education tab — a plain-language page explaining On/Off, Schedules vs
  Watches, Run-now, where results land, and the R4/R5/R6 safety model; plus instructive
  empty-states on Sessions / Schedules / Watches.
• §4.3 Cost-cap field in the schedule/watch create modals, and readable target/KB/matter
  names in list rows (no more raw IDs).
• §4.4 Run-now — backend POST /autonomous/run-now (trigger_kind='manual', reusing the
  executor + brakes), its API client, and the Sessions-page UI + Cypress smoke.
• §4.5 Tabular honesty fix — corrected a Citation-Engine overclaim in the tabular docs to
  describe display-only source-chunk references (DE-309).

---

Documentation & Learn honesty sweep (M4-D2)

A pass to make every user-facing claim match the shipped code:

• Rewrote HONEST-STATE as the M1–M4 capability truth-map and reconciled README, PRD §3.10 +
  brake registers, architecture, db-schema (migrations 0001–0045), observability (spans / attrs /
  audit actions), security boundary registers (R4/R5/R6 → shipped), and the tabular / citation /
  skill-authoring / quickstart docs to source.
• New docs/autonomous-layer.md feature reference; ADR 0013 for the autonomous-layer design.
• Learn: corrected stale playgrounds and pages (including a fabricated skill list and a stale
  "M4 planned" status), and added 4 new How-It-Works playgrounds — Autonomous flow, Autonomous
  primitives, Intake bridges, KB hybrid retrieval, Matters/Org-profile/Privilege-tier — each
  field-checked against source.

---

Fixes & hardening

• DE-325 — build_receipt call sites hardened so a receipt-build failure can't crash the
  worker; brake-halted (R4/R5) sessions still surface their terminal_reason.
• DE-326 — fresh-install worker/api alembic-migration race fixed in docker-compose.yml
  (single migrator; workers wait for api-healthy).
• Standard-cron DoM/DoW OR-semantics + poison-schedule guards; naive-datetime rejection in
  retrieve_chunks since-mode; race-safe precedent upsert.

Schema

• Migration head 0045 (per-trigger max_cost_usd on watches + schedules). Phase 1 added no new
  migration.

---

Honest scope — what did not ship (deferred)

• DE-287 — Word add-in in-pane skill/playbook execution; the add-in surface remains deep-link
  placeholders + an inert tier badge by design.
• DE-309 / DE-310 — tabular per-cell resolvable citations / per-cell cost+tier telemetry
  (cells persist cost_usd: "0", tier_used: null; the pre-flight estimator is unaffected).
• DE-319 — LangGraph held at 0.2 for M4 (0.2 → 1.x migration deferred).
• DE-321 / DE-322 — watch firing under a future KB-sharing model; playbook/project FK
  ownership validation on schedule/watch create.
• DE-323 / DE-324 — autonomous proposals on the Matter detail page; a global-chrome
  notification bell.
• DE-327 — Helm/k8s worker-migration parity (the DE-326 single-migrator guarantee lives only
  in compose; the Helm chart has no worker deployments yet).
• DE-328 — skill_inputs collected in the UI don't yet reach the model for non-templated
  skills (gateway assembler change; first of the post-M4 Donna backend asks).

The platform-cohesion design's §3 model and §5 roadmap (Phases 2–5) are recommendation-only and
were intentionally not built in this release.

---

Release readiness

Branch ↔ main reconciliation — DONE. feat/lqvern-m4-autonomous had diverged from main at
d54df6b (before v0.3.1) and was missing 10 main-only commits. Merge d336c66 brought them all in
— origin/main is now an ancestor of the branch. The merged-in commits:

main commit	PR	what
8b8e549	#96	DE-305 default-install fix — bridge vars ${VAR:-} not ${VAR:?}
82d7874	#97	version bump 0.3.0 → 0.3.1
3e5809b	#98	CI: don't upload SBOM as a Release asset
0101b65	#99/#101	remove dead paddleocr placeholder breaking --profile local (now DE-320)
4df3b9b	#102	chat-receipts: surface anonymization_applied + message_id
7c7ce14	#103	gateway: persist inference_routing_log on streamed completions
9672ef4	#104	observability.md span/attribute correction
438198c	#105	document /v1/models alias fields
5df44b7	#106	add ROADMAP.md + README contributor anchors

Four doc conflicts were resolved keeping the more-recent/accurate side while preserving both sides'
substance (PRD §3.10 dedup + kept-both DE sets incl. DE-320; HONEST-STATE §9 PaddleOCR correction;
observability §3 source-reconciliation; the alignment guide's shipped propose_precedent). api +
gateway __version__ are bumped to 0.4.0.

Post-merge gates — all green: web check:lq-ai 0 errors + vitest 692/692; api ruff/mypy
clean + pytest 95 passed/276 skipped; gateway ruff/mypy --strict clean + pytest 529 passed/2
skipped.

Remaining steps (maintainer):

1. Merge feat/lqvern-m4-autonomous → main (fast-forward is possible since origin/main is an
   ancestor; a --no-ff merge commit is fine too).
2. Tag v0.4.0 (annotated, using the message above), push the tag to both remotes — the existing
   Release workflow builds + signs the images and attaches the SBOM.
3. Optionally rebuild the live stack (docker compose build web && up -d web) on the merged main.

---

Drafted from the main..feat/lqvern-m4-autonomous inventory; reconciled branch HEAD d336c66
(post-merge, 0.4.0). Per-task review trail and verification results are in the Phase-1 plan and the
docs/LQVern/HANDOFF-2026-05-31-… brief.

v0.3.1 — default-install fix (DE-305)

Patch release over v0.3.0.

Fix

• A default docker compose up no longer fails on a fresh install. The opt-in Slack/Teams intake-bridge env vars were declared with the required-error ${VAR:?} form, which Docker Compose evaluates before --profile filtering — so a plain docker compose up (no bridge profile) aborted with required variable SLACK_CLIENT_ID is missing a value, contradicting .env.example. The 8 bridge vars now use ${VAR:-}; the "required when the profile is active" guarantee moved into each bridge's Settings (a Pydantic field validator that fails fast at bridge startup, only when the profile is enabled). Community-reported as #92; tracked as DE-305. (#96)
• Release workflow SBOM job authenticates to GHCR (#95).

Notes

• api + gateway both report 0.3.1.
• No application-code change beyond the version string; the fix is in docker-compose.yml + the bridge services.

Thanks to @legalinnovationaggregator-coder for the precise bug report.

v0.3.0 — M3: Playbooks, Tabular Review, Word add-in & intake bridges, OpenTelemetry

Milestone 3: capability surfaces, integrations, and observability. Self-hosted; bring-your-own-keys.

Highlights

• Playbooks — multi-position cascade execution against a document; Easy Playbook generation.
• Tabular Review — grid extraction across documents with XLSX/CSV export.
• Microsoft Word add-in — Office.js task pane (plumbing: manifest + OAuth + version handshake). In-pane feature surface deferred to M4 (DE-287); signed package community-led (DE-295).
• Slack + Teams intake bridges — admin shell + backend persistence (OAuth E2E validation tracked as DE-312).
• OpenTelemetry deepening — W3C trace-context propagation across api→gateway→provider; domain spans (inference.dispatch, skill.execute, citation.verify, anonymization.pre/.post — attributes carry counts/types only, never raw entity values); deploy recipes (Grafana-Tempo-Loki + standalone collector) and an operator guide (docs/observability.md).
• M3-close transparency pass — Learn-tab visualizations and the use/how/build pages refreshed for M1–M3 reality; GET /admin/v1/anonymization-config implemented; skill author promoted to the wire shape (DE-316); a new "test landscape" contributor playground.

Verification

• api + gateway both report 0.3.0.
• Live-validated: api→gateway→provider traces land in Tempo with domain spans; W3C trace-context propagation confirmed across services.

See docs/HONEST-STATE.md for the authoritative shipped-vs-deferred catalog.

v0.2.0 — M2: Citation Engine, Anonymization Layer, Azure OpenAI

The M2 release of LQ.AI. Three flagship capabilities ship in this version: a four-stage Citation Engine that verifies every model-emitted citation against its source document before rendering; an Anonymization Layer that pseudonymizes sensitive entities in the Inference Gateway before requests leave for the model provider; and an Azure OpenAI provider adapter that unblocks Azure-tenant enterprise deployments.

Highlights

Citation Engine — 4-stage cascade

A model-emitted "<quote>" (Source: [N]) runs through staged verification: exact match → tolerant match → paraphrase judge → optional ensemble. The first stage to verify wins. Failed citations render as "unverified" rather than as confident-looking wrong text. Stage 4 ensemble runs parallel multi-judge dispatch with strict/majority aggregation and persists the tier envelope per row. Per-judge cost calibration uses a rolling average over the inference routing log (replaces the M2-D1 conservative flat constant with measured numbers).

Anonymization Layer — pre/post middleware

The Inference Gateway pseudonymizes detected entities (PERSON, ORGANIZATION, EMAIL_ADDRESS, PHONE_NUMBER, LOCATION, US_BANK_NUMBER + custom CASE_NUMBER / MATTER_NUMBER recognizers) before requests leave for the provider, then rehydrates on the response. Per-request PseudonymMapper is in-memory only — never persisted, never logged. Streaming-aware rehydration with bounded tail buffer. Privileged-project chats skip the layer entirely (Decision A — rewriting privileged work product risks corrupting it); retrieved source documents stay un-pseudonymized so the model has intact source quotes for citation grounding.

Honest validation posture: custom recognizers and middleware integration are tested; Presidio default-recognizer recall/precision on legal-document corpus is empirically unmeasured. Operators with high-confidentiality requirements should read docs/security/anonymization.md §"What's validated vs unvalidated" and consider Tier 1 (Ollama local) routing for matters where the unvalidated risk is unacceptable. Community contribution invited via DE-282.

Azure OpenAI provider adapter

AzureOpenAIAdapter subclasses OpenAIAdapter, sharing the wire format with overrides for the deployment-scoped URL (/openai/deployments/<deployment-id>/chat/completions?api-version=<v>) and api-key auth header. Required api_version field — no silent default because Azure rolls features per api-version. API-key auth ships in v0.2; Azure AD (managed identity / service principal) tracked at DE-278.

Scope reframes (closed without code)

• M2-F1 Citation Engine acceptance corpus → closed via scope reframe. Existing unit + integration + Cypress + browser + round-trip + edge-case tests already pin the load-bearing behavior. Citation type 2 (case-citation validation) and type 3 (case-content accuracy) tracked at DE-279 + DE-280.
• M2-F2 Anonymization acceptance corpus → closed via transparency-first deferral. Pre-deployment validation against legal-document corpus is genuinely open work the maintainer team lacks practice-specific judgment to do alone. Honest disclosure + community-friendly DE-282 invites contribution from practitioners across personal-injury / employment / healthcare / immigration / international practices.

New deferred enhancements filed during M2

DE-274, DE-275, DE-276, DE-277 (M2 cycle) · DE-278, DE-279, DE-280, DE-281, DE-282, DE-283 (M2-E / M2-F closeout). See PRD §9 for the full list.

Test deltas (M1 → M2)

Suite	M1 baseline	v0.2.0	Delta
api/	~700	1013	+313
gateway/	~300	515	+215
web/ vitest	~400	456	+56
Cypress E2E suites	6	7	+1

Provider adapters at v0.2.0

Anthropic · OpenAI · Azure OpenAI · Ollama. Google Vertex AI (DE-034) and AWS Bedrock (DE-035) remain spec'd as contributor-friendly work units on the deferred-enhancement list.

Pre-release validation

Fresh-install validation pass against the m2-development tip from a clean clone (volumes destroyed, images removed). All 7 services healthy; migrations applied through 0029; all probes return expected responses; both new Learn-tab playgrounds (/lq-ai/learn/how §5 Citation Engine cascade + §6 Anonymization Layer pre/post) serve cleanly. One UX paper-cut surfaced — DE-283 (fresh-install login messaging) — filed as a community-friendly DE rather than blocking the release.

Upgrade

LQ.AI is self-hosted; bring-your-own-keys; runs in the operator's environment. The quickstart at docs/quickstart.md walks the full deployment in under 20 minutes against a sample NDA. For operators upgrading from v0.1.0: read docs/HONEST-STATE.md for the per-capability shipped catalog and docs/security/anonymization.md for the honest validation framing on the new privacy controls.

Full per-task detail

docs/M2-IMPLEMENTATION-PLAN.md documents every M2 task with shipped-status and closeout reasoning. 22 commits across PRs #22–#42.